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