Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Simple state transition system over the Identity monad.
Synopsis
- applySTSIndifferently ∷ ∀ s rtype. (STS s, RuleTypeRep rtype, Identity ~ BaseM s) ⇒ RuleContext rtype s → (State s, [PredicateFailure s])
- applySTS ∷ ∀ s rtype. (STS s, RuleTypeRep rtype, BaseM s ~ Identity) ⇒ RuleContext rtype s → Either (NonEmpty (PredicateFailure s)) (State s)
- data STUB (e ∷ Type) (st ∷ Type) (si ∷ Type) (f ∷ Type) (m ∷ Type → Type)
- newtype Threshold a = Threshold a
- type RuleInterpreter ep = ∀ s m rtype. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ RuleContext rtype s → Rule s rtype (State s) → m (EventReturnType ep s (State s, [PredicateFailure s]))
- type STSInterpreter ep = ∀ s m rtype. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ RuleContext rtype s → m (EventReturnType ep s (State s, [PredicateFailure s]))
- data ApplySTSOpts ep = ApplySTSOpts {}
- data ValidationPolicy
- = ValidateAll
- | ValidateNone
- | ValidateSuchThat ([Label] → Bool)
- data AssertionPolicy
- type Label = String
- type Rule sts rtype = F (Clause sts rtype)
- class EventReturnTypeRep ert
- type family EventReturnType ep sts a ∷ Type where ...
- data SingEP ep where
- data EventPolicy
- class (STS sub, BaseM sub ~ BaseM super) ⇒ Embed sub super where
- wrapFailed ∷ PredicateFailure sub → PredicateFailure super
- wrapEvent ∷ Event sub → Event super
- class (Eq (PredicateFailure a), Show (PredicateFailure a), Monad (BaseM a), Typeable a) ⇒ STS a where
- type State a ∷ Type
- type Signal a ∷ Type
- type Environment a ∷ Type
- type BaseM a ∷ Type → Type
- type Event a ∷ Type
- type PredicateFailure a ∷ Type
- initialRules ∷ [InitialRule a]
- transitionRules ∷ [TransitionRule a]
- assertions ∷ [Assertion a]
- renderAssertionViolation ∷ AssertionViolation a → String
- data AssertionException where
- AssertionException ∷ ∀ sts. STS sts ⇒ AssertionViolation sts → AssertionException
- data AssertionViolation sts = AssertionViolation {}
- data Assertion sts
- = PreCondition String (TRC sts → Bool)
- | PostCondition String (TRC sts → State sts → Bool)
- type TransitionRule sts = Rule sts 'Transition (State sts)
- type InitialRule sts = Rule sts 'Initial (State sts)
- type family RuleContext (t ∷ RuleType) = (ctx ∷ Type → Type) | ctx → t where ...
- newtype TRC sts = TRC (Environment sts, State sts, Signal sts)
- newtype IRC sts = IRC (Environment sts)
- class RuleTypeRep t
- data RuleType
- mapEventReturn ∷ ∀ ep sts a b. EventReturnTypeRep ep ⇒ (a → b) → EventReturnType ep sts a → EventReturnType ep sts b
- validate ∷ Validation (NonEmpty (PredicateFailure sts)) () → Rule sts ctx ()
- validateTrans ∷ (e → PredicateFailure sts) → Validation (NonEmpty e) () → Rule sts ctx ()
- validateTransLabeled ∷ (e → PredicateFailure sts) → NonEmpty Label → Validation (NonEmpty e) () → Rule sts ctx ()
- (?!) ∷ Bool → PredicateFailure sts → Rule sts ctx ()
- failBecause ∷ PredicateFailure sts → Rule sts ctx ()
- failOnJust ∷ Maybe a → (a → PredicateFailure sts) → Rule sts ctx ()
- failureOnJust ∷ Maybe a → (a → e) → Validation (NonEmpty e) ()
- failOnNonEmpty ∷ Foldable f ⇒ f a → (NonEmpty a → PredicateFailure sts) → Rule sts ctx ()
- failureOnNonEmpty ∷ Foldable f ⇒ f a → (NonEmpty a → e) → Validation (NonEmpty e) ()
- (?!:) ∷ Either e () → (e → PredicateFailure sts) → Rule sts ctx ()
- labeledPred ∷ NonEmpty Label → Bool → PredicateFailure sts → Rule sts ctx ()
- labeledPredE ∷ NonEmpty Label → Either e () → (e → PredicateFailure sts) → Rule sts ctx ()
- labeled ∷ NonEmpty Label → Rule sts ctx () → Rule sts ctx ()
- trans ∷ Embed sub super ⇒ RuleContext rtype sub → Rule super rtype (State sub)
- ifFailureFree ∷ Rule sts rtype a → Rule sts rtype a → Rule sts rtype a
- whenFailureFree ∷ Rule sts rtype () → Rule sts rtype ()
- liftSTS ∷ STS sts ⇒ BaseM sts a → Rule sts ctx a
- judgmentContext ∷ Rule sts rtype (RuleContext rtype sts)
- applySTSOpts ∷ ∀ s m rtype ep. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ ApplySTSOpts ep → RuleContext rtype s → m (EventReturnType ep s (State s, [PredicateFailure s]))
- applySTSOptsEither ∷ ∀ s m rtype ep. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ ApplySTSOpts ep → RuleContext rtype s → m (Either (NonEmpty (PredicateFailure s)) (EventReturnType ep s (State s)))
- globalAssertionPolicy ∷ AssertionPolicy
- reapplySTS ∷ ∀ s m rtype. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ RuleContext rtype s → m (State s)
- applyRuleInternal ∷ ∀ (ep ∷ EventPolicy) s m rtype result. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ IsFailing → SingEP ep → ValidationPolicy → (IsFailing → STSInterpreter ep) → RuleContext rtype s → Rule s rtype result → m (EventReturnType ep s (result, [PredicateFailure s]))
- applySTSInternal ∷ ∀ s m rtype ep. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ SingEP ep → AssertionPolicy → RuleInterpreter ep → RuleContext rtype s → ExceptT (AssertionViolation s) m (EventReturnType ep s (State s, [PredicateFailure s]))
- sfor_ ∷ (Foldable t, Applicative f) ⇒ t a → (a → f b) → f ()
- tellEvent ∷ Event sts → Rule sts ctx ()
- tellEvents ∷ [Event sts] → Rule sts ctx ()
- runRule ∷ (STS s, RuleTypeRep rtype) ⇒ RuleContext rtype s → Rule s rtype result → BaseM s (result, [PredicateFailure s])
Documentation
applySTSIndifferently ∷ ∀ s rtype. (STS s, RuleTypeRep rtype, Identity ~ BaseM s) ⇒ RuleContext rtype s → (State s, [PredicateFailure s]) Source #
applySTS ∷ ∀ s rtype. (STS s, RuleTypeRep rtype, BaseM s ~ Identity) ⇒ RuleContext rtype s → Either (NonEmpty (PredicateFailure s)) (State s) Source #
data STUB (e ∷ Type) (st ∷ Type) (si ∷ Type) (f ∷ Type) (m ∷ Type → Type) Source #
A stub rule with no transitions to use as a placeholder
Instances
This can be used to specify predicate failures in STS rules where a value is beyond a certain threshold.
TODO move this somewhere more sensible
Instances
type RuleInterpreter ep = ∀ s m rtype. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ RuleContext rtype s → Rule s rtype (State s) → m (EventReturnType ep s (State s, [PredicateFailure s])) Source #
type STSInterpreter ep = ∀ s m rtype. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ RuleContext rtype s → m (EventReturnType ep s (State s, [PredicateFailure s])) Source #
data ApplySTSOpts ep Source #
ApplySTSOpts | |
|
data ValidationPolicy Source #
Control which predicates are evaluated during rule processing.
data AssertionPolicy Source #
Control which assertions are enabled.
AssertionsAll | |
AssertionsPre | Only run preconditions |
AssertionsPost | Only run postconditions |
AssertionsOff |
Instances
Show AssertionPolicy Source # | |
Defined in Control.State.Transition.Extended | |
Eq AssertionPolicy Source # | |
Defined in Control.State.Transition.Extended |
Label for a predicate. This can be used to control which predicates get run.
class EventReturnTypeRep ert Source #
eventReturnTypeRep
type family EventReturnType ep sts a ∷ Type where ... Source #
EventReturnType 'EventPolicyReturn sts a = (a, [Event sts]) | |
EventReturnType _ _ a = a |
class (STS sub, BaseM sub ~ BaseM super) ⇒ Embed sub super where Source #
Embed one STS within another.
wrapFailed ∷ PredicateFailure sub → PredicateFailure super Source #
Wrap a predicate failure of the subsystem in a failure of the super-system.
Instances
STS sts ⇒ Embed sts sts Source # | |
Defined in Control.State.Transition.Extended wrapFailed ∷ PredicateFailure sts → PredicateFailure sts Source # |
class (Eq (PredicateFailure a), Show (PredicateFailure a), Monad (BaseM a), Typeable a) ⇒ STS a where Source #
State transition system.
Type of the state which the system transitions between.
Signal triggering a state change.
type Environment a ∷ Type Source #
Environment type.
type BaseM a ∷ Type → Type Source #
Monad into which to interpret the rules.
Event type.
type PredicateFailure a ∷ Type Source #
Descriptive type for the possible failures which might cause a transition to fail.
As a convention, PredicateFailure
s which are "structural" (meaning that
they are not "throwable" in practice, and are used to pass control from
one transition rule to another) are prefixed with S_
.
Structural PredicateFailure
s represent conditions between rules where
the disjunction of all rules' preconditions is equal to True
. That is,
either one rule will throw a structural PredicateFailure
and the other
will succeed, or vice-versa.
initialRules ∷ [InitialRule a] Source #
Rules governing transition under this system.
default initialRules ∷ Default (State a) ⇒ [InitialRule a] Source #
transitionRules ∷ [TransitionRule a] Source #
assertions ∷ [Assertion a] Source #
Assertions about the transition system.
renderAssertionViolation ∷ AssertionViolation a → String Source #
Render an assertion violation.
Defaults to using show
, but note that this does not know how to render
the context. So for more information you should define your own renderer
here.
Instances
(Eq f, Monad m, Show f, Typeable e, Typeable f, Typeable si, Typeable st, Typeable m) ⇒ STS (STUB e st si f m) Source # | |
Defined in Control.State.Transition.Extended type State (STUB e st si f m) Source # type Signal (STUB e st si f m) Source # type Environment (STUB e st si f m) Source # type BaseM (STUB e st si f m) ∷ Type → Type Source # type Event (STUB e st si f m) Source # type PredicateFailure (STUB e st si f m) Source # initialRules ∷ [InitialRule (STUB e st si f m)] Source # transitionRules ∷ [TransitionRule (STUB e st si f m)] Source # assertions ∷ [Assertion (STUB e st si f m)] Source # renderAssertionViolation ∷ AssertionViolation (STUB e st si f m) → String Source # |
data AssertionException where Source #
AssertionException ∷ ∀ sts. STS sts ⇒ AssertionViolation sts → AssertionException |
Instances
data AssertionViolation sts Source #
Instances
STS sts ⇒ Show (AssertionViolation sts) Source # | |
Defined in Control.State.Transition.Extended |
An assertion is a validation condition for the STS system in question. It should be used to define properties of the system as a whole that cannot be violated under normal circumstances - e.g. a violation implies a failing in the rule logic.
Assertions should not check for conditions that may differ between different rules in a system, since the interpreter may stop the system upon presence of a failed assertion.
Whether assertions are checked is a matter for the STS interpreter.
PreCondition String (TRC sts → Bool) | Pre-condition. Checked before the rule fires. |
PostCondition String (TRC sts → State sts → Bool) | Post-condition. Checked after the rule fires, and given access to the resultant state as well as the initial context. |
type TransitionRule sts = Rule sts 'Transition (State sts) Source #
Context available to transition rules.
TRC (Environment sts, State sts, Signal sts) |
class RuleTypeRep t Source #
rTypeRep
Instances
RuleTypeRep 'Initial Source # | |
Defined in Control.State.Transition.Extended | |
RuleTypeRep 'Transition Source # | |
Defined in Control.State.Transition.Extended rTypeRep ∷ SRuleType 'Transition |
mapEventReturn ∷ ∀ ep sts a b. EventReturnTypeRep ep ⇒ (a → b) → EventReturnType ep sts a → EventReturnType ep sts b Source #
Map over an arbitrary EventReturnType
.
validate ∷ Validation (NonEmpty (PredicateFailure sts)) () → Rule sts ctx () Source #
Fail with PredicateFailure
's in STS if Validation
was unsuccessful.
∷ (e → PredicateFailure sts) | Transformation function for all errors |
→ Validation (NonEmpty e) () | |
→ Rule sts ctx () |
Same as validation
, except with ability to transform opaque failures
into PredicateFailure
s with a help of supplied function.
∷ (e → PredicateFailure sts) | Transformation function for all errors |
→ NonEmpty Label | Supply a list of labels to be used as filters when STS is executed |
→ Validation (NonEmpty e) () | Actual validations to be executed |
→ Rule sts ctx () |
Same as validation
, except with ability to translate opaque failures
into PredicateFailure
s with a help of supplied function.
(?!) ∷ Bool → PredicateFailure sts → Rule sts ctx () infix 1 Source #
Oh noes!
This takes a condition (a boolean expression) and a failure and results in a clause which will throw that failure if the condition fails.
failBecause ∷ PredicateFailure sts → Rule sts ctx () Source #
failOnJust ∷ Maybe a → (a → PredicateFailure sts) → Rule sts ctx () Source #
Produce a predicate failure when condition contains a Just value, contents of which can be used inside the predicate failure
failureOnJust ∷ Maybe a → (a → e) → Validation (NonEmpty e) () Source #
Produce a failure when condition contains a Just value, contents of which can be used inside the failure
failOnNonEmpty ∷ Foldable f ⇒ f a → (NonEmpty a → PredicateFailure sts) → Rule sts ctx () Source #
Produce a predicate failure when supplied foldable is not empty, contents of which will be converted to a NonEmpty list and can be used inside the predicate failure.
failureOnNonEmpty ∷ Foldable f ⇒ f a → (NonEmpty a → e) → Validation (NonEmpty e) () Source #
Produce a failure when supplied foldable is not empty, contents of which will be converted to a NonEmpty list and theh can be used inside the failure.
(?!:) ∷ Either e () → (e → PredicateFailure sts) → Rule sts ctx () Source #
Oh noes with an explanation
We interpret this as "What?" "No!" "Because:"
labeledPred ∷ NonEmpty Label → Bool → PredicateFailure sts → Rule sts ctx () Source #
Labeled predicate. This may be used to control which predicates are run
using ValidateSuchThat
.
labeledPredE ∷ NonEmpty Label → Either e () → (e → PredicateFailure sts) → Rule sts ctx () Source #
Labeled predicate with an explanation
labeled ∷ NonEmpty Label → Rule sts ctx () → Rule sts ctx () Source #
Labeled clause. This will only be executed if the interpreter is set to execute clauses with this label.
whenFailureFree ∷ Rule sts rtype () → Rule sts rtype () Source #
judgmentContext ∷ Rule sts rtype (RuleContext rtype sts) Source #
Get the judgment context
applySTSOpts ∷ ∀ s m rtype ep. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ ApplySTSOpts ep → RuleContext rtype s → m (EventReturnType ep s (State s, [PredicateFailure s])) Source #
Apply an STS with options. Note that this returns both the final state and the list of predicate failures.
applySTSOptsEither ∷ ∀ s m rtype ep. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ ApplySTSOpts ep → RuleContext rtype s → m (Either (NonEmpty (PredicateFailure s)) (EventReturnType ep s (State s))) Source #
reapplySTS ∷ ∀ s m rtype. (STS s, RuleTypeRep rtype, m ~ BaseM s) ⇒ RuleContext rtype s → m (State s) Source #
Re-apply an STS.
It is assumed that the caller of this function has previously applied this STS, and can guarantee that it completed successfully. No predicates or assertions will be checked when calling this function.
∷ ∀ (ep ∷ EventPolicy) s m rtype result. (STS s, RuleTypeRep rtype, m ~ BaseM s) | |
⇒ IsFailing | We need to know if the current STS incurred at least one
PredicateFailure. This is necessary because |
→ SingEP ep | |
→ ValidationPolicy | |
→ (IsFailing → STSInterpreter ep) | Interpreter for subsystems |
→ RuleContext rtype s | |
→ Rule s rtype result | |
→ m (EventReturnType ep s (result, [PredicateFailure s])) |
Apply a rule even if its predicates fail.
If the rule successfully applied, the list of predicate failures will be empty.
∷ ∀ s m rtype ep. (STS s, RuleTypeRep rtype, m ~ BaseM s) | |
⇒ SingEP ep | |
→ AssertionPolicy | |
→ RuleInterpreter ep | Interpreter for rules |
→ RuleContext rtype s | |
→ ExceptT (AssertionViolation s) m (EventReturnType ep s (State s, [PredicateFailure s])) |
sfor_ ∷ (Foldable t, Applicative f) ⇒ t a → (a → f b) → f () Source #
tellEvents ∷ [Event sts] → Rule sts ctx () Source #
runRule ∷ (STS s, RuleTypeRep rtype) ⇒ RuleContext rtype s → Rule s rtype result → BaseM s (result, [PredicateFailure s]) Source #
runRule :: RuleInterpreter 'EventPolicyDiscard run a rule given its context, to get a BaseM computation