Skip to content

README(zh-cn).md

Latest commit

 

History

History
309 lines (225 loc) · 10.1 KB

README(zh-cn).md

File metadata and controls

309 lines (225 loc) · 10.1 KB

CSM-API-String-Arguments-Support

English | 中文

安装量 星级评分 许可证 GitHub下载量

本库扩展了 CSM（通信状态机）框架的 API 参数功能，支持以纯文本格式传递各种数据类型。

库中还附带两个 CSM 模板，内置 Data: Get Configuration、Data: Set Configuration 和 Data: Get Internal Data 状态，可作为构建需要读写 >> internal data >> 移位寄存器数据的 CSM 模块的起点。

example

支持的数据类型

  • 字符串 (String)
  • 路径 (Path)
  • 标签 (Tag)
  • 引用号 (Refnum，包括 IVI/VISA/UserDefinedRefnumTag)
  • 布尔值 (Boolean)
  • 整数 (I8, I16, I32, I64, U8, U16, U32, U64)
  • 浮点数 (DBL/SGL)
  • 复数 (DBL/SGL)
  • 时间戳 (Timestamp)
  • 枚举 (Enum)
  • 数组 (Array)
  • 簇 (Cluster)
  • 其他类型 (使用 CSM-Hexstr 表示)

字符串(String)/路径(Path)/引用号(Refnum)/标签(Tag)

字符串和路径类型中，CSM 关键字（->|、->、-@、-&、>>、,、;）在传递前会自动转换为 %[十六进制] 字符串，效果等同于 CSM AdvanceAPI\CSM Make String Arguments Safe.vi。

Note

引用号（Refnum，包括 IVI/VISA/UserDefinedRefnumTag）和标签（Tag）的转换规则与 String 类型相同。

布尔值(Boolean)

内置的TRUE/FALSE字符串对:

  - T/F
  - True/False
  - On/Off
  - Enable/Disable
  - Active/Inactive
  - valid/Invalid
  - 1/0
  - Open/Close
  - Non-null/null

Note

空字符串将转换为原型(Prototype)的输入值。

Note

可以使用API String - Add Boolean Strings.vi或API String - Remove Boolean Strings.vi自定义布尔字符串对。

Note

标签-数据对(Tag:Value)可以被正确解析。标签仅用于提高可读性，转换过程中会被忽略。

整数(I8,I16,I32,I64,U8,U16,U32,U64)

支持的数据格式包括：普通整数、十进制、十六进制、二进制、八进制，以及带后缀的表示方法。例如：

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

Note

空字符串将转换为原型(Prototype)的输入值。

Note

标签-数据对(Tag:Value)可以被正确解析。标签仅用于提高可读性，转换过程中会被忽略。

浮点数(DBL/SGL)

支持的数据格式包括：普通浮点数、科学计数法以及特殊浮点数。例如：

  - 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)
  - 特殊浮点数值: `e`,`-e`,`pi`,`-pi`,`inf`,`+inf`,`-inf`,`NaN`

Note

空字符串将转换为原型(Prototype)的输入值。

Note

默认精度为6位有效数字。可以通过API String - Set Float Precision.vi修改精度。

Note

标签-数据对(Tag:Value)可以被正确解析。标签仅用于提高可读性，转换过程中会被忽略。

Note

带有单位的浮点数字符串也支持正确解析。

特殊情况说明:

  • 如果浮点数字符串与单位字符串之间存在空格，则浮点数后面的所有内容（包括符号）都被识别为单位字符串。

1.23mA : 浮点数: 1.23m; 单位: A 1.23 mA : 浮点数: 1.23; 单位: mA

  • 对于科学计数法表示的浮点数，无论是否存在空格，浮点数后面的字符串都被识别为单位字符串。

1.23E+5mA: 浮点数: 1.23E+5; 单位: mA 1.23E+5 mA: 浮点数: 1.23E+5; 单位: mA

Note

e、-e、pi、-pi、inf、+inf、-inf 和 NaN 等特殊浮点数值不支持单位。

复数(DBL/SGL)

a+bi 或 a-bi 格式表示复数。其中 a 和 b 支持所有浮点数的表达方式。

Note

空字符串将转换为原型(Prototype)的输入值。

Note

标签-数据对(Tag:Value)可以被正确解析。标签仅用于提高可读性，转换过程中会被忽略。

时间戳(Timestamp)

时间戳的标准格式为：TimeStamp_String(Format_String)。其中 Format_String 用于解析 TimeStamp_String。

"2023-10-11 22:54:33(%<%Y-%m-%d %H:%M:%S>T)" 等效于 UTC 时间戳 "2023-10-11T14:54:33.000Z".

特殊情况说明:

当字符串不包含 Format_String 时，TimeStamp_String 应符合 RFC3339 标准格式。

"2023-10-31T14:49:39.597Z" 为有效的表达方式.
"2023-10-31T22:49:39.597+08:00" 为有效的表达方式.

Note

对于时间戳，空字符串将转换为当前时间。

枚举(Enum)

Indexed Enum 定义为 [索引编号][分隔符][枚举字符串] 格式的字符串。支持以下表达方式：

十六进制索引，-- 作为分隔符：

  • 0x01 -- boolean
  • 0x02 -- string
  • 0x04 -- dbl
  • 0x08 -- number

二进制索引，__ 作为分隔符：

  • 0b0001 __ boolean
  • 0b0010 __ string
  • 0b0100 __ dbl
  • 0b1000 __ number

十进制索引，== 作为分隔符：

  • 1 == boolean
  • 2 == string
  • 4 == dbl
  • 8 == number

Note

索引编号支持所有整数的表达方式。

转换规则1: 没有索引编号时

当没有索引编号时，通过字符串匹配进行转换。

示例：Enum = {AAA, BBBB, CCCC}

  • 字符串 "AAA" 将转换为 Enum(AAA)，数字值为 0
  • 字符串 "CCC" 将转换为 Enum(CCC)，数字值为 2

转换规则2：包含索引编号时

当包含索引编号时，既可以通过字符串匹配转换，也可以通过索引编号匹配转换。

示例：Enum = {1- AAA, 5 - BBBB, 9 - CCCC}

  • 字符串 "AAA" 将转换为 Enum(1- AAA)，数字值为 0
  • 字符串 "5" 将转换为 Enum(5 - BBBB)，数字值为 1
  • 字符串 "9 - CCCC" 将转换为 Enum(9 - CCCC)，数字值为 2

Note

  • 字符串匹配不区分大小写。
  • 字符串匹配采用正则表达式，从枚举列表第一个元素开始依次匹配，直到找到第一个符合项为止，因此支持部分匹配。 例如枚举为：0x00 -- Spring | 0x01 -- Summer | 0x02 -- Autumn | 0x03 -- Winter 输入字符串 "aut" 将匹配到 "Autumn"。

数组(Array)

逗号(,) 用于元素分隔，分号(;) 用于行分隔。方括号([ 和 ]) 用作边界符号。对于非复杂的混合数据类型，方括号可以省略。

示例:

a,b,c,d,e 和 [a,b,c,d,e] 都表示一个包含5个元素的数组：

a b c d e

a;b;c;d;e 和 [a;b;c;d;e] 都表示一个包含5个元素的数组：

a
b
c
d
e

a1, b1, c1, d1, e1; a2, b2, c2, d2, e2 和 [a1, b1, c1, d1, e1; a2, b2, c2, d2, e2] 表示一个 2×5 的二维数组：

a1 b1 c1 d1 e1
a2 b2 c2 d2 e2

Note

空字符串将转换为原型(Prototype)的输入值。

簇(Cluster)

转换规则1：标签-数据对(Tag:Value)模式

在标签-数据对模式下，输入字符串由多个 标签:值 对组成，冒号（:）分隔标签与值，分号（;）分隔不同元素对。花括号（{ 和 }）为边界符，简单数据类型可省略。其他规则如下：

  • 标签对应簇中元素的名称，值根据对应元素的数据类型进行转换。
  • 只需描述需要修改的元素，与原型值一致的元素可省略。
  • 通过名称匹配元素，顺序无关。
  • 对于嵌套簇，子簇元素的标签格式为 父簇标签.子簇元素标签。
  • 若子簇元素标签在整个簇中唯一，可省略父簇标签。
  • 若未提供标签，则输入字符串将转换为簇的第一个元素，方便优先设置第一个元素。

示例:

假设有一个簇的数据原型如下：

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

b:On 和 {b:On} 都表示仅将簇中的布尔类型数据 b 设置为 TRUE。其他元素的值保持原型输入值不变。

b:On;str:abcdef 和 {b:On;str:abcdef} 都表示将簇中的布尔类型数据 b 设置为 TRUE，字符串类型数据 str 设置为 "abcdef"。其他元素的值保持原型输入值不变。

{subCluster.b2:On} 表示将簇中子簇的布尔类型数据 b2 设置为 TRUE。其他元素的值保持原型输入值不变。由于 b2 是唯一的，可以省略父簇标签，直接使用 b2:On 也表示相同的转换。

转换规则2：无标签模式

对于簇，也支持仅输入数据字符串，各值之间用分号分隔。

  • 顺序非常重要。第一个元素值将设置给簇的第一个元素，第二个元素值设置给簇的第二个元素，以此类推。
  • 如果输入字符串的元素数量少于簇的元素数量，剩余的元素将保持不变。
  • 如果输入字符串的元素数量多于簇的元素数量，多余的元素将被忽略。

on;abcdef;13 和 {on;abcdef;13} 都表示将簇中的 b 更改为 TRUE，str 更改为 "abcdef"，U32整数更改为 13。如果簇有更多元素，它们将保持不变。

on;abcdef 和 {on;abcdef} 都表示将簇中的 b 更改为 TRUE，str 更改为 "abcdef"。其他元素的值保持原型输入值不变。

Note

空字符串将转换为原型(Prototype)的输入值。

其他类型(使用CSM-Hexstr)

其他数据类型将首先被转换为变体(Variant)，然后使用CSM-HexStr进行表示和转换。