nydp 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 63983bd000bf898d3987e7878f25a16e0be94924
-  data.tar.gz: ec47cf4bf570c09a63d17a53008fe92671460cbc
+  metadata.gz: f4074a517649b09d3911d3b593e19ff0f0bc6d66
+  data.tar.gz: cf2d6625885b45055f2e09601dc5914da308d5e2
 SHA512:
-  metadata.gz: 02e72f25772989690a4ba44cee9e5f054528d0d2202779674fd232fab1806bf24d2840bd0e6e1ce289875b6aac739cfdd94e7e4da86513d1020cecce1cc7ac62
-  data.tar.gz: 680159117248665c00a5166bf6d9e1a58247170d28d532215529f35f7a562add5464db10ee1bcbc617a38ee7eb3402777c484f27b388834c9da0aef68189947c
+  metadata.gz: 722eb57b1b40efaed06e432f3d70e00e18cda57ccef51b404f755b4b35dab3456a68a3542bb2185e68a22c5c1b2463c0320b5a223fa6901c1240ad542c07a0f3
+  data.tar.gz: 4d5a6a702eb006751548d594515022f1c2e2f8b2697d45b95973db83abb2ad2d53d29d6495fbde9281f21c9ae98bf02e87b5b6c19e6ae9c053ad9152804f41d8

data/README.md

@@ -1,16 +1,18 @@
-# NYDP
+# `'nydp`
 
-NYDP is a new LISP dialect, much inspired by [Arc](http://arclanguage.org/), and implemented in Ruby.
+`'nydp` is a new LISP dialect, much inspired by [Arc](http://arclanguage.org/), and hence indirectly by all of `'arc`'s ancestors,
+and implemented in Ruby.
 
-NYDP is "Not Your Daddy's Parentheses", a reference to [Xkcd 297](http://xkcd.com/297/) (itself a reference
-to Star Wars), as well as to the meme [Not Your Daddy's Q](http://tvtropes.org/pmwiki/pmwiki.php/Main/NotYourDaddysX), where Q is a modern,
-improved Q unlike the Q your daddy used. "NYDP" also shamelessly piggypacks on the
+`'nydp` is "Not Your Daddy's Parentheses", a reference to [Xkcd 297](http://xkcd.com/297/) (itself a reference
+to Star Wars), as well as to the meme [Not Your Daddy's Q](http://tvtropes.org/pmwiki/pmwiki.php/Main/NotYourDaddysX), where Q is a
+modern, improved Q quite unlike the Q your daddy used. `'nydp` also shamelessly piggypacks on the
 catchiness and popularity of the [NYPD](https://en.wikipedia.org/wiki/NYPD_Blue) abbreviation ("New York Police Department",
 for those who have no interest in popular US politics or TV).
 
-We do not wish to suggest by "Not Your Daddy's Parentheses" that Common Lisp, Scheme, Racket, Arc, Clojure or your favourite other lisp are somehow old-fashioned, inferior, or in need of improvement in any way.
+We do not wish to suggest by "Not Your Daddy's Parentheses" that Common Lisp, Scheme, Racket, Arc, Clojure or your favourite
+other lisp are somehow old-fashioned, inferior, or in need of improvement in any way.
 
-The goal of NYDP is to allow untrusted users run sandboxed server-side scripts. By default, NYDP provides no system access :
+The goal of `'nydp` is to allow untrusted users run sandboxed server-side scripts. By default, `'nydp` provides no system access :
 
 * no file functions
 * no network functions
@@ -19,7 +21,10 @@ The goal of NYDP is to allow untrusted users run sandboxed server-side scripts.
 * no threading functions
 * no ruby calls
 
-[Peruse NYDP's features here](lib/lisp/tests) in the `tests` directory.
+[Peruse `'nydp`'s features here](lib/lisp/tests) in the `tests` directory.
+
+Pronunciation guide: there is no fixed canonical pronunciation of `'nydp`. Just keep in mind that if you find yourself
+wading _knee-deep_ through raw sewage, it's still better than working on a java project in a bank.
 
 ## Running
 
@@ -41,7 +46,7 @@ Suppose you want to invoke the function named `question` with some arguments. Do
 ```ruby
 ns     = Nydp.build_nydp     # keep this for later re-use, it's expensive to set up
 
-answer = Nydp.apply_function ns, :question, :life, ("The Universe" and everything())
+answer = Nydp.apply_function ns, :question, :life, ["The Universe" and(everything)]
 
 ==> 42
 ```
@@ -55,7 +60,7 @@ You can maintain multiple `ns` instances without mutual interference. In other w
 
 #### 1. Macro-expansion runs in lisp
 
-After parsing its input, NYDP passes the result as an argument to the `pre-compile` function. This is where things get a little bit circular: initially, `pre-compile` is a builtin function that just returns its argument. `pre-compile` bootstraps itself into existence in [boot.nydp](lib/lisp/boot.nydp).
+After parsing its input, `'nydp` passes the result as an argument to the `pre-compile` function. This is where things get a little bit circular: initially, `pre-compile` is a builtin function that just returns its argument. `pre-compile` bootstraps itself into existence in [boot.nydp](lib/lisp/boot.nydp).
 
 You can override `pre-compile` to transform the expression in any way you wish. By default, the `boot.nydp` implementation of `pre-compile` performs macro-expansion.
 
@@ -185,7 +190,7 @@ nydp > (parse "\"foo\"")
 
 nydp > (let bar "Mister Nice Guy" "hello, ~bar")
 
-==> hello, Mister Nice Guy
+==> "hello, Mister Nice Guy"
 
 ; this is a more tricky example because we need to make a string with an interpolation token in it
 
@@ -193,6 +198,8 @@ nydp > (let s (joinstr "" "\"hello, " '~ "world\"") (parse s))
 
 ==> (string-pieces "hello, " world "") ; "hello, ", followed by the interpolation 'world, followed by the empty string after 'world
 
+; It is possible to nest interpolations. Note that as with many popular language features, just because you can do something, does not mean you should:
+
 nydp > (def also (str) "\nAND ALSO, ~str")
 nydp > (with (a 1 b 2)
          (p "Consider ~a : the first thing,
@@ -204,13 +211,17 @@ nydp > (with (a 1 b 2)
 ==> AND ALSO, Consider 3, the third (and final) thing
 ```
 
-By default, `string-pieces` is a function that just concatenates the string value of its arguments. You can redefine it as a macro to perform more fun stuff, or you can detect it within another macro to do extra-special stuff with it. The 'nydp-html gem detects 'string-pieces and gives it special treatment in order to render haml and textile efficiently, and also to capture and report errors inside interpolations and report them correctly.
+By default, `string-pieces` is a function that just concatenates the string value of its arguments. You can redefine it as a macro to
+perform more fun stuff, or you can detect it within another macro to do extra-special stuff with it. The 'nydp-html gem detects
+'string-pieces and gives it special treatment in order to render haml and textile efficiently, and also to capture and report errors
+inside interpolations and report them correctly.
 
 
 #### 5. No continuations.
 
 Sorry. While technically possible ... why bother?
 
+
 #### 6. No argument destructuring
 
 However, this doesn't need to be built-in, it can be done with macros alone. On the other hand, "rest" arguments are implicitly available using the same syntax as Arc uses:
@@ -277,7 +288,8 @@ nydp > (parse "; blah blah")
 ==> (comment "blah blah")
 ```
 
-Except in 'mac and 'def forms, by default, `comment` is a macro that expands to nil. If you have a better idea, go for it.
+Except in 'mac and 'def forms, by default, `comment` is a macro that expands to nil. If you have a better idea, go for it. Any comments present at the
+beginning of the `body` argument to `mac` or `def` are considered documentation. (See "self-documenting" below).
 
 #### 8 Prefix lists
 

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

@@ -1,10 +1,16 @@
-((fn (dox)
+((fn (dox examples)
      (def dox-add-doc (name what texts args src)
        (hash-set dox
                  name
                  (cons (list name what texts args src)
                        (hash-get dox sym))))
 
+     (def dox-add-examples (name example-exprs)
+       (hash-set examples
+                 name
+                 (cons example-exprs
+                       (hash-get examples sym))))
+
      (def dox-lookup (sym) (hash-get dox sym))
 
      (def dox? (sym) (hash-key? dox sym))
@@ -19,10 +25,13 @@
        (cond (dox? name)
              (car (cddr (cddr (car (dox-lookup name)))))))
 
+     (def dox-examples (name)
+       (hash-get examples name))
+
      (def dox-arg-names (name)
        (cond (dox? name)
              (cadddr (car (dox-lookup name))))))
- (hash))
+ (hash) (hash))
 
 (def isa-comment? (thing)
   (cond (pair? thing)

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

@@ -1,4 +1,7 @@
 (def orf args
+  ; evaluates each arg in 'args, returns the
+  ; first non-nil value, or nil if they are
+  ; all nil
   (cond args
         (cond (car args)
               (car args)
@@ -6,6 +9,7 @@
                      (cdr args)))))
 
 (mac unless (arg . body)
+  ; evaluate 'body if 'arg is nil
   `(if (no ,arg) (do ,@body)))
 
 (def expand-colon-syntax (names)
@@ -27,11 +31,23 @@
   (error "Irregular ': syntax: got ~(inspect names) : not prefix-syntax : in ~(joinstr ":" names)"))
 
 (mac colon-syntax names
+  ; handle syntax of the form a:b, which the parser expands to
+  ; (colon-syntax a b). By default, this complains if colon is used
+  ; as a prefix (ie it disallows ":foo"), otherwise creates a new
+  ; function which is the composition of the functions named in its
+  ; arguments. For example,
+  ; (count:parts spaceship) is the same as (count (parts spaceship))
   ((orf (hash-get colon-syntax-overrides (car names))
         default-colon-syntax)
    names))
 
 (mac bang-syntax (pfx . rest)
+  ; handle syntax of the form !x, which the parser expands to
+  ; (bang-syntax || x). By default, this complains if there is
+  ; a non-empty prefix (ie it disallows x!y), otherwise it creates
+  ; a new function which is the negation of the given named function.
+  ; For example,
+  ; (!eq? a 10) is the same as (no:eq? a 10), which is the same as (no (eq? a 10))
   (if (no (eq? pfx '||))
       (error "Irregular '! syntax: got prefix ~(inspect pfx) in ~(joinstr "!" (cons pfx rest))"))
   (if (cdr rest)
@@ -64,6 +80,30 @@
 (mac let (var val . body)
      `(with (,var ,val) ,@body))
 
+(mac rfn (name parms . body)
+  ; creates a named, locally-scoped function
+  ; with the given parameter names. It is possible
+  ; to reference the function by its name from within
+  ; the function (to pass as an argument or for
+  ; recursive invocation)
+  `(let ,name nil
+     (assign ,name (fn ,parms ,@body))))
+
+(mac afn (parms . body)
+  ; same as 'rfn, but using the name 'self
+  `(rfn self ,parms ,@body))
+
+(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 (fn ,(map car ppairs) ,@body))
+       (,name ,@(map cadr ppairs)))))
+
 (let uniq-counter 0
      (def uniq (prefix)
           (sym (joinstr "-"
@@ -74,16 +114,20 @@
           (assign uniq-counter 0)))
 
 (mac w/uniq (vars . body)
-     (if (pair? vars)
-         `(with ,(apply + (map (fn (n) (list n '(uniq ',n))) vars))
-                ,@body)
-       `(let ,vars (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) (list n '(uniq ',n))) vars))
+             ,@body)
+      `(let ,vars (uniq ',vars) ,@body)))
 
 (mac or args
-     (cond args
-           (w/uniq ora
-                   `(let ,ora ,(car args)
-                         (cond ,ora ,ora (or ,@(cdr args)))))))
+  ; lazy-evaluates each argument, returns the first
+  ; non-nil result, or nil if all evaluate to nil.
+  (cond args
+        (w/uniq ora
+                `(let ,ora ,(car args)
+                   (cond ,ora ,ora (or ,@(cdr args)))))))
 
 (mac pop (xs)
      (w/uniq gp

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

@@ -14,12 +14,10 @@
 
 (def flatten (things)
      (let acc nil
-          (let flattenize nil
-               (assign flattenize (fn (x)
-                                      (if (pair? x)
-                                          (eachr flattenize x)
-                                        (push x acc))))
-               (flattenize things))
+          (rfnwith flattenize (x things)
+                   (if (pair? x)
+                       (eachr flattenize x)
+                       (push x acc)))
           acc))
 
 (def string-strip (txt)
@@ -40,6 +38,9 @@
   (joinstr "" pieces))
 
 (def detect (f things)
+  ; if 'things is a list, return the first item in the list for which 'f returns non-nil
+  ; otherwise, return 'things if (f things) is non-nil
+  ; otherwise, nil
   (if (pair? things)
       (let it (car things)
         (or
@@ -48,10 +49,26 @@
       (f things)
       things))
 
+(def collect (f things)
+  ; if 'things is a list, return all the items in the list for which 'f returns non-nil
+  ; otherwise, return 'things if (f things) is non-nil
+  ; otherwise, nil
+  (rfnwith collector (items things)
+           (if (no items)
+               nil
+               (pair? items)
+               (if (f (car items))
+                   (cons (car items)
+                         (collector (cdr items)))
+                   (collector (cdr items)))
+               (f items)
+               items)))
+
 (def nth (n things)
-     (if (eq? n 0)
-         (car things)
-       (nth (- n 1) (cdr things))))
+  ; returns the n-th item in the list 'things
+  (if (eq? n 0)
+      (car things)
+      (nth (- n 1) (cdr things))))
 
 (def iso (x y)
      (or (eq? x y)
@@ -68,8 +85,10 @@
 (def quotify (arg)      `(quote ,arg))
 
 (def caris (obj things)
-     (and (isa 'pair things)
-          (eq? (car things)  obj)))
+  ; returns true if 'things is a list and the first item of the
+  ; list is the given object
+  (and (isa 'pair things)
+       (eq? (car things)  obj)))
 
 (def len (xs)
   (if (pair? xs)   (+ 1 (len (cdr xs)))
@@ -79,6 +98,7 @@
 (assign dynamics (hash))
 
 (mac dynamic (name)
+  ; creates a dynamic variable.
   (hash-set dynamics name t)
   (let with-mac-name (sym "w/~name")
     (w/uniq prev
@@ -93,20 +113,17 @@
            (def ,name () (hash-get (thread-locals) ',name))))))
 
 (mac on-err (handler . body)
+  ; executes 'body. If an error is raised, executes 'handler. Inside
+  ; 'handler, the parameter 'err refers to the error that was raised.
   `(handle-error (fn (err) ,handler)
                  (fn ()    ,@body)))
 
 (mac ensure (protection . body)
+  ; executes 'body. Afterwards, executes 'protection.
+  ; 'protection is always executed even if there is an error.
   `(ensuring (fn () ,protection)
              (fn ()    ,@body)))
 
-(mac rfn (name parms . body)
-  `(let ,name nil
-     (assign ,name (fn ,parms ,@body))))
-
-(mac afn (parms . body)
-  `(rfn self ,parms ,@body))
-
 (mac loop (start test update . body)
   (w/uniq (gfn gparm)
     `(do ,start
@@ -143,35 +160,6 @@
             acc))
    (car things) (cdr things)))
 
-(def dox-show-src (src)
-  ; show 'src as source code.
-  ; expect to override this later when pretty-printing is available
-  (inspect src))
-
-(def dox-show-info (name what texts args src)
-  ; show the given dox info
-  ; 'info arg is a dox object from the dox system
-  "~(if (eq? what 'mac) "Macro"
-        (eq? what 'def) "Function"
-        what) : ~name
-
-args : ~(inspect args)
-
-~(joinstr "\n" texts)
-
-source
-======
-~(dox-show-src src)
-")
-
-(mac dox (name)
-  ; show dox for the given name
-  `(let infos (dox-lookup ',name)
-     (if (no infos)
-         (p "No documentation for" ',name)
-         (each info infos
-               (p:apply dox-show-info info)))))
-
 (def proper? (list)
   ; t if this is a proper list (last cdr is nil)
   ; nil otherwise (last cdr is neither cons nor nil)

data/lib/lisp/core-045-dox-utils.nydp

@@ -0,0 +1,85 @@
+(def dox-show-src (src)
+  ; show 'src as source code.
+  ; expect to override this later when pretty-printing is available
+  (inspect src))
+
+(def dox-show-info (name what texts args src)
+  ; show the given dox info
+  ; 'info arg is a dox object from the dox system
+  "~(if (eq? what 'mac) "Macro"
+        (eq? what 'def) "Function"
+        what) : ~name
+
+args : ~(inspect args)
+
+~(joinstr "\n" texts)
+
+source
+======
+~(dox-show-src src)
+")
+
+(def dox-show-one-example (name example)
+  "~|name| ~(car example)
+
+running  :
+~(dox-show-src:cadr example)
+
+produces : ~(dox-show-src:caddr example)
+
+--------------------------------
+")
+
+(def dox-show-examples (name examples)
+  (if examples
+  "
+Examples for ~name
+==================
+
+~(joinstr "\n\n" (map (curry dox-show-one-example name) examples))
+
+"))
+
+(def dox-all-items ()
+  ; return all documentation items in a single list
+  (apply joinlists (map dox-lookup (dox-names))))
+
+(def dox-with-documentation (dox-item)
+  ; a documentation filter that returns non-nil for items with text documentation
+  ; use with 'dox-all-items to gather dox items that are explicitly documented
+  ; for example (cleverly-show (collect dox-with-documentation (dox-all-items)))
+  (nth 2 dox-item))
+
+(mac dox (name)
+  ; show dox for the given name, or all available dox if name is not given
+  (if name
+      `(let infos (dox-lookup ',name)
+         (if (no infos)
+             (p "No documentation for" ',name)
+             (each info infos
+                   (p:apply dox-show-info info)))
+         (let examples (dox-examples ',name)
+           (if (no examples)
+               (p "No examples for" ',name)
+               (p (joinstr "\n" (map (curry dox-show-examples ',name) examples)))))
+         nil)
+      `(let infos (collect dox-with-documentation (dox-all-items))
+         (p "documentation available for the following:")
+         (each info infos
+               (p:inspect:firstn 2 info)))))
+
+(def-colon-syntax dox names
+  (let target (cadr names)
+    `(dox ,(if (eq? target '||)
+               nil
+               target))))
+
+(def explain-mac (n expr)
+  (if (eq? n 0)
+      expr
+      (let macfn (hash-get macs (car expr))
+        (if macfn
+            (explain-mac (- n 1)
+                        (apply macfn
+                               (cdr expr)))
+            expr))))