File Coverage

blib/lib/CBOR/Free/Decoder.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             package CBOR::Free::Decoder;
2              
3             =encoding utf8
4              
5             =head1 NAME
6              
7             CBOR::Free::Decoder
8              
9             =head1 SYNOPSIS
10              
11             my $decoder = CBOR::Free::Decoder->new()->set_tag_handlers(
12             2 => sub { DateTime->from_epoch( epoch => shift() ) },
13             );
14              
15             # Enable shared/circular references:
16             $decoder->preserve_references();
17              
18             =head1 DESCRIPTION
19              
20             This class provides an object-oriented interface to L’s
21             decoder. This interface allows interpretation of tagged values.
22              
23             =cut
24              
25             #----------------------------------------------------------------------
26              
27 6     6   100008 use parent qw( CBOR::Free::Decoder::Base );
  6         20  
  6         29  
28              
29 6     6   551 use CBOR::Free ();
  6         13  
  6         171  
30              
31             #----------------------------------------------------------------------
32              
33             =head1 METHODS
34              
35             =head2 $obj = I->new()
36              
37             Creates a new CBOR decoder object.
38              
39             =cut
40              
41             #----------------------------------------------------------------------
42              
43             =head2 $data = I->decode( $CBOR )
44              
45             Same as L’s static function of the same name but applies
46             any tag handlers configured in C.
47              
48             As in L, any unrecognized tags prompt a warning but are
49             otherwise ignored.
50              
51             =cut
52              
53             #----------------------------------------------------------------------
54              
55             =head2 $enabled_yn = I->preserve_references( [$ENABLE] )
56              
57             Enables/disables recognition of CBOR’s shared references. (If no
58             argument is given, shared references will be enabled.)
59              
60             B This option can cause CBOR::Free to create circular
61             references, which can cause memory leaks if not handled properly.
62              
63             =cut
64              
65             #----------------------------------------------------------------------
66              
67             =head2 $enabled_yn = I->naive_utf8( [$ENABLE] )
68              
69             Same interface as C, but this option tells I
70             to forgo UTF-8 validation of CBOR text strings when enabled. This speeds up
71             decoding of text strings but may confuse Perl if invalid UTF-8 is given in
72             a CBOR text string. That may or may not break your application.
73              
74             This I be safe in contexts—such as IPC—where you control the CBOR
75             serialization and can thus ensure validity of the encoded text.
76              
77             If in doubt, leave this off.
78              
79             =cut
80              
81             #----------------------------------------------------------------------
82              
83             =head2 $obj = I->string_decode_cbor();
84              
85             This causes I to decode strings according to their CBOR type:
86             text strings are UTF8-decoded; binary strings are left as-is. This is
87             the default configuration, à la C.
88              
89             =head2 $obj = I->string_decode_never();
90              
91             This causes I to leave all strings undecoded. This is useful for
92             applications that treat all strings as octet sequences. Note that CBOR
93             text strings will still be validated as UTF-8 unless C is
94             enabled.
95              
96             =head2 $obj = I->string_decode_always();
97              
98             This causes I to decode all CBOR strings (including binary strings)
99             as UTF-8, applying appropriate pre-validation unless C is
100             enabled. This is useful if you expect all strings (including binary) to be
101             UTF-8 and want to handle them in Perl as character strings instead of
102             byte strings.
103              
104             =head2 I->set_tag_handlers( %TAG_CALLBACK )
105              
106             Takes a list of key/value pairs where each key is a tag (i.e., number)
107             and each value is a coderef that CBOR::Free will run when that tag is
108             seen during a decode operation. The coderef will receive the tagged value,
109             and its (scalar) return will be inserted into the decoded data structure.
110              
111             To unset a tag handler, assign undef to it.
112              
113             This returns the I.
114              
115             B Handlers assigned here will only fire if CBOR::Free itself
116             doesn’t decode the tag. For example, a handler for the “indirection” tag
117             here will be ignored.
118              
119             =cut
120              
121             1;