util.lsp
Module: util
Author: Jeff OberVersion: 1.4
Location: http://static.artfulcode.net/newlisp/util.lsp
Various functions that the other libraries depend on.
Various helpful utilities for newLISP. Due to a bug in newLISP 9.4.1's hash functionality, newLISP 9.4.2+ is required for this module to function properly.
Version history
1.4 • added slot-value • with-slots now supports string keys • fixed bug when calling with-slots from within a context • with-slots now permits renaming of variables in binding to avoid clashes in nested calls • added get-assoc • added dict-keys • added dokeys 1.3 • with-slots now supports assoc data in the format (key val-1 val-2 ...) and '(key val) 1.2 • fixed bug that caused with-slots to return only the first value of a list 1.1 • added fmap, with-slots, and add-assoc 1.0 • initial releasetype-of
syntax: (type-of object)parameter: object - any object
type-of introspects the type of the passed argument, object, and returns a string representation of its type. Correctly identifies FOOP types as well, returning the string value of the first argument (by calling name on the context of the list).
example:(type-of 10) => "integer" (type-of "hello world") => "string" (type-of true) => "boolean" (type-of '(1 2 3)) => "list" (type-of (fn (x) (+ x x))) => "lambda"
gensym
syntax: (gensym [ctx])parameter: ctx - optional; the context in which to create the symbol (default: MAIN)
Returns a symbol unique to the context passed. If ctx is nil, the symbol is created in MAIN. There is a hard limit on the number of possible symbols generated based on the max integer value of the system. Since newLISP wraps into negative numbers when passing the max value, the effective max value is twice the systems maximum integer value.
example:(gensym) => gensym-1 (gensym) => gensym-2 (define foo:foo) (gensym foo) => foo:gensym-1 (gensym foo) => foo:gensym-2
assoc?
syntax: (assoc? expr)parameter: expr - expression to be tested as an association list
Predicates that expr is an association list with a structure of '((key val) (key val) ...). To evaluate true key may have only one value, and keys must be symbols or strings. Only the first level is tested for associativity.
example:(assoc? '(1 2 3 4)) => nil (assoc? '((a 1) (b 2) (c 3))) => true (assoc? '((a 1) (b 2) (c (1 2 3 4)))) => true
get-assoc
syntax: (get-assoc expr)parameter: expr - association indexing of (assoc-list key-1 [key-2 ...])
Extracts the value of the association expression. Expressions are in the same format as with the assoc function, but the result is the same as the lookup function, except the multiple values are returned correctly.
example: (set 'data '((name "Joe") (friends "John" "Steve")))
(get-assoc (data 'name))
=> "Joe"
(get-assoc (data 'friends))
=> '("John" "Steve")slot-value
syntax: (slot-value slot inst)parameter: slot - string or symbol key for slot
parameter: inst - FOOP instance or assoc list
return: the value associated with slot in inst
slot-value returns the value of slot in FOOP instance or association list inst. The key may be either a string or a symbol.
example: (slot-value "x" '(("x" 10) ("y" 20)))
=> 10
(slot-value 'y '((x 10) (y 20)))
=> 20with-slots
syntax: (with-slots lst-keys instance body-forms*)parameter: lst-keys - list of key symbols present in instance
parameter: lst-assoc - FOOP instance or assoc list
parameter: body-forms* - forms to evaluate
return: the result of the last body-form
with-slots evaluates body-forms in an implicit let in which the symbols in lst-keys have been bound to their paired values in lst-assoc, which must be an association list.
lst-keys may either be a list of symbols (or strings, to intern as symbols) that represent keys in lst-assoc or a list of pairs, each consisting of a key in lst-assoc and the symbol which the key's value will be bound in the body-forms* block. This allows values to be bound to arbitrary symbols in order to avoid name clashes when nesting lists with similar structures.
It is good practice to use an association list for FOOP objects so that the order in which the values appear is unimportant. Using this convention, a FOOP object may also be used in place of lst-assoc.
example: (set 'rise 5 'run 20)
(set 'pt1 '((x 10) (y 30)))
(set 'pt2 '((x 20) (y 40)))
(with-slots (x y) pt1
(list (list 'x (+ x run))
(list 'y (+ y rise))))
=> '((x 30) (y 35))
(with-slots ((x x1) (y y1)) pt1
(with-slots ((x x2) (y y2)) pt2
(println "Point 1: " x1 ", " y1)
(println "Point 2: " x2 ", " y2)))
=> Point 1: 10, 30
=> Point 2: 20, 40fmap
syntax: (fmap sym-fun inst lst*)parameter: sym-fun - quoted symbol naming a context function
parameter: inst - a FOOP instance
parameter: lst* - one or more lists
FOOP methods cannot be easily mapped, since map would require that the function be passed as context:function, curried for the intended FOOP instance. However, currying truncates a function's lambda list to two parameters, the first being the second argument to curry.
fmap solves this, although not extremely efficiently, with a lambda that wraps the context function.
example:(define (Foo:Foo) (list (context))) (define (Foo:make-list inst a b) (list a b)) ; pairs two elements (let ((a '(1 2 3)) (b '(4 5 6)) (inst (Foo))) (fmap 'Foo:make-list inst a b)) => ((1 4) (2 5) (3 6))
dict-keys
syntax: (dict-keys context-dict)parameter: context-dict - context dictionary
Returns a list of keys in the dictionary context-dict.
example: (define dict:dict)
(dict "x" 10)
(dict "y" 20)
(dict-keys dict)
=> '("x" "y")dokeys
syntax: (dokeys (var dict) body)parameter: var - variable to which the key name will be bound
parameter: dict - dictionary from which the keys will be extracted
parameter: body - the body forms to be executed with var bound to dict's keys
Evaluates body in a local block in which var is sequentially bound to each of dict's keys. Note that there is no special ordering of the keys.
example:(define dict:dict) (dict "x" 10) (dict "y" 20) (dokeys (key dict) (println key ": " (dict key))) => x: 10 => y: 20
Artful Code
