1YAML::Tiny(3) User Contributed Perl Documentation YAML::Tiny(3)
2
3
4
6 YAML::Tiny - Read/Write YAML files with as little code as possible
7
9 version 1.73
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
17 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
23 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
28 In exchange for this adding this extreme flexibility, it provides
29 support for only a limited subset of YAML. But the subset supported
30 contains most of the features for the more common uses of YAML.
31
33 Assuming file.yml like this:
34
35 ---
36 rootproperty: blah
37 section:
38 one: two
39 three: four
40 Foo: Bar
41 empty: ~
42
43 Read and write file.yml like this:
44
45 use YAML::Tiny;
46
47 # Open the config
48 my $yaml = YAML::Tiny->read( 'file.yml' );
49
50 # Get a reference to the first document
51 my $config = $yaml->[0];
52
53 # 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
58 # 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
63 # Save the document back to the file
64 $yaml->write( 'file.yml' );
65
66 To create a new YAML file from scratch:
67
68 # Create a new object with a single hashref document
69 my $yaml = YAML::Tiny->new( { wibble => "wobble" } );
70
71 # Add an arrayref document
72 push @$yaml, [ 'foo', 'bar', 'baz' ];
73
74 # Save both documents to a file
75 $yaml->write( 'data.yml' );
76
77 Then data.yml will contain:
78
79 ---
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
91 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
96 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
102 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
106 It only supports a very basic subset of the full YAML specification.
107
108 Usage is targeted at files like Perl's META.yml, for which a small and
109 easily-embeddable module is extremely attractive.
110
111 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
116 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
120 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
130 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
134 Returns the object on success or throws an error on failure.
135
136 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
142 Returns the object on success or throws an error on failure.
143
144 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
148 Returns true on success or throws an error on failure.
149
150 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
155 Returns true on success or throws an error on failure.
156
157 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
162 Starting with version 1.57, all errors are fatal and throw exceptions.
163
164 The $errstr variable is still set when exceptions are thrown, but
165 $errstr and the "errstr()" method are deprecated and may be removed in
166 a 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
173 Dump
174 my $string = Dump(list-of-Perl-data-structures);
175
176 Turn Perl data into YAML. This function works very much like
177 Data::Dumper::Dumper().
178
179 It takes a list of Perl data structures and dumps them into a
180 serialized form.
181
182 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
185 The structures can be references or plain scalars.
186
187 Dies on any error.
188
189 Load
190 my @data_structures = Load(string-containing-a-YAML-stream);
191
192 Turn YAML into Perl data. This is the opposite of Dump.
193
194 Just like Storable's thaw() function or the eval() function in relation
195 to Data::Dumper.
196
197 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
202 my $last_data_structure = Load(string-containing-a-YAML-stream);
203
204 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
208 Dies on any error.
209
210 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
215 DumpFile(filepath, list)
216 Writes the YAML stream to a file with UTF-8 encoding instead of just
217 returning a string.
218
219 Dies on any error.
220
221 LoadFile(filepath)
222 Reads the YAML stream from a UTF-8 encoded file instead of a string.
223
224 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
230 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
234 Terminology and chapter numbers are based on that specification.
235
236 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
242 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
246 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
250 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
254 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
258 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
264 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
267 Both line and inline comments are supported.
268
269 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
272 The use of explicit tags is not supported.
273
274 The use of "null" type scalars is supported via the ~ character.
275
276 The use of "bool" type scalars is not supported.
277
278 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
283 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
287 The use of anchors and aliases is not supported.
288
289 The use of directives is supported only for the %YAML directive.
290
291 3. Processing YAML Tiny Information
292 Processes
293
294 The YAML specification dictates three-phase serialization and three-
295 phase deserialization.
296
297 The YAML Tiny specification does not mandate any particular methodology
298 or mechanism for parsing.
299
300 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
304 Because anchors and aliases are not supported, the resulting
305 representation graph is thus directed but (unlike the main YAML
306 specification) acyclic.
307
308 Circular references/pointers are not possible, and any YAML Tiny
309 serializer detecting a circular reference should error with an
310 appropriate message.
311
312 Presentation Stream
313
314 YAML Tiny reads and write UTF-8 encoded files. Operations on strings
315 expect or produce Unicode characters not UTF-8 encoded bytes.
316
317 Loading Failure Points
318
319 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
324 4. Syntax
325 Character Set
326
327 YAML Tiny streams are processed in memory as Unicode characters and
328 read/written with UTF-8 encoding.
329
330 The escaping and unescaping of the 8-bit YAML escapes is required.
331
332 The escaping and unescaping of 16-bit and 32-bit YAML escapes is not
333 required.
334
335 Indicator Characters
336
337 Support for the "~" null/undefined indicator is required.
338
339 Implementations may represent this as appropriate for the underlying
340 language.
341
342 Support for the "-" block sequence indicator is required.
343
344 Support for the "?" mapping key indicator is not required.
345
346 Support for the ":" mapping value indicator is required.
347
348 Support for the "," flow collection indicator is not required.
349
350 Support for the "[" flow sequence indicator is not required, with one
351 exception (detailed below).
352
353 Support for the "]" flow sequence indicator is not required, with one
354 exception (detailed below).
355
356 Support for the "{" flow mapping indicator is not required, with one
357 exception (detailed below).
358
359 Support for the "}" flow mapping indicator is not required, with one
360 exception (detailed below).
361
362 Support for the "#" comment indicator is required.
363
364 Support for the "&" anchor indicator is not required.
365
366 Support for the "*" alias indicator is not required.
367
368 Support for the "!" tag indicator is not required.
369
370 Support for the "|" literal block indicator is required.
371
372 Support for the ">" folded block indicator is required.
373
374 Support for the "'" single quote indicator is required.
375
376 Support for the """ double quote indicator is required.
377
378 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
382 For example:
383
384 %YAML 1.1
385 ---
386 - A sequence with a single element
387
388 Special Exception:
389
390 To provide the ability to support empty sequences and mappings, support
391 for the constructs [] (empty sequence) and {} (empty mapping) are
392 required.
393
394 For example,
395
396 %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
406 Syntax Primitives
407
408 Other than the empty sequence and mapping cases described above, YAML
409 Tiny supports only the indentation-based block-style group of contexts.
410
411 All five scalar contexts are supported.
412
413 Indentation spaces work as per the YAML specification in all cases.
414
415 Comments work as per the YAML specification in all simple cases.
416 Support for indented multi-line comments is not required.
417
418 Separation spaces work as per the YAML specification in all cases.
419
420 YAML Tiny Character Stream
421
422 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
426 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
430 That is, all of the following should be supported.
431
432 --- #YAML:1.0
433 - foo
434
435 %YAML:1.0
436 ---
437 - foo
438
439 % YAML 1.1
440 ---
441 - foo
442
443 Support for the %TAG directive is not required.
444
445 Support for additional directives is not required.
446
447 Support for the document boundary marker "---" is required.
448
449 Support for the document boundary market "..." is not required.
450
451 If necessary, a document boundary should simply by indicated with a
452 "---" marker, with not preceding "..." marker.
453
454 Support for empty streams (containing no documents) is required.
455
456 Support for implicit document starts is required.
457
458 That is, the following must be equivalent.
459
460 # Full form
461 %YAML 1.1
462 ---
463 foo: bar
464
465 # Implicit form
466 foo: bar
467
468 Nodes
469
470 Support for nodes optional anchor and tag properties is not required.
471
472 Support for node anchors is not required.
473
474 Support for node tags is not required.
475
476 Support for alias nodes is not required.
477
478 Support for flow nodes is not required.
479
480 Support for block nodes is required.
481
482 Scalar Styles
483
484 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
488 Support for multi-line scalar documents starting on the header is not
489 required.
490
491 Support for the chomping indicators on multi-line scalar styles is
492 required.
493
494 Collection Styles
495
496 Support for block-style sequences is required.
497
498 Support for flow-style sequences is not required.
499
500 Support for block-style mappings is required.
501
502 Support for flow-style mappings is not required.
503
504 Both sequences and mappings should be able to be arbitrarily nested.
505
506 Support for plain-style mapping keys is required.
507
508 Support for quoted keys in mappings is not required.
509
510 Support for "?"-indicated explicit keys is not required.
511
512 Here endeth the specification.
513
514 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
518 That is, in some contexts is important that 3 the number is distinctive
519 from "3" the string.
520
521 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
529 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-Tiny>
530
532 Adam Kennedy <adamk@cpan.org>
533
535 · YAML
536
537 · YAML::Syck
538
539 · Config::Tiny
540
541 · CSS::Tiny
542
543 · <http://use.perl.org/use.perl.org/_Alias/journal/29427.html>
544
545 · <http://ali.as/>
546
548 Copyright 2006 - 2013 Adam Kennedy.
549
550 This program is free software; you can redistribute it and/or modify it
551 under the same terms as Perl itself.
552
553 The full text of the license can be found in the LICENSE file included
554 with this module.
555
556
557
558perl v5.28.1 2018-02-21 YAML::Tiny(3)