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

Shortcut for $req->input.

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