home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / util / edit / jade / man / jade.info-3 < prev    next >
Encoding:
GNU Info File  |  1994-10-16  |  49.3 KB  |  1,518 lines
  1. This is Info file jade.info, produced by Makeinfo-1.55 from the input
  2. file jade.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Jade: (jade).            An editor for X11 and AmigaDOS
  6. END-INFO-DIR-ENTRY
  7.  
  8.    This is Edition 1.3, last updated 7 October 1994, of `The Jade
  9. Manual', for Jade, Version 3.2.
  10.  
  11.    Jade is a text editor for X11 (on Unix) and the Amiga.
  12.  
  13.    Copyright 1993, 1994 John Harper.
  14.  
  15.    Permission is granted to make and distribute verbatim copies of this
  16. manual provided the copyright notice and this permission notice are
  17. preserved on all copies.
  18.  
  19.    Permission is granted to copy and distribute modified versions of
  20. this manual under the conditions for verbatim copying, provided that
  21. the entire resulting derived work is distributed under the terms of a
  22. permission notice identical to this one.
  23.  
  24. 
  25. File: jade.info,  Node: Using Marks,  Next: Interrupting Jade,  Prev: Using the Prompt,  Up: Using Jade
  26.  
  27. Using Marks
  28. ===========
  29.  
  30.    Marks are used to record a position in a file, as the file's buffer
  31. is modified so does the position that the mark points to -- a mark will
  32. keep pointing at the same character no matter what happens (unless the
  33. character is deleted!).
  34.  
  35.    The other good thing about marks is that they point to files *not*
  36. buffers. This means that you can set a mark in a buffer, delete the
  37. buffer and then move to the position of the mark, the file will be
  38. reloaded and the cursor will point at the original character.
  39.  
  40.    Normally there are three user-accessible marks (1) and one special
  41. `auto-mark' which is used, amongst other things, to record the
  42. "previous" position of the cursor, allowing you to retrace your last
  43. major step.
  44.  
  45.    The commands available on marks are,
  46.  
  47. `F1'
  48. `F2'
  49. `F3'
  50.      Move to the mark #1, #2 or #3, depending on which function key is
  51.      pressed (F1 means mark #1, etc...). If the file pointed to is not
  52.      in memory it will be loaded into a new buffer.
  53.  
  54. `Shift-F1'
  55. `Shift-F2'
  56. `Shift-F3'
  57.      Set the position of mark #1, #2 or #3, depending on the function
  58.      key.
  59.  
  60. `Ctrl-x Ctrl-x'
  61.      Swap the positions of the cursor and the `auto-mark'.
  62.  
  63. `Ctrl-@'
  64.      Set the position of the `auto-mark'.
  65.  
  66.    ---------- Footnotes ----------
  67.  
  68.    (1)  There is no reason why you can't have more, the editor sets no
  69. limitation on the number of marks available. This is just how I have
  70. set the editor up.
  71.  
  72. 
  73. File: jade.info,  Node: Interrupting Jade,  Next: Recursive Editing,  Prev: Using Marks,  Up: Using Jade
  74.  
  75. Interrupting Jade
  76. =================
  77.  
  78.    It is often useful to be able to tell Jade to quit whatever it is
  79. doing and wait for more commands; this is called "interrupting" Jade.
  80. When the editor receives an interrupt signal it will abort what it is
  81. doing and rewind itself back to the inner-most recursive edit (see
  82. *note Recursive Editing::.).
  83.  
  84.    The interrupt signal differs with the operating system being used,
  85.  
  86.    * Under Unix the `SIGINT' signal is used, this can be sent via the
  87.      `intr' character (get the editor into the foreground of the shell
  88.      it was started from and type `Ctrl-c' in the shell's terminal), or
  89.      directly through the `kill' shell command. For example, look at
  90.      the following shell session extract,
  91.  
  92.           /var/src/jade/man$ ps
  93.             PID TT STAT  TIME COMMAND
  94.              60  1 SW    0:02 (xinit)
  95.              87  1 S     0:08 fvwm
  96.             127 p0 S     0:00 /bin/bash
  97.             155 p0 S     0:04 jade
  98.             156 p1 S     0:00 /bin/bash
  99.             159 p1 R     0:00 ps
  100.           /var/src/jade/man$ kill -INT 155
  101.  
  102.      First the `ps' command is used to find the Jade process' pid (155),
  103.      then the `kill' command is used to send the `INT' signal to this
  104.      process.
  105.  
  106.    * The `Ctrl-c' signal is also used on Amigas, either type this in
  107.      the console window that Jade was launched from or use the `break'
  108.      (or possibly `breaktask') command to send the signal.
  109.  
  110. 
  111. File: jade.info,  Node: Recursive Editing,  Next: Character Images,  Prev: Interrupting Jade,  Up: Using Jade
  112.  
  113. Recursive Editing
  114. =================
  115.  
  116.    Recursive editing is the act of editing a file while the current
  117. command is still being evaluated. For example, when using the
  118. `query-replace' command (`Meta-%') the `Ctrl-r' command enters a
  119. recursive edit to let you edit the buffer, even though you are still
  120. doing a query-replace (which will be resumed when the recursive edit
  121. finishes).
  122.  
  123.    As the name suggests a recursive edit calls the editor's main command
  124. loop recursively from within a command. Any number of recursive edits
  125. may be stacked up and then unwound back to the top-level of the editor.
  126.  
  127.    When a recursive edit is in progress the name of the mode being used
  128. to edit the buffer is shown in *square brackets*, not parentheses as in
  129. the top-level instance.
  130.  
  131.    The commands for manipulating recursive edits are as follows,
  132.  
  133. `Ctrl-]'
  134. `Ctrl-Meta-c'
  135.      Exit the innermost recursive edit, this has no effect at the
  136.      top-level.
  137.  
  138. `Meta-x top-level'
  139.      Return to the outermost edit -- the top-level. This is useful when
  140.      you get "lost" inside a sequence of recursive edits.
  141.  
  142. `Meta-x recursive-edit'
  143.      Enter a new recursive edit; this command is usually best avoided to
  144.      save confusion.
  145.  
  146.    In general, recursive editing is rarely used except in unavoidable
  147. circumstances (i.e. in the Lisp debugger).
  148.  
  149. 
  150. File: jade.info,  Node: Character Images,  Next: Client Editing,  Prev: Recursive Editing,  Up: Using Jade
  151.  
  152. Character Images
  153. ================
  154.  
  155.    In general any character can be mapped to any sequence of up to four
  156. character sized images (called glyphs) when it is drawn into a window.
  157. The TAB character is a notable exception; it expands to as many spaces
  158. as are needed to fill up to the next tab stop.
  159.  
  160.    By default, the editor is set up to display the following,
  161.  
  162. 0 to 31
  163.      A caret (`^') followed by the ASCII value of the character
  164.      exclusive-or'd with 0x40, i.e. `^@' to `^_'.
  165.  
  166. 32 to 126
  167.      Printed literally, this includes all "normal" characters and
  168.      punctuation.
  169.  
  170. 127
  171.      `^?'
  172.  
  173. 128 to 255
  174.      Represented by the octal escape sequence (i.e. `\200') for that
  175.      character's numeric value.
  176.  
  177.    If you want to edit files containing characters in the `Latin1'
  178. character set (numerically, from 160 to 255) you can put the following
  179. in your `.jaderc' file,
  180.  
  181.      (latin-1-mode)
  182.  
  183. this will redefine the necessary characters.
  184.  
  185.    If you want more details about this sort of thing see *Note Glyph
  186. Tables::.
  187.  
  188. 
  189. File: jade.info,  Node: Client Editing,  Next: Compiling Programs,  Prev: Character Images,  Up: Using Jade
  190.  
  191. Client Editing
  192. ==============
  193.  
  194.    Normally you will only have one instance of Jade executing at a
  195. single time. Often though, another program will want you to edit a
  196. file, for example when you are composing a mail message. There is
  197. normally a way to specify which editor you want to use, for example the
  198. `EDITOR' environment variable.
  199.  
  200.    If you were to ask to edit the file in `jade' an *additional*
  201. process executing Jade would be started, totally separate from the
  202. original. It is possible to use the original instance.
  203.  
  204.    Firstly Jade must be set up to listen for clients wanting files
  205. edited, this is done with the `server-open' command. You can either put
  206. this in your `.jaderc' file (with a line like `(server-open)') or call
  207. it manually with the command `Meta-x server-open'.
  208.  
  209.    Only one instance of Jade may be a server at once. If you know that
  210. there is no other Jade running but it still won't let you open a
  211. server, and you are running on Unix, look for a dead socket called
  212. `~/.Jade_rendezvous' and delete it if necessary.
  213.  
  214.    Once the editor is listening for client messages the separate program
  215. `jadeclient' may be used to load files into the server from an external
  216. source. The format of `jadeclient' invocation is,
  217.  
  218.      jadeclient [+LINE-NUMBER] FILE-NAME ...
  219.  
  220. When invoked, it will ask the server to edit each FILE-NAME (initially
  221. positioned at line LINE-NUMBER) in turn, exiting only after each file
  222. has finished being edited.
  223.  
  224.    If when the `jadeclient' program is invoked their is no server open
  225. (i.e. either Jade is not running or you haven't used the `server-open'
  226. function) a message `Jade not running, waiting...' will be printed and
  227. `jadeclient' will sit waiting for you to open a Jade server.
  228.  
  229.    So, simply get the program you want to use Jade to use the
  230. `jadeclient' program as its editor. For example, I use `mh' to handle
  231. my electronic mail; in my `~/.mh_profile' file I have the line,
  232.  
  233.      Editor: jadeclient
  234.  
  235. to tell it that I want to edit my mail in Jade.
  236.  
  237.    The one special command for client/server editing is,
  238.  
  239. `Ctrl-x #'
  240.      If the file being edited in the current buffer is a client file,
  241.      tell the client program which loaded it that it has finished being
  242.      edited. The actual buffer is *not* deleted.
  243.  
  244.    It is also possible to finish editing a client file by simple
  245. deleting its buffer in the normal way (`Ctrl-x k'), *Note Deleting
  246. Buffers::.
  247.  
  248. 
  249. File: jade.info,  Node: Compiling Programs,  Next: Info Mode,  Prev: Client Editing,  Up: Using Jade
  250.  
  251. Compiling Programs
  252. ==================
  253.  
  254.    Jade has a number of features to help you develop programs, foremost
  255. is the ability to run a compilation inside one of the editor's buffers.
  256. Unfortunately, this is only possible when using the Unix operating
  257. system at the present.
  258.  
  259.    Once the compilation has finished you can then step through each
  260. error produced.
  261.  
  262. * Menu:
  263.  
  264. * Running a Compilation::       Launching a compilation process
  265. * Finding Errors::              Stepping through compile errors
  266. * Debugging Programs::          Using GDB in an editor buffer
  267. * Using Grep::                  Searching files for a regexp
  268. * Keeping ChangeLogs::          Simple recording of file revisions
  269.  
  270. 
  271. File: jade.info,  Node: Running a Compilation,  Next: Finding Errors,  Up: Compiling Programs
  272.  
  273. Running a Compilation
  274. ---------------------
  275.  
  276.    The command to run a shell command in a buffer is,
  277.  
  278. `Meta-x compile'
  279.      Prompts you for the command to execute, with a default of the last
  280.      command you ran (starts as `make'). A shell process is created
  281.      which runs asynchronously to the editor in the same directory as
  282.      the current buffer's file was loaded from. The buffer
  283.      `*compilation*' is selected and this is where all output from the
  284.      program is printed.
  285.  
  286.    When the process finishes running a message is printed in the
  287. `*compilation*' buffer telling you its exit-code.
  288.  
  289.    Only one process may be run with the `compile' function at once.
  290.  
  291.    This command is not available on the Amiga version yet.
  292.  
  293. 
  294. File: jade.info,  Node: Finding Errors,  Next: Debugging Programs,  Prev: Running a Compilation,  Up: Compiling Programs
  295.  
  296. Finding Errors
  297. --------------
  298.  
  299.    When you have compiled something with the `Meta-x compile' command
  300. it is possible to step through each of the errors that it produces. To
  301. do this use the command,
  302.  
  303. `Ctrl-x `'
  304.      Displays the next error in the `*compilation*' buffer. The file
  305.      that is in is loaded (if necessary) and the line with the error is
  306.      found.
  307.  
  308.    If you edit a file which has errors in it, then try to find the next
  309. error (which is in the same file) everything will still work. The
  310. positions of errors are updated as the buffers are modified.
  311.  
  312.    The only exception to this is when you invoke the `next-error'
  313. function while the `*compilation*' buffer is still being written to. If
  314. more errors are produced in a file which has been modified since the
  315. compilation started it is likely that the positions will get out of
  316. sync.
  317.  
  318.    By default, the `next-error' function understands the type of error
  319. output that `gcc' produces. This is of the form,
  320.  
  321.      FILE:LINE-NUMBER:DESCRIPTION
  322.  
  323.    It is possible to use other formats though, the variables which
  324. control this are,
  325.  
  326.  - Variable: compile-error-regexp
  327.      Regular expression to match a line containing an error. For `gcc'
  328.      this is `^(.*):([0-9]+):(.+)'.
  329.  
  330.  - Variable: compile-file-expand
  331.      Expansion template to produce the name of the file with the error,
  332.      using `compile-error-regexp' and the line containing the error. By
  333.      default this is `\1'.
  334.  
  335.  - Variable: compile-line-expand
  336.      Similar to `compile-file-expand' except that it expands to a string
  337.      defining the number of the line with the error. By default, `\2'.
  338.  
  339.  - Variable: compile-error-expand
  340.      Similar to `compile-file-expand', but produces the description of
  341.      the error. By default, `\3'.
  342.  
  343. 
  344. File: jade.info,  Node: Debugging Programs,  Next: Using Grep,  Prev: Finding Errors,  Up: Compiling Programs
  345.  
  346. Debugging Programs
  347. ------------------
  348.  
  349.    Jade allows you to run the GDB debugger in a buffer. Some of the
  350. advantages of this over the usual terminal based interaction are,
  351.  
  352.    * The current position of the target program (its "frame") is
  353.      highlighted; the source file is displayed in a separate window
  354.      with the current frame marked (in the same way that a block is
  355.      marked).
  356.  
  357.    * You are able to set and delete breakpoints simply by putting the
  358.      cursor on the line you wish the target to stop at and typing an
  359.      editor command.
  360.  
  361.    To start a gdb subprocess use the `Meta-x gdb' command, you will be
  362. asked to enter the name of the program to debug then gdb will be
  363. started in a new buffer (called `*gdb*' or similar). You are then able
  364. to type commands into the buffer, they will be sent to gdb each time
  365. you type the RET key.
  366.  
  367.    The commands for controlling the gdb subprocess are as follows (the
  368. `Ctrl-c' prefixed commands are only available within the `*gdb*' buffer
  369. whereas the `Ctrl-x Ctrl-a' variations are accessible globally so that
  370. they can be invoked from within the target's source files),
  371.  
  372. `Ctrl-c Ctrl-n'
  373. `Ctrl-x Ctrl-a Ctrl-n'
  374.      Continue execution to the next source line, this is the gdb command
  375.      `next'.
  376.  
  377. `Ctrl-c Ctrl-s'
  378. `Ctrl-x Ctrl-a Ctrl-s'
  379.      Continue execution until a different source line is reached, this
  380.      is the gdb command `step'.
  381.  
  382. `Ctrl-c Ctrl-f'
  383. `Ctrl-x Ctrl-a Ctrl-f'
  384.      Continue running until the current stack frame exits, the `finish'
  385.      command.
  386.  
  387. `Ctrl-c Ctrl-r'
  388. `Ctrl-x Ctrl-a Ctrl-r'
  389.      Resume execution until a breakpoint is reached or the target exits.
  390.  
  391. `Ctrl-c Ctrl-<'
  392. `Ctrl-x Ctrl-a Ctrl-<'
  393.      Display the stack frame above the current one.
  394.  
  395. `Ctrl-c Ctrl->'
  396. `Ctrl-x Ctrl-a Ctrl->'
  397.      Display the stack frame under the current one.
  398.  
  399. `Ctrl-c Ctrl-b'
  400. `Ctrl-x Ctrl-a Ctrl-b'
  401.      Set a breakpoint at the current source line, if the `*gdb*' buffer
  402.      is active the line selected is where the program last stopped.
  403.  
  404. `Ctrl-c Ctrl-t'
  405. `Ctrl-x Ctrl-a Ctrl-t'
  406.      Set a temporary breakpoint at the current source line.
  407.  
  408. `Ctrl-c Ctrl-d'
  409. `Ctrl-x Ctrl-a Ctrl-d'
  410.      Remove all breakpoints which are set at the current source line.
  411.  
  412. `Ctrl-c Ctrl-l'
  413. `Ctrl-x Ctrl-a Ctrl-l'
  414.      Redisplay the current frame, centring it in its window.
  415.  
  416.    For a summary of these commands type `Ctrl-h m' in the `*gdb*'
  417. buffer.
  418.  
  419.    Since the gdb process runs on top of the Shell mode the bindings from
  420. that mode are also available.
  421.  
  422.    There is no limit to the number of gdb processes you may run at once,
  423. each will get its own buffer. When a gdb command is invoked in a buffer
  424. which doesn't have a gdb subprocess (i.e. a source file's buffer) the
  425. command will be sent to the gdb process which either was last sent a
  426. command, or last made the editor display a new frame. Hopefully this
  427. will work fairly intuitively.
  428.  
  429. 
  430. File: jade.info,  Node: Using Grep,  Next: Keeping ChangeLogs,  Prev: Debugging Programs,  Up: Compiling Programs
  431.  
  432. Using Grep
  433. ----------
  434.  
  435.    It is often very useful to grep through a set of files looking for a
  436. regular expression, this is what the `grep' command does. With Jade it
  437. is possible to run an external `grep' program in the `*compilation*'
  438. buffer. This then enables you to step through each grep hit using the
  439. `Ctrl-x `' command, *Note Finding Errors::.
  440.  
  441.    The commands to use grep are,
  442.  
  443. `Meta-x grep'
  444.      Prompt for a string of arguments to give `grep', you do not need to
  445.      provide the name of the program, or the `-n' switch, this is done
  446.      automatically. The shell will do any filename-globbing on the
  447.      arguments so it is advisable to surround the regular expression
  448.      with single quotes.
  449.  
  450.      Note that the regular expression syntax will be different to that
  451.      which Jade uses. Also this command won't work on an Amiga.
  452.  
  453. `Meta-x grep-buffer'
  454.      This command provides a method for scanning the current buffer for
  455.      all lines matching a regular expression (which you are prompted
  456.      for). It is written entirely in Lisp -- this means that the normal
  457.      regular expression syntax is needed and it will work on an Amiga.
  458.  
  459. 
  460. File: jade.info,  Node: Keeping ChangeLogs,  Prev: Using Grep,  Up: Compiling Programs
  461.  
  462. Keeping ChangeLogs
  463. ------------------
  464.  
  465.    A ChangeLog is a file (usually called `ChangeLog') which keeps a log
  466. of all changes you have made to the files in its directory. For
  467. example, the `src/ChangeLog' file for Jade keeps a list of changes made
  468. to the editor's source code.
  469.  
  470.    There is no magic involved, you simply use a command to add a new
  471. entry to a directory's log after modifying a file in that directory.
  472. You then have to enter a summary of the changes that you made.
  473.  
  474.    The command to do this is,
  475.  
  476. `Meta-a'
  477.      Prompts for the name of a directory then lets you type a
  478.      description of the changes you have made.
  479.  
  480.    If you enter more than one change in the same day (and from the same
  481. host) the same heading will be used. The heading consists of the time
  482. and date, your name, your login and the name of the host you're on. (1)
  483.  
  484.    ---------- Footnotes ----------
  485.  
  486.    (1)  On the Amiga there is no way to get these details. So, Jade
  487. looks for some environment variables, `USERNAME' for the login name,
  488. `HOSTNAME' for the name of the host and `REALNAME' for your actual name.
  489.  
  490. 
  491. File: jade.info,  Node: Info Mode,  Next: Shell,  Prev: Compiling Programs,  Up: Using Jade
  492.  
  493. Info Mode
  494. ---------
  495.  
  496.    Despite the name of this section there is actually no such thing as
  497. the `info-mode'. The Lisp file `info.jl' is what this section documents
  498. -- it is a set of Lisp functions which make a buffer (the `*Info*'
  499. buffer) into a simple browser for Info files(1).
  500.  
  501.    To invoke it type `Ctrl-h i', the `*Info*' buffer will be selected
  502. showing the `(dir)' node (the root of the Info documentation tree).
  503.  
  504.    When in the `*Info*' buffer the following key bindings are available.
  505.  
  506. `SPC'
  507.      Displays the next page of the current node.
  508.  
  509. `Backspace'
  510.      Displays the previous page.
  511.  
  512. `1'
  513.      Move to the specified menu-item (`1' means the first, etc) in the
  514.      menu in this node. The keys `1' to `9' work in this way.
  515.  
  516. `b'
  517.      Move to the beginning of the current node.
  518.  
  519. `d'
  520.      Display the directory node (`(dir)') of the Info documentation
  521.      tree.
  522.  
  523. `f'
  524.      Follow a reference, the one under the cursor if one exists.
  525.  
  526. `g'
  527.      Prompt for the name of a node and try to display it.
  528.  
  529. `h'
  530.      Display the Info tutorial node (`(info)Help').
  531.  
  532. `l'
  533.      Go back to the last node that was displayed before this one.
  534.  
  535. `m'
  536.      Prompts for a menu-item (the one on the same line as the cursor is
  537.      the default) and display the node it points to.
  538.  
  539. `n'
  540.      Display the next node.
  541.  
  542. `p'
  543.      Display the previous node.
  544.  
  545. `u'
  546.      Display the node "above" this one.
  547.  
  548. `q'
  549.      Quit the Info browser.
  550.  
  551. `?'
  552.      Display a piece of text describing all commands available in Info
  553.      mode.
  554.  
  555. `RET'
  556.      Go to the link (menu item or xref) described on the current line.
  557.  
  558. `LMB-Click2'
  559.      Go to the link you double clicked on.
  560.  
  561. `TAB'
  562.      Put the cursor on the next link in this node.
  563.  
  564. `Meta-TAB'
  565.      Put the cursor on the previous link.
  566.  
  567.    This mode has a number of disadvantages over the other Info browsers
  568. available (i.e. the stand-alone `info' program, or Emacs' Info viewer):
  569.  
  570.    * It depends wholly on being able to find a tag table in the Info
  571.      file, if it can't it will simply load the whole file into the
  572.      buffer.
  573.  
  574.    * There is no support for the `*' node name.
  575.  
  576.    * Seems not to work 100% with files formatted by Emacs, `makeinfo'
  577.      formatted files work properly though.
  578.  
  579.    * No editing of nodes.
  580.  
  581.    Of course, its main advantage is that it runs in Jade!
  582.  
  583.    ---------- Footnotes ----------
  584.  
  585.    (1)  `Info' is the GNU way of creating hypertext documents, for more
  586. information see *Note Info: (info)Top.
  587.  
  588. 
  589. File: jade.info,  Node: Shell,  Next: Simple Customisation,  Prev: Info Mode,  Up: Using Jade
  590.  
  591. Shell
  592. =====
  593.  
  594.    When running on a Unix-style operating system Jade allows you to run
  595. a shell subprocess in a buffer (usually the `*shell*' buffer). Each
  596. line you type in the buffer is sent to the shell and the output from
  597. the shell is displayed in the buffer.
  598.  
  599. `Meta-x shell'
  600.      Start a new shell subprocess running in a buffer called `*shell*'.
  601.  
  602.      If a buffer `*shell*' already exists a new buffer with a unique
  603.      name will be opened (i.e. `*shell*<2>').
  604.  
  605.      The working directory of the shell subprocess will be the directory
  606.      which the contents of the current buffer was read from.
  607.  
  608.      This command won't work on Amigas!
  609.  
  610.    Each `*shell*' buffer installs the major mode `shell-mode'.  This
  611. provides the following commands.
  612.  
  613. `Ctrl-a'
  614.      Move the cursor to the beginning of the current line, *after* the
  615.      prompt which the shell printed (if one exists).
  616.  
  617. `Ctrl-d'
  618.      If the cursor is at the end of the buffer send the shell process
  619.      the `eof' character (`^D') (signifying the end of the file).
  620.      Otherwise delete the character under the cursor.
  621.  
  622. `RET'
  623.      Send the current line to the shell (minus any prompt at the
  624.      beginning of the line). If the cursor is not on the last line of
  625.      the buffer (i.e.  the most recent prompt) the current line is
  626.      copied to the end of the buffer before being sent.
  627.  
  628. `Ctrl-c Ctrl-n'
  629.      Move the cursor to the next prompt in the buffer.
  630.  
  631. `Ctrl-c Ctrl-p'
  632.      Move to the previous prompt.
  633.  
  634. `Ctrl-c Ctrl-c'
  635.      Send the `intr' character (`^C') to the shell process.
  636.  
  637. `Ctrl-c Ctrl-d'
  638.      Send the `eof' character (`^D') to the shell.
  639.  
  640. `Ctrl-c Ctrl-z'
  641.      Send the `susp' character (`^Z') to the shell.
  642.  
  643. `Ctrl-c Ctrl-\'
  644.      Send the `quit' character (`^\') to the shell.
  645.  
  646.  - Hook: shell-mode-hook
  647.      This hook is evaluated by the Shell mode after it has initialised
  648.      itself (and started its subprocess).
  649.  
  650.    The following variables customise the actions of the Shell mode.
  651.  
  652.  - Variable: shell-file-name
  653.      This variable defines the file name of the shell to run. Its
  654.      default value is either the value of the environment variable
  655.      `SHELL' or if that doesn't exist the file `/bin/sh'.
  656.  
  657.  - Variable: shell-whole-line
  658.      When this variable's value is non-`nil' the RET command always
  659.      sends the whole of the current line (minus any prompt) even when
  660.      the cursor is not at the end of the line. Otherwise only the part
  661.      of the line before the cursor is sent.
  662.  
  663.      The default value of this variable is `t'.
  664.  
  665.  - Variable: shell-prompt-regexp
  666.      This buffer-local variable defines the regular expression used to
  667.      match the prompt printed by the shell each time it waits for you
  668.      to enter a shell command. By default it has the value
  669.      `^[^]#$%>)]*[]#$%>)] *' but this may be incorrect if you have
  670.      modified your shell's prompt.
  671.  
  672. 
  673. File: jade.info,  Node: Simple Customisation,  Prev: Shell,  Up: Using Jade
  674.  
  675. Simple Customisation
  676. ====================
  677.  
  678.    The best way to tailor the editor to your own requirements is with
  679. your personal startup file. This is called `.jaderc' in your home
  680. directory (1), it is a file of Lisp forms evaluated when Jade
  681. initialises itself.
  682.  
  683.    Usually, setting the values of variables in your startup file is
  684. enough to configure Jade how you want, the Lisp function to set a
  685. variable is called `setq', it's first argument is the name of the
  686. variable, it's second the value you wish to set it to. This value will
  687. usually be one of the following data types,
  688.  
  689. `"xyz"'
  690.      A string `xyz'.
  691.  
  692. `123'
  693. `0173'
  694. `0x7b'
  695.      A number, all of the above have the value 123 (in decimal, octal
  696.      and hexadecimal).
  697.  
  698. `nil'
  699. `t'
  700.      A boolean value, `nil' means false, or not true. `t' is the
  701.      opposite (in fact, any value not `nil' is true).
  702.  
  703.    My `.jaderc' file looks something like this (note that semicolons
  704. introduce comments),
  705.  
  706.      ;;;; .jaderc -*-Lisp-*-
  707.      
  708.      ;; Size of tabs for Lisp source is 2
  709.      (setq lisp-body-indent 2)
  710.      
  711.      ;; When on an Amiga, flag that I don't want pull down menus
  712.      (when (amiga-p)
  713.        (setq amiga-no-menus t))
  714.      
  715.      ;; When editing English-text use auto-filling
  716.      (add-hook 'text-mode-hook 'fill-mode-on)
  717.      
  718.      ;; -with a maximum of 74 characters in a line
  719.      (setq fill-column 74)
  720.      
  721.      ;; Start the edit server
  722.      (server-open)
  723.  
  724.    Most simple customisations can be achieved by simply giving a
  725. variable a new value. Use the `setq' special form to do this (a special
  726. form is a type of function) as in the examples above. If you wish to
  727. set variables interactively use the `set' command:
  728.  
  729.      `Meta-x set RET VARIABLE-NAME RET NEW-VALUE RET'.
  730.  
  731.    The `add-hook' function adds a function (in this case `fill-mode-on')
  732. to be called when the specified hook (in this case `text-mode-hook') is
  733. evaluated. The single-quote before the names means that the names are
  734. passed as constants; *not* their values. If you don't quite understand
  735. what I'm talking about don't worry.
  736.  
  737.    For full documentation of Jade's programming language see *Note
  738. Programming Jade::.
  739.  
  740.    ---------- Footnotes ----------
  741.  
  742.    (1)  On the Amiga, your home directory is defined as the contents of
  743. the environment variable `HOME'.
  744.  
  745. 
  746. File: jade.info,  Node: Programming Jade,  Next: Reporting Bugs,  Prev: Using Jade,  Up: Top
  747.  
  748. Programming Jade
  749. ****************
  750.  
  751.    This chapter of the manual is a full guide to Jade's Lisp programming
  752. language, including documentation for most of the built-in functions.
  753.  
  754. * Menu:
  755.  
  756. * Intro::                       Introduction and Lisp conventions
  757.  
  758. * Data Types::                  Data types and values in Lisp
  759. * Numbers::                     Integers and arithmetic functions
  760. * Sequences::                   Ordered sequences of data values
  761. * Symbols::                     Symbols are uniquely named objects
  762.  
  763. * Evaluation::                  Evaluating expressions
  764. * Control Structures::          Special forms. Conditionals, loops, etc...
  765. * Variables::                   Symbols represent named variables
  766. * Functions::                   Functions are the building blocks of Lisp
  767.                                   programs
  768. * Macros::                      User-defined control structures
  769.  
  770. * Streams::                     Data sinks and sources; character streams
  771. * Loading::                     Programs are stored in files
  772. * Compiled Lisp::               Making programs run faster
  773.  
  774. * Hooks::                       Hooks allow the extending of Jade
  775. * Buffers::                     Buffers allow editing of files
  776. * Windows::                     Windows receive input and display buffers
  777. * Positions::                   Coordinates in buffers and cursor movement
  778. * Marks::                       Marks represent the position of a character
  779.                                   in a file
  780. * Glyph Tables::                Controlling the glyphs rendered for each
  781.                                   ASCII character
  782.  
  783. * Input Events::                Objects which represent input events
  784. * Keymaps::                     Mappings between events and commands
  785. * Event Loop::                  The event loop reads input events and
  786.                                   invokes commands
  787.  
  788. * Editing Files::               Files are edited in buffers
  789. * Text::                        Functions to edit buffers with
  790. * Writing Modes::               Creating new editing modes
  791. * Prompting::                   Interactively asking the user a question
  792.  
  793. * Files::                       Manipulating files in the filing system
  794. * Processes::                   Jade can launch and control subprocesses
  795.                                   when running under Unix
  796.  
  797. * Miscellaneous Functions::     Functions which don't fit elsewhere in
  798.                                   this manual
  799.  
  800. * Debugging::                   How to debug Lisp programs
  801. * Tips::                        General recommendations for Lisp programmers
  802.  
  803. 
  804. File: jade.info,  Node: Intro,  Next: Data Types,  Up: Programming Jade
  805.  
  806. Introduction
  807. ============
  808.  
  809.    As you have probably gathered by now, Jade is largely controlled by
  810. its built in programming language: a dialect of Lisp containing many
  811. extensions (non-standard data types and functions) to make it suitable
  812. for controlling an editor. Through this language Jade can be customised
  813. and extended.
  814.  
  815.    I have attempted to make the "standard" portion of the language (i.e.
  816. anything a normal Lisp would have; not related to editing) as compatible
  817. with GNU Emacs Lisp as possible. In some areas this rule doesn't apply,
  818. there will usually be a good reason for this. A few functions have been
  819. inspired by Common Lisp.
  820.  
  821.    The areas of the language which control the *editor* are *not*
  822. compatible with Emacs; some functions may be similar but since the two
  823. editors are fundamentally different I have not attempted to conform with
  824. the Emacs API.
  825.  
  826.    All programs written using only the information in this manual should
  827. be compatible with future revisions of Jade.
  828.  
  829.    This following sections explain some of the most important Lisp
  830. concepts and the conventions I've used in this manual.
  831.  
  832. * Menu:
  833.  
  834. * nil and t::                   Boolean values in Lisp
  835. * The Lisp Reader::             Basic program structure
  836. * Notation::                    Special glyphs used
  837. * Descriptions::                How functions and variables are documented
  838.  
  839. 
  840. File: jade.info,  Node: nil and t,  Next: The Lisp Reader,  Up: Intro
  841.  
  842. nil and t
  843. ---------
  844.  
  845.    The two boolean values in Lisp are the symbols `nil' (FALSE) and `t'
  846. (TRUE). Both these symbols always evaluate to themselves (so they do
  847. not have to be quoted), any attempt to change their values is an error.
  848.  
  849.    All of the conditional instructions regard *anything* which is not
  850. `nil' as being TRUE (i.e. not-FALSE). The actual symbol `t' should be
  851. used where a TRUE boolean value must be explicitly stated to increase
  852. the clarity of the code.
  853.  
  854.    This is not the end of the story; `nil' actually has another meaning:
  855. it represents the empty list. This is a consequence of how lists are
  856. constructed in Lisp, a list of zero elements is stored as the symbol
  857. `nil'.
  858.  
  859.    To the Lisp system itself there is absolutely no difference between
  860. `()' (the notation for a list with zero elements) and `nil' (the symbol
  861. nil).  When writing code however, the list notation is usually used
  862. when the programmer regards the value as a list and the `nil' notation
  863. when its value as a boolean is to be emphasised.
  864.  
  865. 
  866. File: jade.info,  Node: The Lisp Reader,  Next: Notation,  Prev: nil and t,  Up: Intro
  867.  
  868. The Lisp Reader
  869. ---------------
  870.  
  871.    Lisp programs and functions are stored internally as normal Lisp data
  872. objects, the Lisp Reader is the process used to translate textual
  873. descriptions of Lisp objects into the data structures used to represent
  874. the objects.
  875.  
  876.    The Lisp Reader is the collection of internal functions accessed by
  877. the `read' Lisp function. It reads a character at a time from an input
  878. stream until it has parsed a whole Lisp object.
  879.  
  880.    *Note Data Types::.
  881.  
  882. 
  883. File: jade.info,  Node: Notation,  Next: Descriptions,  Prev: The Lisp Reader,  Up: Intro
  884.  
  885. Notation
  886. --------
  887.  
  888.    Wherever an example of evaluating a Lisp form is shown it will be
  889. formatted like this,
  890.  
  891.      (+ 1 2)
  892.          => 3
  893.  
  894. The glyph `=>' is used to show the computed value of a form.
  895.  
  896.    When two forms are shown as being exactly equivalent to one another
  897. the glyph `==' is used, for example,
  898.  
  899.      (car some-variable) == (nth 0 some-variable)
  900.  
  901.    Evaluating some forms result in an error being signalled, this is
  902. denoted by the `error-->' glyph.
  903.  
  904.      (read-file "/tmp/foo")
  905.          error--> File error: No such file or directory, /tmp/foo
  906.  
  907. 
  908. File: jade.info,  Node: Descriptions,  Prev: Notation,  Up: Intro
  909.  
  910. Descriptions
  911. ------------
  912.  
  913.    The simplest type of descriptions are the descriptions of variables
  914. (*note Variables::.), they look something like,
  915.  
  916.  - Variable: grains-of-sand
  917.      This imaginary variable contains the number of grains of sand in a
  918.      one-mile long stretch of an averagely sandy beach.
  919.  
  920.    Hooks (*note Hooks::.) are also described in this format, the only
  921. difference is that `Variable:' is replaced by `Hook:'.
  922.  
  923.    Functions (*note Functions::.) and macros (*note Macros::.) have
  924. more complex descriptions; as well as the name of the thing being
  925. described, they also have a list of arguments which the thing will
  926. accept. Each argument in the list is named and may be referred to in
  927. the body of the description.
  928.  
  929.    Two `special' arguments may be used, `&optional' and `&rest'.  They
  930. have the same meaning as when used in the lambda-list of a function
  931. definition (*note Lambda Expressions::.), that is `&optional' means
  932. that all further arguments are optional, and `&rest' means that zero or
  933. more argument values are coalesced into a list to be used as the value
  934. of the following argument.
  935.  
  936.    An example function definition follows.
  937.  
  938.  - Function: useless-function FIRST &optional SECOND &rest TAIL
  939.      This function returns a list consisting of the values SECOND (when
  940.      undefined the number 42 is used), all the items in the list TAIL
  941.      and FIRST.
  942.  
  943.           (useless-function 'foo 'bar 'xyz 20)
  944.               => (bar xyz 20 foo)
  945.           
  946.           (useless-function '50)
  947.               => (42 50)
  948.  
  949.    Macros and commands (*note Commands::.) are defined in the same way
  950. with `Macro:' or `Command:' replacing `Function:'.
  951.  
  952.    Special forms (*note Special Forms::.) are described similarly to
  953. functions except that the argument list is formatted differently since
  954. special forms are, by definition, more flexible in how they treat their
  955. arguments. Optional values are enclosed in square brackets
  956. (`[OPTIONAL-ARG]') and three dots (`REPEATED-ARG...') indicate where
  957. zero or more arguments are allowed.
  958.  
  959. 
  960. File: jade.info,  Node: Data Types,  Next: Numbers,  Prev: Intro,  Up: Programming Jade
  961.  
  962. Data Types
  963. ==========
  964.  
  965.    The way that data values are represented in Lisp is fundamentally
  966. different to more "conventional" languages such as C or Pascal: in Lisp
  967. each piece of data (a "Lisp Object") has two basic attributes, the
  968. actual data and a tag value defining the *type* of the object. This
  969. means that type checking is performed on the actual data itself, not on
  970. the "variable" holding the data.
  971.  
  972.    All Lisp objects are a member of one of the primitive types; these
  973. are types built into the Lisp system and can represent things like
  974. strings, integers, cons cells, vectors, etc...
  975.  
  976.    More complex types of object can be constructed from these primitive
  977. types, for example a vector of three elements could be regarded as a
  978. type `triple' if necessary. In general, each separate type provides a
  979. predicate function which returns `t' when applied to an object of its
  980. type.
  981.  
  982. * Menu:
  983.  
  984. * Types Summary::               List of the most common types
  985. * Read Syntax::                 Some types can be constructed from source code
  986. * Printed Representation::      All types can be printed
  987. * Equality Predicates::         How to test two objects for equality
  988. * Comparison Predicates::       Comparing two objects as scalars
  989. * Type Predicates::             Each type has a predicate defining it
  990. * Garbage Collection::          Reusing memory from stale objects
  991.  
  992. 
  993. File: jade.info,  Node: Types Summary,  Next: Read Syntax,  Up: Data Types
  994.  
  995. Types Summary
  996. -------------
  997.  
  998.    Each separate data type is documented in its own section, this is a
  999. just a table of the more common types.
  1000.  
  1001. "Integer"
  1002.      32-bit signed integers. *Note Numbers::.
  1003.  
  1004. "Cons cell"
  1005.      An object containing two other Lisp objects. *Note Cons Cells::.
  1006.  
  1007. "List"
  1008.      A sequence of objects, in Lisp lists are not primitive types,
  1009.      instead they are made by chaining together Cons cells. *Note
  1010.      Lists::.
  1011.  
  1012. "Vector"
  1013.      A one-dimensional array of objects. *Note Vectors::.
  1014.  
  1015. "String"
  1016.      A vector of characters. *Note Strings::.
  1017.  
  1018. "Array"
  1019.      An ordered sequence of objects which can be accessed in constant
  1020.      time, either a vector or a string. *Note Sequences::.
  1021.  
  1022. "Sequence"
  1023.      An ordered sequence of objects, either a list or an array.  *Note
  1024.      Sequences::.
  1025.  
  1026. "Symbol"
  1027.      A symbol is a named object; they are used to provide named
  1028.      variables and functions. *Note Symbols::.
  1029.  
  1030. "File"
  1031.      A link to a file in the operating system's filing system, allows
  1032.      access to the file as a stream. *Note Files::.
  1033.  
  1034. "Stream"
  1035.      Serial data sinks and sources. *Note Streams::.
  1036.  
  1037. "Void"
  1038.      No type, only used in symbols to represent an unset function or
  1039.      variable value.
  1040.  
  1041. "Buffer"
  1042.      A "space" in which text can be edited, buffers may be displayed in
  1043.      a window and hence edited by the user. *Note Buffers::.
  1044.  
  1045. "Window"
  1046.      A physical window in the underlying window-system, used for input
  1047.      and output.
  1048.  
  1049. "Position"
  1050.      A pair of integers, used to represent the coordinates of a
  1051.      character in a buffer. *Note Positions::.
  1052.  
  1053. "Mark"
  1054.      A position in a specified file, this file may either be a buffer
  1055.      in memory or a named file. *Note Marks::.
  1056.  
  1057. "Process"
  1058.      An object through which processes may be created and controlled.
  1059.      *Note Processes::.
  1060.  
  1061. "Glyph Table"
  1062.      A lookup-table which is used to map characters in a buffer to the
  1063.      sequence of glyphs they are rendered as. *Note Glyph Tables::.
  1064.  
  1065. "Keymap"
  1066.      A set of key-sequence-to-command mappings; when installed in a
  1067.      buffer it controls how the editor reacts to all input from the
  1068.      user. *Note Keymaps::.
  1069.  
  1070. "Event"
  1071.      An (input-) event from a window.
  1072.  
  1073. 
  1074. File: jade.info,  Node: Read Syntax,  Next: Printed Representation,  Prev: Types Summary,  Up: Data Types
  1075.  
  1076. Read Syntax
  1077. -----------
  1078.  
  1079.    As previously noted the Lisp reader translates textual descriptions
  1080. of Lisp objects into the object they describe (source files are simply
  1081. descriptions of objects). However, not all data types can be created in
  1082. this way: in fact the only types which can are integers, strings,
  1083. symbols, cons cells (or lists) and vectors, all others have to be
  1084. created by calling functions.
  1085.  
  1086.    Note that comments in a Lisp program are introduced by the semi-colon
  1087. character (`;'). Whenever the Lisp reader encounters a semi-colon where
  1088. it's looking for the read syntax of a new Lisp object it will discard
  1089. the rest of the line of input. *Note Comment Styles::.
  1090.  
  1091.    The "read syntax" of an object is the string which when given to the
  1092. reader as input will produce the object. The read syntax of each type
  1093. of object is documented in that type's main section of this manual but
  1094. here is a small taste of how to write each type.
  1095.  
  1096. Integers
  1097.      An integer is simply the number written in either decimal, octal
  1098.      (when the number is preceded by `0') or hexadecimal (when the
  1099.      number is preceded by `0x'). An optional minus sign may be the
  1100.      first character in a number. Some examples are,
  1101.  
  1102.           42
  1103.               => 42
  1104.           
  1105.           0177
  1106.               => 127
  1107.           
  1108.           0xff
  1109.               => 255
  1110.           
  1111.           -0x10
  1112.               => -16
  1113.  
  1114. Strings
  1115.      The read syntax of a string is simply the string with a
  1116.      double-quote character (`"') at each end, for more details see
  1117.      *Note Strings::.
  1118.  
  1119.           "This is a string"
  1120.  
  1121. Cons cells
  1122.      A cons cell is written in what is known as "dotted pair notation"
  1123.      and is just the two objects in the cell separated by a dot and the
  1124.      whole thing in parentheses,
  1125.  
  1126.           (CAR . CDR)
  1127.  
  1128. Lists
  1129.      The syntax of a list is similar to a cons cell (since this is what
  1130.      lists are made of): no dot is used and there may be zero or more
  1131.      objects,
  1132.  
  1133.           (OBJECT1 OBJECT2 OBJECT3 ...)
  1134.           
  1135.           ("foo" ("bar" "baz") 100)
  1136.  
  1137.      The second example is a list of three elements, a string, another
  1138.      list and a number.
  1139.  
  1140. Vectors
  1141.      The read syntax of a vector is very similar to that of a list,
  1142.      simply use square brackets instead of parentheses,
  1143.  
  1144.           [OBJECT1 OBJECT2 OBJECT3 ...]
  1145.  
  1146. Symbols
  1147.      A symbol's read syntax is simply its name, for example the read
  1148.      syntax of a symbol called `my-symbol' is,
  1149.  
  1150.           my-symbol
  1151.  
  1152. 
  1153. File: jade.info,  Node: Printed Representation,  Next: Equality Predicates,  Prev: Read Syntax,  Up: Data Types
  1154.  
  1155. Printed Representation
  1156. ----------------------
  1157.  
  1158.    The "printed representation" of an object is the string produced
  1159. when the object is printed (with one of the `print' functions), this
  1160. will usually be very similar to the read syntax of the object (*note
  1161. Read Syntax::.).
  1162.  
  1163.    Objects which do not have a read syntax *do* have a printed
  1164. representation, it will normally be of the form,
  1165.  
  1166.      #<relevant text>
  1167.  
  1168. where the "relevant text" is object-dependent and usually describes the
  1169. object and its contents. The reader will signal an error if it
  1170. encounters a description of an object in the format `#<...>'.
  1171.  
  1172. 
  1173. File: jade.info,  Node: Equality Predicates,  Next: Comparison Predicates,  Prev: Printed Representation,  Up: Data Types
  1174.  
  1175. Equality Predicates
  1176. -------------------
  1177.  
  1178.  - Function: eq ARG1 ARG2
  1179.      Returns `t' when ARG1 and ARG2 are the same object. Two objects
  1180.      are the same object when they occupy the same place in memory and
  1181.      hence modifying one object would alter the other. The following
  1182.      Lisp fragments may illustrate this,
  1183.  
  1184.           (eq "foo" "foo")    ;the objects are distinct
  1185.               => nil
  1186.           
  1187.           (eq t t)        ;the same object -- the symbol `t'
  1188.               => t
  1189.  
  1190.      Note that the result of `eq' is undefined when called on two
  1191.      integer objects with the same value, see `eql'.
  1192.  
  1193.  - Function: equal ARG1 ARG2
  1194.      The function `equal' compares the structure of the two objects ARG1
  1195.      and ARG2. If they are considered to be equivalent then `t' is
  1196.      returned, otherwise `nil' is returned.
  1197.  
  1198.           (equal "foo" "foo")
  1199.               => t
  1200.           
  1201.           (equal 42 42)
  1202.               => t
  1203.           
  1204.           (equal 42 0)
  1205.               => nil
  1206.           
  1207.           (equal '(x . y) '(x . y))
  1208.               => t
  1209.  
  1210.  - Function: eql ARG1 ARG2
  1211.      This function is a cross between `eq' and `equal': if ARG1 and
  1212.      ARG2 are both numbers then the value of these numbers are compared.
  1213.      Otherwise it behaves in exactly the same manner as `eq' does.
  1214.  
  1215.           (eql 3 3)
  1216.               => t
  1217.           
  1218.           (eql 1 2)
  1219.               => nil
  1220.           
  1221.           (eql "foo" "foo")
  1222.               => nil
  1223.           
  1224.           (eql 'x 'x)
  1225.               => t
  1226.  
  1227. 
  1228. File: jade.info,  Node: Comparison Predicates,  Next: Type Predicates,  Prev: Equality Predicates,  Up: Data Types
  1229.  
  1230. Comparison Predicates
  1231. ---------------------
  1232.  
  1233.    These functions compare their two arguments in a scalar fashion, the
  1234. arguments may be of any type but the results are only meaningful for
  1235. numbers, strings (ASCII values of each byte compared until a
  1236. non-matching pair is found then those two values are compared as
  1237. numbers) and positions.
  1238.  
  1239.  - Function: > ARG1 ARG2
  1240.      Returns `t' when ARG1 is `greater than' ARG2.
  1241.  
  1242.  - Function: >= ARG1 ARG2
  1243.      Returns `t' when ARG1 is `greater than or equal to' ARG2.
  1244.  
  1245.  - Function: < ARG1 ARG2
  1246.      Returns `t' when ARG1 is `less than' ARG2.
  1247.  
  1248.  - Function: <= ARG1 ARG2
  1249.      Returns `t' when ARG1 is `less than or equal to' ARG2.
  1250.  
  1251. 
  1252. File: jade.info,  Node: Type Predicates,  Next: Garbage Collection,  Prev: Comparison Predicates,  Up: Data Types
  1253.  
  1254. Type Predicates
  1255. ---------------
  1256.  
  1257.    Each type has a corresponding predicate which defines the objects
  1258. which are members of that type.
  1259.  
  1260.    * `integerp'
  1261.  
  1262.    * `numberp'
  1263.  
  1264.    * `null'
  1265.  
  1266.    * `consp'
  1267.  
  1268.    * `listp'
  1269.  
  1270.    * `vectorp'
  1271.  
  1272.    * `subrp'
  1273.  
  1274.    * `functionp'
  1275.  
  1276.    * `sequencep'
  1277.  
  1278.    * `stringp'
  1279.  
  1280.    * `symbolp'
  1281.  
  1282.    * `posp'
  1283.  
  1284.    * `bufferp'
  1285.  
  1286.    * `windowp'
  1287.  
  1288.    * `markp'
  1289.  
  1290.    * `processp'
  1291.  
  1292.    * `filep'
  1293.  
  1294.    * `keymapp'
  1295.  
  1296.    * `eventp'
  1297.  
  1298.    * `commandp'
  1299.  
  1300.    The documentation for these functions is with the documentation for
  1301. the relevant type.
  1302.  
  1303. 
  1304. File: jade.info,  Node: Garbage Collection,  Prev: Type Predicates,  Up: Data Types
  1305.  
  1306. Garbage Collection
  1307. ------------------
  1308.  
  1309.    In Lisp, data objects are used very freely; a side effect of this is
  1310. that it is not possible to (easily) know when an object is "stale",
  1311. that is, no references to it exist and it can therefore be reused.
  1312.  
  1313.    The "garbage collector" is used to overcome this problem; whenever
  1314. enough new data objects have been allocated to make it worthwhile,
  1315. everything stops and the garbage collector works its way through memory
  1316. deciding which objects are still in use and which are stale.  The stale
  1317. objects are then recorded as being available for reuse and evaluation
  1318. continues again.
  1319.  
  1320.  - Function: garbage-collect
  1321.      Runs the garbage collector, usually this function doesn't need to
  1322.      be called manually.
  1323.  
  1324.  - Variable: garbage-threshold
  1325.      The number of bytes of data which must be allocated before
  1326.      evaluation will pause and the garbage collector called.
  1327.  
  1328.      Its default value is about 100K.
  1329.  
  1330.    *Note Idle Actions::.
  1331.  
  1332. 
  1333. File: jade.info,  Node: Numbers,  Next: Sequences,  Prev: Data Types,  Up: Programming Jade
  1334.  
  1335. Numbers
  1336. =======
  1337.  
  1338.    Currently Jade is only capable of representing integers, for this it
  1339. uses signed 32-bit integers: this gives a range of -2147483648 through
  1340. 0 to 2147483647.
  1341.  
  1342.    The read syntax of an integer is simply the number written in
  1343. decimal, octal or hexadecimal. If the integer starts with the string
  1344. `0x' it is assumed to be hexadecimal or if it starts with a zero it is
  1345. treated as octal. The first character may be an optional minus or plus
  1346. sign (this should come before any base-specifier). Examples of valid
  1347. integer read syntaxes for the number 42 could be `42', `0x2a', `052',
  1348. `+052', ...
  1349.  
  1350.    An integer's printed representation is simply the number printed in
  1351. decimal with a preceding minus sign if it is negative.
  1352.  
  1353.  - Function: numberp OBJECT
  1354.      This function returns `t' if OBJECT is a number.
  1355.  
  1356.  - Function: integerp OBJECT
  1357.      This function returns `t' when OBJECT is an integer.
  1358.  
  1359. * Menu:
  1360.  
  1361. * Arithmetic Functions::        Adding and substracting...
  1362. * Bitwise Functions::           Using integers as bit-sequences
  1363. * Numeric Predicates::          Comparing numbers
  1364. * Characters::                  Integers are used to represent characters
  1365.  
  1366. 
  1367. File: jade.info,  Node: Arithmetic Functions,  Next: Bitwise Functions,  Up: Numbers
  1368.  
  1369. Arithmetic Functions
  1370. ====================
  1371.  
  1372.    There are a number of functions which perform arithmetic operations
  1373. on numbers, they take a varying number of integer objects as their
  1374. arguments then return a new integer object as their result.
  1375.  
  1376.    Note that none of these functions check for overflow.
  1377.  
  1378.  - Function: + NUMBER1 &rest NUMBERS
  1379.      This functions adds its arguments then returns their sum.
  1380.  
  1381.  - Function: - NUMBER1 &rest NUMBERS
  1382.      If this function is just given one argument (NUMBER1) that number
  1383.      is negated and returned. Otherwise each of NUMBERS is subtracted
  1384.      from a running total starting with the value of NUMBER1.
  1385.  
  1386.           (- 20)
  1387.               => -20
  1388.           
  1389.           (- 20 10 5)
  1390.               => 5
  1391.  
  1392.  - Function: * NUMBER1 &rest NUMBERS
  1393.      This function multiplies its arguments then returns the result.
  1394.  
  1395.  - Function: / NUMBER1 &rest NUMBERS
  1396.      This function performs division, a running-total (initialised from
  1397.      NUMBER1 is successively divided by each of NUMBERS then the result
  1398.      is returned.
  1399.  
  1400.           (/ 100 2)
  1401.               => 50
  1402.           
  1403.           (/ 200 2 5)
  1404.               => 20
  1405.  
  1406.  - Function: % DIVIDEND DIVISOR
  1407.      Returns the remainder from dividing DIVIDEND by DIVISOR.
  1408.  
  1409.           (mod 5 3)
  1410.               => 2
  1411.  
  1412.  - Function: 1+ NUMBER
  1413.      This function returns the result of adding one to NUMBER.
  1414.  
  1415.           (1+ 42)
  1416.               => 43
  1417.  
  1418.  - Function: 1- NUMBER
  1419.      Returns NUMBER minus one.
  1420.  
  1421. 
  1422. File: jade.info,  Node: Bitwise Functions,  Next: Numeric Predicates,  Prev: Arithmetic Functions,  Up: Numbers
  1423.  
  1424. Bitwise Functions
  1425. =================
  1426.  
  1427.    These functions operate on the bit string which an integer is made
  1428. of.
  1429.  
  1430.  - Function: lsh NUMBER COUNT
  1431.      This function bit-shifts the integer NUMBER COUNT bits to the
  1432.      left, if COUNT is negative NUMBER is shifted to the right instead.
  1433.  
  1434.           (lsh 1 8)
  1435.               => 256
  1436.           
  1437.           (lsh 256 -8)
  1438.               => 1
  1439.  
  1440.  - Function: ash NUMBER COUNT
  1441.      Similar to `lsh' except that an arithmetical shift is done, this
  1442.      means that the sign of NUMBER is always preserved.
  1443.  
  1444.           (ash 1 8)
  1445.               => 256
  1446.           
  1447.           (ash -1 2)
  1448.               => -4
  1449.  
  1450.  - Function: logand NUMBER1 &rest NUMBERS
  1451.      This function uses a bit-wise logical `and' operation to combine
  1452.      all its arguments (there must be at least one argument).
  1453.  
  1454.           (logand 15 8)
  1455.               => 8
  1456.           
  1457.           (logand 15 7 20)
  1458.               => 4
  1459.  
  1460.  - Function: logior NUMBER1 &rest NUMBERS
  1461.      Uses a bit-wise logical `inclusive-or' to combine all its
  1462.      arguments (there must always be at least one argument).
  1463.  
  1464.           (logior 1 2 4)
  1465.               => 7
  1466.  
  1467.  - Function: logxor NUMBER1 &rest NUMBERS
  1468.      Uses a bitwise logical `exclusive-or' to combine all its arguments
  1469.      (there must be at least one).
  1470.  
  1471.           (logxor 7 3)
  1472.               => 4
  1473.  
  1474.  - Function: lognot NUMBER
  1475.      This function inverts all the bits in NUMBER.
  1476.  
  1477.           (lognot 0)
  1478.               => -1
  1479.           
  1480.           (lognot 2)
  1481.               => -3
  1482.           
  1483.           (lognot -1)
  1484.               => 0
  1485.  
  1486. 
  1487. File: jade.info,  Node: Numeric Predicates,  Next: Characters,  Prev: Bitwise Functions,  Up: Numbers
  1488.  
  1489. Numeric Predicates
  1490. ==================
  1491.  
  1492.    For the documentation of the functions `>', `<', `>=' and `<=' see
  1493. *Note Comparison Predicates::.
  1494.  
  1495.  - Function: = NUMBER1 NUMBER2
  1496.      This function returns `t' if the two integers NUMBER1 and NUMBER2
  1497.      have the same value.
  1498.  
  1499.           (= 1 1)
  1500.               => t
  1501.           
  1502.           (= 1 0)
  1503.               => nil
  1504.  
  1505.  - Function: /= NUMBER1 NUMBER2
  1506.      This function will return `t' if NUMBER1 and NUMBER2 and not equal
  1507.      to each other.
  1508.  
  1509.           (/= 1 1)
  1510.               => nil
  1511.           
  1512.           (/= 1 0)
  1513.               => t
  1514.  
  1515.  - Function: zerop NUMBER
  1516.      Returns `t' if NUMBER is equal to zero.
  1517.  
  1518.