local-lib5/lib/perl5/i486-linux-gnu-thread-multi/YAML/Syck.pm

   1 package YAML::Syck;
   2 # See documentation after the __END__ mark.
   3
   4 use strict;
   5 use vars qw(
   6     @ISA @EXPORT $VERSION
   7     $Headless $SortKeys $SingleQuote
   8     $ImplicitBinary $ImplicitTyping $ImplicitUnicode
   9     $UseCode $LoadCode $DumpCode
  10     $DeparseObject
  11 );
  12 use 5.006;
  13 use Exporter;
  14
  15 BEGIN {
  16     $VERSION = '1.08';
  17     @EXPORT  = qw( Dump Load DumpFile LoadFile );
  18     @ISA     = qw( Exporter );
  19
  20     $SortKeys = 1;
  21
  22     local $@;
  23     eval {
  24         require XSLoader;
  25         XSLoader::load(__PACKAGE__, $VERSION);
  26         1;
  27     } or do {
  28         require DynaLoader;
  29         push @ISA, 'DynaLoader';
  30         __PACKAGE__->bootstrap($VERSION);
  31     };
  32
  33 }
  34
  35 use constant QR_MAP => {
  36     ''   => sub { qr{$_[0]}     },
  37     x    => sub { qr{$_[0]}x    },
  38     i    => sub { qr{$_[0]}i    },
  39     s    => sub { qr{$_[0]}s    },
  40     m    => sub { qr{$_[0]}m    },
  41     ix   => sub { qr{$_[0]}ix   },
  42     sx   => sub { qr{$_[0]}sx   },
  43     mx   => sub { qr{$_[0]}mx   },
  44     si   => sub { qr{$_[0]}si   },
  45     mi   => sub { qr{$_[0]}mi   },
  46     ms   => sub { qr{$_[0]}sm   },
  47     six  => sub { qr{$_[0]}six  },
  48     mix  => sub { qr{$_[0]}mix  },
  49     msx  => sub { qr{$_[0]}msx  },
  50     msi  => sub { qr{$_[0]}msi  },
  51     msix => sub { qr{$_[0]}msix },
  52 };
  53
  54 sub __qr_helper {
  55     if ($_[0] =~ /\A  \(\?  ([ixsm]*)  (?:-  (?:[ixsm]*))?  : (.*) \)  \z/x) {
  56         my $sub = QR_MAP()->{$1} || QR_MAP()->{''};
  57         &$sub($2);
  58     }
  59     else {
  60         qr/$_[0]/;
  61     }
  62 }
  63
  64 sub Dump {
  65     $#_ ? join('', map { YAML::Syck::DumpYAML($_) } @_)
  66         : YAML::Syck::DumpYAML($_[0]);
  67 }
  68
  69 sub Load {
  70     if (wantarray) {
  71         my ($rv) = YAML::Syck::LoadYAML($_[0]);
  72         @{$rv};
  73     }
  74     else {
  75         YAML::Syck::LoadYAML($_[0]);
  76     }
  77 }
  78
  79 # NOTE. The code below (_is_openhandle) avoids to require/load
  80 # Scalar::Util unless it is given a ref or glob
  81 # as an argument. That is purposeful, so to avoid
  82 # the need for this dependency unless strictly necessary.
  83 # If that was not the case, Scalar::Util::openhandle could
  84 # be used directly.
  85
  86 sub _is_openhandle {
  87     my $h = shift;
  88     if ( ref($h) || ref(\$h) eq 'GLOB' ) {
  89         require Scalar::Util;
  90         return Scalar::Util::openhandle($h);
  91     } else {
  92         return undef;
  93     }
  94 }
  95
  96 sub DumpFile {
  97     my $file = shift;
  98     if ( _is_openhandle($file) ) {
  99         if ($#_) {
 100             print {$file} YAML::Syck::DumpYAML($_) for @_;
 101         }
 102         else {
 103             print {$file} YAML::Syck::DumpYAML($_[0]);
 104         }
 105     }
 106     else {
 107         local *FH;
 108         open FH, "> $file" or die "Cannot write to $file: $!";
 109         if ($#_) {
 110             print FH YAML::Syck::DumpYAML($_) for @_;
 111         }
 112         else {
 113             print FH YAML::Syck::DumpYAML($_[0]);
 114         }
 115         close FH;
 116     }
 117 }
 118
 119 sub LoadFile {
 120     my $file = shift;
 121     if ( _is_openhandle($file) ) {
 122         Load(do { local $/; <$file> });
 123     }
 124     else {
 125         local *FH;
 126         open FH, "< $file" or die "Cannot read from $file: $!";
 127         Load(do { local $/; <FH> });
 128     }
 129 }
 130
 131 1;
 132
 133 __END__
 134 =pod
 135
 136 =head1 NAME
 137
 138 YAML::Syck - Fast, lightweight YAML loader and dumper
 139
 140 =head1 SYNOPSIS
 141
 142     use YAML::Syck;
 143
 144     # Set this for interoperability with other YAML/Syck bindings:
 145     # e.g. Load('Yes') becomes 1 and Load('No') becomes ''.
 146     $YAML::Syck::ImplicitTyping = 1;
 147
 148     $data = Load($yaml);
 149     $yaml = Dump($data);
 150
 151     # $file can be an IO object, or a filename
 152     $data = LoadFile($file);
 153     DumpFile($file, $data);
 154
 155     # A string with multiple YAML streams in it
 156     $yaml = Dump(@data);
 157     @data = Load($yaml);
 158
 159 =head1 WARNING
 160
 161 This module has L<a lot of known
 162 issues|https://rt.cpan.org/Public/Dist/Display.html?Name=YAML-Syck>
 163 and hasn't been actively maintained since 2007. If you encounter an
 164 issue with it probably won't be fixed unless you L<offer up a
 165 patch|http://github.com/avar/YAML-Syck> in Git that's ready for
 166 release.
 167
 168 Consider using L<YAML::XS> instead, or not using YAML at all. YAML is
 169 falling out of style in the Perl community in favor of simpler formats
 170 like JSON, which don't suffer from the bugs and annoying
 171 incompatibilities that plague the ambitious YAML format.
 172
 173 There are still some good reasons to use this module, such as better
 174 interoperability with other syck wrappers (like Ruby's), or some edge
 175 case of YAML's syntax that it handles better. Maybe it'll work
 176 perfectly for you, but if it doesn't you may be in for some pain.
 177
 178 =head1 DESCRIPTION
 179
 180 This module provides a Perl interface to the B<libsyck> data serialization
 181 library.  It exports the C<Dump> and C<Load> functions for converting
 182 Perl data structures to YAML strings, and the other way around.
 183
 184 B<NOTE>: If you are working with other language's YAML/Syck bindings
 185 (such as Ruby), please set C<$YAML::Syck::ImplicitTyping> to C<1> before
 186 calling the C<Load>/C<Dump> functions.  The default setting is for
 187 preserving backward-compatibility with C<YAML.pm>.
 188
 189 =head1 FLAGS
 190
 191 =head2 $YAML::Syck::Headless
 192
 193 Defaults to false.  Setting this to a true value will make C<Dump> omit the
 194 leading C<---\n> marker.
 195
 196 =head2 $YAML::Syck::SortKeys
 197
 198 Defaults to false.  Setting this to a true value will make C<Dump> sort
 199 hash keys.
 200
 201 =head2 $YAML::Syck::SingleQuote
 202
 203 Defaults to false.  Setting this to a true value will make C<Dump> always emit
 204 single quotes instead of bare strings.
 205
 206 =head2 $YAML::Syck::ImplicitTyping
 207
 208 Defaults to false.  Setting this to a true value will make C<Load> recognize
 209 various implicit types in YAML, such as unquoted C<true>, C<false>, as well as
 210 integers and floating-point numbers.  Otherwise, only C<~> is recognized to
 211 be C<undef>.
 212
 213 =head2 $YAML::Syck::ImplicitUnicode
 214
 215 Defaults to false.  For Perl 5.8.0 or later, setting this to a true value will
 216 make C<Load> set Unicode flag on for every string that contains valid UTF8
 217 sequences, and make C<Dump> return a unicode string.
 218
 219 Regardless of this flag, Unicode strings are dumped verbatim without escaping;
 220 byte strings with high-bit set will be dumped with backslash escaping.
 221
 222 However, because YAML does not distinguish between these two kinds of strings,
 223 so this flag will affect loading of both variants of strings.
 224
 225 =head2 $YAML::Syck::ImplicitBinary
 226
 227 Defaults to false.  For Perl 5.8.0 or later, setting this to a true value will
 228 make C<Dump> generate Base64-encoded C<!!binary> data for all non-Unicode
 229 scalars containing high-bit bytes.
 230
 231 =head2 $YAML::Syck::UseCode / $YAML::Syck::LoadCode / $YAML::Syck::DumpCode
 232
 233 These flags control whether or not to try and eval/deparse perl source code;
 234 each of them defaults to false.
 235
 236 Setting C<$YAML::Syck::UseCode> to a true value is equivalent to setting
 237 both C<$YAML::Syck::LoadCode> and C<$YAML::Syck::DumpCode> to true.
 238
 239 =head1 BUGS
 240
 241 Dumping Glob/IO values does not work yet.
 242
 243 =head1 CAVEATS
 244
 245 This module implements the YAML 1.0 spec.  To deal with data in YAML 1.1,
 246 please use the C<YAML::XS> module instead.
 247
 248 The current implementation bundles libsyck source code; if your system has a
 249 site-wide shared libsyck, it will I<not> be used.
 250
 251 Tag names such as C<!!perl/hash:Foo> is blessed into the package C<Foo>, but
 252 the C<!hs/foo> and C<!!hs/Foo> tags are blessed into C<hs::Foo>.  Note that
 253 this holds true even if the tag contains non-word characters; for example,
 254 C<!haskell.org/Foo> is blessed into C<haskell.org::Foo>.  Please use
 255 L<Class::Rebless> to cast it into other user-defined packages.
 256
 257 =head1 SEE ALSO
 258
 259 L<YAML>, L<JSON::Syck>
 260
 261 L<http://www.yaml.org/>
 262
 263 =head1 AUTHORS
 264
 265 Audrey Tang E<lt>cpan@audreyt.orgE<gt>
 266
 267 =head1 COPYRIGHT
 268
 269 Copyright 2005-2009 by Audrey Tang E<lt>cpan@audreyt.orgE<gt>.
 270
 271 This software is released under the MIT license cited below.
 272
 273 The F<libsyck> code bundled with this library is released by
 274 "why the lucky stiff", under a BSD-style license.  See the F<COPYING>
 275 file for details.
 276
 277 =head2 The "MIT" License
 278
 279 Permission is hereby granted, free of charge, to any person obtaining a copy
 280 of this software and associated documentation files (the "Software"), to deal
 281 in the Software without restriction, including without limitation the rights
 282 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 283 copies of the Software, and to permit persons to whom the Software is
 284 furnished to do so, subject to the following conditions:
 285
 286 The above copyright notice and this permission notice shall be included in
 287 all copies or substantial portions of the Software.
 288
 289 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 290 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 291 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
 292 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 293 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 294 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 295 DEALINGS IN THE SOFTWARE.
 296
 297 =cut