[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 body base cookies headers hostname match
      method parameters path snippets uploads/
);

*args   = \&arguments;
*input  = \&body;
*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->body;
    $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->body

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->body

=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

Shortcut for $req->body.

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