/docs/MyDocs

To get this branch, use:
bzr branch http://darksoft.org/webbzr/docs/MyDocs

« back to all changes in this revision

Viewing changes to Development/languages/perl/perl-www.me

  • Committer: Suren A. Chilingaryan
  • Date: 2009-04-09 03:21:08 UTC
  • Revision ID: csa@dside.dyndns.org-20090409032108-w4edamdh4adrgdu3
import

Show diffs side-by-side

added added

removed removed

Lines of Context:
Development/languages/perl/perl-www.me
 
1
.he ''--- URL processing ---''
 
2
.ll 7.9i
 
3
.sh 1 URI::URL
 
4
.br
 
5
Functions and modules to specify & convert URIs (URLs are a type of URI)
 
6
 
 
7
.ta 3.5i
 
8
.in 3.5i
 
9
.ti -3.5i
 
10
\fB$url=new URI::URL($url_str[,$base_url])\fP
 
11
.br
 
12
Creates URI object. $url_str can be relative path & $base_url base path, 
 
13
for example $url_str = "news" and $base_url = "http://3dnews.ru". 
 
14
.ti -3.5i
 
15
\fBabs([$base_url,[scheme])\fP  Return converted relative path to absolute 
 
16
(if $url_str in constructor given as relative path, otherwise returns $url_str
 
17
himself). If first parametr specified it used instead of value specified 
 
18
in $base_url in constructor. If second parametr non-zero will accept relative 
 
19
url with scheme but without host (http:index.html).
 
20
.ti -3.5i
 
21
\fBrel([$base_url])\fP  Returns the current object's URL relative to the base URL
 
22
.ti -3.5i
 
23
\fBas_string()\fP       Returns URL string (http://www.ru/news.htm)
 
24
.ti -3.5i
 
25
\fBbase([base])\fP      Sets/Gets base URL
 
26
.ti -3.5i
 
27
\fBscheme([scheme])\fP  Sets/Gets scheme(HTTP,FTP,...)
 
28
.ti -3.5i
 
29
\fBnetloc([netloc])\fP  Returns user:password@host:port string, or if it specified
 
30
sets apropriate parametrs
 
31
.ti -3.5i
 
32
\fBhost([hostname])\fP  Sets/Gets URL host name
 
33
.ti -3.5i
 
34
\fBuser([user])\fP      Sets/Gets user name
 
35
.ti -3.5i
 
36
\fBpassword([passwd])\fP        Sets/Gets user password
 
37
.ti -3.5i
 
38
\fBport([port])\fP      Sets/Gets port
 
39
.ti -3.5i
 
40
\fBdefault_port([port]\fP       Sets/Gets default port
 
41
.ti -3.5i
 
42
\fBfull_path()\fP       Returns a string consisting of the escaped path, 
 
43
escaped parametrs, and escaped query string.
 
44
.ti -3.5i
 
45
\fBepath([path])\fP     Sets/Get escaped path of the URL
 
46
.ti -3.5i
 
47
\fBpath([path])\fP      Some but not escaped
 
48
.ti -3.5i
 
49
\fBeparams([param])\fP  Sets/Gets escaped parametrs of the URL
 
50
.ti -3.5i
 
51
\fBparams([param])\fP   Some but not escaped
 
52
.ti -3.5i
 
53
\fBequery([query])\fP   Sets/Gets escaped query string of the URL
 
54
.ti -3.5i
 
55
\fBquery([query])\fP    Some but not escaped
 
56
.ti -3.5i
 
57
\fBfrag([frag])\fP      Sets/Gets fragment of the URL
 
58
.ti -3.5i
 
59
\fBcrack()\fP   Returns an array with the following data: (scheme, user, 
 
60
password, host, port, epath, eparms, equery, frag)
 
61
 
 
62
.ti -3.5i
 
63
\fBeq(other_url)\fP     Returns true when object's URL is equal to the specified URL
 
64
 
 
65
.ti -3.5i
 
66
\fBuri_escape($uri|$str[,regexp])\fP    By default 
 
67
escapes RFC1738 characters, otherwise escape \fIregexp\fP characters.
 
68
.ti -3.5i
 
69
\fBuri_unescape($uri)\fP        Restores back
 
70
.in 0
 
71
.hl
 
72
.===========================================================================
 
73
.sh 1 LWP::UserAgent
 
74
 
 
75
.br
 
76
.ta 2.5i
 
77
.in 2.5i
 
78
.ti -2.5i
 
79
\fB$ua=new LWP::UserAgent\fP    You give object a request, which it uses to
 
80
contact server and returns result.
 
81
.ta 2i
 
82
.ti -2.5i
 
83
\fBrequest($req,[file|$sub,size])\fP    
 
84
.br
 
85
Performs request. Returns the information
 
86
received from the server as an HTTP::Response object.
 
87
.ti -2i
 
88
\fI$req\fP      HTTP::Request object
 
89
.ti -2i
 
90
\fIfile\fP      Instead of return HTTP::Response object save all output to 
 
91
specified file
 
92
.ti -2i
 
93
\fI$sub\fP      Reference to subroutine that will process data of the response.
 
94
If \fI'size'\fP argument used, the subroutine will be called any time that
 
95
number of bytes is recived as response data. Subroutine will get \fIresponse data\fP
 
96
as first argument, \fIHTTP::Response\fP as second and \fILWP::Protocol\fP as the third
 
97
.ta 2.5i
 
98
.ti -2.5i
 
99
\fBclone()\fP   Returns a copy of the LWP::UserAgen object
 
100
.ti -2.5i
 
101
\fBis_protocol_supported()\fP If true returned - LWP knows how to handle URL
 
102
with the specified protocol.
 
103
.ti -2.5i
 
104
\fBcookie_jar([$cjar])\fP       Specifies the HTTP::Cookies object to be used
 
105
.ti -2.5i
 
106
\fBcredentials(netloc,realm,uname,pass)\fP
 
107
.br
 
108
.ta 2i
 
109
.ti -2i
 
110
\fInetloc\fP    Network location(usually URL) to which following apply
 
111
.ti -2i
 
112
\fIrealm\fP     The name of server-defined range of URLs that this data applies to
 
113
.ti -2i
 
114
\fIuname\fP     User name for authentication
 
115
.ti -2i
 
116
\fIpass\fP      Password for authentication (By default transmited with 
 
117
MIME base64)
 
118
 
 
119
.ta 2.5i
 
120
.ti -2.5i
 
121
\fBagent([agent])\fP    Set/Get User-Agen in HTTP header
 
122
.ti -2.5i
 
123
\fBtimeout[secs])\fP    Set/Get request timeout (Def: 3min)
 
124
.ti -2.5i
 
125
\fBmax_size[bytes])\fP  Set/Get maximal size for response content (Def: No)
 
126
.ti -2.5i
 
127
\fBfrom([email])\fP     Set/Get E-Mail address for From header
 
128
.ti -2.5i
 
129
\fBparse_head([bool])\fP        Set/Get flag value indicating whether response
 
130
headers are initialized. (Def: true)
 
131
 
 
132
.ti -2.5i
 
133
\fBproxy(prot,proxy)\fP Specifies proxy, first arg specify proxy protocol[http|ftp|...] 
 
134
(may be either single protocol or list of protocols) and second proxy URL address.
 
135
.ti -2.5i
 
136
\fBno_proxy(domains)\fP Don't use proxy for specified list of  domains
 
137
.ti -2.5i
 
138
\fBenv_proxy()\fP       Use proxy parameters from HTTP_PROXY & NO_PROXY
 
139
enviroment virables
 
140
 
 
141
.ti -2.5i
 
142
\fBmirror(url,file)\fP  Copies the contents of url into the file when the 
 
143
length or modification date headers are different form any previous retrival.
 
144
Returns HTTP::Response object, where response code indicates what happened.
 
145
.========================================================================
 
146
.sh 2 LWP::Simple
 
147
.br
 
148
.ta 2.5i
 
149
.in 2.5i
 
150
.ti -2.5i
 
151
\fB$err=get(url)\fP     Returns contents of the specified url
 
152
.ti -2.5i
 
153
\fB$err=getprint(url)\fP        Prints contents of the url on stdout and
 
154
returns HTTP status code given by the server.
 
155
.ti -2.5i
 
156
\fB$err=getstore(url,file)\fP   Stores url into file and returns status
 
157
.ti -2.5i
 
158
\fB$err=mirror(url,file)\fP     Stores if url changed
 
159
.ti -2.5i
 
160
\fBis_success($err)\fP  Returns true if request was successful
 
161
.ti -2.5i
 
162
\fBus_error($err)\fP    Returns true if error occured
 
163
 
 
164
.in 2i
 
165
.ta 2i
 
166
.ti -2i
 
167
\fBhead(url)\fP Returns header information about specified url in the form:\fI ($content_type, 
 
168
$document_length, $modified_time, $expires, $server)\fP
 
169
.==========================================================================
 
170
.sh 1 HTTP::Request
 
171
 
 
172
.br
 
173
.ta 2i
 
174
\fB$req=new HTTP::Request(method,url,[header,[content]])\fP
 
175
.in 2.5i
 
176
.ti -2i
 
177
\fImethod:\fP   HTTP request method (GET,HEAD,POST,PUT,DELETE)
 
178
.ti -2i
 
179
\fIurl:\fP      Either a string with absolute URL or URI::URL object
 
180
.ti -2i
 
181
\fIHeader:\fP   A reference to HTTP::Headers object
 
182
.ti -2i
 
183
\fIContent:\fP  Request content
 
184
.ta 2.5i
 
185
.ti -2.5i
 
186
\fBas_string()\fP       Returns a text version of the request object
 
187
.ti -2.5i
 
188
\fBmethod([method])\fP  Set/Get HTTP method
 
189
.ti -2.5i
 
190
\fBurl([url])\fP        Set/Get URL
 
191
.in 0
 
192
.hl
 
193
.========================================================================
 
194
.sh 1 HTTP::Response
 
195
 
 
196
.in 2.5i
 
197
.ti -2.5i
 
198
\fB$resp=new HTTP::Response(rc,[msg,header,content])\fP
 
199
.ta 2i
 
200
.ti -2i
 
201
\fIrc\fP        Response code(404,...)
 
202
.ti -2i
 
203
\fImsg\fP       Error message("Not found","Ok", ...)
 
204
.ti -2i
 
205
\fIheader\fP    Response header (HTTP::Header object)
 
206
.ti -2i
 
207
\fIcontent\fP   Response content
 
208
.in 0
 
209
.ta 2i
 
210
.in 2i
 
211
.ti -2i
 
212
 
 
213
\fBas_string()\fP       Returns a string version of response
 
214
.ti -2i
 
215
\fBbase()\fP            Returns base URL of the response. If the response was
 
216
HTML, any links from page should be relative to the location returned by this
 
217
method. (Looks for BASE tag or Content-Base/Content Location header, otherwise
 
218
host name used)
 
219
 
 
220
.ti -2i
 
221
\fBcurrent_age()\fP     Returns number of seconds since response was generated
 
222
by original server.
 
223
.ti -2i
 
224
\fBfreshness_lifetime()\fP      Returns number of seconds untill the response
 
225
expires.
 
226
.ti -2i
 
227
\fBfresh_until()\fP     Returns the time when the response expires(in: number of
 
228
seconds since 1970)
 
229
.ti -2i
 
230
\fBis_fresh()\fP        Returns true if the response has not yet expired
 
231
 
 
232
.ti -2i
 
233
\fBcode([code])\fP      Set/Get response code
 
234
.ti -2i 
 
235
\fBmessage([msg])\fP    Set/Get object status code message
 
236
.ti -2i
 
237
\fBis_info()\fP True if response code in [100,199]
 
238
.ti -2i
 
239
\fBis_success()\fP      True if response code in [200,299]
 
240
.ti -2i
 
241
\fBis_redirect()\fP     True if response code in [300,399]
 
242
.ti -2i
 
243
\fBis_error()\fP        True if response code in [400,599]
 
244
.ti -2i
 
245
\fBerror_as_HTML()\fP   Returns HTML explanation of what happened
 
246
.in 0
 
247
.hl
 
248
.========================================================================
 
249
.sh 1 HTTP::Headers
 
250
 
 
251
.in 2.5i
 
252
.ta 2.5i
 
253
.ti -2.5i
 
254
\fB$h=new HTTP::Header([name => val],...)\fP
 
255
.ti -2.5i
 
256
\fBclone()\fP   Create a copy of the current object and returns reference to it
 
257
.ti -2.5i
 
258
\fBheader(field[=>val],...)\fP  Set/Get header fields values
 
259
.ti -2.5i
 
260
\fBpush_header(field=>val)\fP   Set new header field (old value are not removed!)
 
261
.ti -2.5i
 
262
\fBremove_header(field)\fP      Removes header field
 
263
.ti -2.5i
 
264
\fBscan(\\&sub)\fP      Invokes subroutin referenced by $sub for each header in
 
265
the object. The subroutine is passed the name of the header and its values as
 
266
a pair of arguments. For header fields with more than one value, the subroutine
 
267
will be called once for each value.
 
268
.in 0
 
269
.hl
 
270
.============================================================================
 
271
.sh 1 HTTP::Cookies
 
272
Module is used to retrive, return, and manage cookies.
 
273
 
 
274
\fB$cjar=new HTTP::Cookies(file=>name,autosave=>1,ignore_discard=>0)\fP
 
275
.in 2.5i
 
276
.ta 2i
 
277
.ti -2i
 
278
\fIfile\fP      File cookie to be loaded from(automaticaly)
 
279
.ti -2i
 
280
\fIautosave\fP  Save new cookies to file automaticaly
 
281
.ti -2i
 
282
\fIignore_discard\fP    Save to file discarded cookies
 
283
.ta 2.5i
 
284
.ti -2.5i
 
285
\fBas_string([discard])\fP      Returns current content of the cookie jar as
 
286
a string.If discard is true, cookies marked as discarded will not be output.
 
287
.ti -2.5i
 
288
\fBadd_cookie_header($req)\fP   Adds appropriate Cookie header to HTTP::Request
 
289
(Searches cookie jar for any cookies matching the request URL and if they are
 
290
valid(not expired) are used to create Cookie headers.
 
291
.ti -2.5i
 
292
\fBextract_cookies($resp)\fP    Searches HTTP::Response for any Set-Cookie[2] 
 
293
headers and store their information to cookie jar(hisself).
 
294
.ti -2.5i
 
295
\fBload([file])\fP      Loads cookie information from specified file(By default
 
296
from file specified during construction)
 
297
.ti -2.5i
 
298
\fBsave([file])\fP      Saves cookie information
 
299
.ti -2.5i
 
300
\fBrevert()\fP  Restores the cookie jar to its state before the last save
 
301
.ti -2.5i
 
302
\fBclear([domain,path,name])\fP Deletes cookies belonging to specified domain,
 
303
path or name(All if parametr omitted)
 
304
.ti -2.5i
 
305
\fBscan(\\&callback)\fP Invokes callback subroutine for each cookie in the jar.
 
306
Callback called with same options that are given to the set_cookie()
 
307
.ti -2.5i
 
308
\fBset_cookie(
 
309
.ti -2i
 
310
.ta 2i
 
311
\fIversion,\fR  the cookie-spec version number
 
312
.ti -2i
 
313
\fIname,\fR     cookie name
 
314
.ti -2i
 
315
\fIval,\fR      cookie value
 
316
.ti -2i
 
317
\fIpath,\fR     pathname of the URL for which the cookie is set
 
318
.ti -2i
 
319
\fIdomain,\fR   domain name for which cookie is set
 
320
.ti -2i
 
321
\fIport,\fR     pirt number for which cookie is set
 
322
.ti -2i
 
323
\fIpath_spec,\fR        boolean value indicating if the cookie valid for 
 
324
specific URL path(true) or all the URLs in the domain. 
 
325
.ti -2i
 
326
\fIsecure,\fR   boolean value indicating if cookie should only be sent over a
 
327
secure connection
 
328
.ti -2i
 
329
\fImaxage,\fR   number of seconds that the cookie will be valid
 
330
.ti -2i
 
331
\fIdiscard,\fR  boolean, indicating that the cookie should not be sent in any
 
332
future requests and should be discarded upon saving the cookie jar.
 
333
.ti -2i
 
334
\fI\\%misc)\fR  Additional parametrs
 
335
.==========================================================================
 
336
.sh 1 HTTP::Message
 
337
Base class for HTTP::Request, HTTP::Response
 
338
 
 
339
.in 2.5i
 
340
.ta 2.5i
 
341
.ti -2.5i
 
342
\fBclone()\fP   Creates copy of object & return reference to it
 
343
.ti -2.5i
 
344
\fBadd_content(data)\fP Appends data to the end of the object's current entity body.
 
345
.ti -2.5i
 
346
\fBcontent([cnt])\fP    Set/Get content
 
347
.ti -2.5i
 
348
\fBcontent_ref()\fP     Returns reference to the string containig the content body
 
349
.ti -2.5i
 
350
\fBheaders()\fP Returns embedded HTTP::Headers object from the message object
 
351
.ti -2.5i
 
352
\fBprotocol([str])\fP   Set/Get HTTP protocol string(something like HTTP/1.1)
 
353
.in 0
 
354
.hl
 
355
.=============================================================================
 
 
b'\\ No newline at end of file'