nfcscript 0.0.12__tar.gz → 0.0.14__tar.gz

{nfcscript-0.0.12 → nfcscript-0.0.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nfcscript
-Version: 0.0.12
+Version: 0.0.14
 Summary: A plugin-based core engine for DSL-style NFC testing automation.
 Author: crthu
 Requires-Python: >=3.14
@@ -211,7 +211,8 @@ with session() as reader:
 
 | 函数 | 说明 |
 |------|------|
-| `PARSE_HEX(text)` | 解析 hex 字符串 |
+| `PARSE_HEX(text)` | 解析纯 hex，返回 `list[int]` |
+| `PARSE_HEX_BITS(text, last_bits=None)` | 解析 hex + Verilog 位标记，返回 `tuple[list[int], int]` |
 | `FORMAT_HEX(data, last_bits)` | 格式化为可视化 hex |
 
 ### checksum.py

{nfcscript-0.0.12 → nfcscript-0.0.14}/README.md

@@ -201,7 +201,8 @@ with session() as reader:
 
 | 函数 | 说明 |
 |------|------|
-| `PARSE_HEX(text)` | 解析 hex 字符串 |
+| `PARSE_HEX(text)` | 解析纯 hex，返回 `list[int]` |
+| `PARSE_HEX_BITS(text, last_bits=None)` | 解析 hex + Verilog 位标记，返回 `tuple[list[int], int]` |
 | `FORMAT_HEX(data, last_bits)` | 格式化为可视化 hex |
 
 ### checksum.py

{nfcscript-0.0.12 → nfcscript-0.0.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nfcscript"
-version = "0.0.12"
+version = "0.0.14"
 description = "A plugin-based core engine for DSL-style NFC testing automation."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -34,7 +34,7 @@ dev = [
 ]
 
 [tool.bumpversion]
-current_version = "0.0.12"
+current_version = "0.0.14"
 commit = true
 tag = true
 allow_dirty = true

nfcscript-0.0.14/src/nfc/hex_util.py

@@ -0,0 +1,189 @@
+import re
+
+# 位标记正则：匹配 N'hXX 格式 (如 7'h26, 4'hC)
+BIT_PATTERN = re.compile(r"(\d+)\s*\'h\s*([0-9a-fA-F]+)")
+
+
+def PARSE_HEX(text: str) -> list[int]:
+    """
+    解析纯 hex 字符串为 list[int]。
+
+    Args:
+        text: 十六进制文本，支持空格分隔 (如 "AA BB CC" 或 "AABBCC")。
+
+    Returns:
+        list[int]: 解析后的字节列表。
+
+    Raises:
+        ValueError: 不合法的十六进制数据时抛出。
+
+    Examples:
+        >>> PARSE_HEX("AA BB CC")
+        [0xAA, 0xBB, 0xCC]
+        >>> PARSE_HEX("0011")
+        [0x00, 0x11]
+    """
+    # 去空格得到纯 hex
+    clean_hex = text.replace(" ", "").upper()
+
+    # 简单的合法性检查
+    if clean_hex:
+        try:
+            return list(bytes.fromhex(clean_hex))
+        except ValueError:
+            raise ValueError(f"不合法的十六进制数据: {clean_hex}")
+    return []
+
+
+def PARSE_HEX_BITS(text: str, last_bits: int | None = None) -> tuple[list[int], int]:
+    """
+    解析 hex 字符串为 tuple[list[int], int]，支持 Verilog 位标记。
+
+    支持格式:
+    - 纯 hex: "AA BB CC" → ([0xAA, 0xBB, 0xCC], 0)
+    - Verilog 标记: "AA 4'hBB" → ([0xAA, 0x0B], 4)
+    - 混合: "AA BB 7'h03" → ([0xAA, 0xBB, 0x03], 7)
+    - 手动指定: "AA BB", last_bits=4 → ([0xAA, 0xBB], 4)
+
+    Args:
+        text: 十六进制文本，支持空格分隔和 N'hXX 位标记。
+        last_bits: 可选的最后字节有效位数，与 Verilog 标记冲突时报错。
+
+    Returns:
+        tuple[list[int], int]: (字节列表, 最后字节有效位数)。
+
+    Raises:
+        ValueError: 不合法的十六进制数据、位标记冲突或多标记时报错。
+
+    Examples:
+        >>> PARSE_HEX_BITS("AA BB CC")
+        ([0xAA, 0xBB, 0xCC], 0)
+        >>> PARSE_HEX_BITS("AA 4'hBB")
+        ([0xAA, 0x0B], 4)
+        >>> PARSE_HEX_BITS("0011", last_bits=4)
+        ([0x00, 0x01], 4)
+        >>> PARSE_HEX_BITS("AA 4'hBB", last_bits=4)
+        ValueError: 冲突
+    """
+    # 冲突检测：只允许一个 Verilog 标记
+    matches = list(BIT_PATTERN.finditer(text))
+    if len(matches) > 1:
+        raise ValueError("只允许一个 Verilog 位标记")
+    if matches and last_bits is not None:
+        raise ValueError("last_bits 参数与 Verilog 位标记冲突")
+
+    bits = last_bits if last_bits is not None else 0
+
+    # 处理 Verilog 位标记
+    if matches:
+        m = matches[0]
+        n_bits = int(m.group(1))
+        bits = n_bits
+        # 按 bits 截断: 4'hCA → 0x0A
+        val = int(m.group(2), 16) & ((1 << n_bits) - 1)
+        hex_val = format(val, 'X')
+        if len(hex_val) % 2 != 0:
+            hex_val = '0' + hex_val
+        text = text[:m.start()] + hex_val + text[m.end():]
+
+    # 去空格得到纯 hex
+    clean_hex = text.replace(" ", "").upper()
+
+    # 解析 hex 数据
+    if clean_hex:
+        try:
+            data = list(bytes.fromhex(clean_hex))
+        except ValueError:
+            raise ValueError(f"不合法的十六进制数据: {clean_hex}")
+    else:
+        data = []
+
+    # last_bits 截断最后一个字节
+    if bits and data:
+        data[-1] = data[-1] & ((1 << bits) - 1)
+
+    return data, bits
+
+
+def FORMAT_HEX(data: int | bytes | list[int] | str, last_bits: int = 0) -> str:
+    """
+    格式化数据为带位标记的可视化格式。
+
+    支持输入类型: int, bytes, list[int], str (纯 hex)。
+
+    Args:
+        data: 待格式化的数据。
+        last_bits: 最后一个字节的有效位数 (1-7)，0 表示整字节。
+
+    Returns:
+        str: 格式化后的字符串。
+
+    Raises:
+        TypeError: 不支持的输入类型时抛出。
+
+    Examples:
+        >>> FORMAT_HEX(0xAABB03, 7)
+        "AA BB 7'h03"
+        >>> FORMAT_HEX([0xAA, 0xBB, 0x03])
+        'AA BB 03'
+        >>> FORMAT_HEX("AABB", 4)
+        "AA 4'hBB"
+    """
+    # 1. 统一转换为纯十六进制字符串
+    if isinstance(data, int):
+        hex_str = data.to_bytes(max(1, (data.bit_length() + 7) // 8)).hex().upper()
+    elif isinstance(data, bytes):
+        hex_str = data.hex().upper()
+    elif isinstance(data, list):
+        hex_str = bytes(data).hex().upper()
+    elif isinstance(data, str):
+        hex_str = data.replace(" ", "").upper()
+    else:
+        raise TypeError(f"不支持的输入类型: {type(data)}")
+
+    if not hex_str:
+        return ""
+
+    # 2. 如果是整字节 (无 last_bits)
+    if last_bits == 0:
+        return ' '.join(hex_str[i:i+2] for i in range(0, len(hex_str), 2))
+
+    # 3. 有 last_bits，处理最后一个字节
+    if len(hex_str) <= 2:
+        return f"{last_bits}'h{hex_str}"
+
+    prefix = hex_str[:-2]
+    last_byte = hex_str[-2:]
+    formatted_prefix = ' '.join(prefix[i:i+2] for i in range(0, len(prefix), 2))
+    return f"{formatted_prefix} {last_bits}'h{last_byte}"
+
+
+if __name__ == "__main__":
+    # --- 测试例程 ---
+    print("=== Hex 工具测试 ===")
+
+    # 测试用例: (data, last_bits, 类型名)
+    test_cases = [
+        ("AABB03", 7, "str"),
+        (0xAABB03, 7, "int"),
+        (b'\xAA\xBB\x03', 7, "bytes"),
+        ([0xAA, 0xBB, 0x03], 7, "list"),
+        ("FF", 4, "str"),
+        (0xFF, 4, "int"),
+        ("AABBCC", 0, "str"),
+        (0xAABBCC, 0, "int"),
+        (b'\xAA\xBB\xCC', 0, "bytes"),
+    ]
+
+    for data, b, typename in test_cases:
+        formatted = FORMAT_HEX(data, b)
+        print(f"输入: ({data}, {b}, {typename}) -> 格式化: {formatted}")
+
+        # 反向解析验证
+        if b:
+            parsed, bits = PARSE_HEX_BITS(formatted)
+            print(f"解析: {formatted} -> Hex: {parsed}, Bits: {bits}")
+        else:
+            parsed = PARSE_HEX(formatted)
+            print(f"解析: {formatted} -> Hex: {parsed}")
+        print("-" * 20)

{nfcscript-0.0.12 → nfcscript-0.0.14}/src/nfc/reader.py

@@ -103,7 +103,7 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
     # 手动底层寻卡流程
     # 1. REQA
     res_reqa = reqa(cmd=reqa_cmd)
-    if not res_reqa:
+    if not res_reqa.data:
         return None
     atq = res_reqa.data
 
@@ -111,7 +111,7 @@ def active(low_layer: bool = False, ignore_error: bool = False, reqa_cmd: int =
     full_uid = []
     for cl in [1, 2, 3]:
         res = anticoll(cl_level=cl, nvb=0x20)
-        if not res or not res.data:
+        if not res.data:
             return None
 
         data = res.data
@@ -171,7 +171,7 @@ def transceive(data: list[int], tx_crc: bool = True, rx_crc: bool = True) -> lis
     return res.data if res and res.data else []
 
 
-def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True, rx_crc: bool = True) -> TransceiveBits | None:
+def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True, rx_crc: bool = True) -> TransceiveBits:
     """
     使用底层帧交互方式发送数据，并支持对最后一个字节进行位控制。
 
@@ -182,14 +182,15 @@ def transceive_bits(data: list[int], last_tx_bits: int = 0, tx_crc: bool = True,
         rx_crc: 接收时是否自动校验 CRC。False 则原样接收不校验。
 
     Returns:
-        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+        TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
     _state.ensure_connected()
     reader = _state.reader
-    return reader.transceive(data, last_tx_bits=last_tx_bits, tx_crc=tx_crc, rx_crc=rx_crc)
+    res = reader.transceive(data, last_tx_bits=last_tx_bits, tx_crc=tx_crc, rx_crc=rx_crc)
+    return res if res else TransceiveBits(data=[], bits=0)
 
 
-def reqa(cmd: int = 0x26) -> TransceiveBits | None:
+def reqa(cmd: int = 0x26) -> TransceiveBits:
     """
     ISO14443-A REQA (7 bits)。
 
@@ -197,27 +198,27 @@ def reqa(cmd: int = 0x26) -> TransceiveBits | None:
         cmd: REQA 命令字节，默认 0x26。
 
     Returns:
-        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+        TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
     return transceive_bits([cmd], last_tx_bits=7, tx_crc=False, rx_crc=False)
 
 
-def wupa() -> TransceiveBits | None:
+def wupa() -> TransceiveBits:
     """
     ISO14443-A WUPA (7 bits)。
 
     Returns:
-        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+        TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
     return transceive_bits([0x52], last_tx_bits=7, tx_crc=False, rx_crc=False)
 
 
-def halt() -> list[int] | None:
+def halt() -> list[int]:
     """
     ISO14443-A HALT (Standard Frame)。
 
     Returns:
-        list[int] | None: 返回响应数据，失败返回 None。
+        list[int]: 返回响应数据。
     """
     return transceive([0x50, 0x00], tx_crc=True, rx_crc=True)
 
@@ -241,7 +242,7 @@ def _get_sel_cmd(cl_level: int) -> int:
     return sel_map[cl_level]
 
 
-def anticoll(cl_level: int, nvb: int = 0x20, uid_prefix: list[int] = []) -> TransceiveBits | None:
+def anticoll(cl_level: int, nvb: int = 0x20, uid_prefix: list[int] = []) -> TransceiveBits:
     """
     ISO14443-A ANTICOLL (Anti-collision)。
 
@@ -251,13 +252,13 @@ def anticoll(cl_level: int, nvb: int = 0x20, uid_prefix: list[int] = []) -> Tran
         uid_prefix: 已知的部分 UID (0-4 字节)。
 
     Returns:
-        TransceiveBits | None: 包含 data 和 bits 属性，失败返回 None。
+        TransceiveBits: 包含 data 和 bits 属性，失败返回空的 TransceiveBits(data=[], bits=0)。
     """
     cmd = [_get_sel_cmd(cl_level), nvb] + uid_prefix
     return transceive_bits(cmd, last_tx_bits=0, tx_crc=False, rx_crc=False)
 
 
-def select(cl_level: int, uid: list[int]) -> list[int] | None:
+def select(cl_level: int, uid: list[int]) -> list[int]:
     """
     ISO14443-A SELECT (Standard Frame)。
 
@@ -266,7 +267,7 @@ def select(cl_level: int, uid: list[int]) -> list[int] | None:
         uid: 完整 5 字节 UID (包含 BCC)。
 
     Returns:
-        list[int] | None: 返回响应数据，失败返回 None。
+        list[int]: 返回响应数据。
     """
     cmd = [_get_sel_cmd(cl_level), 0x70] + uid
     return transceive(cmd, tx_crc=True, rx_crc=True)

{nfcscript-0.0.12 → nfcscript-0.0.14}/src/nfcscript.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nfcscript
-Version: 0.0.12
+Version: 0.0.14
 Summary: A plugin-based core engine for DSL-style NFC testing automation.
 Author: crthu
 Requires-Python: >=3.14
@@ -211,7 +211,8 @@ with session() as reader:
 
 | 函数 | 说明 |
 |------|------|
-| `PARSE_HEX(text)` | 解析 hex 字符串 |
+| `PARSE_HEX(text)` | 解析纯 hex，返回 `list[int]` |
+| `PARSE_HEX_BITS(text, last_bits=None)` | 解析 hex + Verilog 位标记，返回 `tuple[list[int], int]` |
 | `FORMAT_HEX(data, last_bits)` | 格式化为可视化 hex |
 
 ### checksum.py

nfcscript-0.0.14/tests/test_hex_util.py

@@ -0,0 +1,245 @@
+"""PARSE_HEX / PARSE_HEX_BITS / FORMAT_HEX 测试"""
+import pytest
+from nfc.hex_util import PARSE_HEX, PARSE_HEX_BITS, FORMAT_HEX
+
+
+class TestPARSE_HEX:
+    """PARSE_HEX: 纯 hex 解析，返回 list[int]"""
+
+    def test_simple_hex(self):
+        assert PARSE_HEX("AA BB CC") == [0xAA, 0xBB, 0xCC]
+
+    def test_no_space(self):
+        assert PARSE_HEX("AABBCC") == [0xAA, 0xBB, 0xCC]
+
+    def test_empty_string(self):
+        assert PARSE_HEX("") == []
+
+    def test_whitespace_only(self):
+        assert PARSE_HEX("   ") == []
+
+    def test_single_byte(self):
+        assert PARSE_HEX("FF") == [0xFF]
+
+    def test_lowercase(self):
+        assert PARSE_HEX("ff aa") == [0xFF, 0xAA]
+
+    def test_invalid_hex_raises(self):
+        with pytest.raises(ValueError, match="不合法的十六进制数据"):
+            PARSE_HEX("ZZZZ")
+
+    def test_odd_hex_digits_raises(self):
+        with pytest.raises(ValueError):
+            PARSE_HEX("ABC")
+
+
+class TestPARSE_HEX_BITS:
+    """PARSE_HEX_BITS: 返回 tuple[list[int], int]，支持位截断"""
+
+    # --- 基础测试 ---
+
+    def test_simple_hex(self):
+        assert PARSE_HEX_BITS("AA BB CC") == ([0xAA, 0xBB, 0xCC], 0)
+
+    def test_empty_string(self):
+        assert PARSE_HEX_BITS("") == ([], 0)
+
+    def test_whitespace_only(self):
+        assert PARSE_HEX_BITS("   ") == ([], 0)
+
+    def test_invalid_hex_raises(self):
+        with pytest.raises(ValueError, match="不合法的十六进制数据"):
+            PARSE_HEX_BITS("ZZZZ")
+
+    # --- last_bits 参数测试 ---
+
+    def test_with_last_bits(self):
+        """last_bits=4 截断最后一个字节: 0x11 → 0x01"""
+        assert PARSE_HEX_BITS("00 11", last_bits=4) == ([0x00, 0x01], 4)
+
+    def test_with_last_bits_single_byte(self):
+        """last_bits=7 截断: 0xFF → 0x7F"""
+        assert PARSE_HEX_BITS("FF", last_bits=7) == ([0x7F], 7)
+
+    def test_with_last_bits_no_space(self):
+        assert PARSE_HEX_BITS("0011", last_bits=4) == ([0x00, 0x01], 4)
+
+    # --- Verilog 标记：无截断 ---
+
+    def test_verilog_no_truncate(self):
+        """值在 bits 范围内，无需截断"""
+        assert PARSE_HEX_BITS("7'h03") == ([0x03], 7)
+
+    def test_verilog_no_truncate_even(self):
+        """偶数位 hex，无需填充"""
+        assert PARSE_HEX_BITS("8'hFF") == ([0xFF], 8)
+
+    def test_verilog_no_truncate_4bits(self):
+        """4 位 hex 值，无需截断"""
+        assert PARSE_HEX_BITS("4'hA") == ([0x0A], 4)
+
+    def test_verilog_no_truncate_4bits_max(self):
+        """4 位最大值 F，无需截断"""
+        assert PARSE_HEX_BITS("4'hF") == ([0x0F], 4)
+
+    # --- Verilog 标记：截断高位 ---
+
+    def test_verilog_truncate_4bits(self):
+        """4'hCA → 截断高位 C，只保留 4 位 → 0x0A"""
+        assert PARSE_HEX_BITS("4'hCA") == ([0x0A], 4)
+
+    def test_verilog_truncate_7bits(self):
+        """7'hFF → FF 是 8 位，截断为 7 位 → 0x7F"""
+        assert PARSE_HEX_BITS("7'hFF") == ([0x7F], 7)
+
+    def test_verilog_truncate_4bits_bigger(self):
+        """4'hFF → 截断为 4 位 → 0x0F"""
+        assert PARSE_HEX_BITS("4'hFF") == ([0x0F], 4)
+
+    def test_verilog_truncate_1bit(self):
+        """1'h1 → 1 位最大值 1"""
+        assert PARSE_HEX_BITS("1'h1") == ([0x01], 1)
+
+    def test_verilog_truncate_1bit_zero(self):
+        """1'h0 → 1 位最小值 0"""
+        assert PARSE_HEX_BITS("1'h0") == ([0x00], 1)
+
+    # --- Verilog 标记：奇数位填充 ---
+
+    def test_verilog_odd_pad(self):
+        """4'hB → 奇数位填充为 0B"""
+        assert PARSE_HEX_BITS("4'hB") == ([0x0B], 4)
+
+    def test_verilog_odd_pad_7bits(self):
+        """7'hA → 奇数位填充为 0A，7 位无需截断"""
+        assert PARSE_HEX_BITS("7'hA") == ([0x0A], 7)
+
+    def test_verilog_odd_pad_truncate(self):
+        """4'hCB → 奇数位填充后截断 → 0x0B"""
+        assert PARSE_HEX_BITS("4'hCB") == ([0x0B], 4)
+
+    # --- 混合格式 ---
+
+    def test_mixed_hex_and_verilog(self):
+        """4'hBB → 截断为 4 位 → 0x0B"""
+        assert PARSE_HEX_BITS("AA 4'hBB") == ([0xAA, 0x0B], 4)
+
+    def test_mixed_verilog_last(self):
+        """Verilog 标记在最后"""
+        assert PARSE_HEX_BITS("AA BB 7'h03") == ([0xAA, 0xBB, 0x03], 7)
+
+    def test_mixed_no_space_verilog_end(self):
+        """AABB7'h26 → 正常解析"""
+        assert PARSE_HEX_BITS("AABB7'h26") == ([0xAA, 0xBB, 0x26], 7)
+
+    # --- 冲突检测 ---
+
+    def test_verilog_and_last_bits_conflict(self):
+        with pytest.raises(ValueError, match="冲突"):
+            PARSE_HEX_BITS("AA 4'hBB", last_bits=4)
+
+    def test_multiple_verilog_marks_error(self):
+        """多个 Verilog 标记报错"""
+        with pytest.raises(ValueError, match="只允许一个"):
+            PARSE_HEX_BITS("7'h03 AA 4'hC")
+
+    # --- 小写 hex ---
+
+    def test_verilog_lower_hex(self):
+        assert PARSE_HEX_BITS("7'h0a") == ([0x0A], 7)
+
+    def test_verilog_lower_hex_truncate(self):
+        """4'hca → 截断为 4 位 → 0x0A"""
+        assert PARSE_HEX_BITS("4'hca") == ([0x0A], 4)
+
+
+class TestFORMAT_HEX:
+    """FORMAT_HEX: 格式化为可视化 hex"""
+
+    def test_int_no_bits(self):
+        assert FORMAT_HEX(0xAABBCC) == "AA BB CC"
+
+    def test_int_with_bits(self):
+        assert FORMAT_HEX(0xAABB03, 7) == "AA BB 7'h03"
+
+    def test_int_single_byte_bits(self):
+        assert FORMAT_HEX(0xFF, 4) == "4'hFF"
+
+    def test_bytes_no_bits(self):
+        assert FORMAT_HEX(b'\xAA\xBB\xCC') == "AA BB CC"
+
+    def test_bytes_with_bits(self):
+        assert FORMAT_HEX(b'\xAA\xBB\x03', 7) == "AA BB 7'h03"
+
+    def test_list_no_bits(self):
+        assert FORMAT_HEX([0xAA, 0xBB, 0xCC]) == "AA BB CC"
+
+    def test_list_with_bits(self):
+        assert FORMAT_HEX([0xAA, 0xBB, 0x03], 7) == "AA BB 7'h03"
+
+    def test_str_no_bits(self):
+        assert FORMAT_HEX("AABBCC") == "AA BB CC"
+
+    def test_str_with_bits(self):
+        assert FORMAT_HEX("AABB03", 7) == "AA BB 7'h03"
+
+    def test_empty_string(self):
+        assert FORMAT_HEX("") == ""
+
+    def test_empty_bytes(self):
+        assert FORMAT_HEX(b'') == ""
+
+    def test_empty_list(self):
+        assert FORMAT_HEX([]) == ""
+
+    def test_unsupported_type(self):
+        with pytest.raises(TypeError, match="不支持的输入类型"):
+            FORMAT_HEX(3.14)
+
+    def test_hex_str_with_spaces(self):
+        assert FORMAT_HEX("AA BB CC") == "AA BB CC"
+
+    def test_lowercase_int(self):
+        assert FORMAT_HEX(0xff) == "FF"
+
+    def test_int_zero(self):
+        assert FORMAT_HEX(0) == "00"
+
+    def test_bytes_single(self):
+        assert FORMAT_HEX(b'\xFF') == "FF"
+
+    def test_list_single(self):
+        assert FORMAT_HEX([0xFF]) == "FF"
+
+    def test_int_large(self):
+        assert FORMAT_HEX(0xAABBCCDD) == "AA BB CC DD"
+
+    def test_bits_1(self):
+        assert FORMAT_HEX(0x01, 1) == "1'h01"
+
+    def test_bits_7(self):
+        assert FORMAT_HEX(0x26, 7) == "7'h26"
+
+
+class TestRoundtrip:
+    """PARSE_HEX <-> FORMAT_HEX 往返测试"""
+
+    def test_roundtrip_no_bits(self):
+        data = [0xAA, 0xBB, 0xCC]
+        formatted = FORMAT_HEX(data)
+        parsed = PARSE_HEX(formatted)
+        assert parsed == data
+
+    def test_roundtrip_with_bits(self):
+        data = [0xAA, 0xBB, 0x03]
+        formatted = FORMAT_HEX(data, 7)
+        parsed, bits = PARSE_HEX_BITS(formatted)
+        assert parsed == data
+        assert bits == 7
+
+    def test_roundtrip_single_byte(self):
+        """4'hFF 会被截断为 4 位 → 0x0F"""
+        formatted = FORMAT_HEX(0xFF, 4)
+        parsed, bits = PARSE_HEX_BITS(formatted)
+        assert parsed == [0x0F]
+        assert bits == 4

nfcscript-0.0.12/src/nfc/hex_util.py

@@ -1,131 +0,0 @@
-import re
-
-# 位标记正则：匹配 N'hXX 格式 (如 7'h26, 4'hC)
-BIT_PATTERN = re.compile(r"(\d+)\s*\'h\s*([0-9a-fA-F]+)")
-
-def PARSE_HEX(text: str) -> tuple[str, int]:
-    """
-    解析带位标记的 hex 字符串。
-
-    Args:
-        text: 十六进制文本。
-
-    Returns:
-        tuple[str, int]: (纯十六进制字符串, 最后字节有效位数)。
-
-    Raises:
-        ValueError: 不合法的十六进制数据时抛出。
-
-    Examples:
-        >>> PARSE_HEX("AA BB 7'h03")
-        ('AABB03', 7)
-        >>> PARSE_HEX("FF 4'h0C")
-        ('FF0C', 4)
-        >>> PARSE_HEX("AABBCC")
-        ('AABBCC', 0)
-    """
-    last_bits = 0
-    cleaned = text.strip()
-
-    # 查找所有位标记，从右往左替换避免偏移
-    matches = list(BIT_PATTERN.finditer(cleaned))
-    if matches:
-        last_match = matches[-1]
-        last_bits = int(last_match.group(1))
-
-        for m in reversed(matches):
-            hex_val = m.group(2)
-            if len(hex_val) % 2 != 0:
-                hex_val = "0" + hex_val
-            cleaned = cleaned[:m.start()] + hex_val + cleaned[m.end():]
-
-    # 去空格得到纯 hex
-    clean_hex = cleaned.replace(" ", "")
-
-    # 简单的合法性检查
-    if clean_hex:
-        try:
-            bytes.fromhex(clean_hex)
-        except ValueError:
-            raise ValueError(f"不合法的十六进制数据: {clean_hex}")
-
-    return clean_hex, last_bits
-
-def FORMAT_HEX(data: int | bytes | list[int] | str, last_bits: int = 0) -> str:
-    """
-    格式化数据为带位标记的可视化格式。
-
-    支持输入类型: int, bytes, list[int], str (纯 hex)。
-
-    Args:
-        data: 待格式化的数据。
-        last_bits: 最后一个字节的有效位数 (1-7)，0 表示整字节。
-
-    Returns:
-        str: 格式化后的字符串。
-
-    Raises:
-        TypeError: 不支持的输入类型时抛出。
-
-    Examples:
-        >>> FORMAT_HEX(0xAABB03, 7)
-        "AA BB 7'h03"
-        >>> FORMAT_HEX([0xAA, 0xBB, 0x03])
-        'AA BB 03'
-        >>> FORMAT_HEX("AABB", 4)
-        "AA 4'hBB"
-    """
-    # 1. 统一转换为纯十六进制字符串
-    if isinstance(data, int):
-        hex_str = data.to_bytes(max(1, (data.bit_length() + 7) // 8)).hex().upper()
-    elif isinstance(data, bytes):
-        hex_str = data.hex().upper()
-    elif isinstance(data, list):
-        hex_str = bytes(data).hex().upper()
-    elif isinstance(data, str):
-        hex_str = data.replace(" ", "").upper()
-    else:
-        raise TypeError(f"不支持的输入类型: {type(data)}")
-
-    if not hex_str:
-        return ""
-
-    # 2. 如果是整字节 (无 last_bits)
-    if last_bits == 0:
-        return ' '.join(hex_str[i:i+2] for i in range(0, len(hex_str), 2))
-
-    # 3. 有 last_bits，处理最后一个字节
-    if len(hex_str) <= 2:
-        return f"{last_bits}'h{hex_str}"
-    
-    prefix = hex_str[:-2]
-    last_byte = hex_str[-2:]
-    
-    formatted_prefix = ' '.join(prefix[i:i+2] for i in range(0, len(prefix), 2))
-    return f"{formatted_prefix} {last_bits}'h{last_byte}"
-
-if __name__ == "__main__":
-    # --- 测试例程 ---
-    print("=== Hex 工具测试 ===")
-    
-    # 测试用例: (data, last_bits, 类型名)
-    test_cases = [
-        ("AABB03", 7, "str"),
-        (0xAABB03, 7, "int"),
-        (b'\xAA\xBB\x03', 7, "bytes"),
-        ([0xAA, 0xBB, 0x03], 7, "list"),
-        ("FF", 4, "str"),
-        (0xFF, 4, "int"),
-        ("AABBCC", 0, "str"),
-        (0xAABBCC, 0, "int"),
-        (b'\xAA\xBB\xCC', 0, "bytes"),
-    ]
-    
-    for data, b, typename in test_cases:
-        formatted = FORMAT_HEX(data, b)
-        print(f"输入: ({data}, {b}, {typename}) -> 格式化: {formatted}")
-        
-        # 反向解析验证
-        parsed_h, parsed_b = PARSE_HEX(formatted)
-        print(f"解析: {formatted} -> Hex: {parsed_h}, Bits: {parsed_b}")
-        print("-" * 20)

nfcscript-0.0.12/tests/test_hex_util.py

@@ -1,168 +0,0 @@
-"""PARSE_HEX / FORMAT_HEX 测试"""
-import pytest
-from nfc.hex_util import PARSE_HEX, FORMAT_HEX
-
-
-class TestPARSE_HEX:
-
-    def test_simple_hex(self):
-        assert PARSE_HEX("AA BB CC") == ("AABBCC", 0)
-
-    def test_bit_mark(self):
-        hex_str, bits = PARSE_HEX("AA BB 7'h03")
-        assert hex_str == "AABB03"
-        assert bits == 7
-
-    def test_single_byte_two_digits(self):
-        hex_str, bits = PARSE_HEX("4'h0C")
-        assert hex_str == "0C"
-        assert bits == 4
-
-    def test_single_byte_odd_hex_padded(self):
-        hex_str, bits = PARSE_HEX("4'hC")
-        assert hex_str == "0C"
-        assert bits == 4
-
-    def test_single_byte_odd_hex_a(self):
-        hex_str, bits = PARSE_HEX("7'h3")
-        assert hex_str == "03"
-        assert bits == 7
-
-    def test_no_space(self):
-        assert PARSE_HEX("AABBCC") == ("AABBCC", 0)
-
-    def test_empty_string(self):
-        assert PARSE_HEX("") == ("", 0)
-
-    def test_whitespace_only(self):
-        assert PARSE_HEX("   ") == ("", 0)
-
-    def test_multiple_bit_marks_all_replaced(self):
-        hex_str, bits = PARSE_HEX("7'h03 AA 4'hC")
-        assert hex_str == "03AA0C"
-        assert bits == 4
-
-    def test_multiple_bit_marks_first_and_last(self):
-        hex_str, bits = PARSE_HEX("4'hA BB 7'h03")
-        assert hex_str == "0ABB03"
-        assert bits == 7
-
-    def test_three_bit_marks(self):
-        hex_str, bits = PARSE_HEX("4'h1 4'h2 4'h3")
-        assert hex_str == "010203"
-        assert bits == 4
-
-    def test_invalid_hex_raises(self):
-        with pytest.raises(ValueError, match="不合法的十六进制数据"):
-            PARSE_HEX("ZZZZ")
-
-    def test_odd_hex_digits_raises(self):
-        with pytest.raises(ValueError):
-            PARSE_HEX("ABC")
-
-    def test_hex_with_uppercase(self):
-        assert PARSE_HEX("FF AA") == ("FFAA", 0)
-
-    def test_hex_with_lowercase(self):
-        assert PARSE_HEX("ff aa") == ("ffaa", 0)
-
-    def test_bit_mark_no_space_around(self):
-        hex_str, bits = PARSE_HEX("AA7'h03BB")
-        assert hex_str == "AA03BB"
-        assert bits == 7
-
-    def test_bit_mark_only(self):
-        hex_str, bits = PARSE_HEX("8'hFF")
-        assert hex_str == "FF"
-        assert bits == 8
-
-    def test_bit_mark_with_lower_hex(self):
-        hex_str, bits = PARSE_HEX("7'h0a")
-        assert hex_str == "0a"
-        assert bits == 7
-
-    def test_roundtrip_with_format(self):
-        data = [0xAA, 0xBB, 0x03]
-        formatted = FORMAT_HEX(data, 7)
-        parsed, bits = PARSE_HEX(formatted)
-        assert bits == 7
-        assert bytes.fromhex(parsed) == bytes(data)
-
-    def test_roundtrip_single_byte(self):
-        formatted = FORMAT_HEX(0xFF, 4)
-        parsed, bits = PARSE_HEX(formatted)
-        assert bits == 4
-        assert parsed == "FF"
-
-    def test_roundtrip_no_bits(self):
-        formatted = FORMAT_HEX([0x01, 0x02, 0x03])
-        parsed, bits = PARSE_HEX(formatted)
-        assert bits == 0
-        assert parsed == "010203"
-
-
-class TestFORMAT_HEX:
-
-    def test_int_no_bits(self):
-        assert FORMAT_HEX(0xAABBCC) == "AA BB CC"
-
-    def test_int_with_bits(self):
-        assert FORMAT_HEX(0xAABB03, 7) == "AA BB 7'h03"
-
-    def test_int_single_byte_bits(self):
-        assert FORMAT_HEX(0xFF, 4) == "4'hFF"
-
-    def test_bytes_no_bits(self):
-        assert FORMAT_HEX(b'\xAA\xBB\xCC') == "AA BB CC"
-
-    def test_bytes_with_bits(self):
-        assert FORMAT_HEX(b'\xAA\xBB\x03', 7) == "AA BB 7'h03"
-
-    def test_list_no_bits(self):
-        assert FORMAT_HEX([0xAA, 0xBB, 0xCC]) == "AA BB CC"
-
-    def test_list_with_bits(self):
-        assert FORMAT_HEX([0xAA, 0xBB, 0x03], 7) == "AA BB 7'h03"
-
-    def test_str_no_bits(self):
-        assert FORMAT_HEX("AABBCC") == "AA BB CC"
-
-    def test_str_with_bits(self):
-        assert FORMAT_HEX("AABB03", 7) == "AA BB 7'h03"
-
-    def test_empty_string(self):
-        assert FORMAT_HEX("") == ""
-
-    def test_empty_bytes(self):
-        assert FORMAT_HEX(b'') == ""
-
-    def test_empty_list(self):
-        assert FORMAT_HEX([]) == ""
-
-    def test_unsupported_type(self):
-        with pytest.raises(TypeError, match="不支持的输入类型"):
-            FORMAT_HEX(3.14)
-
-    def test_hex_str_with_spaces(self):
-        assert FORMAT_HEX("AA BB CC") == "AA BB CC"
-
-    def test_lowercase_int(self):
-        assert FORMAT_HEX(0xff) == "FF"
-
-    def test_int_zero(self):
-        assert FORMAT_HEX(0) == "00"
-
-    def test_bytes_single(self):
-        assert FORMAT_HEX(b'\xFF') == "FF"
-
-    def test_list_single(self):
-        assert FORMAT_HEX([0xFF]) == "FF"
-
-    def test_int_large(self):
-        assert FORMAT_HEX(0xAABBCCDD) == "AA BB CC DD"
-
-    def test_bits_1(self):
-        assert FORMAT_HEX(0x01, 1) == "1'h01"
-
-    def test_bits_7(self):
-        assert FORMAT_HEX(0x26, 7) == "7'h26"