risor

README

Risor

Risor is a fast and flexible scripting language for Go developers and DevOps.

Its modules integrate the Go standard library, making it easy to use functions that you're already familiar with as a Go developer.

Scripts are compiled to bytecode and then run on a lightweight virtual machine. Risor is written in pure Go.

Documentation

Documentation is available at risor.io.

You might also want to try evaluating Risor scripts from your browser.

Syntax Example

Here's a short example of how Risor feels like a hybrid of Go and Python. This demonstrates using Risor's pipe expressions to apply a series of transformations:

array := ["gophers", "are", "burrowing", "rodents"]

sentence := array | strings.join(" ") | strings.to_upper

print(sentence)

Output:

GOPHERS ARE BURROWING RODENTS

Getting Started

You might want to head over to Getting Started in the documentation. That said, here are tips for both the CLI and the Go library.

Risor CLI and REPL

If you use Homebrew, you can install the Risor CLI as follows:

brew install risor

Having done that, just run risor to start the CLI or risor -h to see usage information.

Execute a code snippet directly using the -c option:

risor -c "time.now()"

Start the REPL by running risor with no options.

Build and Install the CLI from Source

Build the CLI from source as follows:

git clone git@github.com:risor-io/risor.git
cd risor/cmd/risor
go install -tags aws,k8s,semver,vault .

Go Library

Use go get to add Risor as a dependency of your Go program:

go get github.com/AMuzykus/risor@v1.7.0

Here's an example of using the risor.Eval API to evaluate some code:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/AMuzykus/risor"
)

func main() {
	ctx := context.Background()
	script := "math.sqrt(input)"
	result, err := risor.Eval(ctx, script, risor.WithGlobal("input", 4))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("The square root of 4 is:", result)
}

Built-in Functions and Modules

30+ built-in functions are included and are documented here.

Modules are included that generally wrap the equivalent Go package. For example, there is direct correspondence between base64, bytes, filepath, json, math, os, rand, regexp, strconv, strings, and time Risor modules and the Go standard library.

Risor modules that are beyond the Go standard library currently include aws, pgx, uuid, vault, and k8s.

Go Interface

It is trivial to embed Risor in your Go program in order to evaluate scripts that have access to arbitrary Go structs and other types.

The simplest way to use Risor is to call the Eval function and provide the script source code. The result is returned as a Risor object:

result, err := risor.Eval(ctx, "math.min([5, 2, 7])")
// result is 2, as an *object.Int

Provide input to the script using Risor options:

result, err := risor.Eval(ctx, "input | strings.to_upper", risor.WithGlobal("input", "hello"))
// result is "HELLO", as an *object.String

Use the same mechanism to inject a struct. You can then access fields or call methods on the struct from the Risor script:

type Example struct {
    Message string
}
example := &Example{"abc"}
result, err := risor.Eval(ctx, "len(ex.Message)", risor.WithGlobal("ex", example))
// result is 3, as an *object.Int

Dependencies and Build Options

Risor is designed to have minimal external dependencies in its core libraries. You can choose to opt into various add-on modules if they are of value in your application. The modules are present in this same Git repository, but must be installed with go get as separate dependencies:

Name	Path	Go Get Command
aws	modules/aws	go get github.com/AMuzykus/risor/modules/aws@v1.7.0
bcrypt	modules/bcrypt	go get github.com/AMuzykus/risor/modules/bcrypt@v1.7.0
carbon	modules/carbon	go get github.com/AMuzykus/risor/modules/carbon@v1.7.0
cli	modules/cli	go get github.com/AMuzykus/risor/modules/cli@v1.7.0
image	modules/image	go get github.com/AMuzykus/risor/modules/image@v1.7.0
jmespath	modules/jmespath	go get github.com/AMuzykus/risor/modules/jmespath@v1.7.0
k8s	modules/kubernetes	go get github.com/AMuzykus/risor/modules/kubernetes@v1.7.0
pgx	modules/pgx	go get github.com/AMuzykus/risor/modules/pgx@v1.7.0
s3fs	os/s3fs	go get github.com/AMuzykus/risor/os/s3fs@v1.7.0
semver	modules/semver	go get github.com/AMuzykus/risor/modules/semver@v1.7.0
sql	modules/sql	go get github.com/AMuzykus/risor/modules/sql@v1.7.0
template	modules/template	go get github.com/AMuzykus/risor/modules/template@v1.7.0
uuid	modules/uuid	go get github.com/AMuzykus/risor/modules/uuid@v1.7.0
vault	modules/vault	go get github.com/AMuzykus/risor/modules/vault@v1.7.0

These add-ons are included by default when using the Risor CLI. However, when building Risor into your own program, you'll need to opt-in using go get as described above and then add the modules as globals in Risor scripts as follows:

import (
    "github.com/AMuzykus/risor"
    "github.com/AMuzykus/risor/modules/aws"
    "github.com/AMuzykus/risor/modules/image"
    "github.com/AMuzykus/risor/modules/pgx"
    "github.com/AMuzykus/risor/modules/uuid"
)

func main() {
    source := `"nice modules!"`
    result, err := risor.Eval(ctx, source,
        risor.WithGlobals(map[string]any{
            "aws":   aws.Module(),
            "image": image.Module(),
            "pgx":   pgx.Module(),
            "uuid":  uuid.Module(),
        }))
    // ...
}

Syntax Highlighting

A Risor VSCode extension is already available which currently only offers syntax highlighting.

You can also make use of the Risor TextMate grammar.

Benchmarking

There are two Makefile commands that assist with benchmarking and CPU profiling:

make bench
make pprof

Contributing

Risor is intended to be a community project. You can lend a hand in various ways:

• Please ask questions and share ideas in GitHub discussions
• Share Risor on any social channels that may appreciate it
• Open GitHub issue or a pull request for any bugs you find
• Star the project on GitHub

Contributing New Modules

Adding modules to Risor is a great way to get involved with the project. See this guide for details.

Community Projects

• RSX: Package Risor Scripts into Go Binaries
• Awesome Risor
• tree-sitter-risor
• bench_go_scripting

Discuss the Project

Please visit the GitHub discussions page to share thoughts and questions.

There is also a #risor Slack channel on the Gophers Slack.

Credits

Check CREDITS.md.

License

Released under the Apache License, Version 2.0.

Copyright Curtis Myzie / github.com/myzie.

Documentation

Index

• func Call(ctx context.Context, main *compiler.Code, functionName string, ...) (object.Object, error)
• func Eval(ctx context.Context, source string, options ...Option) (object.Object, error)
• func EvalCode(ctx context.Context, main *compiler.Code, options ...Option) (object.Object, error)
• type Config
  • func NewConfig(opts ...Option) *Config
  • func (cfg *Config) CombinedGlobals() map[string]any
  • func (cfg *Config) CompilerOpts() []compiler.Option
  • func (cfg *Config) GlobalNames() []string
  • func (cfg *Config) Globals() map[string]any
  • func (cfg *Config) VMOpts() []vm.Option
• type Option
  • func WithConcurrency() Option
  • func WithGlobal(name string, value any) Option
  • func WithGlobalOverride(name string, value any) Option
  • func WithGlobals(globals map[string]any) Option
  • func WithImporter(i importer.Importer) Option
  • func WithListenersAllowed() Option
  • func WithLocalImporter(paths []string) Option
  • func WithoutDefaultGlobals() Option
  • func WithoutGlobal(name string) Option
  • func WithoutGlobals(names ...string) Option

Functions

func Call

func Call(
	ctx context.Context,
	main *compiler.Code,
	functionName string,
	args []object.Object,
	options ...Option,
) (object.Object, error)

Call evaluates the precompiled code and then calls the named function. The supplied arguments are passed in the function call. The result of the function call is returned.

func Eval

func Eval(ctx context.Context, source string, options ...Option) (object.Object, error)

Eval evaluates the given source code and returns the result.

func EvalCode

func EvalCode(ctx context.Context, main *compiler.Code, options ...Option) (object.Object, error)

EvalCode evaluates the precompiled code and returns the result.

Types

type Config

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

Config assists in configuring Risor evaluations.

func NewConfig

func NewConfig(opts ...Option) *Config

NewConfig returns a new Risor Config. Use the Risor options functions to customize the configuration.

func (*Config) CombinedGlobals

func (cfg *Config) CombinedGlobals() map[string]any

CombinedGlobals returns a map of all global variables that should be available in a Risor evaluation.

Deprecated: Use Globals instead.

func (*Config) CompilerOpts

func (cfg *Config) CompilerOpts() []compiler.Option

CompilerOpts returns compiler options derived from this configuration.

func (*Config) GlobalNames

func (cfg *Config) GlobalNames() []string

GlobalNames returns a list of all global variables names that should be available in a Risor evaluation.

func (*Config) Globals

func (cfg *Config) Globals() map[string]any

Globals returns a map of all global variables that should be available in a Risor evaluation.

func (*Config) VMOpts

func (cfg *Config) VMOpts() []vm.Option

VMOpts returns virtual machine options derived from this configuration.

type Option

type Option func(*Config)

Option describes a function used to configure a Risor evaluation.

func WithConcurrency

func WithConcurrency() Option

WithConcurrency enables the use of concurrency in Risor evaluations.

func WithGlobal

func WithGlobal(name string, value any) Option

WithGlobal supplies a single named global variable to the Risor evaluation.

func WithGlobalOverride

func WithGlobalOverride(name string, value any) Option

WithGlobalOverride replaces the a global or module builtin with the given value

func WithGlobals

func WithGlobals(globals map[string]any) Option

WithGlobals provides global variables that are made available to Risor evaluations. This option is additive, so multiple WithGlobals options may be supplied. If the same key is supplied multiple times, the last supplied value is used.

func WithImporter

func WithImporter(i importer.Importer) Option

WithImporter supplies an Importer that will be used to execute import statements.

func WithListenersAllowed

func WithListenersAllowed() Option

WithListenersAllowed allows opening sockets for listening.

func WithLocalImporter

func WithLocalImporter(paths []string) Option

WithLocalImporter enables importing Risor modules from the given directory.

func WithoutDefaultGlobals

func WithoutDefaultGlobals() Option

WithoutDefaultGlobals opts out of all default global builtins and modules.

func WithoutGlobal

func WithoutGlobal(name string) Option

WithoutGlobal opts out of a given global builtin or module. If the name can't be resolved, this is a no-op. This does operate on nested modules.

func WithoutGlobals

func WithoutGlobals(names ...string) Option

WithoutGlobals removes multiple global builtins or modules.