nydp 0.4.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 93571312813f5383bd47d92b298cd95b0239f07e
-  data.tar.gz: 242349e0186b701a602e94cbfdba9a1adfb5d5bb
+SHA256:
+  metadata.gz: adb6cc0345ed64c1e0e7ac99c06d9aa1328482e7d51d771cd77b844e1c5a6e14
+  data.tar.gz: 997c1f318ed518f3d2100699c1532db9a140f7109d6e4ddef6e68055466eb23a
 SHA512:
-  metadata.gz: 47e4c03909bcc94e0440d35f6a8e4f3cf36241832a89042456d18d556c6f8a34953d10382e2b5c17df6d28a7c530f9347c505cb6cf66931b9dcf18b34c2df88d
-  data.tar.gz: c899014050d46f2a093dec88a62f6a44ff70fffdd6bc66392338c33699f49c92e4ef0239d49e337685190757b318409d614a9319463dedd0bba1883526e78dc6
+  metadata.gz: 4a80109cc7bf73c177c6f89697e386a0a12d3645512bd14db2ed036711ef2c0b11d80fef67cff8dbc6f7bfed23d103220b9bc909aa9b34590323375db699c5e3
+  data.tar.gz: 25864fdef654329baef7d494a54b926f6dd236399f131e5943505752784713b03dc9e79640407c1df6af17ac380c483d82e2fae5e35fa3f3636b1226384eaa58

data/README.md

@@ -55,6 +55,22 @@ answer = Nydp.apply_function ns, :question, :life, ["The Universe", and_also(eve
 
 You can maintain multiple `ns` instances without mutual interference. In other words, assigning global variables while one `ns` is in scope will not affect the values of variables in any other `ns` (unless you've specifically arranged it to be so by duplicating namespaces or some such sorcery).
 
+
+#### Facing the Truth
+
+In conditional statements, nil is false, anything else is true
+
+```lisp
+(if)           ;; same as (if nil)
+(if a)         ;; same as a
+(if a b)       ;; same as (if a b nil)
+(if a b c)     ;; if a is nil, return c, otherwise return b
+(if a b c d)   ;; same as (if a b (if c d))
+(if a b c d e) ;; same as (if a b (if c d e))
+
+;; and so on
+```
+
 ## Different from Arc :
 
 #### 1. Macro-expansion runs in lisp
@@ -151,8 +167,36 @@ nydp > (map &lastname german-composers)   ; ampersand-syntax creates a function
 
 As with all other syntax, you can of course override the `ampersand-syntax` macro to handle your special needs.
 
+You can combine special syntaxes ("%td" comes from nydp-html gem)
+
+```lisp
+
+nydp > (map %td:&lastname german-composers)
+
+"<td>Bach</td><td>Beethoven</td><td>Wagner</td><td>Mozart</td>"
+
+```
+
+So, @%td@ expands to @(percent-syntax || td)@, @&lastname@ to @(ampersand-syntax || lastname)@, and the whole @%td:&lastname@
+to @(colon-syntax (percent-syntax || td) (ampersand-syntax || lastname))@. Luckily for you, there's a fine @colon-syntax@ macro
+that knows how to build a function out of these bits and pieces.
+
+
 Look for `SYMBOL_OPERATORS` in [parser.rb](lib/nydp/parser.rb) to see which syntax is recognised and in which order. The order of these definitions defines special-syntax-operator precedence.
 
+Any character that is not special syntax will be recognised as part of a symbol. At time of writing, this includes the plus sign, hyphen, and slash.
+
+```lisp
+
+;; nonsense code illustrating the use of certain
+;; characters as function and variable names
+(def //-+ (x y z)
+  (let -*- (x y)
+    (if z (//-+ x y -*-) -*-)))
+
+```
+
+
 #### 3. Special list syntax
 
 The parser detects alternative list delimiters

data/lib/lisp/core-010-precompile.nydp

@@ -1,17 +1,15 @@
-(assign mac-expand (fn (names macfn expr)
-  (cond macfn
-        (pre-compile-with names
-                          (apply macfn (cdr expr)))
-        expr)))
+(assign mac-expand
+        (fn (names macfn expr)
+            (cond macfn
+                  (handle-error
+                   (fn (errors)
+                       (error "expanding" (inspect expr) "with" (inspect macfn)))
+                   (fn ()
+                       (pre-compile-with names (apply macfn (cdr expr)))))
+                  expr)))
 
 (assign macs (hash))
 
-(assign pre-compile-expr
-        (fn (names expr)
-            (mac-expand names
-                        (hash-get names (car expr))
-                        expr)))
-
 (assign pre-compile-each
         (fn (names args)
             (cond args
@@ -33,7 +31,10 @@
                   (cond (eq? (car arg) 'quote)
                         arg
                         (pre-compile-each names
-                                          (pre-compile-expr names arg)))
+                                          (mac-expand names
+                                                      (hash-get names
+                                                                (car arg))
+                                                      arg)))
                   arg)))
 
 (assign pre-compile-debug
@@ -136,7 +137,3 @@
 
 (hash-set macs 'quasiquote
           (fn (arg) (qq-quasiquote arg 0)))
-
-(hash-set macs 'do
-          (fn args
-              `((fn nil ,@args))))

data/lib/lisp/core-012-utils.nydp

@@ -8,7 +8,7 @@
                                    (car args))
                              nil)))
 
-(def map-helper-0 (f things lc _)
+(def map-helper-0 (f things lc)
   (if (pair? things)
       (map-helper-0 f (cdr things) (cdr-set lc (cons (f (car things)))))
       things
@@ -30,8 +30,9 @@
 (def map (f things)
   (map-helper-1 f things (cons)))
 
+;; push 'v onto the value for 'k in 'h
+;; the hash-values of h will all be lists, in reverse order of consing
 (def hash-cons (h k v)
-  ; push 'v onto the value for 'k in 'h
   (hash-set h k (cons v (hash-get h k))))
 
 (def rev (things last-cdr)

data/lib/lisp/core-015-documentation.nydp

@@ -19,6 +19,12 @@
                                  acc)))
       form))
 
+(hash-set macs 'do
+          (fn forms
+              (if (no (cdr forms))
+                  (car forms)
+                  `((fn nil ,@forms)))))
+
 ((fn (this-chapter-name chapters chapter-new chapter-build chapter-add-to-chapter)
      (assign chapters (hash))
 
@@ -64,7 +70,7 @@
 (assign this-script nil)
 (assign this-plugin "Nydp Core")
 
-((fn (dox examples chapters types dox-new dox-build)
+((fn (dox examples chapters types types-chapters dox-new dox-build)
      (def dox-build (hsh name what texts args src chapters)
        (hash-set hsh 'name     name        )
        (hash-set hsh 'what     what        )
@@ -79,16 +85,20 @@
      (def dox-new (item)
        (hash-cons dox (hash-get item 'name) item)
        (hash-cons types (hash-get item 'what) item)
-       (dox-add-to-chapters item (hash-get item 'chapters)))
+       (dox-add-to-chapters item (hash-get item 'what) (hash-get item 'chapters) (hash)))
 
      (def dox-add-doc (name what texts args src chapters more)
        (cond (no (privately))
              (dox-new (dox-build (if more more (hash)) name what texts args src chapters))))
 
-     (def dox-add-to-chapters (item chapters)
+     (def dox-add-to-chapters (item type chapters already)
        (cond chapters
-             (do (chapter-add-item    item (car chapters))
-                 (dox-add-to-chapters item (cdr chapters)))
+         (cond (no (hash-get already (car chapters)))
+           (do (hash-set            already        (car chapters)                       t)
+               (chapter-add-item    item           (car chapters))
+               (hash-cons           types-chapters (inspect (cons type (car chapters))) item)
+               (dox-add-to-chapters item           type (cdr chapters) already))
+           item)
              item))
 
      (def dox-add-examples (name example-exprs)
@@ -102,6 +112,11 @@
      (def dox-types () (hash-keys types))
      (def dox-items-by-type (type) (hash-get types type))
 
+     (def get-types-chapters () types-chapters)
+
+     (def dox-items-by-type-and-chapter (dox-type chapter)
+       (hash-get types-chapters (inspect (cons dox-type chapter))))
+
      (def dox-get-attr (name attr)
        (cond (dox? name)
              (hash-get (car (dox-lookup name)) attr)))
@@ -111,7 +126,7 @@
      (def dox-examples  (name) (hash-get examples name  ))
      (def dox-args      (name) (dox-get-attr name 'args ))
      (def dox-example-names () (hash-keys examples      )))
- (hash) (hash) (hash) (hash) nil)
+ (hash) (hash) (hash) (hash) (hash) nil)
 
 (def plugin-start (name) (assign this-plugin name) (chapter-end))
 (def plugin-end   (name) (assign this-plugin nil ) (chapter-end))
@@ -128,9 +143,9 @@
                     (cond (eq? event 'script-end)
                           (script-end name))))))
 
+;; if the car of 'form is a key of 'hsh, add the cdr of 'form to the value of the key in 'hsh
+;; otherwise add the form to the list whose key is nil
 (def filter-form (hsh form)
-  ; if the car of 'form is a key of 'hsh, add the cdr of 'form to the value of the key in 'hsh
-  ; otherwise add the form to the list whose key is nil
   (cond (cond (pair? form)
               (hash-key? hsh (car form)))
       (hash-cons hsh (car form) (cdr form))
@@ -149,31 +164,43 @@
 (def rev-values (hsh)
   (rev-value-keys (hash-keys hsh) hsh (hash)))
 
+;; group forms by their first element, if the first element
+;; is already a key in hsh, collect all other elements under key nil
 (def filter-forms (hsh forms)
-  ; group forms by their first element, if the first element
-  ; is already a key in hsh, collect all other elements under key nil
   (cond forms
         (filter-forms (filter-form hsh (car forms)) (cdr forms))
         (rev-values hsh)))
 
-(def build-def-hash (hsh)
-  (hash-set hsh 'comment nil)
-  (hash-set hsh 'chapter nil)
-  hsh)
+(def filter-remove (key forms keyforms otherforms)
+  (cond forms
+        (cond (cond (pair? forms) (cond (pair? (car forms)) (eq? key (caar forms))))
+              (filter-remove key (cdr forms) (cons (car forms) keyforms) otherforms)
+              (filter-remove key (cdr forms) keyforms (cons (car forms) otherforms)))
+        (list (rev keyforms) (rev otherforms))))
 
+(assign DEF-FORMS '(comment chapter))
+
+(def build-def-hash ()
+  ((fn (h)
+       (map (fn (k) (hash-set h k nil)) DEF-FORMS)
+       h)
+   (hash)))
+
+(def dox-build-def-name (name) name)
+
+;; used internally by 'mac
 (def define-mac-expr (name args body-forms)
-  ; used internally by 'mac
   `(do (hash-set macs ',name (fun ,args ,@(hash-get body-forms nil)))
-       (dox-add-doc ',name
+       (dox-add-doc ',(dox-build-def-name name)
                     'mac
-                    ',(map car (hash-get body-forms 'comment))
+                    ',(+ (fetch-and-clear-comments) (map car (hash-get body-forms 'comment)))
                     ',args
                     '(mac ,name ,args ,@(hash-get body-forms nil))
                     ',(map car (hash-get body-forms 'chapter)))))
 
 (hash-set macs 'mac
           (fn (name args . body)
-              (define-mac-expr name args (filter-forms (build-def-hash (hash)) body))))
+              (define-mac-expr name args (filter-forms (build-def-hash) body))))
 
 (dox-add-doc 'mac
              'mac
@@ -189,22 +216,26 @@
              '`((fn nil ,@args))
              '(nydp-core))
 
+;; override later to use '= instead of 'assign, giving us hash-assignment and other goodies for free
 (mac def-assign args `(assign ,@args))
 
+;; used internally by 'def
 (def define-def-expr (name args body-forms)
-  ; used internally by 'def
-  `(do (def-assign ,name (fun ,args ,@(filter-comments (hash-get body-forms nil))))
-       (dox-add-doc ',name
+  `(do (def-assign ,name
+         ((fn (self-name)
+              (fun ,args ,@(filter-comments (hash-get body-forms nil))))
+          ',name))
+       (dox-add-doc ',(dox-build-def-name name)
                     'def
                     ',(+ (fetch-and-clear-comments) (map car (hash-get body-forms 'comment)))
                     ',args
                     '(def ,name ,args ,@(hash-get body-forms nil))
                     ',(map car (hash-get body-forms 'chapter)))))
 
+;; define a new function in the global namespace
 (mac def (name args . body)
-  ; define a new function in the global namespace
   (chapter nydp-core)
-  (define-def-expr name args (filter-forms (build-def-hash (hash)) body)))
+  (define-def-expr name args (filter-forms (build-def-hash) body)))
 
 (mac comment (txt)
   (assign comments (cons txt comments))

data/lib/lisp/core-017-builtin-dox.nydp

@@ -1,6 +1,7 @@
 (dox-add-doc 'cons      'def '("with args a and b, returns a new cons cell, (a . b)")                                                                            '(a b)                nil '(list-manipulation))
 (dox-add-doc 'car       'def '("with args a, where a is a cons cell (x . y), return x." "Commonly used to get the first element of a list")                      '(a)                  nil '(list-manipulation))
 (dox-add-doc 'cdr       'def '("with args a, where a is a cons cell (x . y), return y." "Commonly used to get contents of a list, excluding the first element")  '(a)                  nil '(list-manipulation))
+(dox-add-doc 'log       'def '("write arg to Nydp.logger ; be sure to assign Nydp.logger first!")                                                                '(arg)                nil '(nydp-core))
 (dox-add-doc '+         'def '("with rest-args things, return the sum of the elements of things." "Will also increment dates and concatenate strings and lists") 'things               nil '(math))
 (dox-add-doc '-         'def '("return the result of subtracting all other args from the first arg." "(- a b c d) is equivalent to (- a (+ b c d))")             'things               nil '(math))
 (dox-add-doc '*         'def '("with rest-args things, return the product of the elements of things.")                                                           'things               nil '(math))
@@ -35,21 +36,22 @@
 (dox-add-doc 'pair?     'def '("t if arg is a cons cell or (equivalently) the start of a list")                                                                  '(arg)                nil '(nydp-core))
 (dox-add-doc 'hash?     'def '("t if arg is a hash")                                                                                                             '(arg)                nil '(nydp-core))
 (dox-add-doc 'sym?      'def '("t if arg is a symbol, nil otherwise")                                                                                            '(arg)                nil '(nydp-core))
-(dox-add-doc 'ensuring  'def '("execute 'tricky-f, then 'ensure-f afterwards"
-                               "'ensure-f will always be executed, even if there is an error in 'tricky-f"
-                               "returns the return value of 'tricky-f")                                                                                          '(ensure-f tricky-f)  nil '(flow-control))
+(dox-add-doc 'ensuring  'def '("execute 'try-f, then 'ensure-f afterwards"
+                               "'ensure-f will always be executed, even if there is an error in 'try-f"
+                               "returns the return value of 'try-f. Similar to try/finally in java, or begin/ensure in ruby.")                                   '(ensure-f try-f)  nil '(flow-control))
 (dox-add-doc 'inspect   'def '("return a string representing 'arg, potentially (but not always) in a way that can be parsed back in to get the original object") '(arg)                nil '(nydp-core))
 (dox-add-doc 'comment   'def '("does nothing at all." "Intercepted inside 'def and 'mac and used for documentation")                                             '(arg)                nil '(nydp-core))
 (dox-add-doc 'parse-in-string 'def '("parse the given string assuming a string-open delimiter has already been encountered")                                     '(str)                nil '(nydp-core))
 (dox-add-doc 'rand            'def '("return a random number ; with no args, between 0 and 1"
                                      "with 1 arg, an integer less than arg"
-                                     "with two args, an integer >= arg 0 and < arg 1")                                                                           'args                 nil '(math))
-(dox-add-doc 'random-string   'def '("return a random string of length 'len (default 10)")                                                                       '(len)                nil '(string-manipulation))
-(dox-add-doc 'to-string       'def '("return a human-readable string representation of 'arg")                                                                    '(arg)                nil '(string-manipulation))
-(dox-add-doc 'string-length   'def '("return the length of 'arg")                                                                                                '(arg)                nil '(string-manipulation))
-(dox-add-doc 'string-replace  'def '("replace 'pattern with 'insert in 'str")                                                                                    '(pattern insert str) nil '(string-manipulation))
-(dox-add-doc 'string-split    'def '("split 'str delimited by 'delim")                                                                                           '(str delim)          nil '(string-manipulation))
-(dox-add-doc 'string-match    'def '("if 'str matches 'pattern, return hash with keys 'match and 'captures ; otherwise nil")                                     '(str pattern)        nil '(string-manipulation))
+                                     "with two args, an integer >= arg 0 and < arg 1")                                                                           'args                      nil '(math))
+(dox-add-doc 'random-string   'def '("return a random string of length 'len (default 10)")                                                                       '(len)                     nil '(string-manipulation))
+(dox-add-doc 'regexp          'def '("return a regular expression compiled from the given string")                                                               '(str)                     nil '(string-manipulation))
+(dox-add-doc 'to-string       'def '("return a human-readable string representation of 'arg")                                                                    '(arg)                     nil '(string-manipulation))
+(dox-add-doc 'string-length   'def '("return the length of 'arg")                                                                                                '(arg)                     nil '(string-manipulation))
+(dox-add-doc 'string-replace  'def '("replace 'pattern with 'replacement in 'str")                                                                               '(pattern replacement str) nil '(string-manipulation))
+(dox-add-doc 'string-split    'def '("split 'str delimited by 'delim")                                                                                           '(str delim)               nil '(string-manipulation))
+(dox-add-doc 'string-match    'def '("if 'str matches 'pattern, return hash with keys 'match and 'captures ; otherwise nil")                                     '(str pattern)             nil '(string-manipulation))
 (dox-add-doc 'time            'def '("with no args, return the current time."
                                      "With one arg, if 'arg-0 is a number, return the current time plus 'arg-0 seconds."
                                      "With one arg, if 'arg-0 is a date, return the time at the beginning of the given date."
@@ -57,9 +59,9 @@
                                      "With two args, 'arg-0 must be a time."
                                      "If 'arg-1 is a number, return 'arg-0 plus 'arg-1 seconds as a time object."
                                      "If 'arg-1 is a time, return the number of seconds between the two (- 'arg-0 arg-1)."
-                                     "Otherwise, expect 3, 4, 5, or 6 args, to construct a time from"
+                                     "Otherwise, expect 3 or more args, to construct a time from"
                                      "year, month, date, hours, minutes, seconds, milliseconds, reading arguments in that order,"
-                                     "where hours, minutes, seconds, and milliseconds are optional")                                                             'args                 nil '(date-time))
+                                     "where hours, minutes, seconds, and milliseconds are optional")                                                               'args                 nil '(date-time))
 (dox-add-doc 'thread-locals     'def '("return a hash bound to the current thread")                                                                                nil                   nil '(nydp-core))
 (dox-add-doc 'type-of           'def '("return a symbol for the type of 'arg")                                                                                     '(arg)                nil '(nydp-core))
 (dox-add-doc 'eq?               'def '("return 't if 'arg-0 and 'arg-1 are equal, nil otherwise")                                                                  '(arg-0 arg-1)        nil '(nydp-core))

data/lib/lisp/core-020-utils.nydp

@@ -1,4 +1,4 @@
-(assign script-name "core-012-utils.nydp")
+(assign script-name "core-020-utils.nydp")
 
 (dox-add-doc 'if
              'mac
@@ -43,12 +43,12 @@
              '(hash-set h k (cons v (hash-get h k)))
              '(hash-manipulation))
 
+;; equivalent to (join-str "~prefix~joint~(car things)" joint (cdr things)) - except
+;; 'string-pieces hasn't been defined yet, and if it were, it would be defined in terms of
+;; 'join-str, so it would be circular.
+;; see 'joinstr for a more powerful and easier-to-use implementation of the same idea
 (def join-str (prefix joint things)
   (chapter string-manipulation)
-  ; equivalent to (join-str "~prefix~joint~(car things)" joint (cdr things)) - except
-  ; 'string-pieces hasn't been defined yet, and if it were, it would be defined in terms of
-  ; 'join-str, so it would be circular.
-  ; see 'joinstr for a more powerful and easier-to-use implementation of the same idea
   (if things
       (join-str (+ (to-string prefix)
                    joint

data/lib/lisp/core-030-syntax.nydp

@@ -21,16 +21,26 @@ scoping, assignment, anonymous functions and more...")
               (apply orf
                      (cdr args)))))
 
+; returns true if 'things is a list and the first item of the
+; list is the given object
 (def caris (obj things)
-  ; returns true if 'things is a list and the first item of the
-  ; list is the given object
   (and (pair? things)
-       (eq? (car things)  obj)))
+       (eq? (car things) obj)))
 
+; evaluate 'body if 'arg is nil
 (mac unless (arg . body)
-  ; evaluate 'body if 'arg is nil
   `(if (no ,arg) (do ,@body)))
 
+; looks up a key in @
+; assumes local lexical context has defined a hash called '@
+(mac prefix-at-syntax (name . names)
+  `(hash-get @ ',name))
+
+(mac at-syntax names
+  (if (eq? (car names) '||)
+      `(prefix-at-syntax ,@(cdr names))
+      (error "unknown at-syntax: expected prefix-syntax (eg @name), got ~(join-str (car names) "@" (cdr names))")))
+
 (def expand-colon-syntax (names)
   (if (no (cdr names))
           `(apply ,(car names) args)
@@ -84,13 +94,17 @@ scoping, assignment, anonymous functions and more...")
       (cons (list (car things) (cadr things))
             (pairs (cddr things)))))
 
+;; like 'let, but creates and assigns multiple local variables.
+;; for example, "(with (a 1 b 2) (+ a b))" returns 3
 (mac with (parms . body)
-     `((fun ,(map car (pairs parms))
-            ,@body)
-       ,@(map cadr (pairs parms))))
+  `((fun ,(map car (pairs parms))
+         ,@body)
+    ,@(map cadr (pairs parms))))
 
+;; create a lexical scope
+;; where val is assigned to var, execute 'body in that scope
 (mac let (var val . body)
-     `(with (,var ,val) ,@body))
+  `((fun (,var) ,@body) ,val))
 
 (mac rfn (name parms . body)
   ; creates a named, locally-scoped function
@@ -105,17 +119,28 @@ scoping, assignment, anonymous functions and more...")
   ; same as 'rfn, but using the name 'self
   `(rfn self ,parms ,@body))
 
+;; a mix of rfn and with; creates a locally-scoped named function with
+;; the given parameter names, and invokes it with the given parameter
+;; values. It is possible to reference the function by its name from
+;; within the function (to pass as an argument or for recursive
+;; invocation)
 (mac rfnwith (name params . body)
-  ; a mix of rfn and with; creates a locally-scoped named function with
-  ; the given parameter names, and invokes it with the given parameter
-  ; values. It is possible to reference the function by its name from
-  ; within the function (to pass as an argument or for recursive
-  ; invocation)
   (let ppairs (pairs params)
     `(let ,name nil
        (assign ,name (fun ,(map car ppairs) ,@body))
        (,name ,@(map cadr ppairs)))))
 
+;; (andify a b c) is equivalent to
+;; (fn args (and (apply a args) (apply b args) (apply c args)))
+;; or more simply
+;; (fn (x) (and (a x) (b x) (c x)))
+;; note: alias as 'andf ??
+(def andify args
+  (fn args2 (rfnwith self (ands args)
+                     (if ands (if (apply (car ands) args2)
+                                  (self (cdr ands)))
+                         t))))
+
 (let uniq-counter 0
   (def uniq (prefix)
     (assign uniq-counter (+ uniq-counter 1))
@@ -123,9 +148,9 @@ scoping, assignment, anonymous functions and more...")
   (def reset-uniq-counter ()
     (assign uniq-counter 0)))
 
+;; creates a lexical scope with a unique symbol assigned to
+;; each variable in 'vars ; executes the 'body.
 (mac w/uniq (vars . body)
-  ; creates a lexical scope with a unique symbol assigned to
-  ; each variable in 'vars ; executes the 'body.
   (if (pair? vars)
       `(with ,(apply + (map (fn (n) `(,n (uniq ',n))) vars))
              ,@body)
@@ -194,37 +219,79 @@ scoping, assignment, anonymous functions and more...")
   (and (pair? name)
        (caris 'ampersand-syntax (car name))))
 
+;; (= (&key (expr)) (val))
+;; (= ((ampersand-syntax key) (expr)) (val))
+;; 'place is ((ampersand-syntax || key) (expr))
+;; we need (hash-set (expr) 'key (val))
+;; however,
+;; (= (&key.subkey (expr)) (val))
+;; 'place is ((ampersand-syntax || (dot-syntax key subkey)) (expr))
+;; we need (hash-set (hash-get (expr) 'key) 'subkey (val))
 (def ampersand-expression-assignment (place value)
-  ; (= (&key (expr)) (val))
-  ; (= ((ampersand-syntax key) (expr)) (val))
-  ; 'place is ((ampersand-syntax || key) (expr))
-  ; we need (hash-set (expr) 'key (val))
-  ; however,
-  ; (= (&key.subkey (expr)) (val))
-  ; 'place is ((ampersand-syntax || (dot-syntax key subkey)) (expr))
-  ; we need (hash-set (hash-get (expr) 'key) 'subkey (val))
-  (with (k   (cadr:cdar place)
-         hsh (cadr place))
-    (if (caris 'dot-syntax k)
-        (dot-syntax-assignment (cons hsh (cdr k)) value)
-        `(hash-set ,hsh ',k ,value))))
-
-(mac = (name value)
-  ; generic assignment which unlike builtin 'assign, knows how to assign
-  ; to hash keys
-  ; (= (hash-get (expr) 'key) (val) => (hash-set (expr) 'key (val))
-  ; (= h.k (val))                   => (hash-set h 'k (val))
-  ; (= h.j.k (val))                 => (hash-set (hash-get h 'j) 'k (val))
-  ; (= (&key (expr)) (val))         => (hash-set (expr) 'key (val))
-  ; (= (&j.k (expr)) (val))         => (hash-set (hash-get (expr) 'j) 'k (val))
-  (if (isa 'symbol name)
-      `(assign ,name ,value)
-      (caris 'dot-syntax name)
-      (dot-syntax-assignment (cdr name) value)
-      (caris 'hash-get name)
-      (hash-get-assignment (cdr name) value)
-      (ampersand-expression? name)
-      (ampersand-expression-assignment name value)))
+  (let k (cadr:cdar place)
+    (let hsh (cadr place)
+      (if (caris 'dot-syntax k)
+          (dot-syntax-assignment (cons hsh (cdr k)) value)
+          `(hash-set ,hsh ',k ,value)))))
+
+;; used internally by 'destructuring-assign
+(def destructuring-assigns (names values acc)
+  (if names
+      (if (pair? names)
+          (destructuring-assigns
+            (cdr names)
+            `(cdr ,values)
+            (cons `(= ,(car names) (car ,values)) acc))
+          (cons `(= ,names ,values) acc))
+      (rev acc)))
+
+;; used internally by 'assign-expr
+(def destructuring-assign (name value)
+  (w/uniq destructuring-assign
+          `(let ,destructuring-assign ,value
+             ,@(destructuring-assigns name destructuring-assign))))
+
+;; used internally by '= macro
+(def assign-expr (nv)
+  (let name  (car nv)
+    (let value (cadr nv)
+      (if (isa 'symbol name)
+          `(assign ,name ,value)
+          (caris 'dot-syntax name)
+          (dot-syntax-assignment (cdr name) value)
+          (caris 'hash-get name)
+          (hash-get-assignment (cdr name) value)
+          (ampersand-expression? name)
+          (ampersand-expression-assignment name value)
+          (caris 'at-syntax name)
+          `(hash-set @ ',(caddr name) ,value)
+          (pair? name)
+          (destructuring-assign name value)
+          (error "unknown assignment to place: " (inspect name))))))
+
+;; generic assignment which unlike builtin 'assign, knows how to assign
+;; to hash keys
+;; (= (hash-get (expr) 'key) (val) => (hash-set (expr) 'key (val))
+;; (= h.k (val))                   => (hash-set h 'k (val))
+;; (= h.j.k (val))                 => (hash-set (hash-get h 'j) 'k (val))
+;; (= (&key (expr)) (val))         => (hash-set (expr) 'key (val))
+;; (= (&j.k (expr)) (val))         => (hash-set (hash-get (expr) 'j) 'k (val))
+(mac = assignments
+  `(do ,@(map assign-expr (pairs assignments))))
+
+;; like 'let, but creates and assigns multiple local variables.
+;; for example, "(with (a 1 b 2) (+ a b))" returns 3
+;;
+;; later variables can references earlier ones:
+;; (with (a 1 b 2 c (+ a b)) (list a b c)) ;; returns (1 2 3)
+(mac with (assignments . body)
+  `((fun ,(map car (pairs assignments))
+     (= ,@assignments)
+     ,@body) nil))
+
+;; quiet assignment ; like =, but expression returns nil
+(mac #= (name value)
+  `(do (= ,name ,value) nil))
 
 ; increment the value at 'place by 'inc (default 1)
 (mac ++ (place inc) `(= ,place (+ ,place ,(or inc 1))))
@@ -283,16 +350,25 @@ scoping, assignment, anonymous functions and more...")
 ; (eg hash), the mutated value will be returned. See also 'returnlet
 (mac returning (val . body) (w/uniq retval `(returnlet ,retval ,val ,@body)))
 
-(mac aif (expr . body)
-  ; like if, except the value of each condition is locally bound to the variable 'it
-  ; eg (aif (find thing) (show it))
-  ; source: arc.arc
-  `(let it ,expr
-     (if it
+(mac ifv (var expr . body)
+  `(let ,var ,expr
+     (if ,var
          ,@(if (cddr body)
-               `(,(car body) (aif ,@(cdr body)))
+               `(,(car body) (ifv ,var ,@(cdr body)))
                body))))
 
+; like if, except the value of each condition is locally bound to the variable 'it
+; eg (aif (find thing) (show it))
+; source: arc.arc
+(mac aif (expr . body)
+  `(ifv it ,expr ,@body))
+
+;; returns the n-th item in the list 'things
+(def nth (n things)
+  (if (eq? n 0)
+      (car things)
+      (nth (- n 1) (cdr things))))
+
 (def destructure/with (var args n)
   ; provides the argument expression to 'with when
   ; destructuring arguments are present in a 'fun definition
@@ -301,34 +377,52 @@ scoping, assignment, anonymous functions and more...")
       args
       `(,args (nthcdr ,n ,var))))
 
-(def destructure/build (given-args new-args body)
-  ; used internally by 'fun
+;; issue a warning if any arg name is the name of a macro
+(def fun/approve-arg-names (orig args body)
+  (if (pair? args)
+      (do (fun/approve-arg-names orig (car args) body)
+          (fun/approve-arg-names orig (cdr args) body))
+      args
+      (if (hash-get macs args)
+          (warnings/new 'arg-shadows-macro "arg " args " shadows macro " args " in arg list " orig " and body " body))))
+
+;; used internally by 'fun
+(def destructure/build (given-args new-args body next)
   (if (pair? given-args)
       (if (sym? (car given-args))
           (destructure/build (cdr given-args)
                              (cons (car given-args) new-args)
-                             body)
+                             body
+                             next)
           (w/uniq destructure
                   (destructure/build (cdr given-args)
                                      (cons destructure new-args)
-                                     `((with ,(destructure/with destructure (car given-args) 0) ,@body)))))
-      `(fn ,(rev new-args given-args) ,@body)))
-
-
-(def fun/approve-arg-names (orig args)
-  (if (pair? args)
-      (do (fun/approve-arg-names orig (car args))
-          (fun/approve-arg-names orig (cdr args)))
-      args
-      (if (hash-get macs args)
-          (warnings/new 'arg-shadows-macro "arg " args " shadows macro " args " in arg list " orig))))
-
+                                     `((with ,(destructure/with destructure (car given-args) 0) ,@body))
+                                     next)))
+      (next (rev new-args given-args) body)))
+
+(def fun/destructuring-args (args body next)
+  (fun/approve-arg-names args args body)
+  (destructure/build args nil body next))
+
+(assign fun/expanders
+        (list
+         (cons 'destructuring-args fun/destructuring-args)
+         (cons 'core-builder       (fn (args body next) `(fn ,args ,@body)))))
+
+(def fun/expand (args body expanders)
+  (if expanders
+      ((cdar expanders)
+       args
+       body
+       (fn (a b)
+           (fun/expand a b (cdr expanders))))))
+
+;; build a 'fn form, changing 'args and 'body to
+;; properly handle any destructuring args if present
 (mac fun (args . body)
-  ; build a 'fn form, changing 'args and 'body to
-  ; properly handle any destructuring args if present
-  (fun/approve-arg-names args args)
-  (destructure/build args nil body))
+  (fun/expand args body fun/expanders))
 
-; assign (f place) to place
+;; assign (f place) to place
 (mac zap (f place . args)
   `(= ,place (,f ,place ,@args)))