local-lib5/man/man3/JSON::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 "JSON::Syck 3"
 127 .TH JSON::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 JSON::Syck \- JSON is YAML (but consider using \s-1JSON::XS\s0 instead!)
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    use JSON::Syck; # no exports by default
 138 \&
 139 \&    my $data = JSON::Syck::Load($json);
 140 \&    my $json = JSON::Syck::Dump($data);
 141 \&
 142 \&    # $file can be an IO object, or a filename
 143 \&    my $data = JSON::Syck::LoadFile($file);
 144 \&    JSON::Syck::DumpFile($file, $data);
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 JSON::Syck is a syck implementation of \s-1JSON\s0 parsing and generation. Because
 149 \&\s-1JSON\s0 is \s-1YAML\s0 (<http://redhanded.hobix.com/inspect/yamlIsJson.html>), using
 150 syck gives you a fast and memory-efficient parser and dumper for \s-1JSON\s0 data
 151 representation.
 152 .PP
 153 However, a newer module \s-1JSON::XS\s0, has since emerged.  It is more flexible,
 154 efficient and robust, so please consider using it instead of this module.
 155 .SH "DIFFERENCE WITH JSON"
 156 .IX Header "DIFFERENCE WITH JSON"
 157 You might want to know the difference between the \fI\s-1JSON\s0\fR module and
 158 this one.
 159 .PP
 160 Since \s-1JSON\s0 is a pure-perl module and JSON::Syck is based on libsyck,
 161 JSON::Syck is supposed to be very fast and memory efficient. See
 162 chansen's benchmark table at
 163 <http://idisk.mac.com/christian.hansen/Public/perl/serialize.pl>
 164 .PP
 165 \&\s-1JSON\s0.pm comes with dozens of ways to do the same thing and lots of
 166 options, while JSON::Syck doesn't. There's only \f(CW\*(C`Load\*(C'\fR and \f(CW\*(C`Dump\*(C'\fR.
 167 .PP
 168 Oh, and JSON::Syck doesn't use camelCase method names :\-)
 169 .SH "REFERENCES"
 170 .IX Header "REFERENCES"
 171 .SS "\s-1SCALAR\s0 \s-1REFERENCE\s0"
 172 .IX Subsection "SCALAR REFERENCE"
 173 For now, when you pass a scalar reference to JSON::Syck, it
 174 dereferences to get the actual scalar value.
 175 .PP
 176 JSON::Syck raises an exception when you pass in circular references.
 177 .PP
 178 If you want to serialize self refernecing stuff, you should use
 179 \&\s-1YAML\s0 which supports it.
 180 .SS "\s-1SUBROUTINE\s0 \s-1REFERENCE\s0"
 181 .IX Subsection "SUBROUTINE REFERENCE"
 182 When you pass subroutine reference, JSON::Syck dumps it as null.
 183 .SH "UTF\-8 FLAGS"
 184 .IX Header "UTF-8 FLAGS"
 185 By default this module doesn't touch any of utf\-8 flags set in
 186 strings, and assumes \s-1UTF\-8\s0 bytes to be passed and emit.
 187 .PP
 188 However, when you set \f(CW$JSON::Syck::ImplicitUnicode\fR to 1, this
 189 module properly decodes \s-1UTF\-8\s0 binaries and sets \s-1UTF\-8\s0 flag everywhere,
 190 as in:
 191 .PP
 192 .Vb 4
 193 \&  JSON (UTF\-8 bytes)   => Perl (UTF\-8 flagged)
 194 \&  JSON (UTF\-8 flagged) => Perl (UTF\-8 flagged)
 195 \&  Perl (UTF\-8 bytes)   => JSON (UTF\-8 flagged)
 196 \&  Perl (UTF\-8 flagged) => JSON (UTF\-8 flagged)
 197 .Ve
 198 .PP
 199 Unfortunately, there's no implicit way to dump Perl \s-1UTF\-8\s0 flagged data
 200 structure to utf\-8 encoded \s-1JSON\s0. To do this, simply use Encode module, e.g.:
 201 .PP
 202 .Vb 2
 203 \&  use Encode;
 204 \&  use JSON::Syck qw(Dump);
 205 \&
 206 \&  my $json = encode_utf8( Dump($data) );
 207 .Ve
 208 .PP
 209 Alternatively you can use Encode::JavaScript::UCS to encode Unicode
 210 strings as in \fI\f(CI%uXXXX\fI\fR form.
 211 .PP
 212 .Vb 3
 213 \&  use Encode;
 214 \&  use Encode::JavaScript::UCS;
 215 \&  use JSON::Syck qw(Dump);
 216 \&
 217 \&  my $json_unicode_escaped = encode( \*(AqJavaScript\-UCS\*(Aq, Dump($data) );
 218 .Ve
 219 .SH "QUOTING"
 220 .IX Header "QUOTING"
 221 According to the \s-1JSON\s0 specification, all \s-1JSON\s0 strings are to be double-quoted.
 222 However, when embedding JavaScript in \s-1HTML\s0 attributes, it may be more
 223 convenient to use single quotes.
 224 .PP
 225 Set \f(CW$JSON::Syck::SingleQuote\fR to 1 will make both \f(CW\*(C`Dump\*(C'\fR and \f(CW\*(C`Load\*(C'\fR expect
 226 single-quoted string literals.
 227 .SH "SEE ALSO"
 228 .IX Header "SEE ALSO"
 229 \&\s-1JSON::XS\s0,
 230 .SH "AUTHORS"
 231 .IX Header "AUTHORS"
 232 Audrey Tang <cpan@audreyt.org>
 233 .PP
 234 Tatsuhiko Miyagawa <miyagawa@gmail.com>
 235 .SH "COPYRIGHT"
 236 .IX Header "COPYRIGHT"
 237 Copyright 2005\-2009 by Audrey Tang <cpan@audreyt.org>.
 238 .PP
 239 This software is released under the \s-1MIT\s0 license cited below.
 240 .PP
 241 The \fIlibsyck\fR code bundled with this library is released by
 242 \&\*(L"why the lucky stiff\*(R", under a BSD-style license.  See the \fI\s-1COPYING\s0\fR
 243 file for details.
 244 .ie n .SS "The ""\s-1MIT\s0"" License"
 245 .el .SS "The ``\s-1MIT\s0'' License"
 246 .IX Subsection "The MIT License"
 247 Permission is hereby granted, free of charge, to any person obtaining a copy
 248 of this software and associated documentation files (the \*(L"Software\*(R"), to deal
 249 in the Software without restriction, including without limitation the rights
 250 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 251 copies of the Software, and to permit persons to whom the Software is
 252 furnished to do so, subject to the following conditions:
 253 .PP
 254 The above copyright notice and this permission notice shall be included in
 255 all copies or substantial portions of the Software.
 256 .PP
 257 \&\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
 258 \&\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,
 259 \&\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
 260 \&\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
 261 \&\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
 262 \&\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
 263 \&\s-1DEALINGS\s0 \s-1IN\s0 \s-1THE\s0 \s-1SOFTWARE\s0.