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

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

The upload hashref contains the following keys:

=over 4

=item * fh 

Filehandle.

=item * filename 

Client supplied filename.

=item * size

Size of the file in bytes.

=item * tempname

Path to the temporary spool file.

=item * type

Client supplied Content-Type.

=back

=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
	22	sub _assign_values {
	23	my ( $self, $map, $values ) = @_;
	24
	25	while ( my ( $name, $value ) = splice( @{ $values }, 0, 2 ) ) {
	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;
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;
	58	$req->hostname;
	59	$req->match;
	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
b22c6668	144	=item $req->match
fc7ec1d9	145
e7c0c583	146	This contains be the matching part of a regexp action. otherwise it
61b1e958	147	returns the same as 'action'.
fc7ec1d9	148
	149	print $c->request->match;
	150
b5176d9e	151	=item $req->method
	152
	153	Contains the request method (C<GET>, C<POST>, C<HEAD>, etc).
	154
e7c0c583	155	print $c->request->method;
	156
	157	=item $req->param
	158
	159	Get request parameters with a CGI.pm like param method.
	160
	161	$value = $c->request->param('foo');
	162	@values = $c->request->param('foo');
	163	@params = $c->request->param;
	164
	165	=cut
	166
	167	sub param {
	168	my $self = shift;
	169
	170	if ( @_ == 0 ) {
	171	return keys %{ $self->parameters };
	172	}
	173
	174	my $param = shift;
	175
	176	unless ( exists $self->parameters->{$param} ) {
	177	return wantarray ? () : undef;
	178	}
	179
	180	if ( ref $self->parameters->{$param} eq 'ARRAY' ) {
	181	return (wantarray)
	182	? @{ $self->parameters->{$param} }
	183	: $self->parameters->{$param}->[0];
	184	}
	185	else {
	186	return (wantarray)
	187	? ( $self->parameters->{$param} )
	188	: $self->parameters->{$param};
	189	}
	190	}
b5176d9e	191
b22c6668	192	=item $req->params
fc7ec1d9	193
61b1e958	194	Shortcut for $req->parameters.
	195
	196	=item $req->parameters
	197
e7c0c583	198	Returns a reference to a hash containing parameters. Values can
e7c0c583	199	be either a scalar or a arrayref containing scalars.
fc7ec1d9	200
e7c0c583	201	print $c->request->parameters->{field};
e7c0c583	202	print $c->request->parameters->{field}->[0];
fc7ec1d9	203
b22c6668	204	=item $req->path
fc7ec1d9	205
	206	Contains the path.
	207
	208	print $c->request->path;
	209
b5176d9e	210	=item $req->referer
fc7ec1d9	211
61b1e958	212	Shortcut to $req->headers->referer. Referring page.
fc7ec1d9	213
b22c6668	214	=item $req->snippets
fc7ec1d9	215
b22c6668	216	Returns a reference to an array containing regex snippets.
fc7ec1d9	217
	218	my @snippets = @{ $c->request->snippets };
	219
e7c0c583	220	=item $req->upload
	221
	222	A convenient method to $req->uploads.
	223
	224	$upload = $c->request->upload('field');
	225	@uploads = $c->request->upload('field');
	226	@fields = $c->request->upload;
	227
	228	for my $upload ( $c->request->upload('field') ) {
	229	print $upload->{filename};
	230	}
	231
	232	=cut
	233
	234	sub upload {
	235	my $self = shift;
	236
	237	if ( @_ == 0 ) {
	238	return keys %{ $self->uploads };
	239	}
	240
	241	my $upload = shift;
	242
	243	unless ( exists $self->uploads->{$upload} ) {
	244	return wantarray ? () : undef;
	245	}
	246
	247	if ( ref $self->uploads->{$upload} eq 'ARRAY' ) {
	248	return (wantarray)
	249	? @{ $self->uploads->{$upload} }
	250	: $self->uploads->{$upload}->[0];
	251	}
	252	else {
	253	return (wantarray)
	254	? ( $self->uploads->{$upload} )
	255	: $self->uploads->{$upload};
	256	}
	257	}
	258
b22c6668	259	=item $req->uploads
fc7ec1d9	260
e7c0c583	261	Returns a reference to a hash containing uploads. Values can
	262	be either a hashref or a arrayref containing hashrefs.
	263
	264	my $upload = $c->request->uploads->{field};
	265	my $upload = $c->request->uploads->{field}->[0];
	266
	267	The upload hashref contains the following keys:
	268
	269	=over 4
	270
	271	=item * fh
	272
	273	Filehandle.
fc7ec1d9	274
e7c0c583	275	=item * filename
	276
	277	Client supplied filename.
	278
	279	=item * size
	280
	281	Size of the file in bytes.
	282
	283	=item * tempname
	284
	285	Path to the temporary spool file.
	286
	287	=item * type
	288
	289	Client supplied Content-Type.
	290
	291	=back
fc7ec1d9	292
b5176d9e	293	=item $req->user_agent
b5176d9e	294
61b1e958	295	Shortcut to $req->headers->user_agent. User Agent version string.
b5176d9e	296
b22c6668	297	=back
b22c6668	298
fc7ec1d9	299	=head1 AUTHOR
	300
	301	Sebastian Riedel, C<sri@cpan.org>
61b1e958	302	Marcus Ramberg, C<mramberg@cpan.org>
fc7ec1d9	303
	304	=head1 COPYRIGHT
	305
e7c0c583	306	This program is free software, you can redistribute it and/or modify
61b1e958	307	it under the same terms as Perl itself.
fc7ec1d9	308
	309	=cut
	310
	311	1;