home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / languages / lisp / fools / doc / info_doc < prev    next >
Encoding:
Text File  |  1991-10-31  |  10.3 KB  |  250 lines
  1. This document describes features non-standard or peculiar to my
  2. implementation of scheme and assumes that you have loaded the
  3. following files into the interpreter:  init.scm, extra.scm, and
  4. macros.scm (the shell script fl performs part of this task).
  5.  
  6. notation:
  7.  
  8. Square brackets indicate an optional argument.  The ... notation
  9. means zero or more of the preceding argument/form.
  10.  
  11. special forms:
  12.  
  13. (extend-syntax (name key ...) (pattern [fender] expansion) ...)
  14.     Eugene Kohlbecker's extend-syntax.  Kent Dybvig wrote the
  15.     implementation.
  16. (unless test expr ...)
  17.     Evalutate the exprs only if test evaluates to #f.
  18. (when test expr ...)
  19.     Evalutate the exprs only if test does not evalutate to #f.
  20. (do ((var init [step]) ...) (test expr1 ...) expr2 ...)
  21.     Evaluate the expr2s in the scope of the variable vars until
  22.     test evaluates to true.  The vars take on the value of step
  23.     after each iteration (or stay the same if no step was specified).
  24.     The do form evaluates to the value of the last expr1.
  25. (case key ((datum ...) expr ...) ...)
  26.     Evalutate the exprs of the first datum found to be eqv? to key.
  27. (record-case val (key idspec expr ...) ...)
  28.     Evaluate the exprs of the key that matches the car of val.
  29.     The exprs are evaluated in the scope of the pattern variables
  30.     in idspec which are matched to the cdr of val.
  31.     See "The Scheme Programming Language", by Kent Dybvig.
  32. (while test expr ...)
  33.     Evaluate the exprs while test continues to evalutes to #t.
  34. (define-structure (name id1 ...) [((id2 val) ...)])
  35.     Define a structure type called name with user initializable
  36.     fields named after the id1s and automatically intialialized
  37.     fields id2s (to val).
  38.     define-structure defines the constructor (make-name id1 ...);
  39.     the predicate (name? obj); and for each id1 and id2 an accessor
  40.     and mutator: (name-field obj) and (set-name-field! obj val).
  41.     From "The Scheme Programming Language".
  42. (the-environment)
  43.     Evaluates to the current environment.
  44. (define-macro macro-name expander)
  45.     Associate the procedure expander with macro-name.  Before an
  46.     expression is evaluatued, the evaluator applies the expander
  47.     to the arguments of any form whose car is macro-name.  See
  48.     macros below.
  49.  
  50. procedures:
  51.  
  52. (ormap pred list ...)
  53.     Apply pred to the items in list returning the first non-false
  54.     result (or the last result if there were no previous true results).
  55.     Pred must accept as many arguments as lists provided.
  56. (andmap pred list ...)
  57.     Apply pred to the items in list returning the first false result
  58.     (or the last result if there were no previous false results).
  59.     Pred must accept as many arguments as lists provided.
  60. (trace proc)
  61.     Trace calls to proc.  Tail-recursive calls and exits are
  62.     not traceable, because the proc may only be called once.
  63. (untrace proc)
  64.     Stop tracing proc.
  65. (make-box obj)
  66.     Create a pointer to obj.  Literal boxes can be created by #&obj.
  67.     Boxes are from "The Scheme Programming Language".
  68. (set-box! box obj)
  69.     Change the value of pointer box to obj.
  70. (unbox box)
  71.     Dereference the pointer box.
  72. (string->uninterned-symbol string)
  73.     Create a symbol that is not eq? to any other symbol.  Useful
  74.     as identifiers in macros.
  75. (fprintf port format args ...)
  76. (printf format args ...)
  77.     Prints the format string.  The format string can contain embedded
  78.     format specifiers:
  79.         ~s - print arg using write
  80.         ~a - print arg using display
  81.         ~c - print character arg without #\ escape
  82.         ~% - print a newline
  83.         ~~ - print a tilde
  84.     From "The Scheme Programming Language".
  85. (pretty-print expr [port])
  86.     Pretty print expr to port or (current-output-port).
  87.     If expr is a procedure, then its lambda body is printed
  88.     instead (only if SAVE_LAMBDA_BODIES is defined in config.h).
  89.     The pretty printer is loaded by (require 'pp).
  90. (pp expr|macro-name)
  91.     Like pretty-print except if expr is a symbol, it is assumed
  92.     to be a macro name and the body of the macro expander is pretty
  93.     printed instead of the symbol.
  94. (in-package package-name)
  95.     Change the current package to package-name.
  96. (require package-name)
  97.     Load the package package-name if not already loaded.  The name
  98.     of the file to load is constructed by the package-name
  99.     followed by the value of the variable *package-ext*, by default
  100.     ".scm".  The loader looks in the directories in the list
  101.     *package-path*, by default ("./" "~/scm/" "/usr/local/lib/fools/"),
  102.     for the file.
  103. (provide package-name)
  104.     Changes the variable *packages* to reflect that the package has
  105.     been loaded (checked by require).
  106. (package-environment package-name)
  107.     Gets the environment of the package called package-name.
  108. (file-access file-name access-mode)
  109.     Returns #t if file-name can be accessed according to access-mode
  110.     which is a string of access characters:  r - read; w - write;
  111.     x - execute; or f - existence.
  112.     See the UNIX man page for access(2).
  113. (file-open file-name rw-mode)
  114.     Open file with mode rw-mode and return the corresponding file object.
  115.     rw-mode is as specified in the UNIX man page for fopen(3).
  116. (file-close file)
  117.     Close the file object.
  118. (file-tell file)
  119.     Returns the current offset position within the file.
  120. (file-seek file offset offset-type)
  121.     Changes the current offset position within the file to offset
  122.     bytes from the beginning, current posiition, or end of the file
  123.     depending on whether offset-type is #\b, #\c, or #\e respectively.
  124. (eval expr environment)
  125.     Evaluate expr in environment.
  126. (code-body proc)
  127.     Returns the lambda expression for proc.  Note that this is only
  128.     true if the compile option SAVE_LAMBDA_BODIES was defined
  129.     in config.h.
  130. (macro macro-name)
  131.     Get the expander associatiated with macro-name.
  132. (abort)    Abort the current evaluation.
  133. (exit)    Exit from the interpreter.
  134.  
  135. notes:
  136.  
  137. Square brackets can be used instead of parentheses for list syntax.
  138. Curly braces can be used instead of #( and ) for vector syntax.
  139. Evaluating the empty combination, (), does not produce an error.
  140. Vector #(...) and box #&... literals evaluate to themselves.
  141. #f is the empty list (see config.h about how to make #f unique).
  142. Altering constants with mutation operators does not produce an error.
  143. if returns #f if no else clause was specified.
  144. apply is not available as a procedure but allows tail recursion.
  145. String manipulation routines (except string-set!) work on symbols.
  146. Only double precision floating point and long integers are supported.
  147. Most of the number syntax and exactness is not implemented.
  148.  
  149. packages:
  150.  
  151. Fools' lisp packages are similar to packages in Common Lisp.  A
  152. definition in a package is accessed by preceding the identifier of
  153. the definition with the name of the package.  (foo:bar 1 2) calls the
  154. function bar defined in package foo with the arguments 1 and 2.
  155.  
  156. Packages are loaded by the require procedure.  For example, (require 'pp)
  157. loads the pretty printer.
  158.  
  159. Internally, packages are represented by environments.  The environment
  160. for a package is obtained by the package-environment procedure.  The
  161. scope of the package is similar to the scope of a lambda defined in
  162. the global environment:  bindings made inside the package environment
  163. are not visible in the global environment although the bindings of the
  164. global environment are visible in the package.
  165.  
  166. Semantically, package-name:identifier is equivalent to
  167.     (eval 'identifier (package-environment 'package-name)).
  168.  
  169. The evaluator has a notion of the current package.  Expressions are
  170. evaluated in the environment of the current package.  Initially, the
  171. current package is the package named top-level.  Its environment is
  172. the global environment.
  173.  
  174. The in-package procedure changes the current package.  The load
  175. procedure saves and restores the current package around the load,
  176. so you can call load without worrying about whether the current
  177. package changes.  A file can insure that it is loaded into a
  178. particular package by including as the first expression
  179.     (in-package 'package-name).
  180. The provide procedure notes that a particular package has been loaded,
  181. so that subsequent require's will not cause the package to be reloaded.
  182. Often, a provide is the second expression, after an in-package, in a
  183. file.
  184.  
  185. The Common LISP functions export and use-package are not implemented.
  186. As a result, no definition within a package can be hidden (so CL's
  187. package-name::identifier is unnecessary).  There exists a kludge to
  188. export definitions.  Identifiers in define and set! statements can
  189. include a package qualifier to determine where the binding is created.
  190. For example:
  191.     (define top-level:foo (lambda (x) x))
  192. binds foo in the top-level package, although the lambda is defined
  193. within the current package.  Since all packages can access the
  194. environment of the top-level, foo is still available to the current
  195. package.  Chosing a package other than the top-level is not too useful.
  196.  
  197. macros:
  198.  
  199. Define-macro associates a symbol with a procedure that constructs the
  200. expansion.  Before an expression of the form (symbol expr ...) is
  201. evaluated, it is macro expanded if an expander is associated with the
  202. symbol.  The expander is applied to the arguments of the expression.
  203. The result becomes the new expression.  Short circuiting occurs if the
  204. expander returns an expression that is the same form (i.e., the macro
  205. would be applied to the form again).
  206.  
  207. The (define (func arg) body) syntax is layered over the define special
  208. form as a macro:
  209.  
  210. (define-macro define
  211.   (lambda (sym . body)
  212.     (if (pair? sym)
  213.     `(define ,(car sym) (lambda ,(cdr sym) ,@body))
  214.     `(define ,sym ,@body))))
  215.  
  216. A macro for + can combine constants:
  217.  
  218. (define-macro +
  219.   (lambda args
  220.     (let ([constants (filter number? args)]
  221.       [exprs (filter (lambda (x) (not (number? x))) args)])
  222.       (cond [(null? constants)
  223.          `(+ ,@exprs)]
  224.         [(null? exprs)
  225.          (reduce + constants 0)]
  226.         [else
  227.          `(+ ,@exprs ,(reduce + constants 0))]))))
  228.  
  229. Note that macros are currently expanded top down, so sub-expressions
  230. that evaluate to constants will not be spotted by this macro, e.g.,
  231. (macro-expand '(+ (+ 2 4) 3)) yields (+ 6 3).
  232.  
  233. Because macros are expanded before evaluation, they must be defined
  234. before they appear in the program.  Redefining a macro has no effect
  235. on previously defined forms.  Macros are also globally visible.
  236.  
  237. The procedure macro-expand returns its argument expanded.  This is
  238. useful for debugging macros.  Currently, forms, such as lambda, are
  239. not fully expanded.  A second step before evaluation, preprocesses
  240. (and macro expands) all lambda forms.
  241.  
  242. suggested reading:
  243.  
  244. The Structure and Interpretation of Computer Programs
  245.     H. Ableson, G.J. Sussman    
  246. The Scheme Programming Language
  247.     R. Kent Dybvig
  248. Revised^3 Report on the Algorithmic Language Scheme
  249.     J. Rees, W. Clinger, et al.
  250.