X-Git-Url: http://wagnertech.de/gitweb/gitweb.cgi/mfinanz.git/blobdiff_plain/deb4d2dbb676d7d6f69dfe7815d6e0cb09bd4a44..53593baa211863fbf66540cf1bcc36c8fb37257f:/doc/modules/README.YAML diff --git a/doc/modules/README.YAML b/doc/modules/README.YAML deleted file mode 100644 index 0fbb2fd09..000000000 --- a/doc/modules/README.YAML +++ /dev/null @@ -1,611 +0,0 @@ -NAME - YAML - YAML Ain't Markup Language (tm) - -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. - - 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::Lite - The point of YAML::Lite is to strip YAML down to the 90% that people - use most and offer that in a small, fast, stable, pure Perl form. - YAML::Lite 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 strucures 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. - -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 stucture. - 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 sclar 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 parser/loader and the dumper/emitter 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 . - -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 - is the mailing - list. This is where the language is discussed and designed. - - is the official YAML website. - - is the YAML 1.0 specification. - - is the official YAML wiki. - -SEE ALSO - See YAML::Syck. Fast! - -AUTHOR - Ingy döt Net - - is resonsible for YAML.pm. - - The YAML serialization language is the result of years of collaboration - between Oren Ben-Kiki, Clark Evans and Ingy döt Net. Several others - have added help along the way. - -COPYRIGHT - Copyright (c) 2005, 2006. Ingy döt Net. All rights reserved. Copyright - (c) 2001, 2002, 2005. Brian Ingerson. All rights reserved. - - This program is free software; you can redistribute it and/or modify it - under the same terms as Perl itself. - - See -