README.md
1[](https://github.com/toddr/YAML-Syck/actions) [](https://github.com/toddr/YAML-Syck/actions) [](https://github.com/toddr/YAML-Syck/actions)
2
3# NAME
4
5YAML::Syck - Fast, lightweight YAML loader and dumper
6
7# SYNOPSIS
8
9 use YAML::Syck;
10
11 # Set this for interoperability with other YAML/Syck bindings:
12 # e.g. Load('Yes') becomes 1 and Load('No') becomes ''.
13 $YAML::Syck::ImplicitTyping = 1;
14
15 $data = Load($yaml);
16 $yaml = Dump($data);
17
18 # $file can be an IO object, or a filename
19 $data = LoadFile($file);
20 DumpFile($file, $data);
21
22 # A string with multiple YAML streams in it
23 $yaml = Dump(@data);
24 @data = Load($yaml);
25
26 # Dumping into a pre-existing output buffer
27 my $yaml;
28 DumpInto(\$yaml, @data);
29
30# DESCRIPTION
31
32This module provides a Perl interface to the **libsyck** data serialization
33library. It exports the `Dump` and `Load` functions for converting
34Perl data structures to YAML strings, and the other way around.
35
36**NOTE**: If you are working with other language's YAML/Syck bindings
37(such as Ruby), please set `$YAML::Syck::ImplicitTyping` to `1` before
38calling the `Load`/`Dump` functions. The default setting is for
39preserving backward-compatibility with `YAML.pm`.
40
41# Differences Between YAML::Syck and YAML
42
43## Error handling
44
45Some calls are designed to die rather than returning YAML. You should wrap
46your calls in eval to assure you do not get unexpected results.
47
48# FLAGS
49
50## $YAML::Syck::Headless
51
52Defaults to false. Setting this to a true value will make `Dump` omit the
53leading `---\n` marker.
54
55## $YAML::Syck::SortKeys
56
57Defaults to false. Setting this to a true value will make `Dump` sort
58hash keys.
59
60## $YAML::Syck::SingleQuote
61
62Defaults to false. Setting this to a true value will make `Dump` always emit
63single quotes instead of bare strings.
64
65## $YAML::Syck::ImplicitTyping
66
67Defaults to false. Setting this to a true value will make `Load` recognize
68various implicit types in YAML, such as unquoted `true`, `false`, as well as
69integers and floating-point numbers. Otherwise, only `~` is recognized to
70be `undef`.
71
72## $YAML::Syck::ImplicitUnicode
73
74Defaults to false. For Perl 5.8.0 or later, setting this to a true value will
75make `Load` set Unicode flag on for every string that contains valid UTF8
76sequences, and make `Dump` return a unicode string.
77
78Regardless of this flag, Unicode strings are dumped verbatim without escaping;
79byte strings with high-bit set will be dumped with backslash escaping.
80
81However, because YAML does not distinguish between these two kinds of strings,
82so this flag will affect loading of both variants of strings.
83
84If you want to use LoadFile or DumpFile with unicode, you are required to open
85your own file in order to assure it's UTF8 encoded:
86
87 open(my $fh, ">:encoding(UTF-8)", "out.yml");
88 DumpFile($fh, $hashref);
89
90## $YAML::Syck::ImplicitBinary
91
92Defaults to false. For Perl 5.8.0 or later, setting this to a true value will
93make `Dump` generate Base64-encoded `!!binary` data for all non-Unicode
94scalars containing high-bit bytes.
95
96## $YAML::Syck::UseCode / $YAML::Syck::LoadCode / $YAML::Syck::DumpCode
97
98These flags control whether or not to try and eval/deparse perl source code;
99each of them defaults to false.
100
101Setting `$YAML::Syck::UseCode` to a true value is equivalent to setting
102both `$YAML::Syck::LoadCode` and `$YAML::Syck::DumpCode` to true.
103
104## $YAML::Syck::LoadBlessed
105
106Defaults to false. Setting to true will allow YAML::Syck to bless objects as it
107imports objects. This default changed in 1.32.
108
109You can create any kind of object with YAML. The creation itself is not the
110critical part. If the class has a DESTROY method, it will be called once the
111object is deleted. An example with File::Temp removing files can be found at
112[https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=862373](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=862373)
113
114# BUGS
115
116Dumping Glob/IO values do not work yet.
117
118Dumping of Tied variables is unsupported.
119
120Dumping into tied (or other magic variables) with `DumpInto` might not work
121properly in all cases.
122
123# CAVEATS
124
125This module implements the YAML 1.0 spec. To deal with data in YAML 1.1,
126please use the `YAML::XS` module instead.
127
128The current implementation bundles libsyck source code; if your system has a
129site-wide shared libsyck, it will _not_ be used.
130
131Tag names such as `!!perl/hash:Foo` is blessed into the package `Foo`, but
132the `!hs/foo` and `!!hs/Foo` tags are blessed into `hs::Foo`. Note that
133this holds true even if the tag contains non-word characters; for example,
134`!haskell.org/Foo` is blessed into `haskell.org::Foo`. Please use
135[Class::Rebless](https://metacpan.org/pod/Class::Rebless) to cast it into other user-defined packages. You can also
136set the LoadBlessed flag false to disable all blessing.
137
138This module has [a lot of known
139issues](https://rt.cpan.org/Public/Dist/Display.html?Name=YAML-Syck)
140and has only been semi-actively maintained since 2007. If you
141encounter an issue with it probably won't be fixed unless you [offer
142up a patch](http://github.com/toddr/YAML-Syck) in Git that's ready for
143release.
144
145There are still good reasons to use this module, such as better
146interoperability with other syck wrappers (like Ruby's), or some edge
147case of YAML's syntax that it handles better. It'll probably work
148perfectly for you, but if it doesn't you may want to look at
149[YAML::XS](https://metacpan.org/pod/YAML::XS), or perhaps at looking another serialization format like
150[JSON](https://metacpan.org/pod/JSON).
151
152# SEE ALSO
153
154[YAML](https://metacpan.org/pod/YAML), [JSON::Syck](https://metacpan.org/pod/JSON::Syck)
155
156[http://www.yaml.org/](http://www.yaml.org/)
157
158# AUTHORS
159
160Audrey Tang <cpan@audreyt.org>
161
162# COPYRIGHT
163
164Copyright 2005-2009 by Audrey Tang <cpan@audreyt.org>.
165
166This software is released under the MIT license cited below.
167
168The `libsyck` code bundled with this library is released by
169"why the lucky stiff", under a BSD-style license. See the `COPYING`
170file for details.
171
172## The "MIT" License
173
174Permission is hereby granted, free of charge, to any person obtaining a copy
175of this software and associated documentation files (the "Software"), to deal
176in the Software without restriction, including without limitation the rights
177to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
178copies of the Software, and to permit persons to whom the Software is
179furnished to do so, subject to the following conditions:
180
181The above copyright notice and this permission notice shall be included in
182all copies or substantial portions of the Software.
183
184THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
185OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
186FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
187THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
188LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
189FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
190DEALINGS IN THE SOFTWARE.
191
){kind=link}
){kind=link}
){kind=link}