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