home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / me34src.zip / me3 / doc / me3mutt.doc < prev    next >
Text File  |  1995-01-14  |  88KB  |  1,802 lines
  1. !!!Concepts chapter:
  2.   talk about garbage collection:  what when
  3.   talk general about bags, marks, buffers
  4.   talk about current buffer, current window ain't the same
  5. ========================================================================
  6. == The ME Mutt Connection     Craig Durland  9/89 10/91 11/91 6/93 ==
  7. ========================================================================
  8.  
  9.   This document describes the link between the Mutt2 programming
  10. language (see mutt2.doc) and the Mutt Editor (see me3.doc).
  11.  
  12.  
  13.              Copyright 1991 Craig Durland
  14.     Distributed under the terms of the GNU General Public License.
  15.   Distributed "as is", without warranties of any kind, but comments,
  16.            suggestions and bug reports are welcome.
  17.  
  18. ========================================================================
  19. ==        The ME3 Mutt functions                      ==
  20. ========================================================================
  21. (any-modified-buffers) basic.mut            [zip : BOOLEAN]
  22.   Returns TRUE if one or more buffers exist with the Modified bit set
  23.   and the NoCare bit reset.
  24. (append-to-bag bag-id TEXT      <text>)
  25. (append-to-bag bag-id CHARACTERS  <number>)
  26. (append-to-bag bag-id REGION      [mark1 mark2])
  27. (append-to-bag bag-id RECTANGLE   [mark1 mark2])
  28.       where TEXT = 0, CHARACTERS = 1, REGION = 2 and RECTANGLE = 3.
  29.  
  30.     TEXT       :    [NUMBER 0 STRING         : VOID]
  31.     CHARACTERS :    [NUMBER 1 NUMBER        : VOID]
  32.     REGION       :    [NUMBER 2 [NUMBER [NUMBER]] : VOID]
  33.     RECTANGLE  :    [NUMBER 3 [NUMBER [NUMBER]] : VOID]
  34.  
  35.   These functions append text to a bag.  
  36.     TEXT : Appends a string to the bag.
  37.     REGION : Appends the text contained in a region.
  38.     CHARACTERS : Appends n characters, starting from the dot.
  39.     RECTANGLE :    Copies the region-rectangle.  This clears the bag first.
  40.       Note that appending anything to a bag with a rectangle in it
  41.       (unless it is another rectangle) is a no-op until you clear the
  42.       bag.
  43.  
  44.   For example:
  45.     If the region contains "This is a test" then
  46.       (clear-bag 0)
  47.       (append-to-bag 0 REGION) (append-to-bag 0 TEXT " foo bar")
  48.     will set the cut buffer to "This is a test foo bar".
  49.   See also:  create-bag, clear-bag, insert-register, bag-stats,
  50.     bag-to-string, prepend-to-bag, constants in me.mh.
  51. (arg-flag [flag [prefix]]))            [[BOOLEAN [NUMBER]] : BOOLEAN]
  52.   (arg-flag)
  53.     Check to see if somebody set the arg-prefix before calling this
  54.       routine (via (universal-argument) or (arg-prefix n)).
  55.   (arg-flag flag)
  56.     Set arg-flag to flag.  Does not affect arg-prefix.
  57.   (arg-flag flag number)
  58.     Set arg-flag to flag and arg-prefix to number.
  59.   Returns:
  60.     Current setting of arg-flag.
  61.   Notes:
  62.     Arg-flag holds it value until is it is changed by arg-prefix,
  63.       arg-flag, exe-key or the main loop.  Thus, it can be important to
  64.       reset them in your program if you will be calling another program
  65.       that uses them for input (in general, user level programs (eg the
  66.       ones bound to keys).  It is a good idea to make a copy of the
  67.       value upon entry to a program if it is possible that a called
  68.       program might change it.
  69.     Reset by exe-key and the main loop (when all programs are finished
  70.       running) to (FALSE 1).
  71.   See also: arg-prefix, exe-key.
  72. (arg-prefix [arg])                       [[NUMBER] : NUMBER]
  73.   (arg-prefix)
  74.     Return the current value of arg-prefix.
  75.   (arg-prefix number)
  76.     Set the universal-argument and return it.
  77.   Notes:
  78.     The arg-flag is set to TRUE.
  79.   See also: (arg-flag)
  80. (argc)                                [zip : NUMBER]
  81.   The number of parameters on the command line when ME was invoked +1.
  82.   eg "ME foo bar" has argc == 3.
  83.   Use argv to look at the parameters.
  84. (argv)                             [NUMBER : STRING]
  85.   The ME command line parameters.  There are argc of them, numbering
  86.     0...argc-1.  (argv 0) is the name of the program (ME) (unless you are
  87.     running on MS-DOS 2.x where it is ""), (argv 1) is the first word on
  88.     the command line, (argv 2) is the next word, etc.
  89.   Notes:
  90.     Normally, the command line is processed by process-command-line (in
  91.       cmdline.mut).  If you want to add command line args, do it though
  92.       command-line-hook.
  93. (attached-buffer window-id | buffer-name)      [NUMBER|STRING : NUMBER]
  94.   If given a number, attached-buffer returns the buffer id that is
  95.     attached to window n.  n == -1 means use the current window.
  96.   If given a name, attached-buffer returns the id of the buffer that is
  97.     named name.  Returns -2 if the buffer does not exist.
  98.   For example:
  99.     if the cursor is in third window (window #2) which is displaying
  100.       buffer "foobar" and foobar has an id of 123 then:
  101.     (attached-buffer -1) and (attached-buffer 2) both return 123.
  102.     (attached-buffer "foobar") returns 123.
  103.     (attached-buffer "FOOBAR") returns -2.
  104.   See also: buffers, windows.
  105. (attached-file full-file-name)  basic.mut        [STRING : NUMBER]
  106.   Returns the buffer id of the buffer that is attached to file.  If the
  107.     file is not attached to any buffer, -2 is returned.
  108. (autoload function-name file-name) autoload.mut     [STRING STRING : something]
  109.   When function is called for the first time, file is loaded and
  110.     function is called again.
  111.   See autoload.mut for much better documentation.
  112. (bag-stats bag-id pointer-to-data)             [NUMBER BLOB : VOID] 
  113.   Get stats on a bag.  pointer-to-data is a pointer the the data area
  114.     that the stats are put into:
  115.   (byte type) (small-int width height) (int size)    ;; struct BagInfo
  116.     type: 0 means text and 1 is rectangle.
  117.     width, height:  If the register is a rectangle.
  118.     size: Number of bytes in the register.
  119.   For example:
  120.     (defun get-bag-stats
  121.     {
  122.       (byte type)(small-int width height)(int size)    ;; struct BagInfo
  123.       (int n)
  124.  
  125.       (n (convert-to 3 (ask "bag id: ")))
  126.       (bag-stats n (loc type))
  127.       (msg "bag[" n "]: " (if (== type 0) "Text." "Rectangle.")
  128.     " Width:" width " Height:" height " Size:" size
  129.       )
  130.     })
  131.   Note:
  132.     If the bag is not a rectangle, the width and height are garbage.
  133.   See also:  append-to-bag, clear-bag, insert-bag.
  134. (bag-to-file bag-id file-name)             [NUMBER STRING : BOOLEAN]
  135.   Copy the contents of a bag to a file.  If the file already exists, it
  136.     is overwritten.
  137.   If bag-id is bad, the program aborts.
  138.   If some kind of error occurs (can't open file-name or can't write all
  139.     of bag), FALSE is returned so you can clean up if necessary.
  140.   See also: file-to-bag, bag-to-string
  141. (bag-to-string bag-id)                     [NUMBER : STRING]
  142.   Convert bag contents to a string.
  143.   If the bag contains a rectangle, the string will be each line of the
  144.     rectangle, one after the other.
  145.   Note:
  146.     The string sticks around until the bag is changed (clear-bag,
  147.     append-to-bag, etc).  At that point, the string is garbage and can
  148.     cause unknown behavior if used.  Use the string or save it - don't
  149.     expect it to hang around.
  150.   See also: append-to-bag
  151. (bind-key keymap-id program-name key-name ...)
  152.               [NUMBER STRING STRING [STRING STRING ...] : BOOLEAN]
  153.   Put zero or more (program-name key-name) pairs in a keymap.
  154.   Keymap-ids can be 0 (global keymap), 1 (local keymap) or a keymap id
  155.     returned by create-keymap.  If 1 and a local keymap hasn't been
  156.     created yet, bind-key creates it.
  157.   program-name is the name of a non-HIDDEN program that must exist.
  158.   key-name is the string form of a keycode ("a", "C-a", etc).
  159.   Notes:
  160.     (bind-key id "" "C-a") removes key C-a from the keymap.
  161.   See also: create-keymap, install-keymap, clear-keymap.
  162. (bit-and x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  163.   Binary and 2 or more numbers.
  164.   See also bit-or, bit-xor.
  165. (bit-clear x bit)   basic.mut              [NUMBER NUMBER : NUMBER]
  166.   Clear a bit in x.  For example (bit-clear 0xf 2) returns 0xd.
  167. (bit-not x)   basic.mut                  [NUMBER NUMBER : NUMBER]
  168.   Return the ones complement of x.
  169. (bit-or  x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  170.   Binary or 2 or more numbers.
  171.   See also bit-and, bit-xor.
  172. (bit-xor x y [z ...])             [NUMBER NUMBER [NUMBER ...] : NUMBER]
  173.   Binary xor 2 or more numbers.
  174.   See also bit-and, bit-or.
  175. (BoB)  basic.mut                       [zip : BOOLEAN]
  176.   TRUE if the cursor is at the beginning of the buffer.
  177.   See also: EoB.
  178. (buffer-displayed buffer-id)  basic.mut            [NUMBER : BOOLEAN]
  179.   Returns the id of the window that is displaying the buffer.  Returns
  180.     -2 if the buffer is not being displayed.
  181. (buffer-exists buffer-id)    basic.mut        [NUMBER : BOOLEAN]
  182.   Look though all the buffers to see if buffer-id is one of them.
  183.   Returns TRUE if it is.
  184.   Notes:
  185.     This routine can give false readings in the case a buffer has been
  186.     freed and another one created, since buffer id's are recycled.  If
  187.     this might be a problem, put a hook in FREE-BUFFER-HOOK.
  188. (buffer-flags buffer-id [flags])        [NUMBER [NUMBER] : NUMBER]
  189.   Get or set the buffer flags.  There are 32 flags.
  190.     Bit        Flag    Notes
  191.     ---        ----    -----
  192.     0x0001  Modified    1 if the buffer has been modified since last save.
  193.     0x0002  NoCare    1 if don't care about buffer contents.
  194.     0x0004  Hidden    1 if buffer is hidden from user.
  195.     0x0008  Undo    1 if undo is turned on for the buffer.
  196.     0x0010  Mode    Tickle bit: force (modeline-hook) to be called.
  197.     0x0020  Immortal    Not a temporary buffer.
  198.     0x0040  Interactive A buffer for humans.
  199.  
  200.     The lower eight bits are reserved for ME's use, you can use the
  201.       other 24.  Note - you might want to leave a few bits at the bottom
  202.       unused in case I need some more in the future.
  203.   Notes:
  204.     The Modified flag is set whenever the buffer changes.  When it
  205.       changes, (modeline-hook) is called.
  206.     The NoCare flag is used whenever ME wants exit or change a buffer -
  207.       it is set, ME will not ask before changes are made.
  208.     A buffer with the Hidden flag set is invisible to the user -
  209.       (next-buffer) skips it, the help and command completion routines
  210.       ignore it.
  211.     If you want a buffer to have undo, set this bit.  0 (off) is the
  212.       default.
  213.     Mode is a write only flag.  Set it if you want (modeline-hook) to be
  214.       called.
  215.     All buffers are created Mortal by default.  This means that they can
  216.       be garbage collected when your program is done running.  If you
  217.       want the buffer to live forever (at least until you free it), set
  218.       this bit.  Actually, set this bit in (create-buffer).
  219.     ME sets the Interactive bit for program convenience.  I typically
  220.       use it to avoid setting modes, etc for buffers where the modes
  221.       won't be used.  It is set by:  (switch-to-buffer), (visit-file)
  222.         and when the last buffer is freed and I have to create *scratch*.
  223.     If a tickle bit is set, only tickle bits are processed and other
  224.       bits are ignored.  So, for example, if you wanted (modeline-hook)
  225.       called and set the Undo flag, it takes two calls to
  226.       (buffer-flags).
  227.   See also: buffer-modified, create-buffer, modeline-hook.
  228. (buffer-modified buffer-id [bool])          [NUMBER [BOOLEAN] : BOOLEAN]
  229.   Check to see if buffer n is modified.
  230.   If n == -1 the current buffer is used.
  231.   (buffer-modified -1) : TRUE if the current buffer is modified.
  232.   (buffer-modified 123) : TRUE if the buffer with id 123 has been modified.
  233.   (buffer-modified -1 FALSE) : mark the current buffer as not modified.
  234.   See also: buffer-flags, current-buffer, (not-modified).
  235. (buffer-name buffer-id or file-name)          [NUMBER | STRING : STRING]
  236.   (buffer-name buffer-id)
  237.     Return the name of a buffer.
  238.     (buffer-name -1) returns the name of the current buffer.
  239.   (buffer-name file-name)
  240.     Convert a string (assumed to be a file name, maybe with path) into a
  241.       string that can be used as a buffer name.  This is OS dependent
  242.       but usually just removed the path from the file name.
  243.     Notes:
  244.       Wildcards are not expanded, you need to do that yourself.  Use
  245.         (file-name) (for an existing buffer) or the following program:
  246.         ;; Overwrite fname with a canonized file name.
  247.         ;; Returns "" if invalid file name.
  248.     (defun cannonize-file-name (string fname)
  249.       {
  250.         (int bid)
  251.  
  252.         (bid (create-buffer ""))
  253.         (file-name bid fname)
  254.         (fname (file-name bid))
  255.         (free-buffer bid)
  256.  
  257.         (!= "" fname)
  258.       })
  259.     
  260.   See also: create-buffer, current-buffer, file-name.
  261. (buffer-read-only [read-only])        basic.mut    [[BOOLEAN] : BOOLEAN]
  262.   Return TRUE if the current buffer is read only (ie if
  263.     (bit-and BFRead_only (buffer-flags -1)) is non-zero).
  264.   If read-only is passed in, the flag is set.
  265.   See also:  toggle-read-only.
  266. (buffer-stats n array int 6)                  [NUMBER BLOB : VOID]
  267.   Get some stats on the nth buffer.  n == -1 means current buffer.
  268.   These  stats  are:  buffer-size  (in   characters),   dot  (number  of
  269.     characters  from the start of the  buffer),  lines  (number  of text
  270.     lines in the buffer),  buffer-row (the line in the buffer the dot is
  271.     on), wasted (the number of  characters  allocated  but not used) and
  272.     character-at-dot  (ASCII  value  - eg if  the  dot is on a "A"  then
  273.     character-at-dot == 65).
  274.   Note that buffer-size may NOT be the same as the file size.  For
  275.     example, on MS-DOS the buffer is smaller than the file because the
  276.     <carriage-return><newline> is folded into a newline when the file is
  277.     read into the buffer.
  278.   An example of a typical Emacs buffer stats routine (ie whats bound to
  279.     "^X=") is:
  280.     (include tobase.mut)
  281.     (defun show-buffer-stats    ; bind this to "C-X="
  282.     {
  283.         ;; struct BufferInfo
  284.       (int buffer-size dot lines buffer-row wasted char-at-dot ratio)
  285.     
  286.       (buffer-stats -1 (loc buffer-size))
  287.       (ratio 0)(if (!= 0 buffer-size)(ratio (/ (* 100 dot) buffer-size)))
  288.       (msg "Row: " buffer-row "/" lines  " Column: " (current-column)
  289.       " CH: 0x" (tobase char-at-dot 16) 
  290.       " (" ratio "% of " buffer-size ")")
  291.     })
  292.   See also: nth-buffer
  293. (buffer-to-file file-name &lines &error-code)
  294.                       [STRING [NUMBER [NUMBER]] : BOOLEAN]
  295.   Write the contents of the current buffer to a file.
  296.   Returns:
  297.     TRUE is all OK, lines is set to the number of lines written and
  298.       error-code is set to 0.
  299.     FALSE if couldn't successfully write, error_code is set to one of:
  300.     3 Error of some kind.
  301.     4 Bad file name.
  302.   Notes:
  303.     Wildcards (*, ~, etc) in file-name are expanded.
  304.     Buffer changed flag is cleared.
  305.   See also:  file-to-buffer.
  306. (buffer-var var-name [value])                  [STRING [val] : val]
  307.   Each buffer can have local variables.  These vars are not used by ME -
  308.     they are there for program use.
  309.   The current buffer is searched for a buffer variable named var-name.
  310.     If it exists and you are trying to set its value, the value is
  311.     checked to make sure its type matches that of the buffer var and
  312.     then value is copied into the var.
  313.   The var is returned (with the new value if set), ready to be used like
  314.     any other Mutt var.
  315.   For example:
  316.     (int n)
  317.     (create-buffer-var NUMBER "x")    ;; create buffer var x of type number
  318.     (create-buffer-var STRING "s" "t")    ;; create 2 string buffer vars
  319.     (buffer-var "x" 123)    ;; set buffer var x to 123
  320.     (n (buffer-var "x"))    ;; also set n to 123
  321.     (buffer-var "s" "foo bar")    ;; set buffer var s to "foo bar"
  322.   Notes:
  323.     Lists and strings are not as well supported in Mutt2 as they could
  324.       be.  Right now, I don't have list or string pointer variables so
  325.       if you want to use a list or string buffer variable without
  326.       referring to it by name, you have to do extra data copies.  For
  327.       example, if you have a list buffer variable and want to modify it,
  328.       you can either use (buffer-var "foo") every time you need the list
  329.       (and spend time doing lookups) or you can (list foo)(foo
  330.       (buffer-var "foo")) and then use foo as you would any other list.
  331.       The drawback here is a copy of the buffer var is put into foo
  332.       (possibly wasting space if the buffer var is very big and it takes
  333.       time to do the copy).  You also have to remember to copy foo back
  334.       into the buffer bar after you modify it or all your changes will
  335.       be garbage collected into never-never land.  If I ever get around
  336.       to implementing pointer types, you will be able to (pointer list
  337.       foo)(foo (loc (buffer-var "foo"))) and then when you modify foo,
  338.       you will be really modifying the buffer var, avoiding extraneous
  339.       data copies and making less garbage to be collected.  You can fake
  340.       pointers by passing the buffer var to a function:  (bar
  341.       (buffer-var "foo")) where (defun bar (list foo) ...).  bar will
  342.       get a pointer to foo and can change it as described above.
  343.   See also:  create-buffer-var, markring.mut
  344. (buffers)                            [zip : NUMBER]
  345.   Return the number of buffers.
  346.   See also: nth-buffer.
  347.  
  348. (cannonize-file-name file-name)  basic.mut        [STRING : STRING]
  349.   Returns the canonical file name of file-name.  This is a unique file
  350.     name that can be used to compare with other file names.  It is what
  351.     (file-name) returns.  Shell style wildcards (*, ~, etc) are expanded.
  352.   For example, (cannonize-file-name "~craig/*.mut") might return
  353.     "/users/craig/basic.mut".
  354. (case-bag op bag-id)                    [NUMBER NUMBER : VOID]
  355.   Do some case folding on the contents of a bag.
  356.     op    action
  357.     --    ------
  358.     0    Lower case text.  All text in the bag is converted to lower case
  359.     in place.
  360.     1    Upper case text.
  361.     2    Capitalize text.  All text in the bag is capitalized.  The
  362.     starts of words are converted to upper case and all other text
  363.     is converted to lower case.  A character is the start of a word
  364.     if:  It is the first character in the bag and the syntax tables
  365.     say it is a word character or the character is a word character
  366.     and the character before it is a nonword character (white space).
  367.   See also: modify-syntax-entry, case.mut (for examples).
  368. (clear-buffer)                              [zip : VOID]
  369.   Clear the current buffer.
  370.   Remove all contents of the buffer and clear the marks.  There is no
  371.     checking - you need to do that if you care.  If undo is turned on,
  372.     the undo stack is cleared (yeah, I know it stinks, but I had my
  373.     reasons).
  374.   clear-buffer-hook is called unless the buffer is being cleared because
  375.     it is being freed.  That is, when (free-buffer) calls
  376.     (clear-buffer), clear-buffer-hook is not called.  But
  377.     free-buffer-hook is.
  378.   See also: clear-buffer-hook, free-buffer
  379. (clear-bag bag-id)                     [NUMBER : NUMBER]
  380.   Clears the bag by setting it to "".  The bag type is set to TEXT.
  381.   Bag id 0 is the cut buffer.
  382.   Returns bag-id.
  383.   See also:  append-to-bag, create-bag, insert-bag, bag-stats.
  384. (clear-keymap keymap-id)                   [NUMBER : VOID]
  385.   Clear a keymap by removing all the bindings from it.  You should not
  386.     be using this (ie I don't think its really needed), use
  387.     install-keymap instead (maybe installing the null keymap).
  388.   See also:  create-keymap, install-keymap.
  389. (command-flag op flag)         [NUMBER NUMBER : NUMBER | BOOLEAN | VOID]
  390.   The command flag is how key driven routines can "talk" to each other.
  391.     For example, repeated C-n's stay in the same column.  The C-n code
  392.     (next-line), knows that the last command was also a next-file if the
  393.     command flag is set to 4 (CF-LINE).  It also set the command flag to
  394.     4 so that if the next key is a next line, it will know to stay in
  395.     the same column.
  396.   After every keystroke (in the main loop), the current command flag is
  397.     copied to the "last" flag and the current flag is cleared.
  398.   Note:  Command flags only really work for keypress driven routines (ie
  399.     interactive programs bound to keys).  If program calls these
  400.     routines, the command flag is not updated properly because control
  401.     flow is not though the main loop.  Thus, if these routines are
  402.     called several times, they might not function as expected.  Usually
  403.     this is OK.
  404.   If you would like to use a command flag that is not in the predefined
  405.     list, you can have ME create one for you.  By letting ME generate
  406.     it, you can avoid conflicting with future programs.
  407.   (command-flag 0 flag)
  408.     Sets the command flag for this routine to flag.  The next command
  409.     will test against this flag.  Returns VOID.
  410.   (command-flag 1 flag)
  411.     Returns TRUE if the last command set flag.
  412.   (command-flag 2 flag)
  413.     Returns TRUE the last command was did NOT set flag.
  414.   (command-flag 3 flag)
  415.     Sets command flag to flag (same as (command-flag 0 flag)) and
  416.     returns TRUE if the last flag was NOT flag (same as (command-flag 2
  417.     flag)).
  418.   (command-flag 4 ignored)
  419.     Generates and returns a new command flag that can be used by
  420.     routines you write.
  421.   See also:  me.mh for predefined command flags.
  422. (compare-marks [mark1 mark2])            [[NUMBER NUMBER] : NUMBER]
  423.   Returns: 1 (dot on same line as mark), 2 (dot above mark),
  424.     3 (dot below mark).
  425.   See also: region-stats.
  426. (complete selector "prompt")              [NUMBER STRING : STRING]
  427. (complete selector "prompt" list)          [NUMBER STRING LIST: STRING]
  428.   Works the same as (ask) but allows command completion.  The response
  429.     is returned.
  430.     Selector: bitwise OR the lists you want to complete:
  431.     Bit    Value    List
  432.     ---    -----    ----
  433.      0    0x01    Obsolete, not used.
  434.      1    0x02    Program names
  435.         2    0x04    Mutt keywords
  436.         3    0x08    Buffer names
  437.      4    0x10    System variables
  438.      5    0x20    File names
  439.      6    0x40    Sorted list of words
  440.      7    0x80    Don't ask
  441.   For example:  Get a file path, using file name completion and insert
  442.     it at the dot:
  443.     (defun insert-file-name
  444.     { (insert-text (complete 0x20 "file name: ")) })
  445.   To complete from an arbitrary list of words, use list.  The list must
  446.     be sorted (the first word in the list must be the "smallest"
  447.     (alphabetically).  For example:
  448.       (list words)
  449.       (insert-object words 0 "one" "three" "two")
  450.       (complete 0x40 "Pick one: " words)
  451.   To complete a word without querying, use
  452.     (complete (bit-or 0x80 selector) word-to-complete [list])
  453.     The word is completed as far as possible and returned.
  454.   See also: ask (in mutt2.doc), prime-ask.
  455. (create-bag [immortal])                      [[BOOLEAN] : NUMBER]
  456.   Create a bag and return its id.  Whenever you need to do something
  457.     with this new bag, use its id.
  458.   The immortal flag controls how a bag is treated at garbage collection
  459.     time.  If TRUE, the bag won't be garbage collected and you have to
  460.     use free-bag to get rid of the bag.
  461.   The cut buffer always has an id of 0 and is created by ME at startup.
  462.   See also: free-bag, the discussion about garbage collection.
  463. (create-buffer name [flags])            [STRING [NUMBER] : NUMBER]
  464.   Create a buffer and return its id.  Whenever you need to do something
  465.     with this new buffer, use its id.
  466.   The name can be anything you want - it can be empty, contain blanks,
  467.     be the same as other buffer names, etc.  Since the buffer is referred
  468.     to by its id, there is no confusion.  Where the confusion comes in
  469.     is when the user wants to deal with the buffer - in that case, you
  470.     might want to use something reasonable for the name.
  471.   See buffer-flags for info on those.  Remember to set the immortal bit
  472.     if you want the buffer to hang around.
  473.   create-buffer-hook is called.
  474.   See also:  attached-buffer, buffer-flags, free-buffer, the discussion
  475.     about garbage collection, create-buffer-hook.
  476. (create-buffer-var type name [name ...])    [NUMBER STRING ... : VOID]
  477.   Create one or more buffer variables with a given type.
  478.   Supported types:
  479.     NUMBER    0x03
  480.     STRING    0x08
  481.     LIST    0x09
  482.   Buffer local variables are variables that live in a buffer.  This
  483.     allows you to store localized data in a buffer - two buffers can
  484.     have variables of the same name that contain different data (or even
  485.     data with different types).  This is useful when you need one
  486.     variable to hold different data for each buffer (such as with mark
  487.     rings - each buffer has a different ring but the mark ring code is
  488.     the same for all buffers).
  489.   Buffer vars live and die with the buffer.  When the buffer is freed,
  490.     all the buffer vars are too.  This is the only way to remove buffer
  491.     vars from a buffer.
  492.   If a buffer var named <name> already exists, create-buffer-var doesn't
  493.     do anything.  It should at least check to see if the types match.
  494.   See also:  buffer-var, markring.mut
  495. (create-keymap)                              [ : NUMBER]
  496. (create-keymap keymap-to-duplicate)            [NUMBER : NUMBER]
  497.   (create-keymap)
  498.     Create a keymap.
  499.   (create-keymap id)
  500.     Create a keymap by copying an existing keymap.  The new keymap has a
  501.       copy of all the data in the other keymap.
  502.   Returns the id of the created keymap.
  503.   Notes:
  504.     Keymaps can't be freed.
  505.   See also: bind-key, install-keymap, clear-keymap.
  506. (create-mark [immortal])                  [[BOOLEAN] : NUMBER]
  507.   Create a mark and return its id.  Whenever you need to do something
  508.     with this new mark, use its id.  Marks are always created in the
  509.     current buffer and are invalid (ie not marking anything) when
  510.     created.
  511.   The immortal flag controls how a mark is treated at garbage collection
  512.     time.  If TRUE, the mark won't be garbage collected and you have use
  513.     free-mark to get rid of the mark.
  514.   When a buffer is created, two marks are allocated in it:  the dot (id
  515.     0) and the mark (id 1).  They are always in the buffer can be used
  516.     just like any other mark.  They can't be freed.
  517.   See also: free-mark, the discussion about garbage collection and marks.
  518. (create-process)                           [ : NUMBER]
  519. (create-process command)                 [STRING : NUMBER]
  520.   Create a process that will run concurrently with ME.  Command is
  521.     passed to the compute server for parsing and running.  The process
  522.     communicates to your Mutt program via the process-hook hook.
  523.   (create-process) will establish a connection to the compute server.
  524.     You can use it to determine if it is available (returns -1 if the
  525.     compute server is not available, something != -1 if it is).
  526.   Notes:
  527.     The compute server is not built into ME - it is also a separate
  528.       process.  For this reason (and others), only Unix supports
  529.       the compute server.  It needs to be running before create-process
  530.       is called.  The socket name for ME is "$HOME/.ME2.socket".
  531.     You can have many processes running.  Your Mutt programs will have
  532.       to keep track of the process ids to be able to track each process.
  533.   Returns:
  534.     Process id.  -1 if can't create a process.  This id will be used by
  535.       process-hook when the process sends messages to Mutt programs.
  536.   See also:  process-hook, documentation on the compute server
  537.     (comserver.doc).
  538. (current-buffer)                        [zip : NUMBER]
  539. (current-buffer buffer-id [display-buffer])    [NUMBER [BOOLEAN] : NUMBER]
  540.   Return the id of the current buffer.
  541.   To change the current buffer, pass in the id.  If you want the new
  542.     current buffer to be displayed in the current window, pass
  543.     display-buffer as TRUE.  The current window will be sync'ed with the
  544.     buffer (ie the window dot will be in the same place as the buffer
  545.     dot).
  546.   If you change the current buffer without displaying it, the windows
  547.     will be unaffected by anything that happens in the buffer - ie you
  548.     would not be able to see anything happening on the screen.  When
  549.     the program finishes running, the buffers and windows will be synced
  550.     up to what they were before the program ran.
  551.   If you change the current buffer and the new current buffer is
  552.     displayed in a non-current window, changes you make to the buffer
  553.     might not be reflected in that window.  See "update" for more on
  554.     this.
  555.   See also:  create-buffer, buffer-modified, buffer-name, buffers,
  556.     file-name, update.
  557. (current-column [column])                   [[NUMBER] : NUMBER]
  558.   With no argument, returns the column after the dot.  Otherwise, the
  559.     dot is set to column.
  560.   (beginning-of-line) is 1.
  561.   When you set the current-column, the dot will get as close as possible
  562.     to the position you specify, subject to:
  563.     - the dot will not leave the current line.
  564.     - because  of tabs and such, the dot may not be in the  column  you
  565.        specify but will be BEFORE the  character  that would have caused
  566.        the dot to be beyond the specified position.
  567.   The new dot column is returned.
  568.   If you wish to force the dot to be in column n, use (current-column n)
  569.     (to-col n).
  570. (current-directory)                           [ : STRING]
  571. (current-directory directory)                [STRING : BOOLEAN]
  572.   (current-directory) returns the current directory (eg "/users/craig").
  573.   (current-directory "tools") attempts to set the current directory to
  574.       tools.  Returns TRUE if successful, FALSE otherwise.
  575.   See also: dir.mut for examples.
  576. (current-line)                              [ : BOOLEAN]
  577. (current-line n)                    [NUMBER : BOOLEAN]
  578.   (current-line) returns the line number the dot is in, in the current
  579.     buffer.  The first line of the buffer is 1.
  580.   (current-line n):
  581.     Move the dot to the beginning of the nth line in the current buffer.
  582.       If n is negative, got the nth line from the end of the buffer.
  583.     Returns FALSE is try to move off either end of the buffer.  In that
  584.       case the dot is left at the buffer edge it tried to move across
  585.       (at the start of the line).
  586.     Notes:  Line 0 does not really exist so (current-line 0) returns
  587.       FALSE.  If you ignore the error, (current-line 0) is the same as
  588.       (current-line 1).
  589. (current-window [n])                       [[NUMBER] : NUMBER]
  590.   Return the id of the current window.  The windows are numbered 0,
  591.     1, ... (windows)-1 where window 0 is the top window on the screen.
  592.   If changing the current window then:
  593.     The current buffer is changed to the one being displayed in window
  594.       n.  For example, if the current buffer is "foo" and window 0 is
  595.       displaying buffer "bar", (current-window 0) also changes the
  596.       current buffer to "bar".
  597.     The window dot is copied into the buffer dot ie the current buffer
  598.       is sync'ed with the current window.  Thus a buffer will track
  599.       window changes BUT NOT vice versa.
  600.   If you change windows and need the screen cursor to be moved to the
  601.     new window, use (update).  You need to do this (for example), if you
  602.     want (window-row) to work after the change.
  603.   See also:  attached-buffer, windows, update, (next-window),
  604.     (previous-window) (in me3.doc).
  605.  
  606. (delete-region [mark1 [mark2]]            [[NUMBER [NUMBER]] : VOID]
  607.   (delete-region)      is the same as (delete-region THE-DOT THE-MARK)
  608.   (delete-region mark) is the same as (delete-region mark    THE-MARK )
  609.   (delete-region mark1 mark2)
  610.     Delete the region between mark1 and mark2.  The region is not saved.
  611.   Errors:
  612.     One or more of the marks is invalid.
  613.     Ran out of memory.
  614. (do-undo)                            [zip : NUMBER]
  615.   If undo is turned on for this buffer, undo the last block of changes.
  616.   Returns:
  617.     0 : Nothing happened (despite my best efforts)
  618.     1 : Something happened (ie something was undid)
  619.     2 : Problems of some unknow nature
  620.   See also:  buffer-flags, create-buffer, create-buffer-hook.
  621.  
  622. (EoB)                               [zip : BOOLEAN]
  623.   True if the cursor is at the end of the buffer.  Note that end of
  624.     buffer is the empty line you get to with (end-of-buffer).
  625.   See also: BoB.
  626. (erase-rectangle delete)                  [BOOLEAN : VOID]
  627.   Delete or clear the region-rectangle.  If delete is TRUE, the text in
  628.     the rectangle is removed, otherwise it is set to blanks (short lines
  629.     are not extended).
  630.   The dot is left at the upper left corner of the rectangle and the mark
  631.     is at the lower right corner.
  632.   The region-rectangle is the rectangle that has the dot at one corner
  633.     and the mark at the opposite corner.
  634.   See also: append-to-bag, register-stats.
  635. (exe-key keycode)                    [NUMBER : BOOLEAN]
  636.   Execute a key gotten by get-key.  This is the same as pressing that
  637.     key combo on the keyboard.
  638.   Returns TRUE if the key was executable.
  639.   Notes:
  640.    key-pressed is set to the key being executed.
  641.    arg-flag is set to FALSE and arg-prefix is set to 1.
  642.   See also: arg-flag, arg-prefix, get-key, key-pressed.
  643.  
  644. (file-exists file-name)                    [STRING : BOOLEAN]
  645.   Returns TRUE if file-name exists on disk.  If (file-exists file-name)
  646.     returns TRUE then (visit-file file-name) should also return TRUE.
  647. (file-name buffer-id)                     [NUMBER : STRING]
  648. (file-name buffer-id new-name)             [NUMBER STRING : BOOLEAN]
  649. (file-name file-name [search-path])        [STRING [STRING] : STRING]
  650.   (file-name buffer-id)                     [NUMBER : STRING]
  651.     Return the name of the file attached to a buffer.  If a file is NOT
  652.       attached, returns "".
  653.     (file-name -1) returns the name of the file attached to the current
  654.       buffer.
  655.   (file-name buffer-id new-name)
  656.     With new-name, attach a new name for the file attached to the
  657.       current buffer.  Returns TRUE is everything went as expected.
  658.     Wildcards are expanded.
  659.   (file-name file-name [search-path])
  660.     See if file-name can be opened.  If search-path exists, it is used
  661.       to try and find file-name.  Search-path has the same form as the
  662.       ME3 environment variable (same format as the PATH environment
  663.       variable on your OS) and the search is the same as UNIX $PATH
  664.       searches.
  665.     Returns:  "" if file-name not found, otherwise a string that can be
  666.       used in functions (it will have have a path prepended to it).
  667.   (file-name file-name "")
  668.     Don't use a search path.  This is pretty much the same as
  669.       file-exists.
  670.   (file-name file-name)
  671.     Use the same search path as ME does when loading Mutt code.  See
  672.       load-code.
  673.   See also: buffer-name, file-exists, load-code.
  674. (file-to-bag file-name bag-id)             [STRING NUMBER : BOOLEAN]
  675.   Copy the contents of a file to a bag.  The old contents of the bag are
  676.     cleared.
  677.   If bag-id is bad, the program aborts.
  678.   If some kind of error occurs (can't open file-name or can't copy all
  679.     of file-name into bag), FALSE is returned so you can clean up if
  680.     necessary.
  681.   See also: bag-to-file, bag-to-string
  682. (file-to-buffer file-name)                    [STRING : BOOLEAN]
  683. (file-to-buffer file-name lines-read) [STRING pointer-to-NUMBER : BOOLEAN]
  684. (file-to-buffer file-name lines-read error-code)
  685.             [STRING pointer-to-NUMBER pointer-to-NUMBER : BOOLEAN]
  686.   Insert the contents of a file into the current buffer at the dot.
  687.   Returns:
  688.     TRUE is all OK, lines is set to the number of lines read and
  689.       error-code is set to 0.
  690.     FALSE if couldn't successfully read, error_code is set to one of:
  691.     1 File not found.
  692.     2 End of file.
  693.     3 Error of some kind.
  694.     4 Bad file name.
  695.     5 No memory.
  696.   Notes:
  697.     The dot is left after the insert, marks before.
  698.     Wildcards (*, ~, etc) in file-name are expanded.
  699.     Buffer changed flag is cleared.
  700.   See also:  buffer-to-file, clear-buffer, insert-text, insert-bag.
  701. (forward-char n)                    [NUMBER : BOOLEAN]
  702.   Move the dot forward n characters (backwards if n < 0).
  703.   Returns TRUE if all OK, FALSE if try move off the edge of the buffer
  704.     (the dot is left at the closest edge).
  705. (forward-line n)                    [NUMBER : BOOLEAN]
  706.   Move the dot forward n lines (backwards if n < 0).
  707.   The dot is left at column one.
  708.   Returns TRUE if all OK, FALSE if try move off the edge of the buffer
  709.     (the dot is left at the closest edge).
  710. (forward-word n)                    [NUMBER : BOOLEAN]
  711.   Move the dot forward n words (backwards if n < 0).
  712.   Returns TRUE if all OK, FALSE if try move off the edge of the buffer
  713.     (the dot is left at the closest edge).
  714. (free-bag bag-id ...)                [[NUMBER [NUMBER ...]] : VOID]
  715.   Free zero or more bags and their contents.  It is always a good idea
  716.     to free bags after you use them (to save space, etc) but you only
  717.     really have to if the bag is immortal.  Mortal bags will be garbage
  718.     collected after your program has finished running.
  719.   Note:
  720.     While it possible to free the cut-buffer (id 0), it is a bad idea
  721.       (and probably a bug).  Lots of people assume (yeah, I know what
  722.       they say about that) that the cut buffer exists and just use it.
  723.       If you do free it, expect fire works.
  724.   See also: create-bag.
  725. (free-buffer buffer-id)                     [NUMBER : NUMBER]
  726.   Free a buffer and all its contents, keys, marks and other resources.
  727.     If not freed, mortal buffers will be garbage collected.
  728.   free-buffer-hook is called.
  729.   See also: create-buffer.
  730. (free-mark mark-id ...)                [[NUMBER [NUMBER ...]] : VOID]
  731.   Free zero or more marks.  It is always a good idea to free marks after
  732.     you use them (to save space, etc) but you only really have to if the
  733.     mark is immortal.  Mortal marks will be garbage collected after your
  734.     program has finished running.
  735.   You can't free the dot (id 0) or the mark (id 1).
  736.   See also: create-mark.
  737. (free-window [n])                      [[NUMBER] : BOOLEAN]
  738.   Remove the nth window from the screen.  If no arg, remove the current
  739.     window.  n == -1 means the current window.
  740.   If there is only one window on screen, it is not deleted and FALSE is
  741.     returned otherwise TRUE is returned.
  742.   See also: (split-window), (delete-other-windows) (in me3.doc).
  743.  
  744. (get-key)                          [zip : NUMBER]
  745.   Wait for and grab the next ME key combo pressed.  These have a rather
  746.     strange format so it is a good idea to print out the ones you need
  747.     with (insert-text (get-key)).  If you look at the hex values you
  748.     might see a pattern.
  749.   key combo    get-key value
  750.     CR C-M      333 (0x014D)
  751.     f1 F-1     2097 (0x0831)
  752.     a           97 (0x0061)
  753.     A           65 (0x0041)
  754.     ^A C-A      321 (0x0141)
  755.     ^XA ^Xa C-XA 1089 (0x0441)
  756.     ^X^A C-XC-A     1345 (0x0541)
  757.     M-A          577 (0x0241)
  758.   See also: exe-key, getchar.
  759. (get-matched sub-string)                 [STRING : STRING]
  760.   Return the RE substitution of the last (re-search-xxx) or
  761.     (looking-at).
  762.   See regexp.doc for syntax of the sub string.
  763.   eg if (re-search-forward 'f\w*r') matched "foobar" then (get-matched "&")
  764.     returns "foobar".
  765.   See also: (looking-at), (re-string), (re-search-forward),
  766.     (re-search-reverse).
  767. (getchar)                            [zip : STRING]
  768.   Get a character from the keyboard with no echo.  This is different from
  769.     get-key in that the string is the ASCII value of the next key hit.  You
  770.     should only use this for real raw input.
  771.   See also: get-key.
  772. (getenv environment-variable-name)             [STRING : STRING]
  773.   Get the value of a environment variable.
  774.   Returns "" if not found.
  775.   For example: (getenv "SHELL") might return "D:/MUSH.EXE".
  776. (goto-mark mark-id)                    [NUMBER : BOOLEAN]
  777.   Move the dot to the mark whos id is mark-id.
  778.   Returns FALSE if mark-id doesn't exist or the mark is invalid (hasn't
  779.     been set or has been cleared).
  780.   See also:  create-mark, set-mark, swap-marks.
  781.  
  782. (insert-bag bag-id)                       [NUMBER : VOID]
  783.   Insert the contents of a bag at the dot in the current buffer.
  784.   Bag 0 is the cut buffer.  (insert-bag 0) is the same as (yank).
  785.   If the bag contains a rectangle, the upper left corner of the
  786.     rectangle will be at the dot.
  787.   The dot is left after the insert, marks before.
  788.   See also:  create-bag, append-to-bag, clear-bag, bag-stats,
  789.     bag-to-file, file-to-bag, file-to-buffer.
  790. (insert-text stuff)           [STRINGs|NUMBERs|BOOLEANS|VOIDs : VOID]
  791.   Same as msg but the string is inserted into the current buffer.
  792.   eg (insert-text "foo = " foo)
  793.   The dot is left after the insert, marks before.
  794.   See also: insert-bag, file-to-buffer, msg (in mutt2.doc).
  795. (install-keymap keymap-id [where-to-install])    [NUMBER [NUMBER] : NUMBER]
  796.   Installing a keymap:
  797.     (install-keymap id 0) Install the global keymap.
  798.     (install-keymap id 1) Install the keymap as the local keymap in the
  799.       current buffer.
  800.     If id is 2, the NULL keymap (an always empty keymap, always exists)
  801.       is installed.
  802.     Notes:
  803.       You can install the same keymap in several buffers (and as the
  804.         global keymap).  The drawback is a (bind-key) will affect all
  805.     the buffers sharing the keymap.
  806.       If (bind-key) has to create a local keymap (because one hasn't
  807.     been installed before bind-key was run), it will be a short
  808.     lived keymap - the keymap will be freed when the buffer is freed
  809.     or a local keymap is installed.  Otherwise, it is a normal
  810.     buffer but can be a pain because if you swapping keymaps (for
  811.     example for modes), the keymap might disappear.
  812.       The global keymap is created when ME starts (so you don't have to
  813.         create it).  You can install a new keymap over it if you want to.
  814.       If you install a new temporary global keymap (ie you will be
  815.         switching between two (or more) global keymaps), be careful of
  816.     (load-code) (and autoloading).  If the loaded code binds keys
  817.     (in the global keymap), it could very well put the keys in the
  818.     wrong global keymap.
  819.       Keymaps can't be freed (from a program).
  820.   Getting the keymap id:
  821.     (install-keymap 0) Return the id of the global keymap.
  822.     (install-keymap 1) Return the id of the local keymap.  2 if there
  823.       is no local keymap installed.
  824.     (install-keymap 2) Always returns 2.
  825.     (install-keymap n) Returns n if there is a keymap with an id of n,
  826.       otherwise -1.
  827.   See also: bind-key, clear-keymap, create-keymap.
  828. (is-space)                           [zip : BOOLEAN]
  829.   TRUE if character under cursor is a space or tab.
  830.  
  831. (key-bound-to keystroke-string)                 [STRING : STRING]
  832.   Tell what command a key is bound to.
  833.   For example, (key-bound-to "^A") returns "beginning-of-line".
  834.   If the key is not bound, key-bound-to returns "".
  835.   The typical Emacs function to tell what a key is bound to is:
  836.     describe-key    ;; what is a key bound to
  837.     {
  838.       (string key bind)
  839.  
  840.       (key (ask "Key: "))
  841.       (if (== "" (bind (key-bound-to key)))(msg key " is not bound.")
  842.       (msg key " is bound to " bind))
  843.     })
  844.   For Mutt programmer types, a handy program is:
  845.     deref-key    ;; insert name of the function bound to a key
  846.     {
  847.       (string key bind)
  848.       (key (ask "Key: "))
  849.       (if (!= "" (bind (key-bound-to key)))(insert-text bind))
  850.     })
  851.     This allows programming using keys rather than remembering command
  852.       names.
  853.   See also: complete.
  854. (key-pressed)                            [zip : NUMBER]
  855.   Returns the keycode of the key pressed to invoke the currently
  856.     executing program.
  857.   Note: exe-key sets this.
  858.   See also: exe-key, picture-self-insert in picture.mut for an example.
  859. (keystroke-macro command)                [NUMBER : BOOLEAN]
  860. (keystroke-macro 12 [n])                [NUMBER : BOOLEAN]
  861. (keystroke-macro 13)                    [NUMBER : NUMBER]
  862.   Manage keyboard macros.  A keyboard macro is a sequence of key presses.
  863.     (keystroke-macro 10)
  864.       Start recording a keyboard macro.  Returns FALSE if already
  865.       recording a macro.
  866.     (keystroke-macro 11)
  867.       Stop recording a macro.  The keysequence has been stored and can
  868.       be replayed.  Returns FALSE if not recording a macro.
  869.     (keystroke-macro 12 [n])
  870.       Run a keyboard macro n times (default is 0 times).  If any of the
  871.       macro parts errors, the macro is stopped.  Returns FALSE if
  872.       recording or error running the macro.
  873.     (keystroke-macro 13)
  874.       Returns the macro state:
  875.         0 : Macro is off (not recording).  Can be replayed.
  876.     1 : Macro is recording.
  877.     2 : Macro is playing.
  878. (key-waiting [number-of-seconds-to-wait])          [[NUMBER] : BOOLEAN]
  879.   Returns TRUE if a user pressed key is sitting in the input buffer.
  880.   You can also specify the number of seconds to wait for a key to be
  881.     pressed.  If a key is pressed during the wait, (key-waiting)
  882.     immediately returns TRUE.  If no key is pressed and the time is up,
  883.     FALSE is returned.
  884.   Note: (key-waiting) is the same as (key-waiting 0).
  885.   Warning:  There are limits to how long you can wait.  Due to many
  886.     factors, you should limit number-of-seconds-to-wait to less than
  887.     32401 (9 hours).
  888.   See also: getchar, get-key.
  889.  
  890. (list-keys buffer-id word flags keymap ...)
  891.               [NUMBER STRING NUMBER [NUMBER NUMBER ...] : BOOLEAN]
  892.   Insert a list of programs (and the keys bound to them), functions and
  893.     system variables that match word into a buffer.  Keys are listed
  894.     from from the keymaps.
  895.   Input:
  896.     buffer-id : Id of the buffer to insert the text into.
  897.     word:  Match word.  If "", the all names will match.  Otherwise,
  898.       only those names that have word in them will be listed.  Case
  899.       matters, wildcards are not used.
  900.     flags:  Selects which lists to insert.  An bit-or of:
  901.       Bit    List
  902.       ---    ----
  903.        1    Programs and the keys bound to them
  904.        2    Functions (the functions in this file eg list-keys)
  905.        4    System Variables (eg tab-stops)
  906.        8    Only list programs that have keys bound to them.
  907.     keymaps:  Ids of the keymaps to search for keys in (if flags has the
  908.       1 bit set).
  909.   Returns:  TRUE if everything went OK, FALSE if ran out of memory.    
  910. (load-code file-name [complain [check-first]])
  911.                     [STRING [BOOLEAN [BOOLEAN]] : BOOLEAN]
  912.   Load a Mutt executable code file compiled with the Mutt compiler (MC2).
  913.   Where the file is searched for is controlled by the environment
  914.     variable "ME3".  If it doesn't exist, ME uses a default search path.
  915.     The search path is parsed just like the UNIX ksh PATH variable:
  916.       If code-file-name has a slash in it, the search path is not used.
  917.       Everything between separators (":" on UNIX, ";" on MS-DOS) is a path.
  918.       If you want to search the current directory first, you can put a
  919.     separator at the start of the path.  Eg ":/me3" instead of
  920.     ".:/me3".
  921.       If you want to search the current directory last, you can put a
  922.     separator at the end of the path.  Eg "/me3:" instead of
  923.     "/me3:.".
  924.       (Otherwise, you need to use "." to search the current directory.
  925.     Eg "/me3:.:/mutt").
  926.       It is OK if a directory in the search path doesn't exist.
  927.       MS-DOS only:
  928.         "/" and "\" are treated the same way - as "\".
  929.     If code-file-name starts with a drive (eg "A:"), the ME3 path is
  930.       not searched.
  931.     For example:  ME3=$HOME/mutt:.:/usr/local/lib/mutt
  932.       When (load-code "foo") is done, ME will try to load
  933.       "$HOME/mutt/foo.mco", "./foo.mco" and
  934.       "/usr/local/lib/mutt/foo.mco" in succession.
  935.     Default search paths:
  936.       For Unix: "$HOME:/usr/local/me3:/usr/contrib/me3"
  937.       For MS-DOS: "C:/me3"
  938.       If a search path doesn't exist or $ME3 is "", the search behavior
  939.         is the same as if the search path was ".".
  940.   If complain is TRUE (the default), a message is printed if file-name
  941.     is not found.
  942.   If check-first is TRUE (the default is FALSE), ME checks to see if
  943.     file-name has already been loaded.  If it has, it is not loaded
  944.     again.
  945.   Notes:
  946.     The extension (on the code file) MUST be ".mco" but you don't have
  947.       to type it in (ie I'll change it to ".mco" no matter what it is).
  948.   Warnings:
  949.     A program should NOT try to load it self or the file it is defined
  950.       in (eg if foo is defined in bar.mut, foo should not try to (load
  951.       "bar").  This is because the old bar is discarded (to make room
  952.       for the new code) before foo finishes running (ie foo is thrown
  953.       away).  Depending on the OS, this may work but your asking for
  954.       trouble if you do it.
  955.     If a code file is loaded that has the same name (ignoring path) as
  956.       an already loaded code file, it overwrites the old code.  All keys
  957.       bound to functions in the old code are removed.  See autoload.mut
  958.       for more about loading and late binding.
  959. (looking-at RE-string)                    [STRING : BOOLEAN]
  960. (looking-at RE-string move)            [STRING BOOLEAN : BOOLEAN]
  961. (looking-at RE-string move return-count) [STRING BOOLEAN BOOLEAN : NUMBER]
  962.   Test to see if the text following the dot matches a regular
  963.     expression.  TRUE if it does.
  964.   See regexp.doc for syntax of the pattern string.
  965.   Example:
  966.     If the text following the dot is "foobar" then (looking-at 'f\w*r')
  967.       returns TRUE.
  968.   You can retrieve the matched info with get-matched.
  969.   If move is TRUE and there is a match, the dot is moved over the match.
  970.   If return-count is TRUE, the number of characters matched is returned.
  971.     This is zero if there is no match.
  972.   Remember that if you use the "string" form, "\" & "^" MUST be quoted:
  973.     "\\", "\^" if you don't want strange results.  You can
  974.     avoid this problem by using ' instead of ".  (See mutt2.doc).
  975.   See also: get-matched, re-string.
  976.  
  977. (mark-valid mark-id)                    [NUMBER : BOOLEAN]
  978.   Return TRUE if a mark is "valid" - it exists in the current buffer and
  979.     has been set.
  980.   See also:  create-mark, set-mark.
  981. (make-unique-buffer-name base-name) basic.mut        [STRING : STRING]
  982.   The routine creates a unique buffer name.  If no buffer has base-name
  983.     as its name, base-name is returned.  Otherwise, <1>, <2>, etc is
  984.     appended until a unique name is found.
  985. (modify-syntax-entry modify-string)             [STRING : STRING]
  986.   Modify the syntax table that is used by things that deal with words, etc.
  987.     eg (forward-word) or (re-search-forward).
  988.   String has the form: <type><characters to modify> where type is "w" if
  989.     characters are parts of words, "W" if characters are not parts of words.
  990.   eg (modify-syntax-entry "W0123456789") sez numbers are not parts of words
  991.     (modify-syntax-entry "w-") sez "-" is part of a word.
  992.   Default parts of words are: A-Za-z0123456789$'_
  993.   Returns:  modify-string.
  994. (move-cursor row column [text [clear-to-end-of-line]])
  995.                 [NUMBER NUMBER [NUMBER [NUMBER]] : VOID]
  996.   Move the hardware cursor to (row,column).
  997.   Row and column are both start at zero.
  998.   Move-cursor does not change the dot.
  999.   If text, it is written on to the screen at the cursor.  The next
  1000.     (update) OR control returning to the main input loop will cause the
  1001.     text to disappear.
  1002.   If clear-to-end-of-line is TRUE (default is FALSE), anything after the
  1003.     text (on the line) is cleared.
  1004.   See also: puts.
  1005.  
  1006. (nth-buffer [n])                     [NUMBER : NUMBER]
  1007.   Return the id the of the nth buffer.  Buffers are in a list, sorted
  1008.     alphabetically, so (nth-buffer 0) is the buffer with the "smallest"
  1009.     alphabetical name.
  1010.   (nth-buffer) returns the count of the current buffer ie return n where
  1011.     (nth-buffer n) is the id of the current-buffer or find n where
  1012.     (== (nth-buffer n) (current-buffer)) is TRUE.
  1013.  
  1014. (OS-command command [prompt])              [STRING [STRING]] : BOOLEAN]
  1015.   Give a command to the OS (usually a shell) to process.  For example,
  1016.     "ls".  If there is a prompt AND (ask-user), when the command is done
  1017.     and control returns to ME, the prompt is printed and ME waits for a
  1018.     Return or Newline to be typed.  The screen is refreshed in this
  1019.     case, otherwise it is unchanged (you need to do an (update) if you
  1020.     want force a refresh).
  1021.   Returns:
  1022.     TRUE is everything went OK, FALSE if the command didn't work for
  1023.       some reason (OS dependent).
  1024.   See also:  OS-filter, OS-shell.
  1025. (OS-filter filter-name)
  1026. (OS-filter filter-name in-bag-id)
  1027. (OS-filter filter-name in-bag-id out_bag-id)
  1028. (OS-filter filter-name in-bag-id out_bag-id insert-output-at-dot)
  1029.             [STRING [NUMBER [NUMBER [BOOLEAN]]]] : BOOLEAN]
  1030.   If no input bag or output bag, you can use -1 for the id.
  1031.   Uses the Operating System to filter text.  On Unix and MS-DOS, this is
  1032.     "filter-name <text_in >text_out".
  1033.   in-bag-id contains the text_in to be run through the filter.  If id is
  1034.     -1, there is no standard in for the filter.  Useful if you just want
  1035.     stuff like the output of ls or grep.
  1036.   out-bag-id will contain the transformed input text (text_out).  If id
  1037.     is -1, the filter output is ignored (unless insert-output-at-dot is
  1038.     TRUE).  Useful when the filter creates its own files (such as
  1039.     uudecode or uncompress).
  1040.   If insert-output-at-dot is TRUE, the output of the filter is also
  1041.     inserted into the current buffer at the dot.  The insertion is done
  1042.     by file-to-buffer, so the dot is left after the insert, marks before.
  1043.  
  1044.   OS-filter uses up to 2 files to hold the input and output of the
  1045.       filter.
  1046.     On UNIX, these are put in /tmp.  On other systems, they are put in
  1047.     the current directory.  You can change the directory with a
  1048.     environment variable.
  1049.       UNIX : $TMP is used to hold the directory.  eg /v0/users/craig
  1050.         Note that ME adds a trailing "/" to the name.
  1051.       MS-DOS :  TMP is used.  If you have a RAM disk configured as drive
  1052.     D and want the files put in the root:
  1053.     SET TMP=D:
  1054.         Note that ME adds a trailing "/" to the name.
  1055.   See also:  OS-command, OS-shell.
  1056. (OS-shell [flags])                     [[NUMBER]] : BOOLEAN]
  1057.   Fork a shell.  ME waits until the shell exits and then resumes the
  1058.     editing session.
  1059.   Flags:  Implementation dependent.
  1060.     On Unix, flags == 1 means use job control and put ME into the
  1061.       background.
  1062.   See also:  OS-command, OS-filter.
  1063.  
  1064. (pgm-exists program-name)                [STRING : BOOLEAN]
  1065.   Returns TRUE if there is a program named program-name.  Can be used to
  1066.     check if a code file has been loaded (the program is defined in the
  1067.     file).
  1068.   For example:
  1069.     (if (pgm-exists "c-mode-hook") (c-mode-hook))
  1070.     or 
  1071.     (if (pgm-exists "c-mode-hook") (floc "c-mode-hook"()))
  1072.       This second example avoids the possibility of c-mode-hook being
  1073.       hard linked (ie it can be late bound).  Not needed in most cases.
  1074. (popup-buffer buffer-id [row column]) bstats.mut
  1075.     [NUMBER [NUMBER NUMBER] : NUMBER]
  1076.   Display a buffer in another window, creating a window if need be.
  1077.   If the buffer is already in a window, nothing is done.
  1078.   Input:
  1079.     buffer-id : id of the buffer to be displayed
  1080.     Optional:
  1081.       row : row to put the dot on.
  1082.       column : column to put the dot at.
  1083.       If row and column not passed in, dot is not moved.
  1084.   Output:
  1085.     Id of the window that is showing the buffer.
  1086. (prefix-key n [new-prefix])            [NUMBER [STRING] : STRING]
  1087.   Get or set the nth prefix key.  Returns the prefix keycode in ASCII
  1088.     form.
  1089.   n  Notes
  1090.   -  -----
  1091.   0  The META prefix.  Default is C-[ (ESCAPE).
  1092.   1  Default is C-X.
  1093.   2  open
  1094.   3  open
  1095.   META is a prefix so it can be overloaded (mimiced by) another key.
  1096.     A consequence of this is you cannot prefix a METAed key when a META
  1097.     key is a prefix.  For example, C-XM-P is OK but M-XM-P is not.
  1098.   If you have a real META key, you can turn off prefix key 0.
  1099.   Prefix keys 2 and 3 are open - use them for anything you like.
  1100.   To turn off a prefix key, set it to "S-" or some other impossible
  1101.     keycode (like "S-0").
  1102. (prepend-to-bag <numbers>)                    basic.mut
  1103.   Same as append-to-bag except the text is prepended instead of appended.
  1104. (prime-ask [text])                    [[stuff] : STRING]
  1105.   (prime-ask) Reset the prime.
  1106.   (prime-ask text)
  1107.     All the args are concatenated and the result is used as the first
  1108.       user input during the next ask or complete (if they query the
  1109.       user) - it is as if the user types in the text.  For example:
  1110.         (prime-ask "This " "is a" " test")
  1111.     (ask "Yes: ")
  1112.       When run, the user will see:
  1113.         Yes: This is a test
  1114.       If Return is pressed, ask will return "This is a test".
  1115.   Notes:
  1116.     Since the prime is not reset until an ask actually queries the user,
  1117.       you want to reset it after you call ask (with (prime-ask)).  Using
  1118.       the example above, if the (ask) got the answer from the arg list
  1119.       (ie it didn't have to query the user), the prime is not reset and
  1120.       will be used at the next (unknown) ask (unless it is overwritten).
  1121.   See also: complete, ask.
  1122. (puts string)                    [STRINGs|NUMBERs : STRING]
  1123.   Send a string to the terminal.  ME does not see this - (update) won't
  1124.     remove text unless the screen is marked as garbage.
  1125.   Useful for sending escape sequences to the terminal (eg defining
  1126.     function keys), creating popup windows or just doodling on the
  1127.     screen.
  1128.   See also: move-cursor, insert-text, msg, popup.mut
  1129.  
  1130. (re-search-forward regular-expression-search-pattern)    [STRING : BOOLEAN]
  1131.   Search from the dot forward for text that matches the regular
  1132.     expression.  If a match is found, the dot is left after the last
  1133.     matched character.
  1134.   Returns TRUE if a match is found.
  1135.   See also:  re-search-reverse, search-forward, search.mut, regexp.doc.
  1136. (re-search-replace search-pattern replace-pattern)
  1137.                          [STRING STRING : BOOLEAN]
  1138.   Search for (from the dot to the end of the buffer) and replace every
  1139.     occurrence of search-pattern with replace-pattern.  re-search-forward
  1140.     is used to search and get-matched is called at every match to create
  1141.     the replacement text.
  1142.   If re-search-replace is successful, the dot is unmoved and the mark is
  1143.     left after the last replace.  If it fails, the mark is at the start
  1144.     of the search and the dot is left where the failure occurred.
  1145.   Returns TRUE if at least one replace was done, FALSE if search-pattern
  1146.     was not found.
  1147.   See also:  search-replace, qr.mut, re-search-forward, get-matched,
  1148.     regexp.doc.
  1149. (re-search-reverse regular-expression-search-pattern)    [STRING : BOOLEAN]
  1150.   Search from the dot backwards (towards the start of the buffer) for
  1151.     text that matches the regular expression.  If a match is found, the
  1152.     dot is left before the first matched character (ie the cursor is on
  1153.     the first matched character.
  1154.   The match algorithm is:
  1155.     - Backup a character.
  1156.     - Does the RE match the characters after the dot (remember the dot
  1157.     is between two characters).  This is the same as (looking-at
  1158.     search-pattern).
  1159.       Yes:  done, leave the dot where it is.
  1160.       No:  repeat until a match is found or run into the start of the
  1161.     buffer.
  1162.   Returns TRUE if a match is found.
  1163.   See also:  re-search-forward, search-reverse, search.mut, regexp.doc.
  1164. (re-string RE-pattern string)             [STRING STRING : BOOLEAN]
  1165.   Test to see if a string matches a regular expression.
  1166.   Returns TRUE if it does.
  1167.   You can retrieve the matched info with get-matched.
  1168.   See regexp.doc for syntax of the pattern string.
  1169.   See also: get-matched, looking-at.
  1170. (read-clock data)                        [BLOB : VOID]
  1171.   Read the time and date and put them in a structure.
  1172.     (small-int month day year hh mm ss)    ;; TimeInfo
  1173.     (read-clock (floc month))
  1174.   See also:  date.mut for lots of routines that manipulate this data.
  1175. (region-stats pointer-to-data [mark1 [mark2 [goto-top-mark]]])
  1176.                 [BLOB [NUMBER [NUMBER [BOOLEAN]]] : VOID]
  1177.   Get stats on the region.  pointer-to-data is a pointer the data area
  1178.     that the stats are put into:
  1179.     (byte type) (small-int ulcol width height) (int size)  ;; RegionInfo
  1180.       type:  1 (dot on same line as mark), 2 (dot above mark), 3 (dot
  1181.     below mark).  This is the same info as (compare-dot-and-mark).
  1182.       ulcol: upper left column of the region-rectangle.
  1183.       width, height:  of the region-rectangle.
  1184.       size: Number of characters in the region.
  1185.     Mark1 and mark2 default to the dot (0) and the mark (1).
  1186.     If goto-top-mark is TRUE, the dot is moved to the upper left corner
  1187.       of the region.  Default is FALSE.
  1188.   For example:
  1189.     get-region-stats
  1190.     {
  1191.       (byte type)(small-int ulcol width height)(int size)  ;; RegionInfo
  1192.  
  1193.       (region-stats (loc type))
  1194.       (msg
  1195.     (switch type
  1196.       1 "Dot and mark on same line."
  1197.       2 "Dot above mark."
  1198.       3 "Dot below mark."
  1199.     )
  1200.     " Upper left column:" ulcol
  1201.     " Width:" width " Height:" height " Size:" size
  1202.       )
  1203.     })
  1204.   See also: compare-marks.
  1205. (require Mutt-module Mutt-code-file) require.mut    [STRING STRING : zip]
  1206.   Lisp like require.  This routine lets Mutt programs require that
  1207.     certain modules or routines be loaded.
  1208.   For example:  If MAIN contains (require "foo" "bar.mut") or (require
  1209.     "foo" "bar")), when your program is loaded it will load foo.mco if
  1210.     it hasn't been already or routine foo is not present.
  1211.   See also:  require.mut for better docuemtation.
  1212. (run-pgm-on-block pointer-to-code [args]) runblock.mut    [BLOB : SOMETHING]
  1213.   Run code on each line of a block.  Any args are passed to code.  Code
  1214.     should NOT delete or add lines and shouldn't move off the current
  1215.     line.
  1216.   See also: runblock.mut.
  1217.  
  1218. (save-excursion code [args])    basic.mut      [defun pointer [any] : any]
  1219.   Save the current point and buffer, calls code (passing it all the
  1220.     args) then restores the buffer and point and returns what code
  1221.     returned.
  1222.   See also:  save-point for examples.
  1223. (save-point code [args])    basic.mut      [defun pointer [any] : any]
  1224.   This routine saves the current point, calls code (passing it all the
  1225.     args) then restores the point and returns what code returned.
  1226.   For example:
  1227.     1> (defun to-the-moon (bool up)
  1228.          { (if up (beginning-of-buffer)(end-of-buffer)) })
  1229.     2> (msg (save-point (floc to-the-moon) FALSE))
  1230.     When the code at 2> is run, the call (to-the-moon FALSE) is made.
  1231.       to-the-moon moves the point to the end of the buffer and returns
  1232.       TRUE and returns to save-point.  save-point then moves the point
  1233.       back to where it was (before to-the-moon was called) and returns
  1234.       TRUE.
  1235.   The same example using anon defuns:
  1236.     2> (msg (save-point
  1237.      {{ (if (arg 0) (beginning-of-buffer)(end-of-buffer)) }} FALSE))
  1238.     Note that this is bit more cryptic because you have to use the
  1239.     (arg n) notation for passed in arguments.
  1240.   Notes:
  1241.     When using anon defuns, it can get very confusing because the anon
  1242.       routine can't access the variables of the enclosing defun.  You
  1243.       have to remember to pass in the variable and access them via (arg).
  1244.   See also:  save-excursion.
  1245. (scroll-window window-id n [z])        [NUMBER NUMBER [NUMBER] : BOOLEAN]
  1246.   Move the text in a window.  window-id == -1 means move the current
  1247.     window.
  1248.   (scroll-window window-id n)
  1249.     Move the nth window up (or down) by n lines If the dot moves off the
  1250.       screen, it is left at the edge closest to where it moved off.
  1251.   (scroll-window window-id dummy n)
  1252.     Reposition window dot to the nth line from the top (or bottom if n
  1253.       is negative) of the current window.  If n is 0, the window is
  1254.       centered.  Dummy is ignored.
  1255. (search-forward search-pattern)                [STRING : BOOLEAN]
  1256.   Search from the dot forward for text that matches search-pattern.  If
  1257.     a match is found, the dot is left after the last matched character.
  1258.   Returns TRUE if a match is found.
  1259.   See also:  search-reverse, re-search-forward, search.mut.
  1260. (search-replace search-pattern replace-pattern)
  1261.                          [STRING STRING : BOOLEAN]
  1262.   Search for (from the dot to the end of the buffer) and replace every
  1263.     occurrence of search-pattern with replace-pattern.  search-forward is
  1264.     used to search for a match.  Matched text is replaced verbatim with
  1265.     replace-pattern.
  1266.   If search-replace is successful, the dot is unmoved and the mark is
  1267.     left after the last replace.  If it fails, the mark is at the start
  1268.     of the search and the dot is left where the failure occurred.
  1269.   Returns TRUE if at least one replace was done, FALSE if search-pattern
  1270.     was not found.
  1271.   See also: re-search-replace, qr.mut, search-forward.
  1272. (search-reverse search-pattern)                [STRING : BOOLEAN]
  1273.   Search from the dot backwards (towards the start of the buffer) for
  1274.     search-pattern.  If a match is found, the dot is left before the
  1275.     first matched character (ie the cursor is on the first matched
  1276.     character.
  1277.   The match algorithm is:
  1278.     - Backup a character.
  1279.     - Does search-pattern match the characters after the dot (remember
  1280.     the dot is between two characters).
  1281.       Yes:  done, leave the dot where it is.
  1282.       No:  repeat until a match is found or run into the start of the
  1283.     buffer.
  1284.   Returns TRUE if a match is found.
  1285.   See also:  re-search-forward, search-forward, search.mut, regexp.doc.
  1286. (set-mark [mark-id])                       [[NUMBER] : !!!???]
  1287.   Set a mark to match the dot.  The default is mark 1 (the mark).
  1288.   See also:  create-mark, goto-mark, swap-marks, markring.mut.
  1289. (split-window [window-id])                  [[NUMBER] : BOOLEAN]
  1290.   (split-window) same as (split-window -1)
  1291.   (split-window window-id)
  1292.     Split (in half) a window vertically (-1 means the current window).
  1293.       A window smaller than 3 lines can not be split.
  1294.     The new window is put after window-being-split.  This way, if
  1295.       splitting the current window, the current window always remains on
  1296.       top.
  1297.     This command trys to leave the two windows showing identical chunks of
  1298.       the buffer.  If the dot is not in the chunk, the redisplay code will
  1299.       recenter the dot.
  1300.   Returns:
  1301.     TRUE if everything went as expected.
  1302.     FALSE (and window not split) if window to small to split or not
  1303.       enough memory.
  1304.   See also:  window-length, windows.
  1305. (stop-ME level)                           [NUMBER : VOID]
  1306.   (stop-ME 0)
  1307.     Halt all running programs, turn off keyboard macros, etc.  This is
  1308.       the way to stop what ever is running, clean up and return the ME
  1309.       main loop.  stop-ME-hook will be called.
  1310.   (stop-ME 1)
  1311.     Close the display (which will cause leave-ME-hook to be called) and
  1312.       exit back to the OS.  No asking is done.  stop-ME-hook will be
  1313.       called.
  1314.   See also:  leave-ME-hook, stop-ME-hook.
  1315. (swap-marks [mark1-id mark2-id])        [[NUMBER NUMBER] : NUMBER]
  1316.   Exchange the locations that two marks point to.  If you (swap-marks 0
  1317.     1) (the default case, same as (swap-marks)), the dot will move to
  1318.     where the mark was and vice versa.  Doing it again will return the
  1319.     marks to their original values ie (swap-mark a b)(swap-mark a b) is
  1320.     a no op.  If you are moving the dot, the other mark must be valid
  1321.     (ie have been set).  Remember that clear-buffer resets all marks
  1322.     (except the dot).  If you do this, your program will die but ME will
  1323.     be OK.
  1324.   See also: goto-mark
  1325. (sysvar sysvar-name [value])            [STRING [NUMBER] : NUMBER]
  1326.   Access or set a sysvar.  This enables a program to give the user
  1327.     access to sysvars.
  1328.   Example:
  1329.     (string sysvar-name 50)(sysvar-name "HELP")
  1330.     (sysvar sysvar-name) gets the current value of HELP and 
  1331.     (sysvar sysvar-name 0) sets it to zero.
  1332.   See also: sysvar.mut for coding examples.
  1333.  
  1334. (to-col column)                         [NUMBER : NUMBER]
  1335.   Insert space until the dot is at column.  If the dot is at or past
  1336.     column, nothing happens.
  1337.   Returns column.
  1338.   If the sysvar tab-stops is zero then tabs and blanks are used,
  1339.     otherwise only blanks are used as space.
  1340.  
  1341. (update)                               [ : VOID]
  1342. (update update-the-screen)                [BOOLEAN : VOID]
  1343. (update update-the-screen screen-is-garbage)    [BOOLEAN BOOLEAN : VOID]
  1344.   (update) or if update-the-screen is TRUE, the areas of the screen that
  1345.     are out of date are redrawn.  Does not affect the minibuffer.
  1346.     Different from (refresh-screen) in that the refresh occurs now,
  1347.     rather than waiting for the program to end.
  1348.   If update-the-screen is FALSE, just sync the buffer and window.
  1349.   Forces the current window dot to match the current buffer dot IF the
  1350.     current window is displaying the current buffer.
  1351.   If screen-is-garbage is TRUE, the screen is marked as garbage and is
  1352.     the entire screen is cleared and redrawn (if update-the-screen is
  1353.     FALSE this will happen later).  This also clears the minibuffer.
  1354.   Notes:
  1355.     Keys in the typeahead buffer will keep the refresh from completing
  1356.       (ME will finish up later when it has more time).
  1357.     Redrawing the screen can take a long time (from the computers point
  1358.       of view anyway).  If screen is up to date, this is quick (usually
  1359.       only the cursor is moved).
  1360.     It is important to realize that windows and buffers are independent.
  1361.       Changing a buffer does not mean that a window displaying the
  1362.       buffer always reflects those changes.  This is usually only a
  1363.       problem when a program wants a window displaying a buffer to track
  1364.       the changes the program is making to that buffer.  Here are the
  1365.       rules for programs:
  1366.         - Windows and buffers have their own dots.  Changes to a buffer
  1367.       dot does not change the window dot.
  1368.     - If you make changes to a buffer and then want to make changes
  1369.       to the window displaying that buffer, you usually want to do a
  1370.       (update FALSE) after the buffer changes and before the window
  1371.       changes.  If you don't do this, the window dot will be in a
  1372.       different place than the buffer dot and the window probably
  1373.       won't be showing what you expected.  Make sure the current
  1374.       window is displaying the buffer you are changing.
  1375.   See also: current-buffer, current-window.
  1376.  
  1377. (window-ledge [n [left-edge]])              [[NUMBER [NUMBER]] : NUMBER]
  1378.   (window-ledge)  Same as (window-ledge -1).
  1379.   (window-ledge n)
  1380.     Return the left edge of the nth window.  If n == -1, the current
  1381.       window is used.
  1382.   (window-ledge n left-edge)
  1383.     Set the left edge for the nth window and return the value.
  1384.   Notes:
  1385.     The window will display only the text starting at column left-edge.
  1386.     The first column is 0 (not 1 as it is for (current-column)).
  1387.     If horizontal-scroll is enabled and setting window-ledge causes the
  1388.       cursor to move off screen, the display routines will reset the
  1389.       left edge so that the cursor is on screen.  Turning off
  1390.       horizontal-scroll will prevent this, otherwise, you will need to
  1391.       move the cursor to a column in
  1392.       (left-edge, left-edge + screen-width].
  1393.     With this command you can scroll windows manually (ie without using
  1394.       the cursor).
  1395.     The current screen column can be calculated by:
  1396.       (- (current-column)(window-ledge -1))
  1397.   See also: horizontal-scroll.
  1398. (window-length [n [new-length]])           [[NUMBER [NUMBER]]: NUMBER]
  1399.   (window-length)  Same as (window-length -1)
  1400.   (window-length n)
  1401.     Return the length of the nth window (n == -1 means current window).
  1402.     Note that the length does not include the mode line.  If there is
  1403.       only one window then
  1404.       (window-length -1) == (window-length 0) == (- (screen-length) 1).
  1405.   (window-length n new-length)
  1406.     Resize the nth window to the new size (if there is more than one
  1407.       window and the new size won't cause the window to get too big or
  1408.       small).  The new window size is returned.
  1409. (window-row)                            [zip : NUMBER]
  1410.   Return the row the dot is on in the current window.  The top row of a
  1411.     window is 1.  Note that this is not the screen row (unless the
  1412.     current window is the top most one).
  1413.   Note:  It is the display routines that figure out the window-row.  If
  1414.     called when the display is out of sync (such as a program doing
  1415.     display manipulation) this could very well be incorrect.  (update)
  1416.     can force a display sync.
  1417.   Example:
  1418.       (defun move-dot-to-top-of-window
  1419.     {
  1420.       (forward-line (- 1 (window-row)))
  1421.     })
  1422. (windows)                            [zip : NUMBER]
  1423.   Return the number of windows on the screen.  Windows are numbered 0 ..
  1424.     (- (windows) 1).
  1425.   See also: current-window.
  1426.  
  1427. (yesno prompt)            [STRINGs|NUMBERs|BOOLEANs|VOIDs : BOOLEAN]
  1428.   Show the prompt (with " [y/n]? " appended) and wait for [Y, y, N, or n]
  1429.     CR to be typed.  Returns TRUE on Y or y.  The program aborts on ^G.
  1430.     Simular to (ask).
  1431.   Notes:
  1432.     If not interactive (ie the user is not asked), only "y" or "Y" will
  1433.       return TRUE.
  1434.     Use (ask-user) to force user prompting.
  1435.     See (ask) for potential problems.
  1436.  
  1437. ========================================================================
  1438. ==        SYSTEM VARIABLES (sysvars)                  ==
  1439. ========================================================================
  1440. System vars are used like any other var - (sysvar) returns its value and
  1441.   (sysvar value) sets it to value.
  1442. Most sysvars are global - they effect all buffers, windows, etc.  Some
  1443.   sysvars are buffer local - they only effect a single buffer.  When you
  1444.   set a local sysvar, it is set for the current buffer.  If you want to set
  1445.   these to something other than the default for every buffer, do so in
  1446.   create-buffer-hook.
  1447. Unless otherwise noted, all sysvars are global.
  1448.  
  1449. (beep [volume])                           [[NUMBER] : NUMBER]
  1450.   (beep)
  1451.     Ring the bell at the current volume and return the current volume.
  1452.   (beep 0)
  1453.     Turn off the bell, ie set the volume to zero and return the current
  1454.       volume.
  1455.   (beep -1)
  1456.     Return the current volume.
  1457.   (beep volume)
  1458.     Set the bell volume and return the current it.  Currently, the only
  1459.      volume is on (non-zero) or off (0).
  1460.   Initial value: 1
  1461.  
  1462. (case-fold-search [ignore-case])               [[NUMBER] : NUMBER]
  1463.   Affects searching (query-replace, search-forward, search-reverse).
  1464.   If 1, case is ignored.
  1465.   Initial value: 1
  1466. (complete-key [keycode])                   [[NUMBER] : NUMBER]
  1467.   This is the keycode that controls command completion.
  1468.   It is initialized to space (32).
  1469.   (complete-key) returns the current value.
  1470.   To change it, use the keycode.  See get-key.
  1471.   For example:
  1472.     To set the complete key to tab (C-I), use (complete-key 0x149) or
  1473.       (complete-key 329).
  1474.     For space, use (complete-key 32).
  1475.     For control A (C-A), use (complete-key 321).
  1476.  
  1477. (HELP [help-level])    Set the help level           [[NUMBER] : NUMBER]
  1478.   (HELP) returns the current setting.
  1479.   (HELP n) sets the level to n and returns n.
  1480.   Help level:
  1481.     0 : no help
  1482.     1 : gimme help (if you make typo in (ME-command)
  1483.     (describe-bindings) will be executed).
  1484.   Initial value: 1
  1485. (horizontal-scroll [step-size])                   [[NUMBER] : NUMBER]
  1486.   This sysvar controls horizontal scrolling - moving text left and right
  1487.     on the screen.  If 0,  horizontal  scrolling is disabled,  otherwise
  1488.     the horizontal  scrolling rate is set to step-size.  When the screen
  1489.     has to scroll, it will move in chunks in order to reduce the  amount
  1490.     screen   thrashing.  Change  it  to  best  suit  your  hardware  and
  1491.     preferences.
  1492.   The range for step-size is [0 : screen-width).  If you set it outside
  1493.     of this range, you are asking for many unpleasant surprises.
  1494.   See also: window-ledge.
  1495.  
  1496. (modeline-color [color])                   [[STRING] : STRING]
  1497.   Change or get the the mode line color.
  1498.   The current color is returned.
  1499.   Note that the color values are display dependent.
  1500.   In general, the colors are specified as "foreground:background" where
  1501.     the foreground color is the color of the text and the background
  1502.     color is the color of the area the text is on.  For example,
  1503.     "green:black" would be green characters written on black paper.
  1504.   Parsing rules:
  1505.     "foreground:background" : Change both.  If one (or both) of the
  1506.       colors is invalid, it is not changed (but the other might be).
  1507.     "foreground"  : Just change the foreground color.
  1508.     "foreground:" : Just change the foreground color.
  1509.     ":background" : Just change the background color.  Might not work
  1510.       on Unix.
  1511.   For IBM PCs, the color choices are:
  1512.     Forground:  black, blue, green, cyan, red, magenta, brown,
  1513.       lightgrey, darkgrey, lightblue, lightgreen, lightcyan, lightred,
  1514.       magenta, yellow, white.
  1515.     Background:  black, blue, green, cyan, red, magenta, brown,
  1516.       lightgrey.
  1517.     These may not make sense for noncolor displays.
  1518.   For Unix system (or monochrome systems) the choices are white and
  1519.     black.  "black:white" is inverse video.  Only the foreground color
  1520.     is looked at.
  1521.   See also: text-color.
  1522.  
  1523. (overstrike [value])                       [[NUMBER] : NUMBER]
  1524.   Overstrike is the mode opposite of insert (the default mode).  Overstrike
  1525.     mode is very much a bag on the side of ME and ment only for occasional
  1526.     use.
  1527.   The following are different in overstrike mode:
  1528.     - The tab key is disabled but you can still set the tab stops.
  1529.     - <CR> sends you the start of the next line.
  1530.     - Backspace is the same as backward-character.
  1531.     - The mode line.
  1532.     - self-insert don't, they overstrike.
  1533.   Initial value: 0
  1534.  
  1535. (screen-length [new-screen-length])               [[NUMBER] : NUMBER]
  1536.   Change the size of the physical screen.  This allows the same ME code
  1537.     to run on different size screens.
  1538.   For example, say ME came  configured  for a HP150 (which has 24 screen
  1539.     lines) and you wanted to run it on a HP110 (which has 16 lines).  To
  1540.     change  the   screen   size:  (screen-length   16).
  1541.   Range: [3 : 400].  If you change this to be longer that the screen
  1542.     really is, it is hard to edit.
  1543.   See also: errata file.
  1544. (screen-width [new-screen-width])               [[NUMBER] : NUMBER]
  1545.   Change the physical screen width.
  1546.   Range: [15 : 500]
  1547.  
  1548. (tab-stops [tab-size])    Local                   [[NUMBER] : NUMBER]
  1549.   If given an argument then set the tab stops to every nth column.  This
  1550.   is a buffer local variable.
  1551.     If n == 0 use the tab character.
  1552.     If n  > 1 use spaces to simulate the tab character.
  1553.   Initial value: 0
  1554. (text-color [color])                       [[STRING] : STRING]
  1555.   Change or get the the text color.
  1556.   The current color is returned.
  1557.   Note that the color values are display dependent.
  1558.   See also: modeline-color for color values.
  1559.  
  1560. (word-wrap [wrap-column])    Local               [[NUMBER] : NUMBER]
  1561.   Setting word-wrap > 0 turns it on, 0 turns it off.
  1562.   Initial value: 0
  1563.   When ME decides it is time to word wrap, it does a (exe-key "^M")
  1564.     which executes whatever is bound to the Enter key.  This also
  1565.     provides a hook if your program wants to do something at that time.
  1566.   This is a buffer local variable.
  1567.  
  1568. ========================================================================
  1569. ==        Hooks                              ==
  1570. ========================================================================
  1571.  
  1572.    Hooks are Mutt programs that are called by ME when it thinks somebody
  1573. else might be interested in what its about to do.  They allow the Mutt
  1574. programmer to modify ME's behavior.  If a hook is not defined, it is not
  1575. called (ie ME doesn't really care if you don't want to tell it what to
  1576. do).
  1577.  
  1578. Notes:
  1579.   There may be more than one routine that is sharing the hook call.  See
  1580.     the hook support in hook.mut (documented in package.doc).  If you
  1581.     want your code to be a "good citizen" and interact "nicely" with
  1582.     other Mutt code (that uses hooks), it is important that you use
  1583.     (register-hook) and DON'T define a routine that takes over the hook
  1584.     (ie don't defun create-buffer-hook).  key-pressed-hook is the
  1585.     exception.  me.mh has the constants used by register-hook.
  1586.   In general, if you switch buffers, you should switch back so that
  1587.     other routines sharing this hook will have the correct current
  1588.     buffer when they are called.
  1589.   Some hook names are in all upper case (for example,
  1590.     ICLEAR-BUFFER-HOOK).  This means the hook is not called from within
  1591.     ME but is called from hook.mut and can only be accessed though
  1592.     (register-hook).  Otherwise it acts like any other hook.
  1593.   If a hook name starts with an "I", it means the hook is called for
  1594.     interactive buffers.  The hook that doesn't have the leading "I" is
  1595.     called first (for all buffers) and then the interactive hook is
  1596.     called if the buffer is marked interactive.  Interactive buffers are
  1597.     those buffers ment for human interaction.  See buffer-flags and
  1598.     create-buffer for what makes a buffer interactive.
  1599.  
  1600. For examples of how hooks are used, see hook.mut and alamode.mut.
  1601.  
  1602. (clear-buffer-hook)                           [zip : zip]
  1603.   This is called when a buffer is cleared.  It is NOT called if
  1604.     (free-buffer-hook) is being called for the same buffer.  That is,
  1605.     free-buffer calls clear-buffer but in that case, clear-buffer-hook
  1606.     won't be called.  Use free-buffer-hook in that case.
  1607.   Register with
  1608.       (register-hook CLEAR-BUFFER-HOOK name-of-your-routine).
  1609.   See also: ICLEAR-BUFFER-HOOK.
  1610. (COMMAND-LINE-HOOK command-line-arg)            [STRING : BOOLEAN]
  1611.   Called when a command line argument needs to be processed by somebody.
  1612.   Return:  TRUE if you process it, else FALSE.
  1613.   See also:  cmdline.mut in package.doc.
  1614. (create-buffer-hook)                           [zip : zip]
  1615.   This is called when a buffer is created and allows a Mutt program to
  1616.     set up a buffer.
  1617.   Register with
  1618.       (register-hook CREATE-BUFFER-HOOK name-of-your-routine).
  1619.   BUGS:
  1620.     Does not get called for "*scratch*" (the default buffer created when
  1621.       ME starts up) because it is created before any Mutt code is loaded
  1622.       or run.
  1623.     If you want it called for *scratch* then put (create-buffer-hook)
  1624.       into the load time code of myme.mut.  Note that if you delete
  1625.       *scratch* in the MAIN of myme.mut then you will not need to do this
  1626.       because *scratch* will be recreated if no other buffers exist.
  1627.       Also, if you read in a files, create-buffer-hook will be called.
  1628.   See also:  create-buffer, ICREATE-BUFFER-HOOK.
  1629.  
  1630. (enter-ME-hook)                               [zip : zip]
  1631.   When ME starts up and opens the display, it calls this hook.  For
  1632.     example, (OS-command) calls this after the shell command is run and
  1633.     returns control to ME.
  1634.   Note:
  1635.     This is not called when ME is first run because it would be called
  1636.       before any Mutt programs were loaded.  If you need that
  1637.       functionality, do it with MAIN routines.
  1638.     Register with (register-hook ENTER-ME-HOOK name-of-your-routine).
  1639.   See also: leave-ME-hook.
  1640.  
  1641. (free-buffer-hook)                           [zip : zip]
  1642.   This is called when a buffer is freed.
  1643.   Register with
  1644.       (register-hook FREE-BUFFER-HOOK name-of-your-routine).
  1645.   See also: IFREE-BUFFER-HOOK.
  1646.  
  1647. (ICLEAR-BUFFER-HOOK)                           [zip : zip]
  1648.   This is the clear-buffer-hook for interactive buffers.
  1649.     clear-buffer-hook is called for all buffers, ICLEAR-BUFFER-HOOK is
  1650.     only called for interactive buffers.
  1651.   Register with
  1652.       (register-hook ICLEAR-BUFFER-HOOK name-of-your-routine).
  1653.   See also: clear-buffer-hook.
  1654. (ICREATE-BUFFER-HOOK)                           [zip : zip]
  1655.   This is called when a interactive buffer is created and allows a Mutt
  1656.     program to set up a buffer.  Interactive buffers are those buffers
  1657.     ment for human interaction.  Since most Mutt buffer-created code
  1658.     only cares about interactive buffers (why set a buffer mode if
  1659.     nobody will ever use it?) and lots of non-interactive buffers are
  1660.     created, using this hook will reduce work ME has to do (and a few
  1661.     other things that I'm having a hard time explaining).
  1662.   Register with
  1663.       (register-hook ICREATE-BUFFER-HOOK name-of-your-routine).
  1664.   See also:  buffer-flags, create-buffer-hook, IREAD-BUFFER-HOOK,
  1665.     hook.mut.
  1666. (idle-hook ticks-since-not-idle)                [NUMBER : ZIP]
  1667.   This hook is called every tick while ME thinks it is idle.  During
  1668.     each idle "session", the ticks accumulate.  ie the first call is
  1669.     (idle-hook 1), the next is (idle-hook 2), etc while nothing is
  1670.     happening.  If something happens, the tick is reset.
  1671.   Notes:
  1672.     A tick is about one second - it can vary from machine to machine,
  1673.       even during the idle "session".
  1674.     "Nothing happening" means ME is waiting for a keypress, but not in a
  1675.     (ask).
  1676. (IFREE-BUFFER-HOOK)                           [zip : zip]
  1677.   This is the free-buffer-hook for interactive buffers.
  1678.   Register with
  1679.       (register-hook IFREE-BUFFER-HOOK name-of-your-routine).
  1680.   See also: free-buffer-hook.
  1681. (IREAD-FILE-HOOK)                           [zip : zip]
  1682.   This hook is called after a file has been read into the current
  1683.     buffer and the current buffer is interactive.
  1684.   The dot is at the beginning of the buffer.
  1685.   Register with (register-hook IREAD-FILE-HOOK name-of-your-routine).
  1686.   See also:  read-file-hook, ICREATE-BUFFER-HOOK, hook.mut.
  1687.  
  1688. (key-pressed-hook key)                        [NUMBER : zip]
  1689.   This is called when the user presses a key in the main loop (ie
  1690.     key-pressed-hook is not called from the following:  get-key,
  1691.     exe-key, anything that queries the user in the mini buffer).  The
  1692.     key is passed to the hook.  See get-key for the format of a key.
  1693.     After the hook has finished, the key is executed.
  1694.   Notes:
  1695.     This hook is not supported by register-hook.  It really slows things
  1696.       down to do so and is not used much.
  1697.   For example:
  1698.     If the user presses "a", (key-pressed-hook 0x61) is called and then
  1699.       "a" is inserted.
  1700.     Pressing ^X^F causes (key-pressed-hook 0x546) to be called.  After
  1701.       the hook returns, visit-file is called.  Any keys pressed while in
  1702.       visit-file will NOT trigger the hook.
  1703.   See also: key-pressed.
  1704.  
  1705. (leave-ME-hook)                               [zip : zip]
  1706.   Called when the display is being closed in preparation for leaving ME.
  1707.     This is when you quit ME or do something with a shell.
  1708.   Register with (register-hook LEAVE-ME-HOOK name-of-your-routine).
  1709.   See also: enter-ME-hook.
  1710.  
  1711. (modeline-hook)                            [zip : STRING]
  1712.   This hook is called when a window needs a new modeline.  Whatever the
  1713.     hook returns is put into the modeline.  The last character of the
  1714.     return value is repeated to the end of the modeline.
  1715.   For example:
  1716.     (defun modeline-hook
  1717.            { (concat "ME is editing " (buffer-name -1) " -") })
  1718.     If the current buffer is foo, then the modeline line will look like:
  1719.       "ME is editing foo --------------------------------------"
  1720.   Notes:
  1721.     The modelines for windows are not updated until ME thinks that the
  1722.       modeline needs to be updated.  A good way to do this for a buffer
  1723.       is:  (buffer-flags -1 Mode).
  1724.     The last character is repeated because it makes life easier on the
  1725.       hook (it doesn't have to know about the physical display).
  1726.     Not supported by register-hook.  It doesn't make sense to chain this
  1727.       hook.  If you need to have your own modeline for a buffer, do it
  1728.       with a buffer variable (see modeline.mut).  If you don't like the
  1729.       modeline format, change modeline.mut.
  1730.   See also: modeline.mut for examples.
  1731.  
  1732. (overstrike-toggle-hook)                [ZIP : ZIP]
  1733.   If the value of (overstrike) changes, this hook is called.
  1734.   This hook is not handled by (register-hook).
  1735.   See also: overstrike.
  1736.  
  1737. (process-hook pid OUTPUT-STDOUT text)              [NUMBER 1 STRING : ]
  1738. (process-hook pid OUTPUT-STDERR text)              [NUMBER 2 STRING : ]
  1739. (process-hook pid PROCESS-DONE  exit-status)          [NUMBER 0 NUMBER : ]
  1740. (process-hook pid ERROR        error-code)          [NUMBER 3 NUMBER : ]
  1741.     where PROCESS-DONE == 0, OUTPUT-STDOUT == 1, OUTPUT-STDERR == 2,
  1742.       ERROR == 3.
  1743.   This hook is used by external processes (created by create-process)
  1744.     talk to Mutt programs.
  1745.   Since multiple processes can be running, you need to use the hook
  1746.     management facilities in hook.mut so that other Mutt programs can
  1747.     manage their own processes.
  1748.   Remember the id of the process you create so that you can tell if the
  1749.     hook is for you.
  1750.   ERROR codes are:
  1751.     CS_ERROR_SERVER_DIED 0
  1752.       For some reason, the compute server is going to stop running very
  1753.         soon.
  1754.     CS_ERROR_PROTOCOL     1
  1755.       ME sent garbage to the compute server.
  1756.     CS_ERROR_READ     2
  1757.       ME read garbage from the compute server.
  1758.     All these errors result in all processes terminating, not just
  1759.       yours.  You will have to start over and recreate them.  If you see
  1760.         an ERROR event,  ignore the pid and treat handle the error
  1761.     because this is the last event your pid will get (until it is
  1762.     recreated).
  1763.   Register with (register-hook PROCESS-HOOK name-of-your-routine).
  1764.   See also:  create-process, hook.mut, compile.mut, comserver.doc.
  1765.  
  1766. (read-file-hook)                           [zip : zip]
  1767.   This hook is called after a file has been read into the current
  1768.     buffer.
  1769.   The dot is at the beginning of the buffer.
  1770.   Register with (register-hook READ-FILE-HOOK name-of-your-routine).
  1771.   See also:  IREAD-FILE-HOOK, visit-file and read-file (in me3.doc).
  1772.  
  1773. (start-ME-up)
  1774.   Called just before ME starts up it main loop.  This allows your
  1775.     built in programs to initialize themselves with MAIN routines, ME to
  1776.     call programs after they have been initialized (for example,
  1777.     version-hook) and then finish up getting ready to go (for example,
  1778.     process the command line).
  1779. (stop-ME-hook n)                        [NUMBER : zip]
  1780.   This hook is called when (stop-ME x) is called.
  1781.   (stop-ME 0) causes (stop-ME-hook 0).
  1782.   (stop-ME 1) causes (stop-ME-hook 1).
  1783.   If ME is stopped by a (catchable) signal or some other externally
  1784.     caused shut down, (stop-ME-hook 2) is called.  If you catch this, be
  1785.     very careful - ME is in an unknown state.  Your program should do
  1786.     the minimum needed.  If it should terminate due to an error or call
  1787.     (stop-ME 0), ME might not exit.
  1788.   Note:  It is not called when a program is stopped because of an error.
  1789.   See also: stop-ME, leave-ME-hook.
  1790.  
  1791. (version-hook)                              [lots : zip]
  1792.   Called when ME starts up (but before start-ME-up is called) to pass
  1793.     versioning information to programs.
  1794.   Notes:
  1795.     This is called multiple times during startup as the various
  1796.       subcomponents send out version info.
  1797.  
  1798. ========================================================================
  1799. ==        Miscellaneous                          ==
  1800. ========================================================================
  1801.  
  1802.