| 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 | YAML::BEGIN |
| 0 | 0 | 0 | 0s | 0s | YAML::Bless |
| 0 | 0 | 0 | 0s | 0s | YAML::Blessed |
| 0 | 0 | 0 | 0s | 0s | YAML::Dump |
| 0 | 0 | 0 | 0s | 0s | YAML::DumpFile |
| 0 | 0 | 0 | 0s | 0s | YAML::Load |
| 0 | 0 | 0 | 0s | 0s | YAML::LoadFile |
| 0 | 0 | 0 | 0s | 0s | YAML::global_object |
| 0 | 0 | 0 | 0s | 0s | YAML::init_action_object |
| 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 | 1 | 1µs | 1µs | *freeze = \ &Dump; |
| 41 | 1 | 1µs | 1µs | *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 |