This is Info file jade.info, produced by Makeinfo-1.55 from the input file jade.texi. START-INFO-DIR-ENTRY * Jade: (jade). An editor for X11 and AmigaDOS END-INFO-DIR-ENTRY This is Edition 1.3, last updated 7 October 1994, of `The Jade Manual', for Jade, Version 3.2. Jade is a text editor for X11 (on Unix) and the Amiga. Copyright 1993, 1994 John Harper. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.  File: jade.info, Node: Using Marks, Next: Interrupting Jade, Prev: Using the Prompt, Up: Using Jade Using Marks =========== Marks are used to record a position in a file, as the file's buffer is modified so does the position that the mark points to -- a mark will keep pointing at the same character no matter what happens (unless the character is deleted!). The other good thing about marks is that they point to files *not* buffers. This means that you can set a mark in a buffer, delete the buffer and then move to the position of the mark, the file will be reloaded and the cursor will point at the original character. Normally there are three user-accessible marks (1) and one special `auto-mark' which is used, amongst other things, to record the "previous" position of the cursor, allowing you to retrace your last major step. The commands available on marks are, `F1' `F2' `F3' Move to the mark #1, #2 or #3, depending on which function key is pressed (F1 means mark #1, etc...). If the file pointed to is not in memory it will be loaded into a new buffer. `Shift-F1' `Shift-F2' `Shift-F3' Set the position of mark #1, #2 or #3, depending on the function key. `Ctrl-x Ctrl-x' Swap the positions of the cursor and the `auto-mark'. `Ctrl-@' Set the position of the `auto-mark'. ---------- Footnotes ---------- (1) There is no reason why you can't have more, the editor sets no limitation on the number of marks available. This is just how I have set the editor up.  File: jade.info, Node: Interrupting Jade, Next: Recursive Editing, Prev: Using Marks, Up: Using Jade Interrupting Jade ================= It is often useful to be able to tell Jade to quit whatever it is doing and wait for more commands; this is called "interrupting" Jade. When the editor receives an interrupt signal it will abort what it is doing and rewind itself back to the inner-most recursive edit (see *note Recursive Editing::.). The interrupt signal differs with the operating system being used, * Under Unix the `SIGINT' signal is used, this can be sent via the `intr' character (get the editor into the foreground of the shell it was started from and type `Ctrl-c' in the shell's terminal), or directly through the `kill' shell command. For example, look at the following shell session extract, /var/src/jade/man$ ps PID TT STAT TIME COMMAND 60 1 SW 0:02 (xinit) 87 1 S 0:08 fvwm 127 p0 S 0:00 /bin/bash 155 p0 S 0:04 jade 156 p1 S 0:00 /bin/bash 159 p1 R 0:00 ps /var/src/jade/man$ kill -INT 155 First the `ps' command is used to find the Jade process' pid (155), then the `kill' command is used to send the `INT' signal to this process. * The `Ctrl-c' signal is also used on Amigas, either type this in the console window that Jade was launched from or use the `break' (or possibly `breaktask') command to send the signal.  File: jade.info, Node: Recursive Editing, Next: Character Images, Prev: Interrupting Jade, Up: Using Jade Recursive Editing ================= Recursive editing is the act of editing a file while the current command is still being evaluated. For example, when using the `query-replace' command (`Meta-%') the `Ctrl-r' command enters a recursive edit to let you edit the buffer, even though you are still doing a query-replace (which will be resumed when the recursive edit finishes). As the name suggests a recursive edit calls the editor's main command loop recursively from within a command. Any number of recursive edits may be stacked up and then unwound back to the top-level of the editor. When a recursive edit is in progress the name of the mode being used to edit the buffer is shown in *square brackets*, not parentheses as in the top-level instance. The commands for manipulating recursive edits are as follows, `Ctrl-]' `Ctrl-Meta-c' Exit the innermost recursive edit, this has no effect at the top-level. `Meta-x top-level' Return to the outermost edit -- the top-level. This is useful when you get "lost" inside a sequence of recursive edits. `Meta-x recursive-edit' Enter a new recursive edit; this command is usually best avoided to save confusion. In general, recursive editing is rarely used except in unavoidable circumstances (i.e. in the Lisp debugger).  File: jade.info, Node: Character Images, Next: Client Editing, Prev: Recursive Editing, Up: Using Jade Character Images ================ In general any character can be mapped to any sequence of up to four character sized images (called glyphs) when it is drawn into a window. The TAB character is a notable exception; it expands to as many spaces as are needed to fill up to the next tab stop. By default, the editor is set up to display the following, 0 to 31 A caret (`^') followed by the ASCII value of the character exclusive-or'd with 0x40, i.e. `^@' to `^_'. 32 to 126 Printed literally, this includes all "normal" characters and punctuation. 127 `^?' 128 to 255 Represented by the octal escape sequence (i.e. `\200') for that character's numeric value. If you want to edit files containing characters in the `Latin1' character set (numerically, from 160 to 255) you can put the following in your `.jaderc' file, (latin-1-mode) this will redefine the necessary characters. If you want more details about this sort of thing see *Note Glyph Tables::.  File: jade.info, Node: Client Editing, Next: Compiling Programs, Prev: Character Images, Up: Using Jade Client Editing ============== Normally you will only have one instance of Jade executing at a single time. Often though, another program will want you to edit a file, for example when you are composing a mail message. There is normally a way to specify which editor you want to use, for example the `EDITOR' environment variable. If you were to ask to edit the file in `jade' an *additional* process executing Jade would be started, totally separate from the original. It is possible to use the original instance. Firstly Jade must be set up to listen for clients wanting files edited, this is done with the `server-open' command. You can either put this in your `.jaderc' file (with a line like `(server-open)') or call it manually with the command `Meta-x server-open'. Only one instance of Jade may be a server at once. If you know that there is no other Jade running but it still won't let you open a server, and you are running on Unix, look for a dead socket called `~/.Jade_rendezvous' and delete it if necessary. Once the editor is listening for client messages the separate program `jadeclient' may be used to load files into the server from an external source. The format of `jadeclient' invocation is, jadeclient [+LINE-NUMBER] FILE-NAME ... When invoked, it will ask the server to edit each FILE-NAME (initially positioned at line LINE-NUMBER) in turn, exiting only after each file has finished being edited. If when the `jadeclient' program is invoked their is no server open (i.e. either Jade is not running or you haven't used the `server-open' function) a message `Jade not running, waiting...' will be printed and `jadeclient' will sit waiting for you to open a Jade server. So, simply get the program you want to use Jade to use the `jadeclient' program as its editor. For example, I use `mh' to handle my electronic mail; in my `~/.mh_profile' file I have the line, Editor: jadeclient to tell it that I want to edit my mail in Jade. The one special command for client/server editing is, `Ctrl-x #' If the file being edited in the current buffer is a client file, tell the client program which loaded it that it has finished being edited. The actual buffer is *not* deleted. It is also possible to finish editing a client file by simple deleting its buffer in the normal way (`Ctrl-x k'), *Note Deleting Buffers::.  File: jade.info, Node: Compiling Programs, Next: Info Mode, Prev: Client Editing, Up: Using Jade Compiling Programs ================== Jade has a number of features to help you develop programs, foremost is the ability to run a compilation inside one of the editor's buffers. Unfortunately, this is only possible when using the Unix operating system at the present. Once the compilation has finished you can then step through each error produced. * Menu: * Running a Compilation:: Launching a compilation process * Finding Errors:: Stepping through compile errors * Debugging Programs:: Using GDB in an editor buffer * Using Grep:: Searching files for a regexp * Keeping ChangeLogs:: Simple recording of file revisions  File: jade.info, Node: Running a Compilation, Next: Finding Errors, Up: Compiling Programs Running a Compilation --------------------- The command to run a shell command in a buffer is, `Meta-x compile' Prompts you for the command to execute, with a default of the last command you ran (starts as `make'). A shell process is created which runs asynchronously to the editor in the same directory as the current buffer's file was loaded from. The buffer `*compilation*' is selected and this is where all output from the program is printed. When the process finishes running a message is printed in the `*compilation*' buffer telling you its exit-code. Only one process may be run with the `compile' function at once. This command is not available on the Amiga version yet.  File: jade.info, Node: Finding Errors, Next: Debugging Programs, Prev: Running a Compilation, Up: Compiling Programs Finding Errors -------------- When you have compiled something with the `Meta-x compile' command it is possible to step through each of the errors that it produces. To do this use the command, `Ctrl-x `' Displays the next error in the `*compilation*' buffer. The file that is in is loaded (if necessary) and the line with the error is found. If you edit a file which has errors in it, then try to find the next error (which is in the same file) everything will still work. The positions of errors are updated as the buffers are modified. The only exception to this is when you invoke the `next-error' function while the `*compilation*' buffer is still being written to. If more errors are produced in a file which has been modified since the compilation started it is likely that the positions will get out of sync. By default, the `next-error' function understands the type of error output that `gcc' produces. This is of the form, FILE:LINE-NUMBER:DESCRIPTION It is possible to use other formats though, the variables which control this are, - Variable: compile-error-regexp Regular expression to match a line containing an error. For `gcc' this is `^(.*):([0-9]+):(.+)'. - Variable: compile-file-expand Expansion template to produce the name of the file with the error, using `compile-error-regexp' and the line containing the error. By default this is `\1'. - Variable: compile-line-expand Similar to `compile-file-expand' except that it expands to a string defining the number of the line with the error. By default, `\2'. - Variable: compile-error-expand Similar to `compile-file-expand', but produces the description of the error. By default, `\3'.  File: jade.info, Node: Debugging Programs, Next: Using Grep, Prev: Finding Errors, Up: Compiling Programs Debugging Programs ------------------ Jade allows you to run the GDB debugger in a buffer. Some of the advantages of this over the usual terminal based interaction are, * The current position of the target program (its "frame") is highlighted; the source file is displayed in a separate window with the current frame marked (in the same way that a block is marked). * You are able to set and delete breakpoints simply by putting the cursor on the line you wish the target to stop at and typing an editor command. To start a gdb subprocess use the `Meta-x gdb' command, you will be asked to enter the name of the program to debug then gdb will be started in a new buffer (called `*gdb*' or similar). You are then able to type commands into the buffer, they will be sent to gdb each time you type the RET key. The commands for controlling the gdb subprocess are as follows (the `Ctrl-c' prefixed commands are only available within the `*gdb*' buffer whereas the `Ctrl-x Ctrl-a' variations are accessible globally so that they can be invoked from within the target's source files), `Ctrl-c Ctrl-n' `Ctrl-x Ctrl-a Ctrl-n' Continue execution to the next source line, this is the gdb command `next'. `Ctrl-c Ctrl-s' `Ctrl-x Ctrl-a Ctrl-s' Continue execution until a different source line is reached, this is the gdb command `step'. `Ctrl-c Ctrl-f' `Ctrl-x Ctrl-a Ctrl-f' Continue running until the current stack frame exits, the `finish' command. `Ctrl-c Ctrl-r' `Ctrl-x Ctrl-a Ctrl-r' Resume execution until a breakpoint is reached or the target exits. `Ctrl-c Ctrl-<' `Ctrl-x Ctrl-a Ctrl-<' Display the stack frame above the current one. `Ctrl-c Ctrl->' `Ctrl-x Ctrl-a Ctrl->' Display the stack frame under the current one. `Ctrl-c Ctrl-b' `Ctrl-x Ctrl-a Ctrl-b' Set a breakpoint at the current source line, if the `*gdb*' buffer is active the line selected is where the program last stopped. `Ctrl-c Ctrl-t' `Ctrl-x Ctrl-a Ctrl-t' Set a temporary breakpoint at the current source line. `Ctrl-c Ctrl-d' `Ctrl-x Ctrl-a Ctrl-d' Remove all breakpoints which are set at the current source line. `Ctrl-c Ctrl-l' `Ctrl-x Ctrl-a Ctrl-l' Redisplay the current frame, centring it in its window. For a summary of these commands type `Ctrl-h m' in the `*gdb*' buffer. Since the gdb process runs on top of the Shell mode the bindings from that mode are also available. There is no limit to the number of gdb processes you may run at once, each will get its own buffer. When a gdb command is invoked in a buffer which doesn't have a gdb subprocess (i.e. a source file's buffer) the command will be sent to the gdb process which either was last sent a command, or last made the editor display a new frame. Hopefully this will work fairly intuitively.  File: jade.info, Node: Using Grep, Next: Keeping ChangeLogs, Prev: Debugging Programs, Up: Compiling Programs Using Grep ---------- It is often very useful to grep through a set of files looking for a regular expression, this is what the `grep' command does. With Jade it is possible to run an external `grep' program in the `*compilation*' buffer. This then enables you to step through each grep hit using the `Ctrl-x `' command, *Note Finding Errors::. The commands to use grep are, `Meta-x grep' Prompt for a string of arguments to give `grep', you do not need to provide the name of the program, or the `-n' switch, this is done automatically. The shell will do any filename-globbing on the arguments so it is advisable to surround the regular expression with single quotes. Note that the regular expression syntax will be different to that which Jade uses. Also this command won't work on an Amiga. `Meta-x grep-buffer' This command provides a method for scanning the current buffer for all lines matching a regular expression (which you are prompted for). It is written entirely in Lisp -- this means that the normal regular expression syntax is needed and it will work on an Amiga.  File: jade.info, Node: Keeping ChangeLogs, Prev: Using Grep, Up: Compiling Programs Keeping ChangeLogs ------------------ A ChangeLog is a file (usually called `ChangeLog') which keeps a log of all changes you have made to the files in its directory. For example, the `src/ChangeLog' file for Jade keeps a list of changes made to the editor's source code. There is no magic involved, you simply use a command to add a new entry to a directory's log after modifying a file in that directory. You then have to enter a summary of the changes that you made. The command to do this is, `Meta-a' Prompts for the name of a directory then lets you type a description of the changes you have made. If you enter more than one change in the same day (and from the same host) the same heading will be used. The heading consists of the time and date, your name, your login and the name of the host you're on. (1) ---------- Footnotes ---------- (1) On the Amiga there is no way to get these details. So, Jade looks for some environment variables, `USERNAME' for the login name, `HOSTNAME' for the name of the host and `REALNAME' for your actual name.  File: jade.info, Node: Info Mode, Next: Shell, Prev: Compiling Programs, Up: Using Jade Info Mode --------- Despite the name of this section there is actually no such thing as the `info-mode'. The Lisp file `info.jl' is what this section documents -- it is a set of Lisp functions which make a buffer (the `*Info*' buffer) into a simple browser for Info files(1). To invoke it type `Ctrl-h i', the `*Info*' buffer will be selected showing the `(dir)' node (the root of the Info documentation tree). When in the `*Info*' buffer the following key bindings are available. `SPC' Displays the next page of the current node. `Backspace' Displays the previous page. `1' Move to the specified menu-item (`1' means the first, etc) in the menu in this node. The keys `1' to `9' work in this way. `b' Move to the beginning of the current node. `d' Display the directory node (`(dir)') of the Info documentation tree. `f' Follow a reference, the one under the cursor if one exists. `g' Prompt for the name of a node and try to display it. `h' Display the Info tutorial node (`(info)Help'). `l' Go back to the last node that was displayed before this one. `m' Prompts for a menu-item (the one on the same line as the cursor is the default) and display the node it points to. `n' Display the next node. `p' Display the previous node. `u' Display the node "above" this one. `q' Quit the Info browser. `?' Display a piece of text describing all commands available in Info mode. `RET' Go to the link (menu item or xref) described on the current line. `LMB-Click2' Go to the link you double clicked on. `TAB' Put the cursor on the next link in this node. `Meta-TAB' Put the cursor on the previous link. This mode has a number of disadvantages over the other Info browsers available (i.e. the stand-alone `info' program, or Emacs' Info viewer): * It depends wholly on being able to find a tag table in the Info file, if it can't it will simply load the whole file into the buffer. * There is no support for the `*' node name. * Seems not to work 100% with files formatted by Emacs, `makeinfo' formatted files work properly though. * No editing of nodes. Of course, its main advantage is that it runs in Jade! ---------- Footnotes ---------- (1) `Info' is the GNU way of creating hypertext documents, for more information see *Note Info: (info)Top.  File: jade.info, Node: Shell, Next: Simple Customisation, Prev: Info Mode, Up: Using Jade Shell ===== When running on a Unix-style operating system Jade allows you to run a shell subprocess in a buffer (usually the `*shell*' buffer). Each line you type in the buffer is sent to the shell and the output from the shell is displayed in the buffer. `Meta-x shell' Start a new shell subprocess running in a buffer called `*shell*'. If a buffer `*shell*' already exists a new buffer with a unique name will be opened (i.e. `*shell*<2>'). The working directory of the shell subprocess will be the directory which the contents of the current buffer was read from. This command won't work on Amigas! Each `*shell*' buffer installs the major mode `shell-mode'. This provides the following commands. `Ctrl-a' Move the cursor to the beginning of the current line, *after* the prompt which the shell printed (if one exists). `Ctrl-d' If the cursor is at the end of the buffer send the shell process the `eof' character (`^D') (signifying the end of the file). Otherwise delete the character under the cursor. `RET' Send the current line to the shell (minus any prompt at the beginning of the line). If the cursor is not on the last line of the buffer (i.e. the most recent prompt) the current line is copied to the end of the buffer before being sent. `Ctrl-c Ctrl-n' Move the cursor to the next prompt in the buffer. `Ctrl-c Ctrl-p' Move to the previous prompt. `Ctrl-c Ctrl-c' Send the `intr' character (`^C') to the shell process. `Ctrl-c Ctrl-d' Send the `eof' character (`^D') to the shell. `Ctrl-c Ctrl-z' Send the `susp' character (`^Z') to the shell. `Ctrl-c Ctrl-\' Send the `quit' character (`^\') to the shell. - Hook: shell-mode-hook This hook is evaluated by the Shell mode after it has initialised itself (and started its subprocess). The following variables customise the actions of the Shell mode. - Variable: shell-file-name This variable defines the file name of the shell to run. Its default value is either the value of the environment variable `SHELL' or if that doesn't exist the file `/bin/sh'. - Variable: shell-whole-line When this variable's value is non-`nil' the RET command always sends the whole of the current line (minus any prompt) even when the cursor is not at the end of the line. Otherwise only the part of the line before the cursor is sent. The default value of this variable is `t'. - Variable: shell-prompt-regexp This buffer-local variable defines the regular expression used to match the prompt printed by the shell each time it waits for you to enter a shell command. By default it has the value `^[^]#$%>)]*[]#$%>)] *' but this may be incorrect if you have modified your shell's prompt.  File: jade.info, Node: Simple Customisation, Prev: Shell, Up: Using Jade Simple Customisation ==================== The best way to tailor the editor to your own requirements is with your personal startup file. This is called `.jaderc' in your home directory (1), it is a file of Lisp forms evaluated when Jade initialises itself. Usually, setting the values of variables in your startup file is enough to configure Jade how you want, the Lisp function to set a variable is called `setq', it's first argument is the name of the variable, it's second the value you wish to set it to. This value will usually be one of the following data types, `"xyz"' A string `xyz'. `123' `0173' `0x7b' A number, all of the above have the value 123 (in decimal, octal and hexadecimal). `nil' `t' A boolean value, `nil' means false, or not true. `t' is the opposite (in fact, any value not `nil' is true). My `.jaderc' file looks something like this (note that semicolons introduce comments), ;;;; .jaderc -*-Lisp-*- ;; Size of tabs for Lisp source is 2 (setq lisp-body-indent 2) ;; When on an Amiga, flag that I don't want pull down menus (when (amiga-p) (setq amiga-no-menus t)) ;; When editing English-text use auto-filling (add-hook 'text-mode-hook 'fill-mode-on) ;; -with a maximum of 74 characters in a line (setq fill-column 74) ;; Start the edit server (server-open) Most simple customisations can be achieved by simply giving a variable a new value. Use the `setq' special form to do this (a special form is a type of function) as in the examples above. If you wish to set variables interactively use the `set' command: `Meta-x set RET VARIABLE-NAME RET NEW-VALUE RET'. The `add-hook' function adds a function (in this case `fill-mode-on') to be called when the specified hook (in this case `text-mode-hook') is evaluated. The single-quote before the names means that the names are passed as constants; *not* their values. If you don't quite understand what I'm talking about don't worry. For full documentation of Jade's programming language see *Note Programming Jade::. ---------- Footnotes ---------- (1) On the Amiga, your home directory is defined as the contents of the environment variable `HOME'.  File: jade.info, Node: Programming Jade, Next: Reporting Bugs, Prev: Using Jade, Up: Top Programming Jade **************** This chapter of the manual is a full guide to Jade's Lisp programming language, including documentation for most of the built-in functions. * Menu: * Intro:: Introduction and Lisp conventions * Data Types:: Data types and values in Lisp * Numbers:: Integers and arithmetic functions * Sequences:: Ordered sequences of data values * Symbols:: Symbols are uniquely named objects * Evaluation:: Evaluating expressions * Control Structures:: Special forms. Conditionals, loops, etc... * Variables:: Symbols represent named variables * Functions:: Functions are the building blocks of Lisp programs * Macros:: User-defined control structures * Streams:: Data sinks and sources; character streams * Loading:: Programs are stored in files * Compiled Lisp:: Making programs run faster * Hooks:: Hooks allow the extending of Jade * Buffers:: Buffers allow editing of files * Windows:: Windows receive input and display buffers * Positions:: Coordinates in buffers and cursor movement * Marks:: Marks represent the position of a character in a file * Glyph Tables:: Controlling the glyphs rendered for each ASCII character * Input Events:: Objects which represent input events * Keymaps:: Mappings between events and commands * Event Loop:: The event loop reads input events and invokes commands * Editing Files:: Files are edited in buffers * Text:: Functions to edit buffers with * Writing Modes:: Creating new editing modes * Prompting:: Interactively asking the user a question * Files:: Manipulating files in the filing system * Processes:: Jade can launch and control subprocesses when running under Unix * Miscellaneous Functions:: Functions which don't fit elsewhere in this manual * Debugging:: How to debug Lisp programs * Tips:: General recommendations for Lisp programmers  File: jade.info, Node: Intro, Next: Data Types, Up: Programming Jade Introduction ============ As you have probably gathered by now, Jade is largely controlled by its built in programming language: a dialect of Lisp containing many extensions (non-standard data types and functions) to make it suitable for controlling an editor. Through this language Jade can be customised and extended. I have attempted to make the "standard" portion of the language (i.e. anything a normal Lisp would have; not related to editing) as compatible with GNU Emacs Lisp as possible. In some areas this rule doesn't apply, there will usually be a good reason for this. A few functions have been inspired by Common Lisp. The areas of the language which control the *editor* are *not* compatible with Emacs; some functions may be similar but since the two editors are fundamentally different I have not attempted to conform with the Emacs API. All programs written using only the information in this manual should be compatible with future revisions of Jade. This following sections explain some of the most important Lisp concepts and the conventions I've used in this manual. * Menu: * nil and t:: Boolean values in Lisp * The Lisp Reader:: Basic program structure * Notation:: Special glyphs used * Descriptions:: How functions and variables are documented  File: jade.info, Node: nil and t, Next: The Lisp Reader, Up: Intro nil and t --------- The two boolean values in Lisp are the symbols `nil' (FALSE) and `t' (TRUE). Both these symbols always evaluate to themselves (so they do not have to be quoted), any attempt to change their values is an error. All of the conditional instructions regard *anything* which is not `nil' as being TRUE (i.e. not-FALSE). The actual symbol `t' should be used where a TRUE boolean value must be explicitly stated to increase the clarity of the code. This is not the end of the story; `nil' actually has another meaning: it represents the empty list. This is a consequence of how lists are constructed in Lisp, a list of zero elements is stored as the symbol `nil'. To the Lisp system itself there is absolutely no difference between `()' (the notation for a list with zero elements) and `nil' (the symbol nil). When writing code however, the list notation is usually used when the programmer regards the value as a list and the `nil' notation when its value as a boolean is to be emphasised.  File: jade.info, Node: The Lisp Reader, Next: Notation, Prev: nil and t, Up: Intro The Lisp Reader --------------- Lisp programs and functions are stored internally as normal Lisp data objects, the Lisp Reader is the process used to translate textual descriptions of Lisp objects into the data structures used to represent the objects. The Lisp Reader is the collection of internal functions accessed by the `read' Lisp function. It reads a character at a time from an input stream until it has parsed a whole Lisp object. *Note Data Types::.  File: jade.info, Node: Notation, Next: Descriptions, Prev: The Lisp Reader, Up: Intro Notation -------- Wherever an example of evaluating a Lisp form is shown it will be formatted like this, (+ 1 2) => 3 The glyph `=>' is used to show the computed value of a form. When two forms are shown as being exactly equivalent to one another the glyph `==' is used, for example, (car some-variable) == (nth 0 some-variable) Evaluating some forms result in an error being signalled, this is denoted by the `error-->' glyph. (read-file "/tmp/foo") error--> File error: No such file or directory, /tmp/foo  File: jade.info, Node: Descriptions, Prev: Notation, Up: Intro Descriptions ------------ The simplest type of descriptions are the descriptions of variables (*note Variables::.), they look something like, - Variable: grains-of-sand This imaginary variable contains the number of grains of sand in a one-mile long stretch of an averagely sandy beach. Hooks (*note Hooks::.) are also described in this format, the only difference is that `Variable:' is replaced by `Hook:'. Functions (*note Functions::.) and macros (*note Macros::.) have more complex descriptions; as well as the name of the thing being described, they also have a list of arguments which the thing will accept. Each argument in the list is named and may be referred to in the body of the description. Two `special' arguments may be used, `&optional' and `&rest'. They have the same meaning as when used in the lambda-list of a function definition (*note Lambda Expressions::.), that is `&optional' means that all further arguments are optional, and `&rest' means that zero or more argument values are coalesced into a list to be used as the value of the following argument. An example function definition follows. - Function: useless-function FIRST &optional SECOND &rest TAIL This function returns a list consisting of the values SECOND (when undefined the number 42 is used), all the items in the list TAIL and FIRST. (useless-function 'foo 'bar 'xyz 20) => (bar xyz 20 foo) (useless-function '50) => (42 50) Macros and commands (*note Commands::.) are defined in the same way with `Macro:' or `Command:' replacing `Function:'. Special forms (*note Special Forms::.) are described similarly to functions except that the argument list is formatted differently since special forms are, by definition, more flexible in how they treat their arguments. Optional values are enclosed in square brackets (`[OPTIONAL-ARG]') and three dots (`REPEATED-ARG...') indicate where zero or more arguments are allowed.  File: jade.info, Node: Data Types, Next: Numbers, Prev: Intro, Up: Programming Jade Data Types ========== The way that data values are represented in Lisp is fundamentally different to more "conventional" languages such as C or Pascal: in Lisp each piece of data (a "Lisp Object") has two basic attributes, the actual data and a tag value defining the *type* of the object. This means that type checking is performed on the actual data itself, not on the "variable" holding the data. All Lisp objects are a member of one of the primitive types; these are types built into the Lisp system and can represent things like strings, integers, cons cells, vectors, etc... More complex types of object can be constructed from these primitive types, for example a vector of three elements could be regarded as a type `triple' if necessary. In general, each separate type provides a predicate function which returns `t' when applied to an object of its type. * Menu: * Types Summary:: List of the most common types * Read Syntax:: Some types can be constructed from source code * Printed Representation:: All types can be printed * Equality Predicates:: How to test two objects for equality * Comparison Predicates:: Comparing two objects as scalars * Type Predicates:: Each type has a predicate defining it * Garbage Collection:: Reusing memory from stale objects  File: jade.info, Node: Types Summary, Next: Read Syntax, Up: Data Types Types Summary ------------- Each separate data type is documented in its own section, this is a just a table of the more common types. "Integer" 32-bit signed integers. *Note Numbers::. "Cons cell" An object containing two other Lisp objects. *Note Cons Cells::. "List" A sequence of objects, in Lisp lists are not primitive types, instead they are made by chaining together Cons cells. *Note Lists::. "Vector" A one-dimensional array of objects. *Note Vectors::. "String" A vector of characters. *Note Strings::. "Array" An ordered sequence of objects which can be accessed in constant time, either a vector or a string. *Note Sequences::. "Sequence" An ordered sequence of objects, either a list or an array. *Note Sequences::. "Symbol" A symbol is a named object; they are used to provide named variables and functions. *Note Symbols::. "File" A link to a file in the operating system's filing system, allows access to the file as a stream. *Note Files::. "Stream" Serial data sinks and sources. *Note Streams::. "Void" No type, only used in symbols to represent an unset function or variable value. "Buffer" A "space" in which text can be edited, buffers may be displayed in a window and hence edited by the user. *Note Buffers::. "Window" A physical window in the underlying window-system, used for input and output. "Position" A pair of integers, used to represent the coordinates of a character in a buffer. *Note Positions::. "Mark" A position in a specified file, this file may either be a buffer in memory or a named file. *Note Marks::. "Process" An object through which processes may be created and controlled. *Note Processes::. "Glyph Table" A lookup-table which is used to map characters in a buffer to the sequence of glyphs they are rendered as. *Note Glyph Tables::. "Keymap" A set of key-sequence-to-command mappings; when installed in a buffer it controls how the editor reacts to all input from the user. *Note Keymaps::. "Event" An (input-) event from a window.  File: jade.info, Node: Read Syntax, Next: Printed Representation, Prev: Types Summary, Up: Data Types Read Syntax ----------- As previously noted the Lisp reader translates textual descriptions of Lisp objects into the object they describe (source files are simply descriptions of objects). However, not all data types can be created in this way: in fact the only types which can are integers, strings, symbols, cons cells (or lists) and vectors, all others have to be created by calling functions. Note that comments in a Lisp program are introduced by the semi-colon character (`;'). Whenever the Lisp reader encounters a semi-colon where it's looking for the read syntax of a new Lisp object it will discard the rest of the line of input. *Note Comment Styles::. The "read syntax" of an object is the string which when given to the reader as input will produce the object. The read syntax of each type of object is documented in that type's main section of this manual but here is a small taste of how to write each type. Integers An integer is simply the number written in either decimal, octal (when the number is preceded by `0') or hexadecimal (when the number is preceded by `0x'). An optional minus sign may be the first character in a number. Some examples are, 42 => 42 0177 => 127 0xff => 255 -0x10 => -16 Strings The read syntax of a string is simply the string with a double-quote character (`"') at each end, for more details see *Note Strings::. "This is a string" Cons cells A cons cell is written in what is known as "dotted pair notation" and is just the two objects in the cell separated by a dot and the whole thing in parentheses, (CAR . CDR) Lists The syntax of a list is similar to a cons cell (since this is what lists are made of): no dot is used and there may be zero or more objects, (OBJECT1 OBJECT2 OBJECT3 ...) ("foo" ("bar" "baz") 100) The second example is a list of three elements, a string, another list and a number. Vectors The read syntax of a vector is very similar to that of a list, simply use square brackets instead of parentheses, [OBJECT1 OBJECT2 OBJECT3 ...] Symbols A symbol's read syntax is simply its name, for example the read syntax of a symbol called `my-symbol' is, my-symbol  File: jade.info, Node: Printed Representation, Next: Equality Predicates, Prev: Read Syntax, Up: Data Types Printed Representation ---------------------- The "printed representation" of an object is the string produced when the object is printed (with one of the `print' functions), this will usually be very similar to the read syntax of the object (*note Read Syntax::.). Objects which do not have a read syntax *do* have a printed representation, it will normally be of the form, # where the "relevant text" is object-dependent and usually describes the object and its contents. The reader will signal an error if it encounters a description of an object in the format `#<...>'.  File: jade.info, Node: Equality Predicates, Next: Comparison Predicates, Prev: Printed Representation, Up: Data Types Equality Predicates ------------------- - Function: eq ARG1 ARG2 Returns `t' when ARG1 and ARG2 are the same object. Two objects are the same object when they occupy the same place in memory and hence modifying one object would alter the other. The following Lisp fragments may illustrate this, (eq "foo" "foo") ;the objects are distinct => nil (eq t t) ;the same object -- the symbol `t' => t Note that the result of `eq' is undefined when called on two integer objects with the same value, see `eql'. - Function: equal ARG1 ARG2 The function `equal' compares the structure of the two objects ARG1 and ARG2. If they are considered to be equivalent then `t' is returned, otherwise `nil' is returned. (equal "foo" "foo") => t (equal 42 42) => t (equal 42 0) => nil (equal '(x . y) '(x . y)) => t - Function: eql ARG1 ARG2 This function is a cross between `eq' and `equal': if ARG1 and ARG2 are both numbers then the value of these numbers are compared. Otherwise it behaves in exactly the same manner as `eq' does. (eql 3 3) => t (eql 1 2) => nil (eql "foo" "foo") => nil (eql 'x 'x) => t  File: jade.info, Node: Comparison Predicates, Next: Type Predicates, Prev: Equality Predicates, Up: Data Types Comparison Predicates --------------------- These functions compare their two arguments in a scalar fashion, the arguments may be of any type but the results are only meaningful for numbers, strings (ASCII values of each byte compared until a non-matching pair is found then those two values are compared as numbers) and positions. - Function: > ARG1 ARG2 Returns `t' when ARG1 is `greater than' ARG2. - Function: >= ARG1 ARG2 Returns `t' when ARG1 is `greater than or equal to' ARG2. - Function: < ARG1 ARG2 Returns `t' when ARG1 is `less than' ARG2. - Function: <= ARG1 ARG2 Returns `t' when ARG1 is `less than or equal to' ARG2.  File: jade.info, Node: Type Predicates, Next: Garbage Collection, Prev: Comparison Predicates, Up: Data Types Type Predicates --------------- Each type has a corresponding predicate which defines the objects which are members of that type. * `integerp' * `numberp' * `null' * `consp' * `listp' * `vectorp' * `subrp' * `functionp' * `sequencep' * `stringp' * `symbolp' * `posp' * `bufferp' * `windowp' * `markp' * `processp' * `filep' * `keymapp' * `eventp' * `commandp' The documentation for these functions is with the documentation for the relevant type.  File: jade.info, Node: Garbage Collection, Prev: Type Predicates, Up: Data Types Garbage Collection ------------------ In Lisp, data objects are used very freely; a side effect of this is that it is not possible to (easily) know when an object is "stale", that is, no references to it exist and it can therefore be reused. The "garbage collector" is used to overcome this problem; whenever enough new data objects have been allocated to make it worthwhile, everything stops and the garbage collector works its way through memory deciding which objects are still in use and which are stale. The stale objects are then recorded as being available for reuse and evaluation continues again. - Function: garbage-collect Runs the garbage collector, usually this function doesn't need to be called manually. - Variable: garbage-threshold The number of bytes of data which must be allocated before evaluation will pause and the garbage collector called. Its default value is about 100K. *Note Idle Actions::.  File: jade.info, Node: Numbers, Next: Sequences, Prev: Data Types, Up: Programming Jade Numbers ======= Currently Jade is only capable of representing integers, for this it uses signed 32-bit integers: this gives a range of -2147483648 through 0 to 2147483647. The read syntax of an integer is simply the number written in decimal, octal or hexadecimal. If the integer starts with the string `0x' it is assumed to be hexadecimal or if it starts with a zero it is treated as octal. The first character may be an optional minus or plus sign (this should come before any base-specifier). Examples of valid integer read syntaxes for the number 42 could be `42', `0x2a', `052', `+052', ... An integer's printed representation is simply the number printed in decimal with a preceding minus sign if it is negative. - Function: numberp OBJECT This function returns `t' if OBJECT is a number. - Function: integerp OBJECT This function returns `t' when OBJECT is an integer. * Menu: * Arithmetic Functions:: Adding and substracting... * Bitwise Functions:: Using integers as bit-sequences * Numeric Predicates:: Comparing numbers * Characters:: Integers are used to represent characters  File: jade.info, Node: Arithmetic Functions, Next: Bitwise Functions, Up: Numbers Arithmetic Functions ==================== There are a number of functions which perform arithmetic operations on numbers, they take a varying number of integer objects as their arguments then return a new integer object as their result. Note that none of these functions check for overflow. - Function: + NUMBER1 &rest NUMBERS This functions adds its arguments then returns their sum. - Function: - NUMBER1 &rest NUMBERS If this function is just given one argument (NUMBER1) that number is negated and returned. Otherwise each of NUMBERS is subtracted from a running total starting with the value of NUMBER1. (- 20) => -20 (- 20 10 5) => 5 - Function: * NUMBER1 &rest NUMBERS This function multiplies its arguments then returns the result. - Function: / NUMBER1 &rest NUMBERS This function performs division, a running-total (initialised from NUMBER1 is successively divided by each of NUMBERS then the result is returned. (/ 100 2) => 50 (/ 200 2 5) => 20 - Function: % DIVIDEND DIVISOR Returns the remainder from dividing DIVIDEND by DIVISOR. (mod 5 3) => 2 - Function: 1+ NUMBER This function returns the result of adding one to NUMBER. (1+ 42) => 43 - Function: 1- NUMBER Returns NUMBER minus one.  File: jade.info, Node: Bitwise Functions, Next: Numeric Predicates, Prev: Arithmetic Functions, Up: Numbers Bitwise Functions ================= These functions operate on the bit string which an integer is made of. - Function: lsh NUMBER COUNT This function bit-shifts the integer NUMBER COUNT bits to the left, if COUNT is negative NUMBER is shifted to the right instead. (lsh 1 8) => 256 (lsh 256 -8) => 1 - Function: ash NUMBER COUNT Similar to `lsh' except that an arithmetical shift is done, this means that the sign of NUMBER is always preserved. (ash 1 8) => 256 (ash -1 2) => -4 - Function: logand NUMBER1 &rest NUMBERS This function uses a bit-wise logical `and' operation to combine all its arguments (there must be at least one argument). (logand 15 8) => 8 (logand 15 7 20) => 4 - Function: logior NUMBER1 &rest NUMBERS Uses a bit-wise logical `inclusive-or' to combine all its arguments (there must always be at least one argument). (logior 1 2 4) => 7 - Function: logxor NUMBER1 &rest NUMBERS Uses a bitwise logical `exclusive-or' to combine all its arguments (there must be at least one). (logxor 7 3) => 4 - Function: lognot NUMBER This function inverts all the bits in NUMBER. (lognot 0) => -1 (lognot 2) => -3 (lognot -1) => 0  File: jade.info, Node: Numeric Predicates, Next: Characters, Prev: Bitwise Functions, Up: Numbers Numeric Predicates ================== For the documentation of the functions `>', `<', `>=' and `<=' see *Note Comparison Predicates::. - Function: = NUMBER1 NUMBER2 This function returns `t' if the two integers NUMBER1 and NUMBER2 have the same value. (= 1 1) => t (= 1 0) => nil - Function: /= NUMBER1 NUMBER2 This function will return `t' if NUMBER1 and NUMBER2 and not equal to each other. (/= 1 1) => nil (/= 1 0) => t - Function: zerop NUMBER Returns `t' if NUMBER is equal to zero.