lang

package
v0.0.0-...-e081c89 Latest Latest
Warning

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

Go to latest
Published: Feb 17, 2024 License: GPL-2.0 Imports: 46 Imported by: 0

Documentation

Overview

Package lang provides the parser for the murex shell scripting language

Index

Constants

View Source
const (
	NoParsingErrors = 0 + iota
	ErrPipingToNothing
	ErrUnknownParserErrorPipe
	ErrUnableToParseParametersInRunmode
	ErrInvalidParametersInRunmode
)

murex script parsing error codes:

View Source
const (
	// F_DEFAULTS is forking with within the existing function
	F_DEFAULTS = 0

	// F_NEW_MODULE will skip the stage of inheriting the module name from the
	// calling function. You will still then need to specify that module name
	// yourself. eg
	//
	//     fork := p.Fork(F_SHELL|F_NEW_MODULE)
	//     fork.Module = "package/module"
	//     exitNum, err := fork.Execute([]rune{})
	F_NEW_MODULE = 1 << iota

	// F_FUNCTION will assign a bunch of sane default properties for a function
	// call
	F_FUNCTION

	// F_PARENT_VARTABLE will bypass the automatic forking of the var table.
	// The plan is to make this the default because it's what you'd expect to
	// use inside builtins
	F_PARENT_VARTABLE

	// F_NEW_VARTABLE will fork the variable table (not needed when using
	// F_FUNCTION)
	// For reasons I haven't got to the bottom of yet, this is rather glitchy
	// inside builtins.
	F_NEW_VARTABLE

	// F_NEW_CONFIG will fork the config table - eg when calling a new function
	// (not needed when calling F_FUNCTION)
	F_NEW_CONFIG

	// F_NEW_TESTS will start a new scope for the testing framework (not needed
	// when calling F_FUNCTION)
	F_NEW_TESTS

	// F_BACKGROUND this process will run in the background
	F_BACKGROUND

	// F_CREATE_STDIN will create a new stdin stdio.Io interface
	F_CREATE_STDIN

	// F_CREATE_STDOUT will create a new stdout stdio.Io interface
	F_CREATE_STDOUT

	// F_CREATE_STDERR will create a new stderr stdio.Io interface
	F_CREATE_STDERR

	// F_NO_STDIN will ensure stdin will be a nil interface
	F_NO_STDIN

	// F_NO_STDOUT will ensure stdout will be a nil interface
	F_NO_STDOUT

	// F_NO_STDERR will ensure stderr will be a nil interface
	F_NO_STDERR

	// F_PREVIEW
	F_PREVIEW
)
View Source
const (
	// UnitTestAutocomplete is the pseudo-module name for autocomplete blocks
	UnitTestAutocomplete = "(autocomplete)"

	// UnitTestOpen is the pseudo-module name for open handler blocks
	UnitTestOpen = "(open)"

	// UnitTestEvent is the pseudo-module name for event blocks
	UnitTestEvent = "(event)"
)
View Source
const (
	DOT        = ""
	SELF       = "SELF"
	ARGV       = "ARGV"
	ARGS       = "ARGS"
	PARAMS     = "PARAMS"
	MUREX_EXE  = "MUREX_EXE"
	MUREX_ARGS = "MUREX_ARGS"
	MUREX_ARGV = "MUREX_ARGV"
	HOSTNAME   = "HOSTNAME"
	PWD        = "PWD"
	ENV        = "ENV"
	GLOBAL     = "GLOBAL"
	MODULE     = "MOD"
	COLUMNS    = "COLUMNS"
)

Reserved variable names. Set as constants so any typos of these names within the code will be raised as compiler errors

View Source
const ErrDoesNotExist = "does not exist"
View Source
const ExpressionFunctionName = "expr"
View Source
const ForkSuffix = " (fork)"

Variables

View Source
var (
	// ReadIndexes defines the Go functions for the `[ Index ]` murex function
	ReadIndexes = make(map[string]func(*Process, []string) error)

	// ReadNotIndexes defines the Go functions for the `![ Index ]` murex function
	ReadNotIndexes = make(map[string]func(*Process, []string) error)

	// Unmarshallers defines the Go functions for converting a murex data type into a Go interface
	Unmarshallers = make(map[string]func(*Process) (interface{}, error))

	// Marshallers defines the Go functions for converting a Go interface into a murex data type
	Marshallers = make(map[string]func(*Process, interface{}) ([]byte, error))

	MxInterfaces = make(map[string]MxInterface)
)
View Source
var (
	ProfCpuCleanUp func() = func() {}
	ProfMemCleanUp func() = func() {}
)
View Source
var (
	ShowPrompt = make(chan bool, 1)
	HidePrompt = make(chan bool, 1)

	ModuleRunModes map[string]runmode.RunMode = make(map[string]runmode.RunMode)
)
View Source
var (
	// FlagTry is true if murex was started with `--try`
	FlagTry bool

	// FlagTryPipe is true if murex was started with `--trypipe`
	FlagTryPipe bool

	// FlagTryErr is true if murex was started with `--tryerr`
	FlagTryErr bool

	// FlagTryPipeErr is true if murex was started with `--trypipeerr`
	FlagTryPipeErr bool
)
View Source
var (
	// Interactive describes whether murex is running as an interactive shell or not
	Interactive bool

	// ShellProcess is the root murex process
	ShellProcess = &Process{}

	// MxFunctions is a table of global murex functions
	MxFunctions = NewMurexFuncs()

	// PrivateFunctions is a table of private murex functions
	PrivateFunctions = NewMurexPrivs()

	// GoFunctions is a table of available builtin functions
	GoFunctions = make(map[string]func(*Process) error)

	// MethodStdin is a table of all the different commands that can be used as methods
	MethodStdin = newMethods()

	// MethodStdout is a table of all the different output formats supported by a given command (by default)
	MethodStdout = newMethods()

	// GlobalVariables is a table of global variables
	GlobalVariables = NewGlobals()

	// ModuleVariables is a table of module specific variables
	ModuleVariables = NewModuleVars()

	// GlobalAliases is a table of global aliases
	GlobalAliases = NewAliases()

	// GlobalPipes is a table of  named pipes
	GlobalPipes = pipes.NewNamed()

	// GlobalFIDs is a table of running murex processes
	GlobalFIDs = *newFuncID()

	// GlobalUnitTests is a class for all things murex unit tests
	GlobalUnitTests = new(UnitTests)

	// ForegroundProc is the murex FID which currently has "focus"
	ForegroundProc = newForegroundProc()

	// ShellExitNum is for when running murex in interactive shell mode
	ShellExitNum int
)
View Source
var ParseBlock func(block []rune) (*[]functions.FunctionT, error)
View Source
var ParseExpression func([]rune, int, bool) (int, error)
View Source
var ParseStatementParameters func([]rune, *Process) (string, []string, error)

Functions

func ArrayTemplate

func ArrayTemplate(ctx context.Context, marshal func(interface{}) ([]byte, error), unmarshal func([]byte, interface{}) error, read stdio.Io, callback func([]byte)) error

ArrayTemplate is a template function for reading arrays from marshalled data

func ArrayWithTypeTemplate

func ArrayWithTypeTemplate(ctx context.Context, dataType string, marshal func(interface{}) ([]byte, error), unmarshal func([]byte, interface{}) error, read stdio.Io, callback func(interface{}, string)) error

ArrayWithTypeTemplate is a template function for reading arrays from marshalled data

func DefineFunction

func DefineFunction(name string, fn func(*Process) error, StdoutDataType string)

func DefineMethod

func DefineMethod(name string, fn func(*Process) error, StdinDataType, StdoutDataType string)

func Deprecated

func Deprecated(p *Process)

func DumpIndex

func DumpIndex() (dump []string)

DumpIndex returns an array of compiled builtins supporting deserialization by index

func DumpMarshaller

func DumpMarshaller() (dump []string)

DumpMarshaller returns an array of compiled builtins supporting marshalling

func DumpNotIndex

func DumpNotIndex() (dump []string)

DumpNotIndex returns an array of compiled builtins supporting deserialization by !index

func DumpUnmarshaller

func DumpUnmarshaller() (dump []string)

DumpUnmarshaller returns an array of compiled builtins supporting unmarshalling

func DumpVariables

func DumpVariables(p *Process) map[string]interface{}

DumpVariables returns a map of the variables and values for all variables in scope.

func ElementLookup

func ElementLookup(v interface{}, path string) (interface{}, error)

func ErrPrivateNotFound

func ErrPrivateNotFound(module string) error

func Exit

func Exit(exitNum int)

func External

func External(p *Process) error

External executes an external process.

func GetExtType

func GetExtType(extension string) (dt string)

GetExtType gets the murex data type for a corresponding file extension

func GetFileExts

func GetFileExts() map[string]string

GetFileExts returns the file extension lookup table

func GetMimes

func GetMimes() map[string]string

GetMimes returns MIME lookup table

func IndexTemplateObject

func IndexTemplateObject(p *Process, params []string, object *interface{}, marshaller func(interface{}) ([]byte, error)) error

IndexTemplateObject is a handy standard indexer you can use in your custom data types for structured object types. The point of this is to minimize code rewriting and standardising the behavior of the indexer.

func IndexTemplateTable

func IndexTemplateTable(p *Process, params []string, cRecords chan []string, marshaller func([]string) []byte) error

IndexTemplateTable is a handy standard indexer you can use in your custom data types for tabulated / streamed data. The point of this is to minimize code rewriting and standardising the behavior of the indexer.

func InitEnv

func InitEnv()

InitEnv initialises murex. Exported function to enable unit tests.

func MapTemplate

func MapTemplate(dataType string, marshal func(interface{}) ([]byte, error), unmarshal func([]byte, interface{}) error, read stdio.Io, callback func(*stdio.Map)) error

func MarshalData

func MarshalData(p *Process, dataType string, data interface{}) (b []byte, err error)

MarshalData is a global marshaller which should be called from within murex builtin commands (etc). See docs/apis/marshaldata.md for more details

func MimeToMurex

func MimeToMurex(mimeType string) string

MimeToMurex gets the murex data type for a corresponding MIME

func NewMurexPrivs

func NewMurexPrivs() *privateFunctions

func PreviewInit

func PreviewInit()

func ReadFileExtensions

func ReadFileExtensions() (interface{}, error)

ReadFileExtensions returns an interface{} of fileExts. This is only intended to be used by `config.Properties.GoFunc.Read()`

func ReadMimes

func ReadMimes() (interface{}, error)

ReadMimes returns an interface{} of mimes. This is only intended to be used by `config.Properties.GoFunc.Read()`

func SetFileExtensions

func SetFileExtensions(dt string, extension ...string)

SetFileExtensions defines file extension(s) and assign it a murex data type

func SetMime

func SetMime(dt string, mime ...string)

SetMime defines MIME(s) and assign it a murex data type

func UnmarshalData

func UnmarshalData(p *Process, dataType string) (v interface{}, err error)

UnmarshalData is a global unmarshaller which should be called from within murex builtin commands (etc). See docs/apis/marshaldata.md for more details

func UnmarshalDataBuffered

func UnmarshalDataBuffered(parent *Process, b []byte, dataType string) (interface{}, error)

func WriteFileExtensions

func WriteFileExtensions(v interface{}) error

WriteFileExtensions takes a JSON-encoded string and writes it to the fileExts map. This is only intended to be used by `config.Properties.GoFunc.Write()`

func WriteMimes

func WriteMimes(v interface{}) error

WriteMimes takes a JSON-encoded string and writes it to the mimes map. This is only intended to be used by `config.Properties.GoFunc.Write()`

Types

type Alias

type Alias struct {
	Alias   []string
	FileRef *ref.File
}

type Aliases

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

Aliases is a table of aliases

func NewAliases

func NewAliases() (a Aliases)

NewAliases creates a new table of aliases

func (*Aliases) Add

func (a *Aliases) Add(name string, alias []string, fileRef *ref.File)

Add creates an alias

func (*Aliases) Delete

func (a *Aliases) Delete(name string) error

Delete an alias

func (*Aliases) Dump

func (a *Aliases) Dump() map[string]Alias

Dump returns the complete alias table

func (*Aliases) Exists

func (a *Aliases) Exists(name string) (exists bool)

Exists checks if alias exists in table

func (*Aliases) Get

func (a *Aliases) Get(name string) []string

Get the aliased code

func (*Aliases) UpdateMap

func (a *Aliases) UpdateMap(m map[string]bool)

UpdateMap is used for auto-completions. It takes an existing map and updates it's values rather than copying data

type Fork

type Fork struct {
	*Process
	// contains filtered or unexported fields
}

Fork is a forked process

func (*Fork) Execute

func (fork *Fork) Execute(block []rune) (exitNum int, err error)

Execute will run a murex code block

type ForkManagement

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

func NewForkManagement

func NewForkManagement() *ForkManagement

func (*ForkManagement) GetForks

func (fm *ForkManagement) GetForks() []*[]Process

type ModuleVars

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

func NewModuleVars

func NewModuleVars() *ModuleVars

func (*ModuleVars) GetDataType

func (mod *ModuleVars) GetDataType(p *Process, name string) (dt string)

func (*ModuleVars) GetValues

func (mod *ModuleVars) GetValues(p *Process) interface{}

func (*ModuleVars) Set

func (mod *ModuleVars) Set(p *Process, value interface{}, changePath []string, dataType string) (err error)

type MurexFuncs

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

MurexFuncs is a table of murex functions

func NewMurexFuncs

func NewMurexFuncs() *MurexFuncs

NewMurexFuncs creates a new table of murex functions

func (*MurexFuncs) Block

func (mf *MurexFuncs) Block(name string) ([]rune, error)

Block returns function code

func (*MurexFuncs) Define

func (mf *MurexFuncs) Define(name string, parameters []MxFunctionParams, block []rune, fileRef *ref.File)

Define creates a function

func (*MurexFuncs) Dump

func (mf *MurexFuncs) Dump() interface{}

Dump list all murex functions in table

func (*MurexFuncs) Exists

func (mf *MurexFuncs) Exists(name string) bool

Exists checks if function already created

func (*MurexFuncs) Summary

func (mf *MurexFuncs) Summary(name string) (string, error)

Summary returns functions summary

func (*MurexFuncs) Undefine

func (mf *MurexFuncs) Undefine(name string) error

Undefine deletes function from table

func (*MurexFuncs) UpdateMap

func (mf *MurexFuncs) UpdateMap(m map[string]bool)

UpdateMap is used for auto-completions. It takes an existing map and updates it's values rather than copying data

type MxFunctionParams

type MxFunctionParams struct {
	Name        string
	DataType    string
	Description string
	Default     string
}

func ParseMxFunctionParameters

func ParseMxFunctionParameters(parameters string) ([]MxFunctionParams, error)

Parse the function parameter and data type block

type MxInterface

type MxInterface interface {
	GetValue() interface{}
	GetString() string
	Set(interface{}, []string) error
	New(string) (MxInterface, error)
}

type ParserError

type ParserError struct {
	Message string
	Code    int
	EndByte int // this is sometimes useful to know
}

ParserError is the error object used for the murex parser

type Process

type Process struct {
	Id uint32

	Name       process.Name
	Parameters parameters.Parameters

	Context context.Context
	Stdin   stdio.Io
	Stdout  stdio.Io

	Stderr             stdio.Io
	ExitNum            int
	Forks              *ForkManagement
	WaitForTermination chan bool `json:"-"`
	WaitForStopped     chan bool `json:"-"`
	HasStopped         chan bool `json:"-"`
	Done               func()    `json:"-"`
	Kill               func()    `json:"-"`
	Exec               process.Exec
	Scope              *Process `json:"-"`
	Parent             *Process `json:"-"`
	Previous           *Process `json:"-"`
	Next               *Process `json:"-"`
	IsNot              bool
	IsMethod           bool
	OperatorLogicAnd   bool
	OperatorLogicOr    bool
	NamedPipeOut       string
	NamedPipeErr       string
	NamedPipeTest      string

	State      state.State
	Background process.Background
	RunMode    runmode.RunMode
	Config     *config.Config
	Tests      *Tests

	Variables    *Variables
	CreationTime time.Time
	StartTime    time.Time
	FileRef      *ref.File
	CCEvent      func(string, *Process) `json:"-"`
	CCExists     func(string) bool      `json:"-"`
	CCOut        *streams.Stdin         `json:"-"`
	CCErr        *streams.Stdin         `json:"-"`
	// contains filtered or unexported fields
}

Process - Each process running inside the murex shell will be one of these objects. It is equivalent to the /proc directory on Linux, albeit queried through murex as JSON. External processes will also appear in the host OS's process list.

func NewTestProcess

func NewTestProcess() (p *Process)

NewTestProcess creates a dummy process for testing in Go (ie `go test`)

func (*Process) Args

func (p *Process) Args() (string, []string)

Args returns a normalised function name and parameters

func (*Process) Dump

func (p *Process) Dump() interface{}

func (*Process) ErrIfNotAMethod

func (p *Process) ErrIfNotAMethod() error

ErrIfNotAMethod returns a standard error message for builtins not run as methods

func (*Process) Fork

func (p *Process) Fork(flags int) *Fork

Fork will create a new handle for executing a code block

func (*Process) HasCancelled

func (p *Process) HasCancelled() bool

HasCancelled is a wrapper function around context because it's a pretty ugly API

func (*Process) HasTerminated

func (p *Process) HasTerminated() (state bool)

HasTerminated checks if process has terminated. This is a function because terminated state can be subject to race conditions so we need a mutex to make the state thread safe.

func (*Process) KillForks

func (p *Process) KillForks(exitNum int)

func (*Process) SetTerminatedState

func (p *Process) SetTerminatedState(state bool)

SetTerminatedState sets the process terminated state. This is a function because terminated state can be subject to race conditions so we need a mutex to make the state thread safe.

type TestChecks

type TestChecks struct {
	Regexp   *regexp.Regexp
	Block    []rune
	RunBlock func(*Process, []rune, []byte) ([]byte, []byte, error)
	// contains filtered or unexported fields
}

TestChecks are the pipe streams and what test case to check against

type TestProperties

type TestProperties struct {
	Name string

	HasRan bool
	// contains filtered or unexported fields
}

TestProperties are the values prescribed to an individual test case

type TestResult

type TestResult struct {
	Status     TestStatus
	TestName   string
	Message    string
	Exec       string
	Params     []string
	LineNumber int
	ColNumber  int
}

TestResult is a record for each test result

type TestResults

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

TestResults is a class for the entire result set

func (*TestResults) Add

func (tr *TestResults) Add(result *TestResult)

Add appends a result to TestResults

func (*TestResults) Dump

func (tr *TestResults) Dump() interface{}

Dump returns the slice for runtime diagnositics

func (*TestResults) Len

func (tr *TestResults) Len() int

Len returns the length of the results slice

type TestStatus

type TestStatus string

TestStatus is a summarised stamp for a particular result

const (
	// TestPassed means the test has passed
	TestPassed TestStatus = "PASSED"

	// TestFailed means the test has failed
	TestFailed TestStatus = "FAILED"

	// TestError means there was an error running that test case
	TestError TestStatus = "ERROR"

	// TestState is reporting the output from test state blocks
	TestState TestStatus = "STATE"

	// TestInfo is for any additional information on a test that might help
	// debug. This is only provided when `verbose` is enabled: `test verbose`
	TestInfo TestStatus = "INFO"

	// TestMissed means that test was not run (this is usually because
	// it was inside a parent control block - eg if / switch / etc -
	// which flowed down a different pathway. eg:
	//
	//     if { true } else { out <test_example> "example" }
	//
	// `test_example` would not run because `if` would not run the
	// `else` block.
	TestMissed TestStatus = "MISSED"
)

type Tests

type Tests struct {
	Results *TestResults
	// contains filtered or unexported fields
}

Tests is a class of all the tests that needs to run inside a particular scope, plus all of it's results.

func NewTests

func NewTests(p *Process) (tests *Tests)

NewTests creates a new testing scope for Murex's test suite.NewTests. Please note this should NOT be confused with Go tests (go test)!

func (*Tests) AddResult

func (tests *Tests) AddResult(test *TestProperties, p *Process, status TestStatus, message string)

AddResult is called after the test has run so the result can be recorded

func (*Tests) Compare

func (tests *Tests) Compare(name string, p *Process)

Compare is the method which actually runs the individual test cases to see if they pass or fail.

func (*Tests) Define

func (tests *Tests) Define(name string, out *TestChecks, err *TestChecks, exitNum int) error

Define is the method used to define a new test case

func (*Tests) Dump

func (tests *Tests) Dump() interface{}

Dump is used for `runtime --tests`

func (*Tests) ReportMissedTests

func (tests *Tests) ReportMissedTests(p *Process)

ReportMissedTests is used so we have a result of tests that didn't run

func (*Tests) SetStreams

func (tests *Tests) SetStreams(name string, stdout, stderr stdio.Io, exitNumPtr *int) error

SetStreams is called when a particular test case is run. eg

out <test_example> "Run this test"

func (*Tests) State

func (tests *Tests) State(name string, block []rune) error

State creates a new test state

func (*Tests) WriteResults

func (tests *Tests) WriteResults(config *config.Config, pipe stdio.Io) error

WriteResults is the reporting tool

type UnitTestPlan

type UnitTestPlan struct {
	Parameters        []string
	Stdin             string
	StdoutMatch       string
	StderrMatch       string
	StdinType         string
	StdoutType        string
	StderrType        string
	StdoutRegex       string
	StderrRegex       string
	StdoutBlock       string
	StderrBlock       string
	StdoutIsArray     bool
	StderrIsArray     bool
	StdoutIsMap       bool
	StderrIsMap       bool
	ExitNum           int
	StdoutGreaterThan int
	PreBlock          string
	PostBlock         string
}

UnitTestPlan is defined via JSON and specifies an individual test plan

type UnitTests

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

UnitTests is a class for all things murex unit tests

func (*UnitTests) Add

func (ut *UnitTests) Add(function string, test *UnitTestPlan, fileRef *ref.File)

Add a new unit test

func (*UnitTests) Dump

func (ut *UnitTests) Dump() interface{}

Dump the defined unit tests in a JSONable structure

func (*UnitTests) Run

func (ut *UnitTests) Run(p *Process, function string) bool

Run all unit tests against a specific murex function

type Variables

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

Variables is a table of all the variables. This will be local to the scope's process

func NewGlobals

func NewGlobals() *Variables

NewGlobals creates a new global variable table

func NewVariables

func NewVariables(p *Process) *Variables

NewVariables creates a new variable table

func (*Variables) Dump

func (v *Variables) Dump() interface{}

Dump returns a map of the structure of all variables in scope

func (*Variables) GetDataType

func (v *Variables) GetDataType(path string) string

GetDataType returns the data type of the variable stored in the referenced VarTable

func (*Variables) GetString

func (v *Variables) GetString(path string) (string, error)

GetString returns a string representation of the data stored in the requested variable

func (*Variables) GetValue

func (v *Variables) GetValue(path string) (interface{}, error)

GetValue return the value of a variable. If a variable does not exist then GetValue will return nil. Please check if p.Config.Get("proc", "strict-vars", "bool") matters for your usage of GetValue because this API doesn't care. If in doubt use GetString instead.

func (*Variables) Set

func (v *Variables) Set(p *Process, path string, value interface{}, dataType string) error

func (*Variables) Unset

func (v *Variables) Unset(name string) error

Unset removes a variable from the table

Directories

Path Synopsis
Package parameters provides parsing for language command line parameters within murex
Package parameters provides parsing for language command line parameters within murex
Package pipes provides runtime information about murex named pipes
Package pipes provides runtime information about murex named pipes
Package ref provides some reference structures required by multiple packages
Package ref provides some reference structures required by multiple packages
Package runmode provides constants used to describe the run mode of the murex interpreter
Package runmode provides constants used to describe the run mode of the murex interpreter
Package state provides constants used to describe the runtime state of murex functions
Package state provides constants used to describe the runtime state of murex functions

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL