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