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