local-lib5/man/man3/File::Type::Builder.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "File::Type::Builder 3"
 127 .TH File::Type::Builder 3 "2004-05-06" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 File::Type::Builder \- parse mime\-magic and generate code
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    my $build = File::Type::Builder\->new();
 138 \&
 139 \&    while (<magic>) {
 140 \&      chomp;
 141 \&      my $parsed = $build\->parse_magic($_);
 142 \&
 143 \&      my $code   = $build\->string_start($parsed);
 144 \&      (or string_offset or beshort)
 145 \&    }
 146 .Ve
 147 .SH "DESCRIPTION"
 148 .IX Header "DESCRIPTION"
 149 Reads in the mime-magic file format and translates it to code.
 150 (This documentation would be longer if I really expected anyone other
 151 than me to run the code.)
 152 .SH "METHODS"
 153 .IX Header "METHODS"
 154 .SS "new"
 155 .IX Subsection "new"
 156 Creates a new File::Type::Builder object.
 157 .SS "parse_magic"
 158 .IX Subsection "parse_magic"
 159 Pulls apart a line of a mime-magic file using a string of regular
 160 expressions.
 161 .PP
 162 An example mime-magic file can be found in cleancode \s-1CVS\s0 at
 163 <http://cleancode.org/cgi\-bin/viewcvs.cgi/email/mime\-magic.mime?rev=1.1.1.1>
 164 .SS "string"
 165 .IX Subsection "string"
 166 Builds code to match magic that's of type string.
 167 .PP
 168 Has to do some cleverness to make the regular expression work properly.
 169 .SS "be"
 170 .IX Subsection "be"
 171 Builds code to match 'beshort' and 'belong' magic (eg audio/mpeg,
 172 image/jpeg).
 173 .SH "PRIVATE METHODS"
 174 .IX Header "PRIVATE METHODS"
 175 .SS "_substr_matching"
 176 .IX Subsection "_substr_matching"
 177 Sometimes the data is smaller than the offset we're looking for in the
 178 file. If this is the case, then the file is obviously not of that type,
 179 and furthermore we should avoid issuing a couple of warnings that Perl
 180 would otherwise emit.
 181 .PP
 182 This subroutine generates this code.
 183 .SS "_get_escapes"
 184 .IX Subsection "_get_escapes"
 185 Returns a reference to a hash defining characters that should not be
 186 escaped.
 187 .SH "TODO"
 188 .IX Header "TODO"
 189 .RS 4
 190 * Add handlers for other magic types (bedate, byte, etc)
 191 .Sp
 192 * Make verbosity/logging nicer.
 193 .Sp
 194 * Find more edge cases.
 195 .Sp
 196 * Remove redundant 'if (length \f(CW$data\fR > 0)' check.
 197 .RE
 198 .PP
 199 Longer term:
 200 .Sp
 201 .RS 4
 202 * Fix for multiple magic format types?
 203 .RE
 204 .SH "BUGS"
 205 .IX Header "BUGS"
 206 Incomplete. Some known issues with odd entries in mime-magic. Skips
 207 some mime-magic lines.
 208 .SH "SEE ALSO"
 209 .IX Header "SEE ALSO"
 210 File::Type, which is partially generated by this module.
 211 .SH "AUTHOR"
 212 .IX Header "AUTHOR"
 213 Paul Mison <pmison@fotango.com>
 214 .SH "COPYRIGHT"
 215 .IX Header "COPYRIGHT"
 216 Copyright 2003 Fotango Ltd.
 217 .SH "LICENSE"
 218 .IX Header "LICENSE"
 219 Licensed under the same terms as Perl itself.