1YAML(3) User Contributed Perl Documentation YAML(3)
2
6 YAML - YAML Ain't Markup Language™
7
9 This document describes YAML version 1.28.
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()"
100 built-in to deserialize the data. Somebody could add a snippet of
101 Perl 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
218 should take a perl node and return a yaml node. If no second
219 argument is provided, Bless will create a yaml node. This node is
220 not returned, 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 1 (true).
280 When set to true, YAML nodes with special tags will be
282 automatocally blessed into objects:
283 - !perl/hash:Foo::Bar
285 foo: 42
286 When loading untrusted YAML, you should disable this option by
288 setting it to 0. This will also disable setting typeglobs when
289 loading them.
290 LoaderClass
292 You can override which module/class YAML uses for Loading data.
293 Indent
295 This is the number of space characters to use for each indentation
296 level when doing a Dump(). The default is 2.
297 By the way, YAML can use any number of characters for indentation
299 at any level. So if you are editing YAML by hand feel free to do it
300 anyway that looks pleasing to you; just be consistent for a given
301 level.
302 SortKeys
304 Default is 1. (true)
305 Tells YAML.pm whether or not to sort hash keys when storing a
307 document.
308 YAML::Node objects can have their own sort order, which is usually
310 what you want. To override the YAML::Node order and sort the keys
311 anyway, set SortKeys to 2.
312 Stringify
314 Default is 0. (false)
315 Objects with string overloading should honor the overloading and
317 dump the stringification of themselves, rather than the actual
318 object's guts.
319 Numify
321 Default is 0. (false)
322 Values that look like numbers (integers, floats) will be numified
324 when loaded.
325 UseHeader
327 Default is 1. (true)
328 This tells YAML.pm whether to use a separator string for a Dump
330 operation. This only applies to the first document in a stream.
331 Subsequent documents must have a YAML header by definition.
332 UseVersion
334 Default is 0. (false)
335 Tells YAML.pm whether to include the YAML version on the
337 separator/header.
338 --- %YAML:1.0
340 AnchorPrefix
342 Default is ''.
343 Anchor names are normally numeric. YAML.pm simply starts with '1'
345 and increases by one for each new anchor. This option allows you to
346 specify a string to be prepended to each anchor number.
347 UseCode
349 Setting the UseCode option is a shortcut to set both the DumpCode
350 and LoadCode options at once. Setting UseCode to '1' tells YAML.pm
351 to dump Perl code references as Perl (using B::Deparse) and to load
352 them back into memory using eval(). The reason this has to be an
353 option is that using eval() to parse untrusted code is, well,
354 untrustworthy.
355 DumpCode
357 Determines if and how YAML.pm should serialize Perl code
358 references. By default YAML.pm will dump code references as dummy
359 placeholders (much like Data::Dumper). If DumpCode is set to '1' or
360 'deparse', code references will be dumped as actual Perl code.
361 LoadCode
363 LoadCode is the opposite of DumpCode. It tells YAML if and how to
364 deserialize code references. When set to '1' or 'deparse' it will
365 use "eval()". Since this is potentially risky, only use this option
366 if you know where your YAML has been.
367 LoadCode must be enabled also to use the feature of evaluating
369 typeglobs (because with the typeglob feature you would be able to
370 set the variable $YAML::LoadCode from a YAML file).
371 Preserve
373 When set to true, this option tells the Loader to load hashes into
374 YAML::Node objects. These are tied hashes. This has the effect of
375 remembering the key order, thus it will be preserved when the hash
376 is dumped again. See YAML::Node for more information.
377 UseBlock
379 YAML.pm uses heuristics to guess which scalar style is best for a
380 given node. Sometimes you'll want all multiline scalars to use the
381 'block' style. If so, set this option to 1.
382 NOTE: YAML's block style is akin to Perl's here-document.
384 UseFold (Not supported anymore since v0.60)
386 If you want to force YAML to use the 'folded' style for all
387 multiline scalars, then set $UseFold to 1.
388 NOTE: YAML's folded style is akin to the way HTML folds text,
390 except smarter.
391 UseAliases
393 YAML has an alias mechanism such that any given structure in memory
394 gets serialized once. Any other references to that structure are
395 serialized only as alias markers. This is how YAML can serialize
396 duplicate and recursive structures.
397 Sometimes, when you KNOW that your data is nonrecursive in nature,
399 you may want to serialize such that every node is expressed in
400 full. (ie as a copy of the original). Setting $YAML::UseAliases to
401 0 will allow you to do this. This also may result in faster
402 processing because the lookup overhead is by bypassed.
403 THIS OPTION CAN BE DANGEROUS. If your data is recursive, this
405 option will cause Dump() to run in an endless loop, chewing up your
406 computers memory. You have been warned.
407 CompressSeries
409 Default is 1.
410 Compresses the formatting of arrays of hashes:
412 -
414 foo: bar
415 -
416 bar: foo
417 becomes:
419 - foo: bar
421 - bar: foo
422 Since this output is usually more desirable, this option is turned
424 on by default.
425 QuoteNumericStrings
427 Default is 0. (false)
428 Adds detection mechanisms to encode strings that resemble numbers
430 with mandatory quoting.
431 This ensures leading that things like leading/trailing zeros and
433 other formatting are preserved.
434
436 YAML is a full featured data serialization language, and thus has its
437 own terminology.
438 It is important to remember that although YAML is heavily influenced by
440 Perl and Python, it is a language in its own right, not merely just a
441 representation of Perl structures.
442 YAML has three constructs that are conspicuously similar to Perl's
444 hash, array, and scalar. They are called mapping, sequence, and string
445 respectively. By default, they do what you would expect. But each
446 instance may have an explicit or implicit tag (type) that makes it
447 behave differently. In this manner, YAML can be extended to represent
448 Perl's Glob or Python's tuple, or Ruby's Bigint.
449 stream
451 A YAML stream is the full sequence of Unicode characters that a YAML
452 parser would read or a YAML emitter would write. A stream may contain
453 one or more YAML documents separated by YAML headers.
454 ---
456 a: mapping
457 foo: bar
458 ---
459 - a
460 - sequence
461 document
463 A YAML document is an independent data structure representation
464 within a stream. It is a top level node. Each document in a YAML
465 stream must begin with a YAML header line. Actually the header is
466 optional on the first document.
467 ---
469 This: top level mapping
470 is:
471 - a
472 - YAML
473 - document
474 header
476 A YAML header is a line that begins a YAML document. It consists of
477 three dashes, possibly followed by more info. Another purpose of
478 the header line is that it serves as a place to put top level tag
479 and anchor information.
480 --- !recursive-sequence &001
482 - * 001
483 - * 001
484 node
486 A YAML node is the representation of a particular data structure.
487 Nodes may contain other nodes. (In Perl terms, nodes are like
488 scalars. Strings, arrayrefs and hashrefs. But this refers to the
489 serialized format, not the in- memory structure.)
490 tag This is similar to a type. It indicates how a particular YAML node
492 serialization should be transferred into or out of memory. For
493 instance a Foo::Bar object would use the tag 'perl/Foo::Bar':
494 - !perl/Foo::Bar
496 foo: 42
497 bar: stool
498 collection
500 A collection is the generic term for a YAML data grouping. YAML has
501 two types of collections: mappings and sequences. (Similar to
502 hashes and arrays)
503 mapping
505 A mapping is a YAML collection defined by unordered key/value pairs
506 with unique keys. By default YAML mappings are loaded into Perl
507 hashes.
508 a mapping:
510 foo: bar
511 two: times two is 4
512 sequence
514 A sequence is a YAML collection defined by an ordered list of
515 elements. By default YAML sequences are loaded into Perl arrays.
516 a sequence:
518 - one bourbon
519 - one scotch
520 - one beer
521 scalar
523 A scalar is a YAML node that is a single value. By default YAML
524 scalars are loaded into Perl scalars.
525 a scalar key: a scalar value
527 YAML has many styles for representing scalars. This is important
529 because varying data will have varying formatting requirements to
530 retain the optimum human readability.
531 plain scalar
533 A plain scalar is unquoted. All plain scalars are automatic
534 candidates for "implicit tagging". This means that their tag may be
535 determined automatically by examination. The typical uses for this
536 are plain alpha strings, integers, real numbers, dates, times and
537 currency.
538 - a plain string
540 - -42
541 - 3.1415
542 - 12:34
543 - 123 this is an error
544 single quoted scalar
546 This is similar to Perl's use of single quotes. It means no
547 escaping except for single quotes which are escaped by using two
548 adjacent single quotes.
549 - 'When I say ''\n'' I mean "backslash en"'
551 double quoted scalar
553 This is similar to Perl's use of double quotes. Character escaping
554 can be used.
555 - "This scalar\nhas two lines, and a bell -->\a"
557 folded scalar
559 This is a multiline scalar which begins on the next line. It is
560 indicated by a single right angle bracket. It is unescaped like the
561 single quoted scalar. Line folding is also performed.
562 - >
564 This is a multiline scalar which begins on
565 the next line. It is indicated by a single
566 carat. It is unescaped like the single
567 quoted scalar. Line folding is also
568 performed.
569 block scalar
571 This final multiline form is akin to Perl's here-document except
572 that (as in all YAML data) scope is indicated by indentation.
573 Therefore, no ending marker is required. The data is verbatim. No
574 line folding.
575 - |
577 QTY DESC PRICE TOTAL
578 --- ---- ----- -----
579 1 Foo Fighters $19.95 $19.95
580 2 Bar Belles $29.95 $59.90
581 parser
583 A YAML processor has four stages: parse, load, dump, emit.
584 A parser parses a YAML stream. YAML.pm's Load() function contains a
586 parser.
587 loader
589 The other half of the Load() function is a loader. This takes the
590 information from the parser and loads it into a Perl data
591 structure.
592 dumper
594 The Dump() function consists of a dumper and an emitter. The dumper
595 walks through each Perl data structure and gives info to the
596 emitter.
597 emitter
599 The emitter takes info from the dumper and turns it into a YAML
600 stream.
601 NOTE: In YAML.pm the parserloader and the dumperemitter code are
603 currently
604 very closely tied together. In the future they may be broken
605 into
606 separate stages.
607 For more information please refer to the immensely helpful YAML
609 specification available at <http://www.yaml.org/spec/>.
610
612 The YAML::Shell distribution provides script called 'ysh', the YAML
613 shell. ysh provides a simple, interactive way to play with YAML. If
614 you type in Perl code, it displays the result in YAML. If you type in
615 YAML it turns it into Perl code.
616 To run ysh, (assuming you installed it along with YAML.pm) simply type:
618 ysh [options]
620 Please read the "ysh" documentation for the full details. There are
622 lots of options.
623
625 If you find a bug in YAML, please try to recreate it in the YAML Shell
626 with logging turned on ('ysh -L'). When you have successfully
627 reproduced the bug, please mail the LOG file to the author
628 (ingy@cpan.org).
629 WARNING: This is still ALPHA code. Well, most of this code has been
631 around for years...
632 BIGGER WARNING: YAML.pm has been slow in the making, but I am committed
634 to having top notch YAML tools in the Perl world. The YAML team is
635 close to finalizing the YAML 1.1 spec. This version of YAML.pm is based
636 off of a very old pre 1.0 spec. In actuality there isn't a ton of
637 difference, and this YAML.pm is still fairly useful. Things will get
638 much better in the future.
639
641 <http://lists.sourceforge.net/lists/listinfo/yaml-core> is the mailing
642 list. This is where the language is discussed and designed.
643 <http://www.yaml.org> is the official YAML website.
645 <http://www.yaml.org/spec/> is the YAML 1.2 specification.
647 <http://yaml.kwiki.org> is the official YAML wiki.
649
651 · YAML::XS
652
654 Ingy döt Net <ingy@cpan.org>
655
657 Copyright 2001-2019. Ingy döt Net.
658 This program is free software; you can redistribute it and/or modify it
660 under the same terms as Perl itself.
661 See <http://www.perl.com/perl/misc/Artistic.html>
663perl v5.28.1 2019-04-28 YAML(3)