src/third_party/mozjs-45/python/pyasn1/doc/constructed.html

<html>
<title>
PyASN1 Constructed types
</title>
<head>
</head>
<body>
<center>
<table width=60%>
<tr>
<td>

<h4>
1.3 PyASN1 Constructed types
</h4>

<p>
Besides scalar types, ASN.1 specifies so-called constructed ones - these
are capable of holding one or more values of other types, both scalar
and constructed.
</p>

<p>
In pyasn1 implementation, constructed ASN.1 types behave like 
Python sequences, and also support additional component addressing methods,
specific to particular constructed type.
</p>

<a name="1.3.1"></a>
<h4>
1.3.1 Sequence and Set types
</h4>

<p>
The Sequence and Set types have many similar properties:
</p>
<ul>
<li>they can hold any number of inner components of different types
<li>every component has a human-friendly identifier
<li>any component can have a default value
<li>some components can be absent.
</ul>

<p>
However, Sequence type guarantees the ordering of Sequence value components
to match their declaration order. By contrast, components of the
Set type can be ordered to best suite application's needs.
<p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
Record ::= SEQUENCE {
  id        INTEGER,
  room  [0] INTEGER OPTIONAL,
  house [1] INTEGER DEFAULT 0
}
</pre>
</td></tr></table>

<p>
Up to this moment, the only method we used for creating new pyasn1 types
is Python sub-classing. With this method, a new, named Python class is created
what mimics type derivation in ASN.1 grammar. However, ASN.1 also allows for
defining anonymous subtypes (room and house components in the example above).
To support anonymous subtyping in pyasn1, a cloning operation on an existing
pyasn1 type object can be invoked what creates a new instance of original
object with possibly modified properties.
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
>>> from pyasn1.type import univ, namedtype, tag
>>> class Record(univ.Sequence):
...   componentType = namedtype.NamedTypes(
...     namedtype.NamedType('id', univ.Integer()),
...     namedtype.OptionalNamedType(
...       'room',
...       univ.Integer().subtype(
...         implicitTag=tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 0)
...       )
...     ),
...     namedtype.DefaultedNamedType(
...       'house', 
...       univ.Integer(0).subtype(
...         implicitTag=tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 1)
...       )
...     )
...   )
>>>
</pre>
</td></tr></table>

<p>
All pyasn1 constructed type classes have a class attribute <b>componentType</b>
that represent default type specification. Its value is a NamedTypes object.
</p>

<p>
The NamedTypes class instance holds a sequence of NameType, OptionalNamedType
or DefaultedNamedType objects which, in turn, refer to pyasn1 type objects that
represent inner SEQUENCE components specification.
</p>

<p>
Finally, invocation of a subtype() method of pyasn1 type objects in the code
above returns an implicitly tagged copy of original object.
</p>

<p>
Once a SEQUENCE or SET type is decleared with pyasn1, it can be instantiated
and initialized (continuing the above code):
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
>>> record = Record()
>>> record.setComponentByName('id', 123)
>>> print(record.prettyPrint())
Record:
 id=123
>>> 
>>> record.setComponentByPosition(1, 321)
>>> print(record.prettyPrint())
Record:
 id=123
 room=321
>>>
>>> record.setDefaultComponents()
>>> print(record.prettyPrint())
Record:
 id=123
 room=321
 house=0
</pre>
</td></tr></table>

<p>
Inner components of pyasn1 Sequence/Set objects could be accessed using the
following methods:
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
>>> record.getComponentByName('id')
Integer(123)
>>> record.getComponentByPosition(1)
Integer(321)
>>> record[2]
Integer(0)
>>> for idx in range(len(record)):
...   print(record.getNameByPosition(idx), record.getComponentByPosition(idx))
id 123
room 321
house 0
>>>
</pre>
</td></tr></table>

<p>
The Set type share all the properties of Sequence type, and additionally
support by-tag component addressing (as all Set components have distinct
types).
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
>>> from pyasn1.type import univ, namedtype, tag
>>> class Gamer(univ.Set):
...   componentType = namedtype.NamedTypes(
...     namedtype.NamedType('score', univ.Integer()),
...     namedtype.NamedType('player', univ.OctetString()),
...     namedtype.NamedType('id', univ.ObjectIdentifier())
...   )
>>> gamer = Gamer()
>>> gamer.setComponentByType(univ.Integer().getTagSet(), 121343)
>>> gamer.setComponentByType(univ.OctetString().getTagSet(), 'Pascal')
>>> gamer.setComponentByType(univ.ObjectIdentifier().getTagSet(), (1,3,7,2))
>>> print(gamer.prettyPrint())
Gamer:
 score=121343
 player=b'Pascal'
 id=1.3.7.2
>>>
</pre>
</td></tr></table>

<a name="1.3.2"></a>
<h4>
1.3.2 SequenceOf and SetOf types
</h4>

<p>
Both, SequenceOf and SetOf types resemble an unlimited size list of components.
All the components must be of the same type.
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
Progression ::= SEQUENCE OF INTEGER

arithmeticProgression Progression ::= { 1, 3, 5, 7 }
</pre>
</td></tr></table>

<p>
SequenceOf and SetOf types are expressed by the very similar pyasn1 type 
objects. Their components can only be addressed by position and they
both have a property of automatic resize.
</p>

<p>
To specify inner component type, the <b>componentType</b> class attribute
should refer to another pyasn1 type object.
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
>>> from pyasn1.type import univ
>>> class Progression(univ.SequenceOf):
...   componentType = univ.Integer()
>>> arithmeticProgression = Progression()
>>> arithmeticProgression.setComponentByPosition(1, 111)
>>> print(arithmeticProgression.prettyPrint())
Progression:
-empty- 111
>>> arithmeticProgression.setComponentByPosition(0, 100)
>>> print(arithmeticProgression.prettyPrint())
Progression:
100 111
>>>
>>> for idx in range(len(arithmeticProgression)):
...    arithmeticProgression.getComponentByPosition(idx)
Integer(100)
Integer(111)
>>>
</pre>
</td></tr></table>

<p>
Any scalar or constructed pyasn1 type object can serve as an inner component.
Missing components are prohibited in SequenceOf/SetOf value objects.
</p>

<a name="1.3.3"></a>
<h4>
1.3.3 Choice type
</h4>

<p>
Values of ASN.1 CHOICE type can contain only a single value of a type from a 
list of possible alternatives. Alternatives must be ASN.1 types with
distinct tags for the whole structure to remain unambiguous. Unlike most
other types, CHOICE is an untagged one, e.g. it has no base tag of its own.
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
CodeOrMessage ::= CHOICE {
  code    INTEGER,
  message OCTET STRING
}
</pre>
</td></tr></table>

<p>
In pyasn1 implementation, Choice object behaves like Set but accepts only
a single inner component at a time. It also offers a few additional methods
specific to its behaviour.
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
>>> from pyasn1.type import univ, namedtype
>>> class CodeOrMessage(univ.Choice):
...   componentType = namedtype.NamedTypes(
...     namedtype.NamedType('code', univ.Integer()),
...     namedtype.NamedType('message', univ.OctetString())
...   )
>>>
>>> codeOrMessage = CodeOrMessage()
>>> print(codeOrMessage.prettyPrint())
CodeOrMessage:
>>> codeOrMessage.setComponentByName('code', 123)
>>> print(codeOrMessage.prettyPrint())
CodeOrMessage:
 code=123
>>> codeOrMessage.setComponentByName('message', 'my string value')
>>> print(codeOrMessage.prettyPrint())
CodeOrMessage:
 message=b'my string value'
>>>
</pre>
</td></tr></table>

<p>
Since there could be only a single inner component value in the pyasn1 Choice
value object, either of the following methods could be used for fetching it
(continuing previous code):
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
>>> codeOrMessage.getName()
'message'
>>> codeOrMessage.getComponent()
OctetString(b'my string value')
>>>
</pre>
</td></tr></table>

<a name="1.3.4"></a>
<h4>
1.3.4 Any type
</h4>

<p>
The ASN.1 ANY type is a kind of wildcard or placeholder that matches
any other type without knowing it in advance. Like CHOICE type, ANY
has no base tag.
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
Error ::= SEQUENCE {
  code      INTEGER,
  parameter ANY DEFINED BY code
}
</pre>
</td></tr></table>

<p>
The ANY type is frequently used in specifications, where exact type is not
yet agreed upon between communicating parties or the number of possible
alternatives of a type is infinite.
Sometimes an auxiliary selector is kept around to help parties indicate
the kind of ANY payload in effect ("code" in the example above).
</p>

<p>
Values of the ANY type contain serialized ASN.1 value(s) in form of
an octet string. Therefore pyasn1 Any value object share the properties of
pyasn1 OctetString object.
</p>

<table bgcolor="lightgray" border=0 width=100%><TR><TD>
<pre>
>>> from pyasn1.type import univ
>>> someValue = univ.Any(b'\x02\x01\x01')
>>> someValue
Any(b'\x02\x01\x01')
>>> str(someValue)
'\x02\x01\x01'
>>> bytes(someValue)
b'\x02\x01\x01'
>>>
</pre>
</td></tr></table>

<p>
Receiving application is supposed to explicitly deserialize the content of Any
value object, possibly using auxiliary selector for figuring out its ASN.1
type to pick appropriate decoder.
</p>

<p>
There will be some more talk and code snippets covering Any type in the codecs
chapters that follow.
</p>

<hr>

</td>
</tr>
</table>
</center>
</body>
</html>