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