# CSM-API-String-Arguments-Support

**Repository Path**: NEVSTOP-LAB/CSM-API-String-Arguments-Support

## Basic Information

- **Project Name**: CSM-API-String-Arguments-Support
- **Description**: Enhance API String Arguments support of Communicable State Machine(CSM)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-04-26
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: LabVIEW-CSM, labview

## README

# CSM-API-String-Arguments-Support

[English](./README.md) | [中文](./README(zh-cn).md)

[![Installs](https://www.vipm.io/package/nevstop_lib_csm_api_string_arguments_support/badge.svg?metric=installs)](https://www.vipm.io/package/nevstop_lib_csm_api_string_arguments_support/)
[![Stars](https://www.vipm.io/package/nevstop_lib_csm_api_string_arguments_support/badge.svg?metric=stars)](https://www.vipm.io/package/nevstop_lib_csm_api_string_arguments_support/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![GitHub Downloads](https://img.shields.io/github/downloads/NEVSTOP-LAB/CSM-API-String-Arguments-Support/total)](https://github.com/NEVSTOP-LAB/CSM-API-String-Arguments-Support/releases)

This library extends the [CSM](https://github.com/NEVSTOP-LAB/Communicable-State-Machine) (Communicable State Machine) framework's API parameters to support various data types in plain text format.

It also includes two templates with built-in `Data: Get Configuration`, `Data: Set Configuration`, and `Data: Get Internal Data` states — a ready-to-use starting point for CSM modules that need to read and write data in the `>> internal data >>` shift register.

![example](.github/doc.png)

## Supported Data Types

- String
- Path
- Tag
- Refnum (IVI/VISA/UserDefinedRefnumTag)
- Boolean
- Integer (I8,I16,I32,I64,U8,U16,U32,U64)
- Float (DBL/SGL)
- Complex (DBL/SGL)
- Timestamp
- Enum
- Array
- Cluster
- Other (using CSM-Hexstr)

### String/Path/Refnum(IVI/VISA/UserDefinedRefnumTag)/Tag

For String/Path data types, CSM keywords like '->|', '->', '-@', '-&', '>>', ',', and ';' are automatically replaced with %[Hex] strings before passing, similar to how **CSM AdvanceAPI\CSM Make String Arguments Safe.vi** works.

> [!NOTE]
> Refnum(IVI/VISA/UserDefinedRefnumTag) and Tag are also supported, following the same rules as the String type.

### Boolean

Predefined TRUE/FALSE String Pairs:

```text
TRUE/FALSE String Pairs:
  - T/F
  - True/False
  - On/Off
  - Enable/Disable
  - Active/Inactive
  - valid/Invalid
  - 1/0
  - Open/Close
  - Non-null/null
```

> [!NOTE]
> For Boolean values, an empty string will be converted to the input prototype value

> [!NOTE]
> Use `API String - Add Boolean Strings.vi` or `API String - Remove Boolean Strings.vi` to customize your own boolean string pairs.

> [!NOTE]
> Tag-value pairs (Tag:Value) can be parsed correctly. Tags improve readability and are ignored during conversion.

### Integer

Supported formats: Normal, Hex, Binary, Octal, Hex with suffix H, Octal with suffix O, Binary with suffix B, Decimal with suffix D. Examples:

```text
  - 12345
  - 0d12345
  - 0x1234
  - 0b10101010
  - 0o777
  - 1234H
  - 10101010H
  - 7777O
  - 10k
  - 1M
```

> [!NOTE]
> For Integer values, an empty string will be converted to the input prototype value

> [!NOTE]
> Tag-value pair(Tag:Value) could be parsed correctly. Tag is used for readability and will be ignored during conversion.

### Float(DBL/SGL)

Supported formats: Normal Float, Scientific Notation, Special Float. Examples:

```text
  - 1.2345
  - 1.23E+2
  - 1.23E-2
  - 1.23Y (1.23×10^24)
  - 1.23Z (1.23×10^21)
  - 1.23E (1.23×10^18)
  - 1.23P (1.23×10^15)
  - 1.23T (1.23×10^12)
  - 1.23G (1.23×10^9)
  - 1.23M (1.23×10^6)
  - 1.23k (1.23×10^3)
  - 1.23m (1.23×0.001)
  - 1.23u (1.23×0.000001)
  - 1.23n (1.23×10^-9)
  - 1.23p (1.23×10^-12)
  - 1.23f (1.23×10^-15)
  - 1.23a (1.23×10^-18)
  - 1.23z (1.23×10^-21)
  - 1.23y (1.23×10^-24)
  - Special Float: `e`,`-e`,`pi`,`-pi`,`inf`,`+inf`,`-inf`,`NaN`
```

> [!NOTE]
> For Float values, an empty string will be converted to the input prototype value.

> [!NOTE]
> Default precision is 6 decimal places. You can change it using `API String - Set Float Precision.vi`.

> [!NOTE]
> Tag-value pairs can be parsed correctly. Tags improve readability and are ignored during conversion.

> [!NOTE]
> Float strings with units are also supported.

_**Special Cases**_:

- If there is a `space` between the float string and unit string, all text following the float string (including notation) is recognized as the unit string.

> 1.23mA : Float: 1.23m; Unit: A
> 1.23 mA : Float: 1.23; Unit: mA

- In scientific notation mode, any string following the float string is recognized as the unit string, regardless of spaces.

> 1.23E+5mA: Float: 1.23E+5; Unit: mA
> 1.23E+5 mA: Float: 1.23E+5; Unit: mA

> [!NOTE]
> Units are not supported for special float values like `e`,`-e`,`pi`,`-pi`,`inf`,`+inf`,`-inf`, and `NaN`.

### Complex(DBL/SGL)

`a+bi` or `a-bi` represents complex data types. Both `a` and `b` support all Float formats described above.

> [!NOTE]
> For Complex values, an empty string will be converted to the input prototype value

> [!NOTE]
> Tag-value pair could be parsed correctly. Tag is used for readability and will be ignored during conversion.

### Timestamp

Timestamp strings use the format `TimeStamp_String(Format_String)`. The `Format_String` is used to parse the `TimeStamp_String`.

```text
"2023-10-11 22:54:33(%<%Y-%m-%d %H:%M:%S>T)" equals the UTC timestamp string "2023-10-11T14:54:33.000Z".
```

_**Special Case**_:

If no time string format is included, the RFC3339 standard is used by default.

```text
"2023-10-31T14:49:39.597Z" is valid.
"2023-10-31T22:49:39.597+08:00" is valid.
```

`TimeStamp String(FormatString)` is also supported. The `FormatString` enclosed in quotes will be used to parse the `TimeStamp String`.

> [!NOTE]
> For Timestamp values, an empty string will be converted to the current time.

### Enum

Indexed Enum is defined as Enum strings composed of [number] [separator] [enum string]. The following expressions are supported:

> Hexadecimal number with "--" as separator:
>
> - 0x01 -- boolean
> - 0x02 -- string
> - 0x04 -- dbl
> - 0x08 -- number
>
> Binary number with "__" as separator:
>
> - 0b0001 __ boolean
> - 0b0010 __ string
> - 0b0100 __ dbl
> - 0b1000 __ number
>
> Decimal number with "==" as separator:
>
> - 1 == boolean
> - 2 == string
> - 4 == dbl
> - 8 == number

> [!NOTE]
> Index numbers support all integer expressions mentioned earlier.


_**Rule 1: When No Index is Specified**_

When no index is specified, the string is converted to an Enum by matching the string itself.

Example: Enum = {AAA, BBBB, CCCC}

- String "AAA" converts to Enum(AAA), IntegerValue = 0
- String "CCC" converts to Enum(CCC), IntegerValue = 2

_**Rule 2: When Index is Specified**_

When an index is specified, the string can be converted to an Enum by matching either the string or the index.

Example: Enum = {1- AAA, 5 - BBBB, 9 - CCCC}

- String "AAA" converts to Enum(1- AAA), IntegerValue = 0
- String "5" converts to Enum(5 - BBBB), IntegerValue = 1
- String "9 - CCCC" converts to Enum(9 - CCCC), IntegerValue = 2

> [!NOTE]
> - String matching is case-insensitive.
> - String matching performs regex matching from the first element in the enum list until the first match is found. Therefore, partial writing is supported.
>     For example: 0x00 -- Spring | 0x01 -- Summer | 0x02 -- Autumn | 0x03 -- Winter
>     Input string "aut" will match to "Autumn".

### Array

Commas (',') are used as element separators, and semicolons (';') are used as row separators. Square brackets ('[' and ']') serve as boundary symbols but can be omitted for simple data types.

**Examples:**

`a,b,c,d,e` and `[a,b,c,d,e]` both represent a 5-element array:

```text
a b c d e
```

`a;b;c;d;e` and `[a;b;c;d;e]` both represent a 5-element array:

```text
a
b
c
d
e
```

`a1, b1, c1, d1, e1; a2, b2, c2, d2, e2` and `[a1, b1, c1, d1, e1; a2, b2, c2, d2, e2]` both represent a 2×5 2D array:

```text
a1 b1 c1 d1 e1
a2 b2 c2 d2 e2
```

> [!NOTE]
> Empty strings are ignored, and the prototype input value is used as the output.

### Cluster

**Tag:Value Mode**

In Tag:Value mode, the input string consists of tag:value pairs. Tags represent element names in the cluster, and values represent the data to be set. Tags and values are separated by colons (':'), while tag:value pairs are separated by semicolons (';'). Curly braces ('{' and '}') serve as boundary symbols but can be omitted for simple data types. Additional rules:

- Tags correspond to element names in the cluster, and values are converted based on the corresponding element's data type.
- Only elements that need to change must be described; elements matching the data prototype can be omitted.
- The order of tag:value pairs is not important.
- For nested clusters, sub-cluster tags use dot notation (e.g., `ParentTag.ChildTag`).
- If a sub-cluster's tag name is unique, the parent cluster's tag can be omitted.
- If no name is provided, the string input is converted to the first element of the cluster, making it easy to prioritize the first element.

**Example:**

Consider a cluster with the following structure:

```text
typedef cluster{
  Boolean b;
  String str;
  U32 integer
  Cluster subCluster
  {
    Boolean b2;
  }
}
```

> `b:On` and `{b:On}` both set the cluster's boolean value `b` to TRUE. All other elements remain unchanged.
>
> `b:On;str:abcdef` and `{b:On;str:abcdef}` both set the cluster's boolean value `b` to TRUE and string `str` to "abcdef". All other elements remain unchanged.
>
> `{subCluster.b2:On}` sets the boolean value `b2` in the nested `subCluster` to TRUE. All other elements remain unchanged. Since `b2` is unique, the parent cluster's tag can be omitted: `b2:On` achieves the same result.

**Non-Tag Mode**

In Non-Tag mode, the input string consists only of data values separated by semicolons (;).

- Element order is critical. The first value sets the first cluster element, the second value sets the second cluster element, and so on.
- If the input string contains fewer elements than the cluster, the remaining elements retain their original values.
- If the input string contains more elements than the cluster, the extra values are ignored.

> `on;abcdef;13` and `{on;abcdef;13}` both set the cluster's boolean value `b` to TRUE, string `str` to "abcdef", and U32 integer to 13. Any additional cluster elements remain unchanged.
>
> `on;abcdef` and `{on;abcdef}` both set the cluster's boolean value `b` to TRUE and string `str` to "abcdef". All other elements remain unchanged.
>

> [!NOTE]
> Empty strings are converted to the input prototype value.

### Other Data Types

Other data types are treated as variants and transformed using CSM-HexStr.