commit d12ff18dd999f522c2311c191843d74f8eb27a63
parent 983bac0c5383c592e332b5d015c2e535aaa75b40
Author: lash <dev@holbrook.no>
Date: Thu, 6 Apr 2023 12:08:30 +0100
Add documentation
Diffstat:
3 files changed, 24 insertions(+), 11 deletions(-)
diff --git a/go/engine/engine.go b/go/engine/engine.go
@@ -30,7 +30,7 @@ func NewEngine(st *state.State, rs resource.Resource) Engine {
// Init must be explicitly called before using the Engine instance.
//
-// It makes sure bootstrapping code has been executed, and that the exposed bytecode is ready for user input.
+// It loads and executes code for the start node.
func(en *Engine) Init(sym string, ctx context.Context) error {
err := en.st.SetInput([]byte{})
if err != nil {
@@ -47,16 +47,12 @@ func(en *Engine) Init(sym string, ctx context.Context) error {
// Exec processes user input against the current state of the virtual machine environment.
//
-// If successfully executed:
-// - output of the last execution is available using the WriteResult(...) call
-// - Exec(...) may be called again with new input
-//
-// This implementation is in alpha state. That means that any error emitted may have left the system in an undefined state.
-//
-// TODO: Disambiguate errors as critical and resumable errors.
+// If successfully executed, output of the last execution is available using the WriteResult call.
+//
+// A bool return valus of false indicates that execution should be terminated. Calling Exec again has undefined effects.
//
// Fails if:
-// - input is objectively invalid (too long etc)
+// - input is formally invalid (too long etc)
// - no current bytecode is available
// - input processing against bytcode failed
func (en *Engine) Exec(input []byte, ctx context.Context) (bool, error) {
@@ -89,6 +85,10 @@ func (en *Engine) Exec(input []byte, ctx context.Context) (bool, error) {
}
en.st.SetCode(code)
+ if len(code) == 0 {
+ log.Printf("runner finished with no remaining code")
+ return false, nil
+ }
return true, nil
}
diff --git a/go/resource/render.go b/go/resource/render.go
@@ -5,6 +5,7 @@ import (
"text/template"
)
+// DefaultRenderTemplate is an adapter to implement the builtin golang text template renderer as resource.RenderTemplate.
func DefaultRenderTemplate(r Resource, sym string, values map[string]string) (string, error) {
v, err := r.GetTemplate(sym)
if err != nil {
diff --git a/go/resource/resource.go b/go/resource/resource.go
@@ -17,8 +17,8 @@ type Resource interface {
ShiftMenu() (string, string, error) // Remove and return the first menu item in list.
SetMenuBrowse(string, string, bool) error // Set menu browser display details.
RenderTemplate(sym string, values map[string]string) (string, error) // Render the given data map using the template of the symbol.
- RenderMenu() (string, error)
- FuncFor(sym string) (EntryFunc, error) // Resolve symbol code point for.
+ RenderMenu() (string, error) // Render the current state of menu
+ FuncFor(sym string) (EntryFunc, error) // Resolve symbol content point for.
}
type MenuResource struct {
@@ -27,6 +27,11 @@ type MenuResource struct {
prev [2]string
}
+// SetMenuBrowse defines the how pagination menu options should be displayed.
+//
+// The selector is the expected user input, and the title is the description string.
+//
+// If back is set, the option will be defined for returning to a previous page.
func(m *MenuResource) SetMenuBrowse(selector string, title string, back bool) error {
entry := [2]string{selector, title}
if back {
@@ -37,12 +42,16 @@ func(m *MenuResource) SetMenuBrowse(selector string, title string, back bool) er
return nil
}
+// PutMenu adds a menu option to the menu rendering.
func(m *MenuResource) PutMenu(selector string, title string) error {
m.menu = append(m.menu, [2]string{selector, title})
log.Printf("menu %v", m.menu)
return nil
}
+// PutMenu removes and returns the first of remaining menu options.
+//
+// Fails if menu is empty.
func(m *MenuResource) ShiftMenu() (string, string, error) {
if len(m.menu) == 0 {
return "", "", fmt.Errorf("menu is empty")
@@ -52,6 +61,9 @@ func(m *MenuResource) ShiftMenu() (string, string, error) {
return r[0], r[1], nil
}
+// RenderMenu returns the full current state of the menu as a string.
+//
+// After this has been executed, the state of the menu will be empty.
func(m *MenuResource) RenderMenu() (string, error) {
r := ""
for true {
