silk.machine.rules.

Promises a machine keeps on every path, written once with their reason: Rules.

When to use#

Use this module for a promise that covers many rows of a chart, such as "reading never writes a file". Write the promise as a rule, walk the machine with the silk.machine.explore module, and let Rules.broken find every run that breaks it. A test then fails with the reason of the rule, whatever row caused it.

Details#

A rule is about one event and one effect. It is checked on each run of the event: the step that takes the event and the steps of the answers of the world that follow it, see Walk.runs. Two effects are the same when Values.write writes them as the same text.

Import as Rules with import silk.machine.rules { Rules }.

Public declarations: 3.

Rule#

silk
pub struct Rule<X>

One promise of a Rules table.

Field event#

silk
pub event: string<'static>

The name of the event the rule is about, or an empty string for every event.

Field reason#

silk
pub reason: string<'static>

Why the promise holds, in words. A broken rule is reported with it.

Broken#

silk
pub struct Broken

A run that breaks a rule.

Field reason#

silk
pub reason: string<'static>

The reason of the rule.

Field position#

silk
pub position: usize

The position of the run in the list given to Rules.broken.

Rules#

silk
pub struct Rules<E, C, X>

A static table of promises about the effects of a machine with the events E, the context C and the effects X.

When to use#

Build one in a static function with Rules.of and the builders, as a chart is built: Rules<Typed, Disk, Mark>.of() |> Rules.never("Read", writes, "reading never writes"). Check it with Rules.broken.

Field items#

silk
pub items: Intrinsic.StaticSequence<Rule<X>>

Implementation Rules<E, C, X>#

silk
impl<E, C, X> Rules<E, C, X>

Associated function of#

silk
pub static fn of() -> Rules<E, C, X>

Returns a table without rules.

Associated function never#

silk
pub static fn never(
    rules: Rules<E, C, X>,
    event: Intrinsic.VariantName<E>,
    effect_: X,
    reason: string<'static>,
  ) -> Rules<E, C, X>

Adds the promise that no run of event leaves effect_, for the reason reason.

Associated function neverWhen#

silk
pub static fn neverWhen<G>(
    rules: Rules<E, C, X>,
    event: Intrinsic.VariantName<E>,
    guard: G,
    effect_: X,
    reason: string<'static>,
  ) -> Rules<E, C, X>

Adds the promise that no run of event leaves effect_ when guard holds, for the reason reason. guard is a function fn(&C, &E) -> bool or a Guard. It sees the context as it was before the event, and the event.

Associated function neverAny#

silk
pub static fn neverAny(
    rules: Rules<E, C, X>,
    effect_: X,
    reason: string<'static>,
  ) -> Rules<E, C, X>

Adds the promise that no run of any event leaves effect_, for the reason reason.

Associated function always#

silk
pub static fn always(
    rules: Rules<E, C, X>,
    event: Intrinsic.VariantName<E>,
    effect_: X,
    reason: string<'static>,
  ) -> Rules<E, C, X>

Adds the promise that every run of event leaves effect_, for the reason reason.

Associated function alwaysWhen#

silk
pub static fn alwaysWhen<G>(
    rules: Rules<E, C, X>,
    event: Intrinsic.VariantName<E>,
    guard: G,
    effect_: X,
    reason: string<'static>,
  ) -> Rules<E, C, X>

Adds the promise that every run of event leaves effect_ when guard holds, for the reason reason. guard is a function fn(&C, &E) -> bool or a Guard. It sees the context as it was before the event, and the event.

Associated function applying#

silk
pub effect fn applying(
    static rules: Rules<E, C, X>,
    context: &C,
    event: &E,
    reasons: &mut List<string<'static>>,
  ) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends to reasons the reason of each rule of rules that is about event and whose guard holds for context and event, in the order of the table.

Associated function broken#

silk
pub effect fn broken<S: Machine<E, C, X>>(
    static rules: Rules<E, C, X>,
    walk: &Walk<S, E, C, X>,
    runs: &[Run],
    events: &[E],
  ) -> List<Broken>
    ! OutOfMemoryError
    ? &mut Allocator

Returns the runs of runs that break a rule of rules, each with the reason of the rule it breaks.

Details#

walk is the walk the runs come from, see Walk.runs, and events the list of events the walk was made with. A rule is checked on a run when it is about the event of the first step of the run and its guard holds for the context the run starts from.

Category: State machines.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page