nydp 0.4.0 → 0.4.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d9a87eb0c014a51f391ddd1ba6686165a01ab48
-  data.tar.gz: 8c3f3146c0ae8dc18ac6e86324274423d75be651
+  metadata.gz: '06876fcb6832d6737b4763607cfe7b4c0ca003c3'
+  data.tar.gz: b45d30570c913940f93585241c1dad9cc71c5872
 SHA512:
-  metadata.gz: f946a10304dd7422fb73243b9cd3ef40fab33aa9ff4f0b53568278761b64905d00714ed0cf7401db29b8c3613d8a683460ed48feef3f174ab0c724dd3e5f922e
-  data.tar.gz: 1925438dd0eca5a718e6f41ff39ef9f35e1a9ed18279e58f2ebfa88c284cb46526f4864932db706dc346662a59cb153fbec70fca1047aeddc742740de971dab5
+  metadata.gz: d874e4fbbba55a5995f699451bbf305fe7667f4058cdab2e713fe64900bc96ed285fe5ae8d0c460c73001f0a44fb22699c634c2017a723e9c79d818779d38b7e
+  data.tar.gz: 5d5f3aeb4e7c0e65af1024990fdfa5f73a8f4657a06dfd11aaeec172709615a3879f0bdff0efd19475a223add58ee1dd6379951548979eda5b80f30861967e61

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,16 +8,31 @@
                                    (car args))
                              nil)))
 
-(def map (f things)
-  ; transforms the list 'things by applying 'f to each item
-  ; returns the resulting list
+(def map-helper-0 (f things lc)
   (if (pair? things)
-      (cons (f (car things)) (map f (cdr things)))
+      (map-helper-0 f (cdr things) (cdr-set lc (cons (f (car things)))))
       things
-      (f things)))
+      (cdr-set lc (f things))))
+
+(def map-helper-1 (f things acc)
+  (map-helper-0 f things acc)
+  (cdr acc))
+
+;; transforms the list 'things by applying 'f to each item, returns the resulting list
+;; conceptually, does the following:
+;;
+;;   (if (pair? things)
+;;       (cons (f (car things)) (map f (cdr things)))
+;;       things
+;;       (f things))
+;;
+;; however the actual version is more complicated to allow for TCO ("modulo-cons" issue)
+(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

@@ -1,5 +1,28 @@
 (def privately () nil)
 
+(assign comments nil)
+
+(def fetch-and-clear-comments ()
+  ((fn (c) (assign comments nil) c) (rev comments)))
+
+(def filter-comments (form acc)
+  (if (no form)
+      (rev acc)
+      (pair? form)
+      (filter-comments (cdr form)
+                       (if (if (pair? (car form))
+                               (eq? (caar form)
+                                    'comment))
+                           acc
+                           (cons (filter-comments (car form)
+                                                  nil)
+                                 acc)))
+      form))
+
+(hash-set macs 'do
+          (fn forms
+              `((fn nil ,@forms))))
+
 ((fn (this-chapter-name chapters chapter-new chapter-build chapter-add-to-chapter)
      (assign chapters (hash))
 
@@ -45,7 +68,7 @@
 (assign this-script nil)
 (assign this-plugin "Nydp Core")
 
-((fn (dox examples chapters 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        )
@@ -59,26 +82,38 @@
 
      (def dox-new (item)
        (hash-cons dox (hash-get item 'name) item)
-       (dox-add-to-chapters item (hash-get item 'chapters)))
+       (hash-cons types (hash-get item 'what) item)
+       (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)
        (hash-cons examples name example-exprs))
 
-     (def dox-lookup (sym) (hash-get dox sym))
+     (def dox-lookup (name) (hash-get dox name))
 
      (def dox? (sym) (hash-key? dox sym))
 
      (def dox-names () (hash-keys dox))
+     (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)
@@ -89,7 +124,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) 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))
@@ -106,9 +141,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))
@@ -127,9 +162,9 @@
 (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)))
@@ -139,12 +174,14 @@
   (hash-set hsh 'chapter nil)
   hsh)
 
+(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)))))
@@ -169,17 +206,21 @@
 
 (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 ,@(hash-get body-forms nil)))
-       (dox-add-doc ',name
+  `(do (def-assign ,name (fun ,args ,@(filter-comments (hash-get body-forms nil))))
+       (dox-add-doc ',(dox-build-def-name name)
                     'def
-                    ',(map car (hash-get body-forms 'comment))
+                    ',(+ (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)))
+
+(mac comment (txt)
+  (assign comments (cons txt comments))
+  nil)

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,18 +36,21 @@
 (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 '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))
+(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 '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."
@@ -54,35 +58,42 @@
                                      "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))
-(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))
-(dox-add-doc 'cdr-set         'def '("set the cdr of the given 'cell to 'arg, returns 'cell")                                                                    '(cell arg)           nil '(list-manipulation))
-(dox-add-doc 'hash-get        'def '("return the value stored by 'key in 'hsh")                                                                                  '(hsh key)            nil '(hash-manipulation))
-(dox-add-doc 'hash-set        'def '("store 'val under 'key in 'hsh, return 'val")                                                                               '(hsh key val)        nil '(hash-manipulation))
-(dox-add-doc 'hash-keys       'def '("return the list of keys in 'hsh")                                                                                          '(hsh)                nil '(hash-manipulation))
-(dox-add-doc 'hash-key?       'def '("return 't if 'key is a key of 'hsh")                                                                                       '(hsh key)            nil '(hash-manipulation))
-(dox-add-doc 'hash-merge      'def '("return a new hash containing keys and values from 'h0 and 'h1, where values of 'h1 override values of 'h0")                '(h0 h1)              nil '(hash-manipulation))
-(dox-add-doc 'vm-info         'def '("return some information about the state of the current thread")                                                            nil                   nil '(nydp-core))
-(dox-add-doc 'pre-compile     'def '("transform parsed forms before the compile and eval stages")                                                                '(arg)                nil '(nydp-compilation))
-(dox-add-doc 'script-run      'def '("announces the start of a plugin load or a script load."
-                                     "'event may be one of '(script-start script-end plugin-start plugin-end)"
-                                     "'name is the name of the script or plugin concerned")                                                                      '(event name)         nil '(nydp-core))
+                                     "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))
+(dox-add-doc 'cdr-set           'def '("set the cdr of the given 'cell to 'arg, returns 'cell")                                                                    '(cell arg)           nil '(list-manipulation))
+(dox-add-doc 'hash-get          'def '("return the value stored by 'key in 'hsh")                                                                                  '(hsh key)            nil '(hash-manipulation))
+(dox-add-doc 'hash-set          'def '("store 'val under 'key in 'hsh, return 'val")                                                                               '(hsh key val)        nil '(hash-manipulation))
+(dox-add-doc 'hash-keys         'def '("return the list of keys in 'hsh")                                                                                          '(hsh)                nil '(hash-manipulation))
+(dox-add-doc 'hash-key?         'def '("return 't if 'key is a key of 'hsh")                                                                                       '(hsh key)            nil '(hash-manipulation))
+(dox-add-doc 'hash-merge        'def '("return a new hash containing keys and values from 'h0 and 'h1, where values of 'h1 override values of 'h0")                '(h0 h1)              nil '(hash-manipulation))
+(dox-add-doc 'vm-info           'def '("return some information about the state of the current thread")                                                            nil                   nil '(nydp-core))
+(dox-add-doc 'pre-compile       'def '("transform parsed forms before the compile and eval stages")                                                                '(arg)                nil '(nydp-compilation))
+(dox-add-doc 'script-run        'def '("announces the start of a plugin load or a script load."
+                                       "'event may be one of '(script-start script-end plugin-start plugin-end)"
+                                       "'name is the name of the script or plugin concerned")                                                                      '(event name)         nil '(nydp-core))
 
-(dox-add-doc 'chapter-end     'def '("Announce the end of a chapter. Called by 'plugin-start, 'plugin-end, 'script-start, 'script-end")                          nil                   nil '(nydp/documentation))
-(dox-add-doc 'chapter-start   'def '("Announce the start of a chapter. Creates a new chapter if the named chapter does not already exist")                 '(chapter-name description) nil '(nydp/documentation))
-(dox-add-doc 'chapter-names   'def '("Get the names of all the chapters nydp knows about")                                                                       nil                   nil '(nydp/documentation))
-(dox-add-doc 'chapter-current 'def '("Get the name of the chapter in progress right now - this is normally the last value sent to 'chapter-start")               nil                   nil '(nydp/documentation))
-(dox-add-doc 'chapter-delete  'def '("Remove the named chapter")                                                                                                 '(name)               nil '(nydp/documentation))
-(dox-add-doc 'chapter-find    'def '("Get the named chapter")                                                                                                    '(name)               nil '(nydp/documentation))
-(dox-add-doc 'dox-add-doc     'def '("Store the provided documentation item."
-                                     "'name is the name of the item"
-                                     "'what is the type of the item ('def or 'mac or 'thingy ... this is user-definable, not related to 'type-of)"
-                                     "'texts is a list of strings to store for this item"
-                                     "'args is the args if the item has the notion of args"
-                                     "'src the source code of the item if any"
-                                     "'chapters the chapters to which the item should be added, if any")                                          '(name what texts args src chapters) nil '(nydp/documentation))
-(dox-add-doc 'dox-add-examples 'def '("Add the given examples to the dox for the named item")                                                                    '(name example-exprs) nil '(nydp/documentation))
+(dox-add-doc 'chapter-end       'def '("Announce the end of a chapter. Called by 'plugin-start, 'plugin-end, 'script-start, 'script-end")                          nil                   nil '(nydp/documentation))
+(dox-add-doc 'chapter-start     'def '("Announce the start of a chapter. Creates a new chapter if the named chapter does not already exist")                 '(chapter-name description) nil '(nydp/documentation))
+(dox-add-doc 'chapter-names     'def '("Get the names of all the chapters nydp knows about")                                                                       nil                   nil '(nydp/documentation))
+(dox-add-doc 'chapter-current   'def '("Get the name of the chapter in progress right now - this is normally the last value sent to 'chapter-start")               nil                   nil '(nydp/documentation))
+(dox-add-doc 'chapter-delete    'def '("Remove the named chapter")                                                                                                 '(name)               nil '(nydp/documentation))
+(dox-add-doc 'chapter-find      'def '("Get the named chapter")                                                                                                    '(name)               nil '(nydp/documentation))
+(dox-add-doc 'set-intersection  'def '("return the intersection of the given lists")                                                                              'args                 nil '(list-manipulation))
+(dox-add-doc '⋂                'def '("return the intersection of the given lists")                                                                              'args                 nil '(list-manipulation))
+(dox-add-doc 'set-union         'def '("return the union of the given lists")                                                                                      'args                 nil '(list-manipulation))
+(dox-add-doc '⋃                'def '("return the union of the given lists")                                                                                      'args                 nil '(list-manipulation))
+(dox-add-doc 'dox-add-doc       'def '("Store the provided documentation item."
+                                       "'name is the name of the item"
+                                       "'what is the type of the item ('def or 'mac or 'thingy ... this is user-definable, not related to 'type-of)"
+                                       "'texts is a list of strings to store for this item"
+                                       "'args is the args if the item has the notion of args"
+                                       "'src the source code of the item if any"
+                                       "'chapters the chapters to which the item should be added, if any")                                          '(name what texts args src chapters) nil '(nydp/documentation))
+(dox-add-doc 'dox-add-examples  'def '("Add the given examples to the dox for the named item")                                                                    '(name example-exprs) nil '(nydp/documentation))
+(dox-add-doc 'dox-types         'def '("Get the list of types of documented items")                                                                                                 nil nil '(nydp/documentation))
+(dox-add-doc 'dox-lookup        'def '("Get the documentation for the given item")                                                                                              '(name) nil '(nydp/documentation))
+(dox-add-doc 'dox-items-by-type 'def '("Get the list of dox items of a given type")                                                                                            '(type) nil '(nydp/documentation))

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))))
 
+;; same as ( (fn (var) body) val ) -> ie create a lexical scope
+;; where val is assigned to var, execute 'body in that scope
 (mac let (var val . body)
-     `(with (,var ,val) ,@body))
+  `(with (,var ,val) ,@body))
 
 (mac rfn (name parms . body)
   ; creates a named, locally-scoped function
@@ -116,6 +130,17 @@ scoping, assignment, anonymous functions and more...")
        (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))
@@ -127,7 +152,7 @@ scoping, assignment, anonymous functions and more...")
   ; 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) (list n '(uniq ',n))) vars))
+      `(with ,(apply + (map (fn (n) `(,n (uniq ',n))) vars))
              ,@body)
       `(let ,vars (uniq ',vars) ,@body)))
 
@@ -194,29 +219,23 @@ 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))
+;; used internally by '= macro
+(def assign-expr (name value)
   (if (isa 'symbol name)
       `(assign ,name ,value)
       (caris 'dot-syntax name)
@@ -224,15 +243,35 @@ scoping, assignment, anonymous functions and more...")
       (caris 'hash-get name)
       (hash-get-assignment (cdr name) value)
       (ampersand-expression? name)
-      (ampersand-expression-assignment name value)))
-
-(mac def-assign args
-  ; override previous definition to allow expressions like (def hsh.foo (arg arg2) ...)
-  `(= ,@args))
-
-(mac or= (place val)
-  ; evaluate ,val and assign result to ,place only if ,place is already nil
-  `(or ,place (= ,place ,val)))
+      (ampersand-expression-assignment name value)
+      (caris 'at-syntax name)
+      `(hash-set @ ',(caddr 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 = (name value . more)
+  (if more
+      `(do ,(assign-expr name value) (= ,@more))
+      (assign-expr name value)))
+
+;; 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))))
+
+; override previous definition to allow expressions like (def hsh.foo (arg arg2) ...)
+(mac def-assign args `(= ,@args))
+
+; evaluate ,val and assign result to ,place only if ,place is already nil
+(mac or= (place val) `(or ,place (= ,place ,val)))
 
 (def brace-list-hash-key (k)
   (if (isa 'symbol k)      `(quote ,k)
@@ -259,43 +298,42 @@ scoping, assignment, anonymous functions and more...")
       (error "Irregular '& syntax: got suffix ~(inspect (cdr rest)) in ~(join-str pfx "&" rest)")
       (build-ampersand-syntax (car rest))))
 
-(mac brace-list-mono (arg)
-  ; override 'brace-list-mono in order to provide a useful interpretation for "{ x }" syntax
-  arg)
+; override 'brace-list-mono in order to provide a useful interpretation for "{ x }" syntax
+(mac brace-list-mono (arg) arg)
 
-(mac brace-list-empty ()
-  ; interprets "{ }" as new hash
-  '(hash))
+; interprets "{ }" as new hash
+(mac brace-list-empty () '(hash))
 
+; parser expands { foo bar } to (brace-list foo bar)
 (mac brace-list args
-  ; parser expands { foo bar } to (brace-list foo bar)
   (if (no args)
       `(brace-list-empty)
       (no (cdr args))
       `(brace-list-mono ,(car args))
       (brace-list-build-hash args)))
 
-(mac returnlet (var val . body)
-  ; stores ,val in ,var, executes ,@body, returns ,var. Saves a line of code at the end of
-  ; 'let. Assumes 'body is going to do something destructive with 'val, but you want 'val before
-  ; it gets changed. See also 'returning
-  `(let ,var ,val ,@body ,var))
+; stores ,val in ,var, executes ,@body, returns ,var. Saves a line of code at the end of
+; 'let. If 'body assigns to 'var, the assigned value of 'var will be returned. See also 'returning
+(mac returnlet (var val . body) `(let ,var ,val ,@body ,var))
 
-(mac returning (val . body)
-  ; stores ,val, executes ,@body, and returns ,val. Assumes 'body is going to do something
-  ; destructive with 'val, but you want 'val before it gets changed. See also 'returnlet
-  (w/uniq retval `(returnlet ,retval ,val ,@body)))
+; stores ,val, executes ,@body, and returns ,val. Assumes 'body is going to do something
+; destructive with 'val, but you want 'val before it gets changed. Note that if 'val is mutated
+; (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))
+
 (def destructure/with (var args n)
   ; provides the argument expression to 'with when
   ; destructuring arguments are present in a 'fun definition
@@ -318,16 +356,20 @@ scoping, assignment, anonymous functions and more...")
       `(fn ,(rev new-args given-args) ,@body)))
 
 
-(def fun/approve-arg-names (orig args)
+(def fun/approve-arg-names (orig args body)
   (if (pair? args)
-      (do (fun/approve-arg-names orig (car args))
-          (fun/approve-arg-names orig (cdr 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))))
+          (warnings/new 'arg-shadows-macro "arg " args " shadows macro " args " in arg list " orig " and body " body))))
 
+;; 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)
+  (fun/approve-arg-names args args body)
   (destructure/build args nil body))
+
+;; assign (f place) to place
+(mac zap (f place . args)
+  `(= ,place (,f ,place ,@args)))