local-lib5/man/man3/YAML::Tiny.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "YAML::Tiny 3"
 132 .TH YAML::Tiny 3 "2009-07-31" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 YAML::Tiny \- Read/Write YAML files with as little code as possible
 135 .SH "PREAMBLE"
 136 .IX Header "PREAMBLE"
 137 The \s-1YAML\s0 specification is huge. Really, \fBreally\fR huge. It contains all the
 138 functionality of \s-1XML\s0, except with flexibility and choice, which makes it
 139 easier to read, but with a formal specification that is more complex than
 140 \&\s-1XML\s0.
 141 .PP
 142 The original pure-Perl implementation \s-1YAML\s0 costs just over 4 megabytes of
 143 memory to load. Just like with Windows .ini files (3 meg to load) and \s-1CSS\s0
 144 (3.5 meg to load) the situation is just asking for a \fBYAML::Tiny\fR module, an
 145 incomplete but correct and usable subset of the functionality, in as little
 146 code as possible.
 147 .PP
 148 Like the other \f(CW\*(C`::Tiny\*(C'\fR modules, YAML::Tiny will have no non-core
 149 dependencies, not require a compiler, and be back-compatible to at least
 150 perl 5.005_03, and ideally 5.004.
 151 .SH "SYNOPSIS"
 152 .IX Header "SYNOPSIS"
 153 .Vb 2
 154 \&    #############################################
 155 \&    # In your file
 156 .Ve
 157 .PP
 158 .Vb 7
 159 \&    \-\-\-
 160 \&    rootproperty: blah
 161 \&    section:
 162 \&      one: two
 163 \&      three: four
 164 \&      Foo: Bar
 165 \&      empty: ~
 166 .Ve
 167 .PP
 168 .Vb 2
 169 \&    #############################################
 170 \&    # In your program
 171 .Ve
 172 .PP
 173 .Vb 1
 174 \&    use YAML::Tiny;
 175 .Ve
 176 .PP
 177 .Vb 2
 178 \&    # Create a YAML file
 179 \&    my $yaml = YAML::Tiny\->new;
 180 .Ve
 181 .PP
 182 .Vb 2
 183 \&    # Open the config
 184 \&    $yaml = YAML::Tiny\->read( 'file.yml' );
 185 .Ve
 186 .PP
 187 .Vb 4
 188 \&    # Reading properties
 189 \&    my $root = $yaml\->[0]\->{rootproperty};
 190 \&    my $one  = $yaml\->[0]\->{section}\->{one};
 191 \&    my $Foo  = $yaml\->[0]\->{section}\->{Foo};
 192 .Ve
 193 .PP
 194 .Vb 4
 195 \&    # Changing data
 196 \&    $yaml\->[0]\->{newsection} = { this => 'that' }; # Add a section
 197 \&    $yaml\->[0]\->{section}\->{Foo} = 'Not Bar!';     # Change a value
 198 \&    delete $yaml\->[0]\->{section};                  # Delete a value or section
 199 .Ve
 200 .PP
 201 .Vb 2
 202 \&    # Add an entire document
 203 \&    $yaml\->[1] = [ 'foo', 'bar', 'baz' ];
 204 .Ve
 205 .PP
 206 .Vb 2
 207 \&    # Save the file
 208 \&    $yaml\->write( 'file.conf' );
 209 .Ve
 210 .SH "DESCRIPTION"
 211 .IX Header "DESCRIPTION"
 212 \&\fBYAML::Tiny\fR is a perl class for reading and writing YAML-style files,
 213 written with as little code as possible, reducing load time and memory
 214 overhead.
 215 .PP
 216 Most of the time it is accepted that Perl applications use a lot
 217 of memory and modules. The \fB::Tiny\fR family of modules is specifically
 218 intended to provide an ultralight and zero-dependency alternative to
 219 many more-thorough standard modules.
 220 .PP
 221 This module is primarily for reading human-written files (like simple
 222 config files) and generating very simple human-readable files. Note that
 223 I said \fBhuman-readable\fR and not \fBgeek-readable\fR. The sort of files that
 224 your average manager or secretary should be able to look at and make
 225 sense of.
 226 .PP
 227 YAML::Tiny does not generate comments, it won't necesarily preserve the
 228 order of your hashes, and it will normalise if reading in and writing out
 229 again.
 230 .PP
 231 It only supports a very basic subset of the full \s-1YAML\s0 specification.
 232 .PP
 233 Usage is targetted at files like Perl's \s-1META\s0.yml, for which a small and
 234 easily-embeddable module is extremely attractive.
 235 .PP
 236 Features will only be added if they are human readable, and can be written
 237 in a few lines of code. Please don't be offended if your request is
 238 refused. Someone has to draw the line, and for YAML::Tiny that someone is me.
 239 .PP
 240 If you need something with more power move up to \s-1YAML\s0 (4 megabytes of
 241 memory overhead) or YAML::Syck (275k, but requires libsyck and a C
 242 compiler).
 243 .PP
 244 To restate, YAML::Tiny does \fBnot\fR preserve your comments, whitespace, or
 245 the order of your \s-1YAML\s0 data. But it should round-trip from Perl structure
 246 to file and back again just fine.
 247 .SH "YAML TINY SPECIFICATION"
 248 .IX Header "YAML TINY SPECIFICATION"
 249 This section of the documentation provides a specification for \*(L"\s-1YAML\s0 Tiny\*(R",
 250 a subset of the \s-1YAML\s0 specification.
 251 .PP
 252 It is based on and described comparatively to the \s-1YAML\s0 1.1  Working Draft
 253 2004\-12\-28 specification, located at <http://yaml.org/spec/current.html>.
 254 .PP
 255 Terminology and chapter numbers are based on that specification.
 256 .Sh "1. Introduction and Goals"
 257 .IX Subsection "1. Introduction and Goals"
 258 The purpose of the \s-1YAML\s0 Tiny specification is to describe a useful subset of
 259 the \s-1YAML\s0 specification that can be used for typical document-oriented
 260 uses such as configuration files and simple data structure dumps.
 261 .PP
 262 Many specification elements that add flexibility or extensibility are
 263 intentionally removed, as is support for complex datastructures, class
 264 and object\-orientation.
 265 .PP
 266 In general, \s-1YAML\s0 Tiny targets only those data structures available in
 267 \&\s-1JSON\s0, with the additional limitation that only simple keys are supported.
 268 .PP
 269 As a result, all possible \s-1YAML\s0 Tiny documents should be able to be
 270 transformed into an equivalent \s-1JSON\s0 document, although the reverse is
 271 not necesarily true (but will be true in simple cases).
 272 .PP
 273 As a result of these simplifications the \s-1YAML\s0 Tiny specification should
 274 be implementable in a relatively small amount of code in any language
 275 that supports Perl Compatible Regular Expressions (\s-1PCRE\s0).
 276 .Sh "2. Introduction"
 277 .IX Subsection "2. Introduction"
 278 \&\s-1YAML\s0 Tiny supports three data structures. These are scalars (in a variety
 279 of forms), block-form sequences and block-form mappings. Flow-style
 280 sequences and mappings are not supported, with some minor exceptions
 281 detailed later.
 282 .PP
 283 The use of three dashes \*(L"\-\-\-\*(R" to indicate the start of a new document is
 284 supported, and multiple documents per file/stream is allowed.
 285 .PP
 286 Both line and inline comments are supported.
 287 .PP
 288 Scalars are supported via the plain style, single quote and double quote,
 289 as well as literal-style and folded-style multi-line scalars.
 290 .PP
 291 The use of tags is not supported.
 292 .PP
 293 The use of anchors and aliases is not supported.
 294 .PP
 295 The use of directives is supported only for the \f(CW%YAML\fR directive.
 296 .Sh "3. Processing \s-1YAML\s0 Tiny Information"
 297 .IX Subsection "3. Processing YAML Tiny Information"
 298 \&\fBProcesses\fR
 299 .PP
 300 The \s-1YAML\s0 specification dictates three-phase serialization and three-phase
 301 deserialization.
 302 .PP
 303 The \s-1YAML\s0 Tiny specification does not mandate any particular methodology
 304 or mechanism for parsing.
 305 .PP
 306 Any compliant parser is only required to parse a single document at a
 307 time. The ability to support streaming documents is optional and most
 308 likely non\-typical.
 309 .PP
 310 Because anchors and aliases are not supported, the resulting representation
 311 graph is thus directed but (unlike the main \s-1YAML\s0 specification) \fBacyclic\fR.
 312 .PP
 313 Circular references/pointers are not possible, and any \s-1YAML\s0 Tiny serializer
 314 detecting a circulars should error with an appropriate message.
 315 .PP
 316 \&\fBPresentation Stream\fR
 317 .PP
 318 \&\s-1YAML\s0 Tiny is notionally unicode, but support for unicode is required if the
 319 underlying language or system being used to implement a parser does not
 320 support Unicode. If unicode is encountered in this case an error should be
 321 returned.
 322 .PP
 323 \&\fBLoading Failure Points\fR
 324 .PP
 325 \&\s-1YAML\s0 Tiny parsers and emitters are not expected to recover from adapt to
 326 errors. The specific error modality of any implementation is not dictated
 327 (return codes, exceptions, etc) but is expected to be consistant.
 328 .Sh "4. Syntax"
 329 .IX Subsection "4. Syntax"
 330 \&\fBCharacter Set\fR
 331 .PP
 332 \&\s-1YAML\s0 Tiny streams are implemented primarily using the \s-1ASCII\s0 character set,
 333 although the use of Unicode inside strings is allowed if support by the
 334 implementation.
 335 .PP
 336 Specific \s-1YAML\s0 Tiny encoded document types aiming for maximum compatibility
 337 should restrict themselves to \s-1ASCII\s0.
 338 .PP
 339 The escaping and unescaping of the 8\-bit \s-1YAML\s0 escapes is required.
 340 .PP
 341 The escaping and unescaping of 16\-bit and 32\-bit \s-1YAML\s0 escapes is not
 342 required.
 343 .PP
 344 \&\fBIndicator Characters\fR
 345 .PP
 346 Support for the \*(L"~\*(R" null/undefined indicator is required.
 347 .PP
 348 Implementations may represent this as appropriate for the underlying
 349 language.
 350 .PP
 351 Support for the \*(L"\-\*(R" block sequence indicator is required.
 352 .PP
 353 Support for the \*(L"?\*(R" mapping key indicator is \fBnot\fR required.
 354 .PP
 355 Support for the \*(L":\*(R" mapping value indicator is required.
 356 .PP
 357 Support for the \*(L",\*(R" flow collection indicator is \fBnot\fR required.
 358 .PP
 359 Support for the \*(L"[\*(R" flow sequence indicator is \fBnot\fR required, with
 360 one exception (detailed below).
 361 .PP
 362 Support for the \*(L"]\*(R" flow sequence indicator is \fBnot\fR required, with
 363 one exception (detailed below).
 364 .PP
 365 Support for the \*(L"{\*(R" flow mapping indicator is \fBnot\fR required, with
 366 one exception (detailed below).
 367 .PP
 368 Support for the \*(L"}\*(R" flow mapping indicator is \fBnot\fR required, with
 369 one exception (detailed below).
 370 .PP
 371 Support for the \*(L"#\*(R" comment indicator is required.
 372 .PP
 373 Support for the \*(L"&\*(R" anchor indicator is \fBnot\fR required.
 374 .PP
 375 Support for the \*(L"*\*(R" alias indicator is \fBnot\fR required.
 376 .PP
 377 Support for the \*(L"!\*(R" tag indicator is \fBnot\fR required.
 378 .PP
 379 Support for the \*(L"|\*(R" literal block indicator is required.
 380 .PP
 381 Support for the \*(L">\*(R" folded block indicator is required.
 382 .PP
 383 Support for the \*(L"'\*(R" single quote indicator is required.
 384 .PP
 385 Support for the """ double quote indicator is required.
 386 .PP
 387 Support for the \*(L"%\*(R" directive indicator is required, but only
 388 for the special case of a \f(CW%YAML\fR version directive before the
 389 \&\*(L"\-\-\-\*(R" document header, or on the same line as the document header.
 390 .PP
 391 For example:
 392 .PP
 393 .Vb 3
 394 \&  %YAML 1.1
 395 \&  \-\-\-
 396 \&  \- A sequence with a single element
 397 .Ve
 398 .PP
 399 Special Exception:
 400 .PP
 401 To provide the ability to support empty sequences
 402 and mappings, support for the constructs [] (empty sequence) and {}
 403 (empty mapping) are required.
 404 .PP
 405 For example,
 406 .PP
 407 .Vb 9
 408 \&  %YAML 1.1
 409 \&  # A document consisting of only an empty mapping
 410 \&  \-\-\- {}
 411 \&  # A document consisting of only an empty sequence
 412 \&  \-\-\- []
 413 \&  # A document consisting of an empty mapping within a sequence
 414 \&  \- foo
 415 \&  \- {}
 416 \&  \- bar
 417 .Ve
 418 .PP
 419 \&\fBSyntax Primitives\fR
 420 .PP
 421 Other than the empty sequence and mapping cases described above, \s-1YAML\s0 Tiny
 422 supports only the indentation-based block-style group of contexts.
 423 .PP
 424 All five scalar contexts are supported.
 425 .PP
 426 Indentation spaces work as per the \s-1YAML\s0 specification in all cases.
 427 .PP
 428 Comments work as per the \s-1YAML\s0 specification in all simple cases.
 429 Support for indented multi-line comments is \fBnot\fR required.
 430 .PP
 431 Seperation spaces work as per the \s-1YAML\s0 specification in all cases.
 432 .PP
 433 \&\fB\s-1YAML\s0 Tiny Character Stream\fR
 434 .PP
 435 The only directive supported by the \s-1YAML\s0 Tiny specification is the
 436 \&\f(CW%YAML\fR language/version identifier. Although detected, this directive
 437 will have no control over the parsing itself.
 438 .PP
 439 The parser must recognise both the \s-1YAML\s0 1.0 and \s-1YAML\s0 1.1+ formatting
 440 of this directive (as well as the commented form, although no explicit
 441 code should be needed to deal with this case, being a comment anyway)
 442 .PP
 443 That is, all of the following should be supported.
 444 .PP
 445 .Vb 2
 446 \&  \-\-\- #YAML:1.0
 447 \&  \- foo
 448 .Ve
 449 .PP
 450 .Vb 3
 451 \&  %YAML:1.0
 452 \&  \-\-\-
 453 \&  \- foo
 454 .Ve
 455 .PP
 456 .Vb 3
 457 \&  % YAML 1.1
 458 \&  \-\-\-
 459 \&  \- foo
 460 .Ve
 461 .PP
 462 Support for the \f(CW%TAG\fR directive is \fBnot\fR required.
 463 .PP
 464 Support for additional directives is \fBnot\fR required.
 465 .PP
 466 Support for the document boundary marker \*(L"\-\-\-\*(R" is required.
 467 .PP
 468 Support for the document boundary market \*(L"...\*(R" is \fBnot\fR required.
 469 .PP
 470 If necesary, a document boundary should simply by indicated with a
 471 \&\*(L"\-\-\-\*(R" marker, with not preceding \*(L"...\*(R" marker.
 472 .PP
 473 Support for empty streams (containing no documents) is required.
 474 .PP
 475 Support for implicit document starts is required.
 476 .PP
 477 That is, the following must be equivalent.
 478 .PP
 479 .Vb 4
 480 \& # Full form
 481 \& %YAML 1.1
 482 \& \-\-\-
 483 \& foo: bar
 484 .Ve
 485 .PP
 486 .Vb 2
 487 \& # Implicit form
 488 \& foo: bar
 489 .Ve
 490 .PP
 491 \&\fBNodes\fR
 492 .PP
 493 Support for nodes optional anchor and tag properties are \fBnot\fR required.
 494 .PP
 495 Support for node anchors is \fBnot\fR required.
 496 .PP
 497 Supprot for node tags is \fBnot\fR required.
 498 .PP
 499 Support for alias nodes is \fBnot\fR required.
 500 .PP
 501 Support for flow nodes is \fBnot\fR required.
 502 .PP
 503 Support for block nodes is required.
 504 .PP
 505 \&\fBScalar Styles\fR
 506 .PP
 507 Support for all five scalar styles are required as per the \s-1YAML\s0
 508 specification, although support for quoted scalars spanning more
 509 than one line is \fBnot\fR required.
 510 .PP
 511 Support for the chomping indicators on multi-line scalar styles
 512 is required.
 513 .PP
 514 \&\fBCollection Styles\fR
 515 .PP
 516 Support for block-style sequences is required.
 517 .PP
 518 Support for flow-style sequences is \fBnot\fR required.
 519 .PP
 520 Support for block-style mappings is required.
 521 .PP
 522 Support for flow-style mappings is \fBnot\fR required.
 523 .PP
 524 Both sequences and mappings should be able to be arbitrarily
 525 nested.
 526 .PP
 527 Support for plain-style mapping keys is required.
 528 .PP
 529 Support for quoted keys in mappings is \fBnot\fR required.
 530 .PP
 531 Support for \*(L"?\*(R"\-indicated explicit keys is \fBnot\fR required.
 532 .PP
 533 Here endeth the specification.
 534 .Sh "Additional Perl-Specific Notes"
 535 .IX Subsection "Additional Perl-Specific Notes"
 536 For some Perl applications, it's important to know if you really have a
 537 number and not a string.
 538 .PP
 539 That is, in some contexts is important that 3 the number is distinctive
 540 from \*(L"3\*(R" the string.
 541 .PP
 542 Because even Perl itself is not trivially able to understand the difference
 543 (certainly without XS-based modules) Perl implementations of the \s-1YAML\s0 Tiny
 544 specification are not required to retain the distinctiveness of 3 vs \*(L"3\*(R".
 545 .SH "METHODS"
 546 .IX Header "METHODS"
 547 .Sh "new"
 548 .IX Subsection "new"
 549 The constructor \f(CW\*(C`new\*(C'\fR creates and returns an empty \f(CW\*(C`YAML::Tiny\*(C'\fR object.
 550 .ie n .Sh "read $filename"
 551 .el .Sh "read \f(CW$filename\fP"
 552 .IX Subsection "read $filename"
 553 The \f(CW\*(C`read\*(C'\fR constructor reads a \s-1YAML\s0 file, and returns a new
 554 \&\f(CW\*(C`YAML::Tiny\*(C'\fR object containing the contents of the file.
 555 .PP
 556 Returns the object on success, or \f(CW\*(C`undef\*(C'\fR on error.
 557 .PP
 558 When \f(CW\*(C`read\*(C'\fR fails, \f(CW\*(C`YAML::Tiny\*(C'\fR sets an error message internally
 559 you can recover via \f(CW\*(C`YAML::Tiny\->errstr\*(C'\fR. Although in \fBsome\fR
 560 cases a failed \f(CW\*(C`read\*(C'\fR will also set the operating system error
 561 variable \f(CW$!\fR, not all errors do and you should not rely on using
 562 the \f(CW$!\fR variable.
 563 .ie n .Sh "read_string $string;"
 564 .el .Sh "read_string \f(CW$string\fP;"
 565 .IX Subsection "read_string $string;"
 566 The \f(CW\*(C`read_string\*(C'\fR method takes as argument the contents of a \s-1YAML\s0 file
 567 (a \s-1YAML\s0 document) as a string and returns the \f(CW\*(C`YAML::Tiny\*(C'\fR object for
 568 it.
 569 .ie n .Sh "write $filename"
 570 .el .Sh "write \f(CW$filename\fP"
 571 .IX Subsection "write $filename"
 572 The \f(CW\*(C`write\*(C'\fR method generates the file content for the properties, and
 573 writes it to disk to the filename specified.
 574 .PP
 575 Returns true on success or \f(CW\*(C`undef\*(C'\fR on error.
 576 .Sh "write_string"
 577 .IX Subsection "write_string"
 578 Generates the file content for the object and returns it as a string.
 579 .Sh "errstr"
 580 .IX Subsection "errstr"
 581 When an error occurs, you can retrieve the error message either from the
 582 \&\f(CW$YAML::Tiny::errstr\fR variable, or using the \f(CW\*(C`errstr()\*(C'\fR method.
 583 .SH "FUNCTIONS"
 584 .IX Header "FUNCTIONS"
 585 YAML::Tiny implements a number of functions to add compatibility with
 586 the \s-1YAML\s0 \s-1API\s0. These should be a drop-in replacement, except that
 587 YAML::Tiny will \fBnot\fR export functions by default, and so you will need
 588 to explicitly import the functions.
 589 .Sh "Dump"
 590 .IX Subsection "Dump"
 591 .Vb 1
 592 \&  my $string = Dump(list\-of\-Perl\-data\-structures);
 593 .Ve
 594 .PP
 595 Turn Perl data into \s-1YAML\s0. This function works very much like \fIData::Dumper::Dumper()\fR.
 596 .PP
 597 It takes a list of Perl data strucures and dumps them into a serialized form.
 598 .PP
 599 It returns a string containing the \s-1YAML\s0 stream.
 600 .PP
 601 The structures can be references or plain scalars.
 602 .Sh "Load"
 603 .IX Subsection "Load"
 604 .Vb 1
 605 \&  my @documents = Load(string\-containing\-a\-YAML\-stream);
 606 .Ve
 607 .PP
 608 Turn \s-1YAML\s0 into Perl data. This is the opposite of Dump.
 609 .PP
 610 Just like Storable's \fIthaw()\fR function or the \fIeval()\fR function in relation
 611 to Data::Dumper.
 612 .PP
 613 It parses a string containing a valid \s-1YAML\s0 stream into a list of Perl data
 614 structures.
 615 .Sh "\fIfreeze()\fP and \fIthaw()\fP"
 616 .IX Subsection "freeze() and thaw()"
 617 Aliases to \fIDump()\fR and \fILoad()\fR for Storable fans. This will also allow
 618 YAML::Tiny to be plugged directly into modules like \s-1POE\s0.pm, that use the
 619 freeze/thaw \s-1API\s0 for internal serialization.
 620 .Sh "DumpFile(filepath, list)"
 621 .IX Subsection "DumpFile(filepath, list)"
 622 Writes the \s-1YAML\s0 stream to a file instead of just returning a string.
 623 .Sh "LoadFile(filepath)"
 624 .IX Subsection "LoadFile(filepath)"
 625 Reads the \s-1YAML\s0 stream from a file instead of a string.
 626 .SH "SUPPORT"
 627 .IX Header "SUPPORT"
 628 Bugs should be reported via the \s-1CPAN\s0 bug tracker at
 629 .PP
 630 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=YAML\-Tiny>
 631 .SH "AUTHOR"
 632 .IX Header "AUTHOR"
 633 Adam Kennedy <adamk@cpan.org>
 634 .SH "SEE ALSO"
 635 .IX Header "SEE ALSO"
 636 \&\s-1YAML\s0, YAML::Syck, Config::Tiny, CSS::Tiny,
 637 <http://use.perl.org/~Alias/journal/29427>, <http://ali.as/>
 638 .SH "COPYRIGHT"
 639 .IX Header "COPYRIGHT"
 640 Copyright 2006 \- 2009 Adam Kennedy.
 641 .PP
 642 This program is free software; you can redistribute
 643 it and/or modify it under the same terms as Perl itself.
 644 .PP
 645 The full text of the license can be found in the
 646 \&\s-1LICENSE\s0 file included with this module.