home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / new / util / edit / jade / man / jade.info-6 (.txt) < prev    next >
GNU Info File  |  1994-10-16  |  49KB  |  973 lines
  1. This is Info file jade.info, produced by Makeinfo-1.55 from the input
  2. file jade.texi.
  3. START-INFO-DIR-ENTRY
  4. * Jade: (jade).            An editor for X11 and AmigaDOS
  5. END-INFO-DIR-ENTRY
  6.    This is Edition 1.3, last updated 7 October 1994, of `The Jade
  7. Manual', for Jade, Version 3.2.
  8.    Jade is a text editor for X11 (on Unix) and the Amiga.
  9.    Copyright 1993, 1994 John Harper.
  10.    Permission is granted to make and distribute verbatim copies of this
  11. manual provided the copyright notice and this permission notice are
  12. preserved on all copies.
  13.    Permission is granted to copy and distribute modified versions of
  14. this manual under the conditions for verbatim copying, provided that
  15. the entire resulting derived work is distributed under the terms of a
  16. permission notice identical to this one.
  17. File: jade.info,  Node: Macro Expansion,  Next: Compiling Macros,  Prev: Defining Macros,  Up: Macros
  18. Macro Expansion
  19. ---------------
  20.    When a macro call is detected (*note List Forms::.) the function
  21. which is the cdr of the macro's definition (*note Defining Macros::.)
  22. is applied to the macro call's arguments. Unlike in a function call,
  23. the arguments are *not evaluated*, the actual forms are the arguments
  24. to the macro's expansion function. This is so these forms can be
  25. rearranged by the macro's expansion function to create the new form
  26. which will be evaluated.
  27.    There is a function which performs macro expansion, its main use is
  28. to let the Lisp compiler expand macro calls at compile time.
  29.  - Function: macroexpand FORM &optional ENVIRONMENT
  30.      If FORM is a macro call `macroexpand' will expand that call by
  31.      calling the macro's expansion function (the cdr of the macro
  32.      definition).  If this expansion is another macro call the process
  33.      is repeated until an expansion is obtained which is not a macro
  34.      call, this form is then returned.
  35.      The optional ENVIRONMENT argument is an alist of macro definitions
  36.      to use as well as the existing macros; this is mainly used for
  37.      compiling purposes.
  38.           (defmacro when (condition &rest body)
  39.             "Evaluates CONDITION, if it's non-`nil' evaluates the BODY
  40.           forms."
  41.             (list 'if condition (cons 'progn body)))
  42.               => when
  43.           
  44.           (macroexpand '(when x (setq foo bar)))
  45.               => (if x (progn (setq foo bar)))
  46. File: jade.info,  Node: Compiling Macros,  Prev: Macro Expansion,  Up: Macros
  47. Compiling Macros
  48. ----------------
  49.    Although it may seem odd that macros return a form to produce a
  50. result and not simply the result this is their most important feature.
  51. It allows the expansion and the evaluation of the expansion to happen
  52. at different times.
  53.    The Lisp compiler makes use of this; when it comes across a macro
  54. call in a form it is compiling it uses the `macroexpand' function to
  55. produce the expansion of that form which it then compiles straight into
  56. the object code. Obviously this is good for performance (why evaluate
  57. the expansion every time it is needed when once will do?).
  58.    Some rules do need to be observed to make this work properly:
  59.    * When the compiler compiles a file it remembers the macros which
  60.      have been defined by that file; it can only expand a macro call if
  61.      the definition of the macro appears before the macro call itself
  62.      (it can't read your mind).
  63.    * The macro expansion function (i.e. the definition of the macro)
  64.      should not have any side effects or evaluate its arguments (the
  65.      value of a symbol at compile-time probably won't be the same as
  66.      its value at run-time).
  67.    * Macros which are defined by another file must be loaded so they
  68.      can be recognised. Use the `require' function, the compiler will
  69.      evaluate any top-level `require' forms it sees to bring in any
  70.      macro definitions used.
  71. File: jade.info,  Node: Streams,  Next: Loading,  Prev: Macros,  Up: Programming Jade
  72. Streams
  73. =======
  74.    A "stream" is a Lisp object which is either a data sink (an "output
  75. stream") or a data source (an "input stream"). In Jade all streams
  76. produce or consume sequences of 8-bit characters.
  77.    Streams are very flexible, functions using streams for their input
  78. and output do not need to know what type of stream it is. For example
  79. the Lisp reader (the `read' function) takes an input stream as its one
  80. argument, it then reads characters from this stream until it has parsed
  81. a whole object. This stream could be a file, a position in a buffer, a
  82. function or even a string; the `read' function can not tell the
  83. difference.
  84.  - Function: streamp OBJECT
  85.      This function returns `t' if its argument is a stream.
  86. * Menu:
  87. * Input Streams::               Types of input stream
  88. * Output Streams::              Types of output stream
  89. * Input Functions::             Functions to read from streams
  90. * Output Functions::            How to output to a stream
  91. File: jade.info,  Node: Input Streams,  Next: Output Streams,  Up: Streams
  92. Input Streams
  93. -------------
  94.    These are the possible types of input stream, for the functions which
  95. use them see *Note Input Functions::.
  96. `FILE'
  97.      Characters are read from the file object FILE, for the functions
  98.      which manipulate file objects see *Note Files::.
  99. `MARK'
  100.      The marker MARK points to the next character that will be read.
  101.      Each time a character is read the position that MARK points to will
  102.      be advanced to the following character. *Note Marks::.
  103. `BUFFER'
  104.      Reads from the position of the cursor in the buffer BUFFER. This
  105.      position is advanced as characters are read.
  106. `(BUFFER . POSITION)'
  107.      Characters are read from the position POSITION in the buffer
  108.      BUFFER.  POSITION is advanced to the next character as each
  109.      character is read.
  110. `FUNCTION'
  111.      Each time an input character is required the FUNCTION is called
  112.      with no arguments. It should return the character read (an
  113.      integer) or `nil' if for some reason no character is available.
  114.      FUNCTION should also be able to `unread' one character. When this
  115.      happens the function will be called with one argument -- the value
  116.      of the last character read. The function should arrange it so that
  117.      the next time it is called it returns this character. A possible
  118.      implementation could be,
  119.           (defvar ms-unread-char nil
  120.             "If non-nil the character which was pushed back.")
  121.           
  122.           (defun my-stream (&optional unread-char)
  123.             (if unread-char
  124.                 (setq ms-unread-char unread-char)
  125.               (if ms-unread-char
  126.                   (prog1
  127.                     ms-unread-char
  128.                     (setq ms-unread-char nil))
  129.                 ;; Normal case -- read and return a character from somewhere
  130.                 ...
  131. `nil'
  132.      Read from the stream stored in the variable `standard-input'.
  133.    It is also possible to use a string as an input stream. The string to
  134. be read from must be applied to the `make-string-input-stream' function
  135. and the result from this function used as the input stream.
  136.  - Function: make-string-input-stream STRING &optional START
  137.      Returns an input stream which will supply the characters of the
  138.      string STRING in order starting with the character at position
  139.      START (or from position zero if this argument is undefined).
  140.           (read (make-string-input-stream "(1 . 2)"))
  141.               => (1 . 2)
  142.  - Variable: standard-input
  143.      The input stream which is used when no other is specified or is
  144.      `nil'.
  145. File: jade.info,  Node: Output Streams,  Next: Input Functions,  Prev: Input Streams,  Up: Streams
  146. Output Streams
  147. --------------
  148.    These are the different types of output stream, for the functions
  149. which use them see *Note Output Functions::.
  150. `FILE'
  151.      Writes to the file object FILE. *Note Files::.
  152. `MARK'
  153.      Writes to the position pointed to by the marked MARK, then
  154.      advances the position of the mark.
  155. `BUFFER'
  156.      Writes to BUFFER at the position of the cursor in that buffer,
  157.      which is then advanced.
  158. `(BUFFER . POSITION)'
  159.      POSITION in the buffer BUFFER. POSITION is then moved over the
  160.      written text.
  161. `(BUFFER . t)'
  162.      Writes to the end of the buffer BUFFER.
  163. `FUNCTION'
  164.      The function FUNCTION is called with one argument, eithe