Builders

pyrung.core.program.builders

ShiftBuilder

Bases: _BuilderBase

Builder for shift instruction with required .clock().reset() chaining.

clock

clock(
    *conditions: Condition
    | Tag
    | tuple[Condition | Tag, ...]
    | list[Condition | Tag],
) -> ShiftBuilder

Set the shift clock trigger condition.

reset

reset(
    *conditions: Condition
    | Tag
    | tuple[Condition | Tag, ...]
    | list[Condition | Tag],
) -> BlockRange | IndirectBlockRange

Finalize the shift instruction with required reset condition.

CountUpBuilder

Bases: _BuilderBase

Builder for count_up instruction with chaining API (Click-style).

Supports optional .down() and required .reset() chaining: count_up(done, acc, preset=100).reset(reset_tag) count_up(done, acc, preset=50).down(down_cond).reset(reset_tag)

down

down(
    *conditions: Condition
    | Tag
    | tuple[Condition | Tag, ...]
    | list[Condition | Tag],
) -> CountUpBuilder

Add down trigger (optional).

Creates a bidirectional counter that increments on rung true and decrements on down condition true.

Parameters:

Name	Type	Description	Default
*conditions	Condition | Tag | tuple[Condition | Tag, ...] | list[Condition | Tag]	Condition(s) for decrementing the counter.	()

Returns:

Type	Description
CountUpBuilder	Self for chaining.

reset

reset(
    *conditions: Condition
    | Tag
    | tuple[Condition | Tag, ...]
    | list[Condition | Tag],
) -> Tag

Add reset condition (required).

When reset condition is true, clears both done bit and accumulator.

Parameters:

Name	Type	Description	Default
*conditions	Condition | Tag | tuple[Condition | Tag, ...] | list[Condition | Tag]	Condition(s) for resetting the counter.	()

Returns:

Type	Description
Tag	The done bit tag.

CountDownBuilder

Bases: _BuilderBase

Builder for count_down instruction with chaining API (Click-style).

Supports required .reset() chaining: count_down(done, acc, preset=25).reset(reset_tag)

reset

reset(
    *conditions: Condition
    | Tag
    | tuple[Condition | Tag, ...]
    | list[Condition | Tag],
) -> Tag

Add reset condition (required).

When reset condition is true, loads preset into accumulator and clears done bit.

Parameters:

Name	Type	Description	Default
*conditions	Condition | Tag | tuple[Condition | Tag, ...] | list[Condition | Tag]	Condition(s) for resetting the counter.	()

Returns:

Type	Description
Tag	The done bit tag.

OnDelayBuilder

Bases: _AutoFinalizeBuilderBase

Builder for on_delay instruction with optional .reset() chaining (Click-style).

Without .reset(): TON behavior (auto-reset on rung false, non-terminal) With .reset(): RTON behavior (manual reset required, terminal)

reset

reset(
    *conditions: Condition
    | Tag
    | tuple[Condition | Tag, ...]
    | list[Condition | Tag],
) -> Tag

Add reset condition (makes timer retentive - RTON).

When reset condition is true, clears both done bit and accumulator.

Parameters:

Name	Type	Description	Default
*conditions	Condition | Tag | tuple[Condition | Tag, ...] | list[Condition | Tag]	Condition(s) for resetting the timer.	()

Returns:

Type	Description
Tag	The done bit tag.

OffDelayBuilder

Bases: _AutoFinalizeBuilderBase

Builder for off_delay instruction (TOF behavior, Click-style).

Auto-resets when re-enabled.

shift

shift(
    bit_range: BlockRange | IndirectBlockRange,
) -> ShiftBuilder

Shift register instruction builder.

Data input comes from current rung power. Use .clock(...) then .reset(...) to finalize and add the instruction.

Example

with Rung(DataBit): shift(C.select(2, 7)).clock(ClockBit).reset(ResetBit)

count_up

count_up(
    done_bit: Tag, accumulator: Tag, *, preset: Tag | int
) -> CountUpBuilder

Count Up instruction (CTU) - Click-style.

Creates a counter that increments every scan while the rung condition is True. Use rise() on the condition for edge-triggered counting.

Example

with Rung(rise(PartSensor)): count_up(done_bit, acc, preset=100).reset(ResetBtn)

This is a terminal instruction. Requires .reset() chaining.

Parameters:

Name	Type	Description	Default
done_bit	Tag	Tag to set when accumulator >= preset.	required
accumulator	Tag	Tag to increment while rung condition is True.	required
preset	Tag | int	Target value (Tag or int).	required

Returns:

Type	Description
CountUpBuilder	Builder for chaining .down() and .reset().

count_down

count_down(
    done_bit: Tag, accumulator: Tag, *, preset: Tag | int
) -> CountDownBuilder

Count Down instruction (CTD) - Click-style.

Creates a counter that decrements every scan while the rung condition is True. Use rise() on the condition for edge-triggered counting.

Example

with Rung(rise(Dispense)): count_down(done_bit, acc, preset=25).reset(Reload)

This is a terminal instruction. Requires .reset() chaining.

Parameters:

Name	Type	Description	Default
done_bit	Tag	Tag to set when accumulator <= -preset.	required
accumulator	Tag	Tag to decrement while rung condition is True.	required
preset	Tag | int	Target value (Tag or int).	required

Returns:

Type	Description
CountDownBuilder	Builder for chaining .reset().

on_delay

on_delay(
    done_bit: Tag,
    accumulator: Tag,
    *,
    preset: Tag | int,
    unit: TimeUnit = TimeUnit.Tms,
) -> OnDelayBuilder

On-Delay Timer instruction (TON/RTON) - Click-style.

Accumulates time while rung is true.

Example

with Rung(MotorRunning): on_delay(done_bit, acc, preset=5000) # TON on_delay(done_bit, acc, preset=5000).reset(ResetBtn) # RTON

Without .reset(), this is TON and remains composable in-rung. With .reset(), this is RTON and becomes terminal in the current flow.

Parameters:

Name	Type	Description	Default
done_bit	Tag	Tag to set when accumulator >= preset.	required
accumulator	Tag	Tag to increment while enabled.	required
preset	Tag | int	Target value in time units (Tag or int).	required
unit	TimeUnit	Time unit for accumulator (default: Tms).	Tms

Returns:

Type	Description
OnDelayBuilder	Builder for optional .reset() chaining.

off_delay

off_delay(
    done_bit: Tag,
    accumulator: Tag,
    *,
    preset: Tag | int,
    unit: TimeUnit = TimeUnit.Tms,
) -> OffDelayBuilder

Off-Delay Timer instruction (TOF) - Click-style.

Done bit is True while enabled. After disable, counts until preset, then done bit goes False. Auto-resets when re-enabled.

Example

with Rung(MotorCommand): off_delay(done_bit, acc, preset=10000)

Off-delay timers are composable in-rung (not terminal).

Parameters:

Name	Type	Description	Default
done_bit	Tag	Tag that stays True for preset time after rung goes false.	required
accumulator	Tag	Tag to increment while disabled.	required
preset	Tag | int	Delay time in time units (Tag or int).	required
unit	TimeUnit	Time unit for accumulator (default: Tms).	Tms

Returns:

Type	Description
OffDelayBuilder	Builder for the off_delay instruction.