local-lib5/man/man3/WWW::RobotRules.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "WWW::RobotRules 3"
 132 .TH WWW::RobotRules 3 "2009-10-03" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 WWW::RobotRules \- database of robots.txt\-derived permissions
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \& use WWW::RobotRules;
 139 \& my $rules = WWW::RobotRules\->new('MOMspider/1.0');
 140 .Ve
 141 .PP
 142 .Vb 1
 143 \& use LWP::Simple qw(get);
 144 .Ve
 145 .PP
 146 .Vb 5
 147 \& {
 148 \&   my $url = "http://some.place/robots.txt";
 149 \&   my $robots_txt = get $url;
 150 \&   $rules\->parse($url, $robots_txt) if defined $robots_txt;
 151 \& }
 152 .Ve
 153 .PP
 154 .Vb 5
 155 \& {
 156 \&   my $url = "http://some.other.place/robots.txt";
 157 \&   my $robots_txt = get $url;
 158 \&   $rules\->parse($url, $robots_txt) if defined $robots_txt;
 159 \& }
 160 .Ve
 161 .PP
 162 .Vb 6
 163 \& # Now we can check if a URL is valid for those servers
 164 \& # whose "robots.txt" files we've gotten and parsed:
 165 \& if($rules\->allowed($url)) {
 166 \&     $c = get $url;
 167 \&     ...
 168 \& }
 169 .Ve
 170 .SH "DESCRIPTION"
 171 .IX Header "DESCRIPTION"
 172 This module parses \fI/robots.txt\fR files as specified in
 173 \&\*(L"A Standard for Robot Exclusion\*(R", at
 174 <http://www.robotstxt.org/wc/norobots.html>
 175 Webmasters can use the \fI/robots.txt\fR file to forbid conforming
 176 robots from accessing parts of their web site.
 177 .PP
 178 The parsed files are kept in a WWW::RobotRules object, and this object
 179 provides methods to check if access to a given \s-1URL\s0 is prohibited.  The
 180 same WWW::RobotRules object can be used for one or more parsed
 181 \&\fI/robots.txt\fR files on any number of hosts.
 182 .PP
 183 The following methods are provided:
 184 .IP "$rules = WWW::RobotRules\->new($robot_name)" 4
 185 .IX Item "$rules = WWW::RobotRules->new($robot_name)"
 186 This is the constructor for WWW::RobotRules objects.  The first
 187 argument given to \fInew()\fR is the name of the robot.
 188 .ie n .IP "$rules\->parse($robot_txt_url, $content\fR, \f(CW$fresh_until)" 4
 189 .el .IP "$rules\->parse($robot_txt_url, \f(CW$content\fR, \f(CW$fresh_until\fR)" 4
 190 .IX Item "$rules->parse($robot_txt_url, $content, $fresh_until)"
 191 The \fIparse()\fR method takes as arguments the \s-1URL\s0 that was used to
 192 retrieve the \fI/robots.txt\fR file, and the contents of the file.
 193 .IP "$rules\->allowed($uri)" 4
 194 .IX Item "$rules->allowed($uri)"
 195 Returns \s-1TRUE\s0 if this robot is allowed to retrieve this \s-1URL\s0.
 196 .IP "$rules\->agent([$name])" 4
 197 .IX Item "$rules->agent([$name])"
 198 Get/set the agent name. \s-1NOTE:\s0 Changing the agent name will clear the robots.txt
 199 rules and expire times out of the cache.
 200 .SH "ROBOTS.TXT"
 201 .IX Header "ROBOTS.TXT"
 202 The format and semantics of the \*(L"/robots.txt\*(R" file are as follows
 203 (this is an edited abstract of
 204 <http://www.robotstxt.org/wc/norobots.html>):
 205 .PP
 206 The file consists of one or more records separated by one or more
 207 blank lines. Each record contains lines of the form
 208 .PP
 209 .Vb 1
 210 \&  <field\-name>: <value>
 211 .Ve
 212 .PP
 213 The field name is case insensitive.  Text after the '#' character on a
 214 line is ignored during parsing.  This is used for comments.  The
 215 following <field\-names> can be used:
 216 .IP "User-Agent" 3
 217 .IX Item "User-Agent"
 218 The value of this field is the name of the robot the record is
 219 describing access policy for.  If more than one \fIUser-Agent\fR field is
 220 present the record describes an identical access policy for more than
 221 one robot. At least one field needs to be present per record.  If the
 222 value is '*', the record describes the default access policy for any
 223 robot that has not not matched any of the other records.
 224 .Sp
 225 The \fIUser-Agent\fR fields must occur before the \fIDisallow\fR fields.  If a
 226 record contains a \fIUser-Agent\fR field after a \fIDisallow\fR field, that
 227 constitutes a malformed record.  This parser will assume that a blank
 228 line should have been placed before that \fIUser-Agent\fR field, and will
 229 break the record into two.  All the fields before the \fIUser-Agent\fR field
 230 will constitute a record, and the \fIUser-Agent\fR field will be the first
 231 field in a new record.
 232 .IP "Disallow" 3
 233 .IX Item "Disallow"
 234 The value of this field specifies a partial \s-1URL\s0 that is not to be
 235 visited. This can be a full path, or a partial path; any \s-1URL\s0 that
 236 starts with this value will not be retrieved
 237 .PP
 238 Unrecognized records are ignored.
 239 .SH "ROBOTS.TXT EXAMPLES"
 240 .IX Header "ROBOTS.TXT EXAMPLES"
 241 The following example \*(L"/robots.txt\*(R" file specifies that no robots
 242 should visit any \s-1URL\s0 starting with \*(L"/cyberworld/map/\*(R" or \*(L"/tmp/\*(R":
 243 .PP
 244 .Vb 3
 245 \&  User\-agent: *
 246 \&  Disallow: /cyberworld/map/ # This is an infinite virtual URL space
 247 \&  Disallow: /tmp/ # these will soon disappear
 248 .Ve
 249 .PP
 250 This example \*(L"/robots.txt\*(R" file specifies that no robots should visit
 251 any \s-1URL\s0 starting with \*(L"/cyberworld/map/\*(R", except the robot called
 252 \&\*(L"cybermapper\*(R":
 253 .PP
 254 .Vb 2
 255 \&  User\-agent: *
 256 \&  Disallow: /cyberworld/map/ # This is an infinite virtual URL space
 257 .Ve
 258 .PP
 259 .Vb 3
 260 \&  # Cybermapper knows where to go.
 261 \&  User\-agent: cybermapper
 262 \&  Disallow:
 263 .Ve
 264 .PP
 265 This example indicates that no robots should visit this site further:
 266 .PP
 267 .Vb 3
 268 \&  # go away
 269 \&  User\-agent: *
 270 \&  Disallow: /
 271 .Ve
 272 .PP
 273 This is an example of a malformed robots.txt file.
 274 .PP
 275 .Vb 10
 276 \&  # robots.txt for ancientcastle.example.com
 277 \&  # I've locked myself away.
 278 \&  User\-agent: *
 279 \&  Disallow: /
 280 \&  # The castle is your home now, so you can go anywhere you like.
 281 \&  User\-agent: Belle
 282 \&  Disallow: /west\-wing/ # except the west wing!
 283 \&  # It's good to be the Prince...
 284 \&  User\-agent: Beast
 285 \&  Disallow:
 286 .Ve
 287 .PP
 288 This file is missing the required blank lines between records.
 289 However, the intention is clear.
 290 .SH "SEE ALSO"
 291 .IX Header "SEE ALSO"
 292 LWP::RobotUA, WWW::RobotRules::AnyDBM_File