README
¶
GS (Go Script)
GS (Go Script) is a lightweight, high-performance, embeddable scripting language for Go, built around expression-oriented programming and consistent language design principles. Its feature set, including arrow-function lambdas, data-type member functions, and fluent chaining, enables transformation-heavy code to be written as clear expressions instead of loop-and-branch boilerplate. It runs on a bytecode VM implemented in Go, making embedding and sandboxing straightforward in Go services and tools.
Quick Start
Install the cli with Go's toolchain:
go install github.com/jokruger/gs/cmd/gs@latest
Then you can run GS scripts with the gs command or using hashbang:
#!/usr/bin/env gs
fmt := import("fmt")
fmt.println("Hello", "GS")
Documentation
TODO
Contributing
Before contributing, please review docs/project.md and docs/conventions.md for project layout, coding standards and repository contracts.
- Fork the repository and clone your fork locally.
- Make your changes in a focused branch.
- Run the test suite.
- Add or update tests in
tests/unitfor any change that affects language or runtime behavior. - Open a pull request describing the motivation for the change and any new or changed semantics.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Acknowledgements
This project is based on script language Tengo by Daniel Kang. A special thanks to Tengo's creator and contributors.
Documentation
¶
Index ¶
- Constants
- func Eval(ctx context.Context, alloc core.Allocator, expr string, ...) (any, error)
- type Compiled
- func (c *Compiled) Clone() *Compiled
- func (c *Compiled) Get(name string) *Variable
- func (c *Compiled) GetAll() []*Variable
- func (c *Compiled) IsDefined(name string) bool
- func (c *Compiled) Run() error
- func (c *Compiled) RunContext(ctx context.Context) (err error)
- func (c *Compiled) Set(name string, val core.Value) error
- func (c *Compiled) Size() int64
- type Compiler
- type CompilerError
- type Script
- func (s *Script) Add(name string, val core.Value)
- func (s *Script) Compile() (*Compiled, error)
- func (s *Script) EnableFileImport(enable bool)
- func (s *Script) Remove(name string) bool
- func (s *Script) Run() (compiled *Compiled, err error)
- func (s *Script) RunContext(ctx context.Context) (compiled *Compiled, err error)
- func (s *Script) SetImportDir(dir string) error
- func (s *Script) SetImports(modules vm.ModuleGetter)
- func (s *Script) SetMaxAllocs(n int64)
- func (s *Script) SetMaxConstObjects(n int)
- type Variable
- func (v *Variable) Array() []any
- func (v *Variable) Bool() bool
- func (v *Variable) Bytes() []byte
- func (v *Variable) Char() rune
- func (v *Variable) Error() error
- func (v *Variable) Float() float64
- func (v *Variable) Int() int64
- func (v *Variable) IsUndefined() bool
- func (v *Variable) Map() map[string]any
- func (v *Variable) Name() string
- func (v *Variable) Object() core.Value
- func (v *Variable) String() string
- func (v *Variable) Time() time.Time
- func (v *Variable) Value() core.Value
- func (v *Variable) ValueType() string
Constants ¶
const (
// SourceFileExtDefault is the default extension for source files.
SourceFileExtDefault = ".gs"
)
Variables ¶
This section is empty.
Functions ¶
func Eval ¶
func Eval(ctx context.Context, alloc core.Allocator, expr string, params map[string]core.Value) (any, error)
Eval compiles and executes given expr with params, and returns an evaluated value. Argument `expr` must be an expression. Otherwise it will fail to compile. Expression must not use or define variable "__res__" as it's reserved for the internal usage.
Types ¶
type Compiled ¶
type Compiled struct {
// contains filtered or unexported fields
}
Compiled is a compiled instance of the user script. Use Script.Compile() to create Compiled object.
func (*Compiled) Clone ¶
Clone creates a new copy of Compiled. Cloned copies are safe for concurrent use by multiple goroutines.
func (*Compiled) IsDefined ¶
IsDefined returns true if the variable name is defined (has value) before or after the execution.
func (*Compiled) RunContext ¶
RunContext is like Run but includes a context.
type Compiler ¶
type Compiler struct {
// contains filtered or unexported fields
}
Compiler compiles the AST into a bytecode.
func NewCompiler ¶
func NewCompiler( alloc core.Allocator, file *parser.SourceFile, symbolTable *vm.SymbolTable, constants []core.Value, modules vm.ModuleGetter, trace io.Writer, ) *Compiler
NewCompiler creates a Compiler.
func (*Compiler) EnableFileImport ¶
EnableFileImport enables or disables module loading from local files. Local file modules are disabled by default.
func (*Compiler) GetImportFileExt ¶
GetImportFileExt returns the current list of extension name. These are the complementary suffix of the source file to search and load local module files.
func (*Compiler) SetImportDir ¶
SetImportDir sets the initial import directory path for file imports.
func (*Compiler) SetImportFileExt ¶
SetImportFileExt sets the extension name of the source file for loading local module files. Use this method if you want other source file extension than ".gs". This function requires at least one argument, since it will replace the current list of extension name.
type CompilerError ¶
type CompilerError struct {
FileSet *parser.SourceFileSet
Node parser.Node
Err error
}
CompilerError represents a compiler error.
func (*CompilerError) Error ¶
func (e *CompilerError) Error() string
type Script ¶
type Script struct {
// contains filtered or unexported fields
}
Script can simplify compilation and execution of embedded scripts.
func (*Script) Compile ¶
Compile compiles the script with all the defined variables, and, returns Compiled object.
func (*Script) EnableFileImport ¶
EnableFileImport enables or disables module loading from local files. Local file modules are disabled by default.
func (*Script) Remove ¶
Remove removes (undefine) an existing variable for the script. It returns false if the variable name is not defined.
func (*Script) Run ¶
Run compiles and runs the scripts. Use returned compiled object to access global variables.
func (*Script) RunContext ¶
RunContext is like Run but includes a context.
func (*Script) SetImportDir ¶
SetImportDir sets the initial import directory for script files.
func (*Script) SetImports ¶
func (s *Script) SetImports(modules vm.ModuleGetter)
SetImports sets import modules.
func (*Script) SetMaxAllocs ¶
SetMaxAllocs sets the maximum number of objects allocations during the run time. Compiled script will return gse.ErrObjectAllocLimit error if it exceeds this limit.
func (*Script) SetMaxConstObjects ¶
SetMaxConstObjects sets the maximum number of objects in the compiled constants.
type Variable ¶
type Variable struct {
// contains filtered or unexported fields
}
Variable is a user-defined variable for the script.
func NewVariable ¶
NewVariable creates a Variable.
func (*Variable) Array ¶
Array returns []interface value of the variable value. It returns 0 if the value is not convertible to []interface.
func (*Variable) Bool ¶
Bool returns bool value of the variable value. It returns 0 if the value is not convertible to bool.
func (*Variable) Bytes ¶
Bytes returns a byte slice of the variable value. It returns nil if the value is not convertible to byte slice.
func (*Variable) Char ¶
Char returns rune value of the variable value. It returns 0 if the value is not convertible to rune.
func (*Variable) Error ¶
Error returns an error if the underlying value is error object. If not, this returns nil.
func (*Variable) Float ¶
Float returns float64 value of the variable value. It returns 0.0 if the value is not convertible to float64.
func (*Variable) Int ¶
Int returns int64 value of the variable value. It returns 0 if the value is not convertible to int64.
func (*Variable) IsUndefined ¶
IsUndefined returns true if the underlying value is undefined.
func (*Variable) Map ¶
Map returns map[string]any value of the variable value. It returns 0 if the value is not convertible to map[string]any.
func (*Variable) Object ¶
Object returns an underlying Object of the variable value. Note that returned Object is a copy of an actual Object used in the script.
func (*Variable) String ¶
String returns string value of the variable value. It returns 0 if the value is not convertible to string.
func (*Variable) Time ¶
Time returns time.Time value of the variable value. It returns zero time if the value is not convertible to time.Time.
Source Files
Directories