local-lib5/man/man3/YAML.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 "YAML 3"
 132 .TH YAML 3 "2009-08-10" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 YAML \- YAML Ain't Markup Language (tm)
 135 .SH "NOTE"
 136 .IX Header "NOTE"
 137 This module has been released to \s-1CPAN\s0 as YAML::Old, and soon \s-1YAML\s0.pm
 138 will be changed to just be a frontend interface module for all the
 139 various Perl \s-1YAML\s0 implementation modules, including YAML::Old.
 140 .PP
 141 If you want robust and fast \s-1YAML\s0 processing using the normal Dump/Load
 142 \&\s-1API\s0, please consider switching to \s-1YAML::XS\s0. It is by far the best Perl
 143 module for \s-1YAML\s0 at this time. It requires that you have a C compiler,
 144 since it is written in C.
 145 .PP
 146 If you really need to use this version of \s-1YAML\s0.pm it will always be
 147 available as YAML::Old.
 148 .PP
 149 If you don't care which \s-1YAML\s0 module use, as long as it's the best one
 150 installed on your system, use YAML::Any.
 151 .PP
 152 The rest of this documentation is left unchanged, until \s-1YAML\s0.pm is
 153 switched over to the new UI-only version.
 154 .SH "SYNOPSIS"
 155 .IX Header "SYNOPSIS"
 156 .Vb 1
 157 \&    use YAML;
 158 .Ve
 159 .PP
 160 .Vb 20
 161 \&    # Load a YAML stream of 3 YAML documents into Perl data structures.
 162 \&    my ($hashref, $arrayref, $string) = Load(<<'...');
 163 \&    \-\-\-
 164 \&    name: ingy
 165 \&    age: old
 166 \&    weight: heavy
 167 \&    # I should comment that I also like pink, but don't tell anybody.
 168 \&    favorite colors:
 169 \&        \- red
 170 \&        \- green
 171 \&        \- blue
 172 \&    \-\-\-
 173 \&    \- Clark Evans
 174 \&    \- Oren Ben\-Kiki
 175 \&    \- Ingy döt Net
 176 \&    \-\-\- >
 177 \&    You probably think YAML stands for "Yet Another Markup Language". It
 178 \&    ain't! YAML is really a data serialization language. But if you want
 179 \&    to think of it as a markup, that's OK with me. A lot of people try
 180 \&    to use XML as a serialization format.
 181 .Ve
 182 .PP
 183 .Vb 2
 184 \&    "YAML" is catchy and fun to say. Try it. "YAML, YAML, YAML!!!"
 185 \&    ...
 186 .Ve
 187 .PP
 188 .Vb 2
 189 \&    # Dump the Perl data structures back into YAML.
 190 \&    print Dump($string, $arrayref, $hashref);
 191 .Ve
 192 .PP
 193 .Vb 3
 194 \&    # YAML::Dump is used the same way you'd use Data::Dumper::Dumper
 195 \&    use Data::Dumper;
 196 \&    print Dumper($string, $arrayref, $hashref);
 197 .Ve
 198 .SH "DESCRIPTION"
 199 .IX Header "DESCRIPTION"
 200 The \s-1YAML\s0.pm module implements a \s-1YAML\s0 Loader and Dumper based on the \s-1YAML\s0
 201 1.0 specification. <http://www.yaml.org/spec/>
 202 .PP
 203 \&\s-1YAML\s0 is a generic data serialization language that is optimized for
 204 human readability. It can be used to express the data structures of most
 205 modern programming languages. (Including Perl!!!)
 206 .PP
 207 For information on the \s-1YAML\s0 syntax, please refer to the \s-1YAML\s0
 208 specification.
 209 .SH "WHY YAML IS COOL"
 210 .IX Header "WHY YAML IS COOL"
 211 .IP "\s-1YAML\s0 is readable for people." 4
 212 .IX Item "YAML is readable for people."
 213 It makes clear sense out of complex data structures. You should find
 214 that \s-1YAML\s0 is an exceptional data dumping tool. Structure is shown
 215 through indentation, \s-1YAML\s0 supports recursive data, and hash keys are
 216 sorted by default. In addition, \s-1YAML\s0 supports several styles of scalar
 217 formatting for different types of data.
 218 .IP "\s-1YAML\s0 is editable." 4
 219 .IX Item "YAML is editable."
 220 \&\s-1YAML\s0 was designed from the ground up to be an excellent syntax for
 221 configuration files. Almost all programs need configuration files, so
 222 why invent a new syntax for each one? And why subject users to the
 223 complexities of \s-1XML\s0 or native Perl code?
 224 .IP "\s-1YAML\s0 is multilingual." 4
 225 .IX Item "YAML is multilingual."
 226 Yes, \s-1YAML\s0 supports Unicode. But I'm actually referring to programming
 227 languages. \s-1YAML\s0 was designed to meet the serialization needs of Perl,
 228 Python, Ruby, Tcl, \s-1PHP\s0, Javascript and Java. It was also designed to be
 229 interoperable between those languages. That means \s-1YAML\s0 serializations
 230 produced by Perl can be processed by Python.
 231 .IP "\s-1YAML\s0 is taint safe." 4
 232 .IX Item "YAML is taint safe."
 233 Using modules like Data::Dumper for serialization is fine as long as you
 234 can be sure that nobody can tamper with your data files or
 235 transmissions. That's because you need to use Perl's \f(CW\*(C`eval()\*(C'\fR built-in
 236 to deserialize the data. Somebody could add a snippet of Perl to erase
 237 your files.
 238 .Sp
 239 \&\s-1YAML\s0's parser does not need to eval anything.
 240 .IP "\s-1YAML\s0 is full featured." 4
 241 .IX Item "YAML is full featured."
 242 \&\s-1YAML\s0 can accurately serialize all of the common Perl data structures and
 243 deserialize them again without losing data relationships. Although it is
 244 not 100% perfect (no serializer is or can be perfect), it fares as well
 245 as the popular current modules: Data::Dumper, Storable, XML::Dumper and
 246 Data::Denter.
 247 .Sp
 248 \&\s-1YAML\s0.pm also has the ability to handle code (subroutine) references and
 249 typeglobs. (Still experimental) These features are not found in Perl's
 250 other serialization modules.
 251 .IP "\s-1YAML\s0 is extensible." 4
 252 .IX Item "YAML is extensible."
 253 The \s-1YAML\s0 language has been designed to be flexible enough to solve it's
 254 own problems. The markup itself has 3 basic construct which resemble
 255 Perl's hash, array and scalar. By default, these map to their Perl
 256 equivalents. But each \s-1YAML\s0 node also supports a tagging mechanism (type
 257 system) which can cause that node to be interpreted in a completely
 258 different manner. That's how \s-1YAML\s0 can support object serialization and
 259 oddball structures like Perl's typeglob.
 260 .SH "YAML IMPLEMENTATIONS IN PERL"
 261 .IX Header "YAML IMPLEMENTATIONS IN PERL"
 262 This module, \s-1YAML\s0.pm, is really just the interface module for \s-1YAML\s0
 263 modules written in Perl. The basic interface for \s-1YAML\s0 consists of two
 264 functions: \f(CW\*(C`Dump\*(C'\fR and \f(CW\*(C`Load\*(C'\fR. The real work is done by the modules
 265 YAML::Dumper and YAML::Loader.
 266 .PP
 267 Different \s-1YAML\s0 module distributions can be created by subclassing
 268 \&\s-1YAML\s0.pm and YAML::Loader and YAML::Dumper. For example, YAML-Simple
 269 consists of YAML::Simple YAML::Dumper::Simple and YAML::Loader::Simple.
 270 .PP
 271 Why would there be more than one implementation of \s-1YAML\s0? Well, despite
 272 \&\s-1YAML\s0's offering of being a simple data format, \s-1YAML\s0 is actually very
 273 deep and complex. Implementing the entirety of the \s-1YAML\s0 specification is
 274 a daunting task.
 275 .PP
 276 For this reason I am currently working on 3 different \s-1YAML\s0 implementations.
 277 .IP "\s-1YAML\s0" 4
 278 .IX Item "YAML"
 279 The main \s-1YAML\s0 distribution will keeping evolving to support the entire
 280 \&\s-1YAML\s0 specification in pure Perl. This may not be the fastest or most
 281 stable module though. Currently, \s-1YAML\s0.pm has lots of known bugs. It is
 282 mostly a great tool for dumping Perl data structures to a readable form.
 283 .IP "YAML::Lite" 4
 284 .IX Item "YAML::Lite"
 285 The point of YAML::Lite is to strip \s-1YAML\s0 down to the 90% that people
 286 use most and offer that in a small, fast, stable, pure Perl form.
 287 YAML::Lite will simply die when it is asked to do something it can't.
 288 .IP "YAML::Syck" 4
 289 .IX Item "YAML::Syck"
 290 \&\f(CW\*(C`libsyck\*(C'\fR is the C based \s-1YAML\s0 processing library used by the Ruby
 291 programming language (and also Python, \s-1PHP\s0 and Pugs). YAML::Syck is the
 292 Perl binding to \f(CW\*(C`libsyck\*(C'\fR. It should be very fast, but may have
 293 problems of its own. It will also require C compilation.
 294 .Sp
 295 \&\s-1NOTE:\s0 Audrey Tang has actually completed this module and it works great
 296       and is 10 times faster than \s-1YAML\s0.pm.
 297 .PP
 298 In the future, there will likely be even more \s-1YAML\s0 modules. Remember,
 299 people other than Ingy are allowed to write \s-1YAML\s0 modules!
 300 .SH "FUNCTIONAL USAGE"
 301 .IX Header "FUNCTIONAL USAGE"
 302 \&\s-1YAML\s0 is completely \s-1OO\s0 under the hood. Still it exports a few useful top
 303 level functions so that it is dead simple to use. These functions just
 304 do the \s-1OO\s0 stuff for you. If you want direct access to the \s-1OO\s0 \s-1API\s0 see the
 305 documentation for YAML::Dumper and YAML::Loader.
 306 .Sh "Exported Functions"
 307 .IX Subsection "Exported Functions"
 308 The following functions are exported by \s-1YAML\s0.pm by default. The reason
 309 they are exported is so that \s-1YAML\s0 works much like Data::Dumper. If you
 310 don't want functions to be imported, just use \s-1YAML\s0 with an empty
 311 import list:
 312 .PP
 313 .Vb 1
 314 \&    use YAML ();
 315 .Ve
 316 .IP "Dump(list\-of\-Perl\-data\-structures)" 4
 317 .IX Item "Dump(list-of-Perl-data-structures)"
 318 Turn Perl data into \s-1YAML\s0. This function works very much like
 319 \&\fIData::Dumper::Dumper()\fR. It takes a list of Perl data strucures and
 320 dumps them into a serialized form. It returns a string containing the
 321 \&\s-1YAML\s0 stream. The structures can be references or plain scalars.
 322 .IP "Load(string\-containing\-a\-YAML\-stream)" 4
 323 .IX Item "Load(string-containing-a-YAML-stream)"
 324 Turn \s-1YAML\s0 into Perl data. This is the opposite of Dump. Just like
 325 Storable's \fIthaw()\fR function or the \fIeval()\fR function in relation to
 326 Data::Dumper. It parses a string containing a valid \s-1YAML\s0 stream into a
 327 list of Perl data structures.
 328 .Sh "Exportable Functions"
 329 .IX Subsection "Exportable Functions"
 330 These functions are not exported by default but you can request them in
 331 an import list like this:
 332 .PP
 333 .Vb 1
 334 \&    use YAML qw'freeze thaw Bless';
 335 .Ve
 336 .IP "\fIfreeze()\fR and \fIthaw()\fR" 4
 337 .IX Item "freeze() and thaw()"
 338 Aliases to \fIDump()\fR and \fILoad()\fR for Storable fans. This will also allow
 339 \&\s-1YAML\s0.pm to be plugged directly into modules like \s-1POE\s0.pm, that use the
 340 freeze/thaw \s-1API\s0 for internal serialization.
 341 .IP "DumpFile(filepath, list)" 4
 342 .IX Item "DumpFile(filepath, list)"
 343 Writes the \s-1YAML\s0 stream to a file instead of just returning a string.
 344 .IP "LoadFile(filepath)" 4
 345 .IX Item "LoadFile(filepath)"
 346 Reads the \s-1YAML\s0 stream from a file instead of a string.
 347 .IP "Bless(perl\-node, [yaml\-node | class\-name])" 4
 348 .IX Item "Bless(perl-node, [yaml-node | class-name])"
 349 Associate a normal Perl node, with a yaml node. A yaml node is an object
 350 tied to the YAML::Node class. The second argument is either a yaml node
 351 that you've already created or a class (package) name that supports a
 352 \&\fIyaml_dump()\fR function. A \fIyaml_dump()\fR function should take a perl node and
 353 return a yaml node. If no second argument is provided, Bless will create
 354 a yaml node. This node is not returned, but can be retrieved with the
 355 \&\fIBlessed()\fR function.
 356 .Sp
 357 Here's an example of how to use Bless. Say you have a hash containing
 358 three keys, but you only want to dump two of them. Furthermore the keys
 359 must be dumped in a certain order. Here's how you do that:
 360 .Sp
 361 .Vb 5
 362 \&    use YAML qw(Dump Bless);
 363 \&    $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
 364 \&    print Dump $hash;
 365 \&    Bless($hash)\->keys(['banana', 'apple']);
 366 \&    print Dump $hash;
 367 .Ve
 368 .Sp
 369 produces:
 370 .Sp
 371 .Vb 7
 372 \&    \-\-\-
 373 \&    apple: good
 374 \&    banana: bad
 375 \&    cauliflower: ugly
 376 \&    \-\-\-
 377 \&    banana: bad
 378 \&    apple: good
 379 .Ve
 380 .Sp
 381 Bless returns the tied part of a yaml\-node, so that you can call the
 382 YAML::Node methods. This is the same thing that \fIYAML::Node::ynode()\fR
 383 returns. So another way to do the above example is:
 384 .Sp
 385 .Vb 8
 386 \&    use YAML qw(Dump Bless);
 387 \&    use YAML::Node;
 388 \&    $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
 389 \&    print Dump $hash;
 390 \&    Bless($hash);
 391 \&    $ynode = ynode(Blessed($hash));
 392 \&    $ynode\->keys(['banana', 'apple']);
 393 \&    print Dump $hash;
 394 .Ve
 395 .Sp
 396 Note that Blessing a Perl data structure does not change it anyway. The
 397 extra information is stored separately and looked up by the Blessed
 398 node's memory address.
 399 .IP "Blessed(perl\-node)" 4
 400 .IX Item "Blessed(perl-node)"
 401 Returns the yaml node that a particular perl node is associated with
 402 (see above). Returns undef if the node is not (\s-1YAML\s0) Blessed.
 403 .SH "GLOBAL OPTIONS"
 404 .IX Header "GLOBAL OPTIONS"
 405 \&\s-1YAML\s0 options are set using a group of global variables in the \s-1YAML\s0
 406 namespace. This is similar to how Data::Dumper works.
 407 .PP
 408 For example, to change the indentation width, do something like:
 409 .PP
 410 .Vb 1
 411 \&    local $YAML::Indent = 3;
 412 .Ve
 413 .PP
 414 The current options are:
 415 .IP "DumperClass" 4
 416 .IX Item "DumperClass"
 417 You can override which module/class \s-1YAML\s0 uses for Dumping data.
 418 .IP "LoaderClass" 4
 419 .IX Item "LoaderClass"
 420 You can override which module/class \s-1YAML\s0 uses for Loading data.
 421 .IP "Indent" 4
 422 .IX Item "Indent"
 423 This is the number of space characters to use for each indentation level
 424 when doing a \fIDump()\fR. The default is 2.
 425 .Sp
 426 By the way, \s-1YAML\s0 can use any number of characters for indentation at any
 427 level. So if you are editing \s-1YAML\s0 by hand feel free to do it anyway that
 428 looks pleasing to you; just be consistent for a given level.
 429 .IP "SortKeys" 4
 430 .IX Item "SortKeys"
 431 Default is 1. (true)
 432 .Sp
 433 Tells \s-1YAML\s0.pm whether or not to sort hash keys when storing a document.
 434 .Sp
 435 YAML::Node objects can have their own sort order, which is usually what
 436 you want. To override the YAML::Node order and sort the keys anyway, set
 437 SortKeys to 2.
 438 .IP "Stringify" 4
 439 .IX Item "Stringify"
 440 Default is 0. (false)
 441 .Sp
 442 Objects with string overloading should honor the overloading and dump the
 443 stringification of themselves, rather than the actual object's guts.
 444 .IP "UseHeader" 4
 445 .IX Item "UseHeader"
 446 Default is 1. (true)
 447 .Sp
 448 This tells \s-1YAML\s0.pm whether to use a separator string for a Dump
 449 operation. This only applies to the first document in a stream.
 450 Subsequent documents must have a \s-1YAML\s0 header by definition.
 451 .IP "UseVersion" 4
 452 .IX Item "UseVersion"
 453 Default is 0. (false)
 454 .Sp
 455 Tells \s-1YAML\s0.pm whether to include the \s-1YAML\s0 version on the
 456 separator/header.
 457 .Sp
 458 .Vb 1
 459 \&    \-\-\- %YAML:1.0
 460 .Ve
 461 .IP "AnchorPrefix" 4
 462 .IX Item "AnchorPrefix"
 463 Default is ''.
 464 .Sp
 465 Anchor names are normally numeric. \s-1YAML\s0.pm simply starts with '1' and
 466 increases by one for each new anchor. This option allows you to specify a
 467 string to be prepended to each anchor number.
 468 .IP "UseCode" 4
 469 .IX Item "UseCode"
 470 Setting the UseCode option is a shortcut to set both the DumpCode and
 471 LoadCode options at once. Setting UseCode to '1' tells \s-1YAML\s0.pm to dump
 472 Perl code references as Perl (using B::Deparse) and to load them back
 473 into memory using \fIeval()\fR. The reason this has to be an option is that
 474 using \fIeval()\fR to parse untrusted code is, well, untrustworthy.
 475 .IP "DumpCode" 4
 476 .IX Item "DumpCode"
 477 Determines if and how \s-1YAML\s0.pm should serialize Perl code references. By
 478 default \s-1YAML\s0.pm will dump code references as dummy placeholders (much
 479 like Data::Dumper). If DumpCode is set to '1' or 'deparse', code
 480 references will be dumped as actual Perl code.
 481 .Sp
 482 DumpCode can also be set to a subroutine reference so that you can
 483 write your own serializing routine. \s-1YAML\s0.pm passes you the code ref. You
 484 pass back the serialization (as a string) and a format indicator. The
 485 format indicator is a simple string like: 'deparse' or 'bytecode'.
 486 .IP "LoadCode" 4
 487 .IX Item "LoadCode"
 488 LoadCode is the opposite of DumpCode. It tells \s-1YAML\s0 if and how to
 489 deserialize code references. When set to '1' or 'deparse' it will use
 490 \&\f(CW\*(C`eval()\*(C'\fR. Since this is potentially risky, only use this option if you
 491 know where your \s-1YAML\s0 has been.
 492 .Sp
 493 LoadCode can also be set to a subroutine reference so that you can write
 494 your own deserializing routine. \s-1YAML\s0.pm passes the serialization (as a
 495 string) and a format indicator. You pass back the code reference.
 496 .IP "UseBlock" 4
 497 .IX Item "UseBlock"
 498 \&\s-1YAML\s0.pm uses heuristics to guess which scalar style is best for a given
 499 node. Sometimes you'll want all multiline scalars to use the 'block'
 500 style. If so, set this option to 1.
 501 .Sp
 502 \&\s-1NOTE:\s0 \s-1YAML\s0's block style is akin to Perl's here\-document.
 503 .IP "UseFold" 4
 504 .IX Item "UseFold"
 505 If you want to force \s-1YAML\s0 to use the 'folded' style for all multiline
 506 scalars, then set \f(CW$UseFold\fR to 1.
 507 .Sp
 508 \&\s-1NOTE:\s0 \s-1YAML\s0's folded style is akin to the way \s-1HTML\s0 folds text,
 509       except smarter.
 510 .IP "UseAliases" 4
 511 .IX Item "UseAliases"
 512 \&\s-1YAML\s0 has an alias mechanism such that any given structure in memory gets
 513 serialized once. Any other references to that structure are serialized
 514 only as alias markers. This is how \s-1YAML\s0 can serialize duplicate and
 515 recursive structures.
 516 .Sp
 517 Sometimes, when you \s-1KNOW\s0 that your data is nonrecursive in nature, you
 518 may want to serialize such that every node is expressed in full. (ie as
 519 a copy of the original). Setting \f(CW$YAML::UseAliases\fR to 0 will allow you
 520 to do this. This also may result in faster processing because the lookup
 521 overhead is by bypassed.
 522 .Sp
 523 \&\s-1THIS\s0 \s-1OPTION\s0 \s-1CAN\s0 \s-1BE\s0 \s-1DANGEROUS\s0. *If* your data is recursive, this option
 524 *will* cause \fIDump()\fR to run in an endless loop, chewing up your computers
 525 memory. You have been warned.
 526 .IP "CompressSeries" 4
 527 .IX Item "CompressSeries"
 528 Default is 1.
 529 .Sp
 530 Compresses the formatting of arrays of hashes:
 531 .Sp
 532 .Vb 4
 533 \&    \-
 534 \&      foo: bar
 535 \&    \-
 536 \&      bar: foo
 537 .Ve
 538 .Sp
 539 becomes:
 540 .Sp
 541 .Vb 2
 542 \&    \- foo: bar
 543 \&    \- bar: foo
 544 .Ve
 545 .Sp
 546 Since this output is usually more desirable, this option is turned on by
 547 default.
 548 .SH "YAML TERMINOLOGY"
 549 .IX Header "YAML TERMINOLOGY"
 550 \&\s-1YAML\s0 is a full featured data serialization language, and thus has its
 551 own terminology.
 552 .PP
 553 It is important to remember that although \s-1YAML\s0 is heavily influenced by
 554 Perl and Python, it is a language in its own right, not merely just a
 555 representation of Perl structures.
 556 .PP
 557 \&\s-1YAML\s0 has three constructs that are conspicuously similar to Perl's hash,
 558 array, and scalar. They are called mapping, sequence, and string
 559 respectively. By default, they do what you would expect. But each
 560 instance may have an explicit or implicit tag (type) that makes it
 561 behave differently. In this manner, \s-1YAML\s0 can be extended to represent
 562 Perl's Glob or Python's tuple, or Ruby's Bigint.
 563 .IP "stream" 4
 564 .IX Item "stream"
 565 A \s-1YAML\s0 stream is the full sequence of unicode characters that a \s-1YAML\s0
 566 parser would read or a \s-1YAML\s0 emitter would write. A stream may contain
 567 one or more \s-1YAML\s0 documents separated by \s-1YAML\s0 headers.
 568 .Sp
 569 .Vb 6
 570 \&    \-\-\-
 571 \&    a: mapping
 572 \&    foo: bar
 573 \&    \-\-\-
 574 \&    \- a
 575 \&    \- sequence
 576 .Ve
 577 .IP "document" 4
 578 .IX Item "document"
 579 A \s-1YAML\s0 document is an independent data structure representation within a
 580 stream. It is a top level node. Each document in a \s-1YAML\s0 stream must
 581 begin with a \s-1YAML\s0 header line. Actually the header is optional on the
 582 first document.
 583 .Sp
 584 .Vb 6
 585 \&    \-\-\-
 586 \&    This: top level mapping
 587 \&    is:
 588 \&        \- a
 589 \&        \- YAML
 590 \&        \- document
 591 .Ve
 592 .IP "header" 4
 593 .IX Item "header"
 594 A \s-1YAML\s0 header is a line that begins a \s-1YAML\s0 document. It consists of
 595 three dashes, possibly followed by more info. Another purpose of the
 596 header line is that it serves as a place to put top level tag and anchor
 597 information.
 598 .Sp
 599 .Vb 3
 600 \&    \-\-\- !recursive\-sequence &001
 601 \&    \- * 001
 602 \&    \- * 001
 603 .Ve
 604 .IP "node" 4
 605 .IX Item "node"
 606 A \s-1YAML\s0 node is the representation of a particular data stucture. Nodes
 607 may contain other nodes. (In Perl terms, nodes are like scalars.
 608 Strings, arrayrefs and hashrefs. But this refers to the serialized
 609 format, not the in-memory structure.)
 610 .IP "tag" 4
 611 .IX Item "tag"
 612 This is similar to a type. It indicates how a particular \s-1YAML\s0 node
 613 serialization should be transferred into or out of memory. For instance
 614 a Foo::Bar object would use the tag 'perl/Foo::Bar':
 615 .Sp
 616 .Vb 3
 617 \&    \- !perl/Foo::Bar
 618 \&        foo: 42
 619 \&        bar: stool
 620 .Ve
 621 .IP "collection" 4
 622 .IX Item "collection"
 623 A collection is the generic term for a \s-1YAML\s0 data grouping. \s-1YAML\s0 has two
 624 types of collections: mappings and sequences. (Similar to hashes and arrays)
 625 .IP "mapping" 4
 626 .IX Item "mapping"
 627 A mapping is a \s-1YAML\s0 collection defined by unordered key/value pairs with
 628 unique keys. By default \s-1YAML\s0 mappings are loaded into Perl hashes.
 629 .Sp
 630 .Vb 3
 631 \&    a mapping:
 632 \&        foo: bar
 633 \&        two: times two is 4
 634 .Ve
 635 .IP "sequence" 4
 636 .IX Item "sequence"
 637 A sequence is a \s-1YAML\s0 collection defined by an ordered list of elements. By
 638 default \s-1YAML\s0 sequences are loaded into Perl arrays.
 639 .Sp
 640 .Vb 4
 641 \&    a sequence:
 642 \&        \- one bourbon
 643 \&        \- one scotch
 644 \&        \- one beer
 645 .Ve
 646 .IP "scalar" 4
 647 .IX Item "scalar"
 648 A scalar is a \s-1YAML\s0 node that is a single value. By default \s-1YAML\s0 scalars
 649 are loaded into Perl scalars.
 650 .Sp
 651 .Vb 1
 652 \&    a scalar key: a scalar value
 653 .Ve
 654 .Sp
 655 \&\s-1YAML\s0 has many styles for representing scalars. This is important because
 656 varying data will have varying formatting requirements to retain the
 657 optimum human readability.
 658 .IP "plain scalar" 4
 659 .IX Item "plain scalar"
 660 A plain sclar is unquoted. All plain scalars are automatic candidates
 661 for \*(L"implicit tagging\*(R". This means that their tag may be determined
 662 automatically by examination. The typical uses for this are plain alpha
 663 strings, integers, real numbers, dates, times and currency.
 664 .Sp
 665 .Vb 5
 666 \&    \- a plain string
 667 \&    \- \-42
 668 \&    \- 3.1415
 669 \&    \- 12:34
 670 \&    \- 123 this is an error
 671 .Ve
 672 .IP "single quoted scalar" 4
 673 .IX Item "single quoted scalar"
 674 This is similar to Perl's use of single quotes. It means no escaping
 675 except for single quotes which are escaped by using two adjacent
 676 single quotes.
 677 .Sp
 678 .Vb 1
 679 \&    \- 'When I say ''\en'' I mean "backslash en"'
 680 .Ve
 681 .IP "double quoted scalar" 4
 682 .IX Item "double quoted scalar"
 683 This is similar to Perl's use of double quotes. Character escaping can
 684 be used.
 685 .Sp
 686 .Vb 1
 687 \&    \- "This scalar\enhas two lines, and a bell \-\->\ea"
 688 .Ve
 689 .IP "folded scalar" 4
 690 .IX Item "folded scalar"
 691 This is a multiline scalar which begins on the next line. It is
 692 indicated by a single right angle bracket. It is unescaped like the
 693 single quoted scalar. Line folding is also performed.
 694 .Sp
 695 .Vb 6
 696 \&    \- >
 697 \&     This is a multiline scalar which begins on
 698 \&     the next line. It is indicated by a single
 699 \&     carat. It is unescaped like the single
 700 \&     quoted scalar. Line folding is also
 701 \&     performed.
 702 .Ve
 703 .IP "block scalar" 4
 704 .IX Item "block scalar"
 705 This final multiline form is akin to Perl's here-document except that
 706 (as in all \s-1YAML\s0 data) scope is indicated by indentation. Therefore, no
 707 ending marker is required. The data is verbatim. No line folding.
 708 .Sp
 709 .Vb 5
 710 \&    \- |
 711 \&        QTY  DESC          PRICE  TOTAL
 712 \&        \-\-\-  \-\-\-\-          \-\-\-\-\-  \-\-\-\-\-
 713 \&          1  Foo Fighters  $19.95 $19.95
 714 \&          2  Bar Belles    $29.95 $59.90
 715 .Ve
 716 .IP "parser" 4
 717 .IX Item "parser"
 718 A \s-1YAML\s0 processor has four stages: parse, load, dump, emit.
 719 .Sp
 720 A parser parses a \s-1YAML\s0 stream. \s-1YAML\s0.pm's \fILoad()\fR function contains a
 721 parser.
 722 .IP "loader" 4
 723 .IX Item "loader"
 724 The other half of the \fILoad()\fR function is a loader. This takes the
 725 information from the parser and loads it into a Perl data structure.
 726 .IP "dumper" 4
 727 .IX Item "dumper"
 728 The \fIDump()\fR function consists of a dumper and an emitter. The dumper
 729 walks through each Perl data structure and gives info to the emitter.
 730 .IP "emitter" 4
 731 .IX Item "emitter"
 732 The emitter takes info from the dumper and turns it into a \s-1YAML\s0 stream.
 733 .Sp
 734 \&\s-1NOTE:\s0
 735 In \s-1YAML\s0.pm the parser/loader and the dumper/emitter code are currently
 736 very closely tied together. In the future they may be broken into
 737 separate stages.
 738 .PP
 739 For more information please refer to the immensely helpful \s-1YAML\s0
 740 specification available at <http://www.yaml.org/spec/>.
 741 .SH "ysh \- The YAML Shell"
 742 .IX Header "ysh - The YAML Shell"
 743 The \s-1YAML\s0 distribution ships with a script called 'ysh', the \s-1YAML\s0 shell.
 744 ysh provides a simple, interactive way to play with \s-1YAML\s0. If you type in
 745 Perl code, it displays the result in \s-1YAML\s0. If you type in \s-1YAML\s0 it turns
 746 it into Perl code.
 747 .PP
 748 To run ysh, (assuming you installed it along with \s-1YAML\s0.pm) simply type:
 749 .PP
 750 .Vb 1
 751 \&    ysh [options]
 752 .Ve
 753 .PP
 754 Please read the \f(CW\*(C`ysh\*(C'\fR documentation for the full details. There are
 755 lots of options.
 756 .SH "BUGS & DEFICIENCIES"
 757 .IX Header "BUGS & DEFICIENCIES"
 758 If you find a bug in \s-1YAML\s0, please try to recreate it in the \s-1YAML\s0 Shell
 759 with logging turned on ('ysh \-L'). When you have successfully reproduced
 760 the bug, please mail the \s-1LOG\s0 file to the author (ingy@cpan.org).
 761 .PP
 762 \&\s-1WARNING:\s0 This is still *ALPHA* code. Well, most of this code has been
 763 around for years...
 764 .PP
 765 \&\s-1BIGGER\s0 \s-1WARNING:\s0 \s-1YAML\s0.pm has been slow in the making, but I am committed
 766 to having top notch \s-1YAML\s0 tools in the Perl world. The \s-1YAML\s0 team is close
 767 to finalizing the \s-1YAML\s0 1.1 spec. This version of \s-1YAML\s0.pm is based off of
 768 a very old pre 1.0 spec. In actuality there isn't a ton of difference,
 769 and this \s-1YAML\s0.pm is still fairly useful. Things will get much better in
 770 the future.
 771 .SH "RESOURCES"
 772 .IX Header "RESOURCES"
 773 <http://lists.sourceforge.net/lists/listinfo/yaml\-core> is the mailing
 774 list. This is where the language is discussed and designed.
 775 .PP
 776 <http://www.yaml.org> is the official \s-1YAML\s0 website.
 777 .PP
 778 <http://www.yaml.org/spec/> is the \s-1YAML\s0 1.0 specification.
 779 .PP
 780 <http://yaml.kwiki.org> is the official \s-1YAML\s0 wiki.
 781 .SH "SEE ALSO"
 782 .IX Header "SEE ALSO"
 783 See YAML::Syck. Fast!
 784 .SH "AUTHOR"
 785 .IX Header "AUTHOR"
 786 Ingy döt Net <ingy@cpan.org>
 787 .PP
 788 is resonsible for \s-1YAML\s0.pm.
 789 .PP
 790 The \s-1YAML\s0 serialization language is the result of years of collaboration
 791 between Oren Ben\-Kiki, Clark Evans and Ingy döt Net. Several others
 792 have added help along the way.
 793 .SH "COPYRIGHT"
 794 .IX Header "COPYRIGHT"
 795 Copyright (c) 2005, 2006, 2008. Ingy döt Net.
 796 .PP
 797 Copyright (c) 2001, 2002, 2005. Brian Ingerson.
 798 .PP
 799 Some parts copyright (c) 2009 Adam Kennedy
 800 .PP
 801 This program is free software; you can redistribute it and/or modify it
 802 under the same terms as Perl itself.
 803 .PP
 804 See <http://www.perl.com/perl/misc/Artistic.html>