YAML
POD | API |CODE | CPAN
				
			


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