README
¶
Cogent Shell (cosh)
Cogent Shell (cosh) is a shell that combines the best parts of Go and bash to provide an integrated shell experience that allows you to easily run terminal commands while using Go for complicated logic. This allows you to write concise, elegant, and readable shell code that runs quickly on all platforms and transpiles to Go.
Syntax: Go vs. Exec
The critical extension from standard Go syntax is for lines that are processed by the Exec functions, used for running arbitrary programs on the user's executable path. Here are the rules (word = IDENT token):
- Backticks "``" anywhere: Exec. Returns a
string. - Within Exec,
{}: Go - Line starts with
GoKeyword: Go - Line is one word: Exec
- Line starts with
.: Exec - Line starts with
word word: Exec - Line starts with
word {: Exec - Otherwise: Go
Documentation
¶
Overview ¶
Package shell provides the Cogent Shell (cosh), which combines the best parts of Go and bash to provide an integrated shell experience that allows you to easily run terminal commands while using Go for complicated logic.
Index ¶
- type Shell
- func (sh *Shell) AddError(err error) error
- func (sh *Shell) AddLine(ln string)
- func (sh *Shell) Cd(args ...string) error
- func (sh *Shell) Code() string
- func (sh *Shell) Exec(cmd any, args ...any)
- func (sh *Shell) InstallBuiltins()
- func (sh *Shell) Output(cmd any, args ...any) string
- func (sh *Shell) ResetLines()
- func (sh *Shell) RunBuiltin(cmd string, args ...string) bool
- func (sh *Shell) Tokens(ln string) Tokens
- func (sh *Shell) TotalDepth() int
- func (sh *Shell) TranspileCode(code string)
- func (sh *Shell) TranspileExec(toks Tokens, output bool) Tokens
- func (sh *Shell) TranspileExecString(str string, output bool) Tokens
- func (sh *Shell) TranspileFile(in string, out string) error
- func (sh *Shell) TranspileGo(toks Tokens) Tokens
- func (sh *Shell) TranspileLine(ln string) string
- func (sh *Shell) TranspileLineTokens(ln string) Tokens
- type Token
- type Tokens
- func (tk *Tokens) Add(tok token.Token, str ...string) *Token
- func (tk *Tokens) AddTokens(toks Tokens) *Tokens
- func (tk Tokens) BracketDepths() (paren, brace, brack int)
- func (tk Tokens) Code() string
- func (tk *Tokens) DeleteLastComma()
- func (tk Tokens) Last() *Token
- func (tk Tokens) RightMatching() int
- func (tk Tokens) String() string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Shell ¶
type Shell struct {
// Builtins are all the builtin shell commands
Builtins map[string]func(args ...string) error
// Config is the [exec.Config] used to run commands.
Config exec.Config
// depth of parens at the end of the current line. if 0, was complete.
ParenDepth int
// depth of braces at the end of the current line. if 0, was complete.
BraceDepth int
// depth of brackets at the end of the current line. if 0, was complete.
BrackDepth int
// stack of transpiled lines
Lines []string
// stack of runtime errors
Errors []error
}
Shell represents one running shell context.
func (*Shell) AddError ¶
AddError adds the given error to the error stack if it is non-nil. This is the main way that shell errors are handled. It also prints the error.
func (*Shell) Exec ¶
Exec executes the given command string, handling the given arguments appropriately. If there is any error, it adds it to the shell. It forwards output to exec.Config.Stdout and exec.Config.Stderr appropriately.
func (*Shell) InstallBuiltins ¶
func (sh *Shell) InstallBuiltins()
func (*Shell) Output ¶
Output executes the given command string, handling the given arguments appropriately. If there is any error, it adds it to the shell. It returns the stdout as a string and forwards stderr to exec.Config.Stderr appropriately.
func (*Shell) ResetLines ¶
func (sh *Shell) ResetLines()
ResetLines resets the stack of transpiled lines
func (*Shell) TotalDepth ¶
TotalDepth returns the sum of any unresolved paren, brace, or bracket depths.
func (*Shell) TranspileCode ¶
TranspileCode processes each line of given code, adding the results to the LineStack
func (*Shell) TranspileExec ¶
TranspileExec returns transpiled tokens assuming Exec code, with the given bool indicating whether [Output] is needed.
func (*Shell) TranspileExecString ¶
TranspileExecString returns transpiled tokens assuming Exec code, from a backtick-encoded string, with the given bool indicating whether [Output] is needed.
func (*Shell) TranspileFile ¶
TranspileFile transpiles the given input cosh file to the given output Go file, adding package main and func main declarations.
func (*Shell) TranspileGo ¶
TranspileGo returns transpiled tokens assuming Go code. Unpacks any backtick encapsulated shell commands.
func (*Shell) TranspileLine ¶
TranspileLine is the main function for parsing a single line of shell input, returning a new transpiled line of code that converts Exec code into corresponding Go function calls.
func (*Shell) TranspileLineTokens ¶
TranspileLineTokens returns the tokens for the full line
type Token ¶
type Token struct {
// Go token classification
Tok token.Token
// Literal string
Str string
// position in the original string.
// this is only set for the original parse,
// not for transpiled additions.
Pos token.Pos
}
Token provides full data for one token
func (*Token) IsBacktickString ¶
IsBacktickString returns true if the given STRING uses backticks
func (*Token) IsBracket ¶
IsBracket returns true if the given token is a bracket delimiter: paren, brace, bracket
type Tokens ¶
type Tokens []*Token
Tokens is a slice of Token
func (Tokens) BracketDepths ¶
BracketDepths returns the depths for the three bracket delimiters [paren, bracket, brace], based on unmatched right versions.
func (Tokens) Code ¶
Code returns concatenated Str values of the tokens, to generate a surface-valid code string.
func (*Tokens) DeleteLastComma ¶
func (tk *Tokens) DeleteLastComma()
DeleteLastComma removes any final Comma. easier to generate and delete at the end
func (Tokens) RightMatching ¶
RightMatching returns the position (or -1 if not found) for the right matching [paren, bracket, brace] given the left one that is at the 0 position of the current set of tokens.
Source Files
Directories