librelane 2.4.0.dev0__py3-none-any.whl → 2.4.0.dev3__py3-none-any.whl

librelane/__main__.py

@@ -1,3 +1,7 @@
+# Copyright 2025 The American University in Cairo
+#
+# Adapted from OpenLane
+#
 # Copyright 2023 Efabless Corporation
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -202,7 +206,8 @@ def print_version(ctx: click.Context, param: click.Parameter, value: bool):
         f"""
         LibreLane v{__version__}
 
-        Copyright ©2020-2023 Efabless Corporation and other contributors.
+        Copyright ©2020-2025 Efabless Corporation, The American University in
+        Cairo, and other contributors.
 
         Available under the Apache License, version 2. Included with the source code,
         but you can also get a copy at https://www.apache.org/licenses/LICENSE-2.0

librelane/config/config.py

@@ -102,7 +102,7 @@ class PassedDirectoryError(ValueError):
     def __init__(self, config: AnyPath) -> None:
         self.config = str(config)
         super().__init__(
-            "Passing design directories as arguments is unsupported in LibreLane 2 or higher: please pass the configuration file(s) directly."
+            "Passing design directories as arguments is unsupported in LibreLane: please pass the configuration file(s) directly."
         )
 
 
@@ -960,7 +960,7 @@ class Config(GenericImmutableDict[str, Any]):
                 pass
             if not isinstance(dis, int) or dis in [1, 2, 5] or dis > 6:
                 errors.append(
-                    f"DIODE_INSERTION_STRATEGY '{dis}' is not available in LibreLane 2 or higher. See 'Migrating DIODE_INSERTION_STRATEGY' in the docs for more info."
+                    f"DIODE_INSERTION_STRATEGY '{dis}' is not available in LibreLane 2.0 or higher. See 'Migrating DIODE_INSERTION_STRATEGY' in the docs for more info."
                 )
             else:
                 warnings.append(

librelane/config/variable.py

@@ -238,7 +238,7 @@ def some_of(t: Type[Any]) -> Type[Any]:
     return new_union  # type: ignore
 
 
-def repr_type(t: Type[Any]) -> str:  # pragma: no cover
+def repr_type(t: Type[Any], for_document: bool = False) -> str:  # pragma: no cover
     optional = is_optional(t)
     some = some_of(t)
 
@@ -247,18 +247,25 @@ def repr_type(t: Type[Any]) -> str:  # pragma: no cover
     else:
         type_string = str(some)
 
+    if is_dataclass(t):
+        type_string = (
+            f"{{class}}`{some.__qualname__} <{some.__module__}.{some.__qualname__}>`"
+        )
+
+    separator = "｜<br />" if for_document else "｜"
+
     if inspect.isclass(some) and issubclass(some, Enum):
-        type_string = "｜".join([str(e.name) for e in some])
+        type_string = separator.join([str(e.name) for e in some])
         type_string = f"`{type_string}`"
     else:
         origin, args = get_origin(some), get_args(some)
         if origin is not None:
             if origin == Union:
                 arg_strings = [repr_type(arg) for arg in args]
-                type_string = "｜".join(arg_strings)
+                type_string = separator.join(arg_strings)
                 type_string = f"({type_string})"
             elif origin == Literal:
-                return "｜".join([repr(arg) for arg in args])
+                return separator.join([repr(arg) for arg in args])
             else:
                 arg_strings = [repr_type(arg) for arg in args]
                 type_string = f"{type_string}[{', '.join(arg_strings)}]"
@@ -377,9 +384,7 @@ class Variable:
             for easier wrapping by web browsers/PDF renderers/what have you
         :returns: A pretty Markdown string representation of the Variable's type.
         """
-        if for_document:
-            return repr_type(self.type).replace("｜", "｜<br />")
-        return repr_type(self.type)
+        return repr_type(self.type, for_document=for_document)
 
     def desc_repr_md(self) -> str:  # pragma: no cover
         """

librelane/container.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-## This file is internal to LibreLane 2 and is not part of the API.
+## This file is internal to LibreLane and is not part of the API.
 import os
 import re
 import uuid

librelane/env_info.py

@@ -18,7 +18,7 @@
 # environment surveys. Please ensure all code as compatible as possible
 # with ancient versions of Python.
 
-## This file is internal to LibreLane 2 and is not part of the API.
+## This file is internal to LibreLane and is not part of the API.
 import os
 import re
 import sys

librelane/flows/classic.py

@@ -30,11 +30,8 @@ from ..steps import (
 @Flow.factory.register()
 class Classic(SequentialFlow):
     """
-    **Note: While LibreLane 2 has a stable release, the default flow is in beta
-    pending silicon validation. Use at your own risk.**
-
     A flow of type :class:`librelane.flows.SequentialFlow` that is the most
-    similar to the original LibreLane 1.0 flow, running the Verilog RTL through
+    similar to the original OpenLane flow, running the Verilog RTL through
     Yosys, OpenROAD, KLayout and Magic to produce a valid GDSII for simpler designs.
 
     This is the default when using LibreLane via the command-line.

librelane/flows/optimizing.py

@@ -23,7 +23,7 @@ from ..steps import Step, Yosys, OpenROAD, StepError
 from ..logging import get_log_level, set_log_level, LogLevels, success, info
 
 
-#   "Optimizing" is a custom demo flow to show what's possible with non-sequential Flows in LibreLane 2+.
+#   "Optimizing" is a custom demo flow to show what's possible with non-sequential Flows in LibreLan
 #   It works across two steps:
 #   * The Synthesis Exploration - tries multiple synthesis strategies in *parallel*.
 #       The best-performing strategy in terms of minimizing the area makes it to the next stage.

librelane/scripts/odbpy/defutil.py

@@ -21,7 +21,6 @@ from decimal import Decimal
 
 from reader import click_odb, click
 from typing import Tuple, List
-from exception_codes import METAL_LAYER_ERROR, FORMAT_ERROR, NOT_FOUND_ERROR
 
 
 @click.group()
@@ -481,7 +480,7 @@ def parse_obstructions(obstructions) -> List[Tuple[str, List[int]]]:
                 f"[ERROR] Incorrectly formatted input {obs}.\n Format: layer llx lly urx ury, ...",
                 file=sys.stderr,
             )
-            sys.exit(FORMAT_ERROR)
+            sys.exit(1)
         else:
             layer = m.group("layer")
             bbox = [Decimal(x) for x in m.group("bbox").split()]
@@ -505,8 +504,8 @@ def add_obstructions(reader, input_lefs, obstructions):
         layer = obs[0]
         odb_layer = reader.tech.findLayer(layer)
         if odb_layer is None:
-            print(f"[ERROR] layer {layer} doesn't exist.", file=sys.stderr)
-            sys.exit(METAL_LAYER_ERROR)
+            print(f"[ERROR] Layer '{layer}' not found.", file=sys.stderr)
+            sys.exit(1)
         bbox = obs[1]
         dbu = reader.tech.getDbUnitsPerMicron()
         bbox = [int(x * dbu) for x in bbox]
@@ -550,8 +549,8 @@ def remove_obstructions(reader, input_lefs, obstructions):
         bbox = [int(x * dbu) for x in bbox]  # To dbus
         found = False
         if reader.tech.findLayer(layer) is None:
-            print(f"[ERROR] layer {layer} doesn't exist.", file=sys.stderr)
-            sys.exit(METAL_LAYER_ERROR)
+            print(f"[ERROR] Layer '{layer}' not found.", file=sys.stderr)
+            sys.exit(1)
         for odb_obstruction in existing_obstructions:
             odb_layer, odb_bbox, odb_obj = odb_obstruction
             if (odb_layer, odb_bbox) == (layer, bbox):
@@ -565,7 +564,7 @@ def remove_obstructions(reader, input_lefs, obstructions):
                 f"[ERROR] Obstruction on {layer} at {bbox} (DBU) not found.",
                 file=sys.stderr,
             )
-            sys.exit(NOT_FOUND_ERROR)
+            sys.exit(1)
 
 
 cli.add_command(remove_obstructions)

librelane/scripts/odbpy/eco_buffer.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+# Copyright 2025 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import sys
+from reader import click_odb, click, odb
+import grt as GRT
+
+
+def average_location(instances):
+    locations = [instance.getLocation() for instance in instances]
+    x_sum = sum(loc[0] for loc in locations)
+    y_sum = sum(loc[1] for loc in locations)
+    return (x_sum // len(locations), y_sum // len(locations))
+
+
+@click.command()
+@click_odb
+def cli(reader):
+    grt = reader.design.getGlobalRouter()
+    dpl = reader.design.getOpendp()
+
+    insts_to_temporarily_lock_then_unlock_later = []
+    for inst in reader.block.getInsts():
+        if inst.getPlacementStatus() != "LOCKED":
+            insts_to_temporarily_lock_then_unlock_later.append(
+                (inst, inst.getPlacementStatus())
+            )
+            inst.setPlacementStatus("LOCKED")
+
+    reader._grt_setup(grt)
+
+    grt_inc = GRT.IncrementalGRoute(grt, reader.block)
+    i = 0
+
+    for target_info in reader.config["INSERT_ECO_BUFFERS"]:
+        target_name, target_pin = target_info["target"].split("/")
+        name_escaped = reader.escape_verilog_name(target_name)
+        buffer_master = target_info["buffer"]
+
+        master = reader.db.findMaster(buffer_master)
+        if master is None:
+            print(
+                f"[ERROR] Buffer type '{buffer_master}' not found.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        target = reader.block.findInst(name_escaped)
+        if target is None:
+            print(f"[ERROR] Instance '{target_name}' not found.", file=sys.stderr)
+            exit(-1)
+
+        target_iterm = target.findITerm(target_pin)
+        if target_iterm is None:
+            print(
+                f"[ERROR] Pin '{target_pin}' not found for instance '{target_name}'.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        net = target_iterm.getNet()
+        if net is None:
+            print(
+                f"[ERROR] Net not found on pin '{target_pin}' of instance '{target_name}'.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        new_buf_name = f"eco_buffer_{i}"
+        new_net_name = f"eco_buffer_{i}_net"
+        while (
+            reader.block.findInst(new_buf_name) is not None
+            or reader.block.findNet(new_net_name) is not None
+        ):
+            i += 1
+            new_buf_name = f"eco_buffer_{i}"
+            new_net_name = f"eco_buffer_{i}_net"
+
+        # Prepare buffer cell, net
+        eco_buffer = odb.dbInst.create(reader.block, master, new_buf_name)
+        eco_net = odb.dbNet.create(reader.block, new_net_name)
+        buffer_iterms = eco_buffer.getITerms()
+        buffer_a = None
+        for iterm in buffer_iterms:
+            if iterm.isInputSignal():
+                buffer_a = iterm
+                break  # Exit loop once input is found
+        if buffer_a is None:
+            print(
+                f"[ERROR] Buffer {buffer_master} has no input signals.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        buffer_x = None
+        for iterm in buffer_iterms:
+            if iterm.isOutputSignal():
+                buffer_x = iterm
+                break  # Exit loop once output is found
+        if buffer_x is None:
+            print(
+                f"[ERROR] Buffer {buffer_master} has no output signals.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        location_instances = [target]
+        net_iterms = net.getITerms()
+        if target_iterm.getIoType() == "INPUT":
+            driver_iterms = [
+                iterm for iterm in net_iterms if iterm.getIoType() in ["OUTPUT"]
+            ]
+            drivers = [iterm.getInst() for iterm in driver_iterms]
+            location_instances.extend(drivers)
+
+            target_iterm.disconnect()
+            buffer_a.connect(net)
+            buffer_x.connect(eco_net)
+            target_iterm.connect(eco_net)
+        elif target_iterm.getIoType() == "OUTPUT":
+            sink_iterms = [
+                iterm for iterm in net_iterms if iterm.getIoType() in ["INPUT", "INOUT"]
+            ]
+            sinks = [iterm.getInst() for iterm in sink_iterms]
+            location_instances.extend(sinks)
+
+            target_iterm.disconnect()
+            target_iterm.connect(eco_net)
+            buffer_a.connect(eco_net)
+            buffer_x.connect(net)
+        else:
+            print(
+                f"[ERROR] {target_name}/{target_pin} is neither an INPUT or an OUTPUT and is unsupported by this script. To buffer an INOUT port, buffer its drivers instead.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        if target_info.get("placement") is not None:
+            eco_x, eco_y = target_info["placement"]
+            eco_x = reader.block.micronsToDbu(float(eco_x))
+            eco_y = reader.block.micronsToDbu(float(eco_y))
+            eco_loc = (eco_x, eco_y)
+        else:
+            eco_loc = average_location(location_instances)
+
+        eco_buffer.setOrient("R0")
+        eco_buffer.setLocation(*eco_loc)
+        eco_buffer.setPlacementStatus("PLACED")
+        grt.addDirtyNet(net)
+        grt.addDirtyNet(eco_net)
+
+    site = reader.rows[0].getSite()
+    max_disp_x = int(
+        reader.design.micronToDBU(reader.config["PL_MAX_DISPLACEMENT_X"])
+        / site.getWidth()
+    )
+    max_disp_y = int(
+        reader.design.micronToDBU(reader.config["PL_MAX_DISPLACEMENT_Y"])
+        / site.getHeight()
+    )
+    dpl.detailedPlacement(max_disp_x, max_disp_y)
+
+    grt_inc.updateRoutes(True)
+
+    for inst, previous_status in insts_to_temporarily_lock_then_unlock_later:
+        inst.setPlacementStatus(previous_status)
+
+
+if __name__ == "__main__":
+    cli()

librelane/scripts/odbpy/eco_diode.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+# Copyright 2025 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import sys
+from reader import click_odb, click, odb
+import grt as GRT
+
+
+@click.command()
+@click_odb
+def cli(reader):
+    grt = reader.design.getGlobalRouter()
+    dpl = reader.design.getOpendp()
+
+    insts_to_temporarily_lock_then_unlock_later = []
+    for inst in reader.block.getInsts():
+        if inst.getPlacementStatus() != "LOCKED":
+            insts_to_temporarily_lock_then_unlock_later.append(
+                (inst, inst.getPlacementStatus())
+            )
+            inst.setPlacementStatus("LOCKED")
+
+    reader._grt_setup(grt)
+
+    diode_master, diode_pin = reader.config["DIODE_CELL"].split("/")
+
+    # print(grt)
+    grt_inc = GRT.IncrementalGRoute(grt, reader.block)
+    i = 0
+    for target_info in reader.config["INSERT_ECO_DIODES"]:
+        target_name, target_pin = target_info["target"].split("/")
+        name_escaped = reader.escape_verilog_name(target_name)
+
+        target = reader.block.findInst(name_escaped)
+        if target is None:
+            print(
+                f"[ERROR] Instance '{target_name}' not found.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        master = reader.db.findMaster(diode_master)
+        if master is None:
+            print(
+                f"[ERROR] Cell kind '{diode_master}' not found.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        target_iterm = target.findITerm(target_pin)
+        if target_iterm is None:
+            print(
+                f"[ERROR] Pin '{target_pin}' not found for instance {target_name}.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        if target_iterm.getIoType() not in ["INPUT", "INOUT"]:
+            print(
+                f"[ERROR] Pin {target_info['target']} is an OUTPUT pin.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        net = target_iterm.getNet()
+        if net is None:
+            print(
+                f"[ERROR] Pin {target_info['target']} has no nets connected.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        eco_diode_name = f"eco_diode_{i}"
+        while reader.block.findInst(eco_diode_name) is not None:
+            i += 1
+            eco_diode_name = f"eco_diode_{i}"
+
+        eco_diode = odb.dbInst.create(
+            reader.block,
+            master,
+            eco_diode_name,
+        )
+
+        diode_iterm = eco_diode.findITerm(diode_pin)
+        if diode_iterm is None:
+            print(
+                f"[ERROR] Pin '{diode_pin}' on ECO diode not found- invalid DIODE_CELL definition.",
+                file=sys.stderr,
+            )
+            exit(-1)
+
+        sys.stdout.flush()
+
+        if target_info["placement"] is not None:
+            x, y = target_info["placement"]
+            x = reader.block.micronsToDbu(float(x))
+            y = reader.block.micronsToDbu(float(y))
+        else:
+            x, y = target.getLocation()
+
+        eco_diode.setOrient("R0")
+        eco_diode.setLocation(x, y)
+        eco_diode.setPlacementStatus("PLACED")
+
+        diode_iterm.connect(net)
+        grt.addDirtyNet(net)
+
+    site = reader.rows[0].getSite()
+    max_disp_x = int(
+        reader.design.micronToDBU(reader.config["PL_MAX_DISPLACEMENT_X"])
+        / site.getWidth()
+    )
+    max_disp_y = int(
+        reader.design.micronToDBU(reader.config["PL_MAX_DISPLACEMENT_Y"])
+        / site.getHeight()
+    )
+    dpl.detailedPlacement(max_disp_x, max_disp_y)
+
+    grt_inc.updateRoutes(True)
+
+    for inst, previous_status in insts_to_temporarily_lock_then_unlock_later:
+        inst.setPlacementStatus(previous_status)
+
+    reader.design.writeDef("out.def")
+
+
+if __name__ == "__main__":
+    cli()

librelane/scripts/odbpy/{exception_codes.py → ioplace_parser/__init__.py}

@@ -1,4 +1,8 @@
-# Copyright 2023 Efabless Corporation
+# Copyright 2025 The American University in Cairo
+#
+# Adapted from ioplace_parser
+#
+# Copyright 2020-2023 Efabless Corporation
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -11,7 +15,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
-METAL_LAYER_ERROR = 10
-FORMAT_ERROR = 11
-NOT_FOUND_ERROR = 12
+"""
+This is a modified version of https://github.com/efabless/ioplace_parser that
+does NOT use Antlr4 and instead uses a custom parser that is faster and
+dependency-free.
+"""
+from .parse import Side, Order, parse

librelane/scripts/odbpy/ioplace_parser/parse.py

@@ -0,0 +1,147 @@
+# Copyright 2025 The American University in Cairo
+#
+# Adapted from ioplace_parser
+#
+# Copyright 2020-2023 Efabless Corporation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import re
+from enum import IntEnum
+from typing import Literal, Optional, Dict, List, Union
+from decimal import Decimal
+import warnings
+
+from dataclasses import dataclass, field
+
+
+class Order(IntEnum):
+    busMajor = 0
+    bitMajor = 1
+
+
+@dataclass
+class Side:
+    min_distance: Optional[Decimal] = None
+    reverse_result: bool = False
+    pins: List[Union[str, int]] = field(default_factory=list)
+    sort_mode: Optional[Order] = Order.busMajor
+
+
+VALUE_ANNOTATIONS = ["min_distance"]
+STANDALONE_ANNOTATIONS = [
+    "bus_major",
+    "bit_major",
+]
+
+
+def parse(string: str) -> Dict[Literal["N", "E", "W", "S"], Side]:
+    """
+    Parses a pin configuration into a dictionary of the four cardinal sides.
+
+    :param string: The input configuration as a string (not a file path)
+    :returns: A dictionary where each cardinal direction points to a Side object.
+    :raises ValueError: On syntax or token recognition errors
+    """
+    sides = {}
+    current_side: Optional[Side] = None
+    global_sort_mode: Order = Order.busMajor
+    global_min_distance: Optional[Decimal] = None
+
+    string_mut = string
+
+    ws_rx = re.compile(r"^\s+")
+    annotation_rx = re.compile(r"^@\s*(\w+)(?:\s*=\s*([0-9]+(?:.[0-9]+)?))?")
+    direction_rx = re.compile(r"^#\s*([NEWS]R?|BUS_SORT)")
+    virtual_pin_rx = re.compile(r"^\$\s*([0-9]+)")
+    non_ws_rx = re.compile(r"^\S+")
+    while len(string_mut):
+        # annotation
+        if skip_match := ws_rx.search(string_mut):
+            string_mut = string_mut[skip_match.end() :]
+        elif anno_match := annotation_rx.search(string_mut):
+            annotation = anno_match[1]
+            if annotation in VALUE_ANNOTATIONS:
+                if anno_match[2] is None:
+                    raise ValueError(f"Annotation {annotation} requires a value")
+                value = anno_match[2]
+                if annotation == "min_distance":
+                    if current_side is None:
+                        global_min_distance = Decimal(value)
+                    else:
+                        current_side.min_distance = Decimal(value)
+            elif annotation in STANDALONE_ANNOTATIONS:
+                if anno_match[2] is not None:
+                    raise ValueError(
+                        f"Annotation {annotation} cannot be assigned a value"
+                    )
+                if annotation == "bus_major":
+                    if current_side is None:
+                        global_sort_mode = Order.busMajor
+                    else:
+                        current_side.sort_mode = Order.busMajor
+                elif annotation == "bit_major":
+                    if current_side is None:
+                        global_sort_mode = Order.bitMajor
+                    else:
+                        current_side.sort_mode = Order.bitMajor
+            else:
+                raise ValueError(f"Unknown annotation '{annotation}'")
+            string_mut = string_mut[anno_match.end() :]
+        elif dir_match := direction_rx.search(string_mut):
+            direction = dir_match[1]
+            if direction == "BUS_SORT":
+                warnings.warn(
+                    "Specifying bit-major using the direction token ('#BUS_SORT') is deprecated: use @bit_major."
+                )
+                global_sort_mode = Order.bitMajor
+            else:
+                current_side = Side(
+                    min_distance=global_min_distance,
+                    reverse_result=len(direction) == 2,
+                    sort_mode=global_sort_mode,
+                )
+                side: Literal["N", "E", "W", "S"] = direction[0]  # type: ignore
+                sides[side] = current_side
+            string_mut = string_mut[dir_match.end() :]
+        elif vp_match := virtual_pin_rx.search(string_mut):
+            count = int(vp_match[1])
+            if current_side is None:
+                raise ValueError(
+                    f"virtual pin declaration ${count} requires a direction to be set first"
+                )
+            current_side.pins.append(count)
+            string_mut = string_mut[vp_match.end() :]
+        elif nonws_match := non_ws_rx.match(string_mut):
+            # assume regex
+            if current_side is None:
+                raise ValueError(
+                    f"identifier/regex '{nonws_match[0]}' requires a direction to be set first"
+                )
+            current_side.pins.append(nonws_match[0])
+            string_mut = string_mut[nonws_match.end() :]
+        else:
+            raise ValueError(
+                f"Syntax Error: Unexpected character starting at {string_mut[:10]}…"
+            )
+
+    all_sides: List[Literal["N", "E", "W", "S"]] = ["N", "E", "W", "S"]
+    for side in all_sides:
+        if side in sides:
+            continue
+        sides[side] = Side(
+            min_distance=global_min_distance,
+            reverse_result=False,
+            sort_mode=global_sort_mode,
+        )
+
+    return sides