TLV
===

The :mod:`alc.tlv` module contains some functions and classes that help in handling TLV-encoded data.

.. module:: alc.tlv

Decoding a list of TLVs
-----------------------

.. function:: decode(data, tlen=1, llen=1, inclusive=False)

    Retrieves an iterator to iterate over the decoded TLV entries.

    :param bytes data: TLV encoded string to search in
    :param int tlen: length, in bytes, of the type-field
    :param int llen: length, in bytes, of the length-field
    :param bool inclusive: whether the length includes the lengths of both type- and length-fields
    :return: iterator that iterates the entries, returning a tuple of (type, value)

Encoding a list of TLVs
-----------------------

.. function:: encode(items, tlen=1, llen=1, inclusive=False)
    
    Encodes a list of items into a bytes representation.

    :param items: An iterable of tv-pairs, of types (int, bytes).
    :param int tlen: length, in bytes, of the type-field
    :param int llen: length, in bytes, of the length-field
    :param bool inclusive: whether the length includes the lengths of both type- and length-fields
    :return: bytes object encoding the list of tlv-pairs

Finding a specific TLV
----------------------

.. function:: find(data, type, tlen=1, llen=1, inclusive=False)

    Finds the value for a specific type in a TLV encoded string.

    :param bytes data: TLV encoded string to search in
    :param int type: value of the type to search for
    :param int tlen: length, in bytes, of the type-field
    :param int llen: length, in bytes, of the length-field
    :param bool inclusive: whether the length includes the lengths of both type- and length-fields
    :return: the value corresponding with the type, or None if not present

The :class:`alc.tlv.TLV` object
-------------------------------

 .. py:class:: TLV(tlen=1, llen=1, inclusive=False)

    Creates a TLV object that works with a specific type of TLV encoded data.

    :param int tlen: length, in bytes, of the type-field
    :param int llen: length, in bytes, of the length-field
    :param bool inclusive: whether the length includes the lengths of both type- and length-fields

    .. method:: find(self, data, type)
    
        Finds the value for a specific type in a TLV encoded string.
    
        :param bytes data: TLV encoded string to search in
        :param type: value of the type to search for
        :return: the value corresponding with the type, or None if not present
    
    .. method:: decode(self, data):
    
        Retrieves an iterator to iterate over the decoded TLV entries.
        
        :param bytes data: TLV encoded string to search in
        :return: iterator that iterates the entries, returning a tuple of (type, value)
    
    .. method:: encode(self, items):
    
        Encodes a list of items into a bytes representation.
    
        :param items: An iterable of tlv-pairs, of types (int, bytes).
        :return: bytes object encoding the list of tlv-pairs


Example
-------

Creates a bytes object which contains some TLV-encoded data. Both type and length fields are one byte and the length field is inclusive::

      from ubinascii import unhexlify
      data = unhexlify(b"0105666f6f1905626172")

Use the alc.tlv module to list the items or search for a specific item.
The defaults for tlen and llen are correct, but a value must be specified for inclusive::

      from alc import tlv
      list(tlv.decode(data, inclusive=True)) #[(1, b'foo'), (25, b'bar')]
      tlv.find(data, 25, inclusive=True) #b'bar'

If the type of TLV encoding is different from the default values, an object can be created which encapsulates the type of encoding.
This object can be used to work with this kind of tlv-strings without the need of passing the same parameters again and again::

    tlv11i = tlv.TLV(tlen=1, llen=1, inclusive=True)
    list(tlv11i.decode(data)) # [(1, b'foo'), (25, b'bar')]
    tlv11i.find(data, 1) # b'foo'

When the format of the data is not as expected and decoding fails, a ValueError is raised::

    tlv24 = tlv.TLV(tlen=2, llen=4)
    list(tlv24.decode(data))

    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    ValueError: invalid tlv encoded data

Encoding a list of type-value pairs into a bytes object::

    tlv11i.encode([(1, b'foo'), (25, b'bar')]) # b'0105666f6f1905626172'


.. _breaking-tlv:

Breaking changes
----------------

.. warning::
    The functions provided in this module were previously added onto the str class in the Python 2 API. With the Python 3 API, these functions have been removed from the str-class and this module should be used instead.