DSL Reference

Logicarium uses a simple text-based Domain Specific Language (DSL) to describe digital logic circuits. The script is bidirectional: changes in the script update the visual graph, and changes in the graph update the script.

Core Concepts

The script defines two main things:

1. Nodes: Instances of gates or components.
2. Connections: Wires linking outputs to inputs.

Syntax

1. Defining Nodes

Nodes are defined using the @ symbol.

Format:

[Type] [Identifier] @ [X], [Y] [Flags]

• Type: The class of the node (e.g., AND, OR, NOT, In, Out, or a Custom Gate name).
• Identifier: A unique name for this instance (e.g., n1, gateA, my_switch).
• X, Y: The position of the node on the canvas (integers).
• Flags: Optional modifiers.
  • momentary: Only valid for In nodes. Makes the button a momentary push-button instead of a toggle switch.

Examples:

AND gate1 @ 100, 200
In sw1 @ 50, 50 momentary
Out led1 @ 300, 150
NAND logic_gate @ 400, 400

2. Defining Connections

Connections define how signals flow between nodes.

Format:

[SourceIdentifier].[OutputSlot] -> [TargetIdentifier].[InputSlot]

• SourceIdentifier: The ID of the node sending the signal.
• OutputSlot: The specific output pin (usually out for standard gates).
• TargetIdentifier: The ID of the node receiving the signal.
• InputSlot: The specific input pin (e.g., in0, in1 for gates, or in for outputs).

Shorthand: If a node has a default input/output (like standard gates), you can omit the slot name.

• gate1 -> gate2 is equivalent to gate1.out -> gate2.in (simplification depends on node defaults).
• In nodes default to out.
• Out nodes default to in.

Examples:

// Standard Connection
gate1.out -> led1.in

// Connecting specific slots
sw1.out -> gate1.in0
sw2.out -> gate1.in1

// Implicit/Shorthand (if supported by context)
sw1 -> gate1
gate1 -> led1

3. Comments

Any line starting with // is treated as a comment and ignored by the parser.

// This is a comment
AND n1 @ 100, 100

4. Defining Custom Gates

You can define custom gates directly in your script using the define...end syntax.

Format:

define GateName(input1, input2, ...) -> (output1, output2, ...):
  signal = expression
  ...
end

Primitive Operations:

• signal = a AND b - Logical AND of two signals
• signal = a OR b - Logical OR (uses OR gate if defined, otherwise built from AND/NOT)
• signal = NOT a - Logical NOT of one signal
• signal = GateName(args) - Call a previously defined or loaded custom gate

Nested Expressions: You can combine operators using parentheses:

out = NOT (a AND b)           // ✓ NAND operation
out = NOT (NOT a AND NOT b)   // ✓ OR from primitives
out = NOT (a OR b)            // ✓ NOR operation

Or use intermediate signals for clarity:

temp = a AND b
out = NOT temp

Example - Building an OR gate:

define OR(a, b) -> (out):
  na = NOT a
  nb = NOT b
  t = na AND nb
  out = NOT t
end

Example - Using a custom gate:

define XOR(a, b) -> (out):
  na = NOT a
  nb = NOT b
  t1 = a AND nb
  t2 = na AND b
  out = OR(t1, t2)
end

// Now use it in the circuit
XOR gate1 @ 200, 100
In sw1 @ 50, 50
In sw2 @ 50, 150
Out led1 @ 350, 150

// Both styles work - named pins or indexed pins:
sw1.out -> gate1.a       // using defined name
sw2.out -> gate1.b       // using defined name
// OR equivalently:
// sw1.out -> gate1.in0  // using indexed name
// sw2.out -> gate1.in1  // using indexed name

gate1.out -> led1.in

Rules:

• Gates must be defined before they are used
• Use parentheses to group nested expressions

Pin Naming: When you define a gate like define XOR(a, b) -> (out), you can connect to it using either:

• Named pins: xor1.a, xor1.b (the parameter names from the definition)
• Indexed pins: xor1.in0, xor1.in1 (based on parameter order)

Both are equivalent - a maps to in0, b maps to in1, etc.

For detailed tutorials, see Custom Gate Definitions.

Standard Library

The following node types are built-in:

Note: Other gates (OR, XOR, NAND, etc.) must be defined by the user or loaded from a gate library. See Custom Gate Definitions for examples.