core

type Action interface {
	// Exec executes this action.
	//
	// Third argument is for parameters (which can be exposed in
	// the Action's dynamic environment).
	//
	// ToDo: Generalize to return []Bindings?
	Exec(context.Context, Bindings, StepProps) (*Execution, error)

	// Binds optionally gives the set of patterns that match
	// bindings that could be bound during execution.
	//
	// If not nil, the returned set can help with static and
	// dynamic analysis of the machine.
	Binds() []Bindings

	// Emits optionally gives the set of patterns that match
	// messages that could be emitted by this action.
	Emits() []interface{}
}

type ActionSource struct {
	Interpreter string      `json:"interpreter,omitempty" yaml:",omitempty"`
	Source      interface{} `json:"source"`
	Binds       []Bindings  `json:"binds,omitempty" yaml:",omitempty"`
}

type BadBranching struct {
	Spec     *Spec
	NodeName string
}

type Branch struct {
	// Pattern is matched against either a pending message or
	// bindings -- depending on the Branches.Type.
	Pattern interface{} `json:"pattern,omitempty" yaml:",omitempty"`

	// Guard is an optional procedure that will prevent the
	// transition if the procedure returns nil Bindings.
	Guard Action `json:"-" yaml:"-"`

	// GuardSource is an ActionSource that serves as a guard to
	// following this branch.  If the guard returns nil bindings,
	// the branch isn't followed.  Otherwise, the returns bindings
	// are used and the branch is followed.
	GuardSource *ActionSource `json:"guard,omitempty" yaml:"guard,omitempty"`

	// Target is the name of the next state for this transition.
	Target string `json:"target,omitempty" yaml:",omitempty"`
}

type Branches struct {
	// Type is either "message", "bindings", or nil.
	//
	// Type "message" means that an message is required and will be
	// consumed when branches are considered.  Branch Patterns are
	// matched against that message.
	//
	// Type "bindings" means that Branch Patterns are matched
	// against the current Bindings.
	//
	// A nil Type should imply only one Branch with no Pattern.
	Type string `json:"type,omitempty" yaml:",omitempty"`

	// Modes is a set of flags that can inform Branch processing
	// and analysis.  Currently no modes are considered.
	//
	// Example: "exclusive" might declare that the Branch patterns
	// should be mututally exclusive.
	//
	// ToDo: Use a real type instead of string.
	Modes []string `json:"modes,omitempty" yaml:",omitempty"`

	// Branches is the list (ordered) of possible transitions to
	// the next state (if any).
	//
	// No Branches means that this node is terminal.
	Branches []*Branch `json:"branches,omitempty" yaml:",omitempty"`
}

type Breakpoint func(context.Context, *State) bool

type Context interface {
	Deadline() (deadline time.Time, ok bool)
	Done() <-chan struct{}
	Err() error
	Value(key interface{}) interface{}
}

type Control struct {
	// Limit is the maximum number of Steps that a Walk() can take.
	Limit       int                   `json:"limit"`
	Breakpoints map[string]Breakpoint `json:"-"`
}

type Events struct {
	Emitted []interface{} `json:"emitted,omitempty" yaml:",omitempty"`
	Traces  *Traces       `json:"traces,omitempty" yaml:",omitempty"`
}

type Execution struct {
	Bs Bindings
	*Events
}

type FuncAction struct {
	F func(context.Context, Bindings, StepProps) (*Execution, error) `json:"-" yaml:"-"`
	// contains filtered or unexported fields
}

type Interpreter interface {
	// Compile can make something that helps when Exec()ing the
	// code later.
	Compile(ctx context.Context, code interface{}) (interface{}, error)

	// Exec executes the code.  The result of previous Compile()
	// might be provided.
	Exec(ctx context.Context, bs Bindings, props StepProps, code interface{}, compiled interface{}) (*Execution, error)
}

type Interpreters interface {
	Find(interpreterName string) Interpreter
}

type InterpretersMap map[string]Interpreter

type Node struct {
	// Doc is optional document in a format of your choosing.
	Doc string `json:"doc,omitempty" yaml:",omitempty"`

	// Action is an optional action that will be executed upon
	// transition to this node.
	//
	// Note that a node with "message"-based branching cannot have
	// an Action.
	Action Action `json:"-" yaml:"-"`

	// ActionSource, if given, is Compile()ed to an Action.
	ActionSource *ActionSource `json:"action,omitempty" yaml:"action,omitempty"`

	// Branches contains the transitions out of this node.
	Branches *Branches `json:"branching,omitempty" yaml:"branching,omitempty"`
}

type ParamSpec struct {

	// Doc describes the spec in English and Markdown.  Audience
	// is developers, not users.
	Doc string `json:"doc,omitempty" yaml:",omitempty"`

	// PrimitiveType is (for now) any string.
	PrimitiveType string `json:"primitiveType" yaml:"primitiveType"`

	// Default is the default value for a parameter used in case a value is not given in the initial bindings
	Default interface{} `json:"default"`

	// Optional means that the parameter is not required!
	Optional bool `json:"optional,omitempty" yaml:",omitempty"`

	// IsArray specifies whether a value must be an array of
	// values of the PrimitiveType.
	IsArray bool `json:"isArray,omitempty" yaml:"isArray,omitempty"`

	// SemanticType is (for now) any string.
	SemanticType string `json:"semanticType,omitempty" yaml:"semanticType,omitempty"`

	// MinCardinality is the minimum number of values.
	MinCardinality int `json:"minCard,omitempty" yaml:"minCard,omitempty"`

	// MaxCardinality is the maximum number of values.
	//
	// A MaxCardinality greater than one implies the param value
	// IsArray.
	MaxCardinality int `json:"maxCard,omitempty" yaml:"maxCard,omitempty"`

	// Predicate isn't implemented.
	//
	// Could be a predicate that could further validate a
	// parameter value.
	Predicate interface{} `json:"predicate,omitempty" yaml:",omitempty"`

	// Advisory indicates that a violation of this spec is a
	// warning, not an error.
	Advisory bool `json:"advisory,omitempty" yaml:",omitempty"`
}

type Spec struct {
	// Name is the generic name for this machine.  Something like
	// "door-open-notification".  Cf. Id.
	Name string `json:"name,omitempty" yaml:",omitempty"`

	// Version is the version of this generic machine.  Something
	// like "1.2".
	Version string `json:"version,omitempty" yaml:",omitempty"`

	// Id should be a globally unique identifier (such as a hash
	// of a canonical representation of the Spec).
	//
	// This value could be used to determine when a Spec has
	// changed.
	//
	// This package does not read or write this value.
	Id string `json:"id,omitempty" yaml:",omitempty"`

	// Doc is general documentation about how this specification works.
	Doc string `json:"doc,omitempty" yaml:",omitempty"`

	// ParamSpecs is an optional name from a parameter name to a
	// specification for that parameter.
	//
	// A parameter is really just an initial binding that's
	// provided when a machine is created.
	//
	// ToDo: Implement actual check of parameters when machine is
	// created.
	ParamSpecs map[string]ParamSpec `json:"paramSpecs,omitempty" yaml:",omitempty"`

	// Uses is a set of feature tags.
	Uses []string `json:"uses,omitempty" yaml:",omitempty"`

	// Nodes is the structure of the machine.  This value could be
	// a reference that points into a library or whatever.
	Nodes map[string]*Node `json:"nodes,omitempty" yaml:",omitempty"`

	// ErrorNode is an optional name of a node for the machine in
	// the even of an internal error.
	//
	// Probably should just always assume the convention that a
	// node named 'error' is the error node.  ToDo: Consider.
	ErrorNode string `json:"errorNode,omitempty" yaml:",omitempty"`

	// NoAutoErrorNode will instruct the spec compiler not to add
	// an error node if one does not already exist.
	NoAutoErrorNode bool `json:"noErrorNode,omitempty" yaml:",omitempty"`

	// ActionErrorBranches (when true) means that this spec uses
	// branches to handle action errors.  (A branch can match an
	// action error using a "actionError" property with a variable
	// value.)
	//
	// If this switch is off, then any action error will result in
	// a transition to the error state, which is probably not what
	// you want.
	ActionErrorBranches bool `json:"actionErrorBranches,omitempty" yaml:",omitempty"`

	// ActionErrorNode is the name of the target node when an
	// action produces an error.
	//
	// If no value is given, then Step() will return an error
	// rather than a stride ending at a node given by this value.
	ActionErrorNode string `json:"actionErrorNode,omitempty" yaml:",omitempty"`

	// Boot is an optional Action that should be (?) executed when
	// the machine is loaded.  Not implemented yet.
	Boot Action `json:"-" yaml:"-"`

	// BootSource, if given, can be compiled to a Boot Action.
	// See Spec.Compile.
	BootSource *ActionSource `json:"boot,omitempty" yaml:"boot,omitempty"`

	// Toob is of course Boot in reverse.  It's also an optional
	// Action that can/should be executed when a Machine is
	// unloaded, suspended, or whatever.  Not currently connected
	// to anything.
	Toob Action `json:"-" yaml:"-"`

	// ToobSource, if given, can be compiled to a Toob Action.
	// See Spec.Compile.
	ToobSource *ActionSource `json:"toob,omitempty" yaml:"toob,omitempty"`

	// PatternSyntax indicates the syntax (if any) for branch patterns.
	PatternSyntax string `json:"patternSyntax,omitempty" yaml:",omitempty"`

	PatternParser func(string, interface{}) (interface{}, error) `json:"-" yaml:"-"`

	// NoNewMachines will make Step return an error if a pattern
	// match returns more than one set of bindings.
	//
	// ToDo: Implement.
	NoNewMachines bool `json:"noNewMachined,omitempty" yaml:",omitempty"`
	// contains filtered or unexported fields
}

type SpecNotCompiled struct {
	Spec *Spec
}

type Specter interface {
	Spec() *Spec
}

type State struct {
	NodeName string   `json:"node"`
	Bs       Bindings `json:"bs"`
}

type StepProps map[string]interface{}

type StopReason int

type Stride struct {
	// Events gather what was emitted during the step.
	*Events `json:"events,omitempty" yaml:",omitempty"`

	// From is the name of the starting node.
	From *State `json:"from,omitempty" yaml:",omitempty"`

	// To is the new State (if any) resulting from the step.
	To *State `json:"to,omitempty" yaml:",omitempty"`

	// Consumed is the message (if any) that was consumed by the step.
	Consumed interface{} `json:"consumed,omitempty" yaml:",omitempty"`
}

type Traces struct {
	Messages []interface{} `json:"messages,omitempty" yaml:",omitempty"`
}

type UncompiledAction struct {
	Spec     *Spec
	NodeName string
}

type UnknownNode struct {
	Spec     *Spec
	NodeName string
}

type UpdatableSpec struct {
	// contains filtered or unexported fields
}

type Walked struct {
	// Strides contains each Stride taken and the last one
	// attempted.
	Strides []*Stride `json:"strides" yaml:",omitempty"`

	// Remaining stores the messages that Walk failed to consume.
	Remaining []interface{} `json:"remaining,omitempty" yaml:",omitempty"`

	// StoppedBecause reports the reason why the Walk stopped.
	StoppedBecause StopReason `json:"stoppedBecause,omitempty" yaml:",omitempty"`

	// Error stores an internal error that occurred (if any).
	Error error `json:"error,omitempty" yaml:",omitempty"`

	// BreakpointId is the id of the breakpoint, if any, that
	// caused this Walk to stop.
	BreakpointId string `json:"breakpoint,omitempty" yaml:",omitempty"`
}