Sl-sh

Documentation structure for each form

form name	type (see: Type forms)
namespace (fully qualified names are of format namespace::symbol)	usage

example code if exists

Documentation

Char forms

`char-lower`	Type: Function
`root::char-lower`	`Usage: (char-lower char) -> char`

Get lower case (utf) character for a character.


Example:

(test::assert-equal #\a (char-lower #\A))

(test::assert-equal #\a (char-lower #\a))

(test::assert-not-equal #\a (char-lower #\Z))

(test::assert-equal #\λ (char-lower #\Λ))

(test::assert-equal #\λ (char-lower #\λ))

`char-upper`	Type: Function
`root::char-upper`	`Usage: (char-upper char) -> char`

Get upper case (utf) character for a character.


Example:

(test::assert-equal #\A (char-upper #\A))

(test::assert-equal #\A (char-upper #\a))

(test::assert-not-equal #\A (char-upper #\Z))

(test::assert-equal #\Λ (char-upper #\λ))

(test::assert-equal #\Λ (char-upper #\Λ))

`char-whitespace?`	Type: Function
`root::char-whitespace?`	`Usage: (char-whitespace? char) -> t/nil`

Returns true if a character is whitespace, false/nil otherwise.


Example:

(test::assert-true (char-whitespace? #\ ))

(test::assert-true (char-whitespace? #\tab))

(test::assert-false (char-whitespace? #\s))

Conditional forms

`<`	Type: Function
`root::<`	`Usage: (< val0 ... valN)`

Less than. Works for int, float or string.


Example:

(test::assert-true (< 1 2))

(test::assert-true (< 1 2 3 4))

(test::assert-false (< 2 2))

(test::assert-false (< 2 2 2))

(test::assert-false (< 2 2 3))

(test::assert-true (< 1.0 2.0))

(test::assert-false (< 2.0 2.0))

(test::assert-false (< 2.0 2.0 2.0))

(test::assert-false (< 2.0 2.0 3.0))

(test::assert-false (< 2.1 2.0 3.0))

(test::assert-false (< 2 1))

(test::assert-false (< 3 2 3))

(test::assert-true (< "aaa" "aab"))

(test::assert-false (< "aaa" "aaa"))

(test::assert-true (< "aaa" "aab" "ccc"))

(test::assert-false (< "baa" "aab"))

`<=`	Type: Function
`root::<=`	`Usage: (<= val0 ... valN)`

Less than or equal. Works for int, float or string.


Example:

(test::assert-true (<= 1 2))

(test::assert-true (<= 2 2))

(test::assert-true (<= 2 2 2))

(test::assert-true (<= 2 2 3))

(test::assert-true (<= 1.0 2.0))

(test::assert-true (<= 2.0 2.0))

(test::assert-true (<= 2.0 2.0 2.0))

(test::assert-true (<= 2.0 2.0 3.0))

(test::assert-false (<= 2.1 2.0 3.0))

(test::assert-false (<= 2 1))

(test::assert-false (<= 3 2 3))

(test::assert-true (<= "aaa" "aab"))

(test::assert-true (<= "aaa" "aaa"))

(test::assert-true (<= "aaa" "aab" "ccc"))

(test::assert-false (<= "baa" "aab"))

`=`	Type: Function
`root::=`	`Usage: (= val0 ... valN)`

Equals. Works for int, float or string.


Example:

(test::assert-false (= 1 2))

(test::assert-true (= 2 2))

(test::assert-true (= 2 2 2))

(test::assert-false (= 3 2 2))

(test::assert-false (= 3.0 2.0))

(test::assert-true (= 2.0 2.0))

(test::assert-true (= 2.0 2.0 2.0))

(test::assert-false (= 3.0 2.0 2.0))

(test::assert-false (= 2.1 2.0 3.0))

(test::assert-false (= 2 1))

(test::assert-false (= 3 2 1))

(test::assert-false (= 1.1 1.0))

(test::assert-true (= 1.1 1.1))

(test::assert-false (= 3 2 3))

(test::assert-false (= "aab" "aaa"))

(test::assert-true (= "aaa" "aaa"))

(test::assert-true (= "aaa" "aaa" "aaa"))

(test::assert-false (= "aaa" "aaaa" "aaa"))

(test::assert-false (= "ccc" "aab" "aaa"))

(test::assert-false (= "aaa" "aab"))

`>`	Type: Function
`root::>`	`Usage: (> val0 ... valN)`

Greater than. Works for int, float or string.


Example:

(test::assert-false (> 1 2))

(test::assert-false (> 2 2))

(test::assert-false (> 2 2 2))

(test::assert-false (> 3 2 2))

(test::assert-true (> 3.0 2.0))

(test::assert-false (> 2.0 2.0))

(test::assert-false (> 2.0 2.0 2.0))

(test::assert-false (> 3.0 2.0 2.0))

(test::assert-false (> 2.1 2.0 3.0))

(test::assert-true (> 2 1))

(test::assert-true (> 3 2 1))

(test::assert-true (> 1.1 1.0))

(test::assert-false (> 3 2 3))

(test::assert-true (> "aab" "aaa"))

(test::assert-false (> "aaa" "aaa"))

(test::assert-true (> "ccc" "aab" "aaa"))

(test::assert-false (> "aaa" "aab"))

`>=`	Type: Function
`root::>=`	`Usage: (>= val0 ... valN)`

Greater than or equal. Works for int, float or string.


Example:

(test::assert-false (>= 1 2))

(test::assert-true (>= 2 2))

(test::assert-true (>= 2 2 2))

(test::assert-true (>= 3 2 2))

(test::assert-true (>= 3.0 2.0))

(test::assert-true (>= 2.0 2.0))

(test::assert-true (>= 2.0 2.0 2.0))

(test::assert-true (>= 3.0 2.0 2.0))

(test::assert-false (>= 2.1 2.0 3.0))

(test::assert-true (>= 2 1))

(test::assert-true (>= 1.1 1.0))

(test::assert-false (>= 3 2 3))

(test::assert-true (>= "aab" "aaa"))

(test::assert-true (>= "aaa" "aaa"))

(test::assert-true (>= "ccc" "aab" "aaa"))

(test::assert-false (>= "aaa" "aab"))

`and`	Type: SpecialForm
`root::and`	`Usage: (and exp0 ... expN) -> [false(#f) or expN result]`

Evaluates each form until one produces nil or false(#f), produces false(#f) if any form is nil/#f or the result of the last expression. The and form will stop evaluating when the first expression produces nil/#f.


Example:

(test::assert-equal #f (and nil (err "and- can not happen")))

(test::assert-equal #f (and #f (err "and- can not happen")))

(test::assert-equal "and- done" (and #t "and- done"))

(test::assert-equal "and- done" (and #t #t "and- done"))

(test::assert-equal 6 (and #t #t (+ 1 2 3)))

(test::assert-equal 6 (and (/ 10 5) (* 5 2) (+ 1 2 3)))

`cond`	Type: Macro
`root::cond`	`Usage: (cond ((test form)) -> result`

Evaluate each test in order. If it is true then evaluate the form(s) in an implicit do and return the result. Stop evaluting at the first true test. Return nil if no conditions are true.


Example:

(defn select-option (a)

(cond ((= a 1) "opt-one")

((= a 2) (set! b 5) "opt-two")

((= a 3) (str "opt" "-three"))))

(defn select-option-def (a)

(cond ((= a 1) "opt-one")

((= a 2) "opt-two")

((= a 3) (str "opt" "-three"))

(#t "default")))

(def b 0)

(assert-equal "opt-one" (select-option 1))

(assert-equal b 0)

(assert-equal "opt-two" (select-option 2))

(assert-equal b 5)

(assert-equal "opt-three" (select-option 3))

(assert-equal nil (select-option 4))

(assert-equal "opt-one" (select-option-def 1))

(assert-equal "opt-two" (select-option-def 2))

(assert-equal "opt-three" (select-option-def 3))

(assert-equal "default" (select-option-def 4))

`if`	Type: SpecialForm
`root::if`	`Usage: (if p1 a1 p2 a2 ... pn an?) -> [evaled form result]`

If conditional. Will evaluate p1 and if true (i.e. not nil or false) then return the evaluation of a1, if falsey(i.e. nil or false) evaluate p2 and so on. On an odd number of arguments (an is missing) then evaluate and return pn. Return false(#f) if no predicate is true. This degenerates into the traditional (if predicate then-form else-form). NOTE: Both nil and false(#f) are ‘falsey’ for the purposes of if.


Example:

(def test-if-one

(if #t "ONE TRUE" "ONE FALSE"))

(def test-if-two

(if nil "TWO TRUE" "TWO FALSE"))

(def test-if-three

(if #f "THREE TRUE" "THREE FALSE"))

(test::assert-equal "ONE TRUE" test-if-one)

(test::assert-equal "TWO FALSE" test-if-two)

(test::assert-equal "THREE FALSE" test-if-three)

(def test-if-one2

(if #t "ONE2 TRUE"))

(def test-if-two2

(if nil "TWO2 TRUE"))

(def test-if-three2

(if #f "THREE2 TRUE"))

(test::assert-equal "ONE2 TRUE" test-if-one2)

(test::assert-equal #f test-if-two2)

(test::assert-equal #f test-if-three2)

(def test-if-one2

(if nil "ONE FALSE" #t "ONE TRUE" #t "ONE TRUE2"))

(def test-if-two2

(if nil "TWO TRUE" #f "TWO FALSE" #t "TWO TRUE2"))

(def test-if-three2

(if #f "THREE TRUE" nil "THREE FALSE" "THREE DEFAULT"))

(test::assert-equal "ONE TRUE" test-if-one2)

(test::assert-equal "TWO TRUE2" test-if-two2)

(test::assert-equal "THREE DEFAULT" test-if-three2)

(test::assert-equal nil (if nil))

(test::assert-equal #f (if nil #t nil #t nil t))

`match`	Type: Macro
`root::match`	`Usage: (match condition (value form)) -> result`

Evaluate condition and look for matching value in each branch of type (value form*). Form(s) will be wrapped in an implicit do. Use nil to take action if no match (encouraged!).


Example:

(defn select-option (a)

(match a (1 "opt-one")

(2 (set! b 5) "opt-two")

(3 (str "opt" "-three"))))

(defn select-option-def (a)

(match a (1 "opt-one")

(2 "opt-two")

(3 (str "opt" "-three"))

(nil "default")))

(def b 0)

(assert-equal b 0)

(assert-equal "opt-one" (select-option 1))

(assert-equal "opt-two" (select-option 2))

(assert-equal b 5)

(assert-equal "opt-three" (select-option 3))

(assert-equal #f (select-option 4))

(assert-equal "opt-one" (select-option-def 1))

(assert-equal "opt-two" (select-option-def 2))

(assert-equal "opt-three" (select-option-def 3))

(assert-equal "default" (select-option-def 4))

`not`	Type: Function
`root::not`	`Usage: (not expression)`

Return true(#t) if expression is nil, false(#f) otherwise.


Example:

(test::assert-true (not nil))

(test::assert-false (not 10))

(test::assert-false (not #t))

(test::assert-false (not (+ 1 2 3)))

`null`	Type: Function
`root::null`	`Usage: (null expression)`

Return true(#t) if expression is nil (null).


Example:

(test::assert-true (null nil))

(test::assert-false (null 10))

(test::assert-false (null #t))

(test::assert-false (null (+ 1 2 3)))

`or`	Type: SpecialForm
`root::or`	`Usage: (or exp0 ... expN) -> [false(#f) or first non nil expression]`

Evaluates each form until one produces a non-nil/non-false result, produces #f if all expressions are ‘falsey’. The or form will stop evaluating when the first expression produces non-nil/false.


Example:

(test::assert-true (or nil nil #t (err "and- can not happen")))

(test::assert-true (or #f nil #t (err "and- can not happen")))

(test::assert-true (or #f #f #t (err "and- can not happen")))

(test::assert-equal #f (or nil nil nil))

(test::assert-equal #f (or #f nil nil))

(test::assert-equal #f (or #f nil #f))

(test::assert-equal #f (or #f #f #f))

(test::assert-equal "or- done" (or nil "or- done"))

(test::assert-equal "or- done" (or nil nil "or- done"))

(test::assert-equal 6 (or nil nil (+ 1 2 3)))

(test::assert-equal 2 (or (/ 10 5) (* 5 2) (+ 1 2 3)))

`when`	Type: Macro
`root::when`	`Usage: (when provided-condition if-true)`

when is a convenience function used to check a form, provided-condition, and run some form, if-true, if provided-condition evaluates to true.


Example:

(assert-true (when #t #t))

(assert-false (when #t nil))

(assert-false (when nil nil))

Core forms

`collection-src`	Type: String
`root::collection-src`	`Usage: (print collection-src)`

The builtin source code for collection.lisp.


Example:

;(print *collection-src*)

#t

`core-src`	Type: String
`root::core-src`	`Usage: (print core-src)`

The builtin source code for core.lisp.


Example:

;(print *core-src*)

#t

`getopts-src`	Type: String
`root::getopts-src`	`Usage: (print getopts-src)`

The builtin source code for shell.lisp.


Example:

;(print *getopts-src*)

#t

`iterator-src`	Type: String
`root::iterator-src`	`Usage: (print iterator-src)`

The builtin source code for iterator.lisp.


Example:

;(print *iterator-src*)

#t

`lib-src`	Type: String
`root::lib-src`	`Usage: (print lib-src)`

The builtin source code for lib.lisp.


Example:

;(print *lib-src*)

#t

`seq-src`	Type: String
`root::seq-src`	`Usage: (print seq-src)`

The builtin source code for seq.lisp.


Example:

;(print *seq-src*)

#t

`shell-read-src`	Type: String
`root::shell-read-src`	`Usage: (print shell-read-src)`

The builtin source code for shell-read.lisp.


Example:

;(print *shell-read-src*)

#t

`shell-src`	Type: String
`root::shell-src`	`Usage: (print shell-src)`

The builtin source code for shell.lisp.


Example:

;(print *shell-src*)

#t

`slsh-std-src`	Type: String
`root::slsh-std-src`	`Usage: (print slsh-std-src)`

The builtin source code for slsh-std.lisp.


Example:

;(print *slsh-std-src*)

#t

`slshrc-src`	Type: String
`root::slshrc-src`	`Usage: (print slshrc-src)`

The builtin source code for slshrc.


Example:

;(print *slshrc-src*)

#t

`struct-src`	Type: String
`root::struct-src`	`Usage: (print struct-src)`

The builtin source code for struct.lisp.


Example:

;(print *struct-src*)

#t

`test-src`	Type: String
`root::test-src`	`Usage: (print test-src)`

The builtin source code for test.lisp.


Example:

;(print *test-src*)

#t

`and-let*`	Type: Macro
`root::and-let*`	`Usage: (and-let* vals &rest let-body)`

Takes list, vals, of form ((binding0 sexp0) (binding1 sexp1) …) checking if result of each sexp evaluates to false, short circuiting and returning nil if so. If all vals bindings evaluate to true, then the let-body is evaluated with all values of binding bound to the result of the evaluation of sexp. Sexps can reference bindings from previous items in the list of vals. If no let-body is supplied the last binding in the list of vals is returned.


Example:

(test::assert-equal "charlie bravo alpha."

(and-let* ((val (str "alpha."))

(other-val (str "bravo " val)))

(str "charlie " other-val)) "]")

(test::assert-equal "alpha, bravo." (and-let* ((val (do

(str "bravo.")))

(other-val (do

(str "alpha, " val))))))

(test::assert-false (and-let* ((val (do (str "alpha, ") nil))

(other-val (do (str "bravo " val))))))

(test::assert-false (and-let* ((a-list (list 1 2 3 4 5 6 7 8))

(evens (filter (fn (x) (= 0 (% x 2))) a-list))

(doubled (map (fn (x) (* x 2)) evens))

(odds (collect (filter (fn (x) (= 1 (% x 2))) doubled))))

#t))

`apply`	Type: Function
`root::apply`	`Usage: (apply function arg* list)`

Call the provided function with the supplied arguments, last is a list that will be expanded.


Example:

(def test-apply-one (apply str '(\"O\" \"NE\")))

(test::assert-equal \"ONE\" test-apply-one)

(test::assert-equal 10 (apply + 1 '(2 7)))

`back-quote`	Type: SpecialForm
`root::back-quote`	Usage: `expression -> expression

Return expression without evaluation. Always use the ` reader macro or expansion will not work (i.e. (back-quote expression) will not do , expansion). Backquote (unlike quote) allows for symbol/form evaluation using , or ,@.


Example:

(test::assert-equal (list 1 2 3) `(1 2 3))

(test::assert-equal `(1 2 3) '(1 2 3))

(def test-bquote-one 1)

(def test-bquote-list '(1 2 3))

(test::assert-equal (list 1 2 3) `(,test-bquote-one 2 3))

(test::assert-equal (list 1 2 3) `(,@test-bquote-list))

`block`	Type: SpecialForm
`root::block`	`Usage: (block name form*)`

Create a block with name (name is not evaluated), if no return-from encountered then return last expression (like do). Note: If the last expression in a block is a tail call then it can not use return-from since the tail call will leave the block and the return-from will not find it.


Example:

(test::assert-equal '(4 5) (block xxx '(1 2) (return-from xxx '(4 5)) '(a b) '(2 3)))

(test::assert-equal '(4 5) (block xxx '(1 2) (return-from nil '(4 5)) '(a b) '(2 3)))

(test::assert-equal '(5 6) (block xxx '(1 2) (block yyy (return-from xxx '(5 6)) '(a b)) '(2 3)))

(test::assert-equal '(5 6) (block xxx '(1 2) (block yyy ((fn (p) (return-from xxx p)) '(5 6)) '(a b)) '(2 3)))

(test::assert-equal '(2 3) (block xxx '(1 2) (block yyy (return-from yyy #t) '(a b)) '(2 3)))

(test::assert-equal '(5 6) (block yyy ((fn (p) (return-from yyy p)) '(5 6)) '(a b)) '(2 3))

(test::assert-equal 2

(block forloop

(for item in '(1 2 3)

(when (= 2 item)

(return-from forloop item)))

nil)) ; This nil keeps the for loop from being a tail call.

`dec!`	Type: Macro
`root::dec!`	`Usage: (dec! symbol [number]) -> new value`

Decrement the value in symbol by one or the optional number


Example:

(def *dec-test* 5)

(test::assert-equal 4 (dec! *dec-test*))

(test::assert-equal 4 *dec-test*)

(test::assert-error (dec! *dec-test* "xxx"))

(test::assert-equal 1 (dec! *dec-test* 3))

(test::assert-equal 1 *dec-test*)

(def *dec-test* "xxx")

(test::assert-error (dec! *dec-test*))

(let ((dec-test 5))

(test::assert-equal 4 (dec! dec-test))

(test::assert-equal 4 dec-test)

(test::assert-equal 1 (dec! dec-test 3))

(test::assert-equal 1 dec-test))

`def`	Type: SpecialForm
`root::def`	`Usage: (def symbol doc_string? expression) -> expression`

Adds an expression to the current namespace. Return the expression that was defined. Symbol is not evaluted. Can take an option doc string (docstrings can only be set on namespaced (global) symbols).


Example:

(def test-do-one nil)

(def test-do-two nil)

(def test-do-three (do (set! test-do-one "One")(set! test-do-two "Two")"Three"))

(test::assert-equal "One" test-do-one)

(test::assert-equal "Two" test-do-two)

(test::assert-equal "Three" test-do-three)

(let ((test-do-one nil))

; Add this to tthe let's scope (shadow the outer test-do-two).

(test::assert-equal "Default" (def ns::test-do-four "Default"))

; set the currently scoped value.

(set! test-do-one "1111")

(set! test-do-two "2222")

(test::assert-equal "1111" test-do-one)

(test::assert-equal "2222" test-do-two)

(test::assert-equal "Default" test-do-four))

; Original outer scope not changed.

(test::assert-equal "One" test-do-one)

(test::assert-equal "Default" test-do-four)

;(def (sym "test-do-one") "do one")

(test::assert-error (def (sym "test-do-one") "do one"))

;(test::assert-equal "do one" test-do-one)

(test::assert-error (def (sym->str test-do-one) "do one 2"))

`def?`	Type: SpecialForm
`root::def?`	`Usage: (def? expression) -> t\\|nil`

Return true if is a defined symbol (bound within the current scope). If expression is a symbol it is not evaluted and if a list it is evaluted to produce a symbol.


Example:

(def test-is-def #t)

(def test-is-def2 'test-is-def)

(test::assert-true (def? test-is-def))

(test::assert-true (def? (sym "test-is-def")))

(test::assert-true (def? (ref test-is-def2)))

(test::assert-false (def? test-is-def-not-defined))

(test::assert-false (def? (sym "test-is-def-not-defined")))

(test::assert-error (def? (ref test-is-def)))

`defmacro`	Type: Macro
`root::defmacro`	`Usage: (defmacro name doc_string? argument_list body)`

Create a macro and bind it to a symbol in the current scope.


Example:

(defmacro test-mac (x) (let ((y (+ (ref (ref x)) 1))) `(set! ,x ,y)))

(def test-mac-x 2)

(test-mac test-mac-x)

(test::assert-equal 3 test-mac-x)

(defmacro test-mac (x) `(set! ,x 15))

(test-mac test-mac-x)

(test::assert-equal 15 test-mac-x)

`defn`	Type: Macro
`root::defn`	`Usage: (defn name &rest args)`

Define a named function in the current namespace.


Example:

(defn defn-test (x y) (+ x y))

(test::assert-equal 5 (defn-test 2 3))

(defn defn-test (x y) (set! x (* x 2))(+ x y))

(test::assert-equal 7 (defn-test 2 3))

(defn defn-test (x y))

(test::assert-false (defn-test 2 3))

(defn defn-test (x y) #t)

(test::assert-true (defn-test 2 3))

`do`	Type: SpecialForm
`root::do`	`Usage: (do exp0 ... expN) -> expN`

Evaluatate each form and return the last.


Example:

(def test-do-one nil)

(def test-do-two nil)

(def test-do-three (do (set! test-do-one "One")(set! test-do-two "Two")"Three"))

(test::assert-equal "One" test-do-one)

(test::assert-equal "Two" test-do-two)

(test::assert-equal "Three" test-do-three)

`doc`	Type: Function
`root::doc`	`Usage: (doc symbol)`

Return the doc string for a symbol or nil if no string.


Example:

;(doc 'car)

#t

`doc-raw`	Type: Function
`root::doc-raw`	`Usage: (doc-raw symbol)`

Return the raw (unexpanded) doc string for a symbol or nil if no string.


Example:

;(doc-raw 'car)

#t

`dotimes`	Type: Macro
`root::dotimes`	`Usage: (dotimes times body)`

Evaluate body a number of times equal to times’ numerical value.


Example:

(def i 0)

(dotimes 11 (set! i (+ 1 i)))

(assert-equal 11 i)

`dotimes-i`	Type: Macro
`root::dotimes-i`	`Usage: (dotimes-i idx-bind times body)`

Evaluate body a number of times equal to times’ numerical value. Includes an incrementing reference binding, idx-bind, accessible in body.


Example:

(def i 0)

(def i-tot 0)

(dotimes-i idx 11 (do (set! i-tot (+ idx i-tot))(set! i (+ 1 i))))

(assert-equal 11 i)

(assert-equal 55 i-tot)

`dyn`	Type: Macro
`root::dyn`	`Usage: (dyn key value expression) -> result_of_expression`

Creates a dynamic binding for key, assigns value to it and evals expression under it. Note that if key must be a symbol and is not evaluted. The binding is gone once the dyn form ends. This is basically a set! on the binding in an unwind protect to reset it when done. When used on a global will set the first binding found and reset it when done. Calls to dyn can be nested and previous dynamic values will be restored as interior dyn’s exit.


Example:

(defn test-dyn-fn () (print "Print dyn out"))

(dyn *stdout* (open "/tmp/sl-sh.dyn.test" :create :truncate) (test-dyn-fn))

(test::assert-equal "Print dyn out" (read-line (open "/tmp/sl-sh.dyn.test" :read)))

`eprint`	Type: Function
`root::eprint`	`Usage: (eprint arg0 ... argN) -> nil`

Print the arguments (as strings) to stderr.


Example:

; Use a file for stderr for test.

(dyn *stderr* (open "/tmp/sl-sh.eprint.test" :create :truncate) (do (eprint "eprint test out")(eprint " two") (close *stderr*)))

(test::assert-equal "eprint test out two" (read-line (open "/tmp/sl-sh.eprint.test" :read)))

`eprintln`	Type: Function
`root::eprintln`	`Usage: (eprintln arg0 ... argN) -> nil`

Print the arguments (as strings) to stderr and then a newline.


Example:

; Use a file for stderr for test.

(dyn *stderr* (open "/tmp/sl-sh.eprintln.test" :create :truncate) (do (eprintln "eprintln test out")(eprintln "line two") (close *stderr*)))

(def topen (open "/tmp/sl-sh.eprintln.test" :read))

(test::assert-equal "eprintln test out

" (read-line topen))

(test::assert-equal "line two

" (read-line topen))

`err`	Type: Function
`root::err`	`Usage: (err string) -> raises an error`

Raise an error with the supplied string.


Example:

(def test-err-err (get-error (err "Test Error")))

(test::assert-equal :error (car test-err-err))

(test::assert-equal "Test Error" (cadr test-err-err))

`error-stack-off`	Type: Lambda
`root::error-stack-off`	`Usage: (error-stack-off)`

Currently a no-op, used to turn off error stacks.


Example:

; no-op

(error-stack-off)

`error-stack-on`	Type: Lambda
`root::error-stack-on`	`Usage: (error-stack-on)`

Currently a no-op, used to turn on error stacks.


Example:

; no-op

(error-stack-on)

`eval`	Type: Function
`root::eval`	`Usage: (eval expression)`

Evaluate the provided expression. If expression is a string read it to make an ast first to evaluate otherwise evaluate the expression (note eval is a function not a special form, the provided expression will be evaluated as part of call).


Example:

(def test-eval-one nil)

(eval (read "(set! test-eval-one \"ONE\")"))

(test::assert-equal "ONE" test-eval-one)

(eval '(set! test-eval-one "TWO"))

(test::assert-equal "TWO" test-eval-one)

`expand-macro`	Type: Function
`root::expand-macro`	`Usage: (expand-macro expression)`

Expands a macro expression. If that expansion is also a macro then expand it recursively. Just returns the expression if not a macro.


Example:

(test::assert-equal '(def xx "value") (expand-macro '(def xx "value")))

(defmacro mac-test-for

(bind in in_list body) (do

(if (not (= in 'in)) (err "Invalid test-mac-for: (test-mac-for [v] in [iterator] (body))"))

`((fn (,bind)

(if (> (length ,in_list) 0)

(root::loop (plist) (,in_list) (do

(set! ,bind (root::first plist))

(,@body)

(if (> (length plist) 1) (recur (root::rest plist)))))))nil)))

(test::assert-equal '(

(fn

(i)

(if

(> (length '(1 2 3)) 0)

(root::loop

(plist)

('(1 2 3))

(do

(set! i (root::first plist)) nil

(if

(> (length plist) 1)

(recur (root::rest plist))))))) nil)

(expand-macro '(mac-test-for i in '(1 2 3) ())))

(test::assert-equal '(1 2 3) (expand-macro '(1 2 3)))

`expand-macro-all`	Type: Function
`root::expand-macro-all`	`Usage: (expand-macro-all expression)`

Expands a macro expression like expand-macro but also expand any embedded macros. Just returns the expression if not a macro.


Example:

(test::assert-equal '(def xx "value") (expand-macro-all '(def xx "value")))

(defmacro mac-test-loop

(params bindings body)

`((fn ,params ,body) ,@bindings))

(defmacro mac-test-for

(bind in in_list body) (do

(if (not (= in 'in)) (err "Invalid test-mac-for: (test-mac-for [v] in [iterator] (body))"))

`((fn (,bind)

(if (> (length ,in_list) 0)

(mac-test-loop (plist) (,in_list) (do

(set! ,bind (root::first plist))

(,@body)

(if (> (length plist) 1) (recur (root::rest plist)))))))nil)))

(test::assert-equal '(

(fn

(i)

(if

(> (length '(1 2 3)) 0)

(

(fn

(plist)

(do

(set! i (root::first plist)) nil

(if

(> (length plist) 1)

(recur (root::rest plist)))))

'(1 2 3)))) nil)

(expand-macro-all '(mac-test-for i in '(1 2 3) ())))

(test::assert-equal '(1 2 3) (expand-macro-all '(1 2 3)))

`expand-macro1`	Type: Function
`root::expand-macro1`	`Usage: (expand-macro1 expression)`

Expands a macro expression. Only expand the first macro. Just returns the expression if not a macro.


Example:

(test::assert-equal '(def xx "value") (expand-macro1 '(def xx "value")))

(defmacro mac-test-for

(bind in in_list body) (do

(if (not (= in 'in)) (err "Invalid test-mac-for: (test-mac-for [v] in [iterator] (body))"))

`((fn (,bind)

(if (> (length ,in_list) 0)

(root::loop (plist) (,in_list) (do

(set! ,bind (root::first plist))

(,@body)

(if (> (length plist) 1) (recur (root::rest plist)))))))nil)))

(test::assert-equal '((fn

(i)

(if

(> (length '(1 2 3)) 0)

(root::loop

(plist)

('(1 2 3))

(do

(set! i (root::first plist)) nil

(if

(> (length plist) 1)

(recur (root::rest plist)))))))nil)

(expand-macro1 '(mac-test-for i in '(1 2 3) ())))

(test::assert-equal '(1 2 3) (expand-macro1 '(1 2 3)))

`fn`	Type: SpecialForm
`root::fn`	`Usage: (fn (param) expr) -> exprN`

Create a function (lambda).


Example:

(def test-fn1 nil)

(def test-fn2 nil)

(def test-fn3 nil)

(def test-fn-empty ((fn ())))

(test::assert-false test-fn-empty)

((fn () (set! test-fn1 1)))

(test::assert-equal 1 test-fn1)

((fn () (set! test-fn1 10)(set! test-fn2 2)))

(test::assert-equal 10 test-fn1)

(test::assert-equal 2 test-fn2)

((fn () (set! test-fn1 11)(set! test-fn2 20)(set! test-fn3 3)))

(test::assert-equal 11 test-fn1)

(test::assert-equal 20 test-fn2)

(test::assert-equal 3 test-fn3)

((fn (x y z) (set! test-fn1 x)(set! test-fn2 y)(set! test-fn3 z)) 12 21 30)

(test::assert-equal 12 test-fn1)

(test::assert-equal 21 test-fn2)

(test::assert-equal 30 test-fn3)

(test::assert-equal 63 ((fn (x y z) (set! test-fn1 x)(set! test-fn2 y)(set! test-fn3 z)(+ x y z)) 12 21 30))

`format`	Type: Function
`root::format`	`Usage: (format arg0 ... argN) -> string`

Build a formatted string from arguments. Arguments will be turned into strings.


Example:

(test::assert-equal "stringsome" (format "string" "some"))

(test::assert-equal "string" (format "string" ""))

(test::assert-equal "string 50" (format "string" " " 50))

(test::assert-equal "string 50 100.5" (format "string" " " 50 " " 100.5))

`gensym`	Type: Function
`root::gensym`	`Usage: (gensym) -> symbol`

Generate a unique symbol. Gensym uses a prefix of gs@@ followed by an incrementing counter. It is useful to generate unique symbol names when writing macros (for instance).


Example:

(def test-gensym-one (gensym))

(def test-gensym-two (gensym))

(def test-gensym-three (gensym))

(test::assert-true (str-starts-with "gs@@" (sym->str test-gensym-one)))

(test::assert-true (str-starts-with "gs@@" (sym->str test-gensym-two)))

(test::assert-true (str-starts-with "gs@@" (sym->str test-gensym-three)))

(test::assert-true (symbol? (gensym)))

(test::assert-true (symbol? test-gensym-one))

(test::assert-true (symbol? test-gensym-two))

(test::assert-true (symbol? test-gensym-three))

`get-error`	Type: Function
`root::get-error`	`Usage: (get-error exp0 ... expN) -> pair`

Evaluate each form (like do) but on error return (:error msg backtrace) instead of aborting. On success return (:ok . expN-result). If there is no error will return the value of the last expression as the cdr of the pair. Always returns a pair with the first value either being :ok or :error.


Example:

(def get-error-t1 (get-error (err "Some Error")))

(test::assert-equal :error (car get-error-t1))

(test::assert-equal "Some Error" (cadr get-error-t1))

(test::assert-true (vec? (caddr get-error-t1)))

(test::assert-equal '(:ok . "Some String") (get-error "Some String"))

(test::assert-equal '(:ok . "Some Other String") (get-error (def test-get-error "Some ") (str test-get-error "Other String")))

`identity`	Type: Lambda
`root::identity`	`Usage: (identity x)`

Identity function.


Example:

(assert-equal 0 (identity 0))

`inc!`	Type: Macro
`root::inc!`	`Usage: (inc! symbol [number]) -> new value`

Increment the value in symbol by one or the optional number


Example:

(def *inc-test* 1)

(test::assert-equal 2 (inc! *inc-test*))

(test::assert-equal 2 *inc-test*)

(test::assert-equal 5 (inc! *inc-test* 3))

(test::assert-error (inc! *inc-test* "xxx"))

(test::assert-equal 5 *inc-test*)

(def *inc-test* "xxx")

(test::assert-error (inc! *inc-test*))

(let ((inc-test 1))

(test::assert-equal 2 (inc! inc-test))

(test::assert-equal 2 inc-test)

(test::assert-equal 5 (inc! inc-test 3))

(test::assert-equal 5 inc-test))

`intern-stats`	Type: SpecialForm
`root::intern-stats`	`Usage: (intern-stats)`

Prints the stats for interned symbols.


Example:

;(intern-stats)

#t

`len0?`	Type: Macro
`root::len0?`	`Usage: (len0? thing)`

Is the length of thing 0?


Example:

(assert-true (len0? nil))

(assert-true (len0? '()))

(assert-true (len0? (vec)))

(assert-true (len0? (str)))

(assert-true (len0? ""))

(assert-false (len0? '(1)))

(assert-false (len0? (vec 1 2)))

(assert-false (len0? "string"))

`len>0?`	Type: Macro
`root::len>0?`	`Usage: (len>0? thing)`

Is the length of thing greater than 0?


Example:

(assert-false (len>0? nil))

(assert-false (len>0? '()))

(assert-false (len>0? (vec)))

(assert-false (len>0? (str)))

(assert-false (len>0? ""))

(assert-true (len>0? '(1)))

(assert-true (len>0? (vec 1 2)))

(assert-true (len>0? "string"))

`length`	Type: Function
`root::length`	`Usage: (length expression) -> int`

Return length of supplied expression.


Example:

(test::assert-equal 0 (length nil))

(test::assert-equal 5 (length \"12345\"))

; Note the unicode symbol is only one char even though it is more then one byte.

(test::assert-equal 6 (length \"12345Σ\"))

(test::assert-equal 3 (length '(1 2 3)))

(test::assert-equal 3 (length '#(1 2 3)))

(test::assert-equal 3 (length (list 1 2 3)))

(test::assert-equal 3 (length (vec 1 2 3)))

(test::assert-error (length 100))

(test::assert-error (length 100.0))

(test::assert-error (length #\\x))

`let`	Type: Macro
`root::let`	`Usage: (let vals &rest let-body)`

Takes list, vals, of form ((binding0 sexp0) (binding1 sexp1) …) and evaluates let-body with all values of binding bound to the result of the evaluation of sexp.


Example:

(def test-do-one "One1")

(def test-do-two "Two1")

(def test-do-three (let ((test-do-one "One")) (set! test-do-two "Two")(test::assert-equal "One" test-do-one)"Three"))

(test::assert-equal "One1" test-do-one)

(test::assert-equal "Two" test-do-two)

(test::assert-equal "Three" test-do-three)

((fn (idx) (let ((v2 (+ idx 2))(v3 (+ idx 3)))

(test::assert-equal (+ idx 2) v2)

(test::assert-equal (+ idx 3) v3)

(if (< idx 5) (recur (+ idx 1)))))0)

((fn (idx) (let ((v2 (+ idx 2))(v3 (+ idx 3)))

(test::assert-equal (+ idx 2) v2)

(test::assert-equal (+ idx 3) v3)

(if (< idx 5) (this-fn (+ idx 1)))))0)

`let*`	Type: Macro
`root::let*`	`Usage: (let* vals &rest let-body)`

Takes list, vals, of form ((binding0 sexp0) (binding1 sexp1) …) and evaluates let-body with all values of binding bound to the result of the evaluation of sexp. Differs from let in that sexps can reference bindings from previous items in the list of vals.


Example:

(let* ((add-one (fn (x) (+ 1 x)))

(double-add (fn (x) (add-one (add-one x)))))

(test::assert-equal 4 (add-one 3))

(test::assert-equal 6 (double-add 4)))

`loop`	Type: Macro
`root::loop`	`Usage: (loop params bindings &rest body)`

Binds bindings to parameters in body. Use recur with desired bindings for subsequent iteration. Within the loop the lambda ‘break’ will end the loop, break can take an option argument that is what the loop produces (nil if no argument).


Example:

(def tot 0)

(loop (idx) (3) (do

(set! tot (+ tot 1))

(if (> idx 1) (recur (- idx 1)))))

(assert-equal 3 tot)

(def tot 0)

(loop (idx) (0)

(set! tot (+ tot 1))

(if (= idx 2) (break))

(recur (+ idx 1)))

(assert-equal 3 tot)

(assert-equal 11 (loop (idx) (0)

(if (= idx 2) (break 11))

(recur (+ idx 1))))

(assert-false (loop (idx) (0)

(if (= idx 2) (break))

(recur (+ idx 1))))

(assert-error (loop (idx) (0)

(if (= idx 2) (break 1 3))

(recur (+ idx 1))))

`macro`	Type: SpecialForm
`root::macro`	Usage: (macro (args) `(apply + ,@args))

Define an anonymous macro.


Example:

(def test-macro1 nil)

(def test-macro2 nil)

(def test-macro-empty (macro ()))

(test::assert-false (test-macro-empty))

(def test-mac nil)

(def mac-var 2)

(let ((mac-var 3))

(set! test-mac (macro (x) (set! test-macro2 100)(test::assert-equal 3 mac-var)`(* ,mac-var ,x))))

(set! test-macro1 (test-mac 10))

(test::assert-equal 30 test-macro1)

(test::assert-equal 100 test-macro2)

`maybe-docstring?`	Type: Lambda
`root::maybe-docstring?`	`Usage: (maybe-docstring? form)`

True if form might be a docstring, nil otherwise.


Example:

(test::assert-true (maybe-docstring? "string"))

(test::assert-true (maybe-docstring? '(str 1 2 3)))

(test::assert-false (maybe-docstring? '(1 2 3)))

`meta-add-tags`	Type: Function
`root::meta-add-tags`	`Usage: (meta-add-tags expression tag*)`

Adds multiple meta tags to an expression. It will work with symbols or vectors or lists of symbols (or any combination). This is intended for helping with structs and interfaces in lisp, you probably do not want to use it.


Example:

(def meta-add-tags-var '(1 2 3))

(meta-add-tags meta-add-tags-var :tag1)

(test::assert-true (meta-tag? meta-add-tags-var :tag1))

(test::assert-false (meta-tag? meta-add-tags-var :tag2))

(meta-add-tags meta-add-tags-var :tag2 '(:tag3 :tag4) '#(:tag5 :tag6) :tag7)

(test::assert-true (meta-tag? meta-add-tags-var :tag2))

(test::assert-true (meta-tag? meta-add-tags-var :tag3))

(test::assert-true (meta-tag? meta-add-tags-var :tag4))

(test::assert-true (meta-tag? meta-add-tags-var :tag5))

(test::assert-true (meta-tag? meta-add-tags-var :tag6))

(test::assert-true (meta-tag? meta-add-tags-var :tag7))

`meta-column-no`	Type: SpecialForm
`root::meta-column-no`	`Usage: (meta-column-no)`

Column number from the file this came from.


Example:

;(meta-column-no)

#t

`meta-file-name`	Type: SpecialForm
`root::meta-file-name`	`Usage: (meta-file-name)`

File name of the file this came from.


Example:

;(meta-file-name)

#t

`meta-line-no`	Type: SpecialForm
`root::meta-line-no`	`Usage: (meta-line-no)`

Line number from the file this came from.


Example:

;(meta-line-no)

#t

`meta-tag?`	Type: Function
`root::meta-tag?`	`Usage: (meta-tag? expression tag)`

True if expression has the meta tag ‘tag’ set. This is intended for helping with structs and interfaces in lisp, you probably do not want to use it.


Example:

(def meta-add-tag-var '(1 2 3))

(meta-add-tags meta-add-tag-var :tag1)

(test::assert-true (meta-tag? meta-add-tag-var :tag1))

(test::assert-false (meta-tag? meta-add-tag-var :tag2))

`nsubstitute!`	Type: Lambda
`root::nsubstitute!`	`Usage: (nsubstitute! new-item old-item lst &rest mods)`

Replaces all instances of old-item in lst with new-item. If last argument passed in is keyword :first only the first instance of old-item will be replaced.


Example:

(let ((lst (list 1 2 3 4 5)))

(test::assert-equal (list 1 2 10 4 5) (nsubstitute! 10 3 lst))

(test::assert-equal (list 1 2 10 4 5) lst))

`occurs`	Type: Lambda
`root::occurs`	`Usage: (occurs (list 1 2 ...) 7) (occurs (list 1 2 ...) 0 (fn (x) (% x 2)))`

Counts instances of item in sequence. Optional third argument is a function that can be applied to the specific element in the list before equality is tested with item.


Example:

(test::assert-equal 7 (occurs (list 1 3 5 2 4 10 2 4 88 2 1) 0 (fn (x) (% x 2))))

(test::assert-equal 3 (occurs (list 1 3 5 2 4 10 2 4 88 2 1) 2))

(test::assert-equal 0 (occurs (list 1 3 5 2 4 10 2 4 88 2 1) 42))

(test::assert-equal 2 (occurs (list 1 3 5 2 4 10 2 4 88 2 1) 8 (fn (x) (* x 2))))

`print`	Type: Function
`root::print`	`Usage: (print arg0 ... argN) -> nil`

Print the arguments (as strings) to stdout.


Example:

; Use a file for stdout for test.

(dyn *stdout* (open "/tmp/sl-sh.print.test" :create :truncate) (do (print "Print test out")(print " two") (close *stdout*)))

(test::assert-equal "Print test out two" (read-line (open "/tmp/sl-sh.print.test" :read)))

`print-error`	Type: Lambda
`root::print-error`	`Usage: (print-error error)`

Prints out an error with a backtrace. Used with the return of get-error when it produces an error


Example:

(let

((print-error-test (get-error (err "Oops!")))

(file-name "$(temp-dir)/print-error.test")

(topen))

(out> file-name (print-error print-error-test))

(set! topen (open file-name :read))

(test::assert-true (> (length (read-line topen)) 5))

(close topen))

`println`	Type: Function
`root::println`	`Usage: (println arg0 ... argN) -> nil`

Print the arguments (as strings) to stdout and then a newline.


Example:

; Use a file for stdout for test.

(dyn *stdout* (open "/tmp/sl-sh.println.test" :create :truncate) (do (println "Println test out")(println "line two") (close *stdout*)))

(def topen (open "/tmp/sl-sh.println.test" :read))

(test::assert-equal "Println test out

" (read-line topen))

(test::assert-equal "line two

" (read-line topen))

`quote`	Type: SpecialForm
`root::quote`	`Usage: 'expression -> expression`

Return expression without evaluation. The reader macro ‘expression will expand to (quote expression).


Example:

(test::assert-equal (list 1 2 3) (quote (1 2 3)))

(test::assert-equal (list 1 2 3) '(1 2 3))

(test::assert-equal '(1 2 3) (quote (1 2 3)))

`reader-macro-dot`	Type: Lambda
`root::reader-macro-dot`	`Usage: (reader-macro-dot stream ch)`

Reader macro for #.(…). Do not call directly.


Example:

(def dot-test (read "(1 2 #.(* 3 10) #.(str "o" "ne"))))

(test::assert-equal '(1 2 30 "one"))

`recur`	Type: Function
`root::recur`	`Usage: (recur &rest)`

Recursively call the enclosing function with the given parameters. Recur uses tail call optimization and must be in the tail position or it is an error. For a named function it would be equivalent to a normal recursive call in a tail position but it requires a tail position and does not need a name (a normal recursive call would work in a non-tail position but could blow the stack if it is to deep- unlike a recur or tail position recursive call). NOTE: potential footgun, the let macro expands to a lambda (fn) and a recur used inside the let would bind with the let not the enclosing lambda (this would apply to any macro that also expands to a lamda- this is by design with the loop macro but would be unexpected with let).


Example:

(def tot 0)

(loop (idx) (3) (do

(set! tot (+ tot 1))

(if (> idx 1) (recur (- idx 1)))))

(assert-equal 3 tot)

(set! tot 0)

((fn (idx) (do

(set! tot (+ tot 1))

(if (> idx 1) (recur (- idx 1)))))5)

(assert-equal 5 tot)

`ref`	Type: SpecialForm
`root::ref`	`Usage: (ref symbol) -> expression`

Return the expression that is referenced by symbol. Symbol is only evaluated if a list (that produces a symbol) and must be bound in the current scope or an error is raised.


Example:

(def test-is-def #t)

(def test-is-def2 'test-is-def)

(test::assert-true (ref test-is-def))

(set! test-is-def '(1 2 3))

(test::assert-equal '(1 2 3) (ref test-is-def))

(test::assert-error (ref test-is-def-no-exist))

(test::assert-error (ref (ref test-is-def)))

(test::assert-equal '(1 2 3) (ref (ref test-is-def2)))

`return-from`	Type: SpecialForm
`root::return-from`	`Usage: (return-from name expression?)`

Causes enclosing block with name (name is not evaluated) to evaluate to expression.


Example:

(test::assert-equal '(4 5) (block xxx '(1 2) (return-from xxx '(4 5)) '(a b) '(2 3)))

(test::assert-equal '(4 5) (block xxx '(1 2) (return-from nil '(4 5)) '(a b) '(2 3)))

(test::assert-equal '(5 6) (block xxx '(1 2) (block yyy (return-from xxx '(5 6)) '(a b)) '(2 3)))

(test::assert-equal '(5 6) (block xxx '(1 2) (block yyy ((fn (p) (return-from xxx p)) '(5 6)) '(a b)) '(2 3)))

(test::assert-equal '(2 3) (block xxx '(1 2) (block yyy (return-from yyy #t) '(a b)) '(2 3)))

`set!`	Type: SpecialForm
`root::set!`	`Usage: (set! symbol expression) -> expression`

Sets an existing expression in the current scope(s). Return the expression that was set. Symbol is not evaluted. Set will set the first binding it finds starting in the current scope and then trying enclosing scopes until exhausted.


Example:

(def test-do-one nil)

(def test-do-two nil)

(def test-do-three (do (set! test-do-one "One")(set! test-do-two "Two")"Three"))

(test::assert-equal "One" test-do-one)

(test::assert-equal "Two" test-do-two)

(test::assert-equal "Three" test-do-three)

(let ((test-do-one nil))

; set the currently scoped value.

(test::assert-equal "1111" (set! test-do-one "1111"))

(test::assert-equal "1111" test-do-one))

; Original outer scope not changed.

(test::assert-equal "One" test-do-one)

;(set! (sym "test-do-one") "do one")

;(test::assert-equal "do one" test-do-one)

(test::assert-error (set! (sym->str test-do-one) "do one 2"))

`substitute`	Type: Macro
`root::substitute`	`Usage: (substitute new-item old-item lst &rest mods)`

Replaces all instances of old-item in copy of lst with new-item. If last argument passed in is keyword :first only the first instance of old-item will be replaced.


Example:

(let ((lst (list 1 2 3 4 5))

(lst2 (list 1 2 3 3 3 4 5)))

(test::assert-equal (list 1 2 10 4 5) (substitute 10 3 lst))

(test::assert-equal lst lst)

(test::assert-equal (list 1 2 4 4 4 4 5) (substitute 4 3 lst2))

(test::assert-equal (list 1 2 4 3 3 4 5) (substitute 4 3 lst2 :first)))

`undef`	Type: SpecialForm
`root::undef`	`Usage: (undef symbol) -> expression`

Remove a symbol from the current namespace (if it exists). Returns the expression that was removed. It is an error if symbol is not defined in the current namespace. Symbol is not evaluted.


Example:

(def test-undef nil)

(test::assert-true (def? test-undef))

(undef test-undef)

(test::assert-false (def? test-undef))

(def test-undef "undef")

(test::assert-equal "undef" (undef test-undef))

(test::assert-false (def? test-undef))

(test::assert-equal "undef: symbol test-undef not defined in current scope (can only undef symbols in current scope)." (cadr (get-error (undef test-undef))))

`unwind-protect`	Type: Function
`root::unwind-protect`	`Usage: (unwind-protect protected cleanup*) -> [protected result]`

After evaluation first form, make sure the following cleanup forms run (returns first form’s result).


Example:

(def test-unwind-one nil)

(def test-unwind-err (get-error

(unwind-protect (err "Some protected error") (set! test-unwind-one "got it"))))

(test::assert-equal :error (car test-unwind-err))

(test::assert-equal "Some protected error" (cadr test-unwind-err))

(test::assert-equal "got it" test-unwind-one)

(def test-unwind-one nil)

(def test-unwind-two nil)

(def test-unwind-three nil)

(def test-unwind-four nil)

(def test-unwind-err (get-error

(unwind-protect

(do (set! test-unwind-one "set one")(err "Some protected error two")(set! test-unwind-two "set two"))

(set! test-unwind-three "set three")(set! test-unwind-four "set four"))))

(test::assert-equal :error (car test-unwind-err))

(test::assert-equal "Some protected error two" (cadr test-unwind-err))

(test::assert-equal "set one" test-unwind-one)

(test::assert-equal nil test-unwind-two)

(test::assert-equal "set three" test-unwind-three)

(test::assert-equal "set four" test-unwind-four)

`values`	Type: Function
`root::values`	`Usage: (values expression*)`

Produces a multi values object. Useful for returning more then one value from a function when most of time you only care about the first (primary) item. When evaluting a muti values object it will evaluate as if it the first item only.


Example:

(test::assert-true (values? (values 1 "str" 5.5)))

(test::assert-equal 1 (values-nth 0 (values 1 "str" 5.5)))

(test::assert-equal "str" (values-nth 1 (values 1 "str" 5.5)))

(test::assert-equal 5.5 (values-nth 2 (values 1 "str" 5.5)))

`values-length`	Type: Function
`root::values-length`	`Usage: (values-length expression)`

If expression is a values object then return it’s length (number of values).


Example:

(test::assert-equal 3 (values-length (values 1 "str" 5.5)))

(test::assert-equal 2 (values-length (values 1 "str")))

(test::assert-equal 1 (values-length (values "str")))

(test::assert-equal 0 (values-length (values)))

(test::assert-equal "str" (values-nth 1 (values 1 "str" 5.5)))

(test::assert-equal 5.5 (values-nth 2 (values 1 "str" 5.5)))

(def test-vals-len (values 1 "str" 5.5))

(test::assert-equal 3 (values-length test-vals-len))

`values-nth`	Type: Function
`root::values-nth`	`Usage: (values-nth idx expression)`

If expression is a values object then return the item at index idx.


Example:

(test::assert-equal 1 (values-nth 0 (values 1 "str" 5.5)))

(test::assert-equal "str" (values-nth 1 (values 1 "str" 5.5)))

(test::assert-equal 5.5 (values-nth 2 (values 1 "str" 5.5)))

(def test-vals-nth (values 1 "str" 5.5))

(test::assert-equal 1 (values-nth 0 test-vals-nth))

(test::assert-equal "str" (values-nth 1 test-vals-nth))

(test::assert-equal 5.5 (values-nth 2 test-vals-nth))

`var`	Type: SpecialForm
`root::var`	`Usage: (var symbol expression) -> expression`

NOTE: var is deprecated, use let or let* to create local bindings. Adds an expression to the current lexical scope. Return the expression that was defined. This will not add to a namespace (use def for that), use it within functions or let forms to create local bindings. Symbol is not evaluated.


Example:

(let (())

(var test-do-one nil)

(var test-do-two nil)

(var test-do-three (do (set! test-do-one "One")(set! test-do-two "Two")"Three"))

(test::assert-equal "One" test-do-one)

(test::assert-equal "Two" test-do-two)

(test::assert-equal "Three" test-do-three)

(let ((test-do-one nil))

; Add this to the let's scope (shadow the outer test-do-two).

(test::assert-equal "Default" (var test-do-two "Default"))

; set the currently scoped value.

(set! test-do-one "1111")

(set! test-do-two "2222")

(test::assert-equal "1111" test-do-one)

(test::assert-equal "2222" test-do-two))

; Original outer scope not changed.

(test::assert-equal "One" test-do-one)

(test::assert-equal "Two" test-do-two))

File forms

Options to open, one or more of these can be added to open after the filename. A file can only be opened for reading or writing (read is default).

Option	Description
:read	Open file for reading, this is the default.
:write	Open file for writing.
:append	Open file for writing and append new data to end.
:truncate	Open file for write and delete all existing data.
:create	Create the file if it does not exist and open for writing.
:create-new	Create if does not exist, error if it does and open for writing.
:on-error-nil	If open has an error then return nil instead of producing an error.

Notes on closing. Files will close when they go out of scope. Using close will cause a reference to a file to be marked close (removes that reference). If there are more then one references to a file it will not actually close until all are released. Close will also flush the file even if it is not the final reference. If a reference to a file is captured in a closure that can also keep it open (closures currently capture the entire scope not just used symbols).

`cd`	Type: Function
`root::cd`	`Usage: (cd dir-to-change-to)`

Change directory.


Example:

(syscall 'mkdir "/tmp/tst-fs-cd")

(syscall 'touch "/tmp/tst-fs-cd/fs-cd-marker")

(test::assert-false (fs-exists? "fs-cd-marker"))

(pushd "/tmp/tst-fs-cd")

(root::cd "/tmp")

(root::cd "/tmp/tst-fs-cd")

(test::assert-true (fs-exists? "fs-cd-marker"))

(syscall 'rm "/tmp/tst-fs-cd/fs-cd-marker")

(popd)

(syscall 'rmdir "/tmp/tst-fs-cd")

`close`	Type: Function
`root::close`	`Usage: (close file)`

Close a file.


Example:

(def tmp (get-temp))

(def tst-file (open (str tmp "/slsh-tst-open.txt") :create :truncate))

(write-line tst-file "Test Line Two")

(close tst-file)

(def tst-file (open (str tmp "/slsh-tst-open.txt") :read))

(test::assert-equal "Test Line Two

" (read-line tst-file))

(close tst-file)

`collate-fs-changes`	Type: Lambda
`root::collate-fs-changes`	`Usage: (collate-fs-changes file-or-dir-to-watch)`

Takes a file or directory to watch and returns a function that encloses the state of the file or directory (and all its contents). When the resultant function is called it returns a map whose keys are the types of change: :created , :deleted, and :modified and values are vectors of files subject to the change. Each invocation encloses the state of the previous invocation and can be called at any time to report change sets since the last invocation. sample return value: (make-hash ((:modified . #(“/tmp/collate-fs-changes”)) (:deleted . #()) (:created . #(“/tmp/collate-fs-changes/foo1.txt”))))


Example:

(defn test-collate (collate-test-dir)

(let* ((collate-test-file0 (get-temp-file collate-test-dir))

(collator (collate-fs-changes collate-test-dir))

(collate-test-file1 (get-temp-file collate-test-dir))

(slp (sleep 100))

(changes (collator)))

(test::assert-equal (vec collate-test-file1) (hash-get changes :created))

(test::assert-equal (make-vec) (hash-get changes :deleted))

(let ((tst-file (open collate-test-file0 :truncate)))

(write-string tst-file "boop")

(flush tst-file)

(close tst-file))

(sleep 100)

(set! changes (collator))

(test::assert-equal (vec collate-test-file0) (hash-get changes :modified))

(test::assert-equal (make-vec) (hash-get changes :deleted))

(test::assert-equal (make-vec) (hash-get changes :created))

(fs-rm collate-test-dir)

(sleep 100)

(set! changes (collator))

(test::assert-equal (make-vec) (hash-get changes :created))

(test::assert-equal (make-vec) (hash-get changes :modified))

(let ((del-items (hash-get changes :deleted)))

(test::assert-equal 3 (length del-items))

(test::assert-includes collate-test-dir del-items)

(test::assert-includes collate-test-file0 del-items)

(test::assert-includes collate-test-file1 del-items))))

(with-temp (fn (tmp-dir)

(let ((a-dir (get-temp tmp-dir)))

(test-collate a-dir))))

`flush`	Type: Function
`root::flush`	`Usage: (flush file)`

Flush a file.


Example:

(def tmp (get-temp))

(def tst-file (open (str tmp \"/slsh-tst-open.txt\") :create :truncate))

(write-line tst-file \"Test Line Three\")

(flush tst-file)

(def tst-file (open (str tmp \"/slsh-tst-open.txt\") :read))

(test::assert-equal \"Test Line Three\n\" (read-line tst-file))

(close tst-file)

`fs-accessed`	Type: Function
`root::fs-accessed`	`Usage: (fs-accessed /path/to/file/or/dir)`

Returns the unix time file last accessed in ms.


Example:

(with-temp-file (fn (tmp)

(let ((tst-file (open tmp :read))

(last-acc (fs-accessed tmp)))

(close tst-file)

(let ((tst-file (open tmp :read)))

(test::assert-true (> (fs-accessed tmp) last-acc))

(close tst-file))))

`fs-base`	Type: Function
`root::fs-base`	`Usage: (fs-base /path/to/file/or/dir)`

Returns base name of file or directory passed to function.


Example:

(with-temp (fn (tmp)

(let ((tmp-file (temp-file tmp)))

(test::assert-equal (length \".tmp01234\") (length (fs-base tmp-file))))))

`fs-crawl`	Type: Function
`root::fs-crawl`	`Usage: (fs-crawl /path/to/file/or/dir (fn (x) (println "found path" x) [max-depth]`

[:follow-syms]) If a directory is provided the path is recursively searched and every file and directory is called as an argument to the provided function. If a file is provided the path is provided as an argument to the provided function. Takes two optional arguments (in any order) an integer, representing max depth to traverse if file is a directory, or the symbol, :follow-syms, to follow symbol links when traversing if desired.


Example:

(with-temp-file (fn (tmp-file)

(def cnt 0)

(fs-crawl tmp-file (fn (x)

(test::assert-equal (fs-base tmp-file) (fs-base x))

(set! cnt (+ 1 cnt))))

(test::assert-equal 1 cnt)))

(defn create-in (in-dir num-files visited)

(dotimes-i i num-files

(hash-set! visited (get-temp-file in-dir) nil)))

(defn create-dir (tmp-dir visited)

(let ((new-tmp (get-temp tmp-dir)))

(hash-set! visited new-tmp nil)

new-tmp))

(with-temp (fn (root-tmp-dir)

(let ((tmp-file-count 5)

(visited (make-hash)))

(def cnt 0)

(hash-set! visited root-tmp-dir nil)

(create-in root-tmp-dir tmp-file-count visited)

(let* ((tmp-dir (create-dir root-tmp-dir visited))

(new-files (create-in tmp-dir tmp-file-count visited))

(tmp-dir (create-dir tmp-dir visited))

(new-files (create-in tmp-dir tmp-file-count visited)))

(fs-crawl root-tmp-dir (fn (x)

(let ((file (hash-get visited x)))

(test::assert-true (not file)) ;; also tests double counting

(hash-set! visited x #t)

(set! cnt (+ 1 cnt)))))

(test::assert-equal (+ 3 (* 3 tmp-file-count)) cnt)

(test::assert-equal (+ 3 (* 3 tmp-file-count)) (length (hash-keys visited)))

(iterator::map (fn (x) (test::assert-true (hash-get visited y))) (hash-keys visited))))))

(with-temp (fn (root-tmp-dir)

(let ((tmp-file-count 5)

(visited (make-hash)))

(def cnt 0)

(hash-set! visited root-tmp-dir nil)

(create-in root-tmp-dir tmp-file-count visited)

(let* ((tmp-dir (create-dir root-tmp-dir visited))

(new-files (create-in tmp-dir tmp-file-count visited))

(tmp-dir (create-dir tmp-dir (make-hash)))

(new-files (create-in tmp-dir tmp-file-count (make-hash))))

(fs-crawl root-tmp-dir (fn (x)

(let ((file (hash-get visited x)))

(test::assert-true (not file)) ;; also tests double counting

(hash-set! visited x #t)

(set! cnt (+ 1 cnt)))) 2)

(test::assert-equal (+ 3 (* 2 tmp-file-count)) cnt)

(test::assert-equal (+ 3 (* 2 tmp-file-count)) (length (hash-keys visited)))

(iterator::map (fn (x) (test::assert-true (hash-get visited y))) (hash-keys visited))))))

(with-temp (fn (root-tmp-dir)

(let ((tmp-file-count 5)

(visited (make-hash)))

(def cnt 0)

(hash-set! visited root-tmp-dir nil)

(create-in root-tmp-dir tmp-file-count visited)

(let* ((tmp-dir (create-dir root-tmp-dir (make-hash)))

(new-files (create-in tmp-dir tmp-file-count (make-hash)))

(tmp-dir (create-dir tmp-dir (make-hash)))

(new-files (create-in tmp-dir tmp-file-count (make-hash))))

(fs-crawl root-tmp-dir (fn (x)

(let ((file (hash-get visited x)))

(test::assert-true (not file)) ;; also tests double counting

(hash-set! visited x #t)

(set! cnt (+ 1 cnt)))) 1)

(test::assert-equal (+ 2 tmp-file-count) cnt)

(test::assert-equal (+ 2 tmp-file-count) (length (hash-keys visited)))

(iterator::map (fn (x) (test::assert-true (hash-get visited y))) (hash-keys visited))))))

`fs-dir?`	Type: Function
`root::fs-dir?`	`Usage: (fs-dir? path-to-test)`

Is the given path a directory?


Example:

$(mkdir /tmp/tst-fs-dir)

$(touch /tmp/tst-fs-dir/fs-dir-file)

(test::assert-false (fs-dir? "/tmp/tst-fs-dir/fs-dir-file"))

(test::assert-true (fs-dir? "/tmp/tst-fs-dir"))

(test::assert-false (fs-dir? "/tmp/tst-fs-dir/fs-dir-nope"))

$(rm /tmp/tst-fs-dir/fs-dir-file)

$(rmdir /tmp/tst-fs-dir)

`fs-exists?`	Type: Function
`root::fs-exists?`	`Usage: (fs-exists? path-to-test)`

Does the given path exist?


Example:

$(mkdir /tmp/tst-fs-exists)

$(touch /tmp/tst-fs-exists/fs-exists)

(test::assert-true (fs-exists? "/tmp/tst-fs-exists/fs-exists"))

(test::assert-true (fs-exists? "/tmp/tst-fs-exists"))

(test::assert-false (fs-exists? "/tmp/tst-fs-exists/fs-exists-nope"))

$(rm /tmp/tst-fs-exists/fs-exists)

$(rmdir /tmp/tst-fs-exists)

`fs-file?`	Type: Function
`root::fs-file?`	`Usage: (fs-file? path-to-test)`

Is the given path a file?


Example:

$(mkdir /tmp/tst-fs-file)

$(touch "/tmp/tst-fs-file/fs-file")

(test::assert-true (fs-file? "/tmp/tst-fs-file/fs-file"))

(test::assert-false (fs-file? "/tmp/tst-fs-file"))

(test::assert-false (fs-file? "/tmp/tst-fs-file/fs-file-nope"))

$(rm "/tmp/tst-fs-file/fs-file")

$(rmdir /tmp/tst-fs-file)

`fs-len`	Type: Function
`root::fs-len`	`Usage: (fs-len /path/to/file/or/dir)`

Returns the size of the file in bytes.


Example:

(with-temp-file (fn (tmp)

(let ((tst-file (open tmp :create :truncate)))

(write-line tst-file \"Test Line Read Line One\")

(write-string tst-file \"Test Line Read Line Two\")

(flush tst-file)

(close tst-file)

(println \"fs-len is: \" (fs-len tst-file))

(test::assert-equal 47 (fs-len tst-file)))))

`fs-modified`	Type: Function
`root::fs-modified`	`Usage: (fs-modified /path/to/file/or/dir)`

Returns the unix time file last modified in ms.


Example:

(with-temp-file (fn (tmp)

(let ((tst-file (open tmp :create :truncate))

(last-mod (fs-modified tmp)))

(write-line tst-file \"Test Line Read Line One\")

(write-string tst-file \"Test Line Read Line Two\")

(flush tst-file)

(close tst-file)

(test::assert-true (> (fs-modified tmp) last-mod)))))

`fs-notify`	Type: Lambda
`root::fs-notify`	`Usage: (fs-notify callback to-watch &rest args)`

fs-notify is designed to notify the caller of changes to a file or directory heirarchy via a callback that accepts two arguments, the file that changed and the type of change: :created, :deleted, xor :modified. Takes a callback and file or directory to watch for changes and the number of milliseconds to sleep before checking for changes to the provided file/directory hierarchy. This function loops forever, and calls the callback whenever it detects a change. This function relies on the function collate-fs-changes to compute differences. The following invocation of fs-notify prints out every change event for the provided directory, polling every 250ms by default. (fs-notify (fn (f e) (println “file: “ f “, event: “ e)) “/dir/to/watch”) This incovation provides an optional arg to specify the polling rate in ms. (fs-notify (fn (f e) (println “file: “ f “, event: “ e)) “/dir/to/watch” 1000)


Example:

#t

`fs-parent`	Type: Function
`root::fs-parent`	`Usage: (fs-parent /path/to/file/or/dir)`

Returns base name of file or directory passed to function.


Example:

(with-temp (fn (tmp)

(let ((tmp-file (get-temp-file tmp)))

(test::assert-true (fs-same? (fs-parent tmp-file) tmp)))))

`fs-rm`	Type: Function
`root::fs-rm`	`Usage: (fs-rm \"/dir/or/file/to/remove\")`

Takes a file or directory as a string and removes it. Works recursively for directories.


Example:

(def fp nil)

(let* ((a-file (get-temp-file)))

(test::assert-true (fs-exists? a-file))

(set! fp a-file)

(fs-rm a-file)))

(test::assert-false (nil? fp))

(test::assert-false (fs-exists? fp))

`fs-same?`	Type: Function
`root::fs-same?`	`Usage: (fs-same? /path/to/file/or/dir /path/to/file/or/dir)`

Returns true if the two provided file paths refer to the same file or directory.


Example:

(with-temp-file (fn (tmp-file)

(test::assert-true (fs-same? tmp-file tmp-file)))

`get-temp`	Type: Function
`root::get-temp`	`Usage: (get-temp [\"/path/to/directory/to/use/as/base\" \"optional-prefix\" \"optional-suffix\" length])`

Creates a directory inside of an OS specific temporary directory. See temp-dir for OS specific notes. Also accepts an optional prefix, an optional suffix, and an optional length for the random number of characters in the temporary file created. Defaults to prefix of ".tmp", no suffix, and five random characters.


Example:

(test::assert-true (str-contains (temp-dir) (get-temp)))

(with-temp (fn (tmp)

(let ((tmp-dir (get-temp tmp)))

(test::assert-true (str-contains tmp tmp-dir)))))

(with-temp (fn (tmp)

(let ((tmp-dir (get-temp tmp \"some-prefix\")))

(test::assert-true (str-contains tmp tmp-dir))

(test::assert-true (str-contains \"some-prefix\" tmp-dir)))))

(with-temp (fn (tmp)

(let ((tmp-dir (get-temp tmp \"some-prefix\" \"some-suffix\")))

(test::assert-true (str-contains tmp tmp-dir))

(test::assert-true (str-contains \"some-prefix\" tmp-dir))

(test::assert-true (str-contains \"some-suffix\" tmp-dir)))))

(with-temp (fn (tmp)

(let ((tmp-dir (get-temp tmp \"some-prefix\" \"some-suffix\" 6)))

(test::assert-true (str-contains tmp tmp-dir))

(test::assert-true (str-contains \"some-prefix\" tmp-dir))

(test::assert-true (str-contains \"some-suffix\" tmp-dir))

(test::assert-equal (length \"some-prefix012345some-suffix\") (length (fs-base tmp-dir))))))

`get-temp-file`	Type: Function
`root::get-temp-file`	`Usage: (get-temp-file [\"/path/to/directory/to/use/as/base\" \"optional-prefix\" \"optional-suffix\" length])`

Returns name of file created inside temporary directory. Optionally takes a directory to use as the parent directory of the temporary file. Also accepts an optional prefix, an optional suffix, and an optional length for the random number of characters in the temporary files created. Defaults to prefix of ".tmp", no suffix, and five random characters.


Example:

(test::assert-true (str-contains (temp-dir) (get-temp-file)))

(with-temp (fn (tmp)

(let ((tmp-file (get-temp-file tmp)))

(test::assert-true (str-contains tmp tmp-file)))))

(with-temp (fn (tmp)

(let ((tmp-file (get-temp-file tmp \"some-prefix\")))

(test::assert-true (str-contains \"some-prefix\" tmp-file)))))

(with-temp (fn (tmp)

(let ((tmp-file (get-temp-file tmp \"some-prefix\" \"some-suffix\")))

(test::assert-true (str-contains \"some-prefix\" tmp-file))

(test::assert-true (str-contains \"some-suffix\" tmp-file)))))

(with-temp (fn (tmp)

(let ((tmp-file (get-temp-file tmp \"some-prefix\" \"some-suffix\" 10)))

(test::assert-true (str-contains \"some-prefix\" tmp-file))

(test::assert-true (str-contains \"some-suffix\" tmp-file))

(test::assert-equal (length \"some-prefix0123456789some-suffix\") (length (fs-base tmp-file))))))

`glob`	Type: Function
`root::glob`	`Usage: (glob /path/with/*)`

Takes a list/varargs of globs and return the list of them expanded.


Example:

(syscall 'mkdir "/tmp/tst-fs-glob")

(syscall 'touch "/tmp/tst-fs-glob/g1")

(syscall 'touch "/tmp/tst-fs-glob/g2")

(syscall 'touch "/tmp/tst-fs-glob/g3")

(test::assert-equal '("/tmp/tst-fs-glob/g1" "/tmp/tst-fs-glob/g2" "/tmp/tst-fs-glob/g3") (glob "/tmp/tst-fs-glob/*"))

(syscall 'rm "/tmp/tst-fs-glob/g1")

(syscall 'rm "/tmp/tst-fs-glob/g2")

(syscall 'rm "/tmp/tst-fs-glob/g3")

(syscall 'rmdir "/tmp/tst-fs-glob")

`open`	Type: Function
`root::open`	`Usage: (open filename option*)`

Open a file. Options are: :read :write :append :truncate :create :create-new :on-error-nil


Example:

(def tmp (get-temp))

(def test-open-f (open (str tmp "/slsh-tst-open.txt") :create :truncate))

(write-line test-open-f "Test Line One")

(close test-open-f)

(test::assert-equal "Test Line One

" (read-line (open (str tmp "/slsh-tst-open.txt"))))

`read`	Type: Function
`root::read`	`Usage: (read [file\\|string]? end-exp?) -> expression`

Read a file or string and return the next object (symbol, string, list, etc). Raises an error if the file or string has been read unless end-exp is provided then returns that on the end condition. If no parameters are provided then read stdin.


Example:

(def tmp (get-temp))

(def tst-file (open (str tmp "/slsh-tst-open.txt") :create :truncate))

(write-line tst-file "(1 2 3)(x y z)")

;(write-string tst-file "Test Line Read Line Two")

(flush tst-file)

(def tst-file (open (str tmp "/slsh-tst-open.txt") :read))

(test::assert-equal '(1 2 3) (read tst-file))

(test::assert-equal '(x y z) (read tst-file))

(test::assert-error (read test-file))

(close tst-file)

(def tst-file (open (str tmp "/slsh-tst-open.txt") :read))

(test::assert-equal '(1 2 3) (read tst-file :done))

(test::assert-equal '(x y z) (read tst-file :done))

(test::assert-equal :done (read tst-file :done))

(close tst-file)

(test::assert-equal '(4 5 6) (read "(4 5 6)"))

(def test-str "7 8 9")

(test::assert-equal 7 (read test-str))

(test::assert-equal 8 (read test-str))

(test::assert-equal 9 (read test-str))

(test::assert-error (read test-str))

(def test-str "7 8 9")

(test::assert-equal 7 (read test-str :done))

(test::assert-equal 8 (read test-str :done))

(test::assert-equal 9 (read test-str :done))

(test::assert-equal :done (read test-str :done))

(test::assert-equal '(x y z) (read "(x y z)"))

`read-all`	Type: Function
`root::read-all`	`Usage: (read-all [file\\|string]? empty-exp?) -> list\\|vec\\|empty-exp`

Read a file or string and return the list representation. This reads the entire file or string and will wrap in an outer vector if not a vector or list (always returns a vector or list). Unlike most lisp readers this one will put loose symbols in a list (i.e. you enter things at the repl without the enclosing parens). Note the file|string arg is optional, if not provided will read from stdin (or can provide stdin). If the read item is empty (including a comment) then raises an error or produces empty-exp if it is provided.


Example:

(def tmp (get-temp))

(def tst-file (open (str tmp "/slsh-tst-open.txt") :create :truncate))

(write-line tst-file "(1 2 3)(x y z)")

(flush tst-file)

(def tst-file (open (str tmp "/slsh-tst-open.txt") :read))

(test::assert-equal '#((1 2 3)(x y z)) (read-all tst-file))

(close tst-file)

(test::assert-equal '(4 5 6) (read-all "(4 5 6)"))

(test::assert-equal '(7 8 9) (read-all "7 8 9"))

(test::assert-equal '(x y z) (read-all "(x y z)" :not-used))

(test::assert-equal :empty (read-all ";(x y z)" :empty))

`read-line`	Type: Function
`root::read-line`	`Usage: (read-line file) -> string`

Read a line from a file.


Example:

(def tmp (get-temp))

(def tst-file (open (str tmp "slsh-tst-open.txt") :create :truncate))

(write-line tst-file "Test Line Read Line One")

(write-string tst-file "Test Line Read Line Two")

(flush tst-file)

(def tst-file (open (str tmp "slsh-tst-open.txt") :read))

(test::assert-equal "Test Line Read Line One

" (read-line tst-file))

(test::assert-equal "Test Line Read Line Two" (read-line tst-file))

(close tst-file)

`temp-dir`	Type: Function
`root::temp-dir`	`Usage: (temp-dir)`

Returns a string representing the temporary directory. See get-temp for higher level temporary directory creation mechanism. On Unix: Returns the value of the TMPDIR environment variable if it is set, otherwise for non-Android it returns /tmp. If Android, since there is no global temporary folder (it is usually allocated per-app), it returns /data/local/tmp. On Windows: Returns the value of, in order, the TMP, TEMP, USERPROFILE environment variable if any are set and not the empty string. Otherwise, temp_dir returns the path of the Windows directory. This behavior is identical to that of GetTempPath, which this function uses internally.


Example:

(test::assert-true (fs-dir? (temp-dir)))

`with-temp`	Type: Function
`root::with-temp`	`Usage: (with-temp (fn (x) (println \"given temp dir:\" x)) [\"optional-prefix\" \"optional-suffix\" length])`

Takes a function that accepts a temporary directory. This directory will be recursively removed when the provided function is finished executing. Also accepts an optional prefix, an optional suffix, and an optional length for the random number of characters in the temporary directory created. Defaults to prefix of ".tmp", no suffix, and five random characters.


Example:

(def fp nil)

(with-temp (fn (tmp-dir)

(let* ((tmp-file (str tmp-dir \"/sl-sh-tmp-file.txt\"))

(a-file (open tmp-file :create :truncate)))

(test::assert-true (fs-exists? tmp-file))

(set! fp tmp-file)

(close a-file))))

(test::assert-false (nil? fp))

(test::assert-false (fs-exists? fp))

(with-temp

(fn (tmp)

(test::assert-true (str-contains \"some-prefix\" tmp)))

\"some-prefix\")

(with-temp

(fn (tmp)

(test::assert-true (str-contains \"some-prefix\" tmp))

(test::assert-true (str-contains \"some-suffix\" tmp)))

\"some-prefix\"

\"some-suffix\")

(with-temp

(fn (tmp)

(test::assert-true (str-contains \"some-prefix\" tmp))

(test::assert-true (str-contains \"some-suffix\" tmp))

(test::assert-equal (length \"some-prefix0123456789some-suffix\") (length (fs-base tmp))))

\"some-prefix\"

\"some-suffix\"

10)

`with-temp-file`	Type: Function
`root::with-temp-file`	`Usage: (with-temp-file (fn (x) (println \"given temp file:\" x)) [\"optional-prefix\" \"optional-suffix\" length])`

Takes a function that accepts a temporary file. This file will be removed when the provided function is finished executing. Also accepts an optional prefix, an optional suffix, and an optional length for the random number of characters in the temporary file created. Defaults to prefix of ".tmp", no suffix, and five random characters.


Example:

(def fp nil)

(with-temp-file (fn (tmp-file)

(let* ((a-file (open tmp-file :create :truncate)))

(test::assert-true (fs-exists? tmp-file))

(set! fp tmp-file)

(close a-file))))

(test::assert-false (nil? fp))

(test::assert-false (fs-exists? fp))

(with-temp-file

(fn (tmp)

(test::assert-true (str-contains \"some-prefix\" tmp)))

\"some-prefix\")

(with-temp-file

(fn (tmp)

(test::assert-true (str-contains \"some-prefix\" tmp))

(test::assert-true (str-contains \"some-suffix\" tmp)))

\"some-prefix\"

\"some-suffix\")

(with-temp-file

(fn (tmp)

(test::assert-true (str-contains \"some-prefix\" tmp))

(test::assert-true (str-contains \"some-suffix\" tmp))

(test::assert-equal (length \"some-prefix0123456789some-suffix\") (length (fs-base tmp))))

\"some-prefix\"

\"some-suffix\"

10)

`write-line`	Type: Function
`root::write-line`	`Usage: (write-line file string)`

Write a line to a file.


Example:

(def tmp (get-temp))

(def tst-file (open (str tmp "/slsh-tst-open.txt") :create :truncate))

(write-line tst-file "Test Line Write Line")

(flush tst-file)

(def tst-file (open (str tmp "/slsh-tst-open.txt") :read))

(test::assert-equal "Test Line Write Line

" (read-line tst-file))

(close tst-file)

`write-string`	Type: Function
`root::write-string`	`Usage: (write-string file string)`

Write a string to a file.


Example:

(def tmp (get-temp))

(def tst-file (open (str tmp "/slsh-tst-open.txt") :create :truncate))

(write-string tst-file "Test Line Write Line")

(flush tst-file)

(def tst-file (open (str tmp "/slsh-tst-open.txt") :read))

(test::assert-equal "Test Line Write Line" (read-line tst-file))

(close tst-file)

Globals forms

In sl-sh global symbols (made by ‘def) are wrapped in earmuffs like in common lisp. Some of these symbols contain information used by the standard library and may be useful to end users, while others are intended for use in scripting.

`last-command`	Type: String
`root::last-command`

Namespace: root last run command by sl-sh on repl

`last-status`	Type: Int
`root::last-status`

Namespace: root Return code of last run sl-sh command on the repl

`repl-settings`	Type: HashMap
`root::repl-settings`

Namespace: root hash map of repl settings

`std-lib-namespaces`	Type: Vector
`root::std-lib-namespaces`

Namespace: root vector of all namespaces present in sl-sh by default

`std-lib-syms-hash`	Type: HashMap
`root::std-lib-syms-hash`

Namespace: root vector of all symbols in sl-sh-standard library

Hashmap forms

`hash-clear!`	Type: Function
`root::hash-clear!`	`Usage: (hash-clear! hashmap)`

Clears a hashmap. This is a destructive form!


Example:

(def tst-hash (make-hash '((:key1 . \"val one\")(key2 . \"val two\")(\"key3\" . \"val three\")(#\\S . \"val S\"))))

(test::assert-equal 4 (length (hash-keys tst-hash)))

(test::assert-true (hash-haskey tst-hash :key1))

(test::assert-true (hash-haskey tst-hash 'key2))

(test::assert-true (hash-haskey tst-hash \"key3\"))

(test::assert-true (hash-haskey tst-hash #\\S))

(hash-clear! tst-hash)

(test::assert-equal 0 (length (hash-keys tst-hash)))

(test::assert-false (hash-haskey tst-hash :key1))

(test::assert-false (hash-haskey tst-hash 'key2))

(test::assert-false (hash-haskey tst-hash \"key3\"))

(test::assert-false (hash-haskey tst-hash #\\S))

`hash-get`	Type: SpecialForm
`root::hash-get`	`Usage: (hash-get hashmap key default?) -> value`

Get a value for a key from a hashmap. If the optional default is provided and the key is not in the hash then evaluate and return it. NOTE: default will only be evaluted if it is used.


Example:

(def tst-hash (make-hash '((:key1 . "val one")(key2 . "val two")("key3" . "val three")(#\S . "val S"))))

(test::assert-equal 4 (length (hash-keys tst-hash)))

(test::assert-equal "val one" (hash-get tst-hash :key1))

(test::assert-equal "val two" (hash-get tst-hash 'key2))

(test::assert-equal "val three" (hash-get tst-hash "key3"))

(test::assert-equal "val S" (hash-get tst-hash #\S))

(test::assert-equal "default" (hash-get tst-hash :not-here "default"))

(test::assert-equal "string default" (hash-get tst-hash :not-here (str "string " "default")))

`hash-haskey`	Type: Function
`root::hash-haskey`	`Usage: (hash-haskey hashmap key)`

Checks if a key is in a hashmap.


Example:

(def tst-hash (make-hash '((:key1 . \"val one\")(key2 . \"val two\")(\"key3\" . \"val three\")(#\\S . \"val S\"))))

(test::assert-equal 4 (length (hash-keys tst-hash)))

(test::assert-true (hash-haskey tst-hash :key1))

(test::assert-true (hash-haskey tst-hash 'key2))

(test::assert-true (hash-haskey tst-hash \"key3\"))

(test::assert-true (hash-haskey tst-hash #\\S))

(test::assert-false (hash-haskey tst-hash 'key1))

(test::assert-false (hash-haskey tst-hash :key2))

(test::assert-false (hash-haskey tst-hash \"keynone\"))

(hash-remove! tst-hash :key1)

(test::assert-false (hash-haskey tst-hash :key1))

(hash-set! tst-hash :key1 \"val one b\")

(test::assert-true (hash-haskey tst-hash :key1))

`hash-keys`	Type: Function
`root::hash-keys`	`Usage: (hash-keys hashmap)`

Returns a vector of all the hashmaps keys. The keys will be unordered.


Example:

(def tst-hash (make-hash '((:key1 . \"val one\")(key2 . \"val two\")(\"key3\" . \"val three\")(#\\S . \"val S\"))))

(test::assert-equal 4 (length (hash-keys tst-hash)))

(test::assert-true (in? (hash-keys tst-hash) :key1) \" Test :key1\")

(test::assert-true (in? (hash-keys tst-hash) 'key2) \" Test key2\")

; Note string or char used as a key will be a symbol in the hash-keys list...

(test::assert-true (in? (hash-keys tst-hash) 'S) \" Test S\")

(test::assert-true (in? (hash-keys tst-hash) 'key3) \" Test key3\")

(test::assert-false (in? (hash-keys tst-hash) :key4))

`hash-remove!`	Type: Function
`root::hash-remove!`	`Usage: (hash-remove! hashmap key)`

Remove a key from a hashmap. This is a destructive form!


Example:

(def tst-hash (make-hash '((:key1 . \"val one\")(key2 . \"val two\")(\"key3\" . \"val three\")(#\\S . \"val S\"))))

(test::assert-equal 4 (length (hash-keys tst-hash)))

(test::assert-equal \"val one\" (hash-get tst-hash :key1))

(test::assert-equal \"val two\" (hash-get tst-hash 'key2))

(test::assert-equal \"val three\" (hash-get tst-hash \"key3\"))

(test::assert-equal \"val S\" (hash-get tst-hash #\\S))

(hash-remove! tst-hash 'key2)

(test::assert-equal 3 (length (hash-keys tst-hash)))

(test::assert-equal \"val one\" (hash-get tst-hash :key1))

(test::assert-equal \"val three\" (hash-get tst-hash \"key3\"))

(test::assert-equal \"val S\" (hash-get tst-hash #\\S))

(hash-remove! tst-hash :key1)

(test::assert-equal 2 (length (hash-keys tst-hash)))

(test::assert-equal \"val three\" (hash-get tst-hash \"key3\"))

(test::assert-equal \"val S\" (hash-get tst-hash #\\S))

(hash-remove! tst-hash \"key3\")

(test::assert-equal 1 (length (hash-keys tst-hash)))

(test::assert-equal \"val S\" (hash-get tst-hash #\\S))

(hash-remove! tst-hash #\\S)

(test::assert-equal 0 (length (hash-keys tst-hash)))

`hash-set!`	Type: Function
`root::hash-set!`	`Usage: (hash-set! hashmap key value)`

Add or update a hashmap key’s value. This is a destructive form!


Example:

(def tst-hash (make-hash))

(test::assert-equal 0 (length (hash-keys tst-hash)))

(hash-set! tst-hash :new-key '(1 2 3))

(test::assert-equal 1 (length (hash-keys tst-hash)))

(test::assert-equal '(1 2 3) (hash-get tst-hash :new-key))

(def tst-hash (make-hash '((:key1 . \"val one\")(key2 . \"val two\")(\"key3\" . \"val three\"))))

(test::assert-equal 3 (length (hash-keys tst-hash)))

(test::assert-equal \"val one\" (hash-get tst-hash :key1))

(test::assert-equal \"val two\" (hash-get tst-hash 'key2))

(test::assert-equal \"val three\" (hash-get tst-hash \"key3\"))

(hash-set! tst-hash :new-key '(1 2 3))

(test::assert-equal 4 (length (hash-keys tst-hash)))

(test::assert-equal \"val one\" (hash-get tst-hash :key1))

(test::assert-equal \"val two\" (hash-get tst-hash 'key2))

(test::assert-equal \"val three\" (hash-get tst-hash \"key3\"))

(test::assert-equal '(1 2 3) (hash-get tst-hash :new-key))

(hash-set! tst-hash 'key2 \"val two b\")

(hash-set! tst-hash :key1 \"val one b\")

(hash-set! tst-hash \"key3\" \"val three b\")

(test::assert-equal 4 (length (hash-keys tst-hash)))

(test::assert-equal \"val one b\" (hash-get tst-hash :key1))

(test::assert-equal \"val two b\" (hash-get tst-hash 'key2))

(test::assert-equal \"val three b\" (hash-get tst-hash \"key3\"))

(test::assert-equal '(1 2 3) (hash-get tst-hash :new-key))

`make-hash`	Type: Function
`root::make-hash`	`Usage: (make-hash associations?)`

Make a new hash map. If associations is provided (makes an empty map if not) then it is a list of pairs (key . value) that populate the intial map. Neither key nor value in the associations will be evaluated.


Example:

(def tst-hash (make-hash))

(test::assert-equal 0 (length (hash-keys tst-hash)))

(def tst-hash (make-hash ()))

(test::assert-equal 0 (length (hash-keys tst-hash)))

(def tst-hash (make-hash nil))

(test::assert-equal 0 (length (hash-keys tst-hash)))

(def tst-hash (make-hash '((:key1 . \"val one\")(key2 . \"val two\")(\"key3\" . \"val three\"))))

(test::assert-equal 3 (length (hash-keys tst-hash)))

(test::assert-equal \"val one\" (hash-get tst-hash :key1))

(test::assert-equal \"val two\" (hash-get tst-hash 'key2))

(test::assert-equal \"val three\" (hash-get tst-hash \"key3\"))

(def tst-hash (make-hash '#((:keyv1 . \"val one\")(keyv2 . \"val two\")(\"keyv3\" . \"val three\"))))

(test::assert-equal 3 (length (hash-keys tst-hash)))

(test::assert-equal \"val one\" (hash-get tst-hash :keyv1))

(test::assert-equal \"val two\" (hash-get tst-hash 'keyv2))

(test::assert-equal \"val three\" (hash-get tst-hash \"keyv3\"))

; Not in test below that tst-hash-val is NOT evaluated so the symbol is the value.

(def tst-hash-val \"some val\")

(def tst-hash (make-hash '#((:keyv1 . \"val one\")(:keyv2 . \"val two\")(:keyv3 . tst-hash-val))))

(test::assert-equal 3 (length (hash-keys tst-hash)))

(test::assert-equal \"val one\" (hash-get tst-hash :keyv1))

(test::assert-equal \"val two\" (hash-get tst-hash :keyv2))

(test::assert-equal 'tst-hash-val (hash-get tst-hash :keyv3))

Iterator forms

`append`	Type: Lambda
`iterator::append`	`Usage: (append first-iter &rest rest-iters)`

Combine the provided items into a single iterator (calls iter on each parameter). If non-list items are passed they are wrapped in a singleton iterator (i.e. will work with loose object). Note that nil is an empty list not a “loose item”.


Example:

(def test-iter (append '(0 1 2) '#(3 4 5) '(6 7 8 9)))

(assert-false (test-iter :empty?))

(assert-equal 10 (test-iter :count))

(assert-true (test-iter :empty?))

(def test-iter (append '(0 1 2) 3 4 5 '(6 7 8 9)))

(assert-false (test-iter :empty?))

(assert-equal 10 (test-iter :count))

(assert-true (test-iter :empty?))

(def test-iter (append 0 1 2 '(3 4)))

(assert-false (test-iter :empty?))

(assert-equal 0 (test-iter :next!))

(assert-equal 1 (test-iter :next!))

(assert-equal 2 (test-iter :next!))

(assert-equal 3 (test-iter :next!))

(assert-equal 4 (test-iter :next!))

(assert-true (test-iter :empty?))

(def test-iter (append 0 1 2 nil))

(assert-false (test-iter :empty?))

(assert-equal 0 (test-iter :next!))

(assert-equal 1 (test-iter :next!))

(assert-equal 2 (test-iter :next!))

(assert-true (test-iter :empty?))

(def test-iter (append 0 1 2 '(nil)))

(assert-false (test-iter :empty?))

(assert-equal 0 (test-iter :next!))

(assert-equal 1 (test-iter :next!))

(assert-equal 2 (test-iter :next!))

(assert-equal nil (test-iter :next!))

(assert-true (test-iter :empty?))

`append-iter`	Type: Lambda
`iterator::append-iter`	`Usage: (append-iter)`

Iterator that appends multiple iterators. Append iter will consume the iterators it is appending. If non-list items are passed they are wrapped in a singleton iterator (i.e. will work with loose object). attribute: iters private method: :next! method: :empty? method: :init impl iterator::iterator


Example:

(def test-iter ((iterator::append-iter) :init '(0 1 2) '#(3 4 5) '(6 7 8 9)))

(def test-slice-iter (test-iter :slice 3 7))

(assert-false (test-slice-iter :empty?))

(assert-equal 3 (test-slice-iter :next!))

(assert-equal 4 (test-slice-iter :next!))

(assert-equal 5 (test-slice-iter :next!))

(assert-equal 6 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-iter ((iterator::append-iter) :init '(0 1 2) nil '#(3 4 5) nil '(6 7 8 9)))

(def test-slice-iter (test-iter :slice 0 4))

(assert-false (test-slice-iter :empty?))

(assert-equal 0 (test-slice-iter :next!))

(assert-equal 1 (test-slice-iter :next!))

(assert-equal 2 (test-slice-iter :next!))

(assert-equal 3 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-iter ((iterator::append-iter) :init '(0 1 2) '#(3 4 5) '(6 7 8 9)))

(def test-slice-iter (test-iter :slice 7))

(assert-false (test-slice-iter :empty?))

(assert-equal 7 (test-slice-iter :next!))

(assert-equal 8 (test-slice-iter :next!))

(assert-equal 9 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-iter ((iterator::append-iter) :init '(0 1 2) '#(3 4 5) '(6 7 8 9)))

(assert-false (test-iter :empty?))

(assert-equal 10 (test-iter :count))

(assert-true (test-iter :empty?))

(def test-iter ((iterator::append-iter) :init '(0 1 2) '() '#(3 4 5) nil '(6 7 8 9)))

(assert-false (test-iter :empty?))

(assert-equal 10 (test-iter :count))

(assert-true (test-iter :empty?))

(def test-iter ((iterator::append-iter) :init nil '(0 1 2) (vec) '#(3 4 5) '(6 7 8 9) nil))

(assert-false (test-iter :empty?))

(assert-equal 10 (test-iter :count))

(assert-true (test-iter :empty?))

`append-to!`	Type: Lambda
`iterator::append-to!`	`Usage: (append-to! ret &rest others)`

Combine the provided items after the first (first must be a vector or list) into a single iterator. These values are added the first argument destructively. If non-list items are passed they are wrapped in a singleton iterator (i.e. will work with loose object). Note that nil is an empty list not a “loose item”.


Example:

(def test-iter '(0 1 2))

(append-to! test-iter '#(3 4 5) '(6 7 8 9))

(set! test-iter (iter test-iter))

(def test-slice-iter (test-iter :slice 3 7))

(assert-false (test-slice-iter :empty?))

(assert-equal 3 (test-slice-iter :next!))

(assert-equal 4 (test-slice-iter :next!))

(assert-equal 5 (test-slice-iter :next!))

(assert-equal 6 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-iter '(0 1 2))

(append-to! test-iter '#(3 4 5) '(6 7 8 9))

(set! test-iter (iter test-iter))

(def test-slice-iter (test-iter :slice 0 4))

(assert-false (test-slice-iter :empty?))

(assert-equal 0 (test-slice-iter :next!))

(assert-equal 1 (test-slice-iter :next!))

(assert-equal 2 (test-slice-iter :next!))

(assert-equal 3 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-iter '(0 1 2))

(append-to! test-iter '#(3 4 5) '(6 7 8 9))

(set! test-iter (iter test-iter))

(def test-slice-iter (test-iter :slice 7))

(assert-false (test-slice-iter :empty?))

(assert-equal 7 (test-slice-iter :next!))

(assert-equal 8 (test-slice-iter :next!))

(assert-equal 9 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-iter '(0 1 2))

(append-to! test-iter '#(3 4 5) '(6 7 8 9))

(set! test-iter (iter test-iter))

(assert-false (test-iter :empty?))

(assert-equal 10 (test-iter :count))

(assert-true (test-iter :empty?))

(def test-iter nil)

(append-to! test-iter nil '(0 1 2) nil '#(3 4 5) '(6 7 8 9) nil)

(set! test-iter (iter test-iter))

(assert-false (test-iter :empty?))

(assert-equal 10 (test-iter :count))

(assert-true (test-iter :empty?))

(def test-iter (vec 0))

(append-to! test-iter nil '#(1) '(2 3) nil)

(set! test-iter (iter test-iter))

(assert-false (test-iter :empty?))

(assert-equal 0 (test-iter :next!))

(assert-equal 1 (test-iter :next!))

(assert-equal 2 (test-iter :next!))

(assert-equal 3 (test-iter :next!))

(assert-true (test-iter :empty?))

`collect`	Type: Lambda
`iterator::collect`	`Usage: (collect s)`

Collect all the values into a list. This will consume the iterator and produce a new list. Will call iter on input to turn a collection into an iterator.


Example:

(def collect-test (iterator::collect '#(1 2 3)))

(assert-true (list? collect-test))

(assert-equal '(1 2 3) collect-test)

`collect-str`	Type: Lambda
`iterator::collect-str`	`Usage: (collect-str s)`

Collect all the values into a string. This will consume the iterator and produce a new string. Will call iter on input to turn a collection into an iterator.


Example:

(def collect-str-test (iterator::collect-str (iterator::map (fn (ch) (char-upper ch)) "λabc σ")))

(assert-true (string? collect-str-test))

(assert-equal "ΛABC Σ" collect-str-test)

`collect-vec`	Type: Lambda
`iterator::collect-vec`	`Usage: (collect-vec s)`

Collect all the values into a vector. This will consume the iterator and produce a new vector. Will call iter on input to turn a collection into an iterator.


Example:

(def collect-vec-test (iterator::collect-vec '(1 2 3)))

(assert-true (vec? collect-vec-test))

(assert-equal '#(1 2 3) collect-vec-test)

`double-ended-iter?`	Type: Lambda
`iterator::double-ended-iter?`	`Usage: (double-ended-iter? thing)`

Return true if thing is an iterator and double ended, nil otherwise.


Example:

(struct::defstruct test-iter

; fields

(current 0)

; methods

(:fn next! (self) (do (def val current)(set! current (+ 1 current)) val))

(:fn empty? (self) (>= current 3))

(:impl iterator::iterator))

(assert-true (iterator::double-ended-iter? (iterator::iter '(1 2 3))))

(assert-false (iterator::double-ended-iter? '(1 2 3)))

(assert-false (iterator::double-ended-iter? (test-iter)))

`double-ended-iterator`	Type: Lambda
`iterator::double-ended-iterator`	`Usage: (defstruct iter (:fn next! (self)...)(:fn next-back! (self)...)(:fn empty? (self)...)(:impl iterator::iterator iterator::double-ended-iterator))`

Trait that makes an iterator double ended (can get items from front and back. Requires a struct to define methods next-back! and implement iterator. Note that next! and next-back! can not cross, the iterator is empty when they meet. method: :nth-back! Consume the iterator until the nth element from the end and return it (0 based). Note that repeated called to nth-back! will return new data since it consumes the iterator. method: :reverse Produce an iterator that is the reverse of self.


Example:

(ns-import 'struct)

(ns-import 'iterator)

(defstruct test-double-iter

; fields

(current 0)

(current-end 2)

; methods

(:fn next! (self) (do (var val current)(set! current (+ 1 current)) val))

(:fn next-back! (self) (do (var val current-end)(set! current-end (- current-end 1)) val))

(:fn empty? (self) (> current current-end))

(:impl iterator::iterator iterator::double-ended-iterator))

(def tmap (test-double-iter))

(assert-false (tmap :empty?))

(assert-equal 0 (tmap :next!))

(assert-equal 1 (tmap :next!))

(assert-equal 2 (tmap :next!))

(assert-true (tmap :empty?))

(def tmap (test-double-iter))

(assert-false (tmap :empty?))

(assert-equal 2 (tmap :next-back!))

(assert-equal 1 (tmap :next-back!))

(assert-equal 0 (tmap :next-back!))

(assert-true (tmap :empty?))

(def tmap (test-double-iter))

(assert-false (tmap :empty?))

(assert-equal 0 (tmap :next!))

(assert-equal 2 (tmap :next-back!))

(assert-equal 1 (tmap :next-back!))

(assert-true (tmap :empty?))

; :nth-back! Example

(def tmap ((vec-iter) :init '#(0 1 2 3 4) 0))

(assert-false (tmap :empty?))

(assert-equal 4 (tmap :nth-back! 0))

(assert-equal 3 (tmap :nth-back! 0))

(assert-equal 0 (tmap :nth-back! 2))

(assert-true (tmap :empty?))

; :reverse Example

(def tmap ((test-double-iter) :reverse))

(assert-false (tmap :empty?))

(assert-equal 2 (tmap :next!))

(assert-equal 1 (tmap :next!))

(assert-equal 0 (tmap :next!))

(assert-true (tmap :empty?))

`empty?`	Type: Lambda
`iterator::empty?`	`Usage: (empty? s)`

Is an iterator empty (no more items)? Will call iter on input first.


Example:

(assert-true (iterator::empty? nil))

(assert-true (iterator::empty? '#()))

(assert-false (iterator::empty? '#(1)))

`file-iter`	Type: Lambda
`iterator::file-iter`	`Usage: (file-iter)`

Iterator that wraps a file. Each call to next! returns the next line (with trailing newline. attribute: file private attribute: next-line private method: :next! method: :empty? method: :init impl iterator::iterator


Example:

(def tst-file (open "/tmp/file-iter-test.txt" :create :truncate))

(write-line tst-file "line 1")

(write-line tst-file "line 2")

(write-line tst-file "line 3")

(write-string tst-file "line 4")

(close tst-file)

(def test-iter ((iterator::file-iter) :init (open "/tmp/file-iter-test.txt")))

(assert-false (test-iter :empty?))

(assert-equal "line 1\n" (test-iter :next!))

(assert-equal "line 2\n" (test-iter :next!))

(assert-equal "line 3\n" (test-iter :next!))

(assert-equal "line 4" (test-iter :next!))

(assert-true (test-iter :empty?))

`filter`	Type: Lambda
`iterator::filter`	`Usage: (filter predicate items)`

Returns a filter-iter around items (will call iter on items). Iterator that applies a lambda to each element to determine if is returned- is lazy.


Example:

(def test-iter (iterator::filter (fn (x) (not (= x 2))) '(1 2 3)))

(assert-false (test-iter :empty?))

(assert-equal 1 (test-iter :next!))

(assert-equal 3 (test-iter :next!))

(assert-true (test-iter :empty?))

`filter-iter`	Type: Lambda
`iterator::filter-iter`	`Usage: (filter-iter)`

Iterator that applies a lambda to each element to determine if is returned- is lazy. attribute: data private attribute: predicate private attribute: next private attribute: is-empty private method: :next! method: :empty? method: :advance-data! method: :init impl iterator::iterator


Example:

(def test-iter (((iterator::list-iter) :init '(1 2 3)) :filter (fn (x) (not (= x 2)))))

(assert-false (test-iter :empty?))

(assert-equal 1 (test-iter :next!))

(assert-equal 3 (test-iter :next!))

(assert-true (test-iter :empty?))

`for`	Type: Macro
`iterator::for`	`Usage: (for bind in items body)`

Loops over each element in an iterator. Will call iter on the input object. bind is bound to the current element of items and is accesible in body. body is evaluated a number of times equal to the the number of items in in_list.


Example:

(def i 0)

(iterator::for x in (iterator::range 11) (set! i (+ 1 i)))

(assert-equal 11 i)

`for-i`	Type: Macro
`iterator::for-i`	`Usage: (for-i idx-bind bind in items body)`

Loops over each element in an iterator. Will call iter on the input object. idx-bind is bound to an incrementing number starting with 0. bind is bound to the current element of items and is accesible in body. body is evaluated a number of times equal to the the number of items in in_list.


Example:

(def i 0)

(def i-tot 0)

(for-i idx x in '(1 2 3 4 5 6 7 8 9 10 11) (do (set! i-tot (+ idx i-tot))(set! i (+ 1 i))))

(assert-equal 11 i)

(assert-equal 55 i-tot)

`interleave`	Type: Lambda
`iterator::interleave`	`Usage: (interleave fst scnd)`

interleaves two iterators together. Resultant iter is double length of fst unless scnd has less items. Then iter is double length of scnd.


Example:

(ns-import 'iterator)

(test::assert-equal (list 1 2 3 4) (collect (interleave (iter (list 1 3)) (iter (list 2 4)))))

(test::assert-equal (list 1 2 3 4) (collect (interleave (iter (list 1 3)) (iter (list 2 4 5)))))

`interleave-iter`	Type: Lambda
`iterator::interleave-iter`	`Usage: (interleave-iter)`

create iterator that interleaves two iterators together. Resultant iter is double length of fst if fst has less items, or double length of scnd if scnd has less items. attribute: fst private attribute: scnd private attribute: flip-flop private method: :next! method: :empty? method: :init impl iterator::iterator impl iterator::double-ended-iterator


Example:

`iter`	Type: Lambda
`iterator::iter`	`Usage: (iter thing)`

Return thing as an iterator if possible (if it is an iterator just return thing).


Example:

(assert-true (iterator::iter? (iterator::iter '(1 2 3))))

(assert-true (iterator::iter? (iterator::iter '#(1 2 3))))

(assert-true (iterator::iter? (iterator::iter "abc")))

(assert-true (iterator::iter? (iterator::iter (iterator::iter '(1 2 3)))))

`iter?`	Type: Lambda
`iterator::iter?`	`Usage: (iter? thing)`

Return true if thing is an iterator, nil otherwise.


Example:

(assert-true (iterator::iter? (iterator::iter '(1 2 3))))

(assert-false (iterator::iter? '(1 2 3)))

`iterator`	Type: Lambda
`iterator::iterator`	`Usage: (defstruct iter (:fn next! (self)...)(:fn empty? (self)...)(:impl iterator::iterator))`

Trait that provides iterator methods. Requires a struct to define methods next! and empty? method: :collect Collect all the values into a list. This will consume the iterator and produce a new list. method: :collect-vec Collect all the values into a vector. This will consume the iterator and produce a new list. method: :collect-str Collect all the values into a string. This will consume the iterator and produce a new string. method: :map Apply the provided function to each element of the iterator. Map is lazy. method: :filter Apply the provided predicate to the iterator producing only elements that are true. Filter is lazy. method: :slice method: :count Consume the iterator and return the number of items. method: :nth! Consume the iterator until the nth! element and return it (0 based). Note that repeated called to nth! will return new data since it consumes the iterator. method: :double-ended? Return t if this iterator is double ended, nil otherwise.


Example:

(ns-import 'struct)

(ns-import 'iterator)

(defstruct test-iter

; fields

(current 0)

; methods

(:fn next! (self) (do (def val current)(set! current (+ 1 current)) val))

(:fn empty? (self) (>= current 3))

(:impl iterator::iterator))

(def tmap (test-iter))

(assert-false (tmap :empty?))

(assert-equal 0 (tmap :next!))

(assert-equal 1 (tmap :next!))

(assert-equal 2 (tmap :next!))

(assert-true (tmap :empty?))

; :collect Example

(def collect-test ((iter '#(1 2 3)) :collect))

(assert-true (list? collect-test))

(assert-equal '(1 2 3) collect-test)

; :collect-vec Example

(def collect-vec-test ((iter '(1 2 3)) :collect-vec))

(assert-true (vec? collect-vec-test))

(assert-equal '#(1 2 3) collect-vec-test)

; :collect-str Example

(def collect-str-test (((iter "λabc σ") :map (fn (ch) (char-upper ch))) :collect-str))

(assert-true (string? collect-str-test))

(assert-equal "ΛABC Σ" collect-str-test)

; :map Example

(def tmap ((test-iter) :map (fn (x) (+ 1 x))))

(assert-false (tmap :empty?))

(assert-equal 1 (tmap :next!))

(assert-equal 2 (tmap :next!))

(assert-equal 3 (tmap :next!))

(assert-true (tmap :empty?))

; :filter Example

(def tmap ((test-iter) :filter (fn (x) (not (= x 1)))))

(assert-false (tmap :empty?))

(assert-equal 0 (tmap :next!))

(assert-equal 2 (tmap :next!))

(assert-true (tmap :empty?))

; :count Example

(def tmap (test-iter))

(assert-false (tmap :empty?))

(assert-equal 3 (tmap :count))

(assert-true (tmap :empty?))

; :nth! Example

(def tmap ((list-iter) :init '(0 1 2 3 4)))

(assert-false (tmap :empty?))

(assert-equal 0 (tmap :nth! 0))

(assert-equal 1 (tmap :nth! 0))

(assert-equal 4 (tmap :nth! 2))

(assert-true (tmap :empty?))

; :double-ended? Example

(ns-import 'struct)

(ns-import 'iterator)

(defstruct test-double-iter

; fields

(current 0)

(current-end 2)

; methods

(:fn next! (self) (do (def val current)(set! current (+ 1 current)) val))

(:fn next-back! (self) (do (def val current-end)(set! current-end (- current-end 1)) val))

(:fn empty? (self) (> current current-end))

(:impl iterator::iterator iterator::double-ended-iterator))

(assert-false ((test-iter) :double-ended?))

(assert-true ((test-double-iter) :double-ended?))

`list-iter`	Type: Lambda
`iterator::list-iter`	`Usage: (list-iter)`

Iterator that wraps a list. attribute: data private attribute: rev-data private attribute: elements private method: :next! method: :next-back! method: :empty? method: :init method: :make-rev impl iterator::iterator impl iterator::double-ended-iterator


Example:

(def test-list-iter ((list-iter) :init '(1 2 3)))

(assert-false (test-list-iter :empty?))

(assert-equal 1 (test-list-iter :next!))

(assert-equal 2 (test-list-iter :next!))

(assert-equal 3 (test-list-iter :next!))

(assert-true (test-list-iter :empty?))

(def test-list-iter ((list-iter) :init '(1 2 3)))

(assert-false (test-list-iter :empty?))

(assert-equal 1 (test-list-iter :next!))

(assert-equal 3 (test-list-iter :next-back!))

(assert-equal 2 (test-list-iter :next!))

(assert-true (test-list-iter :empty?))

(def test-list-iter ((list-iter) :init '(1 2 3)))

(assert-false (test-list-iter :empty?))

(assert-equal 3 (test-list-iter :next-back!))

(assert-equal 2 (test-list-iter :next-back!))

(assert-equal 1 (test-list-iter :next-back!))

(assert-true (test-list-iter :empty?))

`map`	Type: Lambda
`iterator::map`	`Usage: (map map-fn items)`

Returns a map-iter around items (will call iter on items). Apply the provided function to each element of the iterator. Map is lazy.


Example:

(def tmap (iterator::map (fn (x) (+ 1 x)) '(0 1 2)))

(assert-false (tmap :empty?))

(assert-equal 1 (tmap :next!))

(assert-equal 2 (tmap :next!))

(assert-equal 3 (tmap :next!))

(assert-true (tmap :empty?))

(def tmap (iterator::reverse (iterator::map (fn (x) (+ 1 x)) '(0 1 2))))

(assert-false (tmap :empty?))

(assert-equal 3 (tmap :next!))

(assert-equal 2 (tmap :next!))

(assert-equal 1 (tmap :next!))

(assert-true (tmap :empty?))

`map-iter`	Type: Lambda
`iterator::map-iter`	`Usage: (map-iter)`

Iterator that applies a lambda to each element of another iterator- is lazy. attribute: data private attribute: map-fn private method: :next! method: :next-back! method: :empty? method: :init method: :double-ended? impl iterator::iterator impl iterator::double-ended-iterator


Example:

(def test-map-iter (((iterator::list-iter) :init '(1 2 3)) :map (fn (x) (* x 2))))

(assert-false (test-map-iter :empty?))

(assert-equal 2 (test-map-iter :next!))

(assert-equal 4 (test-map-iter :next!))

(assert-equal 6 (test-map-iter :next!))

(assert-true (test-map-iter :empty?))

`meld`	Type: Lambda
`iterator::meld`	`Usage: (meld fst scnd)`

melds two iterators together. Resultant iter is composed of pairs (fst, scnd) for each value of next! in each provided iterator. Length of returned iter is equal to length of the shortest provided iterator.


Example:

(ns-import 'iterator)

(test::assert-equal (list (join 'string 'bean) (join 'monte 'carlo)) (collect (meld (iter (list 'string 'monte)) (iter (list 'bean 'carlo)))))

(test::assert-equal (list (join 1 2) (join 3 4)) (collect (meld (iter (list 1 3)) (iter (list 2 4 5)))))

`meld-iter`	Type: Lambda
`iterator::meld-iter`	`Usage: (meld-iter)`

create iterator that melds two iterators together. Resultant iter is composed of pairs (fst, scnd) for each value of next! in each provided iterator. Length of meld-iter is equal to length of shorter iterator. attribute: fst private attribute: scnd private attribute: flip-flop private method: :next! method: :empty? method: :init impl iterator::iterator impl iterator::double-ended-iterator


Example:

`next!`	Type: Lambda
`iterator::next!`	`Usage: (next! s)`

Calls iter on s and returns the next item.


Example:

(assert-equal 1 (iterator::next! '(1 2 3)))

(assert-equal 1 (iterator::next! '#(1 2 3)))

(def next-test (iterator::iter '(4 5 6)))

(assert-equal 4 (iterator::next! next-test))

(assert-equal 5 (iterator::next! next-test))

(assert-equal 6 (iterator::next! next-test))

(assert-true (next-test :empty?))

`nth`	Type: Lambda
`iterator::nth`	`Usage: (nth idx coll)`

Consume the iterator until the idx (nth) element and return it (0 based). Note that repeated called to nth will return new data since it consumes the iterator.


Example:

(def tmap ((list-iter) :init '(0 1 2 3 4)))

(assert-false (tmap :empty?))

(assert-equal 0 (nth 0 tmap))

(assert-equal 1 (nth 0 tmap))

(assert-equal 4 (nth 2 tmap))

(assert-true (tmap :empty?))

`range`	Type: Lambda
`iterator::range`	`Usage: (range &rest i)`

Create an iterator that generates numbers within a range. Can be called with one int (n) to produce 0..(n-1) or with two ints (m, n) to produce m..n.


Example:

(def test-iter (iterator::range 3 6))

(assert-false (test-iter :empty?))

(assert-equal 3 (test-iter :next!))

(assert-equal 4 (test-iter :next!))

(assert-equal 5 (test-iter :next!))

(assert-equal 6 (test-iter :next!))

(assert-true (test-iter :empty?))

(def test-iter (iterator::range 3))

(assert-false (test-iter :empty?))

(assert-equal 0 (test-iter :next!))

(assert-equal 1 (test-iter :next!))

(assert-equal 2 (test-iter :next!))

(assert-true (test-iter :empty?))

`range-iter`	Type: Lambda
`iterator::range-iter`	`Usage: (range-iter)`

Iterator that generates numbers within a range. attribute: start private attribute: end private method: :next! method: :next-back! method: :empty? method: :init method: :count impl iterator::iterator impl iterator::double-ended-iterator


Example:

(def test-iter ((range-iter) :init 3 6))

(assert-false (test-iter :empty?))

(assert-equal 3 (test-iter :next!))

(assert-equal 4 (test-iter :next!))

(assert-equal 5 (test-iter :next!))

(assert-equal 6 (test-iter :next!))

(assert-true (test-iter :empty?))

(def test-iter ((range-iter) :init 3 6))

(assert-false (test-iter :empty?))

(assert-equal 6 (test-iter :next-back!))

(assert-equal 5 (test-iter :next-back!))

(assert-equal 4 (test-iter :next-back!))

(assert-equal 3 (test-iter :next-back!))

(assert-true (test-iter :empty?))

`reduce`	Type: Lambda
`iterator::reduce`	`Usage: (reduce reducing-fcn init-val coll)`

reduce is used to amalgamate a provided iterator, coll, and an intitial value, according to the reducing function provided. The iter function will be called on coll to make sure it is an iterator. The reducing-fcn should be a function of two arguments. In the first iteration of reduce, the init-val will be used as the first argument to the reducing-fcn and (next! coll) will be used as the second argument. For all subsequent iterations, The result from the previous application of the reducing-fcn will be used as the first argument to the reducing-fcn and the second argument will be the next item in the collection when the collection is empty reduce will return the amalgamated result.


Example:

(assert-true (= 15 (reduce + 0 (list 1 2 3 4 5))))

(assert-false (= 15 (reduce + 1 (list 1 2 3 4 5))))

(assert-true (= "one hoopy frood" (reduce str "" (list "one " "hoopy " "frood"))))

`reduce-times`	Type: Lambda
`iterator::reduce-times`	`Usage: (reduce-times value wrapping-fcn times)`

Apply wrapping-fcn to value number of times. Function is recursive. Recursive binding for value is previous application of wrapping function to value.


Example:

(assert-equal (list (list 3)) (reduce-times 3 list 2))

(assert-equal 5 (reduce-times (reduce-times 5 list 5) first 5))

`repeat`	Type: Lambda
`iterator::repeat`	`Usage: (repeat target &rest n)`

repeat target n times. if n is not provided returns infinite iterator.


Example:

(test::assert-equal (list #\m #\m #\m #\m) (collect (repeat #\m 4)))

(test::assert-equal (list #\m #\m #\m #\m) (collect (take (repeat #\m) 4)))

`repeat-iter`	Type: Lambda
`iterator::repeat-iter`	`Usage: (repeat-iter)`

iterator that returns provided repeat with specified length. if length is negative returns infinite iterator. attribute: to-repeat private attribute: len private attribute: current private method: :empty? method: :next! method: :init impl iterator::iterator


Example:

`reverse`	Type: Lambda
`iterator::reverse`	`Usage: (reverse items)`

Produce an iterator the is the reverse of items. Will call iter on items and requires a double ended iterator.


Example:

(def tmap (reverse ((vec-iter) :init '#(0 1 2) 0)))

(assert-false (tmap :empty?))

(assert-equal 2 (tmap :next!))

(assert-equal 1 (tmap :next!))

(assert-equal 0 (tmap :next!))

(assert-true (tmap :empty?))

(assert-error (reverse "string"))

`reverse-iter`	Type: Lambda
`iterator::reverse-iter`	`Usage: (reverse-iter)`

Iterator that reverses another iterators direction. Requires a double ended iterator. attribute: wrapped private method: :next! method: :next-back! method: :empty? method: :init impl iterator::iterator impl iterator::double-ended-iterator


Example:

(def test-iter (((vec-iter) :init '#(1 2 3) 0) :reverse))

(assert-false (test-iter :empty?))

(assert-equal 3 (test-iter :next!))

(assert-equal 2 (test-iter :next!))

(assert-equal 1 (test-iter :next!))

(assert-true (test-iter :empty?))

`slice`	Type: Lambda
`iterator::slice`	`Usage: (slice items start &rest end)`

Provides a slice of iterator. Will call iter on items. Slice iter will consume the iterator it is slicing.


Example:

(def test-slice-iter (slice '(0 1 2 3 4 5 6 7 8 9) 3 6))

(assert-false (test-slice-iter :empty?))

(assert-equal 3 (test-slice-iter :next!))

(assert-equal 4 (test-slice-iter :next!))

(assert-equal 5 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-slice-iter (slice '(0 1 2 3 4 5 6 7 8 9) 0 3))

(assert-false (test-slice-iter :empty?))

(assert-equal 0 (test-slice-iter :next!))

(assert-equal 1 (test-slice-iter :next!))

(assert-equal 2 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-slice-iter (slice '(0 1 2 3 4 5 6 7 8 9) 7))

(assert-false (test-slice-iter :empty?))

(assert-equal 7 (test-slice-iter :next!))

(assert-equal 8 (test-slice-iter :next!))

(assert-equal 9 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

`slice-iter`	Type: Lambda
`iterator::slice-iter`	`Usage: (slice-iter)`

Iterator that provides a slice of the underlying iter. Slice iter will consume the iterator it is slicing. attribute: data private attribute: start private attribute: total private attribute: count private method: :next! method: :empty? method: :init impl iterator::iterator


Example:

(def test-slice-iter (((iterator::list-iter) :init '(0 1 2 3 4 5 6 7 8 9)) :slice 3 6))

(assert-false (test-slice-iter :empty?))

(assert-equal 3 (test-slice-iter :next!))

(assert-equal 4 (test-slice-iter :next!))

(assert-equal 5 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-slice-iter (((iterator::list-iter) :init '(0 1 2 3 4 5 6 7 8 9)) :slice 0 3))

(assert-false (test-slice-iter :empty?))

(assert-equal 0 (test-slice-iter :next!))

(assert-equal 1 (test-slice-iter :next!))

(assert-equal 2 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

(def test-slice-iter (((iterator::list-iter) :init '(0 1 2 3 4 5 6 7 8 9)) :slice 7))

(assert-false (test-slice-iter :empty?))

(assert-equal 7 (test-slice-iter :next!))

(assert-equal 8 (test-slice-iter :next!))

(assert-equal 9 (test-slice-iter :next!))

(assert-true (test-slice-iter :empty?))

`string-iter`	Type: Lambda
`iterator::string-iter`	`Usage: (string-iter)`

Iterator that wraps a string. attribute: data private method: :next! method: :empty? method: :init impl iterator::iterator


Example:

(def test-string-iter ((string-iter) :init "123"))

(assert-false (test-string-iter :empty?))

(assert-equal #\1 (test-string-iter :next!))

(assert-equal #\2 (test-string-iter :next!))

(assert-equal #\3 (test-string-iter :next!))

(assert-true (test-string-iter :empty?))

`take`	Type: Lambda
`iterator::take`	`Usage: (take provided-iter n)`

return iterator with first n items of provided-iter. Returned iterator is the same as provided-iter if n is greater than the length of provided-iter.


Example:

(test::assert-equal (list #\m #\m) (collect (take (repeat #\m 4) 2)))

`take-iter`	Type: Lambda
`iterator::take-iter`	`Usage: (take-iter)`

take itertor attribute: provided-iter private attribute: len private attribute: current private method: :empty? method: :next! method: :init impl iterator::iterator


Example:

`vec-iter`	Type: Lambda
`iterator::vec-iter`	`Usage: (vec-iter)`

Iterator that wraps a vector. attribute: data private attribute: start private attribute: end private method: :next! method: :next-back! method: :empty? method: :nth! method: :nth-back! method: :init impl iterator::iterator impl iterator::double-ended-iterator


Example:

(def test-vec-iter ((vec-iter) :init '#(1 2 3) 0))

(assert-false (test-vec-iter :empty?))

(assert-equal 1 (test-vec-iter :next!))

(assert-equal 2 (test-vec-iter :next!))

(assert-equal 3 (test-vec-iter :next!))

(assert-true (test-vec-iter :empty?))

(def test-vec-iter ((vec-iter) :init (vec) 0))

(assert-true (test-vec-iter :empty?))

Logger forms

`logger`	Type: Lambda
`root::logger`	`Usage: (logger)`

logger struct Initialize a logger object with a name and a log level that can be called repeatedly to log to stdout. Supported log levels in order are :trace, :debug, :info, :warn, :error, or :off. Calls to functions provided by struct are noops unless that particular log level is enabled. To override the log level specified in code set the environment variable SLSH_LOG_LEVEL to the desired log level before initializing the struct. Format is: {unix time} {pid} {log level}: [{logger-name}] {log-string} attribute: log-level private attribute: log-level-int private attribute: logger-name private attribute: convert-log-level private method: :get-log method: :log-it method: :trace method: :debug method: :info method: :warn method: :error method: :init


Example:

(defn test-logger (log-name log-level)

(let ((a-logger ((logger) :init log-name log-level))

(str-list (list)))

(append-to! str-list (list (a-logger :get-log :trace (str "test log " log-level))))

(append-to! str-list (list (a-logger :get-log :debug (str "test log " log-level))))

(append-to! str-list (list (a-logger :get-log :info (str "test log " log-level))))

(append-to! str-list (list (a-logger :get-log :warn (str "test log " log-level))))

(append-to! str-list (list (a-logger :get-log :error (str "test log " log-level))))

(collect (filter (fn (x) (not (falsey? x))) str-list))))

(test::assert-equal 5 (length (test-logger "test-logger" :trace)))

(test::assert-equal 4 (length (test-logger "test-logger" :debug)))

(test::assert-equal 3 (length (test-logger "test-logger" :info)))

(test::assert-equal 2 (length (test-logger "test-logger" :warn)))

(test::assert-equal 1 (length (test-logger "test-logger" :error)))

(test::assert-equal 0 (length (test-logger "test-logger" :off)))

(test::assert-error-msg ((logger) :init "test-logger" :bad-log-level) "log level must be a symbol one of: :trace, :debug, :info, :warn, :error, or :off")

(test::assert-error-msg ((logger) :init 'bad-log-name :error) "in-logger-name must be a string.")

Math forms

`%`	Type: Function
`root::%`	`Usage: (% int int)`

Remainder from dividing first int by the second.


Example:

(ns-import 'math)

(test::assert-equal 0 (% 50 10))

(test::assert-equal 5 (% 55 10))

(test::assert-equal 1 (% 1 2))

(test::assert-error (%))

(test::assert-error (% 1))

(test::assert-error (% 1 2 3))

(test::assert-error (% 1 2.0))

`*`	Type: Function
`root::*`	`Usage: (* number*)`

Multiply a sequence of numbers. (*) will return 1.


Example:

(ns-import 'math)

(test::assert-equal 1 (*))

(test::assert-equal 5 (* 5))

(test::assert-equal 5 (* 1 5))

(test::assert-equal 5.0 (* 1.0 5))

(test::assert-equal 7.5 (* 1.5 5))

(test::assert-equal 7.5 (* 1.5 5.0))

(test::assert-equal 15 (* 3 5))

(test::assert-equal 8 (* 1 2 4))

(test::assert-equal 16 (* 2 2 4))

(test::assert-equal 16.0 (* 2 2.0 4))

(test::assert-equal 16.0 (* 2.0 2.0 4.0))

(test::assert-equal 55.0000000001 (* 100 0.55))

(test::assert-error (* 1 2 4 "5"))

`euler`	Type: Float
`math::euler`	`Usage: (print e)`

Float representing euler’s number.


Example:

(ns-import 'math)

(test::assert-equal 2.718281828459045 *e*)

`pi`	Type: Float
`math::pi`	`Usage: (print pi)`

Float representing pi.


Example:

(ns-import 'math)

(test::assert-equal 3.141592653589793 *pi*)

`+`	Type: Function
`root::+`	`Usage: (+ number*)`

Add a sequence of numbers. (+) will return 0.


Example:

(ns-import 'math)

(test::assert-equal 0 (+))

(test::assert-equal 5 (+ 5))

(test::assert-equal 5 (+ (values 5)))

(test::assert-equal 5 (+ (values 5 6)))

(test::assert-equal 10 (+ 5 (values 5 6)))

(test::assert-equal 5 (+ 5.0))

(test::assert-equal 6 (+ 1 5))

(test::assert-equal 6.5 (+ 1 5.5))

(test::assert-equal 7 (+ 1 2 4))

(test::assert-error (+ 1 2 4 "5"))

`-`	Type: Function
`root::-`	`Usage: (- number+)`

Subtract a sequence of numbers. Requires at least one number (negate if only one number).


Example:

(ns-import 'math)

(test::assert-error (-))

(test::assert-error (- 5 "2"))

(test::assert-equal -5 (- 5))

(test::assert-equal -5.0 (- 5.0))

(test::assert-equal -4 (- 1 5))

(test::assert-equal -4.5 (- 1 5.5))

(test::assert-equal 4 (- 10 2 4))

(test::assert-equal 4.9 (- 10.9 2 4))

`/`	Type: Function
`root::/`	`Usage: (/ number+)`

Divide a sequence of numbers. Requires at least two numbers.


Example:

(ns-import 'math)

(test::assert-equal 5 (/ 50 10))

(test::assert-equal 5 (/ 50.0 10.0))

(test::assert-equal 0 (/ 1 5))

(test::assert-equal .2 (/ 1.0 5))

(test::assert-equal .2 (/ 1.0 5.0))

(test::assert-equal 5.5 (/ 5.5 1))

(test::assert-equal 2 (/ 16 2 4))

(test::assert-equal 5 (/ 100 2 5 2))

(test::assert-error (/))

(test::assert-error (/ 1))

(test::assert-error (/ 1 0))

(test::assert-error (/ 10 5 0))

(test::assert-error (/ 10 "5" 2))

`2pow`	Type: Function
`math::2pow`	`Usage: (2pow base)`

Raise 2 to power of argument.


Example:

(ns-import 'math)

(test::assert-equal 1024 (2pow 10))

(test::assert-equal (2pow (* 10 2)) (pow (2pow 10) 2))

`abs`	Type: Function
`math::abs`	`Usage: (abs arg)`

Returns absolute value of arg.


Example:

(ns-import 'math)

(test::assert-equal 2.0 (abs 2))

(test::assert-equal 144 (abs -144))

(test::assert-equal 4.53 (abs -4.53))

`arccos`	Type: Function
`math::arccos`	`Usage: (arccos num)`

Take arccos of argument


Example:

(ns-import 'math)

(test::assert-equal 0.01 (cos (arccos 0.01)))

`arcsin`	Type: Function
`math::arcsin`	`Usage: (arcsin num)`

Take arcsin of argument


Example:

(ns-import 'math)

(test::assert-equal 0.01 (sin (arcsin 0.01)))

`arctan`	Type: Function
`math::arctan`	`Usage: (arctan num)`

Take arctan of argument


Example:

(ns-import 'math)

(test::assert-equal 0.01 (tan (arctan 0.01)))

`ceil`	Type: Function
`math::ceil`	`Usage: (ceil value)`

Returns smallest integer greater than or equal to value.


Example:

(ns-import 'math)

(test::assert-equal 2.0 (ceil 2))

(test::assert-equal 145 (ceil 144.444444))

(test::assert-equal 5 (ceil 4.53))

`cos`	Type: Function
`math::cos`	`Usage: (cos num)`

Take cos of argument


Example:

(ns-import 'math)

(test::assert-equal -0.14550003380861354 (cos 8))

(test::assert-equal (cos 6) (/ (sin 6) (tan 6)))

`exp`	Type: Function
`math::exp`	`Usage: (exp num)`

Returns e ^ num, the exponential function.


Example:

(ns-import 'math)

(test::assert-equal *euler* (exp 1))

(test::assert-equal 1 (exp 0))

(test::assert-equal 42 (exp (lne 42)))

`floor`	Type: Function
`math::floor`	`Usage: (floor value)`

Returns largest integer less than or equal to value.


Example:

(ns-import 'math)

(test::assert-equal 2.0 (floor 2))

(test::assert-equal 144 (floor 144.444444))

(test::assert-equal 4 (floor 4.53))

`fract`	Type: Function
`math::fract`	`Usage: (fract num)`

Returns fractional part of a number


Example:

(ns-import 'math)

(test::assert-equal 0.9893582466233818 (fract 1911.9893582466233818))

(test::assert-equal 0.0 (fract 1911))

`lne`	Type: Function
`math::lne`	`Usage: (lne num)`

Returns natural logarithm of number


Example:

(ns-import 'math)

(def x 7.0)

(def y 11.0)

(test::assert-equal 1 (lne *euler*))

(test::assert-equal 0 (lne 1))

(test::assert-equal (lne (* x y)) (+ (lne x) (lne y)))

(test::assert-equal (lne (/ x y)) (- (lne x) (lne y)))

(test::assert-equal (lne (pow x y)) (* y (lne x)))

`log`	Type: Function
`math::log`	`Usage: (log num base)`

Returns log of number given base.


Example:

(ns-import 'math)

(test::assert-equal 8 (log 256 2))

(test::assert-equal 3 (log 27 3))

(test::assert-equal (log (pow 8 2) 10) (* 2 (log 8 10)))

(test::assert-equal 1 (log 11 11))

(test::assert-equal '-inf (log 0 11))

(test::assert-equal (log 11 5) (/ (log 11 3) (log 5 3)))

`log2`	Type: Function
`math::log2`	`Usage: (log2 num)`

Returns log base 2 of input.


Example:

(ns-import 'math)

(test::assert-equal 7 (log2 128))

(test::assert-equal (log 7 2) (/ 1.0 (log 2 7)))

`pow`	Type: Function
`math::pow`	`Usage: (pow base power)`

Raise first argument to power of second argument.


Example:

(ns-import 'math)

(test::assert-equal 16 (pow 4 2))

(test::assert-equal 10 (log (pow 2 10) 2))

(test::assert-equal (pow 8 15) (* (pow 8 10) (pow 8 5)))

(test::assert-equal (pow 100 3) (/ (pow 100 5) (pow 100 2)))

(test::assert-equal 1 (pow 85 0))

`round`	Type: Function
`math::round`	`Usage: (round arg)`

Round arg to nearest int value.


Example:

(ns-import 'math)

(test::assert-equal 2.0 (round 2))

(test::assert-equal 144 (round 144.444444))

(test::assert-equal 5 (round 4.53))

`sin`	Type: Function
`math::sin`	`Usage: (sin num)`

Take sin of argument


Example:

(ns-import 'math)

(test::assert-equal 0.9893582466233818 (sin 8))

(test::assert-equal (sin 6) (* (tan 6) (cos 6)))

`sqrt`	Type: Function
`math::sqrt`	`Usage: (sqrt num)`

Take square root of argument.


Example:

(ns-import 'math)

(test::assert-equal 2.0 (sqrt 4))

(test::assert-equal 2.04939015319192 (sqrt 4.2))

(test::assert-equal 12 (sqrt 144))

`tan`	Type: Function
`math::tan`	`Usage: (tan num)`

Take tan of argument


Example:

(ns-import 'math)

(test::assert-equal -6.799711455220379 (tan 8))

(test::assert-equal (tan 6) (/ (sin 6) (cos 6)))

`to-degrees`	Type: Function
`math::to-degrees`	`Usage: (to-degrees num)`

Convert degrees to radians.


Example:

(ns-import 'math)

(test::assert-equal 0 (- (to-degrees *pi*) 180))

`to-radians`	Type: Function
`math::to-radians`	`Usage: (to-radians num)`

Convert degrees to radians.


Example:

(ns-import 'math)

(test::assert-equal 0 (- *pi* (to-radians 180)))

Namespace forms

`ns-auto-export`	Type: Macro
`root::ns-auto-export`	`Usage: (ns-auto-export symbol)`

Macro that takes a symbol, the symbol of the current namespace, and writes an ns-export statement that includes all symbols defined in the namespaces scope that do not begin with the ‘-‘ symbol. This is a convenience method that allows user to avoid enumerating all symbols while also introducing a mechanism to exclude symbols from being excluded. Note, if using ns-auto-export, it is not possible to export a symbol that is already defined in another namespace, if said functionality is desired the symbol must be manually exported with another ns-export statement; ns-auto-export can be used in conjunction with ns-export.

`ns-create`	Type: Function
`root::ns-create`	`Usage: (ns-create namespace)`

Creates and enters a new a namespace (must evaluate to a string or symbol).


Example:

(ns-push 'test-ns-create)

(def test-ns-enter *ns*)

(ns-create 'ns-create-test-namespace)

(def test-symbol "testing")

(test::assert-equal "testing" test-symbol)

(ns-enter test-ns-create::test-ns-enter)

(test::assert-false (def? test-symbol))

(ns-pop)

#t

`ns-enter`	Type: Function
`root::ns-enter`	`Usage: (ns-enter namespace)`

Enters an existing namespace (must evaluate to a string or symbol).


Example:

(ns-push 'test-ns-enter)

(def test-ns-enter *ns*)

(ns-create 'ns-enter-test-namespace)

(def test-symbol "testing")

(test::assert-equal "testing" test-symbol)

(ns-enter test-ns-enter::test-ns-enter)

(test::assert-false (def? test-symbol))

(ns-enter 'ns-enter-test-namespace)

(test::assert-true (def? test-symbol))

(test::assert-equal "testing" test-symbol)

(ns-enter test-ns-enter::test-ns-enter)

(ns-pop)

#t

`ns-exists?`	Type: Function
`root::ns-exists?`	`Usage: (ns-exists? namespace)`

True if the supplied namespace exists (must evaluate to a string or symbol).


Example:

(test::assert-false (ns-exists? 'ns-exists-test-namespace))

(ns-push 'ns-exists-test-namespace)

(ns-pop)

(test::assert-true (ns-exists? 'ns-exists-test-namespace))

`ns-export`	Type: Macro
`root::ns-export`	`Usage: (ns-export symbol_or_sequence)`

Export a symbol or list of symbols to be imported into other namespaces.

`ns-import`	Type: Macro
`root::ns-import`	`Usage: (ns-import namespace)`

Import any symbols exported from namespace into the current namespace.

`ns-list`	Type: Function
`root::ns-list`	`Usage: (ns-list)`

Returns a vector of all namespaces.


Example:

(test::assert-not-includes "ns-list-test-namespace" (ns-list))

(ns-push 'ns-list-test-namespace)

(ns-pop)

(test::assert-includes "ns-list-test-namespace" (ns-list))

`ns-pop`	Type: Macro
`root::ns-pop`	`Usage: (ns-pop)`

Returns to the previous namespace saved in the last ns-push.


Example:

(def test-ns-pop *ns*)

(ns-push 'ns-pop-test-namespace)

(test::assert-equal "ns-pop-test-namespace" *active-ns*)

(ns-pop)

(test::assert-equal test-ns-pop *ns*)

`ns-push`	Type: Macro
`root::ns-push`	`Usage: (ns-push 'namespace)`

Pushes the current namespace on a stack for ns-pop and enters or creates namespace.


Example:

(def test-ns-push *ns*)

(ns-push 'ns-pop-test-namespace)

; *ns* will not be right...

(test::assert-equal "ns-pop-test-namespace" *active-ns*)

(ns-push 'ns-pop-test-namespace2)

(test::assert-equal "ns-pop-test-namespace2" *active-ns*)

(ns-pop)

(test::assert-equal "ns-pop-test-namespace" *active-ns*)

(ns-pop)

(test::assert-equal test-ns-push *ns*)

`ns-symbols`	Type: Function
`root::ns-symbols`	`Usage: (ns-symbols namespace)`

Returns the list of all symbols in namespace (must evaluate to a string or symbol).


Example:

(test::assert-includes 'loop (ns-symbols 'root))

(test::assert-not-includes 'dumb-symbol-xxx (ns-symbols 'root))

(test::assert-includes 'car (ns-symbols 'root))

Pair forms

Operations on the ‘Pair’ type (aka Cons Cell) that can be used to create traditional Lisp list structures. These are the default list structure and are produced with bare parentheses in code. These lists can also be created by building them up with joins or with the list form.

`car`	Type: Function
`root::car`	`Usage: (car pair)`

Return the car (first item) from a pair. If used on a proper list this will be the first element.


Example:

(def tst-pairs-two (list 'x 'y 'z))

(test::assert-equal 'x (car tst-pairs-two))

(test::assert-equal 10 (car '(10)))

(test::assert-equal 9 (car '(9 11 13)))

`cdr`	Type: Function
`root::cdr`	`Usage: (cdr pair)`

Return the cdr (second item) from a pair. If used on a proper list this will be the list minus the first element.


Example:

(def tst-pairs-three (list 'x 'y 'z))

(test::assert-equal '(y z) (cdr tst-pairs-three))

(test::assert-equal nil (cdr '(10)))

(test::assert-equal '(13) (cdr '(9 13)))

(test::assert-equal '(11 13) (cdr '(9 11 13)))

`join`	Type: Function
`root::join`	`Usage: (join car cdr)`

Create a pair with the provided car and cdr.


Example:

(def tst-pair-one (join 1 2))

(test::assert-equal 1 (car tst-pair-one))

(test::assert-equal 2 (cdr tst-pair-one))

(test::assert-equal '(1 2 3) (join 1 (join 2 (join 3 nil))))

`list`	Type: Function
`root::list`	`Usage: (list item0 item1 .. itemN)`

Create a proper list from pairs with items 0 - N.


Example:

(test::assert-equal '(1 2 3) (list 1 2 3))

`xar!`	Type: Function
`root::xar!`	`Usage: (xar! pair expression)`

Destructive form that replaces the car (first item) in a pair with a new expression. If used on a proper list will replace the first item. Can be used on nil to create a pair (expression . nil).


Example:

(def tst-pairs-three (list 'x 'y 'z))

(test::assert-equal '(x y z) tst-pairs-three)

(test::assert-equal '(s y z) (xar! tst-pairs-three 's))

(test::assert-equal '(s y z) tst-pairs-three)

(def tst-pairs-four nil)

(test::assert-equal '() tst-pairs-four)

(test::assert-equal '(t) (xar! tst-pairs-four 't))

(test::assert-equal '(t) tst-pairs-four)

`xdr!`	Type: Function
`root::xdr!`	`Usage: (xdr! pair expression)`

Destructive form that replaces the cdr (second item) in a pair with a new expression. If used on a proper list will replace everthing after the first item. Can be used on nil to create a pair (nil . expression).


Example:

(def tst-pairs-five (list 'a 'b 'c))

(test::assert-equal '(a b c) tst-pairs-five)

(test::assert-equal '(a y z) (xdr! tst-pairs-five '(y z)))

(test::assert-equal '(a y z) tst-pairs-five)

(def tst-pairs-six nil)

(test::assert-equal '() tst-pairs-six)

(test::assert-equal '(nil . v) (xdr! tst-pairs-six 'v))

(test::assert-equal '(nil . v) tst-pairs-six)