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) error
- type InvalidRune
- type Parser
- 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 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
- type UnhandledRune
Constants ¶
const Eof = rune(-1)
Variables ¶
var ErrFinished = errors.New("finished")
this provided an alternative to the terminal state holding nil. ( to avoid testing its error when dereferencing )
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 ¶
Types ¶
type InvalidRune ¶
type InvalidRune rune
implements error
func (InvalidRune) Error ¶
func (e InvalidRune) Error() string
type Parser ¶ added in v0.9.1
type Parser struct {
// contains filtered or unexported fields
}
func MakeParser ¶ added in v0.9.1
func MakeParser(in io.RuneReader) Parser
func (*Parser) Parse ¶ added in v0.9.1
always returns an error, and the final state. ex. if the last rune was unhandled, then this returns an UnhandledRune error and the state that failed to handle it.
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 ¶
one or more of the runes must pass the filter
func Error ¶
Used by states to wrap an error in a Terminal state. This is the only way for states to return an error. To stop processing, but return no error: see Finished()
func Finished ¶ added in v0.8.1
func Finished() State
A next state indicating an expected termination. This is used to absorb runes.Eof and end a state gracefully because returning nil on Eof will trigger attempts by chained states to handle the Eof themselves.
func Parallel ¶
Parallel region; run all of the passed states until they all return nil. if any return error, this returns error.
func RunStep ¶
RunStep - run a sequence of of two states sending the current rune to the first state immediately see also: Step()
func Self ¶
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 ¶
Statement functions behave as a State. ( Self works the same, except that passes the state to its function as "self" and this does not )
type Terminal ¶
type Terminal struct {
// contains filtered or unexported fields
}
acts as both an error and a state
type UnhandledRune ¶ added in v0.9.1
type UnhandledRune rune
returned from Parser
func (UnhandledRune) Error ¶ added in v0.9.1
func (u UnhandledRune) Error() string
Source Files