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