[feature] Improved auto-generated connectors and cables

[formatc1702]

From the syntax description:

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.

An idea to remove the restriction of not knowing the designator of auto-generated connectors and not being able to reference them at a later point, would be to add a new syntax feature to allow the user to assign designators to auto-generated connectors.

Proposed syntax:

X.X1

[Edit 2020-10-22: changed from -> to . to distinguish from arrows proposed in #134]

This would generate a new instance of component X and assign it the X1 designator. This is just an idea, an other possible alternatives come to mind:

• X.X1
• X->X1 (possible confusion with arrow notation discussed in #134)
• X:X1 (seems to be legal YAML, even when used as dict key X:X1: [1-4] but probably risky/confusing)
• X$X1
• X1(X)
• X1@X
• and many more The following example takes this a step further, and proposes auto-generating cables as well.

Example for a Y-splice, reusing connectors, ferrules and cables through auto-generation:

connectors:
  X:
    autogenerate: true
    pincount: 4

  F:
    autogenerate: true
    style: simple
    type: ferrule

cables:
  C:
    autogenerate: true
    wirecount: 4
    color_code: DIN

connections:
  -
    - X.X2: [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]

The idea is to make the new syntax work in additon to the current one, which generates unknown, auto-incremented designators not exposed to the user, since that should be good enough for simple cases.

[kvid]

The idea is to make the new syntax work in additon to the current one, which generates unknown, auto-incremented designators not exposed to the user, since that should be good enough for simple cases.

Another idea is that now, when you consider a new syntax for auto-generation of connectors that specifies the resulting designator: Maybe also consider a variation of the same syntax for any auto-generation to release the current single designator syntax for other usage, e.g. a few alternatives:

• X.X1 to specify new designator and X. to replace the current X syntax.
• X1$X to specify new designator and $X to replace the current X synatx.
• X1(X) to specify new designator and (X) to replace the current X syntax.
• X1@X to specify new designator and @X to replace the current X syntax.
• and many more

There might come other needs for the single designator syntax, e.g. as you complain about in https://github.com/formatc1702/WireViz/issues/134#issuecomment-714295069.

[formatc1702]

Let me see if I understand you correctly, by implementing the example I recently used in #185 with your proposed syntax, using . as the magic character.

connectors:
  S:
    style: simple
    # autogenerate: true  # perhaps no longer needed in @kvid's proposed syntax?
    type: splice
    show_name: false

cables:
  W1:
    wirecount: 3
    color_code: DIN
  W2:
    wirecount: 4
    color_code: IEC

connections:
  -
    - W1: [1-3]
    - [S., S., S.S1]  # wires 1+2 use autogenerated splice connectors with unknown autogenerated designator
                      # wire 3   uses autogenerated splice connector  with user-specified        designator
    - W2: [1-3]
  -
    - S1          # reuse S1 for the three-way splice (no need to use S.S1 again since it is already instantiated)
    - W2: 4

[formatc1702]

I have re-read your post and now understand what you mean. I have moved my comment originally posted in 134:

I think instead of - F1. like you propose, I would prefer a more explicit - F1.*N to mean "generate N instances of F1", i.e. - F1*4 being interpreted as - [F1, F1, F1, F1].

This places the "burden" on the user to make sure N matches the pincount/wirecount of the other items in the set, but that is reasonable IMHO, and it's easier to distinguish from the use-case of - F1 meaning "the entire connector"

[formatc1702]

General note: The following notations should be allowed for referencing connectors and cables within a connection set:

• - X1: [...] creates an instance of X1 named X1 the first time it is used, references that instance every subsequent time
• - X.X1: [...] creates an instance of X named X1 the first time it is used.
  • Subsequent calls can use X1 to reference the already created instance
  • Using X.X1 again should also reference that instance
• - X.: [...] creates an instance of X and assigns it an auto-generated designator (likely something like _X1)
  • Subsequent calls generate additional components with new auto-generated designators
  • Since the designator is not known to the user, it cannot be reused. This is analogous to the current behavior of auto-generated connectors

[formatc1702]

Closed in #186.