much stdlib docs

stdlib/call.go

@@ -30,7 +30,6 @@ import (
 )
 
 var bgProcs = make([]*exec.Cmd, 0)
-var LastExitCode int
 var sigs = []os.Signal{
     os.Interrupt,
     syscall.SIGTERM,
@@ -40,8 +39,17 @@ var sigs = []os.Signal{
     syscall.SIGCONT,
 }
 
+/* Exit code of last run process
+ */
+var LastExitCode int
 
-func call(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* Takes n arguments (list of tokens generated by lexing a shell command)
+ * Evaluates arguments, but does not err on undefined symbols (note the last arg to Eval(...))
+ * Executes shell command and returns nil
+ *
+ * Example (l vim file.txt)
+ */
+func Call(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     in = in.Eval(ft, vt, true)
     if in == nil {
         return nil
@@ -100,7 +108,12 @@ func call(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     return nil
 }
 
-func bgcall(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* Starts a call in the background
+ * Takes n args (a shell command not delimited by string delimiters)
+ *
+ * Example: (bg vim file.txt)
+ */
+func Bgcall(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     if in == nil {
         return nil
     }
@@ -144,7 +157,14 @@ func bgcall(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     return nil
 }
 
-func fg(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* brings last BG'ed process into the foreground
+ * returns nil
+ *
+ * Example:
+ *    (bg vim file.txt)
+ *    (fg)
+ */
+func Fg(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     if len(bgProcs) < 1 {
         return nil
     }
@@ -174,7 +194,16 @@ func fg(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     return nil
 }
 
-func jobs(in *ast.Token, vt ast.VarTable, fg ast.FuncTable) *ast.Token {
+/* Takes 0 args
+ * returns a string containing info about current jobs
+ * returns total jobs as well as their PIDs and place in the bg queue
+ *
+ * Example:
+ *    (bg ping google.com)
+ *    (bg .........)
+ *    (jobs)
+ */
+func Jobs(in *ast.Token, vt ast.VarTable, fg ast.FuncTable) *ast.Token {
     ret := &ast.Token{
         Tag: ast.LIST,
     }
@@ -198,7 +227,12 @@ func jobs(in *ast.Token, vt ast.VarTable, fg ast.FuncTable) *ast.Token {
     return ret
 }
 
-func read_cmd(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* calls a command (blocks until completion)
+ * captures stdout and returns it as a string
+ *
+ * Example: ($ echo hello world)
+ */
+func ReadCmd(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     in = in.Eval(ft, vt, true)
 
     if in == nil {
@@ -267,13 +301,25 @@ func read_cmd(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
 
 }
 
-func get_exit(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* Takes 0 arguments
+ * returns the exit code of the last executed program
+ *
+ * Example:
+ *     (sudo apt update)
+ *     (?) <- gets exit code
+ */
+func GetExit(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     ret := &ast.Token{Tag: ast.NUMBER}
     ret.Set(fmt.Sprintf("%d", LastExitCode))
     return ret
 }
 
-func kill(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* takes an argument (pid of process to be killed)
+ * calls Process.Kill() on it
+ * do not use this if you already have a native implementation
+ * (this function not added to functable in stdlib.go)
+ */
+func Kill(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     in = in.Eval(ft, vt, true)
 
     if in.Tag == ast.LIST {