state

Documentation

Overview

Package state maintains the state of the exercise engine.

Index

• type Event
  • func (e *Event) Expected() time.Time
  • func (e *Event) ID() int
  • func (e *Event) LMI() string
  • func (e *Event) Name() string
  • func (e *Event) Notes() []string
  • func (e *Event) Occurred() time.Time
  • func (e *Event) Overdue() bool
  • func (e *Event) RMI() string
  • func (e *Event) Score() int
  • func (e *Event) Station() string
  • func (e *Event) Trigger() int
  • func (e *Event) Type() definition.EventType
• type EventListener
• type LogListener
• type State
  • func New(debug bool) *State
  • func (s *State) AddListener(sl any)
  • func (s *State) AddressForStation(stn string) string
  • func (s *State) AllEvents() []*Event
  • func (s *State) CreateInject(station, name, rmi, method string, trigger int) (e *Event)
  • func (s *State) DropEvent(e *Event)
  • func (s *State) Execute(line string) (e *Event, err error)
  • func (s *State) ExpectEvent(etype definition.EventType, station, name string, by time.Time, trigger int) (e *Event)
  • func (s *State) FindEvent(etype definition.EventType, station, name string) *Event
  • func (s *State) GetEvent(eid int) *Event
  • func (s *State) GetEventByTrigger(etype definition.EventType, station, name string, trigger int) *Event
  • func (s *State) GetSendReceiveEventByStationName(station, name string) *Event
  • func (s *State) IsMessageExpected(station, name string) bool
  • func (s *State) LastEntry() (tstamp time.Time, eid int)
  • func (s *State) LogError(err error)
  • func (s *State) MarkOverdueEvents(asof time.Time)
  • func (s *State) MatchInject(station, name, rmi string) (e *Event)
  • func (s *State) Now() time.Time
  • func (s *State) Open(fname string) (err error)
  • func (s *State) PendingEvent(etype definition.EventType) (event *Event)
  • func (s *State) ReceiveDeliveryReceipt(lmi, rmi string) (e *Event)
  • func (s *State) ReceiveMessage(station, name, lmi, from, subject string) (e *Event)
  • func (s *State) RecordEvent(etype definition.EventType, station, name string) (e *Event)
  • func (s *State) RecordReject(station, name, lmi, from, subject string) (e *Event)
  • func (s *State) ScheduleEvent(etype definition.EventType, station, name string, at time.Time, trigger int) (e *Event)
  • func (s *State) ScoreMessage(e *Event, problems []string, score int) *Event
  • func (s *State) SendMessage(etype definition.EventType, station, name, lmi, subject string, trigger int) (e *Event)
  • func (s *State) SentBulletins() (sbs []*Event)
  • func (s *State) SetNowFunc(now func() time.Time)
  • func (s *State) StartExercise() (e *Event)
  • func (s *State) StartStation(station string) (e *Event)
  • func (s *State) StationStarted(stn string) bool

Types

type Event

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

An Event is a single event in the exercise, either expected or occurred.

func (*Event) Expected

func (e *Event) Expected() time.Time

Expected is the time at which this event is scheduled or by which this event is expected. It is zero if Trigger is zero.

func (*Event) ID

func (e *Event) ID() int

ID is the unique identifier of the event.

func (*Event) LMI

func (e *Event) LMI() string

LMI is the local message ID of the message for a "send" or "receive" event that has occurred. It is empty for other events.

func (*Event) Name

func (e *Event) Name() string

Name is the message name for the event. It can be "UNKNOWN" for a received message that wasn't recognized. It will be "" for events of type "start".

func (*Event) Notes

func (e *Event) Notes() []string

Notes are the notes associated with the event, if any. The returned slice should not be changed by the caller.

func (*Event) Occurred

func (e *Event) Occurred() time.Time

Occurred is the time at which this event occurred. It is zero if the event is anticipated but hasn't yet occurred.

func (*Event) Overdue

func (e *Event) Overdue() bool

Overdue returns whether the event is (or was) overdue.

func (*Event) RMI

func (e *Event) RMI() string

RMI is the remote message ID for a sent or received message. For a sent message, it comes from the delivery receipt; for a received message, it comes from the subject line. It is empty for all other events.

func (*Event) Score

func (e *Event) Score() int

Score is the percentage score (between 0 and 100) for a received message. It is zero for all other events.

func (*Event) Station

func (e *Event) Station() string

Station is the call sign of the station for the event. It can be "UNKNOWN" for a message received from an unknown station. It will be "" for events not associated with a station, such as the start event or the sending of a bulletin.

func (*Event) Trigger

func (e *Event) Trigger() int

Trigger is the unique identifier of the event that triggered this one. It is zero if there is no such event.

func (*Event) Type

func (e *Event) Type() definition.EventType

Type is the type of event.

type EventListener

type EventListener interface {
	// OnEventChange is called whenever an event is created or updated.
	// To receive all event changes starting from the beginning of the
	// exercise, the listener must be added with AddListener before Open is
	// called.
	OnEventChange(e *Event)
}

An EventListener is an object that listens for new and updated events.

type LogListener

type LogListener interface {
	// OnLogLine is called whenever there is a new line added to the state
	// log.  To receive all lines starting from the beginning of the log,
	// the listener must be added with AddListener before Open is called.
	OnLogLine(line string)
}

A LogListener is an object that listens for new lines added to the state log.

type State

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

State represents the state of the exercise engine. Note that the State is not thread-safe. All calls to its methods must be synchronized by the caller.

func New

func New(debug bool) *State

New creates a new State tracker.

func (*State) AddListener

func (s *State) AddListener(sl any)

AddListener adds a listener to the state. It should implement LogListener or EventListener or both. Any number of listeners can be added. To receive notifications from the exercise beginning, AddListener must be called before Open.

func (*State) AddressForStation

func (s *State) AddressForStation(stn string) string

AddressForStation returns the last recorded address from which the named station sent a message. It returns the station name itself (lowercased) if no messages have been received from the station.

func (*State) AllEvents

func (s *State) AllEvents() []*Event

AllEvents returns a slice of all events. It must not be modified.

func (*State) CreateInject

func (s *State) CreateInject(station, name, rmi, method string, trigger int) (e *Event)

func (*State) DropEvent

func (s *State) DropEvent(e *Event)

func (*State) Execute

func (s *State) Execute(line string) (e *Event, err error)

Execute parses and executes a single state change line.

func (*State) ExpectEvent

func (s *State) ExpectEvent(etype definition.EventType, station, name string, by time.Time, trigger int) (e *Event)

func (*State) FindEvent

func (s *State) FindEvent(etype definition.EventType, station, name string) *Event

FindEvent returns the event with the specified type, station, and message name, if it exists. If there is more than one such event, it returns the latest one.

func (*State) GetEvent

func (s *State) GetEvent(eid int) *Event

GetEvent returns the event with the specified ID, or nil if there is none.

func (*State) GetEventByTrigger

func (s *State) GetEventByTrigger(etype definition.EventType, station, name string, trigger int) *Event

GetEventByTrigger returns any existing event with the specified type, station, message name, and trigger.

func (*State) GetSendReceiveEventByStationName

func (s *State) GetSendReceiveEventByStationName(station, name string) *Event

GetSendReceiveEventByStationName returns the Send or Receive event with the specified station and message name.

func (*State) IsMessageExpected

func (s *State) IsMessageExpected(station, name string) bool

IsMessageExpected returns whether a received message with the specified station and message name is expected.

func (*State) LastEntry

func (s *State) LastEntry() (tstamp time.Time, eid int)

LastEntry returns the timestamp and event ID of the last entry in the state log. It returns zeros if there have been no entries.

func (*State) LogError

func (s *State) LogError(err error)

LogError adds an error to the log file.

func (*State) MarkOverdueEvents

func (s *State) MarkOverdueEvents(asof time.Time)

func (*State) MatchInject

func (s *State) MatchInject(station, name, rmi string) (e *Event)

func (*State) Now

func (s *State) Now() time.Time

Now returns the current time of day.

func (*State) Open

func (s *State) Open(fname string) (err error)

Open connects the state tracker to a log file. It opens the log file, creating it if it doesn't already exist. It executes each log entry already in the file. Then it sets up a state listener that adds new log entries to the end of the file. If fname is empty, the default name (exercise.log) is used.

func (*State) PendingEvent

func (s *State) PendingEvent(etype definition.EventType) (event *Event)

PendingEvent returns the past-scheduled but not completed event of the specified type with the lowest scheduled time. If there is no such, it return nil.

func (*State) ReceiveDeliveryReceipt

func (s *State) ReceiveDeliveryReceipt(lmi, rmi string) (e *Event)

func (*State) ReceiveMessage

func (s *State) ReceiveMessage(station, name, lmi, from, subject string) (e *Event)

func (*State) RecordEvent

func (s *State) RecordEvent(etype definition.EventType, station, name string) (e *Event)

func (*State) RecordReject

func (s *State) RecordReject(station, name, lmi, from, subject string) (e *Event)

func (*State) ScheduleEvent

func (s *State) ScheduleEvent(etype definition.EventType, station, name string, at time.Time, trigger int) (e *Event)

func (*State) ScoreMessage

func (s *State) ScoreMessage(e *Event, problems []string, score int) *Event

func (*State) SendMessage

func (s *State) SendMessage(etype definition.EventType, station, name, lmi, subject string, trigger int) (e *Event)

func (*State) SentBulletins

func (s *State) SentBulletins() (sbs []*Event)

SentBulletins returns a list of events for sent bulletins. Only those sent to station "-" are included, and only those that have occurred.

func (*State) SetNowFunc

func (s *State) SetNowFunc(now func() time.Time)

SetNowFunc sets the function used by the state engine to determine the current time of day. It is used for replaying old exercises and for testing.

func (*State) StartExercise

func (s *State) StartExercise() (e *Event)

func (*State) StartStation

func (s *State) StartStation(station string) (e *Event)

func (*State) StationStarted

func (s *State) StationStarted(stn string) bool

StationStarted returns whether the specified station has started the exercise.