commit e5a158b4e5c669ce65c013de4464955055b39af3
parent c2172518ed8e78ac6040e712a29b6b4ad38f1227
Author: lash <dev@holbrook.no>
Date: Sat, 31 Aug 2024 21:34:38 +0100
Add missing package documentation, missing texinfo page
Diffstat:
27 files changed, 110 insertions(+), 4 deletions(-)
diff --git a/db/db.go b/db/db.go
@@ -8,11 +8,17 @@ import (
)
const (
+ // Invalid datatype, must raise error if attempted used.
DATATYPE_UNKNOWN = 0
+ // Bytecode
DATATYPE_BIN = 1
+ // Menu symbol
DATATYPE_MENU = 2
+ // Template symbol
DATATYPE_TEMPLATE = 4
+ // State and cache from persister
DATATYPE_STATE = 8
+ // Application data
DATATYPE_USERSTART = 16
)
@@ -24,7 +30,7 @@ const (
type Db interface {
// Connect prepares the storage backend for use. May panic or error if called more than once.
Connect(ctx context.Context, connStr string) error
- // Close implements io.Closer
+ // Close implements io.Closer. MUST be called before termination after a Connect().
Close() error
// Get retrieves the value belonging to a key. Errors if the key does not exist, or if the retrieval otherwise fails.
Get(ctx context.Context, key []byte) ([]byte, error)
@@ -33,6 +39,9 @@ type Db interface {
// SetPrefix sets the storage context prefix to use for consecutive Get and Put operations.
SetPrefix(pfx uint8)
// SetSession sets the session context to use for consecutive Get and Put operations.
+ // Session only affects the following datatypes:
+ // * DATATYPE_STATE
+ // * DATATYPE_USERSTART
SetSession(sessionId string)
}
@@ -57,6 +66,7 @@ type baseDb struct {
lock uint8
}
+// ensures default locking of read-only entries
func(db *baseDb) defaultLock() {
db.lock = DATATYPE_BIN | DATATYPE_MENU | DATATYPE_TEMPLATE
}
diff --git a/db/doc.go b/db/doc.go
@@ -0,0 +1,2 @@
+// package db contains a generalized data provider interface aswell as a number of built-in implementations.
+package db
diff --git a/db/error.go b/db/error.go
@@ -4,14 +4,17 @@ import (
"fmt"
)
+// ErrNotFound is returned with a key was successfully queried, but did not match a stored key.
type ErrNotFound struct {
k []byte
}
+// NewErrNotFound creates a new ErrNotFound with the given storage key.
func NewErrNotFound(k []byte) error {
return ErrNotFound{k}
}
+// Error implements error.
func(e ErrNotFound) Error() string {
return fmt.Sprintf("key not found: %x", e.k)
}
diff --git a/db/gdbm.go b/db/gdbm.go
@@ -15,6 +15,7 @@ type gdbmDb struct {
prefix uint8
}
+// Creates a new gdbm backed Db implementation.
func NewGdbmDb() *gdbmDb {
db := &gdbmDb{}
db.baseDb.defaultLock()
diff --git a/db/mem.go b/db/mem.go
@@ -12,7 +12,7 @@ type memDb struct {
store map[string][]byte
}
-// NewmemDb returns an already allocated memory backend (volatile) Db implementation.
+// NewmemDb returns an in-process volatile Db implementation.
func NewMemDb(ctx context.Context) *memDb {
db := &memDb{}
db.baseDb.defaultLock()
diff --git a/db/pg.go b/db/pg.go
@@ -8,7 +8,7 @@ import (
"github.com/jackc/pgx/v5/pgxpool"
)
-// pgDb is a Postgresql backend implementation of the Db interface.
+// pgDb is a Postgres backend implementation of the Db interface.
type pgDb struct {
baseDb
conn *pgxpool.Pool
@@ -16,7 +16,7 @@ type pgDb struct {
prefix uint8
}
-// NewpgDb creates a new postgres backed Db implementation.
+// NewpgDb creates a new Postgres backed Db implementation.
func NewPgDb() *pgDb {
db := &pgDb{
schema: "public",
diff --git a/dev/gdbm/main.go b/dev/gdbm/main.go
@@ -1,3 +1,4 @@
+// Executable gdbm processes a given directory recursively and inserts all template files, menu files and bytecode files into corresponding db.Db entries backed by a gdbm backend.
package main
import (
diff --git a/doc/texinfo/exceptions.texi b/doc/texinfo/exceptions.texi
@@ -0,0 +1,66 @@
+@node exceptions
+@chapter Exceptional states
+
+
+@section Ending execution
+
+The @code{vise} VM will terminate execution when it runs out of bytecode.
+
+There may be several different causes of this.
+
+Each case described below references the way the Engine implementation handles an ending execution.
+
+
+@subsection Halting
+
+If the last instruction executed was @code{HALT}, the template of the node where execution terminated should be displayed.
+
+If the template is missing or empty, the last value of the last returned unprocessed symbol from @code{LOAD} (or @code{RELOAD}) should be displayed instead.
+
+If neither exists, it will be considered an @ref{abnormal_termination, abnormal termination} instead.
+
+Otherwise, the execution is considered to have terminated gracefully.
+
+After ending, VM run should start from the topmost node, equivalent to an @code{MOVE ^} instruction.
+
+@anchor{abnormal_termination}
+@subsection Termination
+
+When the VM runs out of bytecode, and the last instruction execution was @emph{not} @code{HALT}, then the @code{TERMINATE} flag will be set.
+
+This will block any future execution of the VM, until the @code{TERMINATE} flag has been explicitly reset.
+
+
+@anchor{default_error}
+@subsection Default error case
+
+When encountering unhandled error states (e.g. external code that returns errors and thus sets @code{LOADFAIL}), the remaining bytecode is purged, and execution is moved to a builtin node called @code{_catch}.
+
+The node has no bytecode by default. If encountered, and if no bytecode has been provided, execution will be stuck on the node @code{_catch} forever.
+
+
+@subsection The @code{CROAK} instruction
+
+The @code{CROAK} instruction may have one of two outcomes.
+
+If encountered while not input (i.e. signal flag @code{READIN} is not set), this will cause a @ref{abnormal_termination, termination}.
+
+Otherwise, it will execute the @ref{default_error, default error case}.
+
+
+
+@section Resuming execution
+
+Depending on the state of the execution end, certain explicit steps may be required.
+
+
+@subsection Graceful exit
+
+Execution will resume from the topmode node, and all flags that are not user-defined will have been reset.
+
+
+@subsection After termination
+
+The @code{TERMINATE} flag, once set, will block any further execution by the VM until it is cleared explicitly by code outside the VM (and the engine).
+
+This is the case even if additional bytecode has been loaded into the state.
diff --git a/examples/db/main.go b/examples/db/main.go
@@ -1,3 +1,4 @@
+// Example: Use db.Db provider for all local data.
package main
import (
diff --git a/examples/gdbm/main.go b/examples/gdbm/main.go
@@ -1,3 +1,4 @@
+// Example: Use gdbm backend to retrieve resources.
package main
import (
diff --git a/examples/helloworld/doc.go b/examples/helloworld/doc.go
@@ -0,0 +1,2 @@
+// Example: Simplest code implementation to be executed by external driver (/dev/interactive)
+package main
diff --git a/examples/http/main.go b/examples/http/main.go
@@ -1,3 +1,4 @@
+// Example: HTTP server wrapper (to be used with manual client).
package main
import (
diff --git a/examples/intro/main.go b/examples/intro/main.go
@@ -1,3 +1,4 @@
+// Example: Basic flags and input processing, and symbol execution.
package main
import (
diff --git a/examples/languages/main.go b/examples/languages/main.go
@@ -1,3 +1,4 @@
+// Example: Set and apply language translation based on input, with and without Gettext.
package main
import (
diff --git a/examples/longmenu/main.go b/examples/longmenu/main.go
@@ -1,3 +1,4 @@
+// Example: Pagination of long resource result content.
package main
import (
diff --git a/examples/pincheck/main.go b/examples/pincheck/main.go
@@ -1,3 +1,4 @@
+// Example: States and branching to check a PIN for access.
package main
import (
diff --git a/examples/preprocessor/main.go b/examples/preprocessor/main.go
@@ -1,3 +1,4 @@
+// Example: Assemble and retrieve state flags using string identifiers specified in csv file.
package main
import (
diff --git a/examples/profile/main.go b/examples/profile/main.go
@@ -1,3 +1,4 @@
+// Example: Profile data completion menu.
package main
import (
diff --git a/examples/quit/main.go b/examples/quit/main.go
@@ -1,3 +1,4 @@
+// Example: Graceful termination that will be resumed from top on next execution.
package main
import (
diff --git a/examples/reuse/main.go b/examples/reuse/main.go
@@ -1,3 +1,4 @@
+// Example: Reuse go functions for multiple LOAD symbols.
package main
import (
diff --git a/examples/session/main.go b/examples/session/main.go
@@ -1,3 +1,4 @@
+// Example: Manual data storage using session id provided to engine.
package main
import (
diff --git a/examples/state/main.go b/examples/state/main.go
@@ -1,3 +1,4 @@
+// Example: Toggling states with external functions.
package main
import (
diff --git a/examples/state_passive/main.go b/examples/state_passive/main.go
@@ -1,3 +1,4 @@
+// Example: Asynchronous state persistence.
package main
import (
diff --git a/examples/validate/main.go b/examples/validate/main.go
@@ -1,3 +1,4 @@
+// Example: Input checker.
package main
import (
diff --git a/lang/doc.go b/lang/doc.go
@@ -0,0 +1,2 @@
+// Package lang provides definitions to specify translation language for template selection and output rendering.
+package lang
diff --git a/logging/doc.go b/logging/doc.go
@@ -0,0 +1,2 @@
+// Package logging provides a logging implementation for internal use in vise.
+package logging
diff --git a/state/doc.go b/state/doc.go
@@ -0,0 +1,2 @@
+// Package state handles execution state, including navigation and state flags.
+package state
