lua

package
v0.0.0 Latest Latest
Warning

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

 Go to latest Published: Dec 26, 2025 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

CRC: crc-LuaResolver.md Spec: libraries.md Sequence: seq-lua-resolve.md

CRC: crc-LuaRuntime.md, crc-LuaSession.md, crc-LuaVariable.md Spec: interfaces.md, deployment.md, libraries.md Sequence: seq-lua-executor-init.md, seq-lua-execute.md, seq-lua-handle-action.md, seq-lua-session-init.md

Package lua provides ViewList wrapper for array value transformation. CRC: crc-ViewList.md, crc-Wrapper.md Spec: viewdefs.md, protocol.md Sequence: seq-viewlist-presenter-sync.md, seq-wrapper-transform.md

Package lua provides ViewListItem type for ViewList array elements. CRC: crc-ViewListItem.md Spec: viewdefs.md Sequence: seq-viewlist-presenter-sync.md, seq-wrapper-transform.md

Package lua provides wrapper support for variable value transformation. CRC: crc-Wrapper.md, crc-Variable.md Spec: protocol.md Sequence: seq-wrapper-transform.md

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GetType 

func GetType(L *lua.LState, obj any) string

func NewViewList 

func NewViewList(sess *LuaSession, variable *TrackerVariableAdapter) interface{}

NewViewList creates a new ViewList wrapper for a variable.

func RegisterCreateFactory 

func RegisterCreateFactory(typeName string, factory CreateFactory)

RegisterCreateFactory registers a Go create factory globally.

func RegisterWrapperType 

func RegisterWrapperType(typeName string, factory WrapperFactory)

RegisterWrapperType registers a Go wrapper factory globally.

Types

type CreateFactory 

type CreateFactory func(session *LuaSession, value interface{}) interface{}

CreateFactory creates a new object instance from a value.

func GetGlobalCreateFactory 

func GetGlobalCreateFactory(typeName string) (CreateFactory, bool)

GetGlobalCreateFactory retrieves a globally registered create factory.

type ItemWrapperInstance 

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

ItemWrapperInstance represents a created item wrapper (presenter).

type LuaResolver 

type LuaResolver struct {
	Session *LuaSession
}

LuaResolver implements changetracker.Resolver for Lua tables and Go wrappers. It navigates Lua tables using GetField/RawGetInt and converts values appropriately.

func (*LuaResolver) Call 

func (r *LuaResolver) Call(obj any, methodName string) (any, error)

Call invokes a zero-argument method on a Lua table and returns the result. Used for computed getters like compute().

func (*LuaResolver) CallWith 

func (r *LuaResolver) CallWith(obj any, methodName string, value any) error

CallWith invokes a one-argument method on a Lua table with the given value. Used for computed setters like setValue(_).

func (*LuaResolver) CreateValue 

func (r *LuaResolver) CreateValue(variable *changetracker.Variable, typ string, value any) any

CreateValue creates a value for the given variable. CRC: crc-LuaResolver.md Spec: protocol.md (Variable Wrappers section)

func (*LuaResolver) CreateWrapper 

func (r *LuaResolver) CreateWrapper(variable *changetracker.Variable) any

CreateWrapper creates a wrapper object for the given variable. The wrapper stands in for the variable's value when child variables navigate paths. Returns the existing wrapper if one exists (for wrapper reuse). CRC: crc-LuaResolver.md Spec: protocol.md (Variable Wrappers section)

func (*LuaResolver) Get 

func (r *LuaResolver) Get(obj any, pathElement any) (any, error)

Get retrieves a value from an object at the given path element.

func (*LuaResolver) GetType 

func (r *LuaResolver) GetType(variable *changetracker.Variable, obj any) string

GetType returns a value's type, given the variable as context. CRC: crc-LuaResolver.md Spec: protocol.md (Variable Wrappers section)

func (*LuaResolver) Set 

func (r *LuaResolver) Set(obj any, pathElement any, value any) error

Set assigns a value in a Lua table at the given path element.

type LuaSession 

type LuaSession struct {
	*Runtime
	ID string // Vended session ID (e.g., "1", "2", "3")

	McpState   *lua.LTable // Logical state root for MCP (defaults to appObject)
	McpStateID int64       // Variable ID of mcpState (if tracked)
	// contains filtered or unexported fields
}

LuaSession represents a per-frontend-session Lua environment. ID is the vended session ID (compact integer string like "1", "2") for backend communication, not the internal UUID which is used for URL paths. Change detection is handled by the tracker in VariableStore.

func (*LuaSession) ArrayGet 

func (s *LuaSession) ArrayGet(array any, index int) (any, error)

func (*LuaSession) ArrayGetter 

func (s *LuaSession) ArrayGetter(array any) (func(int) (any, error), int, error)

func (*LuaSession) GetTracker 

func (s *LuaSession) GetTracker() *changetracker.Tracker

func (*LuaSession) Set 

func (s *LuaSession) Set(varID int64, value any) error

type LuaWrapper 

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

LuaWrapper wraps a Lua table as a Go Wrapper interface.

func NewLuaWrapper 

func NewLuaWrapper(session *LuaSession, template luaTable, variable *TrackerVariableAdapter) *LuaWrapper

NewLuaWrapper creates a wrapper from a Lua table definition.

func (*LuaWrapper) Value 

func (w *LuaWrapper) Value() any

Value returns the wrapped Lua table instance.

type PresenterType 

type PresenterType struct {
	Name    string
	Methods map[string]*lua.LFunction
	Table   *lua.LTable
}

PresenterType represents a Lua-defined presenter type.

type Runtime 

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

Runtime manages embedded Lua VM execution with multiple sessions.

func NewRuntime 

func NewRuntime(cfg *config.Config, luaDir string, vdm *viewdef.ViewdefManager) (*Runtime, error)

NewRuntime creates a new Lua runtime with executor goroutine.

func (*Runtime) AfterBatch 

func (r *Runtime) AfterBatch(vendedID string) []VariableUpdate

AfterBatch triggers change detection for a session after processing a message batch. Returns a list of variable updates that need to be sent to the frontend. vendedID is the compact session ID (e.g., "1", "2").

func (*Runtime) CallLuaWrapperMethod 

func (r *Runtime) CallLuaWrapperMethod(instance interface{}, method string, args ...interface{}) (interface{}, error)

CallLuaWrapperMethod invokes a method on a Lua wrapper table via executor. Used by LuaWrapper to call computeValue and destroy methods. The instance can be any interface{} but must be a *lua.LTable at runtime.

func (*Runtime) CallMethod 

func (r *Runtime) CallMethod(instance *lua.LTable, method string, args ...interface{}) (interface{}, error)

CallMethod invokes a method on a Lua presenter instance via executor.

func (*Runtime) CreateInstance 

func (r *Runtime) CreateInstance(typeName string, props map[string]interface{}) (*lua.LTable, error)

CreateInstance creates a new instance of a presenter type via executor.

func (*Runtime) CreateItemWrapper 

func (r *Runtime) CreateItemWrapper(typeName string, viewItem *ViewListItem) (*ItemWrapperInstance, error)

CreateItemWrapper creates an ItemWrapper instance for a ViewListItem. The ItemWrapper constructor receives the ViewListItem: ItemWrapper(viewListItem). Returns nil if no itemType is specified or the type isn't registered.

func (*Runtime) CreateLuaSession 

func (r *Runtime) CreateLuaSession(vendedID string) (*LuaSession, error)

CreateLuaSession creates a new Lua session for a frontend session. vendedID is the compact session ID (e.g., "1", "2") for backend communication. Loads and executes main.lua with a session global. Must be called after SetVariableStore.

func (*Runtime) DestroyLuaSession 

func (r *Runtime) DestroyLuaSession(vendedID string)

DestroyLuaSession removes a Lua session by its vended ID.

func (*Runtime) ExecuteInSession 

func (r *Runtime) ExecuteInSession(sessionID string, fn func() (interface{}, error)) (interface{}, error)

ExecuteInSession executes a function within the context of a specific session. It sets the global 'session' variable to the target session's table before execution. Spec: mcp.md CRC: crc-LuaRuntime.md Sequence: seq-mcp-run.md

func (*Runtime) GetGlobalTable 

func (r *Runtime) GetGlobalTable(name string) interface{}

GetGlobalTable looks up a Lua global by name and returns it if it's a table. Used for auto-discovery of Lua-defined wrappers. Returns nil if the global doesn't exist or isn't a table.

func (*Runtime) GetLuaSession 

func (r *Runtime) GetLuaSession(vendedID string) (*LuaSession, bool)

GetLuaSession retrieves a Lua session by its vended ID.

func (*Runtime) GetPresenterType 

func (r *Runtime) GetPresenterType(name string) (*PresenterType, bool)

GetPresenterType returns a registered presenter type.

func (*Runtime) GetValue 

func (r *Runtime) GetValue(tbl *lua.LTable, key string) interface{}

GetValue gets a value from a Lua table via executor.

func (*Runtime) HandleFrontendCreate 

func (r *Runtime) HandleFrontendCreate(sessionID string, parentID int64, properties map[string]string) (int64, json.RawMessage, map[string]string, error)

HandleFrontendCreate handles a variable create message from the frontend. For path-based variables, it creates the variable in the tracker and resolves the path. If a wrapper property is set, the tracker automatically creates it via the resolver. Returns the variable ID, resolved value (wrapped if applicable), and properties.

func (*Runtime) HandleFrontendUpdate 

func (r *Runtime) HandleFrontendUpdate(sessionID string, varID int64, value json.RawMessage) error

HandleFrontendUpdate handles an update to a path-based variable from frontend. Updates the backend object via the variable's path using v.Set(). CRC: crc-LuaRuntime.md Sequence: seq-relay-message.md

func (*Runtime) ListPresenterTypes 

func (r *Runtime) ListPresenterTypes() []string

ListPresenterTypes returns all registered presenter type names.

func (*Runtime) LoadCode 

func (r *Runtime) LoadCode(name, code string) (interface{}, error)

LoadCode loads and executes Lua code string via executor. It returns the result of the execution (if any). Spec: mcp.md CRC: crc-LuaRuntime.md

func (*Runtime) LoadFile 

func (r *Runtime) LoadFile(filename string) error

LoadFile loads and executes a Lua file via executor (relative to luaDir).

func (*Runtime) LoadFileAbsolute 

func (r *Runtime) LoadFileAbsolute(path string) error

LoadFileAbsolute loads and executes a Lua file via executor (absolute path).

func (*Runtime) Log 

func (r *Runtime) Log(level int, format string, args ...interface{})

Log logs a message via the config.

func (*Runtime) NotifyPropertyChange 

func (r *Runtime) NotifyPropertyChange(vendedID string, varID int64, property string, value interface{})

NotifyPropertyChange notifies Lua watchers of a property change for a session. Called by external code when a variable property changes. vendedID is the compact session ID (e.g., "1", "2").

func (*Runtime) RedirectOutput 

func (r *Runtime) RedirectOutput(logPath, errPath string) error

RedirectOutput redirects Lua's print function and standard streams to log files. It is used by the MCP server in Configured state. Spec: mcp.md CRC: crc-LuaRuntime.md

func (*Runtime) SetMainLuaCode 

func (r *Runtime) SetMainLuaCode(code string)

SetMainLuaCode sets the main.lua code to execute for each new session. Used when loading from bundle where filesystem access is not available.

func (*Runtime) SetNotificationHandler 

func (r *Runtime) SetNotificationHandler(handler func(method string, params interface{}))

SetNotificationHandler sets the callback for MCP notifications.

func (*Runtime) SetValue 

func (r *Runtime) SetValue(tbl *lua.LTable, key string, value interface{})

SetValue sets a value on a Lua table via executor.

func (*Runtime) SetVariableStore 

func (r *Runtime) SetVariableStore(store VariableStore)

SetVariableStore sets the variable store for session operations.

func (*Runtime) SetWrapperRegistry 

func (r *Runtime) SetWrapperRegistry(registry *WrapperRegistry)

SetWrapperRegistry sets the wrapper registry for registering Lua wrappers.

func (*Runtime) Shutdown 

func (r *Runtime) Shutdown()

Shutdown cleans up the Lua VM and stops executor.

func (*Runtime) TriggerBatch 

func (r *Runtime) TriggerBatch()

type TrackerVariableAdapter 

type TrackerVariableAdapter struct {
	*changetracker.Variable
	Session *LuaSession
}

TrackerVariableAdapter adapts a change-tracker Variable to WrapperVariable interface

func WrapTrackerVariable 

func WrapTrackerVariable(session *LuaSession, v *changetracker.Variable) *TrackerVariableAdapter

type VariableStore 

type VariableStore interface {
	// Session management - each session has its own tracker
	CreateSession(sessionID string, resolver changetracker.Resolver)
	DestroySession(sessionID string)
	GetTracker(sessionID string) *changetracker.Tracker

	// Variable operations (delegate to session's tracker)
	CreateVariable(sessionID string, parentID int64, luaObject *lua.LTable, properties map[string]string) (int64, error)
	Get(id int64) (value json.RawMessage, properties map[string]string, ok bool)
	GetProperty(id int64, name string) (string, bool)
	Update(id int64, value json.RawMessage, properties map[string]string) error
	Destroy(id int64) error

	// Change detection
	DetectChanges(sessionID string) bool
	GetChanges(sessionID string) []changetracker.Change
}

VariableStore interface for session operations.

type VariableUpdate 

type VariableUpdate struct {
	VarID      int64
	Value      json.RawMessage
	Properties map[string]string
}

VariableUpdate represents a detected change to be sent to the frontend.

type ViewList 

type ViewList struct {
	Items          []*ViewListItem // The actual list of ViewListItem objects
	SelectionIndex int             // The current selection index
	// contains filtered or unexported fields
}

ViewList transforms an array of domain object refs into ViewListItem refs. It creates ViewListItem objects for each item in the source array.

func (*ViewList) Destroy 

func (vl *ViewList) Destroy() error

Destroy cleans up all ViewListItems when the variable is destroyed.

func (*ViewList) SyncViewItems 

func (vl *ViewList) SyncViewItems()

SyncViewItems synchronizes the `Items` slice with the `value` slice.

func (*ViewList) Tracker 

func (vl *ViewList) Tracker() *changetracker.Tracker

func (*ViewList) Update 

func (vl *ViewList) Update(newValue interface{})

Update updates the ViewList with a new raw value from the backend.

func (*ViewList) Value 

func (vl *ViewList) Value() interface{}

Value returns the list of ViewListItems.

type ViewListItem 

type ViewListItem struct {
	Item     any // BaseItem or a wrapper, if ViewList.itemType is set
	BaseItem any // Domain object reference
	List     *ViewList
	Index    int
	// contains filtered or unexported fields
}

ViewListItem represents an element in a ViewList. It provides domain object access (Item), presenter access (Item), list context (List), and position tracking (Index).

func NewViewListItem 

func NewViewListItem(item interface{}, list *ViewList, index int) *ViewListItem

NewViewListItem creates a new ViewListItem for a domain object.

func (*ViewListItem) GetBaseItem 

func (vli *ViewListItem) GetBaseItem() interface{}

GetItem returns the (possibly wrapped) item reference.

func (*ViewListItem) GetIndex 

func (vli *ViewListItem) GetIndex() int

GetIndex returns the position in the list.

func (*ViewListItem) GetItem 

func (vli *ViewListItem) GetItem() interface{}

GetItem returns the (possibly wrapped) item reference.

func (*ViewListItem) GetItemObjID 

func (vli *ViewListItem) GetItemObjID() int64

func (*ViewListItem) GetList 

func (vli *ViewListItem) GetList() *ViewList

GetList returns the owning ViewList.

func (*ViewListItem) GetObjID 

func (vli *ViewListItem) GetObjID() int64

func (*ViewListItem) SetIndex 

func (vli *ViewListItem) SetIndex(index int)

SetIndex updates the position (called when list reorders).

type WorkItem 

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

WorkItem represents a unit of work for the executor.

type WorkResult 

type WorkResult struct {
	Value interface{}
	Err   error
}

WorkResult holds the result of a work item.

type WrapperFactory 

type WrapperFactory func(session *LuaSession, variable *TrackerVariableAdapter) interface{}

WrapperFactory creates a new wrapper instance for a variable.

func GetGlobalWrapperFactory 

func GetGlobalWrapperFactory(typeName string) (WrapperFactory, bool)

GetGlobalWrapperFactory retrieves a globally registered wrapper factory.

type WrapperManager 

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

WrapperManager handles wrapper creation for variables.

func NewWrapperManager 

func NewWrapperManager(runtime *Runtime, registry *WrapperRegistry) *WrapperManager

NewWrapperManager creates a new wrapper manager.

func (*WrapperManager) CreateWrapper 

func (m *WrapperManager) CreateWrapper(sessionId string, variable *TrackerVariableAdapter) (interface{}, error)

CreateWrapper creates a new wrapper instance for a variable.

type WrapperRegistry 

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

WrapperRegistry manages registered wrapper types.

func NewWrapperRegistry 

func NewWrapperRegistry() *WrapperRegistry

NewWrapperRegistry creates a new wrapper registry.

func (*WrapperRegistry) Get 

func (r *WrapperRegistry) Get(typeName string) (WrapperFactory, bool)

Get retrieves a wrapper factory by type name.

func (*WrapperRegistry) Register 

func (r *WrapperRegistry) Register(typeName string, factory WrapperFactory)

Register adds a wrapper factory for a type name (instance-specific).

Source Files

View all Source files

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.