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 version 1.74
10
12 The YAML specification is huge. Really, really huge. It contains all
13 the functionality of XML, except with flexibility and choice, which
14 makes it easier to read, but with a formal specification that is more
15 complex than XML.
16 The original pure-Perl implementation YAML costs just over 4 megabytes
18 of memory to load. Just like with Windows .ini files (3 meg to load)
19 and CSS (3.5 meg to load) the situation is just asking for a YAML::Tiny
20 module, an incomplete but correct and usable subset of the
21 functionality, in as little code as possible.
22 Like the other "::Tiny" modules, YAML::Tiny has no non-core
24 dependencies, does not require a compiler to install, is back-
25 compatible to Perl v5.8.1, and can be inlined into other modules if
26 needed.
27 In exchange for adding this extreme flexibility, it provides support
29 for only a limited subset of YAML. But the subset supported contains
30 most of the features for the more common uses of YAML.
31
33 Assuming file.yml like this:
34 ---
36 rootproperty: blah
37 section:
38 one: two
39 three: four
40 Foo: Bar
41 empty: ~
42 Read and write file.yml like this:
44 use YAML::Tiny;
46 # Open the config
48 my $yaml = YAML::Tiny->read( 'file.yml' );
49 # Get a reference to the first document
51 my $config = $yaml->[0];
52 # Or read properties directly
54 my $root = $yaml->[0]->{rootproperty};
55 my $one = $yaml->[0]->{section}->{one};
56 my $Foo = $yaml->[0]->{section}->{Foo};
57 # Change data directly
59 $yaml->[0]->{newsection} = { this => 'that' }; # Add a section
60 $yaml->[0]->{section}->{Foo} = 'Not Bar!'; # Change a value
61 delete $yaml->[0]->{section}; # Delete a value
62 # Save the document back to the file
64 $yaml->write( 'file.yml' );
65 To create a new YAML file from scratch:
67 # Create a new object with a single hashref document
69 my $yaml = YAML::Tiny->new( { wibble => "wobble" } );
70 # Add an arrayref document
72 push @$yaml, [ 'foo', 'bar', 'baz' ];
73 # Save both documents to a file
75 $yaml->write( 'data.yml' );
76 Then data.yml will contain:
78 ---
80 wibble: wobble
81 ---
82 - foo
83 - bar
84 - baz
85
87 YAML::Tiny is a perl class for reading and writing YAML-style files,
88 written with as little code as possible, reducing load time and memory
89 overhead.
90 Most of the time it is accepted that Perl applications use a lot of
92 memory and modules. The ::Tiny family of modules is specifically
93 intended to provide an ultralight and zero-dependency alternative to
94 many more-thorough standard modules.
95 This module is primarily for reading human-written files (like simple
97 config files) and generating very simple human-readable files. Note
98 that I said human-readable and not geek-readable. The sort of files
99 that your average manager or secretary should be able to look at and
100 make sense of.
101 YAML::Tiny does not generate comments, it won't necessarily preserve
103 the order of your hashes, and it will normalise if reading in and
104 writing out again.
105 It only supports a very basic subset of the full YAML specification.
107 Usage is targeted at files like Perl's META.yml, for which a small and
109 easily-embeddable module is extremely attractive.
110 Features will only be added if they are human readable, and can be
112 written in a few lines of code. Please don't be offended if your
113 request is refused. Someone has to draw the line, and for YAML::Tiny
114 that someone is me.
115 If you need something with more power move up to YAML (7 megabytes of
117 memory overhead) or YAML::XS (6 megabytes memory overhead and requires
118 a C compiler).
119 To restate, YAML::Tiny does not preserve your comments, whitespace, or
121 the order of your YAML data. But it should round-trip from Perl
122 structure to file and back again just fine.
123
125 new
126 The constructor "new" creates a "YAML::Tiny" object as a blessed array
127 reference. Any arguments provided are taken as separate documents to
128 be serialized.
129 read $filename
131 The "read" constructor reads a YAML file from a file name, and returns
132 a new "YAML::Tiny" object containing the parsed content.
133 Returns the object on success or throws an error on failure.
135 read_string $string;
137 The "read_string" constructor reads YAML data from a character string,
138 and returns a new "YAML::Tiny" object containing the parsed content.
139 If you have read the string from a file yourself, be sure that you have
140 correctly decoded it into characters first.
141 Returns the object on success or throws an error on failure.
143 write $filename
145 The "write" method generates the file content for the properties, and
146 writes it to disk using UTF-8 encoding to the filename specified.
147 Returns true on success or throws an error on failure.
149 write_string
151 Generates the file content for the object and returns it as a character
152 string. This may contain non-ASCII characters and should be encoded
153 before writing it to a file.
154 Returns true on success or throws an error on failure.
156 errstr (DEPRECATED)
158 Prior to version 1.57, some errors were fatal and others were available
159 only via the $YAML::Tiny::errstr variable, which could be accessed via
160 the errstr() method.
161 Starting with version 1.57, all errors are fatal and throw exceptions.
163 The $errstr variable is still set when exceptions are thrown, but
165 $errstr and the errstr() method are deprecated and may be removed in a
166 future release. The first use of errstr() will issue a deprecation
167 warning.
168
170 YAML::Tiny implements a number of functions to add compatibility with
171 the YAML API. These should be a drop-in replacement.
172 Dump
174 my $string = Dump(list-of-Perl-data-structures);
175 Turn Perl data into YAML. This function works very much like
177 Data::Dumper::Dumper().
178 It takes a list of Perl data structures and dumps them into a
180 serialized form.
181 It returns a character string containing the YAML stream. Be sure to
183 encode it as UTF-8 before serializing to a file or socket.
184 The structures can be references or plain scalars.
186 Dies on any error.
188 Load
190 my @data_structures = Load(string-containing-a-YAML-stream);
191 Turn YAML into Perl data. This is the opposite of Dump.
193 Just like Storable's thaw() function or the eval() function in relation
195 to Data::Dumper.
196 It parses a character string containing a valid YAML stream into a list
198 of Perl data structures representing the individual YAML documents. Be
199 sure to decode the character string correctly if the string came from
200 a file or socket.
201 my $last_data_structure = Load(string-containing-a-YAML-stream);
203 For consistency with YAML.pm, when Load is called in scalar context, it
205 returns the data structure corresponding to the last of the YAML
206 documents found in the input stream.
207 Dies on any error.
209 freeze() and thaw()
211 Aliases to Dump() and Load() for Storable fans. This will also allow
212 YAML::Tiny to be plugged directly into modules like POE.pm, that use
213 the freeze/thaw API for internal serialization.
214 DumpFile(filepath, list)
216 Writes the YAML stream to a file with UTF-8 encoding instead of just
217 returning a string.
218 Dies on any error.
220 LoadFile(filepath)
222 Reads the YAML stream from a UTF-8 encoded file instead of a string.
223 Dies on any error.
225
227 This section of the documentation provides a specification for "YAML
228 Tiny", a subset of the YAML specification.
229 It is based on and described comparatively to the YAML 1.1 Working
231 Draft 2004-12-28 specification, located at
232 <http://yaml.org/spec/current.html>.
233 Terminology and chapter numbers are based on that specification.
235 1. Introduction and Goals
237 The purpose of the YAML Tiny specification is to describe a useful
238 subset of the YAML specification that can be used for typical document-
239 oriented use cases such as configuration files and simple data
240 structure dumps.
241 Many specification elements that add flexibility or extensibility are
243 intentionally removed, as is support for complex data structures, class
244 and object-orientation.
245 In general, the YAML Tiny language targets only those data structures
247 available in JSON, with the additional limitation that only simple keys
248 are supported.
249 As a result, all possible YAML Tiny documents should be able to be
251 transformed into an equivalent JSON document, although the reverse is
252 not necessarily true (but will be true in simple cases).
253 As a result of these simplifications the YAML Tiny specification should
255 be implementable in a (relatively) small amount of code in any language
256 that supports Perl Compatible Regular Expressions (PCRE).
257 2. Introduction
259 YAML Tiny supports three data structures. These are scalars (in a
260 variety of forms), block-form sequences and block-form mappings. Flow-
261 style sequences and mappings are not supported, with some minor
262 exceptions detailed later.
263 The use of three dashes "---" to indicate the start of a new document
265 is supported, and multiple documents per file/stream is allowed.
266 Both line and inline comments are supported.
268 Scalars are supported via the plain style, single quote and double
270 quote, as well as literal-style and folded-style multi-line scalars.
271 The use of explicit tags is not supported.
273 The use of "null" type scalars is supported via the ~ character.
275 The use of "bool" type scalars is not supported.
277 However, serializer implementations should take care to explicitly
279 escape strings that match a "bool" keyword in the following set to
280 prevent other implementations that do support "bool" accidentally
281 reading a string as a boolean
282 y|Y|yes|Yes|YES|n|N|no|No|NO
284 |true|True|TRUE|false|False|FALSE
285 |on|On|ON|off|Off|OFF
286 The use of anchors and aliases is not supported.
288 The use of directives is supported only for the %YAML directive.
290 3. Processing YAML Tiny Information
292 Processes
293 The YAML specification dictates three-phase serialization and three-
295 phase deserialization.
296 The YAML Tiny specification does not mandate any particular methodology
298 or mechanism for parsing.
299 Any compliant parser is only required to parse a single document at a
301 time. The ability to support streaming documents is optional and most
302 likely non-typical.
303 Because anchors and aliases are not supported, the resulting
305 representation graph is thus directed but (unlike the main YAML
306 specification) acyclic.
307 Circular references/pointers are not possible, and any YAML Tiny
309 serializer detecting a circular reference should error with an
310 appropriate message.
311 Presentation Stream
313 YAML Tiny reads and write UTF-8 encoded files. Operations on strings
315 expect or produce Unicode characters not UTF-8 encoded bytes.
316 Loading Failure Points
318 YAML Tiny parsers and emitters are not expected to recover from, or
320 adapt to, errors. The specific error modality of any implementation is
321 not dictated (return codes, exceptions, etc.) but is expected to be
322 consistent.
323 4. Syntax
325 Character Set
326 YAML Tiny streams are processed in memory as Unicode characters and
328 read/written with UTF-8 encoding.
329 The escaping and unescaping of the 8-bit YAML escapes is required.
331 The escaping and unescaping of 16-bit and 32-bit YAML escapes is not
333 required.
334 Indicator Characters
336 Support for the "~" null/undefined indicator is required.
338 Implementations may represent this as appropriate for the underlying
340 language.
341 Support for the "-" block sequence indicator is required.
343 Support for the "?" mapping key indicator is not required.
345 Support for the ":" mapping value indicator is required.
347 Support for the "," flow collection indicator is not required.
349 Support for the "[" flow sequence indicator is not required, with one
351 exception (detailed below).
352 Support for the "]" flow sequence indicator is not required, with one
354 exception (detailed below).
355 Support for the "{" flow mapping indicator is not required, with one
357 exception (detailed below).
358 Support for the "}" flow mapping indicator is not required, with one
360 exception (detailed below).
361 Support for the "#" comment indicator is required.
363 Support for the "&" anchor indicator is not required.
365 Support for the "*" alias indicator is not required.
367 Support for the "!" tag indicator is not required.
369 Support for the "|" literal block indicator is required.
371 Support for the ">" folded block indicator is required.
373 Support for the "'" single quote indicator is required.
375 Support for the """ double quote indicator is required.
377 Support for the "%" directive indicator is required, but only for the
379 special case of a %YAML version directive before the "---" document
380 header, or on the same line as the document header.
381 For example:
383 %YAML 1.1
385 ---
386 - A sequence with a single element
387 Special Exception:
389 To provide the ability to support empty sequences and mappings, support
391 for the constructs [] (empty sequence) and {} (empty mapping) are
392 required.
393 For example,
395 %YAML 1.1
397 # A document consisting of only an empty mapping
398 --- {}
399 # A document consisting of only an empty sequence
400 --- []
401 # A document consisting of an empty mapping within a sequence
402 - foo
403 - {}
404 - bar
405 Syntax Primitives
407 Other than the empty sequence and mapping cases described above, YAML
409 Tiny supports only the indentation-based block-style group of contexts.
410 All five scalar contexts are supported.
412 Indentation spaces work as per the YAML specification in all cases.
414 Comments work as per the YAML specification in all simple cases.
416 Support for indented multi-line comments is not required.
417 Separation spaces work as per the YAML specification in all cases.
419 YAML Tiny Character Stream
421 The only directive supported by the YAML Tiny specification is the
423 %YAML language/version identifier. Although detected, this directive
424 will have no control over the parsing itself.
425 The parser must recognise both the YAML 1.0 and YAML 1.1+ formatting of
427 this directive (as well as the commented form, although no explicit
428 code should be needed to deal with this case, being a comment anyway)
429 That is, all of the following should be supported.
431 --- #YAML:1.0
433 - foo
434 %YAML:1.0
436 ---
437 - foo
438 % YAML 1.1
440 ---
441 - foo
442 Support for the %TAG directive is not required.
444 Support for additional directives is not required.
446 Support for the document boundary marker "---" is required.
448 Support for the document boundary market "..." is not required.
450 If necessary, a document boundary should simply be indicated with a
452 "---" marker, with no preceding "..." marker.
453 Support for empty streams (containing no documents) is required.
455 Support for implicit document starts is required.
457 That is, the following must be equivalent.
459 # Full form
461 %YAML 1.1
462 ---
463 foo: bar
464 # Implicit form
466 foo: bar
467 Nodes
469 Support for nodes optional anchor and tag properties is not required.
471 Support for node anchors is not required.
473 Support for node tags is not required.
475 Support for alias nodes is not required.
477 Support for flow nodes is not required.
479 Support for block nodes is required.
481 Scalar Styles
483 Support for all five scalar styles is required as per the YAML
485 specification, although support for quoted scalars spanning more than
486 one line is not required.
487 Support for multi-line scalar documents starting on the header is not
489 required.
490 Support for the chomping indicators on multi-line scalar styles is
492 required.
493 Collection Styles
495 Support for block-style sequences is required.
497 Support for flow-style sequences is not required.
499 Support for block-style mappings is required.
501 Support for flow-style mappings is not required.
503 Both sequences and mappings should be able to be arbitrarily nested.
505 Support for plain-style mapping keys is required.
507 Support for quoted keys in mappings is not required.
509 Support for "?"-indicated explicit keys is not required.
511 Here endeth the specification.
513 Additional Perl-Specific Notes
515 For some Perl applications, it's important to know if you really have a
516 number and not a string.
517 That is, in some contexts is important that 3 the number is distinctive
519 from "3" the string.
520 Because even Perl itself is not trivially able to understand the
522 difference (certainly without XS-based modules) Perl implementations of
523 the YAML Tiny specification are not required to retain the
524 distinctiveness of 3 vs "3".
525
527 Bugs should be reported via the CPAN bug tracker at
528 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-Tiny>
530
532 Adam Kennedy <adamk@cpan.org>
533
535 • YAML
536 • YAML::Syck
538 • Config::Tiny
540 • CSS::Tiny
542 • <http://use.perl.org/use.perl.org/_Alias/journal/29427.html>
544 • <http://ali.as/>
546
548 Copyright 2006 - 2013 Adam Kennedy.
549 This program is free software; you can redistribute it and/or modify it
551 under the same terms as Perl itself.
552 The full text of the license can be found in the LICENSE file included
554 with this module.
555perl v5.38.0 2023-07-21 YAML::Tiny(3)