← Back to branch summary

~ubuntu-branches/ubuntu/edgy/libwww-perl/edgy

« back to all changes in this revision

Viewing changes to lib/HTTP/Request.pm

  • Committer: Bazaar Package Importer
  • Author(s): Jay Bonci
  • Date: 2005-02-13 18:45:32 UTC
  • mfrom: (2.1.2 hoary)
  • Revision ID: james.westby@ubuntu.com-20050213184532-67qvopi4wre3010u
Tags: 5.803-4
http://bugs.debian.org/294597
http://bugs.debian.org/294595
* Make GET/POST/HEAD symlinks (Closes: #294597)
* lwp-requests now honors -b when dumping links (Closes: #294595)
  - Thanks to giuseppe bonacci for the patch
* Moved symlinks to a libwww-perl.links file

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/HTTP/Request.pm
1
 
#
2
 
# $Id: Request.pm,v 1.30 2001/11/15 06:42:40 gisle Exp $
3
 
 
4
1
package HTTP::Request;
5
2
 
6
 
=head1 NAME
7
 
 
8
 
HTTP::Request - Class encapsulating HTTP Requests
9
 
 
10
 
=head1 SYNOPSIS
11
 
 
12
 
 require HTTP::Request;
13
 
 $request = HTTP::Request->new(GET => 'http://www.oslo.net/');
14
 
 
15
 
=head1 DESCRIPTION
16
 
 
17
 
C<HTTP::Request> is a class encapsulating HTTP style requests,
18
 
consisting of a request line, some headers, and some (potentially empty)
19
 
content. Note that the LWP library also uses this HTTP style requests
20
 
for non-HTTP protocols.
21
 
 
22
 
Instances of this class are usually passed to the C<request()> method
23
 
of an C<LWP::UserAgent> object:
24
 
 
25
 
 $ua = LWP::UserAgent->new;
26
 
 $request = HTTP::Request->new(GET => 'http://www.oslo.net/');
27
 
 $response = $ua->request($request);
28
 
 
29
 
C<HTTP::Request> is a subclass of C<HTTP::Message> and therefore
30
 
inherits its methods.  The inherited methods most often used are header(),
31
 
push_header(), remove_header(), and content(). See L<HTTP::Message> for details.
32
 
 
33
 
The following additional methods are available:
34
 
 
35
 
=over 4
36
 
 
37
 
=cut
 
3
# $Id: Request.pm,v 1.40 2004/04/07 10:44:47 gisle Exp $
38
4
 
39
5
require HTTP::Message;
40
6
@ISA = qw(HTTP::Message);
41
 
$VERSION = sprintf("%d.%02d", q$Revision: 1.30 $ =~ /(\d+)\.(\d+)/);
 
7
$VERSION = sprintf("%d.%02d", q$Revision: 1.40 $ =~ /(\d+)\.(\d+)/);
42
8
 
43
9
use strict;
44
10
 
45
 
=item $r = HTTP::Request->new($method, $uri)
46
 
 
47
 
=item $r = HTTP::Request->new($method, $uri, $header)
48
 
 
49
 
=item $r = HTTP::Request->new($method, $uri, $header, $content)
50
 
 
51
 
Constructs a new C<HTTP::Request> object describing a request on the
52
 
object C<$uri> using method C<$method>.  The C<$uri> argument can be
53
 
either a string, or a reference to a C<URI> object.  The optional $header
54
 
argument should be a reference to an C<HTTP::Headers> object.
55
 
The optional $content argument should be a string.
56
 
 
57
 
=cut
 
11
 
58
12
 
59
13
sub new
60
14
{
66
20
}
67
21
 
68
22
 
 
23
sub parse
 
24
{
 
25
    my($class, $str) = @_;
 
26
    my $request_line;
 
27
    if ($str =~ s/^(.*)\n//) {
 
28
        $request_line = $1;
 
29
    }
 
30
    else {
 
31
        $request_line = $str;
 
32
        $str = "";
 
33
    }
 
34
 
 
35
    my $self = $class->SUPER::parse($str);
 
36
    my($method, $uri, $protocol) = split(' ', $request_line);
 
37
    $self->method($method) if defined($method);
 
38
    $self->uri($uri) if defined($uri);
 
39
    $self->protocol($protocol) if $protocol;
 
40
    $self;
 
41
}
 
42
 
 
43
 
69
44
sub clone
70
45
{
71
46
    my $self = shift;
76
51
}
77
52
 
78
53
 
79
 
=item $r->method([$val])
80
 
 
81
 
=item $r->uri([$val])
82
 
 
83
 
These methods provide public access to the attributes containing
84
 
respectively the method of the request and the URI object of the
85
 
request.
86
 
 
87
 
If an argument is given the attribute is given that as its new
88
 
value. If no argument is given the value is not touched. In either
89
 
case the previous value is returned.
90
 
 
91
 
The method() method argument should be a string.
92
 
 
93
 
The uri() method accept both a reference to a URI object and a
94
 
string as its argument.  If a string is given, then it should be
95
 
parseable as an absolute URI.
96
 
 
97
 
=cut
98
 
 
99
 
sub method  { shift->_elem('_method', @_); }
 
54
sub method
 
55
{
 
56
    shift->_elem('_method', @_);
 
57
}
 
58
 
100
59
 
101
60
sub uri
102
61
{
106
65
        my $uri = shift;
107
66
        if (!defined $uri) {
108
67
            # that's ok
109
 
        } elsif (ref $uri) {
 
68
        }
 
69
        elsif (ref $uri) {
110
70
            Carp::croak("A URI can't be a " . ref($uri) . " reference")
111
71
                if ref($uri) eq 'HASH' or ref($uri) eq 'ARRAY';
112
72
            Carp::croak("Can't use a " . ref($uri) . " object as a URI")
117
77
                eval { local $SIG{__DIE__}; $uri = $uri->abs; };
118
78
                die $@ if $@ && $@ !~ /Missing base argument/;
119
79
            }
120
 
        } else {
 
80
        }
 
81
        else {
121
82
            $uri = $HTTP::URI_CLASS->new($uri);
122
83
        }
123
84
        $self->{'_uri'} = $uri;
125
86
    $old;
126
87
}
127
88
 
128
 
*url = \&uri;  # this is the same for now
129
 
 
130
 
=item $r->as_string()
131
 
 
132
 
Method returning a textual representation of the request.
133
 
Mainly useful for debugging purposes. It takes no arguments.
134
 
 
135
 
=cut
 
89
*url = \&uri;  # legacy
 
90
 
136
91
 
137
92
sub as_string
138
93
{
139
94
    my $self = shift;
140
 
    my @result;
141
 
    #push(@result, "---- $self -----");
142
 
    my $req_line = $self->method || "[NO METHOD]";
 
95
    my($eol) = @_;
 
96
    $eol = "\n" unless defined $eol;
 
97
 
 
98
    my $req_line = $self->method || "-";
143
99
    my $uri = $self->uri;
144
 
    $uri = (defined $uri) ? $uri->as_string : "[NO URI]";
 
100
    $uri = (defined $uri) ? $uri->as_string : "-";
145
101
    $req_line .= " $uri";
146
102
    my $proto = $self->protocol;
147
103
    $req_line .= " $proto" if $proto;
148
104
 
149
 
    push(@result, $req_line);
150
 
    push(@result, $self->headers_as_string);
151
 
    my $content = $self->content;
152
 
    if (defined $content) {
153
 
        push(@result, $content);
154
 
    }
155
 
    #push(@result, ("-" x 40));
156
 
    join("\n", @result, "");
 
105
    return join($eol, $req_line, $self->SUPER::as_string(@_));
157
106
}
158
107
 
 
108
 
159
109
1;
160
110
 
 
111
__END__
 
112
 
 
113
=head1 NAME
 
114
 
 
115
HTTP::Request - HTTP style request message
 
116
 
 
117
=head1 SYNOPSIS
 
118
 
 
119
 require HTTP::Request;
 
120
 $request = HTTP::Request->new(GET => 'http://www.example.com/');
 
121
 
 
122
and usually used like this:
 
123
 
 
124
 $ua = LWP::UserAgent->new;
 
125
 $response = $ua->request($request);
 
126
 
 
127
=head1 DESCRIPTION
 
128
 
 
129
C<HTTP::Request> is a class encapsulating HTTP style requests,
 
130
consisting of a request line, some headers, and a content body. Note
 
131
that the LWP library uses HTTP style requests even for non-HTTP
 
132
protocols.  Instances of this class are usually passed to the
 
133
request() method of an C<LWP::UserAgent> object.
 
134
 
 
135
C<HTTP::Request> is a subclass of C<HTTP::Message> and therefore
 
136
inherits its methods.  The following additional methods are available:
 
137
 
 
138
=over 4
 
139
 
 
140
=item $r = HTTP::Request->new( $method, $uri )
 
141
 
 
142
=item $r = HTTP::Request->new( $method, $uri, $header )
 
143
 
 
144
=item $r = HTTP::Request->new( $method, $uri, $header, $content )
 
145
 
 
146
Constructs a new C<HTTP::Request> object describing a request on the
 
147
object $uri using method $method.  The $method argument must be a
 
148
string.  The $uri argument can be either a string, or a reference to a
 
149
C<URI> object.  The optional $header argument should be a reference to
 
150
an C<HTTP::Headers> object or a plain array reference of key/value
 
151
pairs.  The optional $content argument should be a string of bytes.
 
152
 
 
153
=item $r = HTTP::Request->parse( $str )
 
154
 
 
155
This constructs a new request object by parsing the given string.
 
156
 
 
157
=item $r->method
 
158
 
 
159
=item $r->method( $val )
 
160
 
 
161
This is used to get/set the method attribute.  The method should be a
 
162
short string like "GET", "HEAD", "PUT" or "POST".
 
163
 
 
164
=item $r->uri
 
165
 
 
166
=item $r->uri( $val )
 
167
 
 
168
This is used to get/set the uri attribute.  The $val can be a
 
169
reference to a URI object or a plain string.  If a string is given,
 
170
then it should be parseable as an absolute URI.
 
171
 
 
172
=item $r->header( $field )
 
173
 
 
174
=item $r->header( $field => $value )
 
175
 
 
176
This is used to get/set header values and it is inherited from
 
177
C<HTTP::Headers> via C<HTTP::Message>.  See L<HTTP::Headers> for
 
178
details and other similar methods that can be used to access the
 
179
headers.
 
180
 
 
181
=item $r->content
 
182
 
 
183
=item $r->content( $content )
 
184
 
 
185
This is used to get/set the content and it is inherited from the
 
186
C<HTTP::Message> base class.  See L<HTTP::Message> for details and
 
187
other methods that can be used to access the content.
 
188
 
 
189
Note that the content should be a string of bytes.  Strings in perl
 
190
can contain characters outside the range of a byte.  The C<Encode>
 
191
module can be used to turn such strings into a string of bytes.
 
192
 
 
193
=item $r->as_string
 
194
 
 
195
=item $r->as_string( $eol )
 
196
 
 
197
Method returning a textual representation of the request.
 
198
 
161
199
=back
162
200
 
163
201
=head1 SEE ALSO
164
202
 
165
 
L<HTTP::Headers>, L<HTTP::Message>, L<HTTP::Request::Common>
 
203
L<HTTP::Headers>, L<HTTP::Message>, L<HTTP::Request::Common>,
 
204
L<HTTP::Response>
166
205
 
167
206
=head1 COPYRIGHT
168
207
 
169
 
Copyright 1995-2001 Gisle Aas.
 
208
Copyright 1995-2004 Gisle Aas.
170
209
 
171
210
This library is free software; you can redistribute it and/or
172
211
modify it under the same terms as Perl itself.
173
212
 
174
 
=cut