doc/modules/README.YAML

   1 NAME
   2     YAML - YAML Ain't Markup Language (tm)
   3
   4 SYNOPSIS
   5         use YAML;
   6
   7         # Load a YAML stream of 3 YAML documents into Perl data structures.
   8         my ($hashref, $arrayref, $string) = Load(<<'...');
   9         ---
  10         name: ingy
  11         age: old
  12         weight: heavy
  13         # I should comment that I also like pink, but don't tell anybody.
  14         favorite colors:
  15             - red
  16             - green
  17             - blue
  18         ---
  19         - Clark Evans
  20         - Oren Ben-Kiki
  21         - Ingy döt Net
  22         --- >
  23         You probably think YAML stands for "Yet Another Markup Language". It
  24         ain't! YAML is really a data serialization language. But if you want
  25         to think of it as a markup, that's OK with me. A lot of people try
  26         to use XML as a serialization format.
  27
  28         "YAML" is catchy and fun to say. Try it. "YAML, YAML, YAML!!!"
  29         ...
  30
  31         # Dump the Perl data structures back into YAML.
  32         print Dump($string, $arrayref, $hashref);
  33
  34         # YAML::Dump is used the same way you'd use Data::Dumper::Dumper
  35         use Data::Dumper;
  36         print Dumper($string, $arrayref, $hashref);
  37
  38 DESCRIPTION
  39     The YAML.pm module implements a YAML Loader and Dumper based on the YAML
  40     1.0 specification. <http://www.yaml.org/spec/>
  41
  42     YAML is a generic data serialization language that is optimized for
  43     human readability. It can be used to express the data structures of most
  44     modern programming languages. (Including Perl!!!)
  45
  46     For information on the YAML syntax, please refer to the YAML
  47     specification.
  48
  49 WHY YAML IS COOL
  50     YAML is readable for people.
  51         It makes clear sense out of complex data structures. You should find
  52         that YAML is an exceptional data dumping tool. Structure is shown
  53         through indentation, YAML supports recursive data, and hash keys are
  54         sorted by default. In addition, YAML supports several styles of
  55         scalar formatting for different types of data.
  56
  57     YAML is editable.
  58         YAML was designed from the ground up to be an excellent syntax for
  59         configuration files. Almost all programs need configuration files,
  60         so why invent a new syntax for each one? And why subject users to
  61         the complexities of XML or native Perl code?
  62
  63     YAML is multilingual.
  64         Yes, YAML supports Unicode. But I'm actually referring to
  65         programming languages. YAML was designed to meet the serialization
  66         needs of Perl, Python, Ruby, Tcl, PHP, Javascript and Java. It was
  67         also designed to be interoperable between those languages. That
  68         means YAML serializations produced by Perl can be processed by
  69         Python.
  70
  71     YAML is taint safe.
  72         Using modules like Data::Dumper for serialization is fine as long as
  73         you can be sure that nobody can tamper with your data files or
  74         transmissions. That's because you need to use Perl's "eval()"
  75         built-in to deserialize the data. Somebody could add a snippet of
  76         Perl to erase your files.
  77
  78         YAML's parser does not need to eval anything.
  79
  80     YAML is full featured.
  81         YAML can accurately serialize all of the common Perl data structures
  82         and deserialize them again without losing data relationships.
  83         Although it is not 100% perfect (no serializer is or can be
  84         perfect), it fares as well as the popular current modules:
  85         Data::Dumper, Storable, XML::Dumper and Data::Denter.
  86
  87         YAML.pm also has the ability to handle code (subroutine) references
  88         and typeglobs. (Still experimental) These features are not found in
  89         Perl's other serialization modules.
  90
  91     YAML is extensible.
  92         The YAML language has been designed to be flexible enough to solve
  93         it's own problems. The markup itself has 3 basic construct which
  94         resemble Perl's hash, array and scalar. By default, these map to
  95         their Perl equivalents. But each YAML node also supports a tagging
  96         mechanism (type system) which can cause that node to be interpreted
  97         in a completely different manner. That's how YAML can support object
  98         serialization and oddball structures like Perl's typeglob.
  99
 100 YAML IMPLEMENTATIONS IN PERL
 101     This module, YAML.pm, is really just the interface module for YAML
 102     modules written in Perl. The basic interface for YAML consists of two
 103     functions: "Dump" and "Load". The real work is done by the modules
 104     YAML::Dumper and YAML::Loader.
 105
 106     Different YAML module distributions can be created by subclassing
 107     YAML.pm and YAML::Loader and YAML::Dumper. For example, YAML-Simple
 108     consists of YAML::Simple YAML::Dumper::Simple and YAML::Loader::Simple.
 109
 110     Why would there be more than one implementation of YAML? Well, despite
 111     YAML's offering of being a simple data format, YAML is actually very
 112     deep and complex. Implementing the entirety of the YAML specification is
 113     a daunting task.
 114
 115     For this reason I am currently working on 3 different YAML
 116     implementations.
 117
 118     YAML
 119         The main YAML distribution will keeping evolving to support the
 120         entire YAML specification in pure Perl. This may not be the fastest
 121         or most stable module though. Currently, YAML.pm has lots of known
 122         bugs. It is mostly a great tool for dumping Perl data structures to
 123         a readable form.
 124
 125     YAML::Lite
 126         The point of YAML::Lite is to strip YAML down to the 90% that people
 127         use most and offer that in a small, fast, stable, pure Perl form.
 128         YAML::Lite will simply die when it is asked to do something it
 129         can't.
 130
 131     YAML::Syck
 132         "libsyck" is the C based YAML processing library used by the Ruby
 133         programming language (and also Python, PHP and Pugs). YAML::Syck is
 134         the Perl binding to "libsyck". It should be very fast, but may have
 135         problems of its own. It will also require C compilation.
 136
 137         NOTE: Audrey Tang has actually completed this module and it works
 138         great and is 10 times faster than YAML.pm.
 139
 140     In the future, there will likely be even more YAML modules. Remember,
 141     people other than Ingy are allowed to write YAML modules!
 142
 143 FUNCTIONAL USAGE
 144     YAML is completely OO under the hood. Still it exports a few useful top
 145     level functions so that it is dead simple to use. These functions just
 146     do the OO stuff for you. If you want direct access to the OO API see the
 147     documentation for YAML::Dumper and YAML::Loader.
 148
 149   Exported Functions
 150     The following functions are exported by YAML.pm by default. The reason
 151     they are exported is so that YAML works much like Data::Dumper. If you
 152     don't want functions to be imported, just use YAML with an empty import
 153     list:
 154
 155         use YAML ();
 156
 157     Dump(list-of-Perl-data-structures)
 158         Turn Perl data into YAML. This function works very much like
 159         Data::Dumper::Dumper(). It takes a list of Perl data strucures and
 160         dumps them into a serialized form. It returns a string containing
 161         the YAML stream. The structures can be references or plain scalars.
 162
 163     Load(string-containing-a-YAML-stream)
 164         Turn YAML into Perl data. This is the opposite of Dump. Just like
 165         Storable's thaw() function or the eval() function in relation to
 166         Data::Dumper. It parses a string containing a valid YAML stream into
 167         a list of Perl data structures.
 168
 169   Exportable Functions
 170     These functions are not exported by default but you can request them in
 171     an import list like this:
 172
 173         use YAML qw'freeze thaw Bless';
 174
 175     freeze() and thaw()
 176         Aliases to Dump() and Load() for Storable fans. This will also allow
 177         YAML.pm to be plugged directly into modules like POE.pm, that use
 178         the freeze/thaw API for internal serialization.
 179
 180     DumpFile(filepath, list)
 181         Writes the YAML stream to a file instead of just returning a string.
 182
 183     LoadFile(filepath)
 184         Reads the YAML stream from a file instead of a string.
 185
 186     Bless(perl-node, [yaml-node | class-name])
 187         Associate a normal Perl node, with a yaml node. A yaml node is an
 188         object tied to the YAML::Node class. The second argument is either a
 189         yaml node that you've already created or a class (package) name that
 190         supports a yaml_dump() function. A yaml_dump() function should take
 191         a perl node and return a yaml node. If no second argument is
 192         provided, Bless will create a yaml node. This node is not returned,
 193         but can be retrieved with the Blessed() function.
 194
 195         Here's an example of how to use Bless. Say you have a hash
 196         containing three keys, but you only want to dump two of them.
 197         Furthermore the keys must be dumped in a certain order. Here's how
 198         you do that:
 199
 200             use YAML qw(Dump Bless);
 201             $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
 202             print Dump $hash;
 203             Bless($hash)->keys(['banana', 'apple']);
 204             print Dump $hash;
 205
 206         produces:
 207
 208             ---
 209             apple: good
 210             banana: bad
 211             cauliflower: ugly
 212             ---
 213             banana: bad
 214             apple: good
 215
 216         Bless returns the tied part of a yaml-node, so that you can call the
 217         YAML::Node methods. This is the same thing that YAML::Node::ynode()
 218         returns. So another way to do the above example is:
 219
 220             use YAML qw(Dump Bless);
 221             use YAML::Node;
 222             $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
 223             print Dump $hash;
 224             Bless($hash);
 225             $ynode = ynode(Blessed($hash));
 226             $ynode->keys(['banana', 'apple']);
 227             print Dump $hash;
 228
 229         Note that Blessing a Perl data structure does not change it anyway.
 230         The extra information is stored separately and looked up by the
 231         Blessed node's memory address.
 232
 233     Blessed(perl-node)
 234         Returns the yaml node that a particular perl node is associated with
 235         (see above). Returns undef if the node is not (YAML) Blessed.
 236
 237 GLOBAL OPTIONS
 238     YAML options are set using a group of global variables in the YAML
 239     namespace. This is similar to how Data::Dumper works.
 240
 241     For example, to change the indentation width, do something like:
 242
 243         local $YAML::Indent = 3;
 244
 245     The current options are:
 246
 247     DumperClass
 248         You can override which module/class YAML uses for Dumping data.
 249
 250     LoaderClass
 251         You can override which module/class YAML uses for Loading data.
 252
 253     Indent
 254         This is the number of space characters to use for each indentation
 255         level when doing a Dump(). The default is 2.
 256
 257         By the way, YAML can use any number of characters for indentation at
 258         any level. So if you are editing YAML by hand feel free to do it
 259         anyway that looks pleasing to you; just be consistent for a given
 260         level.
 261
 262     SortKeys
 263         Default is 1. (true)
 264
 265         Tells YAML.pm whether or not to sort hash keys when storing a
 266         document.
 267
 268         YAML::Node objects can have their own sort order, which is usually
 269         what you want. To override the YAML::Node order and sort the keys
 270         anyway, set SortKeys to 2.
 271
 272     Stringify
 273         Default is 0. (false)
 274
 275         Objects with string overloading should honor the overloading and
 276         dump the stringification of themselves, rather than the actual
 277         object's guts.
 278
 279     UseHeader
 280         Default is 1. (true)
 281
 282         This tells YAML.pm whether to use a separator string for a Dump
 283         operation. This only applies to the first document in a stream.
 284         Subsequent documents must have a YAML header by definition.
 285
 286     UseVersion
 287         Default is 0. (false)
 288
 289         Tells YAML.pm whether to include the YAML version on the
 290         separator/header.
 291
 292             --- %YAML:1.0
 293
 294     AnchorPrefix
 295         Default is ''.
 296
 297         Anchor names are normally numeric. YAML.pm simply starts with '1'
 298         and increases by one for each new anchor. This option allows you to
 299         specify a string to be prepended to each anchor number.
 300
 301     UseCode
 302         Setting the UseCode option is a shortcut to set both the DumpCode
 303         and LoadCode options at once. Setting UseCode to '1' tells YAML.pm
 304         to dump Perl code references as Perl (using B::Deparse) and to load
 305         them back into memory using eval(). The reason this has to be an
 306         option is that using eval() to parse untrusted code is, well,
 307         untrustworthy.
 308
 309     DumpCode
 310         Determines if and how YAML.pm should serialize Perl code references.
 311         By default YAML.pm will dump code references as dummy placeholders
 312         (much like Data::Dumper). If DumpCode is set to '1' or 'deparse',
 313         code references will be dumped as actual Perl code.
 314
 315         DumpCode can also be set to a subroutine reference so that you can
 316         write your own serializing routine. YAML.pm passes you the code ref.
 317         You pass back the serialization (as a string) and a format
 318         indicator. The format indicator is a simple string like: 'deparse'
 319         or 'bytecode'.
 320
 321     LoadCode
 322         LoadCode is the opposite of DumpCode. It tells YAML if and how to
 323         deserialize code references. When set to '1' or 'deparse' it will
 324         use "eval()". Since this is potentially risky, only use this option
 325         if you know where your YAML has been.
 326
 327         LoadCode can also be set to a subroutine reference so that you can
 328         write your own deserializing routine. YAML.pm passes the
 329         serialization (as a string) and a format indicator. You pass back
 330         the code reference.
 331
 332     UseBlock
 333         YAML.pm uses heuristics to guess which scalar style is best for a
 334         given node. Sometimes you'll want all multiline scalars to use the
 335         'block' style. If so, set this option to 1.
 336
 337         NOTE: YAML's block style is akin to Perl's here-document.
 338
 339     UseFold
 340         If you want to force YAML to use the 'folded' style for all
 341         multiline scalars, then set $UseFold to 1.
 342
 343         NOTE: YAML's folded style is akin to the way HTML folds text, except
 344         smarter.
 345
 346     UseAliases
 347         YAML has an alias mechanism such that any given structure in memory
 348         gets serialized once. Any other references to that structure are
 349         serialized only as alias markers. This is how YAML can serialize
 350         duplicate and recursive structures.
 351
 352         Sometimes, when you KNOW that your data is nonrecursive in nature,
 353         you may want to serialize such that every node is expressed in full.
 354         (ie as a copy of the original). Setting $YAML::UseAliases to 0 will
 355         allow you to do this. This also may result in faster processing
 356         because the lookup overhead is by bypassed.
 357
 358         THIS OPTION CAN BE DANGEROUS. *If* your data is recursive, this
 359         option *will* cause Dump() to run in an endless loop, chewing up
 360         your computers memory. You have been warned.
 361
 362     CompressSeries
 363         Default is 1.
 364
 365         Compresses the formatting of arrays of hashes:
 366
 367             -
 368               foo: bar
 369             -
 370               bar: foo
 371
 372         becomes:
 373
 374             - foo: bar
 375             - bar: foo
 376
 377         Since this output is usually more desirable, this option is turned
 378         on by default.
 379
 380 YAML TERMINOLOGY
 381     YAML is a full featured data serialization language, and thus has its
 382     own terminology.
 383
 384     It is important to remember that although YAML is heavily influenced by
 385     Perl and Python, it is a language in its own right, not merely just a
 386     representation of Perl structures.
 387
 388     YAML has three constructs that are conspicuously similar to Perl's hash,
 389     array, and scalar. They are called mapping, sequence, and string
 390     respectively. By default, they do what you would expect. But each
 391     instance may have an explicit or implicit tag (type) that makes it
 392     behave differently. In this manner, YAML can be extended to represent
 393     Perl's Glob or Python's tuple, or Ruby's Bigint.
 394
 395     stream
 396         A YAML stream is the full sequence of unicode characters that a YAML
 397         parser would read or a YAML emitter would write. A stream may
 398         contain one or more YAML documents separated by YAML headers.
 399
 400             ---
 401             a: mapping
 402             foo: bar
 403             ---
 404             - a
 405             - sequence
 406
 407     document
 408         A YAML document is an independent data structure representation
 409         within a stream. It is a top level node. Each document in a YAML
 410         stream must begin with a YAML header line. Actually the header is
 411         optional on the first document.
 412
 413             ---
 414             This: top level mapping
 415             is:
 416                 - a
 417                 - YAML
 418                 - document
 419
 420     header
 421         A YAML header is a line that begins a YAML document. It consists of
 422         three dashes, possibly followed by more info. Another purpose of the
 423         header line is that it serves as a place to put top level tag and
 424         anchor information.
 425
 426             --- !recursive-sequence &001
 427             - * 001
 428             - * 001
 429
 430     node
 431         A YAML node is the representation of a particular data stucture.
 432         Nodes may contain other nodes. (In Perl terms, nodes are like
 433         scalars. Strings, arrayrefs and hashrefs. But this refers to the
 434         serialized format, not the in-memory structure.)
 435
 436     tag This is similar to a type. It indicates how a particular YAML node
 437         serialization should be transferred into or out of memory. For
 438         instance a Foo::Bar object would use the tag 'perl/Foo::Bar':
 439
 440             - !perl/Foo::Bar
 441                 foo: 42
 442                 bar: stool
 443
 444     collection
 445         A collection is the generic term for a YAML data grouping. YAML has
 446         two types of collections: mappings and sequences. (Similar to hashes
 447         and arrays)
 448
 449     mapping
 450         A mapping is a YAML collection defined by unordered key/value pairs
 451         with unique keys. By default YAML mappings are loaded into Perl
 452         hashes.
 453
 454             a mapping:
 455                 foo: bar
 456                 two: times two is 4
 457
 458     sequence
 459         A sequence is a YAML collection defined by an ordered list of
 460         elements. By default YAML sequences are loaded into Perl arrays.
 461
 462             a sequence:
 463                 - one bourbon
 464                 - one scotch
 465                 - one beer
 466
 467     scalar
 468         A scalar is a YAML node that is a single value. By default YAML
 469         scalars are loaded into Perl scalars.
 470
 471             a scalar key: a scalar value
 472
 473         YAML has many styles for representing scalars. This is important
 474         because varying data will have varying formatting requirements to
 475         retain the optimum human readability.
 476
 477     plain scalar
 478         A plain sclar is unquoted. All plain scalars are automatic
 479         candidates for "implicit tagging". This means that their tag may be
 480         determined automatically by examination. The typical uses for this
 481         are plain alpha strings, integers, real numbers, dates, times and
 482         currency.
 483
 484             - a plain string
 485             - -42
 486             - 3.1415
 487             - 12:34
 488             - 123 this is an error
 489
 490     single quoted scalar
 491         This is similar to Perl's use of single quotes. It means no escaping
 492         except for single quotes which are escaped by using two adjacent
 493         single quotes.
 494
 495             - 'When I say ''\n'' I mean "backslash en"'
 496
 497     double quoted scalar
 498         This is similar to Perl's use of double quotes. Character escaping
 499         can be used.
 500
 501             - "This scalar\nhas two lines, and a bell -->\a"
 502
 503     folded scalar
 504         This is a multiline scalar which begins on the next line. It is
 505         indicated by a single right angle bracket. It is unescaped like the
 506         single quoted scalar. Line folding is also performed.
 507
 508             - >
 509              This is a multiline scalar which begins on
 510              the next line. It is indicated by a single
 511              carat. It is unescaped like the single
 512              quoted scalar. Line folding is also
 513              performed.
 514
 515     block scalar
 516         This final multiline form is akin to Perl's here-document except
 517         that (as in all YAML data) scope is indicated by indentation.
 518         Therefore, no ending marker is required. The data is verbatim. No
 519         line folding.
 520
 521             - |
 522                 QTY  DESC          PRICE  TOTAL
 523                 ---  ----          -----  -----
 524                   1  Foo Fighters  $19.95 $19.95
 525                   2  Bar Belles    $29.95 $59.90
 526
 527     parser
 528         A YAML processor has four stages: parse, load, dump, emit.
 529
 530         A parser parses a YAML stream. YAML.pm's Load() function contains a
 531         parser.
 532
 533     loader
 534         The other half of the Load() function is a loader. This takes the
 535         information from the parser and loads it into a Perl data structure.
 536
 537     dumper
 538         The Dump() function consists of a dumper and an emitter. The dumper
 539         walks through each Perl data structure and gives info to the
 540         emitter.
 541
 542     emitter
 543         The emitter takes info from the dumper and turns it into a YAML
 544         stream.
 545
 546         NOTE: In YAML.pm the parser/loader and the dumper/emitter code are
 547         currently very closely tied together. In the future they may be
 548         broken into separate stages.
 549
 550     For more information please refer to the immensely helpful YAML
 551     specification available at <http://www.yaml.org/spec/>.
 552
 553 ysh - The YAML Shell
 554     The YAML distribution ships with a script called 'ysh', the YAML shell.
 555     ysh provides a simple, interactive way to play with YAML. If you type in
 556     Perl code, it displays the result in YAML. If you type in YAML it turns
 557     it into Perl code.
 558
 559     To run ysh, (assuming you installed it along with YAML.pm) simply type:
 560
 561         ysh [options]
 562
 563     Please read the "ysh" documentation for the full details. There are lots
 564     of options.
 565
 566 BUGS & DEFICIENCIES
 567     If you find a bug in YAML, please try to recreate it in the YAML Shell
 568     with logging turned on ('ysh -L'). When you have successfully reproduced
 569     the bug, please mail the LOG file to the author (ingy@cpan.org).
 570
 571     WARNING: This is still *ALPHA* code. Well, most of this code has been
 572     around for years...
 573
 574     BIGGER WARNING: YAML.pm has been slow in the making, but I am committed
 575     to having top notch YAML tools in the Perl world. The YAML team is close
 576     to finalizing the YAML 1.1 spec. This version of YAML.pm is based off of
 577     a very old pre 1.0 spec. In actuality there isn't a ton of difference,
 578     and this YAML.pm is still fairly useful. Things will get much better in
 579     the future.
 580
 581 RESOURCES
 582     <http://lists.sourceforge.net/lists/listinfo/yaml-core> is the mailing
 583     list. This is where the language is discussed and designed.
 584
 585     <http://www.yaml.org> is the official YAML website.
 586
 587     <http://www.yaml.org/spec/> is the YAML 1.0 specification.
 588
 589     <http://yaml.kwiki.org> is the official YAML wiki.
 590
 591 SEE ALSO
 592     See YAML::Syck. Fast!
 593
 594 AUTHOR
 595     Ingy döt Net <ingy@cpan.org>
 596
 597     is resonsible for YAML.pm.
 598
 599     The YAML serialization language is the result of years of collaboration
 600     between Oren Ben-Kiki, Clark Evans and Ingy döt Net. Several others
 601     have added help along the way.
 602
 603 COPYRIGHT
 604     Copyright (c) 2005, 2006. Ingy döt Net. All rights reserved. Copyright
 605     (c) 2001, 2002, 2005. Brian Ingerson. All rights reserved.
 606
 607     This program is free software; you can redistribute it and/or modify it
 608     under the same terms as Perl itself.
 609
 610     See <http://www.perl.com/perl/misc/Artistic.html>
 611