ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/README
(Generate patch)

Comparing JSON-XS/README (file contents):
Revision 1.18 by root, Tue Aug 28 02:06:06 2007 UTC vs.
Revision 1.19 by root, Sat Oct 13 01:57:46 2007 UTC

1NAME 1NAME
2 JSON::XS - JSON serialising/deserialising, done correctly and fast 2 JSON::XS - JSON serialising/deserialising, done correctly and fast
3
4 JSON::XS - 正しくて高速な JSON
5 シリアライザ/デシリアライザ
6 (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html)
3 7
4SYNOPSIS 8SYNOPSIS
5 use JSON::XS; 9 use JSON::XS;
6 10
7 # exported functions, they croak on error 11 # exported functions, they croak on error
… …
67FUNCTIONAL INTERFACE 71FUNCTIONAL INTERFACE
68 The following convinience methods are provided by this module. They are 72 The following convinience methods are provided by this module. They are
69 exported by default: 73 exported by default:
70 74
71 $json_text = to_json $perl_scalar 75 $json_text = to_json $perl_scalar
72 Converts the given Perl data structure (a simple scalar or a 76 Converts the given Perl data structure to a UTF-8 encoded, binary
73 reference to a hash or array) to a UTF-8 encoded, binary string
74 (that is, the string contains octets only). Croaks on error. 77 string (that is, the string contains octets only). Croaks on error.
75 78
76 This function call is functionally identical to: 79 This function call is functionally identical to:
77 80
78 $json_text = JSON::XS->new->utf8->encode ($perl_scalar) 81 $json_text = JSON::XS->new->utf8->encode ($perl_scalar)
79 82
80 except being faster. 83 except being faster.
81 84
82 $perl_scalar = from_json $json_text 85 $perl_scalar = from_json $json_text
83 The opposite of "to_json": expects an UTF-8 (binary) string and 86 The opposite of "to_json": expects an UTF-8 (binary) string and
84 tries to parse that as an UTF-8 encoded JSON text, returning the 87 tries to parse that as an UTF-8 encoded JSON text, returning the
85 resulting simple scalar or reference. Croaks on error. 88 resulting reference. Croaks on error.
86 89
87 This function call is functionally identical to: 90 This function call is functionally identical to:
88 91
89 $perl_scalar = JSON::XS->new->utf8->decode ($json_text) 92 $perl_scalar = JSON::XS->new->utf8->decode ($json_text)
90 93
… …
96 respectively and are used to represent JSON "true" and "false" 99 respectively and are used to represent JSON "true" and "false"
97 values in Perl. 100 values in Perl.
98 101
99 See MAPPING, below, for more information on how JSON values are 102 See MAPPING, below, for more information on how JSON values are
100 mapped to Perl. 103 mapped to Perl.
104
105A FEW NOTES ON UNICODE AND PERL
106 Since this often leads to confusion, here are a few very clear words on
107 how Unicode works in Perl, modulo bugs.
108
109 1. Perl strings can store characters with ordinal values > 255.
110 This enables you to store unicode characters as single characters in
111 a Perl string - very natural.
112
113 2. Perl does *not* associate an encoding with your strings.
114 Unless you force it to, e.g. when matching it against a regex, or
115 printing the scalar to a file, in which case Perl either interprets
116 your string as locale-encoded text, octets/binary, or as Unicode,
117 depending on various settings. In no case is an encoding stored
118 together with your data, it is *use* that decides encoding, not any
119 magical metadata.
120
121 3. The internal utf-8 flag has no meaning with regards to the encoding
122 of your string.
123 Just ignore that flag unless you debug a Perl bug, a module written
124 in XS or want to dive into the internals of perl. Otherwise it will
125 only confuse you, as, despite the name, it says nothing about how
126 your string is encoded. You can have unicode strings with that flag
127 set, with that flag clear, and you can have binary data with that
128 flag set and that flag clear. Other possibilities exist, too.
129
130 If you didn't know about that flag, just the better, pretend it
131 doesn't exist.
132
133 4. A "Unicode String" is simply a string where each character can be
134 validly interpreted as a Unicode codepoint.
135 If you have UTF-8 encoded data, it is no longer a Unicode string,
136 but a Unicode string encoded in UTF-8, giving you a binary string.
137
138 5. A string containing "high" (> 255) character values is *not* a UTF-8
139 string.
140 Its a fact. Learn to live with it.
141
142 I hope this helps :)
101 143
102OBJECT-ORIENTED INTERFACE 144OBJECT-ORIENTED INTERFACE
103 The object oriented interface lets you configure your own encoding or 145 The object oriented interface lets you configure your own encoding or
104 decoding style, within the limits of supported formats. 146 decoding style, within the limits of supported formats.
105 147
… …
601 643
602 to_json [\0,JSON::XS::true] # yields [false,true] 644 to_json [\0,JSON::XS::true] # yields [false,true]
603 645
604 JSON::XS::true, JSON::XS::false 646 JSON::XS::true, JSON::XS::false
605 These special values become JSON true and JSON false values, 647 These special values become JSON true and JSON false values,
606 respectively. You cna alos use "\1" and "\0" directly if you want. 648 respectively. You can also use "\1" and "\0" directly if you want.
607 649
608 blessed objects 650 blessed objects
609 Blessed objects are not allowed. JSON::XS currently tries to encode 651 Blessed objects are not allowed. JSON::XS currently tries to encode
610 their underlying representation (hash- or arrayref), but this 652 their underlying representation (hash- or arrayref), but this
611 behaviour might change in future versions. 653 behaviour might change in future versions.
… …
846 you are vulnerable to some common attack vectors (which really are 888 you are vulnerable to some common attack vectors (which really are
847 browser design bugs, but it is still you who will have to deal with it, 889 browser design bugs, but it is still you who will have to deal with it,
848 as major browser developers care only for features, not about doing 890 as major browser developers care only for features, not about doing
849 security right). 891 security right).
850 892
893THREADS
894 This module is *not* guarenteed to be thread safe and there are no plans
895 to change this until Perl gets thread support (as opposed to the
896 horribly slow so-called "threads" which are simply slow and bloated
897 process simulations - use fork, its *much* faster, cheaper, better).
898
899 (It might actually work, but you ahve ben warned).
900
851BUGS 901BUGS
852 While the goal of this module is to be correct, that unfortunately does 902 While the goal of this module is to be correct, that unfortunately does
853 not mean its bug-free, only that I think its design is bug-free. It is 903 not mean its bug-free, only that I think its design is bug-free. It is
854 still relatively early in its development. If you keep reporting bugs 904 still relatively early in its development. If you keep reporting bugs
855 they will be fixed swiftly, though. 905 they will be fixed swiftly, though.
856 906
907 Please refrain from using rt.cpan.org or any other bug reporting
908 service. I put the contact address into my modules for a reason.
909
857AUTHOR 910AUTHOR
858 Marc Lehmann <schmorp@schmorp.de> 911 Marc Lehmann <schmorp@schmorp.de>
859 http://home.schmorp.de/ 912 http://home.schmorp.de/
860 913

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines