Merge upstream PR wireviz#357: Add optional per-node tweak with name placeholder

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: brettjforsyth

docs/syntax.md

@@ -85,6 +85,10 @@ tweak:  # optional tweaking of .gv output
   # loops
   loops: <List>  # every list item is itself a list of exactly two pins
                  # on the connector that are to be shorted
+
+  # optional tweaking of .gv output executed for each instance of this connector
+  tweak:  # see below
+
 ```
 
 ## Cable attributes
@@ -148,6 +152,9 @@ tweak:  # optional tweaking of .gv output
   show_wirecount: <bool>    # defaults to true
   show_wirenumbers: <bool>  # defaults to true for cables; false for bundles
 
+  # optional tweaking of .gv output executed for each instance of this cable
+  tweak:  # see below
+
 ```
 
 ## Connection sets
@@ -452,6 +459,13 @@ Alternatively items can be added to just the BOM by putting them in the section
   # This feature is experimental and might change
   # or be removed in future versions.
 
+  placeholder: <str>  # Substring to be replaced with node name
+    # An empty string as placeholder disable replacements.
+    # When placeholder is absent, the global placeholder is used.
+    # For tweak sections in connectors and cables, all substrings
+    # matching the placeholder text will be replaced with the name
+    # of connector/cable in all override and append entries.
+
   override:  # dict of .gv entries to override
     # Each entry is identified by its leading string
     # in lines beginning with a TAB character.

src/wireviz/DataClasses.py

@@ -72,6 +72,7 @@ def __post_init__(self):
 
 @dataclass
 class Tweak:
+    placeholder: Optional[PlainText] = None
     override: Optional[Dict[Designator, Dict[str, Optional[str]]]] = None
     append: Union[str, List[str], None] = None
 
@@ -163,10 +164,13 @@ class Connector:
     loops: List[List[Pin]] = field(default_factory=list)
     ignore_in_bom: bool = False
     additional_components: List[AdditionalComponent] = field(default_factory=list)
+    tweak: Optional[Tweak] = None
 
     def __post_init__(self) -> None:
         if isinstance(self.image, dict):
             self.image = Image(**self.image)
+        if self.tweak is not None:
+            self.tweak = Tweak(**self.tweak)
 
         self.ports_left = False
         self.ports_right = False
@@ -328,10 +332,13 @@ class Cable:
     show_wirenumbers: Optional[bool] = None
     ignore_in_bom: bool = False
     additional_components: List[AdditionalComponent] = field(default_factory=list)
+    tweak: Optional[Tweak] = None
 
     def __post_init__(self) -> None:
         if isinstance(self.image, dict):
             self.image = Image(**self.image)
+        if self.tweak is not None:
+            self.tweak = Tweak(**self.tweak)
 
         if isinstance(self.gauge, str):  # gauge and unit specified
             try:

src/wireviz/Harness.py

@@ -29,6 +29,7 @@
     component_table_entry,
     generate_bom,
     get_additional_component_table,
+    make_list,
     pn_info_string,
 )
 from wireviz.wv_colors import get_color_hex, translate_color
@@ -80,12 +81,47 @@ def __post_init__(self):
         self._bom = []  # Internal Cache for generated bom
         self.additional_bom_items = []
 
+    def extend_tweak(self, node: Union[Connector, Cable]) -> None:
+        """Extend self.tweak with node.tweak after replacing placeholders."""
+        if node.tweak:
+            ph = node.tweak.placeholder
+            # An empty string is a legal value to avoid the global placeholder
+            if ph is None:  # This must therefore be a test for None!
+                ph = self.tweak.placeholder  # Use the global placeholder
+            # Create function rph() to replace any placeholder with node name
+            rph = (
+                (lambda s: s.replace(ph, node.name) if isinstance(s, str) else s)
+                if ph
+                else lambda s: s  # No-change-lambda if no placeholder
+            )
+            n_override = node.tweak.override or {}
+            s_override = self.tweak.override or {}
+            for id, n_dict in n_override.items():
+                id = rph(id)
+                s_dict = s_override.get(id, {})
+                for k, v in n_dict.items():
+                    k, v = rph(k), rph(v)
+                    if k in s_dict and v != s_dict[k]:
+                        raise ValueError(
+                            f"{node.name}.tweak.override.{id}.{k}={v!r} conflicts"
+                            f" with tweak.override.{id}.{k}={s_dict[k]!r}"
+                        )
+                    s_dict[k] = v
+                s_override[id] = s_dict  # Never empty, because nothing deleted
+            self.tweak.override = s_override or None
+            self.tweak.append = (
+                make_list(self.tweak.append)
+                + [rph(v) for v in make_list(node.tweak.append)]
+            ) or None
+
     def add_connector(self, name: str, *args, **kwargs) -> None:
         check_old(f"Connector '{name}'", OLD_CONNECTOR_ATTR, kwargs)
         self.connectors[name] = Connector(name, *args, **kwargs)
+        self.extend_tweak(self.connectors[name])
 
     def add_cable(self, name: str, *args, **kwargs) -> None:
         self.cables[name] = Cable(name, *args, **kwargs)
+        self.extend_tweak(self.cables[name])
 
     def add_mate_pin(self, from_name, from_pin, to_name, to_pin, arrow_type) -> None:
         self.mates.append(MatePin(from_name, from_pin, to_name, to_pin, arrow_type))