# Items

Items are entities that make up the structure of a SECS message.
For the sake of this package, lists are also assumed to be items.

## Item types

| Type | Class | Code |
|---|---|---|
| List | {py:class}`secsgem.secs.items.ItemL` | L |
| Binary | {py:class}`secsgem.secs.items.ItemB` | B |
| Boolean | {py:class}`secsgem.secs.items.ItemBOOLEAN` | TF |
| ASCII | {py:class}`secsgem.secs.items.ItemA` | A |
| JIS-8 | {py:class}`secsgem.secs.items.ItemJ` | J |
| 8-Byte integer | {py:class}`secsgem.secs.items.ItemI8` | I8 |
| 1-Byte integer | {py:class}`secsgem.secs.items.ItemI1` | I1 |
| 2-Byte integer | {py:class}`secsgem.secs.items.ItemI2` | I2 |
| 4-Byte integer | {py:class}`secsgem.secs.items.ItemI4` | I4 |
| 8-Byte float | {py:class}`secsgem.secs.items.ItemF8` | F8 |
| 4-Byte float | {py:class}`secsgem.secs.items.ItemF4` | F8 |
| 8-Byte unsigned integer | {py:class}`secsgem.secs.items.ItemU8` | U8 |
| 1-Byte unsigned integer | {py:class}`secsgem.secs.items.ItemU1` | U1 |
| 2-Byte unsigned integer | {py:class}`secsgem.secs.items.ItemU2` | U2 |
| 4-Byte unsigned integer | {py:class}`secsgem.secs.items.ItemU4` | U4 |

## Creating items

### From value
Item objects can be created with the `from_value` method of the `Item` class.

```python
>>> import secsgem.secs.items
>>> 
>>> secsgem.secs.items.Item.from_value(10)
< U1 10 >
>>>
>>> secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U1 10 >
    < F4 2.5 >
>

```

This will automatically select the item type for the python values passed.
But this can be overridden by passing in a item object instead of a python value.

```python
>>> secsgem.secs.items.Item.from_value([secsgem.secs.items.ItemU4(10)])
< L [1]
    < U4 10 >
>

```

Specific item types can be initialized by using python values in the constructor.

```python
>>> secsgem.secs.items.ItemI4(10)
< I4 10 >
>>>
>>> secsgem.secs.items.ItemI4([10, 20])
< I4 10 20 >
>>>
>>> secsgem.secs.items.ItemL([10, 20])
< L [2]
    < U1 10 >
    < U1 20 >
>
>>>
>>> secsgem.secs.items.ItemI4("text")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/secsgem/secs/item.py", line 132, in __init__
    self._value = self.validate_value(value)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/secsgem/secs/item_number.py", line 77, in validate_value
    raise self._invalid_type_exception(value)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/secsgem/secs/item.py", line 508, in _invalid_type_exception
    raise TypeError(f"Invalid value '{data}' of '{data.__class__.__name__}' for '{cls.__name__}'")
TypeError: Invalid value 'text' of 'str' for 'ItemI4'
```

### From SML text

A item can also be created using a SML string.

```python
>>> secsgem.secs.items.Item.from_sml("< U4 10 >")
< U4 10 >
>>> 
>>> type(secsgem.secs.items.Item.from_sml("< U4 10 >"))
<class 'secsgem.secs.item_number.ItemU4'>
>>> 
>>> secsgem.secs.items.Item.from_sml("""
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U4 10 >
    < F4 2.5 >
>
""")
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U4 10 >
    < F4 2.5 >
>
```

### From protocol text

Binary data received via SECS-I/HSMS can be decoded using the classes decode method.

```python
>>> secsgem.secs.items.Item.decode(b'\x01\x03\x01\x02A\x05Hallo!\x04Welt\xa5\x01\n\x91\x04@ \x00\x00')
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U1 10 >
    < F4 2.5 >
>
```

## Getting data

### Python value

Python values from an item can be retrieved using the `value` attribute.

```python
>>> item = secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
>>> item.value
[['Hallo', b'Welt'], 10, 2.5]
```

### SML text

A SML string can be generated by using the `sml` attribute.

```python
>>> item = secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
>>> item.sml
'< L [3]\n    < L [2]\n        < A "Hallo">\n        < B 0x57 0x65 0x6c 0x74 >\n    >\n    < U1 10 >\n    < F4 2.5 >\n>'
```

The python output for the item object also prints the SML text

```python
>>> item = secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
>>> item
< L [3]
    < L [2]
        < A "Hallo">
        < B 0x57 0x65 0x6c 0x74 >
    >
    < U1 10 >
    < F4 2.5 >
>
```

### Protocol text

The SECS-I/HSMS protocol text can be generated using the `encode` method.

```python
>>> item = secsgem.secs.items.Item.from_value([["Hallo", b"Welt"], 10, 2.5])
>>> item.encode()
b'\x01\x03\x01\x02A\x05Hallo!\x04Welt\xa5\x01\n\x91\x04@ \x00\x00'
```