Implement mates between connectors, better autogeneration

docs/syntax.md

@@ -85,22 +85,8 @@ 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
-
-  # auto-generation
-  autogenerate: <bool>  # optional; defaults to false; see below
-
 ```
 
-### Auto-generation of connectors
-
-The `autogenerate: true` option is especially useful for very simple, recurring connectors such as crimp ferrules, splices, and others, where it would be a hassle to individually assign unique designators for every instance.
-
-By default, when defining a connector, it will be generated once using the specified designator, and can be referenced multiple times, in different connection sets (see below).
-
-If `autogenerate: true` is set, the connector will _not_ be generated at first. When defining the `connections` section (see below), every time the connector is mentioned, a new instance with an auto-incremented designator is generated and attached.
-
-Since the auto-incremented and auto-assigned designator is not known to the user, one instance of the connector can not be referenced again outside the point of creation. The `autogenerate: true` option is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out. If more wires are to be attached (e.g. for a three-way splice, or a crimp where multiple wires are joined), a separate connector with `autogenerate: false` and a user-defined, unique designator needs to be used.
-
 ## Cable attributes
 
 ```yaml
@@ -173,6 +159,7 @@ connections:
   -                # Each list entry is a connection set
     - <component>    # Each connection set is itself a list of items
     - <component>    # Items must alternatingly belong to the connectors and cables sections
+                     # Arrows may be used instead of cables
     -...
 
   - # example (single connection)
@@ -189,6 +176,18 @@ connections:
     - [<connector>, ..., <connector>]     # specify multiple simple connectors to attach in parallel
                                           # these may be unique, auto-generated, or a mix of both
 
+  - # example (arrows between pins)
+    - <connector>: [<pin>, ..., <pin>]
+    - [<arrow>, ..., <arrow>]             # draw arrow linking pins of both connectors
+                                          # use single line arrows (--, <--, <-->, -->)
+    - <connector>: [<pin>, ..., <pin>]
+
+  - # example (arrows between connectors)
+    - <connector>                  
+    - <arrow>                               # draw arrow linking the connectors themselves
+                                            # use double line arrow (==, <==, <==>, ==>)
+    - <connector>
+
   ...    
 ```
 
@@ -199,6 +198,7 @@ connections:
 - When a connection set defines multiple parallel connections, the number of specified `<pin>`s and `<wire>`s for each component in the set must match. When specifying only one designator, one is auto-generated for each connection of the set.
 - `<pin>` may reference a pin's unique ID (as per the connector's `pins` attribute, auto-numbered from 1 by default) or its label (as per `pinlabels`).
 - `<wire>` may reference a wire's number within a cable/bundle, its label (as per `wirelabels`) or, if unambiguous, its color.
+- For `<arrow>`, see below.
 
 ### Single connections
 
@@ -249,6 +249,80 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
   - `<int>-<int>` auto-expands to a range.
   - `<str>` to refer to a wire's label or color, if unambiguous.
 
+### Arrows
+
+Arrows may be used in place of wires to join two connectors. This can represent the mating of matching connectors.
+
+To represent joining individual pins between two connectors, a list of single arrows is used:
+```yaml
+connections:
+  -
+    - <connector>: [<pin>,...,<pin>]
+    - [<arrow>, ..., <arrow>]         # --, <--, <--> or -->
+    - <connector>: [<pin>,...,<pin>]
+```
+
+To represent mating of two connectors as a whole, one double arrow is used:
+```yaml
+connections:
+  -
+    - <connector>  # using connector designator only
+    - <arrow>      # ==, <==, <==> or ==>
+    - <connector>
+  -
+    - ...
+    - <connector>: [<pin>, ...]  # designator and pinlist (pinlist is ignored)
+                                 # useful when combining arrows and wires
+    - <arrow>                    # ==, <==, <==> or ==>
+    - <connector>: [<pin>, ...]
+    - ...
+```
+
+### Autogeneration of items
+
+For very simple, recurring connectors such as crimp ferrules, splices and others, where it would be a hassle to individually assign unique designators for every instance, autogeneration may be used. Both connectors and cables can be autogenerated.
+
+Example (see `connections` section):
+
+```yaml
+connectors:
+  X:
+    # ...
+  Y:
+    # ...
+  Z:
+    style: simple
+    # ...
+cables:
+  V:
+    # ...
+  W:
+    # ...
+
+connections:
+  -  # no autogeneration (normal use)
+    - X: [1,2,...]  # Use X as both the template and the instance designator
+    - V: [1,2,...]  # Use V as both the template and the instance designator
+    # ...
+
+  -  # autogeneration of named instances
+    - Y.Y1: [1,2,...]  # Use template Y, generate instance with designator Y1
+    - W.W1: [1,2,...]  # Use template W, generate instance with designator W1
+    - Y.Y2: [1,2,...]  # generate more instances from the same templates
+    - W.W2: [1,2,...]
+    - Y.Y3: [1,2,...]  
+
+  -  # autogeneration of unnamed instances
+    - Y3:   [1,2,...]  # reuse existing instance Y3
+    - W.W4: [1,2,...]
+    - Z.             # Use template Z, generate one unnamed instance
+                     # for each connection in set
+```
+
+Since the internally assigned designator of an unnamed component is not known to the user, one instance of the connector can not be referenced again outside the point of creation (i.e. in other connection sets, or later in the same set). Autogeneration of unnamed instances is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out.
+If a component is to be used in other connection sets (e.g. for a three-way splice, or a crimp where multiple wires are joined), a named instance needs to be used.
+
+Names of autogenerated components are hidden by default. While they can be shown in the graphical output using the `show_name: true` option, it is not recommended to manually use the internally assigned designator (starting with a double underscore `__`), since it might change in future WireViz versions, or when the order of items in connection sets changes.
 
 
 ## Metadata entries
@@ -300,6 +374,7 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
   mini_bom_mode: <bool>        # Default = True
 ```
 
+
 ## BOM items and additional components
 
 Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM,

examples/demo02.yml

@@ -22,9 +22,8 @@ connectors:
   X4:
     <<: *molex_f
     pinlabels: [GND, +12V, MISO, MOSI, SCK]
-  ferrule_crimp:
+  F:
     style: simple
-    autogenerate: true
     type: Crimp ferrule
     subtype: 0.25 mm²
     color: YE
@@ -64,6 +63,6 @@ connections:
     - W3: [1-4]
     - X4: [1,3-5]
   -
-    - ferrule_crimp
+    - F.
     - W4: [1,2]
     - X4: [1,2]

examples/ex04.yml

@@ -8,13 +8,12 @@ cables:
     category: bundle
 
 connectors:
-  ferrule_crimp:
+  F:
     style: simple
-    autogenerate: true
     type: Crimp ferrule
 
 connections:
   -
-    - ferrule_crimp
+    - F.
     - W1: [1-6]
-    - ferrule_crimp
+    - F.

examples/ex11.yml

@@ -0,0 +1,25 @@
+# based on @stmaxed's example in #134
+
+connectors:
+  X1: &X
+    type: Screw connector
+    subtype: male
+    color: GN
+    pincount: 4
+    pinlabels: [A, B, C, D]
+  F:
+    style: simple
+    type: Ferrule
+    color: GY
+
+cables:
+  W:
+    color: BK
+    colors: [BK, WH, BU, BN]
+
+connections:
+  -  # ferrules + connector X1
+    - W.W1: [1-4]
+    - F.
+    - -->
+    - X1: [1-4]

examples/ex12.yml

@@ -0,0 +1,25 @@
+# based on @MSBGit's example in #134
+
+connectors:
+  X1: &dupont
+    type: Dupont 2.54mm
+    subtype: male
+    pincount: 5
+    color: BK
+  X2:
+    <<: *dupont
+    subtype: female
+
+cables:
+  W:
+    category: bundle
+    colors: [RD, BK, BU, GN]
+    length: 0.2
+
+connections:
+  -
+    - W.W1: [1-4]
+    - X1: [1-4]
+    - ==>
+    - X2: [1-4]
+    - W.W2: [1-4]

examples/ex13.yml

@@ -0,0 +1,26 @@
+# based on @formatc1702's example in #184
+
+connectors:
+  X:
+    pincount: 4
+    pinlabels: [A, B, C, D]
+  F:
+    style: simple
+    type: ferrule
+
+cables:
+  C:
+    wirecount: 4
+    color_code: DIN
+
+connections:
+  -
+    - X.X1: [1-4]
+    - C.C1: [1-4]
+    - [F.F1, F.F2, F.F3, F.F4]  # generate new instances of F and assign designators
+    - C.C2: [1-4]
+    - X.X2: [1-4]
+  -
+    - [F1, F2, F3, F4]  # use previously assigned designators
+    - C.C3: [1-4]
+    - X.X3: [1-4]

examples/ex14.yml

@@ -0,0 +1,55 @@
+connectors:
+  JSTMALE: &JST_SM  # use generic names here, assign designators at generation time
+    type: JST SM
+    subtype: male
+    pincount: 4
+    pinlabels: [A, B, C, D]
+  JSTFEMALE:
+    <<: *JST_SM  # easily create JSTMALE's matching connector
+    subtype: female
+  X4:  # this connector is only used once, use fixed designator here already
+    type: Screw terminal connector
+    pincount: 4
+    color: GN
+    pinlabels: [W, X, Y, Z]
+  S:
+    style: simple
+    type: Splice
+    color: CU
+  F:
+    style: simple
+    type: Ferrule
+    color: GY
+
+
+cables:
+  CABLE:
+    wirecount: 4
+    color_code: DIN
+    length: 0.1
+  WIRE:
+    wirecount: 1
+    colors: [BK]
+    length: 0.1
+
+connections:
+  -
+    - JSTMALE.X1: [4-1]   # use `.` syntax to generate a new instance of JSTMALE, named X1
+    - CABLE.W1: [1-4]     # same syntax for cables
+    - [S., S., S.S1, S.]  # splice W1 and W2 together; only wire #3 needs a user-defined designator
+    - CABLE.W2: [1-4]
+    - S.                  # test shorthand, auto-get required number of ferrules from context
+    - CABLE.W21: [1-4]
+    - JSTFEMALE.X2: [1-4]
+    - <=>                 # mate X2 and X3
+    - JSTMALE.X3: [1-4]
+    - CABLE.W3: [1-4]
+    - [F., F., F., F.]
+    - -->                 # insert ferrules into screw terminal connector
+    - X4: [2,1,4,3]       # X4 does not require auto-generation, thus no `.` syntax here
+  -
+    - S1: [1]             # reuse previously generated splice
+                          # TODO: Make it work with `- F1` only, making pin 1 is implied
+    - WIRE.: [1]          # We don't care about a simple wire's designator, auto-generate please!
+                          # TODO: Make it work with `- W.W4: 1`, dropping the need for `[]`
+    - X2: [4]