From fec3550702288546052bd68c1819ddf49514c820 Mon Sep 17 00:00:00 2001 From: Aidan Date: Sat, 18 Jul 2020 14:40:35 -0700 Subject: [PATCH] ast package full godoc --- ast/eval.go | 6 ++++-- ast/func_table.go | 28 +++++++++++++++++++++++++--- ast/lex.go | 5 +++++ ast/token.go | 7 +++++++ ast/tokenstack.go | 7 +++++++ ast/var_table.go | 40 ++++++++++++++++++++-------------------- util/shell_complete.go | 1 - 7 files changed, 68 insertions(+), 26 deletions(-) diff --git a/ast/eval.go b/ast/eval.go index 48c6ff4..e82a89b 100644 --- a/ast/eval.go +++ b/ast/eval.go @@ -19,12 +19,14 @@ package ast import "gitlab.com/whom/shs/log" -/* determines whether or not to execute a system call +/* determines whether or not to execute a system binary * when a function cannot be found in the functable * (use case: shell) - * ExecFunc determines the name of the system call function to fetch */ var ExecWhenFuncUndef = false + +/* name of the command used to execute a system binary + */ var ExecFunc = "l" /* Runs through an AST of tokens diff --git a/ast/func_table.go b/ast/func_table.go index 3a2db29..b939e0c 100644 --- a/ast/func_table.go +++ b/ast/func_table.go @@ -19,18 +19,35 @@ package ast import "gitlab.com/whom/shs/log" +/* expected function header for any stdlib function + */ type Operation func(*Token, VarTable, FuncTable) *Token +/* holds a stdlib function along with relevant metadata + */ type Function struct { + // go function that list of args are passed to Function Operation + + // name of function Name string + + // number of times user has called this function TimesCalled int - Args int // TODO: Make this a list of expected types (TAGs) + + // number of args required + Args int } +/* holds a mapping of key to function + * passed to eval and into function calls + * initialized by repl at startup + */ type FuncTable *map[string]*Function -// TODO: Currently only checks arg list length +/* validates an individual call of a function + * makes sure correct arguments are passed in + */ func (f Function) ParseFunction(args *Token) bool { // handle infinite args if f.Args < 0 { @@ -52,6 +69,9 @@ func (f Function) ParseFunction(args *Token) bool { return true } +/* handles a call to a function + * calls ParseFunction and increments TimesCalled + */ func (f Function) CallFunction(args *Token, vt VarTable, ft FuncTable) *Token { if !f.ParseFunction(args) { log.Log(log.ERR, @@ -64,6 +84,8 @@ func (f Function) CallFunction(args *Token, vt VarTable, ft FuncTable) *Token { return f.Function(args, vt, ft) } +/* searches for function mapped to argument in FuncTable + */ func GetFunction(arg string, table FuncTable) *Function { target, ok := (*table)[arg] if !ok { @@ -77,7 +99,7 @@ func GetFunction(arg string, table FuncTable) *Function { } -/* lists all functions in table +/* returns list of all functions in table */ func ListFuncs(ft FuncTable) []string { keys := make([]string, len(*ft)) diff --git a/ast/lex.go b/ast/lex.go index 285fd94..3031cab 100644 --- a/ast/lex.go +++ b/ast/lex.go @@ -22,8 +22,12 @@ import ( "unicode" ) +// all delimiters that work on strings const string_delims string = "\"'`" +/* takes a line of user input + * returns an unsimplified tree of tokens + */ func Lex(input string) *Token { ret := lex(input) if ret == nil { @@ -201,6 +205,7 @@ error: return nil } +// returns true if a string could contain an int or float func StrIsNumber(arg string) bool { dotCount := 0 diff --git a/ast/token.go b/ast/token.go index 367cd42..b9ba0ca 100644 --- a/ast/token.go +++ b/ast/token.go @@ -19,7 +19,11 @@ package ast import "fmt" +/* token_t is a tag that declares the type of the + * datum contained in a token + */ type Token_t int + const ( LIST Token_t = iota STRING Token_t = iota @@ -31,6 +35,9 @@ const ( FALSE string = "F" ) +/* Contains a parsed lexeme + * and a pointer to the next parsed lexeme in the same scope + */ type Token struct { Next *Token Tag Token_t diff --git a/ast/tokenstack.go b/ast/tokenstack.go index 9f7360b..136ccae 100644 --- a/ast/tokenstack.go +++ b/ast/tokenstack.go @@ -17,16 +17,23 @@ package ast +/* primitive stack type for tokens + * useful for iterative algorithms on tokens + */ type TokenStack struct { buffer []*Token capacity int } +/* push token onto stack + */ func (s *TokenStack) Push(v *Token) { s.capacity++ s.buffer = append(s.buffer, v) } +/* pop token off stack + */ func (s *TokenStack) Pop() *Token { if s.capacity <= 0 { return nil diff --git a/ast/var_table.go b/ast/var_table.go index 072ec99..ab1eec2 100644 --- a/ast/var_table.go +++ b/ast/var_table.go @@ -26,11 +26,19 @@ import ( "gitlab.com/whom/shs/log" ) -// Trigger this if you are using this for a shell +/* defines whether or not to synchronize tokens wiht os environment vars + * will not sync non stringable tokens + */ var SyncTablesWithOSEnviron = false +/* mapping of key to token. + */ type VarTable *map[string]*Token +/* retrieve the token cooresponding to a given key + * if SyncTablesWithOSEnviron is true and no token exists for a key + * os Environment variables will be searched for the key + */ func GetVar(arg string, vt VarTable) *Token { val, ok := (*vt)[arg] if !ok { @@ -55,8 +63,10 @@ func GetVar(arg string, vt VarTable) *Token { return val } -// TODO: this could be much more optimal -// probably a stdlib thing +/* adds a key->token mapping to the table + * if SyncTablesWithOSEnviron is true, will also add value to os environment + * will not do so for non stringable tokens + */ func SetVar(variable string, value *Token, vt VarTable) { (*vt)[variable] = value if SyncTablesWithOSEnviron && @@ -85,22 +95,9 @@ func ListVars(vt VarTable) []string { return keys } -// Library represents variables defined in inner scope -// It is assumed library is ordered from innermost scope to outermost scope -func GetVarFromTables(arg string, library []VarTable) *Token { - var res *Token - res = nil - for i := 0; i < len(library); i += 1 { - res = GetVar(arg, library[i]) - if res != nil { - // TODO: Log scope res was found in? - break - } - } - - return res -} - +/* if SyncTablesWithOSEnviron is true + * function will put ever environment variable into VarTable + */ func InitVarTable(table VarTable) { if !SyncTablesWithOSEnviron { return @@ -133,7 +130,10 @@ func DeleteVarTable(table VarTable) { } } } - +a +/* removes var from vartable + * if SyncTablesWithOSENviron is true, also unsets environment variable + */ func RemoveVar(arg string, table VarTable) { if SyncTablesWithOSEnviron { err := os.Unsetenv(arg) diff --git a/util/shell_complete.go b/util/shell_complete.go index 67e9b6c..e2e4731 100644 --- a/util/shell_complete.go +++ b/util/shell_complete.go @@ -18,7 +18,6 @@ package util import ( - "fmt" "strings" "io/ioutil" "gitlab.com/whom/shs/log"