NAME

Nile::HTTP::Response - The HTTP response manager.

SYNOPSIS

# get response instance
$res = $app->response;

$res->code(200);
#$res->status(200);

$res->header('Content-Type' => 'text/plain');
#$res->content_type('text/html');
$res->header(Content_Base => 'http://www.mewsoft.com/');
$res->header(Accept => "text/html, text/plain, image/*");
$res->header(MIME_Version => '1.0', User_Agent   => 'Nile Web Client/0.27');
$res->cookies->{username} = {
        value => 'mewsoft',
        path  => "/",
        domain => '.mewsoft.com',
        expires => time + 24 * 60 * 60,
    };
#$res->body("Hello world content");
$res->content("Hello world content");

# PSGI response
 $response = $res->finalize;
 # [$code, $headers, $body]
 ($code, $headers, $body) = @$response;

# headers as string
$headers_str = $res->headers_as_string($eol)

# message as string
print $res->as_string($eol);

# HTTP/1.1 200 OK
# Accept: text/html, text/plain, image/*
# User-Agent: Nile Web Client/0.27
# Content-Type: text/plain
# Content-Base: http://www.mewsoft.com/
# MIME-Version: 1.0
# Set-Cookie: username=mewsoft; domain=.mewsoft.com; path=/; expires=Fri, 25-Jul-2014 19:10:45 GMT
#
# Hello world content

DESCRIPTION

Nile::HTTP::Response - The HTTP response manager allows you to create PSGI response array ref.

headers

$headers = $res->headers;
$res->headers([ 'Content-Type' => 'text/html' ]);
$res->headers({ 'Content-Type' => 'text/html' });
$res->headers( HTTP::Headers->new );

Sets and gets HTTP headers of the response. Setter can take either an array ref, a hash ref or HTTP::Headers object containing a list of headers.

This is HTTP::Headers object and all its methods available:

say $res->headers->header_field_names();
say $res->headers->remove_content_headers();
$res->headers->clear();

header

$res->header('X-Foo' => 'bar');
my $val = $res->header('X-Foo');

Sets and gets HTTP header of the response.

remove_header

   # delete
   $res->remove_header('Content-Type');

Removes the header fields with the specified names.

status

$res->status(200);
$status = $res->status;

Sets and gets HTTP status code. code is an alias.

body

$res->body($body_str);
$res->body([ "Hello", "World" ]);
$res->body($io);

Gets and sets HTTP response body. Setter can take either a string, an array ref, or an IO::Handle-like object. content is an alias.

Note that this method doesn't automatically set Content-Length for the response. You have to set it manually if you want, with the content_length method.

cookies

$res->cookies->{name} = 123;
$res->cookies->{name} = {value => '123'};

Returns a hash reference containing cookies to be set in the response. The keys of the hash are the cookies' names, and their corresponding values are a plain string (for value with everything else defaults) or a hash reference that can contain keys such as value, domain, expires, path, httponly, secure, max-age.

expires can take a string or an integer (as an epoch time) and does not convert string formats such as +3M.

$res->cookies->{name} = {
    value => 'test',
    path  => "/",
    domain => '.example.com',
    expires => time + 24 * 60 * 60,
};

content_length

$res->content_length(123);

A decimal number indicating the size in bytes of the message content. Shortcut for the equivalent get/set method in $res->headers.

content_type

$res->content_type('text/plain');

The Content-Type header field indicates the media type of the message content. Shortcut for the equivalent get/set method in $res->headers.

content_encoding

$res->content_encoding('gzip');

Shortcut for the equivalent get/set method in $res->headers.

location

Gets and sets Location header.

Note that this method doesn't normalize the given URI string in the setter.

redirect

$res->redirect($url);
$res->redirect($url, 301);

Sets redirect URL with an optional status code, which defaults to 302.

Note that this method doesn't normalize the given URI string. Users of this module have to be responsible about properly encoding URI paths and parameters.

finalize

$res = $res->finalize;
# [$code, \@headers, $body]
($code, $headers, $body) = @$res;

Returns the status code, headers, and body of this response as a PSGI response array reference.

to_app

$res_app = $res->to_app;

A helper shortcut for sub { $res->finalize }.

headers_as_string

$headers = $res->headers_as_string($eol)

Return the header fields as a formatted MIME header.

The optional $eol parameter specifies the line ending sequence to use. The default is "\n". Embedded "\n" characters in header field values will be substituted with this line ending sequence.

as_string

$message = $res->as_string($eol);

Returns the message formatted as a single string.

The optional $eol parameter specifies the line ending sequence to use. The default is "\n". If no $eol is given then as_string will ensure that the returned string is newline terminated (even when the message content is not). No extra newline is appended if an explicit $eol is passed.

render

$res->render;

Prints the message formatted as a single string to the standard output.

cookie_date

say $res->cookie_date( time + 24 * 60 * 60);
#Fri, 25-Jul-2014 20:46:53 GMT

Returns cookie formated date.

http_date

say $res->http_date(time);
#Thu, 24 Jul 2014 20:46:53 GMT

Returns http formated date.

status_message($code)

The status_message() function will translate status codes to human readable strings. If the $code is unknown, then undef is returned.

is_info( $code )

Return TRUE if $code is an Informational status code (1xx). This class of status code indicates a provisional response which can't have any content.

is_success( $code )

Return TRUE if $code is a Successful status code (2xx).

is_redirect( $code )

Return TRUE if $code is a Redirection status code (3xx). This class of status code indicates that further action needs to be taken by the user agent in order to fulfill the request.

is_error( $code )

Return TRUE if $code is an Error status code (4xx or 5xx). The function returns TRUE for both client and server error status codes.

is_client_error( $code )

Return TRUE if $code is a Client Error status code (4xx). This class of status code is intended for cases in which the client seems to have erred.

is_server_error( $code )

Return TRUE if $code is a Server Error status code (5xx). This class of status codes is intended for cases in which the server is aware that it has erred or is incapable of performing the request.

Bugs

This project is available on github at https://github.com/mewsoft/Nile.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Nile.

SOURCE

Source repository is at https://github.com/mewsoft/Nile.

ACKNOWLEDGMENT

This module is based on Plack::Response HTTP::Message

SEE ALSO

See Nile for details about the complete framework.

AUTHOR

Ahmed Amin Elsheshtawy, احمد امين الششتاوى <mewsoft@cpan.org> Website: http://www.mewsoft.com

COPYRIGHT AND LICENSE

Copyright (C) 2014-2015 by Dr. Ahmed Amin Elsheshtawy احمد امين الششتاوى mewsoft@cpan.org, support@mewsoft.com, https://github.com/mewsoft/Nile, http://www.mewsoft.com

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Nile

perl -MCPAN -e shell
install Nile