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

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "YAML::Syck 3"
 127 .TH YAML::Syck 3 "2010-05-23" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 YAML::Syck \- Fast, lightweight YAML loader and dumper
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use YAML::Syck;
 138 \&
 139 \&    # Set this for interoperability with other YAML/Syck bindings:
 140 \&    # e.g. Load(\*(AqYes\*(Aq) becomes 1 and Load(\*(AqNo\*(Aq) becomes \*(Aq\*(Aq.
 141 \&    $YAML::Syck::ImplicitTyping = 1;
 142 \&
 143 \&    $data = Load($yaml);
 144 \&    $yaml = Dump($data);
 145 \&
 146 \&    # $file can be an IO object, or a filename
 147 \&    $data = LoadFile($file);
 148 \&    DumpFile($file, $data);
 149 \&
 150 \&    # A string with multiple YAML streams in it
 151 \&    $yaml = Dump(@data);
 152 \&    @data = Load($yaml);
 153 .Ve
 154 .SH "WARNING"
 155 .IX Header "WARNING"
 156 This module has <a lot of known
 157 issues>
 158 and hasn't been actively maintained since 2007. If you encounter an
 159 issue with it probably won't be fixed unless you <offer up a
 160 patch> in Git that's ready for
 161 release.
 162 .PP
 163 Consider using \s-1YAML::XS\s0 instead, or not using \s-1YAML\s0 at all. \s-1YAML\s0 is
 164 falling out of style in the Perl community in favor of simpler formats
 165 like \s-1JSON\s0, which don't suffer from the bugs and annoying
 166 incompatibilities that plague the ambitious \s-1YAML\s0 format.
 167 .PP
 168 There are still some good reasons to use this module, such as better
 169 interoperability with other syck wrappers (like Ruby's), or some edge
 170 case of \s-1YAML\s0's syntax that it handles better. Maybe it'll work
 171 perfectly for you, but if it doesn't you may be in for some pain.
 172 .SH "DESCRIPTION"
 173 .IX Header "DESCRIPTION"
 174 This module provides a Perl interface to the \fBlibsyck\fR data serialization
 175 library.  It exports the \f(CW\*(C`Dump\*(C'\fR and \f(CW\*(C`Load\*(C'\fR functions for converting
 176 Perl data structures to \s-1YAML\s0 strings, and the other way around.
 177 .PP
 178 \&\fB\s-1NOTE\s0\fR: If you are working with other language's YAML/Syck bindings
 179 (such as Ruby), please set \f(CW$YAML::Syck::ImplicitTyping\fR to \f(CW1\fR before
 180 calling the \f(CW\*(C`Load\*(C'\fR/\f(CW\*(C`Dump\*(C'\fR functions.  The default setting is for
 181 preserving backward-compatibility with \f(CW\*(C`YAML.pm\*(C'\fR.
 182 .SH "FLAGS"
 183 .IX Header "FLAGS"
 184 .ie n .SS "$YAML::Syck::Headless"
 185 .el .SS "\f(CW$YAML::Syck::Headless\fP"
 186 .IX Subsection "$YAML::Syck::Headless"
 187 Defaults to false.  Setting this to a true value will make \f(CW\*(C`Dump\*(C'\fR omit the
 188 leading \f(CW\*(C`\-\-\-\en\*(C'\fR marker.
 189 .ie n .SS "$YAML::Syck::SortKeys"
 190 .el .SS "\f(CW$YAML::Syck::SortKeys\fP"
 191 .IX Subsection "$YAML::Syck::SortKeys"
 192 Defaults to false.  Setting this to a true value will make \f(CW\*(C`Dump\*(C'\fR sort
 193 hash keys.
 194 .ie n .SS "$YAML::Syck::SingleQuote"
 195 .el .SS "\f(CW$YAML::Syck::SingleQuote\fP"
 196 .IX Subsection "$YAML::Syck::SingleQuote"
 197 Defaults to false.  Setting this to a true value will make \f(CW\*(C`Dump\*(C'\fR always emit
 198 single quotes instead of bare strings.
 199 .ie n .SS "$YAML::Syck::ImplicitTyping"
 200 .el .SS "\f(CW$YAML::Syck::ImplicitTyping\fP"
 201 .IX Subsection "$YAML::Syck::ImplicitTyping"
 202 Defaults to false.  Setting this to a true value will make \f(CW\*(C`Load\*(C'\fR recognize
 203 various implicit types in \s-1YAML\s0, such as unquoted \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`false\*(C'\fR, as well as
 204 integers and floating-point numbers.  Otherwise, only \f(CW\*(C`~\*(C'\fR is recognized to
 205 be \f(CW\*(C`undef\*(C'\fR.
 206 .ie n .SS "$YAML::Syck::ImplicitUnicode"
 207 .el .SS "\f(CW$YAML::Syck::ImplicitUnicode\fP"
 208 .IX Subsection "$YAML::Syck::ImplicitUnicode"
 209 Defaults to false.  For Perl 5.8.0 or later, setting this to a true value will
 210 make \f(CW\*(C`Load\*(C'\fR set Unicode flag on for every string that contains valid \s-1UTF8\s0
 211 sequences, and make \f(CW\*(C`Dump\*(C'\fR return a unicode string.
 212 .PP
 213 Regardless of this flag, Unicode strings are dumped verbatim without escaping;
 214 byte strings with high-bit set will be dumped with backslash escaping.
 215 .PP
 216 However, because \s-1YAML\s0 does not distinguish between these two kinds of strings,
 217 so this flag will affect loading of both variants of strings.
 218 .ie n .SS "$YAML::Syck::ImplicitBinary"
 219 .el .SS "\f(CW$YAML::Syck::ImplicitBinary\fP"
 220 .IX Subsection "$YAML::Syck::ImplicitBinary"
 221 Defaults to false.  For Perl 5.8.0 or later, setting this to a true value will
 222 make \f(CW\*(C`Dump\*(C'\fR generate Base64\-encoded \f(CW\*(C`!!binary\*(C'\fR data for all non-Unicode
 223 scalars containing high-bit bytes.
 224 .ie n .SS "$YAML::Syck::UseCode / $YAML::Syck::LoadCode / $YAML::Syck::DumpCode"
 225 .el .SS "\f(CW$YAML::Syck::UseCode\fP / \f(CW$YAML::Syck::LoadCode\fP / \f(CW$YAML::Syck::DumpCode\fP"
 226 .IX Subsection "$YAML::Syck::UseCode / $YAML::Syck::LoadCode / $YAML::Syck::DumpCode"
 227 These flags control whether or not to try and eval/deparse perl source code;
 228 each of them defaults to false.
 229 .PP
 230 Setting \f(CW$YAML::Syck::UseCode\fR to a true value is equivalent to setting
 231 both \f(CW$YAML::Syck::LoadCode\fR and \f(CW$YAML::Syck::DumpCode\fR to true.
 232 .SH "BUGS"
 233 .IX Header "BUGS"
 234 Dumping Glob/IO values does not work yet.
 235 .SH "CAVEATS"
 236 .IX Header "CAVEATS"
 237 This module implements the \s-1YAML\s0 1.0 spec.  To deal with data in \s-1YAML\s0 1.1,
 238 please use the \f(CW\*(C`YAML::XS\*(C'\fR module instead.
 239 .PP
 240 The current implementation bundles libsyck source code; if your system has a
 241 site-wide shared libsyck, it will \fInot\fR be used.
 242 .PP
 243 Tag names such as \f(CW\*(C`!!perl/hash:Foo\*(C'\fR is blessed into the package \f(CW\*(C`Foo\*(C'\fR, but
 244 the \f(CW\*(C`!hs/foo\*(C'\fR and \f(CW\*(C`!!hs/Foo\*(C'\fR tags are blessed into \f(CW\*(C`hs::Foo\*(C'\fR.  Note that
 245 this holds true even if the tag contains non-word characters; for example,
 246 \&\f(CW\*(C`!haskell.org/Foo\*(C'\fR is blessed into \f(CW\*(C`haskell.org::Foo\*(C'\fR.  Please use
 247 Class::Rebless to cast it into other user-defined packages.
 248 .SH "SEE ALSO"
 249 .IX Header "SEE ALSO"
 250 \&\s-1YAML\s0, JSON::Syck
 251 .PP
 252 <http://www.yaml.org/>
 253 .SH "AUTHORS"
 254 .IX Header "AUTHORS"
 255 Audrey Tang <cpan@audreyt.org>
 256 .SH "COPYRIGHT"
 257 .IX Header "COPYRIGHT"
 258 Copyright 2005\-2009 by Audrey Tang <cpan@audreyt.org>.
 259 .PP
 260 This software is released under the \s-1MIT\s0 license cited below.
 261 .PP
 262 The \fIlibsyck\fR code bundled with this library is released by
 263 \&\*(L"why the lucky stiff\*(R", under a BSD-style license.  See the \fI\s-1COPYING\s0\fR
 264 file for details.
 265 .ie n .SS "The ""\s-1MIT\s0"" License"
 266 .el .SS "The ``\s-1MIT\s0'' License"
 267 .IX Subsection "The MIT License"
 268 Permission is hereby granted, free of charge, to any person obtaining a copy
 269 of this software and associated documentation files (the \*(L"Software\*(R"), to deal
 270 in the Software without restriction, including without limitation the rights
 271 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 272 copies of the Software, and to permit persons to whom the Software is
 273 furnished to do so, subject to the following conditions:
 274 .PP
 275 The above copyright notice and this permission notice shall be included in
 276 all copies or substantial portions of the Software.
 277 .PP
 278 \&\s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R", \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EXPRESS\s0
 279 \&\s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1THE\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0,
 280 \&\s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0 \s-1AND\s0 \s-1NONINFRINGEMENT\s0. \s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1SHALL\s0
 281 \&\s-1THE\s0 \s-1AUTHORS\s0 \s-1OR\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1BE\s0 \s-1LIABLE\s0 \s-1FOR\s0 \s-1ANY\s0 \s-1CLAIM\s0, \s-1DAMAGES\s0 \s-1OR\s0 \s-1OTHER\s0
 282 \&\s-1LIABILITY\s0, \s-1WHETHER\s0 \s-1IN\s0 \s-1AN\s0 \s-1ACTION\s0 \s-1OF\s0 \s-1CONTRACT\s0, \s-1TORT\s0 \s-1OR\s0 \s-1OTHERWISE\s0, \s-1ARISING\s0
 283 \&\s-1FROM\s0, \s-1OUT\s0 \s-1OF\s0 \s-1OR\s0 \s-1IN\s0 \s-1CONNECTION\s0 \s-1WITH\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1OR\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1OTHER\s0
 284 \&\s-1DEALINGS\s0 \s-1IN\s0 \s-1THE\s0 \s-1SOFTWARE\s0.