1. iris-dollar-list

Interpretor of $list for python named DollarList.

This interpretor was made because :

• I wanted to use $list in python.
• Embedded Python do not support $list.
• The native API version do not support embedded $list in $list.

This is a work in progress. For now, it only support embedded $list in $list, int and string.

WIP float,decimal,double

This module is available on Pypi :

pip3 install iris-dollar-list

It is compatible with embedded python and native api.

1.1. Table of Contents

• 1. iris-dollar-list
  • 1.1. Table of Contents
  • 1.2. Usage
  • 1.3. functions
  • 1.3.1. append
  • 1.3.2. from_bytes
  • 1.3.3. from_list
  • 1.3.4. to_bytes
  • 1.3.5. to_list
• 2. $list
  • 2.1. What is $list ?
  • 2.2. How it works ?
  • 2.2.1. Header
    • 2.2.1.1. Size
    • 2.2.1.2. Type
  • 2.2.2. Body
    • 2.2.2.1. Ascii
    • 2.2.2.2. Unicode
    • 2.2.2.3. Int
    • 2.2.2.4. Negative Int
    • 2.2.2.5. Float
    • 2.2.2.6. Negative Float
    • 2.2.2.7. Double
    • 2.2.2.8. Compact Double
  • 2.3. Development

1.2. Usage

example :

set ^list = $lb("test",$lb(4))

example of use with native api :

import iris
from iris_dollar_list import DollarList

conn = iris.connect("localhost", 57161,"IRISAPP", "SuperUser", "SYS")

iris_obj = iris.createIRIS(conn)

gl = iris_obj.get("^list")

my_list = DollarList.from_bytes(gl.encode('ascii'))

print(my_list.to_list())
# ['test', [4]]

example of use with embedded python :

import iris
from iris_dollar_list import DollarList

gl = iris.gref("^list")

my_list = DollarList.from_bytes(gl[None].encode('ascii'))

print(my_list.to_list())
# ['test', [4]]

1.3. functions

1.3.1. append

Append an element to the list.

This element can be :
* a string
* an int
* a DollarList
* a DollarItem

my_list = DollarList()
my_list.append("one")
my_list.append(1)
my_list.append(DollarList.from_list(["list",2]))
my_list.append(DollarItem(dollar_type=1, value="item",
                          raw_value=b"item",
                          buffer=b'\x06\x01item'))
print(DollarList.from_bytes(my_list.to_bytes()))
# $lb("one",1,$lb("list",2),"item")

1.3.2. from_bytes

Create a DollarList from bytes.

my_list = DollarList.from_bytes(b'\x05\x01one')
print(my_list)
# $lb("one")

1.3.3. from_list

Create a DollarList from a list.

print(DollarList.from_list(["list",2]))
# $lb("list",2)

1.3.4. to_bytes

Convert the DollarList to bytes.

my_list = DollarList.from_list(["list",2])
print(my_list.to_bytes())
# b'\x06\x01list\x03\x04\x02'

1.3.5. to_list

Convert the DollarList to a list.

my_list = DollarList.from_bytes(b'\x05\x01one')
print(my_list.to_list())
# ['one']

2. $list

2.1. What is $list ?

$list is binary format for storing data. It is used in Iris Engine. It is a format that is easy to read and write. It is also easy to parse.

The neat thing about $list is that it is not limited for storage. It also used for communication on the SuperServer port of IRIS.

2.2. How it works ?

$list is a binary format that store list of values. Each value is stored in a block. Each block is composed of a header and a body. The header is composed of a size and a type. The body is composed of the value.

2.2.1. Header

The header is composed of a size and a type.

2.2.1.1. Size

The size dictates the size of the block. The size is stored in N bytes.
N is determined by the number of bytes that are zero in the first bytes of the header.
The size is stored in little endian.

2.2.1.2. Type

The type is a byte that represent the type of the value.
The type is stored just after the size.

List of types:
* ascii: 0x01
* unicode: 0x02
* int: 0x04
* negative int: 0x05
* float: 0x06
* negative float: 0x07
* double: 0x08
* compact double: 0x09

2.2.2. Body

The body is composed of the value.

To parse the body, you need to know the type of the value.

2.2.2.1. Ascii

Decode the value as ascii.

If decoding fails, consider the value as a sub-list.

If decoding the sub-list fails, consider the value as a binary.

2.2.2.2. Unicode

Decode the value as unicode.

2.2.2.3. Int

Parse the value as an integer in little endian and unsigned.

2.2.2.4. Negative Int

Parse the value as an integer in little endian and signed.