CBOR-XS/doc/indirection.pod

=head1 REGISTRATION INFORMATION

   Tag             22098 (indirection)
   Data Item       multiple
   Semantics       hint that indicates an additional level of indirection
   Reference       http://cbor.schmorp.de/indirection
   Contact         Marc A. Lehmann <cbor@schmorp.de>

=head1 SUMMARY

This tag indicates an additional level of indirection when
decoding a value.

=head1 BACKGROUND

Data structures in some languages or data models sometimes employ
references, pointers or similar forms of indirection to represent
relationships between values. For example, in Perl, CBOR arrays are
usually represented as references to perl arrays, rather than arrays
themselves, while simple scalar values are represented as these values
themselves. However, CBOR leaves explicit references unencodable - while
arrays and maps might implicitly result in references, references to
simple values, or references to references are not representable.

For example, in Perl:

   { 1, 2, 3, 4 } # reference to a hash, becomes CBOR map
   [ 1, 2, 3, 4 } # reference to an array, becomes CBOR array
   \5             # reference to the scalar value 5, needs extension
   \[]            # reference to a reference to an array, needs extension

This tag allows to encode such references - prefixing a value with this
tag indicates a hint to the decoder that the original value was actually
a reference. Decoders can chose to heed the hint (if their data model has
a convenient representation), or simply ignore it and decode the value
as-is.

For example, CBOR encoders for Perl would not use the indirection tag for
hash and array references, as the only way to reference these values in a
data structure is already by reference. However, references to strings,
numbers, other references or other complex objects would be encoded by
tagging the referenced value with the indirection tag.

Indirection tags can be nested - each additional level of nesting would
indicate an additional indirection.

=head1 EXAMPLES

The following Perl data structure is an array containing a reference to an
array, followed by a reference to a string:

   [[], \"string"]

Since Perl cannot have "naked" arrays or maps inside another data
structure, but only a reference to it, the natural encoding of this
data structure uses a normal array for the array-reference (i.e. it
omits the reference). The string reference is uncommon but valid, and
not the natural way to store a string inside another data structure. An
encoder might therefore chose to encode this string reference using the
indirection tag:

   256([[], 22098("string")])

   d9 0100                  # tag(256)
      82                    # array(2)
         80                 # array(0)
         d9 5652            # tag(22098)
            66              # text(6)
               737472696e67 # "string"

=head1 IMPLEMENTATIONS

This section lists known implementations of this extension (L<drop me a
mail|mailto:cbor@schmorp.de?Subject=CBOR-indirection> if you want to be
listed here).

=over 4

=item * [Perl] L<CBOR::XS|http://software.schmorp.de/pkg/CBOR-XS.html> (reference implementation)

=back

Revision:	1.3
Committed:	Tue Dec 27 21:24:33 2016 UTC (9 years, 8 months ago) by root
Branch:	MAIN
CVS Tags:	rel-1_71, rel-1_7
Changes since 1.2:	+10 -0 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 REGISTRATION INFORMATION
2
3			Tag 22098 (indirection)
4			Data Item multiple
5			Semantics hint that indicates an additional level of indirection
6			Reference http://cbor.schmorp.de/indirection
7			Contact Marc A. Lehmann <cbor@schmorp.de>
8
9			=head1 SUMMARY
10
11			This tag indicates an additional level of indirection when
12			decoding a value.
13
14			=head1 BACKGROUND
15
16			Data structures in some languages or data models sometimes employ
17			references, pointers or similar forms of indirection to represent
18			relationships between values. For example, in Perl, CBOR arrays are
19			usually represented as references to perl arrays, rather than arrays
20			themselves, while simple scalar values are represented as these values
21			themselves. However, CBOR leaves explicit references unencodable - while
22			arrays and maps might implicitly result in references, references to
23			simple values, or references to references are not representable.
24
25			For example, in Perl:
26
27			{ 1, 2, 3, 4 } # reference to a hash, becomes CBOR map
28			[ 1, 2, 3, 4 } # reference to an array, becomes CBOR array
29			\5 # reference to the scalar value 5, needs extension
30			\[] # reference to a reference to an array, needs extension
31
32			This tag allows to encode such references - prefixing a value with this
33			tag indicates a hint to the decoder that the original value was actually
34			a reference. Decoders can chose to heed the hint (if their data model has
35			a convenient representation), or simply ignore it and decode the value
36			as-is.
37
38			For example, CBOR encoders for Perl would not use the indirection tag for
39			hash and array references, as the only way to reference these values in a
40			data structure is already by reference. However, references to strings,
41			numbers, other references or other complex objects would be encoded by
42			tagging the referenced value with the indirection tag.
43
44			Indirection tags can be nested - each additional level of nesting would
45			indicate an additional indirection.
46
47			=head1 EXAMPLES
48
49	root	1.2	The following Perl data structure is an array containing a reference to an
50			array, followed by a reference to a string:
51
52			[[], \"string"]
53
54			Since Perl cannot have "naked" arrays or maps inside another data
55			structure, but only a reference to it, the natural encoding of this
56			data structure uses a normal array for the array-reference (i.e. it
57			omits the reference). The string reference is uncommon but valid, and
58			not the natural way to store a string inside another data structure. An
59			encoder might therefore chose to encode this string reference using the
60			indirection tag:
61
62			256([[], 22098("string")])
63
64			d9 0100 # tag(256)
65			82 # array(2)
66			80 # array(0)
67			d9 5652 # tag(22098)
68			66 # text(6)
69			737472696e67 # "string"
70
71	root	1.3	=head1 IMPLEMENTATIONS
72	root	1.2
73	root	1.3	This section lists known implementations of this extension (L<drop me a
74			mail\|mailto:cbor@schmorp.de?Subject=CBOR-indirection> if you want to be
75			listed here).
76
77			=over 4
78
79			=item * [Perl] L<CBOR::XS\|http://software.schmorp.de/pkg/CBOR-XS.html> (reference implementation)
80
81			=back
82	root	1.1