view release on metacpan or  search on metacpan

lib/Catalyst/Response.pm  view on Meta::CPAN

        }

        $self->location($location);
        $self->status($status);
    }

    return $self->location;
}

=head2 $res->location

Sets or returns the HTTP 'Location'.

=head2 $res->status

Sets or returns the HTTP status.

    $c->response->status(404);

$res->code is an alias for this, to match HTTP::Response->code.

=head2 $res->write( $data )

Writes $data to the output stream.  Calling this method will finalize your
headers and send the headers and status code response to the client (so changing
them afterwards is a waste... be sure to set your headers correctly first).

You may call this as often as you want throughout your response cycle.  You may
even set a 'body' afterward.  So for example you might write your HTTP headers
and the HEAD section of your document and then set the body from a template
driven from a database.  In some cases this can seem to the client as if you had
a faster overall response (but note that unless your server support chunked
body your content is likely to get queued anyway (L<Starman> and most other
http 1.1 webservers support this).

If there is an encoding set, we encode each line of the response (the default
encoding is UTF-8).

=head2 $res->unencoded_write( $data )

Works just like ->write but we don't apply any content encoding to C<$data>.  Use
this if you are already encoding the $data or the data is arriving from an encoded
storage.

=head2 $res->write_fh

Returns an instance of L<Catalyst::Response::Writer>, which is a lightweight
decorator over the PSGI C<$writer> object (see L<PSGI.pod\Delayed-Response-and-Streaming-Body>).

In addition to proxying the C<write> and C<close> method from the underlying PSGI
writer, this proxy object knows any application wide encoding, and provides a method
C<write_encoded> that will properly encode your written lines based upon your
encoding settings.  By default in L<Catalyst> responses are UTF-8 encoded and this
is the encoding used if you respond via C<write_encoded>.  If you want to handle
encoding yourself, you can use the C<write> method directly.

Encoding only applies to content types for which it matters.  Currently the following
content types are assumed to need encoding: text (including HTML), xml and javascript.

We provide access to this object so that you can properly close over it for use in
asynchronous and nonblocking applications.  For example (assuming you are using a supporting
server, like L<Twiggy>:

    package AsyncExample::Controller::Root;

    use Moose;

    BEGIN { extends 'Catalyst::Controller' }

    sub prepare_cb {
      my $write_fh = pop;
      return sub {
        my $message = shift;
        $write_fh->write("Finishing: $message\n");
        $write_fh->close;
      };
    }

    sub anyevent :Local :Args(0) {
      my ($self, $c) = @_;
      my $cb = $self->prepare_cb($c->res->write_fh);

      my $watcher;
      $watcher = AnyEvent->timer(
        after => 5,
        cb => sub {
          $cb->(scalar localtime);
          undef $watcher; # cancel circular-ref
        });
    }

Like the 'write' method, calling this will finalize headers. Unlike 'write' when you
can this it is assumed you are taking control of the response so the body is never
finalized (there isn't one anyway) and you need to call the close method.

=head2 $res->print( @data )

Prints @data to the output stream, separated by $,.  This lets you pass
the response object to functions that want to write to an L<IO::Handle>.

=head2 $res->finalize_headers()

Writes headers to response if not already written

=head2 from_psgi_response

Given a PSGI response (either three element ARRAY reference OR coderef expecting
a $responder) set the response from it.

Properly supports streaming and delayed response and / or async IO if running
under an expected event loop.

If passed an object, will expect that object to do a method C<as_psgi>.

Example:

    package MyApp::Web::Controller::Test;

    use base 'Catalyst::Controller';
    use Plack::App::Directory;