[catagits/Catalyst-Runtime.git] / lib / Catalyst / Request.pm

package Catalyst::Request;

use strict;
use base 'Class::Accessor::Fast';

__PACKAGE__->mk_accessors(
    qw/action address arguments base cookies headers input hostname match 
      method parameters path snippets uploads/
);

*args   = \&arguments;
*params = \&parameters;

sub content_encoding { shift->headers->content_encoding(@_) }
sub content_length   { shift->headers->content_length(@_)   }
sub content_type     { shift->headers->content_type(@_)     }
sub header           { shift->headers->header(@_)           }
sub referer          { shift->headers->referer(@_)          }
sub user_agent       { shift->headers->user_agent(@_)       }

sub _assign_values {
    my ( $self, $map, $values ) = @_;

    while ( my ( $name, $value ) = splice( @{$values}, 0, 2 ) ) {

        if ( exists $map->{$name} ) {
            for ( $map->{$name} ) {
                $_ = [$_] unless ref($_) eq "ARRAY";
                push( @$_, $value );
            }
        }
        else {
            $map->{$name} = $value;
        }
    }
}

=head1 NAME

Catalyst::Request - Catalyst Request Class

=head1 SYNOPSIS


    $req = $c->request;
    $req->action;
    $req->address;
    $req->args;
    $req->arguments;
    $req->base;
    $req->content_encoding;
    $req->content_length;
    $req->content_type;
    $req->cookies;
    $req->header;
    $req->headers;
    $req->hostname;
    $req->input;
    $req->match;
    $req->method;
    $req->param;
    $req->params;
    $req->parameters;
    $req->path;
    $req->referer;
    $req->snippets;
    $req->upload;
    $req->uploads;
    $req->user_agent

See also L<Catalyst>.

=head1 DESCRIPTION

This is the Catalyst Request class, which provides a set of accessors to the
request data.  The request object is prepared by the specialized Catalyst
Engine module thus hiding the details of the particular engine implementation.


=head1 METHODS

=over 4

=item $req->action

Contains the requested action.

    print $c->request->action;

=item $req->address

Contains the remote address.

    print $c->request->address

=item $req->args

Shortcut for arguments

=item $req->arguments

Returns a reference to an array containing the arguments.

    print $c->request->arguments->[0];

=item $req->base

Contains the url base. This will always have a trailing slash.

=item $req->content_encoding

Shortcut to $req->headers->content_encoding

=item $req->content_length

Shortcut to $req->headers->content_length

=item $req->content_type

Shortcut to $req->headers->content_type

=item $req->cookies

Returns a reference to a hash containing the cookies.

    print $c->request->cookies->{mycookie}->value;

=item $req->header

Shortcut to $req->headers->header

=item $req->headers

Returns an L<HTTP::Headers> object containing the headers.

    print $c->request->headers->header('X-Catalyst');

=item $req->hostname

Contains the hostname of the remote user.

    print $c->request->hostname

=item $req->input

Contains the message body of the request unless Content-Type is
C<application/x-www-form-urlencoded> or C<multipart/form-data>.

    print $c->request->input

=item $req->match

This contains be the matching part of a regexp action. otherwise it
returns the same as 'action'.

    print $c->request->match;

=item $req->method

Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).

    print $c->request->method;

=item $req->param

Get request parameters with a CGI.pm like param method.

    $value  = $c->request->param('foo');
    @values = $c->request->param('foo');
    @params = $c->request->param;

=cut

sub param {
    my $self = shift;

    if ( @_ == 0 ) {
        return keys %{ $self->parameters };
    }

    my $param = shift;

    unless ( exists $self->parameters->{$param} ) {
        return wantarray ? () : undef;
    }

    if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
        return (wantarray)
          ? @{ $self->parameters->{$param} }
          : $self->parameters->{$param}->[0];
    }
    else {
        return (wantarray)
          ? ( $self->parameters->{$param} )
          : $self->parameters->{$param};
    }
}

=item $req->params

Shortcut for $req->parameters.

=item $req->parameters

Returns a reference to a hash containing parameters. Values can
be either a scalar or a arrayref containing scalars.

    print $c->request->parameters->{field};
    print $c->request->parameters->{field}->[0];

=item $req->path

Contains the path.

    print $c->request->path;

=item $req->referer

Shortcut to $req->headers->referer. Referring page.

=item $req->snippets

Returns a reference to an array containing regex snippets.

    my @snippets = @{ $c->request->snippets };

=item $req->upload

A convenient method to $req->uploads.

    $upload  = $c->request->upload('field');
    @uploads = $c->request->upload('field');
    @fields  = $c->request->upload;
    
    for my $upload ( $c->request->upload('field') ) {
        print $upload->filename;
    }

=cut

sub upload {
    my $self = shift;

    if ( @_ == 0 ) {
        return keys %{ $self->uploads };
    }

    my $upload = shift;

    unless ( exists $self->uploads->{$upload} ) {
        return wantarray ? () : undef;
    }

    if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
        return (wantarray)
          ? @{ $self->uploads->{$upload} }
          : $self->uploads->{$upload}->[0];
    }
    else {
        return (wantarray)
          ? ( $self->uploads->{$upload} )
          : $self->uploads->{$upload};
    }
}

=item $req->uploads

Returns a reference to a hash containing uploads. Values can be either a 
hashref or a arrayref containing C<Catalyst::Request::Upload> objects.

    my $upload = $c->request->uploads->{field};
    my $upload = $c->request->uploads->{field}->[0];

=item $req->user_agent

Shortcut to $req->headers->user_agent. User Agent version string.

=back

=head1 AUTHOR

Sebastian Riedel, C<sri@cpan.org>
Marcus Ramberg, C<mramberg@cpan.org>

=head1 COPYRIGHT

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

=cut

1;
Commit	Line	Data
fc7ec1d9	1	package Catalyst::Request;
	2
	3	use strict;
	4	use base 'Class::Accessor::Fast';
	5
	6	__PACKAGE__->mk_accessors(
61bacdcc	7	qw/action address arguments base cookies headers input hostname match
61bacdcc	8	method parameters path snippets uploads/
fc7ec1d9	9	);
	10
	11	*args = \&arguments;
	12	*params = \&parameters;
	13
f7e4e231	14	sub content_encoding { shift->headers->content_encoding(@_) }
	15	sub content_length { shift->headers->content_length(@_) }
	16	sub content_type { shift->headers->content_type(@_) }
	17	sub header { shift->headers->header(@_) }
	18	sub referer { shift->headers->referer(@_) }
	19	sub user_agent { shift->headers->user_agent(@_) }
	20
e7c0c583	21	sub _assign_values {
e7c0c583	22	my ( $self, $map, $values ) = @_;
146554c5	23
146554c5	24	while ( my ( $name, $value ) = splice( @{$values}, 0, 2 ) ) {
e7c0c583	25
	26	if ( exists $map->{$name} ) {
	27	for ( $map->{$name} ) {
	28	$_ = [$_] unless ref($_) eq "ARRAY";
	29	push( @$_, $value );
	30	}
	31	}
	32	else {
	33	$map->{$name} = $value;
	34	}
	35	}
	36	}
	37
fc7ec1d9	38	=head1 NAME
	39
	40	Catalyst::Request - Catalyst Request Class
	41
	42	=head1 SYNOPSIS
	43
b22c6668	44
	45	$req = $c->request;
	46	$req->action;
	47	$req->address;
	48	$req->args;
	49	$req->arguments;
	50	$req->base;
b5176d9e	51	$req->content_encoding;
	52	$req->content_length;
	53	$req->content_type;
b22c6668	54	$req->cookies;
b5176d9e	55	$req->header;
b22c6668	56	$req->headers;
b22c6668	57	$req->hostname;
61bacdcc	58	$req->input;
b22c6668	59	$req->match;
b22c6668	60	$req->method;
e7c0c583	61	$req->param;
b22c6668	62	$req->params;
e7c0c583	63	$req->parameters;
b22c6668	64	$req->path;
b5176d9e	65	$req->referer;
b22c6668	66	$req->snippets;
e7c0c583	67	$req->upload;
b22c6668	68	$req->uploads;
b5176d9e	69	$req->user_agent
b22c6668	70
b22c6668	71	See also L<Catalyst>.
fc7ec1d9	72
	73	=head1 DESCRIPTION
	74
b22c6668	75	This is the Catalyst Request class, which provides a set of accessors to the
	76	request data. The request object is prepared by the specialized Catalyst
	77	Engine module thus hiding the details of the particular engine implementation.
	78
	79
	80	=head1 METHODS
fc7ec1d9	81
b22c6668	82	=over 4
fc7ec1d9	83
b22c6668	84	=item $req->action
fc7ec1d9	85
61b1e958	86	Contains the requested action.
fc7ec1d9	87
	88	print $c->request->action;
	89
b22c6668	90	=item $req->address
0556eb49	91
	92	Contains the remote address.
	93
	94	print $c->request->address
	95
b22c6668	96	=item $req->args
b22c6668	97
61b1e958	98	Shortcut for arguments
	99
	100	=item $req->arguments
	101
b22c6668	102	Returns a reference to an array containing the arguments.
fc7ec1d9	103
	104	print $c->request->arguments->[0];
	105
b22c6668	106	=item $req->base
fc7ec1d9	107
61b1e958	108	Contains the url base. This will always have a trailing slash.
fc7ec1d9	109
b5176d9e	110	=item $req->content_encoding
	111
	112	Shortcut to $req->headers->content_encoding
	113
	114	=item $req->content_length
	115
	116	Shortcut to $req->headers->content_length
	117
	118	=item $req->content_type
	119
	120	Shortcut to $req->headers->content_type
	121
b22c6668	122	=item $req->cookies
fc7ec1d9	123
b22c6668	124	Returns a reference to a hash containing the cookies.
fc7ec1d9	125
	126	print $c->request->cookies->{mycookie}->value;
	127
b5176d9e	128	=item $req->header
	129
	130	Shortcut to $req->headers->header
	131
b22c6668	132	=item $req->headers
fc7ec1d9	133
b22c6668	134	Returns an L<HTTP::Headers> object containing the headers.
fc7ec1d9	135
	136	print $c->request->headers->header('X-Catalyst');
	137
b22c6668	138	=item $req->hostname
0556eb49	139
61b1e958	140	Contains the hostname of the remote user.
0556eb49	141
	142	print $c->request->hostname
	143
61bacdcc	144	=item $req->input
	145
	146	Contains the message body of the request unless Content-Type is
	147	C<application/x-www-form-urlencoded> or C<multipart/form-data>.
	148
	149	print $c->request->input
	150
b22c6668	151	=item $req->match
fc7ec1d9	152
e7c0c583	153	This contains be the matching part of a regexp action. otherwise it
61b1e958	154	returns the same as 'action'.
fc7ec1d9	155
	156	print $c->request->match;
	157
b5176d9e	158	=item $req->method
	159
	160	Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
	161
e7c0c583	162	print $c->request->method;
	163
	164	=item $req->param
	165
	166	Get request parameters with a CGI.pm like param method.
	167
	168	$value = $c->request->param('foo');
	169	@values = $c->request->param('foo');
	170	@params = $c->request->param;
	171
	172	=cut
	173
	174	sub param {
	175	my $self = shift;
	176
	177	if ( @_ == 0 ) {
	178	return keys %{ $self->parameters };
	179	}
	180
	181	my $param = shift;
	182
	183	unless ( exists $self->parameters->{$param} ) {
	184	return wantarray ? () : undef;
	185	}
	186
	187	if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
	188	return (wantarray)
	189	? @{ $self->parameters->{$param} }
	190	: $self->parameters->{$param}->[0];
	191	}
	192	else {
	193	return (wantarray)
	194	? ( $self->parameters->{$param} )
	195	: $self->parameters->{$param};
	196	}
	197	}
b5176d9e	198
b22c6668	199	=item $req->params
fc7ec1d9	200
61b1e958	201	Shortcut for $req->parameters.
	202
	203	=item $req->parameters
	204
e7c0c583	205	Returns a reference to a hash containing parameters. Values can
e7c0c583	206	be either a scalar or a arrayref containing scalars.
fc7ec1d9	207
e7c0c583	208	print $c->request->parameters->{field};
e7c0c583	209	print $c->request->parameters->{field}->[0];
fc7ec1d9	210
b22c6668	211	=item $req->path
fc7ec1d9	212
	213	Contains the path.
	214
	215	print $c->request->path;
	216
b5176d9e	217	=item $req->referer
fc7ec1d9	218
61b1e958	219	Shortcut to $req->headers->referer. Referring page.
fc7ec1d9	220
b22c6668	221	=item $req->snippets
fc7ec1d9	222
b22c6668	223	Returns a reference to an array containing regex snippets.
fc7ec1d9	224
	225	my @snippets = @{ $c->request->snippets };
	226
e7c0c583	227	=item $req->upload
	228
	229	A convenient method to $req->uploads.
	230
	231	$upload = $c->request->upload('field');
	232	@uploads = $c->request->upload('field');
	233	@fields = $c->request->upload;
	234
	235	for my $upload ( $c->request->upload('field') ) {
146554c5	236	print $upload->filename;
e7c0c583	237	}
	238
	239	=cut
	240
	241	sub upload {
	242	my $self = shift;
	243
	244	if ( @_ == 0 ) {
	245	return keys %{ $self->uploads };
	246	}
	247
	248	my $upload = shift;
	249
	250	unless ( exists $self->uploads->{$upload} ) {
	251	return wantarray ? () : undef;
	252	}
	253
	254	if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
	255	return (wantarray)
	256	? @{ $self->uploads->{$upload} }
	257	: $self->uploads->{$upload}->[0];
	258	}
	259	else {
	260	return (wantarray)
	261	? ( $self->uploads->{$upload} )
	262	: $self->uploads->{$upload};
	263	}
	264	}
	265
b22c6668	266	=item $req->uploads
fc7ec1d9	267
146554c5	268	Returns a reference to a hash containing uploads. Values can be either a
146554c5	269	hashref or a arrayref containing C<Catalyst::Request::Upload> objects.
e7c0c583	270
	271	my $upload = $c->request->uploads->{field};
	272	my $upload = $c->request->uploads->{field}->[0];
	273
b5176d9e	274	=item $req->user_agent
b5176d9e	275
61b1e958	276	Shortcut to $req->headers->user_agent. User Agent version string.
b5176d9e	277
b22c6668	278	=back
b22c6668	279
fc7ec1d9	280	=head1 AUTHOR
	281
	282	Sebastian Riedel, C<sri@cpan.org>
61b1e958	283	Marcus Ramberg, C<mramberg@cpan.org>
fc7ec1d9	284
	285	=head1 COPYRIGHT
	286
e7c0c583	287	This program is free software, you can redistribute it and/or modify
61b1e958	288	it under the same terms as Perl itself.
fc7ec1d9	289
	290	=cut
	291
	292	1;