nydp 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 858b22d67ba13ec86efe8a00fd10b5fa813aee8c
-  data.tar.gz: 24876cc3c6e1389f656640d3548574d7241b3725
+SHA256:
+  metadata.gz: '0389044de6d7b6230da9315bc8dde967e1ddf8ed77df2b8ef4106ce9bfc3e93a'
+  data.tar.gz: 133567982e2fbb734ea429e98197e4b7d5bc49c2130f64ec630c095adcd1f250
 SHA512:
-  metadata.gz: 2c0094a86976f2272a70b9c5ea8b76e36face05f089ad9c7a0d51c3de251081230ce85d37e11f9ccaf23cd3d0433a655464d9193dfba37f1e1526fd929e03a13
-  data.tar.gz: 9eb38db6a571768e8da0bdddbd6420e7627f492748aa64aac0e8e48e08c9af416da84c5be0b8e3828559d1988de250f9f72eaa3d25166f5001c7a1896a9d8203
+  metadata.gz: 2516bbc0473796915710786bb8b43ac339df657438e5a35d8f8d38cb5a7b46c1663b09a8cea266369b168530b63a1f249daf882d2712cd8558febb167bc648ef
+  data.tar.gz: 2548a1e1259f053ff25bc490d13f44579720be5f0ea7954915917092a04d0619f0b014221f55ed6b1f86f5046f5a6a7244348ff4805a2282ece150c3993be71f

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

@@ -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 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        )
@@ -78,26 +84,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)
@@ -108,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) 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))
@@ -125,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))
@@ -146,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
@@ -186,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,37 +59,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 'set-intersection '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 '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