@openpowershift/logic-diagram-language 0.1.0

package/spec/sections/examples.adoc

@@ -0,0 +1,212 @@
+== Complete Examples
+
+=== Simple Logic
+
+[source,ldl]
+----
+// Protection logic for CBFPS
+CBFPS = AB AND DC OR (NOT DC AND GF)
+
+// Style overrides
+STYLE
+  #G1 { stroke: red; }
+END STYLE
+----
+
+This expands to:
+
+. A NOT gate (anonymous) with input `DC` and output to the right AND gate.
+. An AND gate (`G1`) with inputs `AB`, `DC`.
+. An AND gate (anonymous) with inputs `(NOT DC)`, `GF`.
+. An OR gate (anonymous) combining the two AND gates' outputs.
+. Final output `CBFPS`.
+
+=== Timer Object
+
+[source,ldl]
+----
+// Timer-based protection
+SVT#1
+SVT#1.INPUT = A OR B
+SVT#1.PICKUP = 30 s
+SVT#1.DROPOUT = 10 s
+
+SVT#1.LINK = "https://docs.example.com/svt-timer"
+----
+
+=== Interlocking Example
+
+A realistic protection interlocking for a collector feeder close operation:
+
+[source,ldl]
+----
+// Interlocking Example for Collector Feeder Q01 (Close)
+
+I1.Name = "CBQ 00 Open"
+I1.Description = "(BI 3.1)"
+
+I2.Name = "BB Not Earthed"
+I2.Description = "(BI 3.24)"
+
+I3.Name = "D/S Q01 Open"
+I3.Description = "(BI 3.3)"
+
+I4.Name = "E/S Q05 Open"
+I4.Description = "(BI 3.5)"
+
+I5.Name = "KF1 Release"
+I5.Description = "(BI 3.15)"
+
+I6.Name = "In Remote"
+I6.Description = "(BI 3.11)"
+
+I7.Name = "SCADA ON"
+I7.Description = "(BI 3.23)"
+
+I8.Name = "DNP Close Command"
+I8.Description = "(via RTU)"
+
+I9.Name = "In Local"
+I9.Description = "(BI 3.12)"
+
+I10.Name = "Close Switch"
+I10.Description = "(BI 3.20)"
+
+O1 = (I1 AND I2) AND (I3 AND I4 AND NOT I5) AND ((I6 AND I7 AND I8) OR (I9 AND I10))
+
+O1.Name = "Output"
+O1.Description = "(BO 3.2)"
+----
+
+This expands to:
+
+. Ten input ports (`I1` through `I10`) with human-readable names and descriptions.
+. A NOT gate for `NOT I5`.
+. An AND gate combining `I3`, `I4`, and the output of `NOT I5`.
+. An AND gate combining `I1` and `I2`.
+. An AND gate combining `I6`, `I7`, and `I8`.
+. An AND gate combining `I9` and `I10`.
+. An OR gate combining the two sub-expressions.
+. A final AND gate combining all three AND outputs.
+. One output port `O1` with name "Output" and description "(BO 3.2)".
+
+=== Inversion Bubbles
+
+Using `OPTION INVERSION = BUBBLES` renders NOT operations as inversion circles on the downstream gate's input port, eliminating the separate NOT gate column:
+
+[source,ldl]
+----
+OPTION INVERSION = BUBBLES
+
+I1.Name = "Start Permitted"
+I1.Description = "(BI 1.1)"
+I2.Name = "Stop Condition"
+I2.Description = "(BI 1.2)"
+I3.Name = "Reset"
+I3.Description = "(BI 1.3)"
+
+O1 = I1 AND NOT I2 AND I3
+O1.Name = "Run"
+O1.Description = "(BO 1.1)"
+----
+
+With `GATES` mode, this would render as: `I2 → [NOT] → [AND] ← I1, I3 → O1`.
+
+With `BUBBLES` mode, the NOT gate is eliminated and a bubble (○) appears on the AND gate's input that receives `I2`: `I2 → ○[AND] ← I1, I3 → O1`.
+
+=== Input Bars
+
+Using `OPTION GATE_INPUT_STYLE = BARS` keeps multi-input gates at their 2-input base size with vertical input bars for additional inputs:
+
+[source,ldl]
+----
+OPTION GATE_INPUT_STYLE = BARS
+
+I1.Name = "CBQ 00 Open"
+I2.Name = "BB Not Earthed"
+I3.Name = "D/S Q01 Open"
+I4.Name = "E/S Q05 Open"
+I5.Name = "KF1 Release"
+
+O1 = I1 AND I2 AND I3 AND I4 AND I5
+O1.Name = "Output"
+----
+
+With `EXPAND` mode, the AND gate expands vertically to accommodate five input ports. With `BARS` mode, the AND gate stays at 2-input height and inputs 3-5 connect via a vertical bar on the left side.
+
+=== Square Ports
+
+Using `OPTION PORT_STYLE = SQUARE` renders all port markers as squares instead of circles:
+
+[source,ldl]
+----
+OPTION PORT_STYLE = SQUARE
+
+A.Name = "Signal A"
+B.Name = "Signal B"
+O1 = A AND B
+O1.Name = "Result"
+----
+
+Individual ports can override the document default:
+
+[source,ldl]
+----
+OPTION PORT_STYLE = CIRCLE
+I1.Style = SQUARE
+
+O1 = I1 AND I2
+----
+
+In this case, all ports are circles except `I1` which is a square.
+
+=== Combined Options
+
+Options can be combined freely:
+
+[source,ldl]
+----
+OPTION INVERSION = BUBBLES
+OPTION GATE_INPUT_STYLE = BARS
+OPTION PORT_STYLE = SQUARE
+
+I1.Name = "Start"
+I2.Name = "Stop"
+I3.Name = "Reset"
+I4.Name = "Enable"
+I5.Name = "Supervision"
+I6.Name = "Override"
+
+O1 = (I1 AND NOT I2) AND (I3 AND I4 AND I5 AND I6)
+O1.Name = "Master Trip"
+O1.Description = "(BO 1.1)"
+----
+
+This renders with:
+. Inversion bubbles instead of NOT gates (the `NOT I2` input shows as a bubble on the AND gate).
+. Input bars on the 4-input AND gate (I3 through I6 connect via a vertical bar).
+. Square port markers throughout.
+
+=== Full Diagram
+
+[source,ldl]
+----
+// Trip Logic Diagram
+// File: trip_logic.ldl
+
+IMPORT TEMPLATE "templates/timer.ldlt" AS T
+
+SVT#1
+SVT#1.INPUT = OVERCURRENT_A OR OVERCURRENT_B
+SVT#1.PICKUP = 30 s
+SVT#1.DROPOUT = 10 s
+
+TRIP = SVT#1.OUTPUT AND MANUAL_TRIP
+
+STYLESHEET "styles/protection.css"
+
+STYLE
+  #1 { fill: #ffe0e0; }
+  SVT { stroke: #cc0000; }
+END STYLE
+----

package/spec/sections/expressions.adoc

@@ -0,0 +1,182 @@
+== Expressions
+
+=== Boolean Expressions
+
+A boolean expression defines the logical relationship between inputs and an output.
+
+[literal]
+....
+OUTPUT = EXPR
+....
+
+Where `EXPR` is composed of identifiers and the operators `AND`, `OR`, `NOT`, with parenthetical grouping.
+
+=== Intermediate Signals and Outputs
+
+Every assignment names a signal. A name that is *referenced inside another assignment* is a
+*consumed intermediate*: it is shared (its driving gate/block fans out to the consumers) and is
+**not drawn as an output** on the right. Only names that are not consumed — the sinks, furthest
+to the right — are drawn as outputs.
+
+[literal]
+....
+B    = COMPARE(IA, IPICKUP)      // consumed by A and others -> internal, not an output
+A    = SR(B, RESET) OR B OR C    // consumed by TRIP -> internal, not an output
+TRIP = TIMER(A, 0, 30cyc)        // not consumed -> output
+....
+
+To force a consumed intermediate to also be shown as an output, set `NAME.OUT = TRUE`:
+
+[literal]
+....
+B.OUT = TRUE                     // B is now drawn as an output as well as feeding its consumers
+....
+
+A name that references *itself* (a feedback/seal-in, e.g. `Q = SET OR (Q AND NOT RESET)`) is
+always drawn — the self-reference is a loop-back, not a consumer.
+
+A consumed intermediate can still be *labelled at its fan-out junction* — a net label on the
+shared signal — by giving it a name and/or description. The label is drawn just above the
+driving gate/block's output, and wires route around it:
+
+[literal]
+....
+A           = SR(B, RESET) OR B OR C
+A.Name        = "Trip Permit"
+A.Description = "Seal-in"        // A stays internal but its junction is labelled
+....
+
+This is also how a *gate* is labelled: name the gate by assigning it to an intermediate, then
+set the name/description — they appear at the gate's output and wires route around them. For a
+gate that only drives an output, use a pass-through assignment so the gate stays internal:
+
+[literal]
+....
+PH = O51 OR O50 OR NEGSEQ        // name the OR gate "PH"
+PH.Name        = "Phase OC"
+PH.Description = "51/50/46"
+TRIP = PH AND ENABLE             // ... used here, so PH is internal and labelled
+
+OC   = E51N OR E50N              // a gate that only drives an output:
+TRIP2 = OC                       // pass-through keeps OC internal (labelled), TRIP2 is the output
+OC.Name = "Earth Fault"
+....
+
+=== Operator Precedence
+
+Operators are listed from highest to lowest precedence:
+
+[cols="1m,4m,2m"]
+|===
+| Precedence | Operator | Arity
+| 1 (highest) | `NOT` | Unary prefix
+| 2 | `AND` | Binary infix
+| 3 (lowest) | `OR` | Binary infix
+|===
+
+Parentheses override precedence.
+
+=== Examples
+
+[literal]
+....
+CBFPS = AB AND DC OR (NOT DC AND GF)
+....
+
+Parses as:
+
+[literal]
+....
+CBFPS = (AB AND DC) OR ((NOT DC) AND GF)
+....
+
+=== Expanded Form
+
+For readability, an expression may be written across multiple lines using continuation:
+
+[literal]
+....
+CBFPS = AB AND DC
+     OR (NOT DC AND GF)
+....
+
+A continuation line is one that begins with whitespace and follows a prior expression line. The leading operator on a continuation line is treated as part of the expression.
+
+=== Derived Operators
+
+The following compound operators are syntactic sugar:
+
+[cols="2m,4m,4m"]
+|===
+| Operator | Expansion | Description
+| `NAND` | `NOT (... AND ...)` | Negated AND
+| `NOR` | `NOT (... OR ...)` | Negated OR
+| `XOR` | Exclusive OR | One but not both
+| `XNOR` | `NOT (... XOR ...)` | Equivalence
+|===
+
+=== Inversion Rendering
+
+When `OPTION INVERSION = BUBBLES` is set, all `NOT` operations in expressions are rendered as inversion bubbles rather than as separate NOT gate symbols.
+
+==== Input-Side Bubbles
+
+When a `NOT` operation feeds into a gate input, the bubble appears on that input port:
+
+[literal]
+....
+O1 = I1 AND NOT I2
+....
+
+With `OPTION INVERSION = GATES`: `I2 → [NOT] → [AND] ← I1 → O1`
+
+With `OPTION INVERSION = BUBBLES`: `I2 → ○[AND] ← I1 → O1`
+
+==== Output-Side Bubbles
+
+When a `NOT` operation wraps a gate's output, the bubble appears on that gate's output port:
+
+[literal]
+....
+O1 = NOT (I1 AND I2)
+....
+
+With `OPTION INVERSION = GATES`: `[AND] → [NOT] → O1`
+
+With `OPTION INVERSION = BUBBLES`: `[AND]○ → O1`
+
+When a `NOT` operation feeds directly into an output, the bubble appears on the output port's input:
+
+[literal]
+....
+O1 = NOT I1
+....
+
+With `OPTION INVERSION = GATES`: `I1 → [NOT] → O1`
+
+With `OPTION INVERSION = BUBBLES`: `I1 → ○O1`
+
+==== Double-Inversion Cancellation
+
+Consecutive `NOT` operations are algebraically simplified:
+
+* `NOT NOT X = X` (even number of inversions cancels out; no bubble)
+* `NOT NOT NOT X = NOT X` (odd number reduces to a single inversion; one bubble)
+
+For example:
+
+[literal]
+....
+O1 = NOT NOT I1
+....
+
+Renders as: `I1 → O1` (no bubble; both inversions cancel)
+
+[literal]
+....
+O1 = NOT NOT NOT I1
+....
+
+Renders as: `I1 → ○O1` (triple inversion reduces to single inversion)
+
+The NOT gate is never placed as a separate column when `OPTION INVERSION = BUBBLES`. Instead, the downstream port (input or output) is marked with a bubble, and the wire from the NOT's source connects directly to that bubbled port.

package/spec/sections/file-extension.adoc

@@ -0,0 +1,5 @@
+== File Extension
+
+LDL source files use the extension `.ldl`.
+
+Template files use the extension `.ldlt`.

package/spec/sections/function-blocks.adoc

@@ -0,0 +1,120 @@
+== Function Blocks (SEL-style)
+
+In addition to the boolean operators, an expression may use *function-block primitives*
+modelled on SEL relay SELogic elements. Each is written as a function call and returns a
+logic signal, so it composes with `AND`/`OR`/`NOT` and nests like any sub-expression.
+
+[cols="2m,4m,5"]
+|===
+| Block | Syntax | Description
+
+| Pickup/Dropout timer
+| `TIMER(in, pu, do)`
+| Output asserts `pu` after `in` rises and remains asserted `do` after `in` falls. Settings
+  may be positional (`TIMER(IN, 2cyc, 5cyc)`) or named (`TIMER(IN, PU=2cyc, DO=5cyc)`). A bare
+  number is read as cycles; `0` means no delay. Either delay may be omitted (defaults to 0).
+
+| SR latch
+| `SR(set, reset)`
+| Set/reset latch. `.Q` (default) asserts on `set` and de-asserts on `reset`; `.NQ` is the
+  inverted output Q̄. **Reset-dominant** by default (when both inputs are asserted, the output
+  is reset); override with `DOMINANT=SET`. Each output port is drawn only when referenced.
+
+| Rising-edge trigger
+| `RISING(in)`
+| A one-interval pulse on each 0→1 transition of `in` (SEL rising-edge / `R_TRIG`).
+
+| Falling-edge trigger
+| `FALLING(in)`
+| A one-interval pulse on each 1→0 transition of `in`.
+
+| Comparator
+| `COMPARE(plus, minus)`
+| Asserts when the `+` (first) input is greater than or equal to the `−` (second) input.
+  Drawn as a comparator triangle. Inputs are analog quantities; the output is logic.
+|===
+
+=== Generic Blocks (FB)
+
+`FB` is a *generic user block* — a square box with whatever inputs and outputs you need, for
+representing a function whose internals are not drawn. Inputs come from the call arguments
+(optionally labelled `NAME=expr`); outputs are the `.port` selectors you reference. The instance
+`name` is centred in the box, the `description` below it.
+
+[literal]
+....
+TRIP  = FB#PROT(PHASE=IA, EARTH=IN, EN=ENABLE).TRIP
+ALARM = FB#PROT(PHASE=IA, EARTH=IN, EN=ENABLE).ALARM
+PROT.Name        = "Feeder Protection"
+PROT.Description = "SEL-751A"
+....
+
+* Each argument is an input port (left side). `NAME=expr` labels that port; a bare argument is
+  an unlabelled input.
+* Each distinct `.port` referenced is an output port (right side), labelled with the port name.
+  The block instance is de-duplicated by `#id`, so the example above is one box with two outputs.
+* The box is sized to its name, port labels and port counts.
+
+=== Instance IDs and Settings
+
+A block may be given an explicit *instance id* as part of its name, written `BLOCK#id`
+immediately before the argument list (matching the `SYMBOL_NAME#ID` convention, see
+<<symbol-definitions>>). The id can then carry a name, description, or other settings via
+`id.Property`:
+
+[literal]
+....
+HOT = COMPARE#C1(IA, IPK)
+C1.Name = "50P1"
+C1.Description = "Phase overcurrent element"
+....
+
+When no id is given, the block is anonymous and the assigned output name (the left-hand side)
+is its identity.
+
+=== Output Port Selection
+
+A block's output is selected with a trailing `.port` after the call. Most blocks have a single
+output, used by default. The SR latch has two: `.Q` (the default) and `.NQ` (the inverted
+output Q̄). Selecting `.NQ` yields only Q̄, and **only the referenced output port is drawn**:
+
+[literal]
+....
+PERMIT = SR#L1(START, STOP)          // uses Q (default); only Q is drawn
+BLOCK  = SR#L1(START, STOP).NQ       // uses Q̄ only; only NQ is drawn
+....
+
+If both `.Q` and `.NQ` of the same instance are referenced, both ports are drawn.
+
+=== Composition and Feedback
+
+Blocks nest and chain freely:
+
+[literal]
+....
+LATCH = SR(RISING(START), STOP)
+RUN   = TIMER(A AND B, 0, 10cyc) AND ENABLE
+....
+
+A latch output fed back into its own set/reset logic (the canonical seal-in) is drawn as a
+loop-back wire (see <<feedback-loops>>).
+
+A previously-defined output used as a *block argument* is substituted with its driving signal —
+the block taps the same source (a fan-out) rather than gaining a duplicate input. This lets a
+named intermediate be threaded into a block:
+
+[literal]
+....
+A    = SR(COMPARE(IA, IPICKUP), RESET)
+TRIP = TIMER(A, 0, 30cyc)              // the SR latch feeds the timer; A is not duplicated
+....
+
+=== Rendering (SEL Style)
+
+* *TIMER* — a rectangle with a diagonal ramp from the bottom-left to the top-right corner; the
+  pickup (`PU`) delay is shown in the upper-left, the dropout (`DO`) delay in the lower-right.
+* *SR* — a rectangle with `S` (top-left) and `R` (bottom-left) input ports and `Q` on the
+  right; the inverted output `Q̄` is added at the lower right only when referenced.
+* *RISING* / *FALLING* — a small block bearing a rising/falling step glyph.
+* *COMPARE* — a comparator triangle with `+` and `−` input ports on the left and the output
+  on the right.

package/spec/sections/grammar.adoc

@@ -0,0 +1,64 @@
+== Grammar
+
+The following is the formal grammar for LDL in EBNF notation:
+
+[source,ebnf]
+----
+diagram        ::= ( statement )* EOF ;
+
+statement      ::= object_decl
+                 | port_meta
+                 | attribute_decl
+                 | option_decl
+                 | link_decl
+                 | style_block
+                 | stylesheet_decl
+                 | import_decl
+                 | symbol_def
+                 | expression
+                 | connect_stmt
+                 | comment
+                 ;
+
+object_decl    ::= SYMBOL_NAME ( '#' IDENTIFIER )? ;
+port_meta      ::= ( IDENTIFIER | SYMBOL_NAME ) '.' ( 'Name' | 'Description' | 'Style' ) '=' STRING ;
+attribute_decl ::= OBJECT_REF '.' IDENTIFIER '=' literal ;
+option_decl    ::= 'OPTION' IDENTIFIER '=' IDENTIFIER ;
+link_decl      ::= OBJECT_REF ( '.' PORT_NAME )? '.LINK' '=' STRING ;
+
+OBJECT_REF     ::= SYMBOL_NAME ( '#' IDENTIFIER )? ;
+
+expression     ::= or_expr ;
+or_expr        ::= and_expr ( 'OR' and_expr )* ;
+and_expr       ::= not_expr ( 'AND' not_expr )* ;
+not_expr       ::= 'NOT' not_expr | primary ;
+primary        ::= '(' expression ')' | IDENTIFIER | OBJECT_REF '.' PORT_NAME ;
+
+connect_stmt   ::= 'CONNECT' port_ref port_ref ;
+port_ref       ::= OBJECT_REF '.' PORT_NAME ;
+
+style_block    ::= 'STYLE' ( CSS_CONTENT ) 'END' 'STYLE' ;
+stylesheet_decl::= 'STYLESHEET' STRING ;
+
+import_decl    ::= 'IMPORT' 'TEMPLATE' STRING ( 'AS' IDENTIFIER )? ;
+
+symbol_def     ::= 'SYMBOL' SYMBOL_NAME
+                    ( 'SVG' '=' STRING )?
+                    ( port_decl )*
+                    ( attr_decl_in_symbol )*
+                    ( 'LOGIC' '=' expression )?
+                    'END' 'SYMBOL' ;
+port_decl      ::= 'PORT' ( 'INPUT' | 'OUTPUT' | 'BIDI' ) IDENTIFIER
+                    ( ':' ( 'LEFT' | 'RIGHT' | 'TOP' | 'BOTTOM' ) )? ;
+attr_decl_in_symbol ::= 'ATTRIBUTE' IDENTIFIER '=' literal ;
+
+literal        ::= INTEGER | FLOAT | STRING | DURATION | BOOL ;
+DURATION       ::= NUMBER ( 'ms' | 's' | 'm' ) ;
+IDENTIFIER     ::= [a-zA-Z_][a-zA-Z0-9_]* ;
+SYMBOL_NAME    ::= [A-Z][A-Z0-9_]* ;
+STRING         ::= '"' [^"]* '"' ;
+
+comment        ::= line_comment | block_comment ;
+line_comment   ::= '//' ~NEWLINE ;
+block_comment  ::= '/*' ( block_comment | ~('*/') )* '*/' ;
+----

package/spec/sections/hyperlinks.adoc

@@ -0,0 +1,18 @@
+== Hyperlinks
+
+Any object or port may carry a hyperlink:
+
+[literal]
+....
+OBJECT#ID.LINK = "https://example.com/doc"
+PORT OBJECT#ID.PORT_NAME.LINK = "https://example.com/signal"
+....
+
+In the rendered SVG, the symbol or port is wrapped in an `<a>` element:
+
+[source,xml]
+----
+<a xlink:href="https://example.com/doc" target="_blank">
+  <g class="ldl-symbol" id="G1">...</g>
+</a>
+----

package/spec/sections/introduction.adoc

@@ -0,0 +1,16 @@
+== Introduction
+
+The Logic Diagram Language (LDL) is a domain-specific language for describing logic diagrams composed of boolean gates, composite symbols, and their interconnections. LDL targets rendering to SVG and PDF via a TypeScript toolchain.
+
+The language has two primary concerns:
+
+. **Expression logic** -- declaring boolean relationships between inputs and outputs.
+. **Symbol definition** -- describing reusable SVG-based components with typed ports and configurable attributes.
+
+=== Design Principles
+
+* *Expression-first*: A simple boolean expression should produce a complete diagram.
+* *Symbol-oriented*: Every rendered element is an SVG symbol; gates are just symbols with predefined logic.
+* *Declarative*: The language describes *what*, not *how* -- routing and layout are the renderer's concern.
+* *Extensible*: New symbols can be defined or imported without changing the language.
+* *Stylable*: Every element can carry an identifier for CSS-based styling.