pawscript

package module
v0.2.9-alpha-r3 Latest Latest
Warning

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

 Go to latest Published: Dec 18, 2025 License: MIT Imports: 2 Imported by: 0

README

PawScript

PawScript: a command language with token-based suspension suitable for general purpose scripting, but built with application integration in mind.

If you use this, please support me on ko-fi: https://ko-fi.com/jeffday

ko-fi

Features

  • Cross-Platform: Native builds for arm64/x86_64 on macOS, Linux, Windows, plus WebAssembly
  • Module System: Namespaced standard library (core::, io::, os::, math::, str::, channels::, fibers::)
  • Fibers & Channels: Lightweight concurrent execution with channel-based communication
  • Token-Based Suspension: Pause and resume execution for async operations
  • Macro System: Reusable command sequences with lexical scoping and argument substitution
  • Immutable Lists: Copy-on-write semantics with named argument support (key: value)
  • Custom IO Channels: Host apps can provide custom stdin/stdout/stderr handlers
  • Brace Expressions: Inline command evaluation with {...} substitution
  • Thread-Safe: All operations safe for concurrent use
  • Host Integration: Clean API for embedding in applications

Installation

Detailed instructions coming soon.

License

MIT

Contributing

Contributions are welcome! Please ensure:

  1. Code follows Go conventions
  2. All tests pass
  3. New features include tests
  4. Documentation is updated

Architecture

Core components in src/:

  • pawscript.go: Main API and PawScript instance
  • types.go: Core type definitions (StoredList, StoredChannel, StoredMacro, etc.)
  • parser.go: Command parsing with source mapping
  • executor_*.go: Execution engine (core, commands, tokens, resolution, substitution, formatting)
  • state.go: Execution state and variable management
  • module.go: Module environment with copy-on-write semantics
  • macro.go: Macro system with lexical scoping
  • channel.go: Channel implementation for inter-fiber communication
  • fiber.go: Fiber system for concurrent execution

Standard library in src/lib_*.go:

  • lib_core.go: core::, macros::, flow::, debug:: modules
  • lib_math.go: math::, cmp:: modules
  • lib_types.go: strlist::, str:: modules
  • lib_system.go: os::, io::, sys:: modules
  • lib_channels.go: channels:: module
  • lib_fibers.go: fibers:: module

Supporting files:

  • stdlib.go: Library registration and helpers
  • io_channels.go: Native IO channel setup (with custom handler support)
  • os_args.go: Script argument handling
  • logger.go: Logging with position tracking
  • cmd/paw/main.go: CLI tool

Examples

See the examples/ directory for sample scripts and usage patterns.

Changelog

See CHANGELOG.md

Documentation

Overview

Package pawscript provides a scripting language interpreter that can be embedded in Go applications.

This package re-exports the public API from the implementation in src/. For full documentation, see the implementation package.

Basic usage: 

ps := pawscript.New(&pawscript.Config{
	Debug:       false,
	AllowMacros: true,
})
ps.RegisterStandardLibrary(nil)
ps.Execute("echo 'Hello, World!'")

Index

Constants

View Source 
const (
	OptimizeNone  = impl.OptimizeNone
	OptimizeBasic = impl.OptimizeBasic
)

Optimization level constants.

View Source 
const (
	StringStorageThreshold = impl.StringStorageThreshold
	BlockStorageThreshold  = impl.BlockStorageThreshold
)

Storage thresholds.

View Source 
const (
	LevelTrace  = impl.LevelTrace
	LevelInfo   = impl.LevelInfo
	LevelDebug  = impl.LevelDebug
	LevelNotice = impl.LevelNotice
	LevelWarn   = impl.LevelWarn
	LevelError  = impl.LevelError
	LevelFatal  = impl.LevelFatal
)

Log level constants.

View Source 
const (
	CatNone     = impl.CatNone
	CatParse    = impl.CatParse
	CatCommand  = impl.CatCommand
	CatVariable = impl.CatVariable
	CatArgument = impl.CatArgument
	CatIO       = impl.CatIO
	CatNetwork  = impl.CatNetwork
	CatMacro    = impl.CatMacro
	CatAsync    = impl.CatAsync
	CatMemory   = impl.CatMemory
	CatMath     = impl.CatMath
	CatList     = impl.CatList
	CatString   = impl.CatString
	CatType     = impl.CatType
	CatFlow     = impl.CatFlow
	CatSystem   = impl.CatSystem
	CatApp      = impl.CatApp
	CatUser     = impl.CatUser
)

Log category constants.

Variables

This section is empty.

Functions

func ChannelRecv 

func ChannelRecv(ch *StoredChannel) (int, interface{}, error)

ChannelRecv receives a message from a channel.

func CleanupTerminal 

func CleanupTerminal()

CleanupTerminal restores terminal to normal state.

func FormatValueColored 

func FormatValueColored(value interface{}, pretty bool, cfg DisplayColorConfig, ps *PawScript) string

FormatValueColored formats a value with ANSI colors.

func RequestToken 

func RequestToken(ps *PawScript, cleanup func(string), parentToken string, timeout time.Duration) string

RequestToken is a convenience function for creating async tokens. For most use cases, use Context.RequestToken() instead.

func SerializePSL 

func SerializePSL(config PSLMap) string

SerializePSL serializes a map to PSL format.

func SerializePSLList 

func SerializePSLList(list PSLList) string

SerializePSLList serializes a list to PSL format.

func SerializePSLPretty 

func SerializePSLPretty(config PSLMap) string

SerializePSLPretty serializes a map to pretty PSL format.

Types

type ActualUndefined 

type ActualUndefined = impl.ActualUndefined

ActualUndefined represents the undefined value type. Use ActualUndefined{} to create an instance.

type BoolStatus 

type BoolStatus = impl.BoolStatus

BoolStatus is a boolean result from command execution.

type BreakResult 

type BreakResult = impl.BreakResult

BreakResult signals break from a loop.

type BubbleEntry 

type BubbleEntry = impl.BubbleEntry

BubbleEntry is a single bubble for out-of-band values.

type ChannelMessage 

type ChannelMessage = impl.ChannelMessage

ChannelMessage is a message in a channel buffer.

type CommandSequence 

type CommandSequence = impl.CommandSequence

CommandSequence represents suspended command execution.

type Config 

type Config = impl.Config

Config holds configuration options for the interpreter.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a new Config with default values.

type Context 

type Context = impl.Context

Context is passed to command handlers during execution.

type ContinueResult 

type ContinueResult = impl.ContinueResult

ContinueResult signals continue in a loop.

type DisplayColorConfig 

type DisplayColorConfig = impl.DisplayColorConfig

DisplayColorConfig holds display color settings.

func DefaultDisplayColors 

func DefaultDisplayColors() DisplayColorConfig

DefaultDisplayColors returns the default display color configuration.

type EarlyReturn 

type EarlyReturn = impl.EarlyReturn

EarlyReturn signals early termination from a block.

type ExecutionState 

type ExecutionState = impl.ExecutionState

ExecutionState manages result state and variables during execution.

func NewExecutionState 

func NewExecutionState() *ExecutionState

NewExecutionState creates a new execution state.

func NewExecutionStateFrom 

func NewExecutionStateFrom(parent *ExecutionState) *ExecutionState

NewExecutionStateFrom creates a child execution state.

func NewExecutionStateFromSharedVars 

func NewExecutionStateFromSharedVars(parent *ExecutionState) *ExecutionState

NewExecutionStateFromSharedVars creates a state with shared variables.

type FiberHandle 

type FiberHandle = impl.FiberHandle

FiberHandle is a lightweight thread handle.

type FileAccessConfig 

type FileAccessConfig = impl.FileAccessConfig

FileAccessConfig controls file system access permissions.

type Handler 

type Handler = impl.Handler

Handler is the function signature for command handlers.

type IOChannelConfig 

type IOChannelConfig = impl.IOChannelConfig

IOChannelConfig holds configuration for I/O channel setup.

type ItemMetadata 

type ItemMetadata = impl.ItemMetadata

ItemMetadata provides comprehensive metadata tracking.

type Library 

type Library = impl.Library

Library is a collection of module sections.

type ListTypeInfo 

type ListTypeInfo = impl.ListTypeInfo

ListTypeInfo tracks type information for lists.

func NewEmptyTypeInfo 

func NewEmptyTypeInfo() ListTypeInfo

NewEmptyTypeInfo creates empty type info.

type LogCategory 

type LogCategory = impl.LogCategory

LogCategory identifies the logging subsystem.

func AllLogCategories 

func AllLogCategories() []LogCategory

AllLogCategories returns all available log categories.

type LogLevel 

type LogLevel = impl.LogLevel

LogLevel represents log severity.

type MacroContext 

type MacroContext = impl.MacroContext

MacroContext tracks macro invocation chain for debugging.

type MacroDefinition 

type MacroDefinition = impl.MacroDefinition

MacroDefinition holds macro definition data.

type ModuleEnvironment 

type ModuleEnvironment = impl.ModuleEnvironment

ModuleEnvironment manages module state.

func NewChildModuleEnvironment 

func NewChildModuleEnvironment(parent *ModuleEnvironment) *ModuleEnvironment

NewChildModuleEnvironment creates a child module environment.

func NewMacroModuleEnvironment 

func NewMacroModuleEnvironment(parent *ModuleEnvironment) *ModuleEnvironment

NewMacroModuleEnvironment creates a module environment for macros.

func NewModuleEnvironment 

func NewModuleEnvironment() *ModuleEnvironment

NewModuleEnvironment creates a new module environment.

type ModuleItem 

type ModuleItem = impl.ModuleItem

ModuleItem represents an exported item (command, macro, or object).

type ModuleSection 

type ModuleSection = impl.ModuleSection

ModuleSection is a map of items in a module section.

type ObjectRef 

type ObjectRef = impl.ObjectRef

ObjectRef is a reference to a stored object.

type OptimizationLevel 

type OptimizationLevel = impl.OptimizationLevel

OptimizationLevel controls optimization passes.

type OutputContext 

type OutputContext = impl.OutputContext

OutputContext provides logger context.

func NewOutputContext 

func NewOutputContext(state *ExecutionState, executor interface{}) *OutputContext

NewOutputContext creates a new output context.

type PSLConfig 

type PSLConfig = impl.PSLConfig

PSLConfig is an alias for PSLMap.

type PSLList 

type PSLList = impl.PSLList

PSLList is a list for PSL serialization.

func ParsePSLList 

func ParsePSLList(input string) (PSLList, error)

ParsePSLList parses a PSL string into a list.

type PSLMap 

type PSLMap = impl.PSLMap

PSLMap is a map for PSL serialization.

func ParsePSL 

func ParsePSL(input string) (PSLMap, error)

ParsePSL parses a PSL string into a map.

type ParenGroup 

type ParenGroup = impl.ParenGroup

ParenGroup represents a parenthesized value.

type ParsedCommand 

type ParsedCommand = impl.ParsedCommand

ParsedCommand is a parsed command with metadata.

type PawScript 

type PawScript = impl.PawScript

PawScript is the main interpreter instance.

func New 

func New(config *Config) *PawScript

New creates a new PawScript interpreter with the given configuration.

type PawScriptError 

type PawScriptError = impl.PawScriptError

PawScriptError is an error with position information.

type QuotedString 

type QuotedString = impl.QuotedString

QuotedString represents a quoted string value.

type REPL 

type REPL = impl.REPL

REPL is the Read-Eval-Print Loop for interactive sessions.

func NewREPL 

func NewREPL(config REPLConfig, output func(string)) *REPL

NewREPL creates a new REPL with the given configuration.

func NewREPLWithInterpreter 

func NewREPLWithInterpreter(ps *PawScript, output func(string)) *REPL

NewREPLWithInterpreter creates a REPL with an existing interpreter.

type REPLConfig 

type REPLConfig = impl.REPLConfig

REPLConfig holds configuration for the REPL.

type Result 

type Result = impl.Result

Result is the interface returned by command handlers.

type ResumeData 

type ResumeData = impl.ResumeData

ResumeData holds resume information.

type SourcePosition 

type SourcePosition = impl.SourcePosition

SourcePosition tracks location in source code for error reporting.

type StoredBlock 

type StoredBlock = impl.StoredBlock

StoredBlock represents a large code block stored by reference.

type StoredBytes 

type StoredBytes = impl.StoredBytes

StoredBytes is an immutable byte array.

func NewStoredBytes 

func NewStoredBytes(data []byte) StoredBytes

NewStoredBytes creates a new byte array.

func NewStoredBytesFromInts 

func NewStoredBytesFromInts(values []int64) StoredBytes

NewStoredBytesFromInts creates a byte array from int64 values.

func StoredBytesFromString 

func StoredBytesFromString(s string) (StoredBytes, error)

StoredBytesFromString parses a string into a StoredBytes.

type StoredChannel 

type StoredChannel = impl.StoredChannel

StoredChannel is a bidirectional communication channel.

func NewStoredChannel 

func NewStoredChannel(bufferSize int) *StoredChannel

NewStoredChannel creates a new channel with the given buffer size.

type StoredCommand 

type StoredCommand = impl.StoredCommand

StoredCommand wraps a command handler for storage.

func NewStoredCommand 

func NewStoredCommand(name string, handler Handler) StoredCommand

NewStoredCommand creates a new stored command.

type StoredFile 

type StoredFile = impl.StoredFile

StoredFile is an open file handle.

type StoredList 

type StoredList = impl.StoredList

StoredList is an immutable list with optional named arguments.

func NewStoredListWithNamed 

func NewStoredListWithNamed(items []interface{}, namedArgs map[string]interface{}) StoredList

NewStoredListWithNamed creates a list with named arguments.

func NewStoredListWithoutRefs 

func NewStoredListWithoutRefs(items []interface{}) StoredList

NewStoredListWithoutRefs creates a list without reference tracking.

type StoredMacro 

type StoredMacro = impl.StoredMacro

StoredMacro is a macro stored as a reference-counted object.

func NewStoredMacro 

func NewStoredMacro(commands string, position *SourcePosition) StoredMacro

NewStoredMacro creates a new stored macro.

func NewStoredMacroWithEnv 

func NewStoredMacroWithEnv(commands string, position *SourcePosition, moduleEnv *ModuleEnvironment) StoredMacro

NewStoredMacroWithEnv creates a macro with module environment.

type StoredString 

type StoredString = impl.StoredString

StoredString represents a large string stored by reference.

type StoredStruct 

type StoredStruct = impl.StoredStruct

StoredStruct is an instance of a defined struct type.

func NewStoredStruct 

func NewStoredStruct(defID int, size int) StoredStruct

NewStoredStruct creates a new struct instance.

func NewStoredStructArray 

func NewStoredStructArray(defID int, size int, n int) StoredStruct

NewStoredStructArray creates a struct array.

type SuspendResult 

type SuspendResult = impl.SuspendResult

SuspendResult signals suspension of execution.

type Symbol 

type Symbol = impl.Symbol

Symbol represents a bare identifier.

type TerminalCapabilities 

type TerminalCapabilities = impl.TerminalCapabilities

TerminalCapabilities describes terminal features.

type TokenData 

type TokenData = impl.TokenData

TokenData holds information about an active async token.

type TokenResult 

type TokenResult = impl.TokenResult

TokenResult represents an async token for suspended operations.

type YieldResult 

type YieldResult = impl.YieldResult

YieldResult signals yielding from a generator.

Source Files

View all Source files

Directories

Path Synopsis
src
cmd/exec_examples command
cmd/paw command
cmd/pawgui command
pawgui - PawScript with Fyne GUI support A drop-in replacement for paw with additional GUI capabilities
 pawgui - PawScript with Fyne GUI support A drop-in replacement for paw with additional GUI capabilities
cmd/pawgui-gtk command
pawgui-gtk - GTK3-based GUI for PawScript with custom terminal emulator Cross-platform: works on Linux, macOS, and Windows
 pawgui-gtk - GTK3-based GUI for PawScript with custom terminal emulator Cross-platform: works on Linux, macOS, and Windows
cmd/pawgui-qt command
pawgui-qt - Qt-based GUI for PawScript with custom terminal emulator Cross-platform: works on Linux, macOS, and Windows
 pawgui-qt - Qt-based GUI for PawScript with custom terminal emulator Cross-platform: works on Linux, macOS, and Windows
cmd/token_example command
pkg/pawgui
Package pawgui provides shared functionality for PawScript GUI implementations.
 Package pawgui provides shared functionality for PawScript GUI implementations.
pkg/purfecterm
Package purfecterm provides the core terminal emulation logic shared between GUI toolkit implementations (GTK, Qt, etc.).
 Package purfecterm provides the core terminal emulation logic shared between GUI toolkit implementations (GTK, Qt, etc.).
pkg/purfecterm-gtk
pkg/purfecterm-qt
wasm command

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.