much stdlib docs

stdlib/filesys.go

@@ -46,7 +46,14 @@ func AbsPath(arg string) string {
     return arg
 }
 
-func cd(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* Takes one arg, returns nil
+ * changes directory to the path in the arg
+ * fails if arg is not stringable
+ *
+ * Example:
+ *     (cd (concat HOME "/go"))
+ */
+func Cd(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     in = in.Eval(ft, vt, true)
 
     if in == nil {
@@ -68,11 +75,19 @@ func cd(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     return nil
 }
 
-func fexists(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* Takes one arg, returns a bool
+ * Returns true if arg is a filepath that exists
+ * returns nil if arg is not a string type
+ *
+ * Example:
+ *    (touch test)
+ *    (fexists test)
+ */
+func Fexists(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     in = in.Eval(ft, vt, false)
-    if in == nil || (in.Tag != ast.NUMBER && in.Tag != ast.STRING) {
+    if in == nil || in.Tag != ast.STRING {
         log.Log(log.ERR, 
-            "argument to fexists must be a string or number",
+            "argument to fexists must be a string",
             "fexists")
         return nil
     }
@@ -92,7 +107,14 @@ func fexists(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     return ret
 }
 
-func fread(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* Takes one arg, returns a string
+ * Returns contents of file in arg
+ * returns nil if file doesnt exist
+ *
+ * Example:
+ *    (fread (concat HOME ".shsrc"))
+ */
+func Fread(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     in = in.Eval(ft, vt, false)
     exists := fexists(in, vt, ft) // some waste, extra use of Eval
     if exists == nil || exists.Tag != ast.BOOL || exists.Value() == ast.FALSE {
@@ -116,7 +138,14 @@ func fread(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     return ret
 }
 
-func fwrite(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* Takes two arguments a filepath and a string
+ * CLOBBERS FILE CONTENTS
+ * Returns nil
+ *
+ * Example:
+ *     (fwrite "test" "one two three")
+ */
+func Fwrite(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     in = in.Eval(ft, vt, false)
     if in == nil || in.Tag == ast.SYMBOL || in.Tag == ast.LIST {
         log.Log(log.ERR,
@@ -146,7 +175,14 @@ func fwrite(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     return nil
 }
 
-func fappend(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
+/* Takes two arguments a filepath and a string
+ * DOES NOT CLOBBER FILE CONTENTS
+ * Returns nil
+ *
+ * Example:
+ *     (fwrite "test" "one two three")
+ */
+func Fappend(in *ast.Token, vt ast.VarTable, ft ast.FuncTable) *ast.Token {
     in = in.Eval(ft, vt, false)
     if in == nil || in.Tag == ast.SYMBOL || in.Tag == ast.LIST {
         log.Log(log.ERR,