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.80 by root, Fri Dec 11 06:05:33 2020 UTC vs.
Revision 1.89 by root, Fri Sep 8 20:03:06 2023 UTC

… …
64 64
65package CBOR::XS; 65package CBOR::XS;
66 66
67use common::sense; 67use common::sense;
68 68
69our $VERSION = 1.83; 69our $VERSION = 1.87;
70our @ISA = qw(Exporter); 70our @ISA = qw(Exporter);
71 71
72our @EXPORT = qw(encode_cbor decode_cbor); 72our @EXPORT = qw(encode_cbor decode_cbor);
73 73
74use Exporter; 74use Exporter;
… …
121but configures the coder object to be safe to use with untrusted 121but configures the coder object to be safe to use with untrusted
122data. Currently, this is equivalent to: 122data. Currently, this is equivalent to:
123 123
124 my $cbor = CBOR::XS 124 my $cbor = CBOR::XS
125 ->new 125 ->new
126 ->validate_utf8
126 ->forbid_objects 127 ->forbid_objects
127 ->filter (\&CBOR::XS::safe_filter) 128 ->filter (\&CBOR::XS::safe_filter)
128 ->max_size (1e8); 129 ->max_size (1e8);
129 130
130But is more future proof (it is better to crash because of a change than 131But is more future proof (it is better to crash because of a change than
… …
133=cut 134=cut
134 135
135sub new_safe { 136sub new_safe {
136 CBOR::XS 137 CBOR::XS
137 ->new 138 ->new
139 ->validate_utf8
138 ->forbid_objects 140 ->forbid_objects
139 ->filter (\&CBOR::XS::safe_filter) 141 ->filter (\&CBOR::XS::safe_filter)
140 ->max_size (1e8) 142 ->max_size (1e8)
141} 143}
142 144
… …
214communication partner supports the value sharing extensions to CBOR 216communication partner supports the value sharing extensions to CBOR
215(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the 217(L<http://cbor.schmorp.de/value-sharing>), as without decoder support, the
216resulting data structure might be unusable. 218resulting data structure might be unusable.
217 219
218Detecting shared values incurs a runtime overhead when values are encoded 220Detecting shared values incurs a runtime overhead when values are encoded
219that have a reference counter large than one, and might unnecessarily 221that have a reference counter larger than one, and might unnecessarily
220increase the encoded size, as potentially shared values are encoded as 222increase the encoded size, as potentially shared values are encoded as
221shareable whether or not they are actually shared. 223shareable whether or not they are actually shared.
222 224
223At the moment, only targets of references can be shared (e.g. scalars, 225At the moment, only targets of references can be shared (e.g. scalars,
224arrays or hashes pointed to by a reference). Weirder constructs, such as 226arrays or hashes pointed to by a reference). Weirder constructs, such as
… …
243isn't prepared for this will not leak memory. 245isn't prepared for this will not leak memory.
244 246
245If C<$enable> is false (the default), then C<decode> will throw an error 247If C<$enable> is false (the default), then C<decode> will throw an error
246when it encounters a self-referential/cyclic data structure. 248when it encounters a self-referential/cyclic data structure.
247 249
248FUTURE DIRECTION: the motivation behind this option is to avoid I<real> 250This option does not affect C<encode> in any way - shared values and
249cycles - future versions of this module might chose to decode cyclic data 251references will always be encoded properly if present.
250structures using weak references when this option is off, instead of 252
251throwing an error. 253=item $cbor = $cbor->allow_weak_cycles ([$enable])
254
255=item $enabled = $cbor->get_allow_weak_cycles
256
257This works like C<allow_cycles> in that it allows the resulting data
258structures to contain cycles, but unlike C<allow_cycles>, those cyclic
259rreferences will be weak. That means that code that recurrsively walks
260the data structure must be prepared with cycles, but at least not special
261precautions must be implemented to free these data structures.
262
263Only those references leading to actual cycles will be weakened - other
264references, e.g. when the same hash or arrray is referenced multiple times
265in an arrray, will be normal references.
252 266
253This option does not affect C<encode> in any way - shared values and 267This option does not affect C<encode> in any way - shared values and
254references will always be encoded properly if present. 268references will always be encoded properly if present.
255 269
256=item $cbor = $cbor->forbid_objects ([$enable]) 270=item $cbor = $cbor->forbid_objects ([$enable])
… …
471Perl data structure in memory at one time, it does allow you to parse a 485Perl data structure in memory at one time, it does allow you to parse a
472CBOR stream incrementally, using a similar to using "decode_prefix" to see 486CBOR stream incrementally, using a similar to using "decode_prefix" to see
473if a full CBOR object is available, but is much more efficient. 487if a full CBOR object is available, but is much more efficient.
474 488
475It basically works by parsing as much of a CBOR string as possible - if 489It basically works by parsing as much of a CBOR string as possible - if
476the CBOR data is not complete yet, the pasrer will remember where it was, 490the CBOR data is not complete yet, the parser will remember where it was,
477to be able to restart when more data has been accumulated. Once enough 491to be able to restart when more data has been accumulated. Once enough
478data is available to either decode a complete CBOR value or raise an 492data is available to either decode a complete CBOR value or raise an
479error, a real decode will be attempted. 493error, a real decode will be attempted.
480 494
481A typical use case would be a network protocol that consists of sending 495A typical use case would be a network protocol that consists of sending
… …
633create such objects. 647create such objects.
634 648
635=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error 649=item Types::Serialiser::true, Types::Serialiser::false, Types::Serialiser::error
636 650
637These special values become CBOR true, CBOR false and CBOR undefined 651These special values become CBOR true, CBOR false and CBOR undefined
638values, respectively. You can also use C<\1>, C<\0> and C<\undef> directly 652values, respectively.
639if you want.
640 653
641=item other blessed objects 654=item other blessed objects
642 655
643Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See 656Other blessed objects are serialised via C<TO_CBOR> or C<FREEZE>. See
644L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this 657L<TAG HANDLING AND EXTENSIONS> for specific classes handled by this
… …
704=back 717=back
705 718
706=head2 TYPE CASTS 719=head2 TYPE CASTS
707 720
708B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to 721B<EXPERIMENTAL>: As an experimental extension, C<CBOR::XS> allows you to
709force specific cbor types to be used when encoding. That allows you to 722force specific CBOR types to be used when encoding. That allows you to
710encode types not normally accessible (e.g. half floats) as well as force 723encode types not normally accessible (e.g. half floats) as well as force
711string types even when C<text_strings> is in effect. 724string types even when C<text_strings> is in effect.
712 725
713Type forcing is done by calling a special "cast" function which keeps a 726Type forcing is done by calling a special "cast" function which keeps a
714copy of the value and returns a new value that can be handed over to any 727copy of the value and returns a new value that can be handed over to any
… …
756 769
757Forces double-float (IEEE 754 binary64) encoding of the given value. 770Forces double-float (IEEE 754 binary64) encoding of the given value.
758 771
759=item CBOR::XS::as_cbor $cbor_text 772=item CBOR::XS::as_cbor $cbor_text
760 773
761Not a type cast per-se, this type cast forces the argument to eb encoded 774Not a type cast per-se, this type cast forces the argument to be encoded
762as-is. This can be used to embed pre-encoded CBOR data. 775as-is. This can be used to embed pre-encoded CBOR data.
763 776
764Note that no checking on the validity of the C<$cbor_text> is done - it's 777Note that no checking on the validity of the C<$cbor_text> is done - it's
765the callers responsibility to correctly encode values. 778the callers responsibility to correctly encode values.
766 779
… …
773 786
774The single argument must be an array reference with an even number of 787The single argument must be an array reference with an even number of
775elements. 788elements.
776 789
777Note that only the reference to the array is copied, the array itself is 790Note that only the reference to the array is copied, the array itself is
778not. Modifications done to the array before calling an encoding fuinction 791not. Modifications done to the array before calling an encoding function
779will be reflected in the encoded output. 792will be reflected in the encoded output.
780 793
781Example: encode a CBOR map with a string and an integer as keys. 794Example: encode a CBOR map with a string and an integer as keys.
782 795
783 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"] 796 encode_cbor CBOR::XS::as_map [string => "value", 5 => "value"]

Diff Legend

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