1YAML::Tiny(3) User Contributed Perl Documentation YAML::Tiny(3)
2
6 YAML::Tiny - Read/Write YAML files with as little code as possible
7
9 The YAML specification is huge. Really, really huge. It contains all
10 the functionality of XML, except with flexibility and choice, which
11 makes it easier to read, but with a formal specification that is more
12 complex than XML.
13 The original pure-Perl implementation YAML costs just over 4 megabytes
15 of memory to load. Just like with Windows .ini files (3 meg to load)
16 and CSS (3.5 meg to load) the situation is just asking for a YAML::Tiny
17 module, an incomplete but correct and usable subset of the
18 functionality, in as little code as possible.
19 Like the other "::Tiny" modules, YAML::Tiny has no non-core
21 dependencies, does not require a compiler to install, is back-
22 compatible to Perl 5.004, and can be inlined into other modules if
23 needed.
24 In exchange for this adding this extreme flexibility, it provides
26 support for only a limited subset of YAML. But the subset supported
27 contains most of the features for the more common usese of YAML.
28
30 #############################################
31 # In your file
32 ---
34 rootproperty: blah
35 section:
36 one: two
37 three: four
38 Foo: Bar
39 empty: ~
40 #############################################
44 # In your program
45 use YAML::Tiny;
47 # Create a YAML file
49 my $yaml = YAML::Tiny->new;
50 # Open the config
52 $yaml = YAML::Tiny->read( 'file.yml' );
53 # Reading properties
55 my $root = $yaml->[0]->{rootproperty};
56 my $one = $yaml->[0]->{section}->{one};
57 my $Foo = $yaml->[0]->{section}->{Foo};
58 # Changing data
60 $yaml->[0]->{newsection} = { this => 'that' }; # Add a section
61 $yaml->[0]->{section}->{Foo} = 'Not Bar!'; # Change a value
62 delete $yaml->[0]->{section}; # Delete a value
63 # Add an entire document
65 $yaml->[1] = [ 'foo', 'bar', 'baz' ];
66 # Save the file
68 $yaml->write( 'file.conf' );
69
71 YAML::Tiny is a perl class for reading and writing YAML-style files,
72 written with as little code as possible, reducing load time and memory
73 overhead.
74 Most of the time it is accepted that Perl applications use a lot of
76 memory and modules. The ::Tiny family of modules is specifically
77 intended to provide an ultralight and zero-dependency alternative to
78 many more-thorough standard modules.
79 This module is primarily for reading human-written files (like simple
81 config files) and generating very simple human-readable files. Note
82 that I said human-readable and not geek-readable. The sort of files
83 that your average manager or secretary should be able to look at and
84 make sense of.
85 YAML::Tiny does not generate comments, it won't necesarily preserve the
87 order of your hashes, and it will normalise if reading in and writing
88 out again.
89 It only supports a very basic subset of the full YAML specification.
91 Usage is targetted at files like Perl's META.yml, for which a small and
93 easily-embeddable module is extremely attractive.
94 Features will only be added if they are human readable, and can be
96 written in a few lines of code. Please don't be offended if your
97 request is refused. Someone has to draw the line, and for YAML::Tiny
98 that someone is me.
99 If you need something with more power move up to YAML (4 megabytes of
101 memory overhead) or YAML::Syck (275k, but requires libsyck and a C
102 compiler).
103 To restate, YAML::Tiny does not preserve your comments, whitespace, or
105 the order of your YAML data. But it should round-trip from Perl
106 structure to file and back again just fine.
107
109 This section of the documentation provides a specification for "YAML
110 Tiny", a subset of the YAML specification.
111 It is based on and described comparatively to the YAML 1.1 Working
113 Draft 2004-12-28 specification, located at
114 <http://yaml.org/spec/current.html>.
115 Terminology and chapter numbers are based on that specification.
117 1. Introduction and Goals
119 The purpose of the YAML Tiny specification is to describe a useful
120 subset of the YAML specification that can be used for typical document-
121 oriented use cases such as configuration files and simple data
122 structure dumps.
123 Many specification elements that add flexibility or extensibility are
125 intentionally removed, as is support for complex datastructures, class
126 and object-orientation.
127 In general, the YAML Tiny language targets only those data structures
129 available in JSON, with the additional limitation that only simple keys
130 are supported.
131 As a result, all possible YAML Tiny documents should be able to be
133 transformed into an equivalent JSON document, although the reverse is
134 not necesarily true (but will be true in simple cases).
135 As a result of these simplifications the YAML Tiny specification should
137 be implementable in a (relatively) small amount of code in any language
138 that supports Perl Compatible Regular Expressions (PCRE).
139 2. Introduction
141 YAML Tiny supports three data structures. These are scalars (in a
142 variety of forms), block-form sequences and block-form mappings. Flow-
143 style sequences and mappings are not supported, with some minor
144 exceptions detailed later.
145 The use of three dashes "---" to indicate the start of a new document
147 is supported, and multiple documents per file/stream is allowed.
148 Both line and inline comments are supported.
150 Scalars are supported via the plain style, single quote and double
152 quote, as well as literal-style and folded-style multi-line scalars.
153 The use of explicit tags is not supported.
155 The use of "null" type scalars is supported via the ~ character.
157 The use of "bool" type scalars is not supported.
159 However, serializer implementations should take care to explicitly
161 escape strings that match a "bool" keyword in the following set to
162 prevent other implementations that do support "bool" accidentally
163 reading a string as a boolean
164 y|Y|yes|Yes|YES|n|N|no|No|NO
166 |true|True|TRUE|false|False|FALSE
167 |on|On|ON|off|Off|OFF
168 The use of anchors and aliases is not supported.
170 The use of directives is supported only for the %YAML directive.
172 3. Processing YAML Tiny Information
174 Processes
175 The YAML specification dictates three-phase serialization and three-
177 phase deserialization.
178 The YAML Tiny specification does not mandate any particular methodology
180 or mechanism for parsing.
181 Any compliant parser is only required to parse a single document at a
183 time. The ability to support streaming documents is optional and most
184 likely non-typical.
185 Because anchors and aliases are not supported, the resulting
187 representation graph is thus directed but (unlike the main YAML
188 specification) acyclic.
189 Circular references/pointers are not possible, and any YAML Tiny
191 serializer detecting a circular reference should error with an
192 appropriate message.
193 Presentation Stream
195 YAML Tiny is notionally unicode, but support for unicode is required if
197 the underlying language or system being used to implement a parser does
198 not support Unicode. If unicode is encountered in this case an error
199 should be returned.
200 Loading Failure Points
202 YAML Tiny parsers and emitters are not expected to recover from adapt
204 to errors. The specific error modality of any implementation is not
205 dictated (return codes, exceptions, etc) but is expected to be
206 consistant.
207 4. Syntax
209 Character Set
210 YAML Tiny streams are implemented primarily using the ASCII character
212 set, although the use of Unicode inside strings is allowed if support
213 by the implementation.
214 Specific YAML Tiny encoded document types aiming for maximum
216 compatibility should restrict themselves to ASCII.
217 The escaping and unescaping of the 8-bit YAML escapes is required.
219 The escaping and unescaping of 16-bit and 32-bit YAML escapes is not
221 required.
222 Indicator Characters
224 Support for the "~" null/undefined indicator is required.
226 Implementations may represent this as appropriate for the underlying
228 language.
229 Support for the "-" block sequence indicator is required.
231 Support for the "?" mapping key indicator is not required.
233 Support for the ":" mapping value indicator is required.
235 Support for the "," flow collection indicator is not required.
237 Support for the "[" flow sequence indicator is not required, with one
239 exception (detailed below).
240 Support for the "]" flow sequence indicator is not required, with one
242 exception (detailed below).
243 Support for the "{" flow mapping indicator is not required, with one
245 exception (detailed below).
246 Support for the "}" flow mapping indicator is not required, with one
248 exception (detailed below).
249 Support for the "#" comment indicator is required.
251 Support for the "&" anchor indicator is not required.
253 Support for the "*" alias indicator is not required.
255 Support for the "!" tag indicator is not required.
257 Support for the "|" literal block indicator is required.
259 Support for the ">" folded block indicator is required.
261 Support for the "'" single quote indicator is required.
263 Support for the """ double quote indicator is required.
265 Support for the "%" directive indicator is required, but only for the
267 special case of a %YAML version directive before the "---" document
268 header, or on the same line as the document header.
269 For example:
271 %YAML 1.1
273 ---
274 - A sequence with a single element
275 Special Exception:
277 To provide the ability to support empty sequences and mappings, support
279 for the constructs [] (empty sequence) and {} (empty mapping) are
280 required.
281 For example,
283 %YAML 1.1
285 # A document consisting of only an empty mapping
286 --- {}
287 # A document consisting of only an empty sequence
288 --- []
289 # A document consisting of an empty mapping within a sequence
290 - foo
291 - {}
292 - bar
293 Syntax Primitives
295 Other than the empty sequence and mapping cases described above, YAML
297 Tiny supports only the indentation-based block-style group of contexts.
298 All five scalar contexts are supported.
300 Indentation spaces work as per the YAML specification in all cases.
302 Comments work as per the YAML specification in all simple cases.
304 Support for indented multi-line comments is not required.
305 Seperation spaces work as per the YAML specification in all cases.
307 YAML Tiny Character Stream
309 The only directive supported by the YAML Tiny specification is the
311 %YAML language/version identifier. Although detected, this directive
312 will have no control over the parsing itself.
313 The parser must recognise both the YAML 1.0 and YAML 1.1+ formatting of
315 this directive (as well as the commented form, although no explicit
316 code should be needed to deal with this case, being a comment anyway)
317 That is, all of the following should be supported.
319 --- #YAML:1.0
321 - foo
322 %YAML:1.0
324 ---
325 - foo
326 % YAML 1.1
328 ---
329 - foo
330 Support for the %TAG directive is not required.
332 Support for additional directives is not required.
334 Support for the document boundary marker "---" is required.
336 Support for the document boundary market "..." is not required.
338 If necesary, a document boundary should simply by indicated with a
340 "---" marker, with not preceding "..." marker.
341 Support for empty streams (containing no documents) is required.
343 Support for implicit document starts is required.
345 That is, the following must be equivalent.
347 # Full form
349 %YAML 1.1
350 ---
351 foo: bar
352 # Implicit form
354 foo: bar
355 Nodes
357 Support for nodes optional anchor and tag properties are not required.
359 Support for node anchors is not required.
361 Support for node tags is not required.
363 Support for alias nodes is not required.
365 Support for flow nodes is not required.
367 Support for block nodes is required.
369 Scalar Styles
371 Support for all five scalar styles are required as per the YAML
373 specification, although support for quoted scalars spanning more than
374 one line is not required.
375 Support for the chomping indicators on multi-line scalar styles is
377 required.
378 Collection Styles
380 Support for block-style sequences is required.
382 Support for flow-style sequences is not required.
384 Support for block-style mappings is required.
386 Support for flow-style mappings is not required.
388 Both sequences and mappings should be able to be arbitrarily nested.
390 Support for plain-style mapping keys is required.
392 Support for quoted keys in mappings is not required.
394 Support for "?"-indicated explicit keys is not required.
396 Here endeth the specification.
398 Additional Perl-Specific Notes
400 For some Perl applications, it's important to know if you really have a
401 number and not a string.
402 That is, in some contexts is important that 3 the number is distinctive
404 from "3" the string.
405 Because even Perl itself is not trivially able to understand the
407 difference (certainly without XS-based modules) Perl implementations of
408 the YAML Tiny specification are not required to retain the
409 distinctiveness of 3 vs "3".
410
412 new
413 The constructor "new" creates and returns an empty "YAML::Tiny" object.
414 read $filename
416 The "read" constructor reads a YAML file from a file name, and returns
417 a new "YAML::Tiny" object containing the parsed content.
418 Returns the object on success, or "undef" on error.
420 When "read" fails, "YAML::Tiny" sets an error message internally you
422 can recover via "YAML::Tiny->errstr". Although in some cases a failed
423 "read" will also set the operating system error variable $!, not all
424 errors do and you should not rely on using the $! variable.
425 read_string $string;
427 The "read" constructor reads a YAML file from a file name, and returns
428 a new "YAML::Tiny" object containing the parsed content.
429 Returns the object on success, or "undef" on error.
431 write $filename
433 The "write" method generates the file content for the properties, and
434 writes it to disk to the filename specified.
435 Returns true on success or "undef" on error.
437 write_string
439 Generates the file content for the object and returns it as a string.
440 errstr
442 When an error occurs, you can retrieve the error message either from
443 the $YAML::Tiny::errstr variable, or using the "errstr()" method.
444
446 YAML::Tiny implements a number of functions to add compatibility with
447 the YAML API. These should be a drop-in replacement, except that
448 YAML::Tiny will not export functions by default, and so you will need
449 to explicitly import the functions.
450 Dump
452 my $string = Dump(list-of-Perl-data-structures);
453 Turn Perl data into YAML. This function works very much like
455 Data::Dumper::Dumper().
456 It takes a list of Perl data strucures and dumps them into a serialized
458 form.
459 It returns a string containing the YAML stream.
461 The structures can be references or plain scalars.
463 Load
465 my @documents = Load(string-containing-a-YAML-stream);
466 Turn YAML into Perl data. This is the opposite of Dump.
468 Just like Storable's thaw() function or the eval() function in relation
470 to Data::Dumper.
471 It parses a string containing a valid YAML stream into a list of Perl
473 data structures.
474 freeze() and thaw()
476 Aliases to Dump() and Load() for Storable fans. This will also allow
477 YAML::Tiny to be plugged directly into modules like POE.pm, that use
478 the freeze/thaw API for internal serialization.
479 DumpFile(filepath, list)
481 Writes the YAML stream to a file instead of just returning a string.
482 LoadFile(filepath)
484 Reads the YAML stream from a file instead of a string.
485
487 Bugs should be reported via the CPAN bug tracker at
488 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-Tiny>
490
492 Adam Kennedy <adamk@cpan.org>
493
495 YAML, YAML::Syck, Config::Tiny, CSS::Tiny,
496 <http://use.perl.org/~Alias/journal/29427>, <http://ali.as/>
497
499 Copyright 2006 - 2012 Adam Kennedy.
500 This program is free software; you can redistribute it and/or modify it
502 under the same terms as Perl itself.
503 The full text of the license can be found in the LICENSE file included
505 with this module.
506perl v5.16.3 2012-03-11 YAML::Tiny(3)