Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

-*-Text-*-
This is the file <info>eclu.info, which documents the CLU Mode
EMACS package.

File: ECLU	Node: Top	Up: (EMACS)	Next: Commands

	---> report bugs and misfeatures to WBA@XX <---

	EMACS CLU mode is an editing package to facilitate editing of
CLU programs.  It is most briefly described as being LISP mode which
knows about the CLU statement nesting keywords.  That is, it replaces
the "S-expression" with a "CLUexp" -- a properly nested CLU expression
or statement.

	CLU mode is entered with the command M-X CLU Mode.  This mode
is also entered by the usual mechanism when a file with the
incantation "-*-CLU-*-" on the first nonempty line is read in.

	A CLUexp is a properly nested piece of text in which the
nesting depth is increased by these "beginning" tokens:

   (  [  {   begin proc iter cluster if for while tagcase except

and is decreased by these "ending" tokens:

   )  ]  }   end

Furthermore, these "intermediate" tokens:

   then elseif else do tag others when

are treated like an invisible "end begin" pair.  This assists the
indenter.  The types of the beginning and ending tokens are not
checked against each other.  For example, "begin )" is a legal CLUexp
(though it will confuse the "display matching paren" feature, since
the latter does not know about keywords.)

	In CLU mode, letters, digits and underscore are alphabetic;
all others are break characters.  But see the special treatment of
dollarsign and period by C-M-F and C-M-B.  All of the usual word
commands (M-F, M-B, M-D, M-rubout, M-T, etc.) are available.

* Menu:

* Commands::		List of available commands.
* Indent::		The indentation format.
* Comments::		Comment conventions.
* Variables::		Synopsis of all variables used.
* Restrictions::	Things that might confuse it.


ECLU  Node: Commands	Previous: Restrictions	Up: Top	Next: Indent

The commands of CLU mode are listed below.  These generally try to be
as similar as possible to the corresponding commands of Lisp or
Fundamental mode.

C-M-F		  ^R Forward CLUexp
-----------------------------------
Move forward one complete CLUexp, or as many as the argument.  If the
argument is negative, move backward.

C-M-B		  ^R Backward CLUexp
------------------------------------
Move backward one complete CLUexp, or as many as the argument.  If the
argument is negative, move forward.

   It is an error to go forward by a CLUexp if just before an
   "ending" or "intermediate" token, or to go backward if just
   after a "beginning" or "intermediate" token.  A CLUexp is a
   properly nested piece of text, or a sequence of alphabetic
   characters, or a character or string constant.  These commands
   will go past any other text that they encounter on the way to
   the CLUexp: operators, whitespace, comments, etc.

   If, after going past an alphabetic CLUexp in either direction,
   the very next character is a dollarsign or period and the next
   is alphabetic, it passes an extra CLUexp.  So, for example,
   "foo.bar" and "int$add" are considered single CLUexp's, but
   "(foo).bar" and "[int]$add" are each two CLUexp's.  To get EMACS
   to stop on the period or dollarsign between two symbols, use the
   word commands M-F or M-B instead of C-M-F or C-M-B.

C-M-K		  ^R Kill CLUexp
C-M-rubout	  ^R Backward Kill CLUexp
-----------------------------------------
These kill the text between the current location and where C-M-F or
C-M-B would go.  They can take positive or negative arguments like
C-M-F and C-M-B.  The killed text is placed on the Kill Ring.

   Note - to move blocks of text around, these commands do not kill
   the carriage return at the end of the last line.  A better way is
   to use M-H to mark the entire block and then C-W or M-W or whatever.

C-M-@		 ^R Mark CLUexp
-------------------------------
This places a mark one (or several) CLUexp's from the cursor, in the
appropriate direction.  The cursor does not move.

M-H		  ^R Mark Lines Of CLUexp
-----------------------------------------
This BACKS UP TO THE BEGINNING OF THE LINE, counts the appropriate
number of CLUexp's forward or backward, and places the region around
them, including extra text so that the region contains only complete
lines. The mark is left at the beginning and the cursor at the end.

C-M-T		  ^R Transpose CLUexps
--------------------------------------
This performs the standard EMACS transposition operation, transposing
the CLUexps before and after the cursor.  With a positive argument it
transposes the CLUexps before and after the cursor, moves right, and
repeats the specified number of times, dragging the CLUexp to the left
of the cursor right.  With a negative argument, it transposes the two
CLUexps to the left of the cursor, moves between them, and repeats the
specified number of times, exactly undoing the positive argument form.
With a zero argument, it transposes the CLUexps after point and mark.

C-M-D		  ^R Down CLUexp
--------------------------------
This goes forward into ("down") 1 level of CLU structure, or as many
as the argument.  Given a negative argument, it goes forward out that
many levels.  C-M-D and C-M-U are easier to remember if one thinks of
them as traversing a series of left parentheses, that is, a "downward
slope".  That way, down means forward and up means backward.

C-M-U, C-M-(	  ^R Backward Up CLUexp
---------------------------------------
This goes backward out ("up") 1 level of CLU structure, or as many as
the argument.  Given a negative argument, it goes backward into that
many levels.  Note that the sign of the argument never changes the
direction. 

C-M-)		  ^R Forward Up CLUexp
--------------------------------------
This goes forward out 1 level of CLU structure, or as many as the
argument.  Given a negative argument, it goes forward into that many
levels.  The mnemonic significance of C-M-( and C-M-) is that they go
out of CLU structure as if searching for the appropriate type of
parenthesis.

C-M-A		  ^R Beginning of Module
----------------------------------------
This moves to the beginning of this or the previous module definition.
Given an argument, it does it that many times.  It leaves a mark in
case it is typed by accident.  A module definition begins with a line
whose first three tokens are a symbol, equals sign, and "proc",
"iter", or "cluster", with optional whitespace around them.

M-(		 ^R Make CLU ()
M-[		 ^R Make CLU []
M-{		 ^R Make CLU {}
-------------------------------
These insert a pair of parens, brackets, or braces, leaving the cursor
between them.  If given an explicit positive argument, they push the
closing paren, bracket, or brace forward past the specified number of
already existing CLUexps.  M-( is similar to its behavior in LISP
mode.  M-[ and M-{ are new.  Note that the definition of M-[ destroys
the function ^R Backward Paragraph, which is not useful in CLU mode.

tab		 ^R Indent for CLU
----------------------------------
If there is anything other than whitespace to the left on this line, a
tab character is inserted.

Otherwise, if the line is not empty, the indentation is set to be
correct relative to to the last nonempty line preceding, excluding
lines with only single or triple percent comments.  Any comment has
its indentation set according to the algorithm described elsewhere.
The cursor is left at the beginning of the line in this case.

If the line is empty, indentation is created to align what will be
typed next, assuming it will not start with "ending" tokens.  (It
can't really set the indentation right for a line it hasn't seen yet,
but the use of the linefeed command can correct this.)  The cursor is
left at the end of the indentation.

linefeed	  ^R Indent new CLU Line
----------------------------------------
This deletes whitespace to the left of the cursor, inserts a CRLF, and
behaves, roughly, as though tab were typed.  That is, it sets up the
indentation correctly for the next line.  It does one other thing: if
typed at the end of a line, it corrects the indentation of that line
before going to the next, on the assumption that that line's
indentation was calculated before it was actually typed.  Thus the
behavior of linefeed is such that, if fresh text is typed in using
linefeed to start new lines, the text will indent itself correctly.
Lines beginning with tokens such as "end" or "else" will be too far to
the right while they are being typed, but they will correct themselves
when they are ended with linefeeds.

If not typed at the end of a line, it breaks the text at that point
and sets the indentation of the next line, but does not attempt to
correct the indentation of the original line.  This may be used for
"manual grinding".  For example, if we have

   OBJ := thing$make_const(block${val: foo$make_x(V), typ: Y})
                                  ^                  ^

and we type linefeeds at the points shown, we get

   OBJ := thing$make_const(block${
	 val: foo$make_x(V),
	 typ: Y})

C-;, M-;	 ^R Indent for CLUcomment
-----------------------------------------
This aligns an existing comment on the current line, depending on
whether it begins with one, two, or more percents, according to the
algorithm described elsewhere.  If there is no comment, it creates a
single percent comment ready to be typed into.  The cursor is always
left after the comment starter.

Given a numeric argument N, it aligns existing comments (not creating
new ones) in the next N lines, and leaves the cursor after those
lines.

M-linefeed, M-J	 ^R Indent New CLUcomment Line
----------------------------------------------
This deletes whitespace to the left of the cursor, inserts a CRLF,
and, if the old line contained a comment, creates indentation and
percents for a continuation of that comment on the next line.  The
number of percents and starting column are copied from the previous
line.  If it was typed at the end of a line, the new line will be
empty except for the indentation and percents, ready for a comment to
be typed in.  In this case it also corrects the indentation of the
preceding line, just as simple linefeed does.  Hence, fresh text typed
in with linefeeds and meta-linefeeds will indent itself.  If it was
not typed at the end of a line, that line will not be corrected, and
the text after the point where it is typed will become the comment on
the new line.

If this is typed when not in a comment, the behavior is the same as
simple linefeed.

M-G		 ^R Indent CLU Region
-------------------------------------
The lines between the cursor and the mark (that is, the lines whose
first characters are between the cursor and the mark) are indented
according to the algorithm described elsewhere.  The indentation of
the first such line is set to be correct relative to the last nonempty
line preceding, excluding lines with only single or triple percent
comments.  All comments are appropriately indented according to the
algorithm described elsewhere.  Mark is left at the beginning of the
newly indented text and the cursor at the end, unless an argument (for
example, just C-U) is given, in which case they are the other way
around.  Nothing is moved from one line to another.  There is no
"grind" operation.

M-Q		  ^R Indent Lines Of CLUexp
-------------------------------------------
This BACKS UP TO THE BEGINNING OF THE LINE, counts the appropriate
number of CLUexp's forward or backward, and indents the resulting
region just as M-G does.  Mark is left at the beginning and the cursor
at the end.  This is just M-H followed by M-G.

M-&		  ^R CLU Compile
--------------------------------
This runs a CLU compiler in an inferior fork, creating one if
necessary.  The compiler is kept from one run to another until killed
by C-U 0 M-&.  It first offers to write out each file, unless there is
a numeric arg other than 0.  It then reads a command line to pass to
CLU: in this line, any occurrence of "&" is translated into the name
of the visited file.  If the line is empty, "compile &" is used, that
is, the visited file is compiled.  The command line may have several
commands separated by "#", for example, "optimize time # compile &".
The "stay" command is always implicitly added.

When the compiler finishes, the file "clu.junk" on the connected
directory is then displayed as if with M-X View File.  Type a space to
go to the next screenful, or backspace to back up.  Space after the
end will terminate viewing and go back to the visited file.

If M-& is called with an argument of zero, the compiler is simply
killed, so that a fresh one will be created next time.

******************** RECOVERING FROM MISTAKES ********************

The text killed or indented by C-M-K, C-M-rubout, M-G, or M-Q can be
restored with the "M-X Undo" command.  Killed text can also be brought
back with the C-Y command.


ECLU  Node: Indent	Previous: Commands	Up: Top	Next: Comments

	The indentation format is quite simple.  (Of course, you don't
need to format your program this way; this is simply the format that
results from using the automatic indentation commands such as M-G or
M-Q.)

	Lines of code are indented relative to each other according to
the lowest nesting level that they attain after the initial run of
ending tokens.  A sample is

if X then			% minimum level=0, set to 1 by "if"
   foo				% 1
elseif Y then			% 0, since "elseif" goes down to 0,
				% then back to 1
   if P then Q else R end	% 1 (oscillates between 1 and 2)
   for
      J : int in T$indexes(Q)	% 2
   do				% down to 1, then back to 2
      F := S${			% min is 2, then up to 3
	 a: 1,			% 3
	 b: 2,
	 c: 3}			% down to 2, but not in initial run of
				%   ending tokens, so it counts as 3
   end				% down to 1
end				% down to 0

	The indentation per nesting level is the value of the variable
CLU Indent Offset.  It is normally 3.


ECLU  Node: Comments	Previous: Indent	Up: Top	Next: Variables

	The comment character is of course percent, and all of the
usual comment operations are available.  The standard EMACS
conventions apply:

   A comment beginning with a single "%" will be indented by indenting
   commands (M-; for example) to column 32, or some multiple of 8
   beyond that if necessary.  The variables Comment Column and Comment
   Rounding may be used to alter these numbers.

   A comment beginning with "%%" and with only whitespace before it is
   indented as though it were code.  That is, it is aligned relative to
   the CLU code preceding it.

   A comment beginning with "%%%" is never moved by the indenting
   commands, unless they push the preceding text into it.  Double
   and triple percent comments should be on lines by themselves.


ECLU  Node: Variables	Previous: Comments	Up: Top	Next: Restrictions

The CLU library has a few switches you can set to customize its
behavior.  For info on how to set the variables:  
*Note Vars: (EMACS)Variables.

Comment Column and Comment Rounding determine the normal starting
column for single percent comments and the action to take when that is
not suitable.  The normal values are 32 and the next acceptable
multiple of 8.  Comment Column may be set to the current horizontal
position (or a numerical argument) by C-X ;.  It may also be changed
on a per-buffer basis by a Local Modes specification at the end of the
text file, or by running M-X Edit Options.  It may also be set for all
CLU buffers by defining the variable CLUcomment Column in an INIT or
EVARS file.

Comment Begin contains the string used to start newly created
comments.  It is normally "% ", so one blank is created after the
percent. It may be changed to get a different number of leading
blanks.  It may be changed on a per-buffer basis by a Local Modes
specification at the end of the text file, or by running M-X Edit
Options.  It may also be set for all CLU buffers by defining the
variable CLUcomment Begin in an INIT or EVARS file.

CLU Indent Offset gives the amount of indentation per nesting level.
The normal value is 3.  It may be changed by an INIT or EVARS file or
by running M-X Edit Options, or, on a per-buffer basis, by a Local
Modes specification at the end of the text file.

CLU Compiler contains the name of the compiler to be used by M-&.  Its
normal value is "ps:<subsys>clu.exe.0", for the "old" CLU.
	***** this is true for the MIT-EE machine only *****
It may be changed (to "ps:<subsys>tcmp.exe.0", for example) by an INIT
or EVARS file, or by M-X Edit Options.  However, it is only examined
when a new compiler is loaded, so, when M-X Edit Options is used, you
must kill the present compiler with C-U 0 M-& to force it to load a
new one.

Do not change Comment Start or Comment End.  The syntax of comments is
built in to the functions of CLU Mode.


ECLU  Node: Restrictions	Previous: Variables	Up: Top	Next: Commands

	The CLUexp parsing routines may behave strangely if started
from within a comment or a character or string constant, or if a
character or string constant extends past a line boundary (not legal
in CLU).

	The "display matching paren" feature uses a TECO mechanism
that does not know the full syntax of CLU, so it may be fooled by
parens, brackets, or braces inside character or string constants or
comments.  The CLUexp parsing routines have no such problems.

	A few of the standard EMACS routines for dealing with comments
can be confused by percent in a string.  These include possibly C-U
C-X ;, ^R Indent Comment Relative, ^R Indent Nested, and ^R Auto Fill
Space.


Tag Table:
File: ECLU	Node: Top115
ECLU  Node: Commands1846
ECLU  Node: Indent13075
ECLU  Node: Comments14111
ECLU  Node: Variables14965
ECLU  Node: Restrictions17069

End Tag Table