# 1. iris-dollar-list
[](https://pypi.org/project/iris-dollar-list/)
[](https://pypi.org/project/iris-dollar-list/)
[](https://github.com/grongierisc/iris-dollar-list/blob/main/LICENSE)
[](https://github.com/grongierisc/iris-dollar-list/actions)
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 :**
```sh
pip3 install iris-dollar-list
```
It is compatible with embedded python and native api.
## 1.1. Table of Contents
- [1. iris-dollar-list](#1-iris-dollar-list)
- [1.1. Table of Contents](#11-table-of-contents)
- [1.2. Usage](#12-usage)
- [1.3. functions](#13-functions)
- [1.3.1. append](#131-append)
- [1.3.2. from_bytes](#132-from_bytes)
- [1.3.3. from_list](#133-from_list)
- [1.3.4. from_string](#134-from_string)
- [1.3.5. to_bytes](#135-to_bytes)
- [1.3.6. to_list](#136-to_list)
- [2. $list](#2-list)
- [2.1. What is $list ?](#21-what-is-list-)
- [2.2. How it works ?](#22-how-it-works-)
- [2.2.1. Header](#221-header)
- [2.2.1.1. Size](#2211-size)
- [2.2.1.2. Type](#2212-type)
- [2.2.2. Body](#222-body)
- [2.2.2.1. Ascii](#2221-ascii)
- [2.2.2.2. Unicode](#2222-unicode)
- [2.2.2.3. Int](#2223-int)
- [2.2.2.4. Negative Int](#2224-negative-int)
- [2.2.2.5. Float](#2225-float)
- [2.2.2.6. Negative Float](#2226-negative-float)
- [2.2.2.7. Double](#2227-double)
- [2.2.2.8. Compact Double](#2228-compact-double)
- [2.3. Development](#23-development)
## 1.2. Usage
example :
```objectscript
set ^list = $lb("test",$lb(4))
```
example of use with native api :
```python
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 :
```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
```python
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))
# $lb("one",1,$lb("list",2),"item")
```
### 1.3.2. from_bytes
Create a DollarList from bytes.
```python
my_list = DollarList.from_bytes(b'\x05\x01one')
print(my_list)
# $lb("one")
```
### 1.3.3. from_list
Create a DollarList from a list.
```python
print(DollarList.from_list(["list",2]))
# $lb("list",2)
```
### 1.3.4. from_string
Create a DollarList from a string.
```python
str_list = DollarList.from_string('$lb("test",$lb(4))')
print(str_list)
# $lb("test",$lb(4))
print(str_list.to_list())
# ['test', [4]]
```
### 1.3.5. to_bytes
Convert the DollarList to bytes.
```python
my_list = DollarList.from_list(["list",2])
print(my_list.to_bytes())
# b'\x06\x01list\x03\x04\x02'
```
### 1.3.6. to_list
Convert the DollarList to a list.
```python
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.
The header can have a size of 2, 4 or 8 bytes.
Three types of header are possible :
* 2 bytes header
* 1 byte for the size
* 1 byte for the type
* 4 bytes header
* 1 bytes of \x00
* 2 bytes for the size
* 1 byte for the type
* 8 bytes header
* 3 bytes of \x00
* 4 bytes for the size
* 1 byte for the type
#### 2.2.1.1. Size
There is 3 types of size :
* 1 byte, if the first byte is not \x00
* 2 bytes, if the first byte is \x00 and the int value of the second two bytes is not 0
* 4 bytes, else (the first 3 bytes are \x00)
#### 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.
#### 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
Raw data
{
"_id": null,
"home_page": "https://github.com/grongierisc/iris-dollar-list",
"name": "iris-dollar-list",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "iris-dollar-list",
"author": "grongier",
"author_email": "guillaume.rongier@intersystems.com",
"download_url": "https://files.pythonhosted.org/packages/fe/df/66dfea224aeb71e609defe9c6ed5fb4ca8a510e88c8db1a3399bcc97737e/iris-dollar-list-0.9.6.tar.gz",
"platform": null,
"description": "# 1. iris-dollar-list\n\n[](https://pypi.org/project/iris-dollar-list/)\n[](https://pypi.org/project/iris-dollar-list/)\n[](https://github.com/grongierisc/iris-dollar-list/blob/main/LICENSE)\n[](https://github.com/grongierisc/iris-dollar-list/actions)\n\nInterpretor of $list for python named DollarList.\n\nThis interpretor was made because :\n * I wanted to use $list in python. \n * Embedded Python do not support $list. \n * The native API version do not support embedded $list in $list. \n\nThis is a work in progress. For now, it only support embedded $list in $list, int and string.\n\nWIP float,decimal,double\n\n **This module is available on Pypi :**\n\n```sh\npip3 install iris-dollar-list\n```\n\nIt is compatible with embedded python and native api.\n\n## 1.1. Table of Contents\n\n- [1. iris-dollar-list](#1-iris-dollar-list)\n - [1.1. Table of Contents](#11-table-of-contents)\n - [1.2. Usage](#12-usage)\n - [1.3. functions](#13-functions)\n - [1.3.1. append](#131-append)\n - [1.3.2. from_bytes](#132-from_bytes)\n - [1.3.3. from_list](#133-from_list)\n - [1.3.4. from_string](#134-from_string)\n - [1.3.5. to_bytes](#135-to_bytes)\n - [1.3.6. to_list](#136-to_list)\n- [2. $list](#2-list)\n - [2.1. What is $list ?](#21-what-is-list-)\n - [2.2. How it works ?](#22-how-it-works-)\n - [2.2.1. Header](#221-header)\n - [2.2.1.1. Size](#2211-size)\n - [2.2.1.2. Type](#2212-type)\n - [2.2.2. Body](#222-body)\n - [2.2.2.1. Ascii](#2221-ascii)\n - [2.2.2.2. Unicode](#2222-unicode)\n - [2.2.2.3. Int](#2223-int)\n - [2.2.2.4. Negative Int](#2224-negative-int)\n - [2.2.2.5. Float](#2225-float)\n - [2.2.2.6. Negative Float](#2226-negative-float)\n - [2.2.2.7. Double](#2227-double)\n - [2.2.2.8. Compact Double](#2228-compact-double)\n - [2.3. Development](#23-development)\n\n## 1.2. Usage\n\nexample :\n\n```objectscript\nset ^list = $lb(\"test\",$lb(4))\n```\n\nexample of use with native api : \n \n\n```python\nimport iris\nfrom iris_dollar_list import DollarList\n \nconn = iris.connect(\"localhost\", 57161,\"IRISAPP\", \"SuperUser\", \"SYS\")\n \niris_obj = iris.createIRIS(conn)\n \ngl = iris_obj.get(\"^list\")\n \nmy_list = DollarList.from_bytes(gl.encode('ascii'))\n \nprint(my_list.to_list())\n# ['test', [4]]\n```\n\nexample of use with embedded python :\n\n```python\nimport iris\nfrom iris_dollar_list import DollarList\n \ngl = iris.gref(\"^list\")\n \nmy_list = DollarList.from_bytes(gl[None].encode('ascii'))\n \nprint(my_list.to_list())\n# ['test', [4]]\n```\n\n## 1.3. functions\n\n### 1.3.1. append\n\nAppend an element to the list.\n\nThis element can be :\n * a string\n * an int\n * a DollarList\n * a DollarItem\n\n```python\nmy_list = DollarList()\nmy_list.append(\"one\")\nmy_list.append(1)\nmy_list.append(DollarList.from_list([\"list\",2]))\nmy_list.append(DollarItem(dollar_type=1, value=\"item\",\n raw_value=b\"item\",\n buffer=b'\\x06\\x01item'))\nprint(DollarList.from_bytes(my_list))\n# $lb(\"one\",1,$lb(\"list\",2),\"item\")\n```\n\n### 1.3.2. from_bytes\n\nCreate a DollarList from bytes.\n\n```python\nmy_list = DollarList.from_bytes(b'\\x05\\x01one')\nprint(my_list)\n# $lb(\"one\")\n```\n\n### 1.3.3. from_list\n\nCreate a DollarList from a list.\n\n```python\nprint(DollarList.from_list([\"list\",2]))\n# $lb(\"list\",2)\n```\n\n### 1.3.4. from_string\n\nCreate a DollarList from a string.\n\n```python\nstr_list = DollarList.from_string('$lb(\"test\",$lb(4))')\nprint(str_list)\n# $lb(\"test\",$lb(4))\nprint(str_list.to_list())\n# ['test', [4]]\n```\n\n### 1.3.5. to_bytes\n\nConvert the DollarList to bytes.\n\n```python\nmy_list = DollarList.from_list([\"list\",2])\nprint(my_list.to_bytes())\n# b'\\x06\\x01list\\x03\\x04\\x02'\n```\n\n### 1.3.6. to_list\n\nConvert the DollarList to a list.\n\n```python\nmy_list = DollarList.from_bytes(b'\\x05\\x01one')\nprint(my_list.to_list())\n# ['one']\n```\n\n# 2. $list\n\n## 2.1. What is $list ?\n\n$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.\n\nThe neat thing about $list is that it is not limited for storage. It also used for communication on the SuperServer port of IRIS.\n\n## 2.2. How it works ?\n\n$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.\n\n### 2.2.1. Header\n\nThe header is composed of a size and a type. \nThe header can have a size of 2, 4 or 8 bytes.\n\nThree types of header are possible :\n * 2 bytes header\n * 1 byte for the size\n * 1 byte for the type\n * 4 bytes header\n * 1 bytes of \\x00\n * 2 bytes for the size\n * 1 byte for the type\n * 8 bytes header\n * 3 bytes of \\x00\n * 4 bytes for the size\n * 1 byte for the type\n\n#### 2.2.1.1. Size\n\nThere is 3 types of size :\n * 1 byte, if the first byte is not \\x00\n * 2 bytes, if the first byte is \\x00 and the int value of the second two bytes is not 0\n * 4 bytes, else (the first 3 bytes are \\x00)\n\n#### 2.2.1.2. Type\n\nThe type is a byte that represent the type of the value. \nThe type is stored just after the size.\n\nList of types:\n * ascii: 0x01\n * unicode: 0x02\n * int: 0x04\n * negative int: 0x05\n * float: 0x06\n * negative float: 0x07\n * double: 0x08\n * compact double: 0x09\n\n### 2.2.2. Body\n\nThe body is composed of the value.\n\nTo parse the body, you need to know the type of the value.\n\n#### 2.2.2.1. Ascii\n\nDecode the value as ascii.\n\nIf decoding fails, consider the value as a sub-list.\n\nIf decoding the sub-list fails, consider the value as a binary.\n\n#### 2.2.2.2. Unicode\n\nDecode the value as unicode.\n\n#### 2.2.2.3. Int\n\nParse the value as an integer in little endian and unsigned.\n\n#### 2.2.2.4. Negative Int\n\nParse the value as an integer in little endian and signed.\n\n#### 2.2.2.5. Float\n\n????\n\n#### 2.2.2.6. Negative Float\n\n????\n\n#### 2.2.2.7. Double\n\n????\n\n#### 2.2.2.8. Compact Double\n\n????\n\n\n## 2.3. Development\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "iris-dollar-list",
"version": "0.9.6",
"project_urls": {
"Homepage": "https://github.com/grongierisc/iris-dollar-list"
},
"split_keywords": [
"iris-dollar-list"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6abda09cff3661edee0d7144137e6f6ae8ee655e5409d55308e3877c36c39d0e",
"md5": "31889fec315bbc9ecff9d67e02069579",
"sha256": "dffd2d16f60de0477d05f1795857011253c251ea41a143b62e2ef8c38b380ab6"
},
"downloads": -1,
"filename": "iris_dollar_list-0.9.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "31889fec315bbc9ecff9d67e02069579",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8570,
"upload_time": "2023-08-02T12:11:54",
"upload_time_iso_8601": "2023-08-02T12:11:54.522709Z",
"url": "https://files.pythonhosted.org/packages/6a/bd/a09cff3661edee0d7144137e6f6ae8ee655e5409d55308e3877c36c39d0e/iris_dollar_list-0.9.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fedf66dfea224aeb71e609defe9c6ed5fb4ca8a510e88c8db1a3399bcc97737e",
"md5": "37240cf73a5d3b779391a099f31e6422",
"sha256": "e7ca7a65d06bb69538805ca5e2b1eb912ede22f7a1338533d561e173c3199b7a"
},
"downloads": -1,
"filename": "iris-dollar-list-0.9.6.tar.gz",
"has_sig": false,
"md5_digest": "37240cf73a5d3b779391a099f31e6422",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10252,
"upload_time": "2023-08-02T12:12:00",
"upload_time_iso_8601": "2023-08-02T12:12:00.847461Z",
"url": "https://files.pythonhosted.org/packages/fe/df/66dfea224aeb71e609defe9c6ed5fb4ca8a510e88c8db1a3399bcc97737e/iris-dollar-list-0.9.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-02 12:12:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "grongierisc",
"github_project": "iris-dollar-list",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "iris-dollar-list"
}
JSON
