Debian Codegraph @

README

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