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 will have no non-core
21 dependencies, not require a compiler, and be back-compatible to at
22 least perl 5.005_03, and ideally 5.004.
23
25 #############################################
26 # In your file
27 ---
29 rootproperty: blah
30 section:
31 one: two
32 three: four
33 Foo: Bar
34 empty: ~
35 #############################################
39 # In your program
40 use YAML::Tiny;
42 # Create a YAML file
44 my $yaml = YAML::Tiny->new;
45 # Open the config
47 $yaml = YAML::Tiny->read( 'file.yml' );
48 # Reading properties
50 my $root = $yaml->[0]->{rootproperty};
51 my $one = $yaml->[0]->{section}->{one};
52 my $Foo = $yaml->[0]->{section}->{Foo};
53 # Changing data
55 $yaml->[0]->{newsection} = { this => 'that' }; # Add a section
56 $yaml->[0]->{section}->{Foo} = 'Not Bar!'; # Change a value
57 delete $yaml->[0]->{section}; # Delete a value or section
58 # Add an entire document
60 $yaml->[1] = [ 'foo', 'bar', 'baz' ];
61 # Save the file
63 $yaml->write( 'file.conf' );
64
66 YAML::Tiny is a perl class for reading and writing YAML-style files,
67 written with as little code as possible, reducing load time and memory
68 overhead.
69 Most of the time it is accepted that Perl applications use a lot of
71 memory and modules. The ::Tiny family of modules is specifically
72 intended to provide an ultralight and zero-dependency alternative to
73 many more-thorough standard modules.
74 This module is primarily for reading human-written files (like simple
76 config files) and generating very simple human-readable files. Note
77 that I said human-readable and not geek-readable. The sort of files
78 that your average manager or secretary should be able to look at and
79 make sense of.
80 YAML::Tiny does not generate comments, it won't necesarily preserve the
82 order of your hashes, and it will normalise if reading in and writing
83 out again.
84 It only supports a very basic subset of the full YAML specification.
86 Usage is targetted at files like Perl's META.yml, for which a small and
88 easily-embeddable module is extremely attractive.
89 Features will only be added if they are human readable, and can be
91 written in a few lines of code. Please don't be offended if your
92 request is refused. Someone has to draw the line, and for YAML::Tiny
93 that someone is me.
94 If you need something with more power move up to YAML (4 megabytes of
96 memory overhead) or YAML::Syck (275k, but requires libsyck and a C
97 compiler).
98 To restate, YAML::Tiny does not preserve your comments, whitespace, or
100 the order of your YAML data. But it should round-trip from Perl
101 structure to file and back again just fine.
102
104 This section of the documentation provides a specification for "YAML
105 Tiny", a subset of the YAML specification.
106 It is based on and described comparatively to the YAML 1.1 Working
108 Draft 2004-12-28 specification, located at
109 <http://yaml.org/spec/current.html>.
110 Terminology and chapter numbers are based on that specification.
112 1. Introduction and Goals
114 The purpose of the YAML Tiny specification is to describe a useful
115 subset of the YAML specification that can be used for typical document-
116 oriented uses such as configuration files and simple data structure
117 dumps.
118 Many specification elements that add flexibility or extensibility are
120 intentionally removed, as is support for complex datastructures, class
121 and object-orientation.
122 In general, YAML Tiny targets only those data structures available in
124 JSON, with the additional limitation that only simple keys are
125 supported.
126 As a result, all possible YAML Tiny documents should be able to be
128 transformed into an equivalent JSON document, although the reverse is
129 not necesarily true (but will be true in simple cases).
130 As a result of these simplifications the YAML Tiny specification should
132 be implementable in a relatively small amount of code in any language
133 that supports Perl Compatible Regular Expressions (PCRE).
134 2. Introduction
136 YAML Tiny supports three data structures. These are scalars (in a
137 variety of forms), block-form sequences and block-form mappings. Flow-
138 style sequences and mappings are not supported, with some minor
139 exceptions detailed later.
140 The use of three dashes "---" to indicate the start of a new document
142 is supported, and multiple documents per file/stream is allowed.
143 Both line and inline comments are supported.
145 Scalars are supported via the plain style, single quote and double
147 quote, as well as literal-style and folded-style multi-line scalars.
148 The use of tags is not supported.
150 The use of anchors and aliases is not supported.
152 The use of directives is supported only for the %YAML directive.
154 3. Processing YAML Tiny Information
156 Processes
157 The YAML specification dictates three-phase serialization and three-
159 phase deserialization.
160 The YAML Tiny specification does not mandate any particular methodology
162 or mechanism for parsing.
163 Any compliant parser is only required to parse a single document at a
165 time. The ability to support streaming documents is optional and most
166 likely non-typical.
167 Because anchors and aliases are not supported, the resulting
169 representation graph is thus directed but (unlike the main YAML
170 specification) acyclic.
171 Circular references/pointers are not possible, and any YAML Tiny
173 serializer detecting a circulars should error with an appropriate
174 message.
175 Presentation Stream
177 YAML Tiny is notionally unicode, but support for unicode is required if
179 the underlying language or system being used to implement a parser does
180 not support Unicode. If unicode is encountered in this case an error
181 should be returned.
182 Loading Failure Points
184 YAML Tiny parsers and emitters are not expected to recover from adapt
186 to errors. The specific error modality of any implementation is not
187 dictated (return codes, exceptions, etc) but is expected to be
188 consistant.
189 4. Syntax
191 Character Set
192 YAML Tiny streams are implemented primarily using the ASCII character
194 set, although the use of Unicode inside strings is allowed if support
195 by the implementation.
196 Specific YAML Tiny encoded document types aiming for maximum
198 compatibility should restrict themselves to ASCII.
199 The escaping and unescaping of the 8-bit YAML escapes is required.
201 The escaping and unescaping of 16-bit and 32-bit YAML escapes is not
203 required.
204 Indicator Characters
206 Support for the "~" null/undefined indicator is required.
208 Implementations may represent this as appropriate for the underlying
210 language.
211 Support for the "-" block sequence indicator is required.
213 Support for the "?" mapping key indicator is not required.
215 Support for the ":" mapping value indicator is required.
217 Support for the "," flow collection indicator is not required.
219 Support for the "[" flow sequence indicator is not required, with one
221 exception (detailed below).
222 Support for the "]" flow sequence indicator is not required, with one
224 exception (detailed below).
225 Support for the "{" flow mapping indicator is not required, with one
227 exception (detailed below).
228 Support for the "}" flow mapping indicator is not required, with one
230 exception (detailed below).
231 Support for the "#" comment indicator is required.
233 Support for the "&" anchor indicator is not required.
235 Support for the "*" alias indicator is not required.
237 Support for the "!" tag indicator is not required.
239 Support for the "|" literal block indicator is required.
241 Support for the ">" folded block indicator is required.
243 Support for the "'" single quote indicator is required.
245 Support for the """ double quote indicator is required.
247 Support for the "%" directive indicator is required, but only for the
249 special case of a %YAML version directive before the "---" document
250 header, or on the same line as the document header.
251 For example:
253 %YAML 1.1
255 ---
256 - A sequence with a single element
257 Special Exception:
259 To provide the ability to support empty sequences and mappings, support
261 for the constructs [] (empty sequence) and {} (empty mapping) are
262 required.
263 For example,
265 %YAML 1.1
267 # A document consisting of only an empty mapping
268 --- {}
269 # A document consisting of only an empty sequence
270 --- []
271 # A document consisting of an empty mapping within a sequence
272 - foo
273 - {}
274 - bar
275 Syntax Primitives
277 Other than the empty sequence and mapping cases described above, YAML
279 Tiny supports only the indentation-based block-style group of contexts.
280 All five scalar contexts are supported.
282 Indentation spaces work as per the YAML specification in all cases.
284 Comments work as per the YAML specification in all simple cases.
286 Support for indented multi-line comments is not required.
287 Seperation spaces work as per the YAML specification in all cases.
289 YAML Tiny Character Stream
291 The only directive supported by the YAML Tiny specification is the
293 %YAML language/version identifier. Although detected, this directive
294 will have no control over the parsing itself.
295 The parser must recognise both the YAML 1.0 and YAML 1.1+ formatting of
297 this directive (as well as the commented form, although no explicit
298 code should be needed to deal with this case, being a comment anyway)
299 That is, all of the following should be supported.
301 --- #YAML:1.0
303 - foo
304 %YAML:1.0
306 ---
307 - foo
308 % YAML 1.1
310 ---
311 - foo
312 Support for the %TAG directive is not required.
314 Support for additional directives is not required.
316 Support for the document boundary marker "---" is required.
318 Support for the document boundary market "..." is not required.
320 If necesary, a document boundary should simply by indicated with a
322 "---" marker, with not preceding "..." marker.
323 Support for empty streams (containing no documents) is required.
325 Support for implicit document starts is required.
327 That is, the following must be equivalent.
329 # Full form
331 %YAML 1.1
332 ---
333 foo: bar
334 # Implicit form
336 foo: bar
337 Nodes
339 Support for nodes optional anchor and tag properties are not required.
341 Support for node anchors is not required.
343 Supprot for node tags is not required.
345 Support for alias nodes is not required.
347 Support for flow nodes is not required.
349 Support for block nodes is required.
351 Scalar Styles
353 Support for all five scalar styles are required as per the YAML
355 specification, although support for quoted scalars spanning more than
356 one line is not required.
357 Support for the chomping indicators on multi-line scalar styles is
359 required.
360 Collection Styles
362 Support for block-style sequences is required.
364 Support for flow-style sequences is not required.
366 Support for block-style mappings is required.
368 Support for flow-style mappings is not required.
370 Both sequences and mappings should be able to be arbitrarily nested.
372 Support for plain-style mapping keys is required.
374 Support for quoted keys in mappings is not required.
376 Support for "?"-indicated explicit keys is not required.
378 Here endeth the specification.
380 Additional Perl-Specific Notes
382 For some Perl applications, it's important to know if you really have a
383 number and not a string.
384 That is, in some contexts is important that 3 the number is distinctive
386 from "3" the string.
387 Because even Perl itself is not trivially able to understand the
389 difference (certainly without XS-based modules) Perl implementations of
390 the YAML Tiny specification are not required to retain the
391 distinctiveness of 3 vs "3".
392
394 new
395 The constructor "new" creates and returns an empty "YAML::Tiny" object.
396 read $filename
398 The "read" constructor reads a YAML file, and returns a new
399 "YAML::Tiny" object containing the contents of the file.
400 Returns the object on success, or "undef" on error.
402 When "read" fails, "YAML::Tiny" sets an error message internally you
404 can recover via "YAML::Tiny->errstr". Although in some cases a failed
405 "read" will also set the operating system error variable $!, not all
406 errors do and you should not rely on using the $! variable.
407 read_string $string;
409 The "read_string" method takes as argument the contents of a YAML file
410 (a YAML document) as a string and returns the "YAML::Tiny" object for
411 it.
412 write $filename
414 The "write" method generates the file content for the properties, and
415 writes it to disk to the filename specified.
416 Returns true on success or "undef" on error.
418 write_string
420 Generates the file content for the object and returns it as a string.
421 errstr
423 When an error occurs, you can retrieve the error message either from
424 the $YAML::Tiny::errstr variable, or using the "errstr()" method.
425
427 YAML::Tiny implements a number of functions to add compatibility with
428 the YAML API. These should be a drop-in replacement, except that
429 YAML::Tiny will not export functions by default, and so you will need
430 to explicitly import the functions.
431 Dump
433 my $string = Dump(list-of-Perl-data-structures);
434 Turn Perl data into YAML. This function works very much like
436 Data::Dumper::Dumper().
437 It takes a list of Perl data strucures and dumps them into a serialized
439 form.
440 It returns a string containing the YAML stream.
442 The structures can be references or plain scalars.
444 Load
446 my @documents = Load(string-containing-a-YAML-stream);
447 Turn YAML into Perl data. This is the opposite of Dump.
449 Just like Storable's thaw() function or the eval() function in relation
451 to Data::Dumper.
452 It parses a string containing a valid YAML stream into a list of Perl
454 data structures.
455 freeze() and thaw()
457 Aliases to Dump() and Load() for Storable fans. This will also allow
458 YAML::Tiny to be plugged directly into modules like POE.pm, that use
459 the freeze/thaw API for internal serialization.
460 DumpFile(filepath, list)
462 Writes the YAML stream to a file instead of just returning a string.
463 LoadFile(filepath)
465 Reads the YAML stream from a file instead of a string.
466
468 Bugs should be reported via the CPAN bug tracker at
469 http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-Tiny
471 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-Tiny>
472
474 Adam Kennedy <adamk@cpan.org>
475
477 YAML, YAML::Syck, Config::Tiny, CSS::Tiny,
478 <http://use.perl.org/~Alias/journal/29427>, <http://ali.as/>
479
481 Copyright 2006 - 2009 Adam Kennedy.
482 This program is free software; you can redistribute it and/or modify it
484 under the same terms as Perl itself.
485 The full text of the license can be found in the LICENSE file included
487 with this module.
488perl v5.12.0 2009-07-31 YAML::Tiny(3)