YAML-1.15HEADYAML-1.15master

1 files changed, 696 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..883a922
--- /dev/null
+++ b/README
@@ -0,0 +1,696 @@
+NAME
+
+    YAML - YAML Ain't Markup Language™
+
+VERSION
+
+    This document describes YAML version 1.15.
+
+NOTE
+
+    This module has been released to CPAN as YAML::Old, and soon YAML.pm
+    will be changed to just be a frontend interface module for all the
+    various Perl YAML implementation modules, including YAML::Old.
+
+    If you want robust and fast YAML processing using the normal Dump/Load
+    API, please consider switching to YAML::XS. It is by far the best Perl
+    module for YAML at this time. It requires that you have a C compiler,
+    since it is written in C.
+
+    If you really need to use this version of YAML.pm it will always be
+    available as YAML::Old.
+
+    The rest of this documentation is left unchanged, until YAML.pm is
+    switched over to the new UI-only version.
+
+SYNOPSIS
+
+        use YAML;
+    
+        # Load a YAML stream of 3 YAML documents into Perl data structures.
+        my ($hashref, $arrayref, $string) = Load(<<'...');
+        ---
+        name: ingy
+        age: old
+        weight: heavy
+        # I should comment that I also like pink, but don't tell anybody.
+        favorite colors:
+          - red
+          - green
+          - blue
+        ---
+        - Clark Evans
+        - Oren Ben-Kiki
+        - Ingy döt Net
+        --- >
+        You probably think YAML stands for "Yet Another Markup Language". It
+        ain't! YAML is really a data serialization language. But if you want
+        to think of it as a markup, that's OK with me. A lot of people try
+        to use XML as a serialization format.
+    
+        "YAML" is catchy and fun to say. Try it. "YAML, YAML, YAML!!!"
+        ...
+    
+        # Dump the Perl data structures back into YAML.
+        print Dump($string, $arrayref, $hashref);
+    
+        # YAML::Dump is used the same way you'd use Data::Dumper::Dumper
+        use Data::Dumper;
+        print Dumper($string, $arrayref, $hashref);
+
+DESCRIPTION
+
+    The YAML.pm module implements a YAML Loader and Dumper based on the
+    YAML 1.0 specification. http://www.yaml.org/spec/
+
+    YAML is a generic data serialization language that is optimized for
+    human readability. It can be used to express the data structures of
+    most modern programming languages. (Including Perl!!!)
+
+    For information on the YAML syntax, please refer to the YAML
+    specification.
+
+WHY YAML IS COOL
+
+    YAML is readable for people.
+
+      It makes clear sense out of complex data structures. You should find
+      that YAML is an exceptional data dumping tool. Structure is shown
+      through indentation, YAML supports recursive data, and hash keys are
+      sorted by default. In addition, YAML supports several styles of
+      scalar formatting for different types of data.
+
+    YAML is editable.
+
+      YAML was designed from the ground up to be an excellent syntax for
+      configuration files. Almost all programs need configuration files, so
+      why invent a new syntax for each one? And why subject users to the
+      complexities of XML or native Perl code?
+
+    YAML is multilingual.
+
+      Yes, YAML supports Unicode. But I'm actually referring to programming
+      languages. YAML was designed to meet the serialization needs of Perl,
+      Python, Ruby, Tcl, PHP, Javascript and Java. It was also designed to
+      be interoperable between those languages. That means YAML
+      serializations produced by Perl can be processed by Python.
+
+    YAML is taint safe.
+
+      Using modules like Data::Dumper for serialization is fine as long as
+      you can be sure that nobody can tamper with your data files or
+      transmissions. That's because you need to use Perl's eval() built-in
+      to deserialize the data. Somebody could add a snippet of Perl to
+      erase your files.
+
+      YAML's parser does not need to eval anything.
+
+    YAML is full featured.
+
+      YAML can accurately serialize all of the common Perl data structures
+      and deserialize them again without losing data relationships.
+      Although it is not 100% perfect (no serializer is or can be perfect),
+      it fares as well as the popular current modules: Data::Dumper,
+      Storable, XML::Dumper and Data::Denter.
+
+      YAML.pm also has the ability to handle code (subroutine) references
+      and typeglobs. (Still experimental) These features are not found in
+      Perl's other serialization modules.
+
+    YAML is extensible.
+
+      The YAML language has been designed to be flexible enough to solve
+      it's own problems. The markup itself has 3 basic construct which
+      resemble Perl's hash, array and scalar. By default, these map to
+      their Perl equivalents. But each YAML node also supports a tagging
+      mechanism (type system) which can cause that node to be interpreted
+      in a completely different manner. That's how YAML can support object
+      serialization and oddball structures like Perl's typeglob.
+
+YAML IMPLEMENTATIONS IN PERL
+
+    This module, YAML.pm, is really just the interface module for YAML
+    modules written in Perl. The basic interface for YAML consists of two
+    functions: Dump and Load. The real work is done by the modules
+    YAML::Dumper and YAML::Loader.
+
+    Different YAML module distributions can be created by subclassing
+    YAML.pm and YAML::Loader and YAML::Dumper. For example, YAML-Simple
+    consists of YAML::Simple YAML::Dumper::Simple and YAML::Loader::Simple.
+
+    Why would there be more than one implementation of YAML? Well, despite
+    YAML's offering of being a simple data format, YAML is actually very
+    deep and complex. Implementing the entirety of the YAML specification
+    is a daunting task.
+
+    For this reason I am currently working on 3 different YAML
+    implementations.
+
+    YAML
+
+      The main YAML distribution will keeping evolving to support the
+      entire YAML specification in pure Perl. This may not be the fastest
+      or most stable module though. Currently, YAML.pm has lots of known
+      bugs. It is mostly a great tool for dumping Perl data structures to a
+      readable form.
+
+    YAML::Tiny
+
+      The point of YAML::Tiny is to strip YAML down to the 90% that people
+      use most and offer that in a small, fast, stable, pure Perl form.
+      YAML::Tiny will simply die when it is asked to do something it can't.
+
+    YAML::Syck
+
+      libsyck is the C based YAML processing library used by the Ruby
+      programming language (and also Python, PHP and Pugs). YAML::Syck is
+      the Perl binding to libsyck. It should be very fast, but may have
+      problems of its own. It will also require C compilation.
+
+      NOTE: Audrey Tang has actually completed this module and it works
+      great and is 10 times faster than YAML.pm.
+
+    In the future, there will likely be even more YAML modules. Remember,
+    people other than Ingy are allowed to write YAML modules!
+
+FUNCTIONAL USAGE
+
+    YAML is completely OO under the hood. Still it exports a few useful top
+    level functions so that it is dead simple to use. These functions just
+    do the OO stuff for you. If you want direct access to the OO API see
+    the documentation for YAML::Dumper and YAML::Loader.
+
+ Exported Functions
+
+    The following functions are exported by YAML.pm by default. The reason
+    they are exported is so that YAML works much like Data::Dumper. If you
+    don't want functions to be imported, just use YAML with an empty import
+    list:
+
+        use YAML ();
+
+    Dump(list-of-Perl-data-structures)
+
+      Turn Perl data into YAML. This function works very much like
+      Data::Dumper::Dumper(). It takes a list of Perl data structures and
+      dumps them into a serialized form. It returns a string containing the
+      YAML stream. The structures can be references or plain scalars.
+
+    Load(string-containing-a-YAML-stream)
+
+      Turn YAML into Perl data. This is the opposite of Dump. Just like
+      Storable's thaw() function or the eval() function in relation to
+      Data::Dumper. It parses a string containing a valid YAML stream into
+      a list of Perl data structures.
+
+ Exportable Functions
+
+    These functions are not exported by default but you can request them in
+    an import list like this:
+
+        use YAML qw'freeze thaw Bless';
+
+    freeze() and thaw()
+
+      Aliases to Dump() and Load() for Storable fans. This will also allow
+      YAML.pm to be plugged directly into modules like POE.pm, that use the
+      freeze/thaw API for internal serialization.
+
+    DumpFile(filepath, list)
+
+      Writes the YAML stream to a file instead of just returning a string.
+
+    LoadFile(filepath)
+
+      Reads the YAML stream from a file instead of a string.
+
+    Bless(perl-node, [yaml-node | class-name])
+
+      Associate a normal Perl node, with a yaml node. A yaml node is an
+      object tied to the YAML::Node class. The second argument is either a
+      yaml node that you've already created or a class (package) name that
+      supports a yaml_dump() function. A yaml_dump() function should take a
+      perl node and return a yaml node. If no second argument is provided,
+      Bless will create a yaml node. This node is not returned, but can be
+      retrieved with the Blessed() function.
+
+      Here's an example of how to use Bless. Say you have a hash containing
+      three keys, but you only want to dump two of them. Furthermore the
+      keys must be dumped in a certain order. Here's how you do that:
+
+          use YAML qw(Dump Bless);
+          $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
+          print Dump $hash;
+          Bless($hash)->keys(['banana', 'apple']);
+          print Dump $hash;
+
+      produces:
+
+          ---
+          apple: good
+          banana: bad
+          cauliflower: ugly
+          ---
+          banana: bad
+          apple: good
+
+      Bless returns the tied part of a yaml-node, so that you can call the
+      YAML::Node methods. This is the same thing that YAML::Node::ynode()
+      returns. So another way to do the above example is:
+
+          use YAML qw(Dump Bless);
+          use YAML::Node;
+          $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
+          print Dump $hash;
+          Bless($hash);
+          $ynode = ynode(Blessed($hash));
+          $ynode->keys(['banana', 'apple']);
+          print Dump $hash;
+
+      Note that Blessing a Perl data structure does not change it anyway.
+      The extra information is stored separately and looked up by the
+      Blessed node's memory address.
+
+    Blessed(perl-node)
+
+      Returns the yaml node that a particular perl node is associated with
+      (see above). Returns undef if the node is not (YAML) Blessed.
+
+GLOBAL OPTIONS
+
+    YAML options are set using a group of global variables in the YAML
+    namespace. This is similar to how Data::Dumper works.
+
+    For example, to change the indentation width, do something like:
+
+        local $YAML::Indent = 3;
+
+    The current options are:
+
+    DumperClass
+
+      You can override which module/class YAML uses for Dumping data.
+
+    LoaderClass
+
+      You can override which module/class YAML uses for Loading data.
+
+    Indent
+
+      This is the number of space characters to use for each indentation
+      level when doing a Dump(). The default is 2.
+
+      By the way, YAML can use any number of characters for indentation at
+      any level. So if you are editing YAML by hand feel free to do it
+      anyway that looks pleasing to you; just be consistent for a given
+      level.
+
+    SortKeys
+
+      Default is 1. (true)
+
+      Tells YAML.pm whether or not to sort hash keys when storing a
+      document.
+
+      YAML::Node objects can have their own sort order, which is usually
+      what you want. To override the YAML::Node order and sort the keys
+      anyway, set SortKeys to 2.
+
+    Stringify
+
+      Default is 0. (false)
+
+      Objects with string overloading should honor the overloading and dump
+      the stringification of themselves, rather than the actual object's
+      guts.
+
+    UseHeader
+
+      Default is 1. (true)
+
+      This tells YAML.pm whether to use a separator string for a Dump
+      operation. This only applies to the first document in a stream.
+      Subsequent documents must have a YAML header by definition.
+
+    UseVersion
+
+      Default is 0. (false)
+
+      Tells YAML.pm whether to include the YAML version on the
+      separator/header.
+
+          --- %YAML:1.0
+
+    AnchorPrefix
+
+      Default is ''.
+
+      Anchor names are normally numeric. YAML.pm simply starts with '1' and
+      increases by one for each new anchor. This option allows you to
+      specify a string to be prepended to each anchor number.
+
+    UseCode
+
+      Setting the UseCode option is a shortcut to set both the DumpCode and
+      LoadCode options at once. Setting UseCode to '1' tells YAML.pm to
+      dump Perl code references as Perl (using B::Deparse) and to load them
+      back into memory using eval(). The reason this has to be an option is
+      that using eval() to parse untrusted code is, well, untrustworthy.
+
+    DumpCode
+
+      Determines if and how YAML.pm should serialize Perl code references.
+      By default YAML.pm will dump code references as dummy placeholders
+      (much like Data::Dumper). If DumpCode is set to '1' or 'deparse',
+      code references will be dumped as actual Perl code.
+
+      DumpCode can also be set to a subroutine reference so that you can
+      write your own serializing routine. YAML.pm passes you the code ref.
+      You pass back the serialization (as a string) and a format indicator.
+      The format indicator is a simple string like: 'deparse' or
+      'bytecode'.
+
+    LoadCode
+
+      LoadCode is the opposite of DumpCode. It tells YAML if and how to
+      deserialize code references. When set to '1' or 'deparse' it will use
+      eval(). Since this is potentially risky, only use this option if you
+      know where your YAML has been.
+
+      LoadCode can also be set to a subroutine reference so that you can
+      write your own deserializing routine. YAML.pm passes the
+      serialization (as a string) and a format indicator. You pass back the
+      code reference.
+
+    UseBlock
+
+      YAML.pm uses heuristics to guess which scalar style is best for a
+      given node. Sometimes you'll want all multiline scalars to use the
+      'block' style. If so, set this option to 1.
+
+      NOTE: YAML's block style is akin to Perl's here-document.
+
+    UseFold
+
+      If you want to force YAML to use the 'folded' style for all multiline
+      scalars, then set $UseFold to 1.
+
+      NOTE: YAML's folded style is akin to the way HTML folds text, except
+      smarter.
+
+    UseAliases
+
+      YAML has an alias mechanism such that any given structure in memory
+      gets serialized once. Any other references to that structure are
+      serialized only as alias markers. This is how YAML can serialize
+      duplicate and recursive structures.
+
+      Sometimes, when you KNOW that your data is nonrecursive in nature,
+      you may want to serialize such that every node is expressed in full.
+      (ie as a copy of the original). Setting $YAML::UseAliases to 0 will
+      allow you to do this. This also may result in faster processing
+      because the lookup overhead is by bypassed.
+
+      THIS OPTION CAN BE DANGEROUS. If your data is recursive, this option
+      will cause Dump() to run in an endless loop, chewing up your
+      computers memory. You have been warned.
+
+    CompressSeries
+
+      Default is 1.
+
+      Compresses the formatting of arrays of hashes:
+
+          -
+            foo: bar
+          -
+            bar: foo
+
+      becomes:
+
+          - foo: bar
+          - bar: foo
+
+      Since this output is usually more desirable, this option is turned on
+      by default.
+
+    QuoteNumericStrings
+
+      Default is 0. (false)
+
+      Adds detection mechanisms to encode strings that resemble numbers
+      with mandatory quoting.
+
+      This ensures leading that things like leading/trailing zeros and
+      other formatting are preserved.
+
+YAML TERMINOLOGY
+
+    YAML is a full featured data serialization language, and thus has its
+    own terminology.
+
+    It is important to remember that although YAML is heavily influenced by
+    Perl and Python, it is a language in its own right, not merely just a
+    representation of Perl structures.
+
+    YAML has three constructs that are conspicuously similar to Perl's
+    hash, array, and scalar. They are called mapping, sequence, and string
+    respectively. By default, they do what you would expect. But each
+    instance may have an explicit or implicit tag (type) that makes it
+    behave differently. In this manner, YAML can be extended to represent
+    Perl's Glob or Python's tuple, or Ruby's Bigint.
+
+    stream
+
+          A YAML stream is the full sequence of Unicode characters that a YAML
+          parser would read or a YAML emitter would write. A stream may contain
+          one or more YAML documents separated by YAML headers.
+      
+          ---
+          a: mapping
+          foo: bar
+          ---
+          - a
+          - sequence
+
+    document
+
+      A YAML document is an independent data structure representation
+      within a stream. It is a top level node. Each document in a YAML
+      stream must begin with a YAML header line. Actually the header is
+      optional on the first document.
+
+          ---
+          This: top level mapping
+          is:
+              - a
+              - YAML
+              - document
+
+    header
+
+      A YAML header is a line that begins a YAML document. It consists of
+      three dashes, possibly followed by more info. Another purpose of the
+      header line is that it serves as a place to put top level tag and
+      anchor information.
+
+          --- !recursive-sequence &001
+          - * 001
+          - * 001
+
+    node
+
+      A YAML node is the representation of a particular data structure.
+      Nodes may contain other nodes. (In Perl terms, nodes are like
+      scalars. Strings, arrayrefs and hashrefs. But this refers to the
+      serialized format, not the in- memory structure.)
+
+    tag
+
+      This is similar to a type. It indicates how a particular YAML node
+      serialization should be transferred into or out of memory. For
+      instance a Foo::Bar object would use the tag 'perl/Foo::Bar':
+
+          - !perl/Foo::Bar
+              foo: 42
+              bar: stool
+
+    collection
+
+      A collection is the generic term for a YAML data grouping. YAML has
+      two types of collections: mappings and sequences. (Similar to hashes
+      and arrays)
+
+    mapping
+
+      A mapping is a YAML collection defined by unordered key/value pairs
+      with unique keys. By default YAML mappings are loaded into Perl
+      hashes.
+
+          a mapping:
+              foo: bar
+              two: times two is 4
+
+    sequence
+
+      A sequence is a YAML collection defined by an ordered list of
+      elements. By default YAML sequences are loaded into Perl arrays.
+
+          a sequence:
+              - one bourbon
+              - one scotch
+              - one beer
+
+    scalar
+
+      A scalar is a YAML node that is a single value. By default YAML
+      scalars are loaded into Perl scalars.
+
+          a scalar key: a scalar value
+
+      YAML has many styles for representing scalars. This is important
+      because varying data will have varying formatting requirements to
+      retain the optimum human readability.
+
+    plain scalar
+
+      A plain scalar is unquoted. All plain scalars are automatic
+      candidates for "implicit tagging". This means that their tag may be
+      determined automatically by examination. The typical uses for this
+      are plain alpha strings, integers, real numbers, dates, times and
+      currency.
+
+          - a plain string
+          - -42
+          - 3.1415
+          - 12:34
+          - 123 this is an error
+
+    single quoted scalar
+
+      This is similar to Perl's use of single quotes. It means no escaping
+      except for single quotes which are escaped by using two adjacent
+      single quotes.
+
+          - 'When I say ''\n'' I mean "backslash en"'
+
+    double quoted scalar
+
+      This is similar to Perl's use of double quotes. Character escaping
+      can be used.
+
+          - "This scalar\nhas two lines, and a bell -->\a"
+
+    folded scalar
+
+      This is a multiline scalar which begins on the next line. It is
+      indicated by a single right angle bracket. It is unescaped like the
+      single quoted scalar. Line folding is also performed.
+
+          - >
+           This is a multiline scalar which begins on
+           the next line. It is indicated by a single
+           carat. It is unescaped like the single
+           quoted scalar. Line folding is also
+           performed.
+
+    block scalar
+
+      This final multiline form is akin to Perl's here-document except that
+      (as in all YAML data) scope is indicated by indentation. Therefore,
+      no ending marker is required. The data is verbatim. No line folding.
+
+          - |
+              QTY  DESC          PRICE  TOTAL
+              ---  ----          -----  -----
+                1  Foo Fighters  $19.95 $19.95
+                2  Bar Belles    $29.95 $59.90
+
+    parser
+
+      A YAML processor has four stages: parse, load, dump, emit.
+
+      A parser parses a YAML stream. YAML.pm's Load() function contains a
+      parser.
+
+    loader
+
+      The other half of the Load() function is a loader. This takes the
+      information from the parser and loads it into a Perl data structure.
+
+    dumper
+
+      The Dump() function consists of a dumper and an emitter. The dumper
+      walks through each Perl data structure and gives info to the emitter.
+
+    emitter
+
+      The emitter takes info from the dumper and turns it into a YAML
+      stream.
+
+      NOTE: In YAML.pm the parserloader and the dumperemitter code are
+      currently very closely tied together. In the future they may be
+      broken into separate stages.
+
+    For more information please refer to the immensely helpful YAML
+    specification available at http://www.yaml.org/spec/.
+
+YSH - THE YAML SHELL
+
+    The YAML distribution ships with a script called 'ysh', the YAML shell.
+    ysh provides a simple, interactive way to play with YAML. If you type
+    in Perl code, it displays the result in YAML. If you type in YAML it
+    turns it into Perl code.
+
+    To run ysh, (assuming you installed it along with YAML.pm) simply type:
+
+        ysh [options]
+
+    Please read the ysh documentation for the full details. There are lots
+    of options.
+
+BUGS & DEFICIENCIES
+
+    If you find a bug in YAML, please try to recreate it in the YAML Shell
+    with logging turned on ('ysh -L'). When you have successfully
+    reproduced the bug, please mail the LOG file to the author
+    (ingy@cpan.org).
+
+    WARNING: This is still ALPHA code. Well, most of this code has been
+    around for years...
+
+    BIGGER WARNING: YAML.pm has been slow in the making, but I am committed
+    to having top notch YAML tools in the Perl world. The YAML team is
+    close to finalizing the YAML 1.1 spec. This version of YAML.pm is based
+    off of a very old pre 1.0 spec. In actuality there isn't a ton of
+    difference, and this YAML.pm is still fairly useful. Things will get
+    much better in the future.
+
+RESOURCES
+
+    http://lists.sourceforge.net/lists/listinfo/yaml-core is the mailing
+    list. This is where the language is discussed and designed.
+
+    http://www.yaml.org is the official YAML website.
+
+    http://www.yaml.org/spec/ is the YAML 1.2 specification.
+
+    http://yaml.kwiki.org is the official YAML wiki.
+
+SEE ALSO
+
+      * YAML::XS
+
+AUTHOR
+
+    Ingy döt Net <ingy@cpan.org>
+
+COPYRIGHT AND LICENSE
+
+    Copyright 2001-2015. Ingy döt Net.
+
+    This program is free software; you can redistribute it and/or modify it
+    under the same terms as Perl itself.
+
+    See http://www.perl.com/perl/misc/Artistic.html
+