history

package
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 10, 2025 License: MIT Imports: 6 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrEOT occurs when the end (or the start) of a timeline is reached and any
	// iteration should stop. Readers must not wrap this error as callers are
	// expected to check for this error with the == operator.
	//
	// Format:
	// 	"end of the timeline has been reached"
	ErrEOT error = errors.New("end of the timeline has been reached")

	// ErrSubject occurs when evaluators have detected that an error has occurred in the subject
	// but it was expected not to happen. Readers must not wrap this error as callers are
	// expected to check for this error with the == operator.
	//
	// Format:
	// 	"detected subject to have an error"
	ErrSubject error = errors.New("detected subject to have an error")

	// ErrEmptyStack occurs when a stack is empty. Readers must not wrap this error as callers are
	// expected to check for this error with the == operator.
	//
	// Format:
	// 	"stack is empty"
	ErrEmptyStack error = errors.New("stack is empty")
)

Functions

func AsSeq 

func AsSeq[S Subject[E], E Event](initFn func() (S, error), store_invalids bool) iter.Seq2[Result[E], error]

AsSeq returns a pull-based iterator over the final results of the evaluation that generates the results in a procedural manner.

The iterator is lazily generated by walking the history forward by one step at a time and applying the next event to the subject. Only when a result has no more next events it is yielded. However, if the result is unsuccessful (i.e., the subject has errors), it won't be yielded until no more successful results are possible. This allows for stopping the evaluation early if a satisfying solution is found before all the possible results are exhausted.

For optimization reasons, not only the evaluator does not use recursion, but it also is thread-safe. Yet, the evaluator itself does not use any concurrency model. For that, a specific method must be called to enable concurrency.

Parameters:

  • initFn: The evaluator to use.
  • store_invalids: Whether to store invalid results in the final results.

Returns:

  • iter.Seq2[Result[E], error]: The iterator over the final results of the evaluation that generates the results in a procedural manner. (Never returns nil.)

The `store_invalids` parameter can be used to store invalid results in the final results. This can be useful for debugging purposes. However, it may occupy a lot of memory so it can be disabled if it is not needed.

func NewErrInvalidType 

func NewErrInvalidType(got any, want any) error

NewErrInvalidType creates a new ErrInvalidType error.

Parameters:

  • got: The actual type of the value.
  • want: The expected type of the value.

Returns:

  • error: The newly created error. Never returns nil.

Format: 

"want <want>, got <got>"

Where:

  • <want> is the expected type of the value.
  • <got> is the actual type of the value.

func Shadow 

func Shadow[E Event](initFn InitFn[E], timeline []E) iter.Seq2[Subject[E], error]

Shadow returns a pull-based iterator over the subjects generated by applying a sequence of events to an initial subject created by the init function.

The function iteratively applies each event in the given timeline to the subject. If an error occurs during the application of an event, the error is yielded and the iteration stops. The subject is yielded before and after each event is applied.

Parameters:

  • initFn: A function that initializes and returns a new subject.
  • timeline: A slice of events to be applied to the subject.

Returns:

  • iter.Seq2[Subject[E], error]: An iterator yielding subjects and errors encountered during event application.

This is used as a way to "replay" a sequence of events to a subject.

func SubjectOf 

func SubjectOf[S Subject[E], E Event](result Result[E]) (S, error)

SubjectOf returns the subject of the given result.

Parameters:

  • result: The result to get the subject from.

Returns:

  • S: The subject of the result.
  • error: An error if the subject is not the expected type.

Types

type ErrInvalidType 

type ErrInvalidType struct {
	// Want is the expected type of the value.
	Want any

	// Got is the actual type of the value.
	Got any
}

ErrInvalidType is an error that occurs when the type of a value is not as expected.

func (ErrInvalidType) Error 

func (e ErrInvalidType) Error() string

Error implements error.

type Event 

type Event interface{}

Event is the interface for events.

type History 

type History[E Event] struct {
	// contains filtered or unexported fields
}

History is a history of events.

func (History[E]) AppendEvent 

func (h History[E]) AppendEvent(event E) History[E]

AppendEvent creates a new History[E] that is a copy of the parameter but with the given event appended to the timeline.

The new History[E] will have its arrow in the same position as the parameter.

Parameters:

  • event: The event to append to the timeline.

Returns:

  • History[E]: A new History[E] with the given event appended to the timeline.

func (History[E]) Arrow 

func (h History[E]) Arrow() uint

Arrow returns the current index of the arrow in the timeline.

Returns:

  • uint: The current index of the arrow in the timeline.

func (History[E]) CurrentEvent 

func (h History[E]) CurrentEvent() (E, bool)

CurrentEvent returns the event at the current position of the arrow, or a default-constructed event and false if the arrow is out of bounds.

Returns:

  • E: The event at the current position of the arrow, or a default-constructed event if the arrow is out of bounds.
  • bool: True if the arrow is in bounds, false otherwise.

func (*History[E]) Restart 

func (h *History[E]) Restart() error

Restart resets the arrow to the beginning of the timeline.

Returns:

  • error: An error if the history could not be reset.

Errors:

  • common.ErrNilReceiver: If the receiver is nil.

func (History[E]) Size added in v0.1.2 

func (h History[E]) Size() uint

Size returns the number of events in the history.

Returns:

  • uint: The number of events in the history.

func (History[E]) Timeline 

func (h History[E]) Timeline() []E

Timeline returns a copy of the timeline of events.

Returns:

  • []E: A copy of the timeline of events.

func (*History[E]) WalkBackward 

func (h *History[E]) WalkBackward() (E, error)

WalkBackward moves the arrow backward and returns the event at the new position.

The arrow is moved one position backward, and the event at the new position is returned. If the arrow is already at the beginning of the timeline, the function returns a default-constructed event and an error.

Returns:

  • E: The event at the new position of the arrow, or a default-constructed event if the arrow is at the beginning of the timeline.
  • error: An error if the walk fails.

Errors:

  • common.ErrNilReceiver: If the history is nil.
  • ErrEOT: If the end of the timeline is reached.

func (*History[E]) WalkForward 

func (h *History[E]) WalkForward() (E, error)

WalkForward moves the arrow forward and returns the event at the new position.

The arrow is moved one position forward, and the event at the new position is returned. If the arrow is already at the end of the timeline, the function returns a default-constructed event and an error.

Returns:

  • E: The event at the new position of the arrow, or a default-constructed event if the arrow is at the end of the timeline.
  • error: An error if the walk fails.

Errors:

  • common.ErrNilReceiver: If the history is nil.
  • ErrEOT: If the end of the timeline is reached.

type InitFn 

type InitFn[E Event] func() (Subject[E], error)

Init creates a new subject and returns it. If an error does not occur, the subject must not be nil.

Returns:

  • Subject[E]: The new subject.
  • error: An error if it cannot create a new subject.

Errors:

  • common.ErrNilReceiver: If the receiver is nil.
  • any other error: Implementation-specific.

func New 

func New[S Subject[E], E Event](initFn func() (S, error)) InitFn[E]

New returns an InitFn that returns the initial state of the subject.

Parameters:

  • initFn: A function that returns the initial state of the subject.

Returns:

  • InitFn[E]: The init function. (Never returns nil.)

If the `initFn` is nil, the function will always fail.

type Result 

type Result[E Event] struct {
	// Timeline is the timeline of events.
	Timeline []E

	// Subject is the subject that was used to process the events.
	Subject Subject[E]
}

Result is the result of a history walk.

func Execute 

func Execute[E Event](seq iter.Seq2[Result[E], error]) ([]Result[E], bool, error)

Execute executes the evaluator and returns the final results. This can either be all valid results or all invalid results (no mixed results).

Parameters:

  • seq: The sequence of results to execute.

Returns:

  • []Result[E]: A slice of the final results of the evaluation.
  • bool: True if all the results are valid, false otherwise.
  • error: The first error encountered during the execution of the sequence, or nil if no errors were encountered.

Since this stores all the results, it is not as efficient as the `AsSeq` method.

type Subject 

type Subject[E Event] interface {
	// HasError checks whether the subject has encountered non-fatal errors.
	//
	// Returns:
	//   - bool: True if the subject has encountered non-fatal errors, false otherwise.
	HasError() bool

	// ApplyEvent applies the given event to the subject.
	//
	// Parameters:
	//   - event: The event to apply.
	//
	// Returns:
	//   - error: An error if the subject cannot apply the event, nil otherwise.
	//
	// The error returned is for panic-level of errors. For any other error, make use
	// of the `HasError` method.
	ApplyEvent(event E) error

	// NextEvents returns the next events that can be applied to the subject.
	//
	// Returns:
	//   - []E: The next events that can be applied to the subject.
	//   - error: An error if the subject cannot return the next events, nil otherwise.
	//
	// The error returned is for panic-level of errors. For any other error, make use
	// of the `HasError` method.
	NextEvents() ([]E, error)

	// Err returns the last error encountered by the subject. Because this function
	// builds the error, it assumes an error has occurred when this function is called;
	// thus, it may return an error even if the subject has no errors.
	//
	// Returns:
	//   - error: The last error encountered by the subject.
	Err() error
}

Subject is a subject that can be used to process events.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.