YAML
POD | API |CODE | CPAN
				
			


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