charm

Documentation

Overview

Package charm provides common utilities for parsing documents using hand-rolled hierarchical state machines. Its So named because what this package lacks in speed or good sense, it makes up in strange charm.

Index

• Constants
• Variables
• func ParseEof(str string, first State) (err error)
• func Read(in io.RuneReader, first State) (err error)
• type EndpointError
  • func (e EndpointError) End() int
  • func (e EndpointError) Error() (ret string)
• type InvalidRune
  • func (e InvalidRune) Error() string
• type State
  • func AtleastOne(filter func(r rune) bool) State
  • func Error(e error) State
  • func Finished() State
  • func MakeState(next func() State) State
  • func OnExit(name string, onExit func()) State
  • func Optional(filter func(r rune) bool) State
  • func Parallel(name string, rs ...State) State
  • func Parse(str string, first State) (ret State, err error)
  • func Require(filter func(r rune) bool) State
  • func RunState(r rune, state State) (ret State)
  • func RunStep(r rune, child, parent State) State
  • func Self(name string, closure func(State, rune) State) State
  • func Statement(name string, closure func(rune) State) State
  • func Step(child, parent State) State
  • func UnhandledNext() State
• type Terminal
  • func (e Terminal) Error() string
  • func (e Terminal) Finished() bool
  • func (e Terminal) NewRune(r rune) (ret State)
  • func (e Terminal) String() string
  • func (e Terminal) Unwrap() error

Constants

const Eof = rune(-1)

Variables

var StateName = func(n State) (ret string) {
	if s, ok := n.(interface{ String() string }); !ok {
		ret = "unknown state"
	} else {
		ret = s.String()
	}
	return
}

replaceable function for printing the name of a state by default uses Stringer's String(), if not implemented it returns "unknown state" test packages can overwrite with something that uses package reflect if desired.

Functions

func ParseEof

func ParseEof(str string, first State) (err error)

ParseEof sends each rune of string to the passed state chart; after its done with the string, it sends an eof(-1) to flush any remaining data. see also Parse() which does not send the eof.

func Read

func Read(in io.RuneReader, first State) (err error)

Types

type EndpointError

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

ended before the whole input was parsed.

func (EndpointError) End

func (e EndpointError) End() int

index of the failure point in the input

func (EndpointError) Error

func (e EndpointError) Error() (ret string)

type InvalidRune

type InvalidRune rune

implements error

func (InvalidRune) Error

func (e InvalidRune) Error() string

type State

type State interface {
	// process the next element of the incoming data,
	// return the next state or nil when done.
	NewRune(rune) State
}

definition of states n the state chart if State implements Stringer StateName() will use it.

func AtleastOne

func AtleastOne(filter func(r rune) bool) State

one or more of the runes must pass the filter

func Error

func Error(e error) State

a next state indicating an error that caused the state machine to exit

func Finished

func Finished() State

a next state indicating an expected termination. ( for example, to absorb runes.Eof and end a state gracefully. | whereas returning nil from a state would consider the Eof unhandled | and trigger attempts by chained states to handle the Eof themselves. )

func MakeState

func MakeState(next func() State) State

Creates a state on demand

func OnExit

func OnExit(name string, onExit func()) State

For use in Step() to run an action after the first step completes.

func Optional

func Optional(filter func(r rune) bool) State

zero or more of the runes must pass the filter

func Parallel

func Parallel(name string, rs ...State) State

Parallel region; run all of the passed states until they all return nil. if any return error, this returns error.

func Parse

func Parse(str string, first State) (ret State, err error)

Parse sends each rune of string to the passed state chart, Returns the error underlying error states, or the last returned state if there was no error.

func Require

func Require(filter func(r rune) bool) State

ensure the next rune passes the filter

func RunState

func RunState(r rune, state State) (ret State)

calls NewRune on state. sometimes this is a more convenient notation.

func RunStep

func RunStep(r rune, child, parent State) State

RunStep - run a sequence of of two states sending the current rune to the first state immediately see also: Step()

func Self

func Self(name string, closure func(State, rune) State) State

Self are States which pass a function pointer as the first argument to the state callback. This allows closures to return themselves. For example, the following state returns itself forever:

var recursive  Self = func(self State, r rune) State { return self }

func Statement

func Statement(name string, closure func(rune) State) State

Statement functions behave as a State. ( Self works the same, except that passes the state to its function as "self" and this does not )

func Step

func Step(child, parent State) State

Step - construct a sequence of two states. If the next rune is not handled by the first state or any of its returned states, the rune is handed to the second state. this acts similar to a parent-child statechart.

func UnhandledNext

func UnhandledNext() State

the next rune will return unhandled

type Terminal

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

acts as both an error and a state

func (Terminal) Error

func (e Terminal) Error() string

terminal implements error

func (Terminal) Finished

func (e Terminal) Finished() bool

func (Terminal) NewRune

func (e Terminal) NewRune(r rune) (ret State)

returns itself forever

func (Terminal) String

func (e Terminal) String() string

implements string for printing states

func (Terminal) Unwrap

func (e Terminal) Unwrap() error

access the underlying error