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#
pub struct Rule<X>One promise of a Rules table.
Field event#
pub event: string<'static>The name of the event the rule is about, or an empty string for every event.
Field reason#
pub reason: string<'static>Why the promise holds, in words. A broken rule is reported with it.
Broken#
pub struct BrokenA run that breaks a rule.
Field reason#
pub reason: string<'static>The reason of the rule.
Field position#
pub position: usizeThe position of the run in the list given to Rules.broken.
Rules#
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#
pub items: Intrinsic.StaticSequence<Rule<X>>Implementation Rules<E, C, X>#
impl<E, C, X> Rules<E, C, X>Associated function of#
pub static fn of() -> Rules<E, C, X>Returns a table without rules.
Associated function never#
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#
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#
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#
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#
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#
pub effect fn applying(
static rules: Rules<E, C, X>,
context: &C,
event: &E,
reasons: &mut List<string<'static>>,
) -> ()
! OutOfMemoryError
? &mut AllocatorAppends 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#
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 AllocatorReturns 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.