Merge pull request #105 from skx/examples

Examples

README.md

@@ -62,7 +62,7 @@ Once installed there are three ways to execute code:
 * By specifying an expression to execute upon the command-line:
   * `yal -e '(print (os))'`
 * By passing the name of a file containing lisp code to read and execute:
-  * `yal test.lisp`
+  * `yal examples/test.lisp`
 * By launching the interpreter with zero arguments, which will start the interactive REPL mode.
   * If present the file `~/.yalrc` is loaded before the REPL starts.
   * Here is a sample [.yalrc](.yalrc) file which shows the kind of thing you might wish to do.
@@ -170,17 +170,19 @@ Here the regular expressions will be matched against the name of the file(s) in
 
 ## Examples
 
-A reasonable amount of sample code can be found in the various included files:
+A reasonable amount of sample code can be found beneath the [examples/](examples/) directory, including:
 
-* [fibonacci.list](fibonacci.lisp)
+* [examples/fibonacci.list](examples/fibonacci.lisp)
   * Calculate the first 25 numbers of the Fibonacci sequence.
-* [fizzbuzz.lisp](fizzbuzz.lisp)
+* [examples/fizzbuzz.lisp](examples/fizzbuzz.lisp)
   * A standalone sample of solving the fizzbuzz problem.
-* [mtest.lisp](mtest.lisp)
-  * Shows simple some macro examples, but see [lisp-tests.lisp](lisp-tests.lisp) for a more useful example.
-* [sorting.lisp](sorting.lisp)
+* [examples/mtest.lisp](examples/mtest.lisp)
+  * Shows simple some macro examples, but see [examples/lisp-tests.lisp](examples/lisp-tests.lisp) for a more useful example.
+    * This uses macros in an interesting way.
+    * It is also used to actually test the various Lisp-methods we've implemented.
+* [examples/sorting.lisp](examples/sorting.lisp)
   * Demonstrates writing & benchmarking sorting-routines.
-* [test.lisp](test.lisp)
+* [examples/test.lisp](examples/test.lisp)
   * A misc. collection of sample code, functions, and notes.
 
 As noted there is a standard-library of functions which are loaded along with any user-supplied script - that library of functions may also provide a useful reference and example of yal-code:
@@ -189,7 +191,7 @@ As noted there is a standard-library of functions which are loaded along with an
 
 The standard-library contains its own series of test-cases written in Lisp:
 
-* [lisp-tests.lisp](lisp-tests.lisp)
+* [examples/lisp-tests.lisp](examples/lisp-tests.lisp)
 
 The lisp-tests.lisp file contains a simple macro for defining test-cases, and uses that to good effect to test a range of our lisp-implemented primitives.
 

examples/Makefile

@@ -0,0 +1,5 @@
+#
+# Generate README.md, by running readme.lisp.
+#
+README.md: *.lisp
+	../yal readme.lisp > README.md

examples/README.md

@@ -0,0 +1,27 @@
+# Examples
+
+This directory contains some simple lisp examples, which can be executed via `yal`.
+
+
+* [dynamic.lisp](dynamic.lisp)
+  * Execute code by name, via introspection.
+* [fibonacci.lisp](fibonacci.lisp)
+  * Calculate the first 25 fibonacci numbers.
+* [fizzbuzz.lisp](fizzbuzz.lisp)
+  * Show the fizzbuzz up to 50.
+* [hash.lisp](hash.lisp)
+  * Demonstrate working with hashes.
+* [lisp-tests.lisp](lisp-tests.lisp)
+  * A simple lisp-based testing framework for our primitives.
+* [mtest.lisp](mtest.lisp)
+  * Simple tests of our macro system.
+* [readme.lisp](readme.lisp)
+  * Generate a README.md file, based on directory contents.
+* [sorting.lisp](sorting.lisp)
+  * Demonstrate generating random lists, and sorting them.
+* [test.lisp](test.lisp)
+  * Simple feature-tests/demonstrations of our system.
+* [time.lisp](time.lisp)
+  * Demonstrate our date/time functions.
+* [try.lisp](try.lisp)
+  * Demonstrate our error-handling, with try/catch.

fizzbuzz.lisp → examples/fizzbuzz.lisp

@@ -1,4 +1,4 @@
-;;; fizzbuzz2.lisp - A simple fizzbuzz implementation
+;;; fizzbuzz2.lisp - Show the fizzbuzz up to 50.
 
 ;; Taking advantage of our (cond) primitive we can just return the
 ;; string to print for any given number.

lisp-tests.lisp → examples/lisp-tests.lisp

@@ -1,4 +1,4 @@
-;;; tests.lisp - Some simple tests of our lisp-written primitives
+;;; tests.lisp - A simple lisp-based testing framework for our primitives.
 
 ;;; About
 ;;

examples/readme.lisp

@@ -0,0 +1,37 @@
+;;; readme.lisp - Generate a README.md file, based on directory contents.
+
+;;
+;; This directory contains *.lisp, echo of which has a header-line prefixed
+;; with three semi-colons:
+;;
+;;     ;;; foo.lisp - Information
+;;
+;; This script reads those files and outputs a simple index, of the filename
+;; and the information.
+;;
+
+(set! lisp:files (fn* ()
+                      "Return a list of all the lisp files in the current directory"
+                      (sort (glob "*.lisp"))))
+
+
+(set! lisp:info (fn* (file)
+                     "Output a brief overview of the given file"
+                     (let* (
+                            text (file:lines file)
+                            line  (nth text 0)
+                            info (match "^([^-]*)-+[ ]+(.*)$" line))
+                       (when (list? info)
+                         (print "* [%s](%s)" file file)
+                         (print "  * %s" (nth info 2))))))
+
+
+(set! lisp:index (fn* ()
+                      "Generate a README.md snippet"
+                      (let* (files (lisp:files))
+                        (apply files lisp:info()))))
+
+(print "# Examples\n")
+(print "This directory contains some simple lisp examples, which can be executed via `yal`.\n\n")
+
+(lisp:index)

time.lisp → examples/time.lisp

@@ -1,4 +1,4 @@
-;;; time.lisp - Demonstrate the date/time functions
+;;; time.lisp - Demonstrate our date/time functions.
 
 ;;
 ;; This is a sample input file for our minimal lisp interpreter.

try.lisp → examples/try.lisp

@@ -1,4 +1,4 @@
-;;; try.lisp - Demonstrate our try/catch behaviour
+;;; try.lisp - Demonstrate our error-handling, with try/catch.
 
 ;;
 ;; This file demonstrates our try/catch behaviour, which allows