cleanup and writing docs

bin/pre.slime

@@ -1,15 +1,13 @@
 (define nil ())
 
-(define defun
-  (macro (@name @params :rest @body)
-    (eval (pair 'define (pair @name (pair (pair 'lambda (pair @params @body)) nil))))))
-
 (define defmacro
   (macro (@name @params :rest @body)
-    (eval (pair 'define (pair @name (pair (pair 'macro (pair @params @body)) nil))))))
+     "Macro for creating macros with a more concise syntax."
+     (eval (pair 'define (pair @name (pair (pair 'macro (pair @params @body)) nil))))))
 
-(defmacro pe (@expr)
-  (printf @expr "evaluates to" (eval @expr)))
+(defmacro defun (@name @params :rest @body)
+    "Macro for creating functions with a more concise syntax."
+    (eval (pair 'define (pair @name (pair (pair 'lambda (pair @params @body)) nil)))))
 
 (defun nil? (x)
   "Checks if the argument is nil."
@@ -53,7 +51,7 @@ ithe sequence as arguemens."
   (eval (pair fun seq)))
 
 (defmacro when (@test :rest @body)
-  "Executes the code in :rest if test is true"
+  "Executes the code in :rest if test is true."
   (if (eval @test)
       (eval (pair prog @body))
     nil))
@@ -83,25 +81,35 @@ the (rest) of the last element of the sequence."
   seq)
 
 (defun incr (val)
+  "Adds one to the argument."
   (+ val 1))
 
 (defun decr (val)
+  "Subtracts one from the argument."
   (- val 1))
 
 (defun append (seq elem)
+  "Appends an element to a sequence, by extendeing the list
+with (pair elem nil)."
   (extend seq (pair elem nil)))
 
 (defun length (seq)
+  "Returns the length of the given sequence."
   (if (nil? seq)
       0
     (incr (length (rest seq)))))
 
 (defmacro n-times (@times @action)
+  "Executes @action @times times."
   (unless (<= (eval @times) 0)
     (eval @action)
-    (eval (list n-times (list - @times 1) @action))))
+    (apply n-times (list (list - @times 1) @action))))
 
 (defmacro for (@symbol @from @to :rest @for-body)
+  "Designed to resemble a C style for loop. It takes a symbol as
+well as its starting number and end number and executes the
+@for-body with the defined symbol for all numbers between @from
+to @to, where @to is exclusive."
   (if (< (eval @from) (eval @to))
       (macro-define @op incr)
     (if (> (eval @from) (eval @to))
@@ -115,12 +123,11 @@ the (rest) of the last element of the sequence."
 (defun range (:keys from :defaults-to 0 to)
   "Returns a sequence of numbers starting with the number defined
 by the key 'from' and ends with the number defined in 'to'."
-  (if (< from to)
-      (pair from (range :from (+ 1 from) :to to))
-    nil))
+  (when (< from to)
+      (pair from (range :from (+ 1 from) :to to))))
 
 (defun map (fun seq)
-  "Takes a sequence and a function as arguments and returns a new
+  "Takes a function and a sequence as arguments and returns a new
 sequence which contains the results of using the first sequences
 elemens as argument to that function."
   (if (nil? seq)
@@ -129,15 +136,15 @@ elemens as argument to that function."
           (map fun (rest seq)))))
 
 (defun reduce (fun seq)
-  "Takes a sequence and a function as arguments and applies the
+  "Takes a function and a sequence as arguments and applies the
 function to the argument sequence. This only works correctly if
 the given function accepts a variable amount of parameters. If
 your funciton is limited to two arguments, use `reduce-binary'
 instead."
-  (eval (pair fun seq)))
+  (apply fun seq))
 
 (defun reduce-binary (fun seq)
-  "Takes a sequence and a function as arguments and applies the
+  "Takes a function and a sequence as arguments and applies the
 function to the argument sequence. reduce-binary applies the
 arguments `pair-wise' which means it works with binary functions
 as compared to `reduce'."
@@ -147,23 +154,32 @@ as compared to `reduce'."
          (reduce-binary fun (rest seq)))))
 
 (defun filter (fun seq)
-  (if (nil? seq)
-      nil
+  "Takes a function and a sequence as arguments and applies the
+function to every value in the sequence. If the result of that
+funciton application returns a truthy value, the original value is
+added to a list, which in the end is returned."
+  (when seq
     (if (fun (first seq))
         (pair (first seq)
               (filter fun (rest seq)))
       (filter fun (rest seq)))))
 
-(defmacro printf-quoted (:keys @sep :defaults-to " " @end :defaults-to "\n" :rest @args)
-  (if (nil? @args)
-      (prog (print (eval @end)) nil)
-    (prog
-     (print (first @args))
-     (when (not (nil? (rest @args))) (print (eval @sep)))
-     (eval
-      (pair printf-quoted
-            (extend (list :@sep (eval @sep) :@end (eval @end)) (rest @args)))))))
-
 (defun printf (:keys sep :defaults-to " " end :defaults-to "\n" :rest args)
-  (define command-args (extend (list :@sep (eval sep) :@end (eval end)) args))
-  (eval (pair printf-quoted command-args)))
+  "A wrapper for the built-in (print) that accepts a variable number
+of arguments and also provides keywords for specifying the printed
+separators between the arguments and what should be printed after the
+las argument."
+  (defmacro printf-quoted (:keys @sep @end :rest @args)
+    (if (nil? @args)
+        (prog (print (eval @end)) nil)
+      (prog
+       (print (first @args))
+       (unless (nil? (rest @args))
+         (print (eval @sep)))
+       (eval (pair printf-quoted
+              (extend (list :@sep (eval @sep) :@end (eval @end)) (rest @args)))))))
+
+  (eval (pair printf-quoted (extend (list :@sep (eval sep) :@end (eval end)) args))))
+
+(defmacro pe (@expr)
+  (printf @expr "evaluates to" (eval @expr)))