1YAML::Tiny(3)         User Contributed Perl Documentation        YAML::Tiny(3)
2
3
4

NAME

6       YAML::Tiny - Read/Write YAML files with as little code as possible
7

VERSION

9       version 1.73
10

PREAMBLE

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

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

FUNCTIONS

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

YAML TINY SPECIFICATION

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

SUPPORT

527       Bugs should be reported via the CPAN bug tracker at
528
529       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML-Tiny>
530

AUTHOR

532       Adam Kennedy <adamk@cpan.org>
533

SEE ALSO

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.36.0                      2022-07-22                     YAML::Tiny(3)
Impressum