allbery@uunet.UU.NET (Brandon S. Allbery - comp.sources.misc) (06/11/89)
Posting-number: Volume 7, Issue 24
Submitted-by: fox@marlow.UUCP (Paul Fox)
Archive-name: crisp1.9/part04
#!/bin/sh
# this is part 3 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file help/crisp/features/Options.hlp continued
#
CurArch=3
if test ! -r s2_seq_.tmp
then echo "Please unpack part 1 first!"
exit 1; fi
( read Scheck
if test "$Scheck" != $CurArch
then echo "Please unpack part $Scheck next!"
exit 1;
else exit 0; fi
) < s2_seq_.tmp || exit 1
echo "x - Continuing file help/crisp/features/Options.hlp"
sed 's/^X//' << 'SHAR_EOF' >> help/crisp/features/Options.hlp
Xexpressions typed at the 'Search fwd:' and 'Search back:'
Xprompts are to be CRISP style regular expressions or Unix
Xstyle regular expressions.
X
X> The Tabs Option
X
XThis option is used to turn on or off hard or soft tabs.
SHAR_EOF
echo "File help/crisp/features/Options.hlp is complete"
chmod 0644 help/crisp/features/Options.hlp || echo "restore of help/crisp/features/Options.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Program.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Program.hlp &&
XThis section describes the features in the programming
Xutilities menu. Some of these macro are normally mapped to
Xthe keyboard but can be difficult to remember where on the
Xkeyboard they are.
X
X> The Match Brackets Macro
X
XThis macro emulates the vi '%' function. If the cursor is
Xcurrently located on a bracket - either open or close
X(round, curly or square - (), [], {}), then the cursor is
Xmoved to the matching bracket. Alternate calls to this
Xmacro take you back to where you started.
X
XThis macro is very useful when writing C code, or CRISP
Xmacros which use macros to indicate language blocks, and a
Xmissing bracket somewhere can result in spurious syntax
Xerrors from the compiler.
X
XThis macro does not take into account brackets inside
Xstring literals, string constants or comments.
X
X> The Find Function Macro
X
XThis macro is similar to the vi tags macro. A function
Xname should be typed in at the 'Function:' prompt, and
XCRISP will take you to the file in which that function
Xexists and put the cursor on the line of the function
Xdefinition.
X
XThis macro relies on the standard Unix utility 'ctags' to
Xgenerate a tags file. A tags file is a file which contains
Xa list of all functions in all the files in the current
Xdirectory together with a line used to select that file.
X
XAt the moment, this function can only be used with C
Xfunction definitions or CRISP macro definitions, since
Xctags only works with .c files. In order to create a tags
Xfile for CRISP macros, use the (mtags) macro. The (mtags)
Xmacro will generate a tags file from all the .m files in
Xthe current directory.
X
X
X> The List Functions Macro
X
XThis macro is used to generate an index of all the
Xfunctions or sections in the current buffer. This function
Ximplements the (routines) macro. The routines macro can be
Xused on the following file types:
X
X .c C source files.
X .h C header files.
X .m macro files.
X .mm nroff/troff text files using the -mm macros.
X .hlp Text files using the '>' section delimiter.
X .asm Finds all PROC/proc definitions.
X .s Finds all assembler labels.
X .y Finds all yacc grammar definitions.
X
XA pop-up window is displayed with a list of the functions
Xor sections displayed. The cursor can then be used to
Xselect a function and if <Enter> is hit, then the cursor
Xis taken to the start of the appropriate function or
Xsection.
X
XThe <Alt-C> key is mapped, and if pressed causes the
Xbuffer containing the list of functions/sections to be
Xcopied to the scrap. This allows the user to easily
Xgenerate a list of functions/sections in the current
Xbuffer and can then insert this list at the top of the
Xcurrent buffer, for example. Some people like to list the
Xfunctions defined in the current file at the top of the
Xfile, and so this is provided for them.
X
XThe (routines) macro uses the file extension to
Xdistinguish how to find the functions or sections. .h
Xfiles are treated as C program include files. This means
Xthat using the routines macro on CRISP .h files is not
Xpossible, unless you change the default behaviour for the
Xroutines macros.
X
XSelecting a .h file causes all typedef's and struct
Xdefinitions to be displayed.
X
XFor .mm files, the sections are delimited by lines that
Xstart with the .TH, .SH, or .H macros.
X
SHAR_EOF
chmod 0644 help/crisp/features/Program.hlp || echo "restore of help/crisp/features/Program.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Region.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Region.hlp &&
XThis section describes the macros which can be used on
Xmarked areas of the buffer.
X
X> Justifying Text
X
XThis macro can used to format and justify text. This macro
Xcan be used with text files or C programs for pretty
Xcomments.
X
XThe text to be justified should be first highlited.
XJustifying text can be done to produce ragged margins or
Xright justified margins. The margin is set to a default of
X60. This can be altered by setting the option in the
XOptions menu (under Documents).
X
XAll the text in the CRISP help files was justified using
Xthis feature.
X
XText with C comments can be justified as well. This is
Xdone by first stripping off any comment characters at the
Xstart and end of each line in the region, justifying the
Xraw text, and then putting back the start and end of line
Xcharacters. Currently justification of C comments can only
Xbe performed for comments which are to appear at the start
Xof the line, ie it cannot be done with comments which are
Xto maintain alignment with C code.
X
XThis macro is usually mapped to the <Ctrl-F> key.
X
X> Lower and Uppercasing Text
X
XText highlited by a marker can be turned to lower or upper
Xcase using the 'Lower case text' or 'Upper case text'
Xoptions from the Regions menu.
X
X> Indenting Block
X
XText which has been highlited can be indented or
Xunindented by selecting the 'Indent Block' or 'Unindent
XBlock' options from the Regions menu.
X
XIndenting is performed by inserting a <Tab> character at
Xthe start of each line in the block.
X
XUnindenting is performed by removing the first <Tab> at
Xthe start of each line.
X
XThe indent and unindent macros do not currently support
Xfiles using soft tabs.
X
XThis feature calls the (<<) and (>>) macros. (These macros
Xare so named because they are the names for the same
Xfeature in 'vi').
SHAR_EOF
chmod 0644 help/crisp/features/Region.hlp || echo "restore of help/crisp/features/Region.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Buflist.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Buflist.hlp &&
XThe (buffer_list) macro pops up a window which can be used
Xto see what buffers have been created, and which files are
Xin those buffers. This macro is usually mapped to the
X<Alt-B> key sequence.
X
XThe cursor keys can be used to scroll through the list of
Xbuffers. Pressing the <Enter> key makes that buffer the
Xcurrent buffer.
X
XPressing 'W' or 'w' will write the buffer away, as if an
X<Alt-W> had been done on the buffer.
X
XPressing 'D' or 'd' will delete the buffer. If the buffer
Xhas been modified, then you will be prompted to see if you
Xare sure. You cannot delete a buffer which is currently on
Xdisplay in a window.
X
XThe display consists of a number of fields:
X
X - an index field for fast selection.
X - the number of lines in the buffer.
X - the current line number.
X - flag settings.
X - the full file-name of the buffer.
X
XThe flag settings are as follows:
X
X * if buffer has been modified.
X P if buffer has a process attached.
X B if buffer will be backed up on saving.
X R if buffer is read-only.
SHAR_EOF
chmod 0644 help/crisp/features/Buflist.hlp || echo "restore of help/crisp/features/Buflist.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Spell.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Spell.hlp &&
XThe spell macro is used to check the current buffer for
Xspelling errors. It can either be called from the Features
Xmenu, or via the (spell) macro from the Command: prompt.
X
XThe standard Unix utility 'spell' is needed for this macro
Xto work. The output of the spell program is read into a
XCRISP buffer, and the macro goes through the list of bad
X(or questionable) spellings and prompts the user to change
Xthe entry.
X
XIf the user hits <Enter> at the word prompted for, then
Xthe spell macro goes on to the next word in the list. The
Xuser can type in a different spelling or modify the
Xdefault value at the prompt.
X
XIf the user modifies a word in error, then the (translate)
Xmacro is used to change all occurences of the mis-spelled
Xword in the current buffer. The (translate) macro prompts
Xthe user for each word to be replaced. This is done
Xbecause sometimes the (translate) macro may matched part
Xof a word unintentionally.
X
XIf the user aborts the spelling checking (via <Esc>), then
Xhe/she can return to checking the next word by using the
X<Ctrl-N> or <Ctrl-P> keys. <Ctrl-N> goes on to the next
Xword in the list; <Ctrl-P> selects the previous word in
Xthe list.
X
SHAR_EOF
chmod 0644 help/crisp/features/Spell.hlp || echo "restore of help/crisp/features/Spell.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Wc.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Wc.hlp &&
XThis macro counts how many words there are in the current
Xbuffer and displays the average word length.
X
XThis macro can also be accessed at the Command: prompt by
Xtyping 'wc'.
X
XThis macro uses the Unix 'wc' program to perform the word
Xcounting.
X
SHAR_EOF
chmod 0644 help/crisp/features/Wc.hlp || echo "restore of help/crisp/features/Wc.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Shell.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Shell.hlp &&
XThis option allows the user to create a shell-buffer. A
Xshell buffer is a buffer which has a PTY attached, and
Xacts like a window onto the process underneath. The user
Xcan type in any normal shell commands.
X
XThe cursor movement keys can be used to scroll through the
Xbuffer and the editing keys can be used to edit any part
Xof the current command line using the full power and
Xflexibility of CRISP.
X
XIn addition, the <Ctrl-N> and <Ctrl-P> keys are mapped to
Xallow easy access to previously typed in commands. The
Xshell macro saves the last 20 commands typed in, and these
Xkeys can be used to scroll through the commands typed in.
X(This is similar to the history editing facility of the
XKorn-shell).
X
XSelecting this option from the menu automatically creates
Xa shell window using the C-shell. If you prefer to use the
XBourne shell or Korn Shells, then you can use the 'sh' or
X'ksh' commands at the Command prompt. (The Korn shell
Xoption will only work if you have the Korn shell installed
Xon your system).
X
XNote that the shell macros shouldn't be used with programs
Xwhich operate in single character input mode, eg vi,
Xtelnet, etc. CRISP does not know that these program
Xoperate in single character input mode, and the input will
Xget mangled.
X
X
SHAR_EOF
chmod 0644 help/crisp/features/Shell.hlp || echo "restore of help/crisp/features/Shell.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Abbrev.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Abbrev.hlp &&
XThis menu is the abbreviations menu. It has been selected
Xbecause you typed the <Tab> key at the command prompt and
Xthe word you have partially typed is ambiguous. The
Xentries in this menu are the available valid options which
Xmatch your partially typed in input.
X
XIf you wish to select one of these items, use the cursor
Xkeys to move to the selection and press <Enter>. If you do
Xnot want to select one of these options, type <Esc>.
X
XIf you select one of these inputs, the prompt will change
Xas if you had typed in the word in full.
SHAR_EOF
chmod 0644 help/crisp/features/Abbrev.hlp || echo "restore of help/crisp/features/Abbrev.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/AbbFiles.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/AbbFiles.hlp &&
XThis menu is selected because you have partially typed a
Xfilename at the prompt. This menu is a selection of the
Xfiles in the current directory or within the directory
Xpartially typed by you.
X
XYou can use the arrow keys to scroll through the
Xselection. Pressing <Enter> on a filename will the current
Xprompt to treat that as if you had typed it in yourself.
X
XFilenames ending in '/' indicate directories. Selecting a
Xdirectory will update the menu display with all files in
Xthat directory. Selecting the '..' entry allows you to
Xwalk up the directory path.
SHAR_EOF
chmod 0644 help/crisp/features/AbbFiles.hlp || echo "restore of help/crisp/features/AbbFiles.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Ascii.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Ascii.hlp &&
XThis macro can be used to obtain a quick reference ASCII
Xwall chart. The (ascii) macro supports the ability to
Xdisplay the ascii characters in hexadecimal, octal or
Xdecimal formats.
SHAR_EOF
chmod 0644 help/crisp/features/Ascii.hlp || echo "restore of help/crisp/features/Ascii.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Calc.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Calc.hlp &&
XThe (calc) macro displays a calculator which can be used
Xfor simple arithmetic operations. The calculator window
Xlooks like a normal pocket calculator. Features of the
Xcalculator are:
X
X - Supports 32 bit integers
X - Supports AND, OR, XOR and NOT
X - 10 number memory.
X - Easy to use base conversions.
X
XThe calculator display has two main areas - the top line
Xwhich contains the value of the current expression, and a
Xbase indicator. The base indicator (DEC, OCT or HEX)
Xappears to the left of the line. This is the base that
Xnumbers may be typed in and the base that results are
Xdisplayed in.
X
XNumbers may be typed in using the keys: 0-9 and a-f (for
Xhex numbers). The following operators are supported:
X
X + 32 bit addition
X - 32 bit subtraction
X * 32 bit multiplication
X / 32 bit division
X % 32 bit remainder
X A 32 bit logical AND
X R 32 bit logical OR
X X 32 bit logical XOR
X
XIn addition, the following unary operators may be used:
X
X S changes sign of number on display.
X N 1's complement of number on display.
X
XThe following base conversions are available:
X
X H change base to hex
X O change base to octal
X D change base to decimal
X
XIn addition the calculator has a 10-number memory. The
Xmemories are accessed via the following key sequences:
X
X rN recall memory N
X sN store number on display in memory N
X
Xwhere N is a digit (0-9) representing the memory. The
Xcalculator macro prompts the user for the memory number
Xafter the 'r' and 's' commands.
X
SHAR_EOF
chmod 0644 help/crisp/features/Calc.hlp || echo "restore of help/crisp/features/Calc.hlp fails"
mkdir help help/crisp help/crisp/features >/dev/null 2>&1
echo "x - extracting help/crisp/features/Mail.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/features/Mail.hlp &&
XThe following sections describe how to use the mail
Xfacility of CRISP.
X
XWhen the mail macro is selected, either from the Features
Xmenu or directly from the keyboard prompt, the mail macro
Xchecks your mail file. The mail file is usually located in
X/usr/spool/mail/USERNAME. If there is no file by this
Xname, then the mail macro simply says 'There is no mail
Xfor you.'
X
XIf the mail file exists and is not empty, then the mail
Xfacility pops up a window, similar to the 'Buffer List'
Xwindow showing you the items in the mail file.
X
XEach line of the list consists of four fields - a message
Xnumber field; a field containing the Subject: line; the
Xnumber of lines in the message (including headers) in
Xsquare brackets. The last field is who the message is from.
X
XThe usual cursor movement keys may be used to navigate
Xthrough the selection menu. Hitting <Enter> at an entry
Xpops up a window containing the message selected. The user
Xmay scroll through the message.
X
XThe save ('s' or 'S') and write ('w' or 'W') commands may
Xbe used to save a message away. These commands are
Xsimilar, except that the Save command does not include the
Xheader lines, whereas the Write command does. The user is
Xprompted for a file name in which to place the file
Xcontents. The default file is ~/mbox. When the file is
Xsaved, the entry in the selection menu is marked as
X'<Message Deleted>'.
X
XThe Delete command ('d' or 'D') allows the user to delete
Xa message. The message entry in the window is marked with
Xthe '<Message Deleted>' message. Deleted messages cannot
Xcurrently be undeleted. The message itself is not deleted
Xuntil the user exits the mail selection menu (via <Esc>).
XIf you delete a message and wish to un-delete the message,
Xthe best thing to do is use the Quit command.
X
XThe Quit command ('q' or 'Q') aborts the mail reading
Xsession without updating the users mail file.
X
XTo exit from the mail macro, use the '<Esc>' key. This
Xwill update the users mail file by deleting all read or
Xdeleted messages from it. The users spool mail is written
Xback using the (write_buffer) primitive and thus a backup
Xfile will be put in the standard place. This may be
Xconsidered either a feature or a potentially serious
Xsecurity hole.
X
X> Mail Watching
X
XWhen the mail macro is loaded, it registers itself with
Xthe idle timer. Whenever the idle timer goes off, the
Xmacro checks to see if new mail has arrived and prints the
Xmessage: "There is new mail."
X
X> Bugs
X
XThe mail macro currently does not allow you to reply to
Xmail messages.
X
XWhen in the message pop-up window, you should be able to
Xsave/write the buffer contents.
X
XThe macro should check to see if the mail file has been
Xupdated before updating it.
X
SHAR_EOF
chmod 0644 help/crisp/features/Mail.hlp || echo "restore of help/crisp/features/Mail.hlp fails"
mkdir help help/crisp help/crisp/lang >/dev/null 2>&1
echo "x - extracting help/crisp/lang/Macros.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/lang/Macros.hlp &&
XThis section describes what a macro file is and how they
Xare created.
X
XA macro file is an ASCII file which contains a sequence of
Xprogram statements which are interpreted by CRISP in order
Xto add higher-level functions to help in the process of
Xcreating and editing files.
X
XThis help package is an example of a set of macros.
X
XCRISP itself consists of a macro-language interpreter
Xtogether with about a set of 250 builtin primitives which
Xunderstand the concepts of buffers, windows, files, etc.
X
X> File Name Conventions
X
XThere are two types of macro files - the raw source files,
Xwhich usually have the extension '.m', and compiled macro
Xfiles, which usually have the extension '.cm'.
X
XCompiled macro files are loaded much faster than the raw
Xsource files. The source files are meant to be readable by
Xhumans; compiled files are only readable by CRISP.
XCompiled files are designed to be loaded quickly.
X
X> The Macro Compiler
X
XCRISP comes with two programs - 'cr' which is the main
Xeditor, and a macro compiler, called 'cm'. cm takes .m
Xfiles, compiles them, checks for syntax errors, and
Xproduces .cm files as output.
X
X> Syntax of a Source File
X
XA source file generally consists of the following:
X
X - zero or more #include directives.
X - zero or more #define directives.
X - one or more macro definitions.
X
X> Comments
X
XCRISP source files may be commented. There are currently
Xthree styles of commenting. When CRISP encounters a ';'
X(semicolon) in a line outside of double-quotes, it assumes
Xthe rest of the line is a comment.
X
XThe alternative style of comments is to use the sequence
Xof characters '//'. Like semicolon, all characters up
Xuntil the end of line are ignored. This alternative is not
Xa preferred way of commenting, and is subject to removal
Xin a later version of the software.
X
XThe other form of commenting is C commenting, ie using the
Xnon-nesting /* and */ comment delimiters.
X
XComments should be used freely - they do not affect the
Xspeed of execution of macros, and are stripped from the
Xinput files when loading or compiling.
X
X> The #include Directive
X
XThe #include directive is similar to that of C, it causes
Xthe named file to be textually included at the point it is
Xreferenced.
X
XThe syntax is:
X
X # include "file-name"
X
Xor
X
X # include <file-name>
X
Xwhere file-name is the name of the file to be included.
X
XCRISP searches a number of directories in order to find
Xthe named file. The order of searching is as follows:
X
X 1. If the ".." form is used then CRISP tries to access
X file-name in the current directory. If the <..>
X form is used, then CRISP skips to step 3.
X 2. Then it tries the same directory where the original .m
X file was included.
X 3. Then it tries all directories in the BPATH environment
X variable.
X
XThe #include directive may occur anywhere - even in the
Xmiddle of macros, although it is good style to keep them
Xat the top of a .m file.
X
X> The #define Directive
X
XThe #define directive is similar to that of C, but is not
Xas generic. The current version of CRISP does the #define
Xparsing itself, and does not implement the full
Xfunctionality of the C #define.
X
XThe syntax of a #define is:
X
X # define VAR "string"
X
Xor
X
X # define VAR number
X
Xwhere number is limited to a single number in decimal or
Xhexadecimal format. Generic expressions are not allowed
Xfor the macro expansion of VAR.
X
XVAR has the same syntax as any other variable in the
Xlanguage.
X
XAs CRISP parses a macro language, it checks every token to
Xsee if it matches a #define macro variable. If so, it
Xreplaces the token with the value specified in the #define.
X
X> Tokens of the Language
X
XCRISP parses the input file, strips comments and performs
Xmacro and #include substitution. After this raw
Xprocessing, CRISP is left with a stream of tokens. There
Xare only a few token types in the language:
X
X - Open Bracket - (
X - Close Bracket - )
X - Identifier
X - Numeric Constant
X - String Constant
X
XBrackets are used to delimit statements and blocks of
Xstatements.
X
X> Syntax of an Identifier
X
XAn identifier may consist of the following characters:
X
X - Alphabetics A-Z, a-z
X - Numerics 0-9
X - Specials _, +, -, /, *, =, !, <, >, %, &, |, ~, $
X
XAn identifier can start with any of the above, except a
Xnumeric.
X
XFor example, the following are valid identifiers:
X
X fred
X _fred
X _fred_&_harry
X ---
X <_>
X
XIdentifiers are used as the names of macros, CRISP builtin
Xprimitives, and as variables. Identifiers containing
Xspecial characters other than '_' should be avoided since
Xa future release of CRISP may use these characters as
Xdelimiter characters.
X
X> Numeric Constants
X
XA numeric token is used to contain a literal number.
XInteger variables in the language are internally
Xrepresented as 2's complement 32-bit integers. Numeric
Xliterals are restricted to this range.
X
XNumeric constants may be classified as one of the following:
X
X - Decimal constants
X - Octal Constants
X - Hex constants
X - Character constants.
X
XA decimal constant simply consists of a sequence of
Xdigits, the first of which may not be zero.
X
XAn octal constant consists of the digits 0-7, with the
Xfirst digit being zero. (If the first digit is not a zero,
Xthen it is treated as a decimal number).
X
XA hex constant consists of the string '0x' or '0X'
Xfollowed by a sequence of hex digits.
X
XThe following show examples of constants:
X
X 10 integer constant
X 0 zero.
X 007 octal constant, value 7 decimal.
X 0377 octal constant, value 255 decimal.
X 0x1f octal constant, value 31 decimal.
X
X> Character Constants
X
XA character constant consists of an expression surrounded
Xby apostrophes ('). A simple character constant would be
X'a', which is an integer number with the value of the
XASCII letter "a". CRISP understands some of the ANSI X3J11
XC standards committee character escapes:
X
X - \t, \n, \f, and \r stand for the ASCII value of the
X tab, newline, formfeed and carriage-return characters.
X - \x followed by one or two hex digits stands for the
X character whose ASCII value is represented by
X the hex digits.
X - \X where X is any other character allows character X
X to appear in a character constant.
X
XThe following are some examples of character constants:
X
X 'a' character constant, value 101 decimal.
X '\f' character constant, value 12 decimal.
X '\'' character constant, value 39 decimal.
X
X> String Constants
X
XString constants are sequences of characters enclosed in
Xdouble-quotes. Any character except a new-line may appear
Xin a string constant.
X
XString constants support the notion of escaping to allow
Xotherwise illegal characters into the string. The escaping
Xis performed with the backslash character. The same class
Xof backslash escapes may be performed as for character
Xconstants.
X
X> Syntax of a List Expression
X
XApart from the #include and #define statements, the CRISP
Xlanguage has a very regular appearance. It is very similar
Xto LISP, and consists of sequences of statements enclosed
Xin brackets.
X
XAt the innermost level, a list (or statement) looks like
Xthis:
X
X (id-1 [id-2 [id-3 ..]])
X
Xwhere id-1 is either an identifier, a string literal, or
Xnumeric literal. There may be one or more identifiers
Xwithin the brackets.
X
XAt the next level, an identifier can itself be a list, e.g.
X
X (1 (2 3) 4)
X
Xis a list containing three elements (or atoms), the second
Xof which is a list itself, consisting of two integers.
X
X> Syntax of a Macro Definition
X
XA macro definition is a list, as follows:
X
X (macro name list)
X
Xwhere 'macro' is the name of the CRISP builtin 'macro',
Xwhich is used to declare a macro. name is an identifier
X(conforming to the rules described above). list is a
Xsequence of lists which will be executed when the
Xidentifier, name, appears during the course of execution
Xof other macros.
X
XFor example, the following declares a macro, which prints
Xthe result of adding the two integer arguments passed to it:
X
X (macro sum
X (
X (int x y)
X (get_parm 0 x)
X (get_parm 1 y)
X (message "%d + %d = %d" x y (+ x y))
X )
X )
X
XIn this case, the macro sum has associated with it a list
Xwhich consists of 4 sub-lists which consists of calls to
Xvarious CRISP primitives.
X
XIf a macro file contains a macro called '_init' then when the
Xmacro file is loaded, this macro will be executed first. This
Xallows the user to perform some initialisation actions before
Xany of the other macros get to execute.
X
X> Parsing the Language
X
XWhen CRISP executes a macro, it performs the following steps in
Xevaluating the language:
X
X - if the current execution item is a list, execute
X the first atom in the list. (This is a recursive step).
X - if the current execution item is an identifier, look
X to see if it is a builtin. If so, evaluate the rest
X of the list as the arguments for the builtin.
X - if the current execution item is an identifier, look
X to see if it is a macro name. If so, execute the
X list associated with the macro. The rest of the original
X list is saved as the arguments to the macro.
X - if the current execution item is an integer, place its
X value in the accumulator.
X - if the current execution item is a string, place its value
X in the accumulator.
X
XWhat this all means is that the following are valid macros:
X
X (macro x (message "hello"))
X (macro x ((message "hello")))
X (macro x ((message "hello") ())))
SHAR_EOF
chmod 0644 help/crisp/lang/Macros.hlp || echo "restore of help/crisp/lang/Macros.hlp fails"
mkdir help help/crisp help/crisp/lang >/dev/null 2>&1
echo "x - extracting help/crisp/lang/Vars.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/lang/Vars.hlp &&
XThis section describes the builtin data types which CRISP
Xcan support in the macro language.
X
XCRISP supports three basic data types:
X
X - 32-bit two's complement integers.
X - variable length strings.
X - variable length lists.
X
XCRISP supports named variables, which may have one of
Xthree storage classes:
X
X - local variables
X - global variables
X - buffer-local variables
X
X> Integers
X
XIntegers are used mainly for counting, eg lines in the
Xbuffer, loop counts, etc. CRISP provides a variety of
Xprimitives for handling integers.
X
XThe integer data type is designed to be machine
Xindependent and thus you can always guarantee that at
Xleast 32-bit precision will be available.
X
X> Strings
X
XStrings are used to store character information. There is
Xno intrinsic limit to the size of a string. On some
Xmachines strings are limited to 64K-1 in size, and on
Xothers, upto 2^32-1 bytes.
X
XThese limits should be more than ample for any
Xapplication. Any application wanting to create strings
Xlarger than these limits should probably consider an
Xalternative implementation strategy.
X
XStrings are dynamic in nature and are allocated as much
Xspace as is needed. No pre-allocation is necessary. There
Xare no internal limits (as there are in BRIEF).
X
XThe internal strategy for strings is to increase the
Xmemory allocated for strings when they need it. Initially
Xall strings start off as the null (zero-length string). It
Xis probably a bad idea to create a global string and
Xassign a large string to it, since the storage allocated
Xto the string will stay in existence for ever, or until
Xthe string gets bigger. CRISP makes no attempt to truncate
Xthe memory allocated to strings. This is done in the
Xinterests of efficiency, and the common case is for
Xstrings to not be very long, so the wastage is not
Ximportant.
X
XUnderstanding the strategy used for string allocation is
Ximportant if anyone is contemplating writing a macro which
Xtries to read the entire contents of a buffer into one
Xstring variable.
X
X> Lists
X
XLists are very useful data types for storing collections
Xof data items. CRISP does not support arrays, records or
Xstructures. Instead it only supports lists.
X
XLists may be considered as anonymous structures, or
Xvariable length arrays.
X
XA list is defined as a sequence of zero or more atoms. A
Xlist with no atoms in it is referred to as the null list.
X
XAn atom may be either an integer, string or another list.
X
XLists are defined either as literal constants in a macro
X(see (quote_list)), or may be built up by adding atoms to
Xan existing list.
X
XThere is no intrinsic limit to the number of items in a
Xlist.
X
XLists are provided to make some operations easier, and to
Xovercome some of the difficulties in programming macros.
X
XIt must be understood that lists are designed to provide a
Xmore efficient way of constructing certain classes of
Xmacros. Although the lists in CRISP are very powerful,
Xtheir implementation leaves a lot to be desired.
X
XLists provide a half-way house between that of BRIEF and
Xthat of Emacs. BRIEF is well known for being a very
Xpowerful editor with its macro programming language, but
Xis not very good at dealing with data types more
Xcomplicated than integers or strings. Emacs on the other
Xhand is a full blown Lisp interpreter which is very large
Xand expensive on virtual memory.
X
XCRISP needs more memory in its operation than BRIEF does,
Xbut is not as demanding as Emacs. Macros which cause lists
Xto be copied around will suffer badly in execution speed.
XLists should be used mainly small collections of objects
X(say 10-100).
X
X> The NULL data type
X
XCRISP supports the notion of a data type which has no
Xvalue and no type. This is referred to as NULL. NULL is
Xthe default value of lists (after they have been declared
Xvia the (list) macro, for example).
X
XThe NULL data type is also sometimes needed as a place
Xholder when calling macros. The arguments to other macros
Xand CRISP builtins are specified by their position in the
Xargument list. In order to allow a non-value to be passed
Xto the CRISP builtins the NULL identifier can be specified.
X
XSome CRISP macros allow NULL arguments, and in some cases
Xthe primitives will prompt the user for the missing
Xvalues, eg the pattern to search for in (search_fwd).
X
X> Storage Classes
X
XCRISP supports three types of storage classes - local,
Xglobal, and buffer local.
X
XLocal variables are similar to any other language. Local
Xvariables in CRISP are dynamically bound. This means that
Xif the following two macros are defined:
X
X (macro x
X (
X (int alpha)
X (y)
X )
X )
X (macro y
X (
X (message "alpha=%d" alpha)
X )
X )
X
Xthen the variable alpha is available to macro y, only if
Xmacro y is called from macro x, where alpha is defined.
X
XThe definition of alpha in macro x is an example of a
Xlocal definition. The variable alpha only exists whilst
Xmacro x is executing. When macro x terminates, the storage
Xallocated to alpha is freed.
X
XAll macros may recurse. In the example above, if macro x
Xcalls itself, or macro y calls x, then another instance of
Xalpha will be created. In this case the highest level
Xdefinition of alpha is said to be in scope.
X
X> Global Variables
X
XGlobal variables are different to local variables in that
Xa global variable once brought into existence, never gets
Xdestroyed. Global variables are defined by the CRISP
Xbuiltin operator (global).
X
XThe following illustrates how to define a global variable:
X
X (macro x
X (
X (int beta)
X (global beta)
X )
X )
X
XIn this instance, a variable beta is first declared as a
Xlocal variable. Subsequently it is declared as a global.
XThis removes the variable from the local symbol table and
Xputs it into the global symbol table.
X
XAny variable may be made global - integers, strings or
Xlists.
X
XOnce a variable has been made global, it may be referenced
Xfrom any other macro or macro file. (BRIEF requires the
Xuse of the extern macro in order to access global symbols
Xdefined in other files).
X
XIf a global variable is defined, say fred, and a macro is
Xcalled which redefines fred as a local variable, then an
Xerror will be generated by CRISP.
X
X> Buffer-Local Variables
X
XCRISP supports a third type of variable - buffer local.
XBuffer local variables are similar to global variables,
Xexcept they only come into scope when the buffer
Xassociated with the variables is set to be the current
Xbuffer.
X
XThis allows a set of variables to be associated with a
Xparticular buffer. The reasoning behind buffer-local
Xvariables is to implement things like auto-indent, or
Xlanguage sensitive editing modes where a number of
Xvariables need to be associated with a particular buffer.
XLocal variables are obviously not sufficient here since
Xthey are destroyed when the macro defining them exits.
XGlobal variables are also not sufficient, although global
Xlists could be used.
X
XUsing global-lists to store the states of individual
Xbuffers would not only complicate the macros using these
Xvariables but would add an execution burden to macros
Xusing them.
X
XBuffer-local variables are brought into existence via the
X(make_local_variable) macro primitive.
X
SHAR_EOF
chmod 0644 help/crisp/lang/Vars.hlp || echo "restore of help/crisp/lang/Vars.hlp fails"
mkdir help help/crisp help/crisp/lang >/dev/null 2>&1
echo "x - extracting help/crisp/lang/Compiler.hlp (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/lang/Compiler.hlp &&
XThis section describes the macro compiler.
X
X> The cm Command
X
Xcm is the name of the program which translates macros in
Xhuman readable source format (.m files) into an internal
Xformat for easy processing by CRISP (.cm).
X
XThe command line syntax is:
X
X cm [-aLl] [-o output_file] file1.m file2.m ..
X
XThe usual way to invoke cm is simply:
X
X cm fred.m
X
XThis compiles the file fred.m, and creates a file fred.cm in
Xthe same directory as fred.m. Compiled macro files are loaded
Xsignificantly more quickly and execute slightly more
Xefficiently than pure source files.
X
Xcm checks for syntax errors as it goes along - the most
Xcommon errors are unmatched brackets, and unterminated string
Xconstants.
X
X> Command Line Switches
X
Xcm has a number of switches. Most of these are used for
Xdebugging the compiler itself and for disassembling compiled
Xmacro files.
X
X -a This switch is used to print out the relative
X amount of space used by individual components of
X the compiled language. It is used for fine
X tuning the pseudo code generated by the
X compiler. Most users can ignore this switch.
X This switch currently does not work.
X
X -l This switch is used to print out each macro so
X that the internal parsing can be checked. This
X switch currently does not work.
X
X -L This switch is used to print out the internal
X pseudo code used to represent a macro and allows
X debugging of the internal code generator. This
X switch currently does not work.
X
X
SHAR_EOF
chmod 0644 help/crisp/lang/Compiler.hlp || echo "restore of help/crisp/lang/Compiler.hlp fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/A.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/A.cmd &&
X.HU abort
XSYNOPSIS: (abort)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to abort CRISP - it causes an
X unconditional exit from CRISP after resetting the keyboard
X state.
X
X It should be used with extreme care since no checks are
X made to see if buffers need to be saved, etc.
X
X Its primary use will be in debugging macros.
X.HU above
XSYNOPSIS: (above expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 and expr2 are integer values and expr1
X is greater than expr2; returns 1 if expr1 & expr2 are
X string expressions and expr1 lexicographically follows
X expr2. Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions.
X
X (above) is the same as (> ..)
X.HU above_eq
XSYNOPSIS: (above_eq expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 and expr2 are integer values and expr1
X is greater than or equal to expr2; returns 1 if expr1 &
X expr2 are string expressions and expr1 lexicographically
X follows expr2 or is equal to expr2. Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions. This is the same as (>= ..).
X.HU append_list
XSYNOPSIS: (append_list list_var list_expr)
X
XRETURN VALUE:
X
X Returns the list formed by the concatenation of list_var
X and list_expr.
X
XDESCRIPTION:
X
X append_list is used to create a new list. It takes the
X list in the variable list_var, and appends a copy of
X list_expr to the end of it.
X.HU assign_to_key
XSYNOPSIS: (assign_to_key [key] [macro])
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to bind a macro to a function key. The
X key is given by the string parameter, key, and if omitted
X is prompted for. key may be specified as either an
X internal key code, or may be specified by a portable
X abbreviation. The portable abbreviations are given below.
X
X macro is either the name of a macro to execute when that
X key is pressed or is a list of instructions (using the
X (quote_list) macro). Specifying a list obviates the need
X to define trivial macros which perform simple actions.
X Using a macro name allows more complicated actions to be
X specified.
X
X (The \ (backslash) character can be used to turn off the
X effect of the special characters). key is a string which
X may take one of the following forms:
X
X x the actual key 'x'.
X ^x the key control-x.
X
X #123 the key whose internal key code is 123. This
X method of defining keys is not recommended. It
X is provided for compatability with BRIEF, but is
X useless since BRIEF allows PC keyboard scancodes
X to be entered in this way. PC keyboard scancodes
X have very little relevance outside of DOS.
X
X xyz the sequence of keys x, followed by y, followed
X by z. This allows multiple keys to be bound to a
X macro. Note that this is not the same as using
X (set_term_keyboard) to define a key.
X <Fn>
X when n is in the range 1..12. This is a synonym for
X Function Key n.
X
X <Ctrl-Fn>, <Shift-Fn>, <Alt-Fn>
X (n == 1..12).
X <Alt-x>
X where n is an upper or lower case letter. The
X case of the letter is ignored. On the Sun
X keyboard, LEFT/RIGHT act as the ALT key for the
X main keyboard only.
X <Alt-n>
X where n is in the range 0..9. On a PC keyboard this
X means the top numeric keys with the ALT key pressed.
X On a Sun-3 keyboard, this is the same as LEFT/RIGHT
X pressed whilst hitting a digit key.
X <Ins>
X The keypad Insert key.
X <Del>
X The DELETE key.
X <Backspace>
X The backspace key.
X <Keypad-minus>
X The '-' key on the keypad (relevant to PC
X keyboards only).
X <Keypad-plus>
X The '+' key on the keypad (relevant to PC
X keyboards only).
X <Enter>
X The ENTER or RETURN key.
X
X <Esc>, <Tab>, <PgDn>, <PgUp>, <Left>, <Right>, <Up>, <Down>,
X <Home>, <End>
X Same as keys labelled as such on keyboard. On
X keyboards which dont have markings for these
X keys, various approximations are possible. Refer
X to the tty/*.m files for further details.
X.HU atoi
XSYNOPSIS: (atoi string [char])
X
XRETURN VALUE:
X
X Returns integer value of argument string treated as an
X ascii number or the ascii value of the first character in
X string if char is zero.
X
XDESCRIPTION:
X
X This macro converts string, which is a string
X representation of a decimal number to binary. If char is
X specified and is zero, then the ascii value of the first
X character in string is returned.
X.HU attach_buffer
XSYNOPSIS: (attach_buffer bufnum)
X
XRETURN VALUE:
X
X No value is returned.
X
XDESCRIPTION:
X
X This command attaches the specified buffer to the
X currently selected window. This means that the next time
X the window is refreshed the specified buffer will be
X displayed in the current window.
X
X When the specified buffer is attached to the current
X window, the top title of the window is changed to reflect
X the buffer or filename associated with the buffer.
X
X This call is necessary after changing a window with
X (set_window). Take care to ensure that when a window is
X refreshed on the screen that it always has a buffer
X attached to it, otherwise CRISP may core dump.
X
X This command is only intended for use by macro
X programmers, and macros using (attach_buffer) should be
X frequently saved during development to avoid unexpected
X crashes.
X
XEXAMPLES:
X
X The following example shows the outline of a macro which
X attaches a new buffer to the current window.
X
X (int newbuf)
X
X (= newbuf (user_func))
X (attach_buffer newbuf)
X // Refresh screen with buffer contents.
X (refresh)
X.HU autoload
XSYNOPSIS: (autoload file macro1 [macro2] ..)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to define the whereabouts of macros.
X Whenever CRISP encounters a reference to a macro which is
X not currently defined, it searches an internal list to see
X if an (autoload) macro has mentioned it. If so, the file
X parameter says in which file it can find the macro.
X
X file should be specified as the basename of the macro file
X (ie without a .m or .cm suffix). This lets CRISP search
X the BPATH variable to see if it can find a .m or .cm file.
X
X If it finds the file, it then performs a (load_macro)
X operation. If the macro definition is still not resolved
X after auto-loading the macro file, then CRISP prints an
X error message.
X
X An arbritrary number of macro names may appear after the
X file parameter.
X
X autoloading is a useful feature since it speeds CRISP up
X in that it doesn't need to load macros which aren't
X referenced.
X
SHAR_EOF
chmod 0644 help/crisp/prim/A.cmd || echo "restore of help/crisp/prim/A.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/B.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/B.cmd &&
X.HU backspace
XSYNOPSIS: (backspace)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This deletes the character to the left of the cursor in
X the current buffer. If the cursor is at the beginning of
X the line then the current line is appended to the end of
X the previous line.
X.HU beep
XSYNOPSIS: (beep)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro sends a bell or beep to the screen causing an
X audible sound. This macro can be used by error macros.
X.HU beginning_of_line
XSYNOPSIS: (beginning_of_line)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X Moves the cursor to column 1 of the current line.
X.HU below
XSYNOPSIS: (below expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 and expr2 are integer values and expr1
X is less than expr2; returns 1 if expr1 & expr2 are string
X expressions and expr1 lexicographically preceeds expr2.
X Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions.
X
X (below) is the same as (< ..)
X.HU below_eq
XSYNOPSIS: (below_eq expr1 expr2)
X
XRETURN VALUE:
X
X Returns 1 if expr1 and expr2 are integer values and expr1
X is less than or equal expr2; returns 1 if expr1 & expr2
X are string expressions and expr1 lexicographically follows
X expr2 or is equal to expr2. Returns 0 otherwise.
X
XDESCRIPTION:
X
X expr1 & expr2 must either be both integer expressions or
X string expressions. This is the same as (<= ..).
X.HU borders
XSYNOPSIS: (borders [expr])
X
XRETURN VALUE:
X
X Returns zero if borders are turned off; non-zero if
X borders are enabled for windows.
X
XDESCRIPTION:
X
X This macro can be used to turn off borders for windows. By
X default they are on.
X
X If expr is omitted, then the current value is toggled.
X Otherwise the internal toggle is set to the value of expr.
X Non-zero means borders are on.
X
X On some terminals, having borderless windows is less
X expensive on screen updating than on others, because of
X the overhead involved in drawing the borders around the
X windows.
X.HU break
XSYNOPSIS: (break)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro acts like the C break statement. It exits the
X current innermost (while) loop.
X
SHAR_EOF
chmod 0644 help/crisp/prim/B.cmd || echo "restore of help/crisp/prim/B.cmd fails"
mkdir help help/crisp help/crisp/prim >/dev/null 2>&1
echo "x - extracting help/crisp/prim/C.cmd (Text)"
sed 's/^X//' << 'SHAR_EOF' > help/crisp/prim/C.cmd &&
X.HU call_registered_macro
XSYNOPSIS: (call_registered_macro n)
X
XRETURN VALUE:
X
X Nothing.
X
XDESCRIPTION:
X
X This macro is used to trigger a registered macro. n is an
X integer expression specifying the registered macro to
X trigger.
X
X See (register_macro) for further details on the different
X registered macro types.
X.HU car
XSYNOPSIS: (car list_expr)
X
XRETURN VALUE:
X
X Returns the value of the first element in the list_expr.
X
XDESCRIPTION:
X
X This macro is used to make a copy of the first atom in the
SHAR_EOF
echo "End of part 3"
echo "File help/crisp/prim/C.cmd is continued in part 4"
echo "4" > s2_seq_.tmp
exit 0
--
===================== Reuters Ltd PLC,
Tel: +44 628 891313 x. 212 Westthorpe House,
UUCP: fox%marlow.uucp@idec.stc.co.uk Little Marlow,
Bucks, England SL7 3RQ