ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/CBOR-XS/XS.pm
(Generate patch)

Comparing CBOR-XS/XS.pm (file contents):
Revision 1.3 by root, Sat Oct 26 11:08:34 2013 UTC vs.
Revision 1.4 by root, Sat Oct 26 22:25:47 2013 UTC

… …
163 163
164=head2 CBOR -> PERL 164=head2 CBOR -> PERL
165 165
166=over 4 166=over 4
167 167
168=item integers
169
170CBOR integers become (numeric) perl scalars. On perls without 64 bit
171support, 64 bit integers will be truncated or otherwise corrupted.
172
173=item byte strings
174
175Byte strings will become octet strings in Perl (the byte values 0..255
176will simply become characters of the same value in Perl).
177
178=item UTF-8 strings
179
180UTF-8 strings in CBOR will be decoded, i.e. the UTF-8 octets will be
181decoded into proper Unicode code points. At the moment, the validity of
182the UTF-8 octets will not be validated - corrupt input will result in
183corrupted Perl strings.
184
185=item arrays, maps
186
187CBOR arrays and CBOR maps will be converted into references to a Perl
188array or hash, respectively. The keys of the map will be stringified
189during this process.
190
168=item True, False 191=item true, false
169 192
170These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>, 193These CBOR values become C<CBOR::XS::true> and C<CBOR::XS::false>,
171respectively. They are overloaded to act almost exactly like the numbers 194respectively. They are overloaded to act almost exactly like the numbers
172C<1> and C<0>. You can check whether a scalar is a CBOR boolean by using 195C<1> and C<0>. You can check whether a scalar is a CBOR boolean by using
173the C<CBOR::XS::is_bool> function. 196the C<CBOR::XS::is_bool> function.
174 197
175=item Null, Undefined 198=item null, undefined
176 199
177CBOR Null and Undefined values becomes C<undef> in Perl (in the future, 200CBOR null and undefined values becomes C<undef> in Perl (in the future,
178Undefined may raise an exception). 201Undefined may raise an exception or something else).
202
203=item tags
204
205Tagged items consists of a numeric tag and another CBOR value. The tag
20655799 is ignored (this tag implements the magic header).
207
208All other tags are currently converted into a L<CBOR::XS::Tagged> object,
209which is simply a blessed array reference consistsing of the numeric tag
210value followed by the (decoded) BOR value.
211
212=item anything else
213
214Anything else (e.g. unsupported simple values) will raise a decoding
215error.
179 216
180=back 217=back
181 218
182 219
183=head2 PERL -> CBOR 220=head2 PERL -> CBOR
… …
188 225
189=over 4 226=over 4
190 227
191=item hash references 228=item hash references
192 229
193Perl hash references become CBOR maps. As there is no inherent ordering 230Perl hash references become CBOR maps. As there is no inherent ordering in
194in hash keys (or CBOR maps), they will usually be encoded in a 231hash keys (or CBOR maps), they will usually be encoded in a pseudo-random
195pseudo-random order. 232order.
233
234Currently, tied hashes will use the indefinite-length format, while normal
235hashes will use the fixed-length format.
196 236
197=item array references 237=item array references
198 238
199Perl array references become CBOR arrays. 239Perl array references become fixed-length CBOR arrays.
200 240
201=item other references 241=item other references
202 242
203Other unblessed references are generally not allowed and will cause an 243Other unblessed references are generally not allowed and will cause an
204exception to be thrown, except for references to the integers C<0> and 244exception to be thrown, except for references to the integers C<0> and
205C<1>, which get turned into C<False> and C<True> in CBOR. 245C<1>, which get turned into false and true in CBOR.
246
247=item CBOR::XS::Tagged objects
248
249Objects of this type must be arrays consisting of a single C<[tag, value]>
250pair. The (numerical) tag will be encoded as a CBOR tag, the value will be
251encoded as appropriate for the value.
206 252
207=item CBOR::XS::true, CBOR::XS::false 253=item CBOR::XS::true, CBOR::XS::false
208 254
209These special values become CBOR True and CBOR False values, 255These special values become CBOR true and CBOR false values,
210respectively. You can also use C<\1> and C<\0> directly if you want. 256respectively. You can also use C<\1> and C<\0> directly if you want.
211 257
212=item blessed objects 258=item blessed objects
213 259
214Blessed objects are not directly representable in CBOR. TODO 260Other blessed objects currently need to have a C<TO_CBOR> method. It
215See the 261will be called on every object that is being serialised, and must return
216C<allow_blessed> and C<convert_blessed> methods on various options on 262something that can be encoded in CBOR.
217how to deal with this: basically, you can choose between throwing an
218exception, encoding the reference as if it weren't blessed, or provide
219your own serialiser method.
220 263
221=item simple scalars 264=item simple scalars
222 265
223TODO 266TODO
224Simple Perl scalars (any scalar that is not a reference) are the most 267Simple Perl scalars (any scalar that is not a reference) are the most
225difficult objects to encode: CBOR::XS will encode undefined scalars as 268difficult objects to encode: CBOR::XS will encode undefined scalars as
226CBOR C<Null> values, scalars that have last been used in a string context 269CBOR null values, scalars that have last been used in a string context
227before encoding as CBOR strings, and anything else as number value: 270before encoding as CBOR strings, and anything else as number value:
228 271
229 # dump as number 272 # dump as number
230 encode_cbor [2] # yields [2] 273 encode_cbor [2] # yields [2]
231 encode_cbor [-3.0e17] # yields [-3e+17] 274 encode_cbor [-3.0e17] # yields [-3e+17]
… …
253 296
254You can not currently force the type in other, less obscure, ways. Tell me 297You can not currently force the type in other, less obscure, ways. Tell me
255if you need this capability (but don't forget to explain why it's needed 298if you need this capability (but don't forget to explain why it's needed
256:). 299:).
257 300
258Note that numerical precision has the same meaning as under Perl (so 301Perl values that seem to be integers generally use the shortest possible
259binary to decimal conversion follows the same rules as in Perl, which 302representation. Floating-point values will use either the IEEE single
260can differ to other languages). Also, your perl interpreter might expose 303format if possible without loss of precision, otherwise the IEEE double
261extensions to the floating point numbers of your platform, such as 304format will be used. Perls that use formats other than IEEE double to
262infinities or NaN's - these cannot be represented in CBOR, and it is an 305represent numerical values are supported, but might suffer loss of
263error to pass those in. 306precision.
264 307
265=back 308=back
266 309
267 310
268=head2 MAGIC HEADER 311=head2 MAGIC HEADER
… …
278required. 321required.
279 322
280 323
281=head2 CBOR and JSON 324=head2 CBOR and JSON
282 325
283TODO 326CBOR is supposed to implement a superset of the JSON data model, and is,
327with some coercion, able to represent all JSON texts (something that other
328"binary JSON" formats such as BSON generally do not support).
329
330CBOR implements some extra hints and support for JSON interoperability,
331and the spec offers further guidance for conversion between CBOR and
332JSON. None of this is currently implemented in CBOR, and the guidelines
333in the spec do not result in correct round-tripping of data. If JSON
334interoperability is improved in the future, then the goal will be to
335ensure that decoded JSON data will round-trip encoding and decoding to
336CBOR intact.
284 337
285 338
286=head1 SECURITY CONSIDERATIONS 339=head1 SECURITY CONSIDERATIONS
287 340
288When you are using CBOR in a protocol, talking to untrusted potentially 341When you are using CBOR in a protocol, talking to untrusted potentially

Diff Legend

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