parsing#

Lightweight parsers for KnotPy notations.

Functions here parse tiny, dependency-free fragments such as endpoints (a12), arcs (two endpoints concatenated, e.g. a1b5), comma-separated arc lists, and simple “rows of integers” strings.

These utilities are intentionally strict and small; they’re used by several notation modules and should stay fast and import-light.

Functions

`parse_arc`(arc)	Parse a concatenated arc like `'a1b5'` → `(('a', 1), ('b', 5))`.
`parse_arcs`(arcs)	Parse a comma-separated list of arcs.
`parse_endpoint`(endpoint)	Parse a single endpoint like `'a9'` into `('a', 9)`.
`parse_spaced_rows`(data_str)	Parse space-separated integers into one row or multiple rows.
`universal_list_of_lists_parser`(input_str)	Best-effort parser for “list of lists” written in a few loose styles.

parse_endpoint(endpoint)#

Parse a single endpoint like 'a9' into ('a', 9).

Accepts exactly one ASCII letter followed by one or more digits. Whitespace around the letter and digits is ignored.

Parameters:: endpoint (str) – Endpoint string, e.g. 'a0', 'Z12'.
Returns:: (letter, index) pair.
Raises:: ValueError – If the format is invalid.
Return type:: Tuple[str, int]

parse_arc(arc)#

Parse a concatenated arc like 'a1b5' → (('a', 1), ('b', 5)).

The function finds exactly two endpoint tokens (letter+digits). Tokens may have surrounding whitespace.

Parameters:: arc (str) – Arc string, e.g. 'a1b5' or ' a12 b003 '.
Returns:: A pair of parsed endpoints.
Raises:: ValueError – If exactly two endpoints are not found or any endpoint is invalid.
Return type:: Tuple[Tuple[str, int], Tuple[str, int]]

parse_arcs(arcs)#

Parse a comma-separated list of arcs.

Example

'a6b6, a9u8' → [(('a', 6), ('b', 6)), (('a', 9), ('u', 8))].

Parameters:: arcs (str) – A string like 'a1b2, c3d4' (commas may be surrounded by spaces).
Returns:: List of parsed arcs.
Raises:: ValueError – If any individual arc is invalid.
Return type:: List[Tuple[Tuple[str, int], Tuple[str, int]]]

parse_spaced_rows(data_str)#

Parse space-separated integers into one row or multiple rows.

Accepts commas or semicolons as row separators.

Examples

"1 2 3" → [1, 2, 3]
"1 2 3, 4 5 -6" → [[1, 2, 3], [4, 5, -6]]
"1 2 3 ; 4 5 -6" → [[1, 2, 3], [4, 5, -6]]

Parameters:: data_str (str) – Input string.
Returns:: A single list of ints if one row is given, otherwise list of rows.
Return type:: List[int] | List[List[int]]

universal_list_of_lists_parser(input_str)#

Best-effort parser for “list of lists” written in a few loose styles.

This helper is kept for compatibility and is intentionally permissive. It supports inputs like:

"[1 2 3], [4 5 6]"
"(1 2 3) (4 5 6)"
"1 2 3, 4 5 6"
"1 2 3; 4 5 -6"

Items are split by commas/whitespace; integers are converted to int, other tokens are kept as str.

Parameters:: input_str (str) – Source text.
Returns:: A list of lists with parsed items.
Return type:: List[List[str | int]]

Notes

This is not a general parser. Prefer structured formats where possible.