sh

README

sh

Package sh provides the integration of the codeberg.org/gonix/gio unix.Filter with the mvdan.cc/sh/v3. This means that the code implementing unix.Filter interface can be executed as a part of a shell script. This has several advantages

• Self-contained: Scripts are not longer required to be installed on a target system.
• Write once and run anywhere: Different tools implementations are irrelevant. Script can use the same tools everywhere.
• Go dependency tracking: Execute the exactly same version of a tool everywhere. Need an another option? Just update your go.mod.
• Experiments: it is possible, though not yet implemented, to combine OpenBSD tool with a Plan 9 and GNU utilities in a single script.

Example

The full example can be found in test/sh_test.go. Keep in mind that mvdan.cc/sh/v3 package implements the full support for shell scripting and not just a pipe.

The following code runs an example which looks a bit strange. All commands are prefixed by gonix/, which is incompatible with a regular shell. However this is not a regular shell. Not a single binary was installed in order for this to work, not a single execve syscall has been called.

FILE=/etc/passwd"
gonix/cat ${FILE} | gonix/wc -l

import (
  "codeberg.org/gonix/gonix/cat"
  "codeberg.org/gonix/gonix/wc"
  "codeberg.org/gonix/sh"

  "mvdan.cc/sh/v3/interp"
  "mvdan.cc/sh/v3/syntax"
)

func main() {
  const SCRIPT = `gonix/cat ${FILE} | gonix/wc -l`

  var cmds = map[string]sh.CommandBuilder{
    "gonix/cat": cat.FromArgs,
    "gonix/wc":  wc.FromArgs,
  }
  c := sh.NewCommands(cmds)

  file, _ := syntax.NewParser().Parse(strings.NewReader(SCRIPT), "")
  runner, _ := interp.New(
    interp.Env(expand.ListEnviron("FILE=/etc/passwd")),
    interp.StdIO(nil, os.Stdout, os.Stderr),
    interp.ExecHandlers(c.ExecHandler),
  )
  // Output
  // 13
}

Documentation

Overview

package sh integrates mvdan.cc/sh/v3 with gio

Index

• func GetDirFunc(ctx context.Context) (string, bool)
• func GetEnvFunc(ctx context.Context) (env iter.Seq2[string, string])
• func LookupEnvFunc(ctx context.Context, name string) (string, bool)
• type Filters
  • func NewFilters(filters unix.FilterLookupFunc, opts ...unix.ShellContextOption) Filters
  • func (f Filters) ExecHandler(next interp.ExecHandlerFunc) interp.ExecHandlerFunc
  • func (f Filters) Lookup(command string) (unix.FilterBuilderFunc, bool)

Functions

func GetDirFunc

func GetDirFunc(ctx context.Context) (string, bool)

GetDirFunc extracts the knowledge about working directory from shell context

func GetEnvFunc

func GetEnvFunc(ctx context.Context) (env iter.Seq2[string, string])

GetEnvFunc iterates through environment of a shell context

func LookupEnvFunc

func LookupEnvFunc(ctx context.Context, name string) (string, bool)

Types

type Filters

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

Filters registers filter by name allowing new commands to be "installed" for a given script

func NewFilters

func NewFilters(filters unix.FilterLookupFunc, opts ...unix.ShellContextOption) Filters

func (Filters) ExecHandler

func (f Filters) ExecHandler(next interp.ExecHandlerFunc) interp.ExecHandlerFunc

ExecHandler is an argument for interp.ExecHandlers of mvdan.cc/sh/v3/interp This executes all registered filters via unix.Pipe interface

func (Filters) Lookup

func (f Filters) Lookup(command string) (unix.FilterBuilderFunc, bool)