[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(@_)       }

=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 };
    }

    if ( @_ == 1 and ref( $_[0] ) eq 'ARRAY' ) {

        while ( my ( $field, $value ) = splice( @{ $_[0] }, 0, 2 ) ) {

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

        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 };
    }

    if ( @_ == 1 and ref( $_[0] ) eq 'ARRAY' ) {

        while ( my ( $field, $upload ) = splice( @{ $_[0] }, 0, 2 ) ) {

            if ( exists $self->uploads->{$field} ) {
                for ( $self->uploads->{$field} ) {
                    $_ = [$_] unless ref($_) eq "ARRAY";
                    push( @$_, $upload );
                }
            }
            else {
                $self->uploads->{$field} = $upload;
            }
        }
    }

    if ( @_ == 1 ) {

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