1YAML(3) User Contributed Perl Documentation YAML(3)
2
6 YAML - YAML Ain't Markup Language™
7
9 This document describes YAML version 1.30.
10
12 This module has been released to CPAN as YAML::Old, and soon YAML.pm
13 will be changed to just be a frontend interface module for all the
14 various Perl YAML implementation modules, including YAML::Old.
15 If you want robust and fast YAML processing using the normal Dump/Load
17 API, please consider switching to YAML::XS. It is by far the best Perl
18 module for YAML at this time. It requires that you have a C compiler,
19 since it is written in C.
20 If you really need to use this version of YAML.pm it will always be
22 available as YAML::Old.
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 # A Mapping
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 # A Sequence
43 - Oren Ben-Kiki
44 - Ingy döt Net
45 --- > # A Block Scalar
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 Since version 1.25 YAML.pm supports trailing comments.
62
64 The YAML.pm module implements a YAML Loader and Dumper based on the
65 YAML 1.0 specification. <http://www.yaml.org/spec/>
66 YAML is a generic data serialization language that is optimized for
68 human readability. It can be used to express the data structures of
69 most modern programming languages. (Including Perl!!!)
70 For information on the YAML syntax, please refer to the YAML
72 specification.
73
75 YAML is readable for people.
76 It makes clear sense out of complex data structures. You should
77 find that YAML is an exceptional data dumping tool. Structure is
78 shown through indentation, YAML supports recursive data, and hash
79 keys are sorted by default. In addition, YAML supports several
80 styles of scalar formatting for different types of data.
81 YAML is editable.
83 YAML was designed from the ground up to be an excellent syntax for
84 configuration files. Almost all programs need configuration files,
85 so why invent a new syntax for each one? And why subject users to
86 the complexities of XML or native Perl code?
87 YAML is multilingual.
89 Yes, YAML supports Unicode. But I'm actually referring to
90 programming languages. YAML was designed to meet the serialization
91 needs of Perl, Python, Ruby, Tcl, PHP, Javascript and Java. It was
92 also designed to be interoperable between those languages. That
93 means YAML serializations produced by Perl can be processed by
94 Python.
95 YAML is taint safe.
97 Using modules like Data::Dumper for serialization is fine as long
98 as you can be sure that nobody can tamper with your data files or
99 transmissions. That's because you need to use Perl's eval() built-
100 in to deserialize the data. Somebody could add a snippet of Perl
101 to erase your files.
102 YAML's parser does not need to eval anything.
104 YAML is full featured.
106 YAML can accurately serialize all of the common Perl data
107 structures and deserialize them again without losing data
108 relationships. Although it is not 100% perfect (no serializer is or
109 can be perfect), it fares as well as the popular current modules:
110 Data::Dumper, Storable, XML::Dumper and Data::Denter.
111 YAML.pm also has the ability to handle code (subroutine) references
113 and typeglobs. (Still experimental) These features are not found in
114 Perl's other serialization modules.
115 YAML is extensible.
117 The YAML language has been designed to be flexible enough to solve
118 it's own problems. The markup itself has 3 basic construct which
119 resemble Perl's hash, array and scalar. By default, these map to
120 their Perl equivalents. But each YAML node also supports a tagging
121 mechanism (type system) which can cause that node to be interpreted
122 in a completely different manner. That's how YAML can support
123 object serialization and oddball structures like Perl's typeglob.
124
126 This module, YAML.pm, is really just the interface module for YAML
127 modules written in Perl. The basic interface for YAML consists of two
128 functions: "Dump" and "Load". The real work is done by the modules
129 YAML::Dumper and YAML::Loader.
130 Different YAML module distributions can be created by subclassing
132 YAML.pm and YAML::Loader and YAML::Dumper. For example, YAML-Simple
133 consists of YAML::Simple YAML::Dumper::Simple and YAML::Loader::Simple.
134 Why would there be more than one implementation of YAML? Well, despite
136 YAML's offering of being a simple data format, YAML is actually very
137 deep and complex. Implementing the entirety of the YAML specification
138 is a daunting task.
139 For this reason I am currently working on 3 different YAML
141 implementations.
142 YAML
144 The main YAML distribution will keeping evolving to support the
145 entire YAML specification in pure Perl. This may not be the fastest
146 or most stable module though. Currently, YAML.pm has lots of known
147 bugs. It is mostly a great tool for dumping Perl data structures to
148 a readable form.
149 YAML::Tiny
151 The point of YAML::Tiny is to strip YAML down to the 90% that
152 people use most and offer that in a small, fast, stable, pure Perl
153 form. YAML::Tiny will simply die when it is asked to do something
154 it can't.
155 YAML::Syck
157 "libsyck" is the C based YAML processing library used by the Ruby
158 programming language (and also Python, PHP and Pugs). YAML::Syck is
159 the Perl binding to "libsyck". It should be very fast, but may have
160 problems of its own. It will also require C compilation.
161 NOTE: Audrey Tang has actually completed this module and it works
163 great and is
164 10 times faster than YAML.pm.
165 In the future, there will likely be even more YAML modules. Remember,
167 people other than Ingy are allowed to write YAML modules!
168
170 YAML is completely OO under the hood. Still it exports a few useful top
171 level functions so that it is dead simple to use. These functions just
172 do the OO stuff for you. If you want direct access to the OO API see
173 the documentation for YAML::Dumper and YAML::Loader.
174 Exported Functions
176 The following functions are exported by YAML.pm by default. The reason
177 they are exported is so that YAML works much like Data::Dumper. If you
178 don't want functions to be imported, just use YAML with an empty import
179 list:
180 use YAML ();
182 Dump(list-of-Perl-data-structures)
184 Turn Perl data into YAML. This function works very much like
185 Data::Dumper::Dumper(). It takes a list of Perl data structures and
186 dumps them into a serialized form. It returns a string containing
187 the YAML stream. The structures can be references or plain scalars.
188 Load(string-containing-a-YAML-stream)
190 Turn YAML into Perl data. This is the opposite of Dump. Just like
191 Storable's thaw() function or the eval() function in relation to
192 Data::Dumper. It parses a string containing a valid YAML stream
193 into a list of Perl data structures.
194 Exportable Functions
196 These functions are not exported by default but you can request them in
197 an import list like this:
198 use YAML qw'freeze thaw Bless';
200 freeze() and thaw()
202 Aliases to Dump() and Load() for Storable fans. This will also
203 allow YAML.pm to be plugged directly into modules like POE.pm, that
204 use the freeze/thaw API for internal serialization.
205 DumpFile(filepath, list)
207 Writes the YAML stream to a file instead of just returning a
208 string.
209 LoadFile(filepath)
211 Reads the YAML stream from a file instead of a string.
212 Bless(perl-node, [yaml-node | class-name])
214 Associate a normal Perl node, with a yaml node. A yaml node is an
215 object tied to the YAML::Node class. The second argument is either
216 a yaml node that you've already created or a class (package) name
217 that supports a yaml_dump() function. A yaml_dump() function should
218 take a perl node and return a yaml node. If no second argument is
219 provided, Bless will create a yaml node. This node is not returned,
220 but can be retrieved with the Blessed() function.
221 Here's an example of how to use Bless. Say you have a hash
223 containing three keys, but you only want to dump two of them.
224 Furthermore the keys must be dumped in a certain order. Here's how
225 you do that:
226 use YAML qw(Dump Bless);
228 $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
229 print Dump $hash;
230 Bless($hash)->keys(['banana', 'apple']);
231 print Dump $hash;
232 produces:
234 ---
236 apple: good
237 banana: bad
238 cauliflower: ugly
239 ---
240 banana: bad
241 apple: good
242 Bless returns the tied part of a yaml-node, so that you can call
244 the YAML::Node methods. This is the same thing that
245 YAML::Node::ynode() returns. So another way to do the above
246 example is:
247 use YAML qw(Dump Bless);
249 use YAML::Node;
250 $hash = {apple => 'good', banana => 'bad', cauliflower => 'ugly'};
251 print Dump $hash;
252 Bless($hash);
253 $ynode = ynode(Blessed($hash));
254 $ynode->keys(['banana', 'apple']);
255 print Dump $hash;
256 Note that Blessing a Perl data structure does not change it anyway.
258 The extra information is stored separately and looked up by the
259 Blessed node's memory address.
260 Blessed(perl-node)
262 Returns the yaml node that a particular perl node is associated
263 with (see above). Returns undef if the node is not (YAML) Blessed.
264
266 YAML options are set using a group of global variables in the YAML
267 namespace. This is similar to how Data::Dumper works.
268 For example, to change the indentation width, do something like:
270 local $YAML::Indent = 3;
272 The current options are:
274 DumperClass
276 You can override which module/class YAML uses for Dumping data.
277 LoadBlessed (since 1.25)
279 Default is undef (false)
280 The default was changed in version 1.30.
282 When set to true, YAML nodes with special tags will be
284 automatocally blessed into objects:
285 - !perl/hash:Foo::Bar
287 foo: 42
288 When loading untrusted YAML, you should disable this option by
290 setting it to 0. This will also disable setting typeglobs when
291 loading them.
292 You can create any kind of object with YAML. The creation itself is
294 not the critical part. If the class has a "DESTROY" method, it will
295 be called once the object is deleted. An example with File::Temp
296 removing files can be found at
297 <https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=862373>
298 LoaderClass
300 You can override which module/class YAML uses for Loading data.
301 Indent
303 This is the number of space characters to use for each indentation
304 level when doing a Dump(). The default is 2.
305 By the way, YAML can use any number of characters for indentation
307 at any level. So if you are editing YAML by hand feel free to do it
308 anyway that looks pleasing to you; just be consistent for a given
309 level.
310 SortKeys
312 Default is 1. (true)
313 Tells YAML.pm whether or not to sort hash keys when storing a
315 document.
316 YAML::Node objects can have their own sort order, which is usually
318 what you want. To override the YAML::Node order and sort the keys
319 anyway, set SortKeys to 2.
320 Stringify
322 Default is 0. (false)
323 Objects with string overloading should honor the overloading and
325 dump the stringification of themselves, rather than the actual
326 object's guts.
327 Numify
329 Default is 0. (false)
330 Values that look like numbers (integers, floats) will be numified
332 when loaded.
333 UseHeader
335 Default is 1. (true)
336 This tells YAML.pm whether to use a separator string for a Dump
338 operation. This only applies to the first document in a stream.
339 Subsequent documents must have a YAML header by definition.
340 UseVersion
342 Default is 0. (false)
343 Tells YAML.pm whether to include the YAML version on the
345 separator/header.
346 --- %YAML:1.0
348 AnchorPrefix
350 Default is ''.
351 Anchor names are normally numeric. YAML.pm simply starts with '1'
353 and increases by one for each new anchor. This option allows you to
354 specify a string to be prepended to each anchor number.
355 UseCode
357 Setting the UseCode option is a shortcut to set both the DumpCode
358 and LoadCode options at once. Setting UseCode to '1' tells YAML.pm
359 to dump Perl code references as Perl (using B::Deparse) and to load
360 them back into memory using eval(). The reason this has to be an
361 option is that using eval() to parse untrusted code is, well,
362 untrustworthy.
363 DumpCode
365 Determines if and how YAML.pm should serialize Perl code
366 references. By default YAML.pm will dump code references as dummy
367 placeholders (much like Data::Dumper). If DumpCode is set to '1' or
368 'deparse', code references will be dumped as actual Perl code.
369 LoadCode
371 LoadCode is the opposite of DumpCode. It tells YAML if and how to
372 deserialize code references. When set to '1' or 'deparse' it will
373 use eval(). Since this is potentially risky, only use this option
374 if you know where your YAML has been.
375 LoadCode must be enabled also to use the feature of evaluating
377 typeglobs (because with the typeglob feature you would be able to
378 set the variable $YAML::LoadCode from a YAML file).
379 Preserve
381 When set to true, this option tells the Loader to load hashes into
382 YAML::Node objects. These are tied hashes. This has the effect of
383 remembering the key order, thus it will be preserved when the hash
384 is dumped again. See YAML::Node for more information.
385 UseBlock
387 YAML.pm uses heuristics to guess which scalar style is best for a
388 given node. Sometimes you'll want all multiline scalars to use the
389 'block' style. If so, set this option to 1.
390 NOTE: YAML's block style is akin to Perl's here-document.
392 UseFold (Not supported anymore since v0.60)
394 If you want to force YAML to use the 'folded' style for all
395 multiline scalars, then set $UseFold to 1.
396 NOTE: YAML's folded style is akin to the way HTML folds text,
398 except smarter.
399 UseAliases
401 YAML has an alias mechanism such that any given structure in memory
402 gets serialized once. Any other references to that structure are
403 serialized only as alias markers. This is how YAML can serialize
404 duplicate and recursive structures.
405 Sometimes, when you KNOW that your data is nonrecursive in nature,
407 you may want to serialize such that every node is expressed in
408 full. (ie as a copy of the original). Setting $YAML::UseAliases to
409 0 will allow you to do this. This also may result in faster
410 processing because the lookup overhead is by bypassed.
411 THIS OPTION CAN BE DANGEROUS. If your data is recursive, this
413 option will cause Dump() to run in an endless loop, chewing up your
414 computers memory. You have been warned.
415 CompressSeries
417 Default is 1.
418 Compresses the formatting of arrays of hashes:
420 -
422 foo: bar
423 -
424 bar: foo
425 becomes:
427 - foo: bar
429 - bar: foo
430 Since this output is usually more desirable, this option is turned
432 on by default.
433 QuoteNumericStrings
435 Default is 0. (false)
436 Adds detection mechanisms to encode strings that resemble numbers
438 with mandatory quoting.
439 This ensures leading that things like leading/trailing zeros and
441 other formatting are preserved.
442
444 YAML is a full featured data serialization language, and thus has its
445 own terminology.
446 It is important to remember that although YAML is heavily influenced by
448 Perl and Python, it is a language in its own right, not merely just a
449 representation of Perl structures.
450 YAML has three constructs that are conspicuously similar to Perl's
452 hash, array, and scalar. They are called mapping, sequence, and string
453 respectively. By default, they do what you would expect. But each
454 instance may have an explicit or implicit tag (type) that makes it
455 behave differently. In this manner, YAML can be extended to represent
456 Perl's Glob or Python's tuple, or Ruby's Bigint.
457 stream
459 A YAML stream is the full sequence of Unicode characters that a YAML
460 parser would read or a YAML emitter would write. A stream may contain
461 one or more YAML documents separated by YAML headers.
462 ---
464 a: mapping
465 foo: bar
466 ---
467 - a
468 - sequence
469 document
471 A YAML document is an independent data structure representation
472 within a stream. It is a top level node. Each document in a YAML
473 stream must begin with a YAML header line. Actually the header is
474 optional on the first document.
475 ---
477 This: top level mapping
478 is:
479 - a
480 - YAML
481 - document
482 header
484 A YAML header is a line that begins a YAML document. It consists of
485 three dashes, possibly followed by more info. Another purpose of
486 the header line is that it serves as a place to put top level tag
487 and anchor information.
488 --- !recursive-sequence &001
490 - * 001
491 - * 001
492 node
494 A YAML node is the representation of a particular data structure.
495 Nodes may contain other nodes. (In Perl terms, nodes are like
496 scalars. Strings, arrayrefs and hashrefs. But this refers to the
497 serialized format, not the in- memory structure.)
498 tag This is similar to a type. It indicates how a particular YAML node
500 serialization should be transferred into or out of memory. For
501 instance a Foo::Bar object would use the tag 'perl/Foo::Bar':
502 - !perl/Foo::Bar
504 foo: 42
505 bar: stool
506 collection
508 A collection is the generic term for a YAML data grouping. YAML has
509 two types of collections: mappings and sequences. (Similar to
510 hashes and arrays)
511 mapping
513 A mapping is a YAML collection defined by unordered key/value pairs
514 with unique keys. By default YAML mappings are loaded into Perl
515 hashes.
516 a mapping:
518 foo: bar
519 two: times two is 4
520 sequence
522 A sequence is a YAML collection defined by an ordered list of
523 elements. By default YAML sequences are loaded into Perl arrays.
524 a sequence:
526 - one bourbon
527 - one scotch
528 - one beer
529 scalar
531 A scalar is a YAML node that is a single value. By default YAML
532 scalars are loaded into Perl scalars.
533 a scalar key: a scalar value
535 YAML has many styles for representing scalars. This is important
537 because varying data will have varying formatting requirements to
538 retain the optimum human readability.
539 plain scalar
541 A plain scalar is unquoted. All plain scalars are automatic
542 candidates for "implicit tagging". This means that their tag may be
543 determined automatically by examination. The typical uses for this
544 are plain alpha strings, integers, real numbers, dates, times and
545 currency.
546 - a plain string
548 - -42
549 - 3.1415
550 - 12:34
551 - 123 this is an error
552 single quoted scalar
554 This is similar to Perl's use of single quotes. It means no
555 escaping except for single quotes which are escaped by using two
556 adjacent single quotes.
557 - 'When I say ''\n'' I mean "backslash en"'
559 double quoted scalar
561 This is similar to Perl's use of double quotes. Character escaping
562 can be used.
563 - "This scalar\nhas two lines, and a bell -->\a"
565 folded scalar
567 This is a multiline scalar which begins on the next line. It is
568 indicated by a single right angle bracket. It is unescaped like the
569 single quoted scalar. Line folding is also performed.
570 - >
572 This is a multiline scalar which begins on
573 the next line. It is indicated by a single
574 carat. It is unescaped like the single
575 quoted scalar. Line folding is also
576 performed.
577 block scalar
579 This final multiline form is akin to Perl's here-document except
580 that (as in all YAML data) scope is indicated by indentation.
581 Therefore, no ending marker is required. The data is verbatim. No
582 line folding.
583 - |
585 QTY DESC PRICE TOTAL
586 --- ---- ----- -----
587 1 Foo Fighters $19.95 $19.95
588 2 Bar Belles $29.95 $59.90
589 parser
591 A YAML processor has four stages: parse, load, dump, emit.
592 A parser parses a YAML stream. YAML.pm's Load() function contains a
594 parser.
595 loader
597 The other half of the Load() function is a loader. This takes the
598 information from the parser and loads it into a Perl data
599 structure.
600 dumper
602 The Dump() function consists of a dumper and an emitter. The dumper
603 walks through each Perl data structure and gives info to the
604 emitter.
605 emitter
607 The emitter takes info from the dumper and turns it into a YAML
608 stream.
609 NOTE: In YAML.pm the parserloader and the dumperemitter code are
611 currently
612 very closely tied together. In the future they may be broken
613 into
614 separate stages.
615 For more information please refer to the immensely helpful YAML
617 specification available at <http://www.yaml.org/spec/>.
618
620 The YAML::Shell distribution provides script called 'ysh', the YAML
621 shell. ysh provides a simple, interactive way to play with YAML. If
622 you type in Perl code, it displays the result in YAML. If you type in
623 YAML it turns it into Perl code.
624 To run ysh, (assuming you installed it along with YAML.pm) simply type:
626 ysh [options]
628 Please read the "ysh" documentation for the full details. There are
630 lots of options.
631
633 If you find a bug in YAML, please try to recreate it in the YAML Shell
634 with logging turned on ('ysh -L'). When you have successfully
635 reproduced the bug, please mail the LOG file to the author
636 (ingy@cpan.org).
637 WARNING: This is still ALPHA code. Well, most of this code has been
639 around for years...
640 BIGGER WARNING: YAML.pm has been slow in the making, but I am committed
642 to having top notch YAML tools in the Perl world. The YAML team is
643 close to finalizing the YAML 1.1 spec. This version of YAML.pm is based
644 off of a very old pre 1.0 spec. In actuality there isn't a ton of
645 difference, and this YAML.pm is still fairly useful. Things will get
646 much better in the future.
647
649 <http://lists.sourceforge.net/lists/listinfo/yaml-core> is the mailing
650 list. This is where the language is discussed and designed.
651 <http://www.yaml.org> is the official YAML website.
653 <http://www.yaml.org/spec/> is the YAML 1.2 specification.
655 <http://yaml.kwiki.org> is the official YAML wiki.
657
659 • YAML::XS
660
662 Ingy döt Net <ingy@cpan.org>
663
665 Copyright 2001-2020. Ingy döt Net.
666 This program is free software; you can redistribute it and/or modify it
668 under the same terms as Perl itself.
669 See <http://www.perl.com/perl/misc/Artistic.html>
671perl v5.36.0 2023-01-20 YAML(3)