indent(2)

NAME

indent - Manage the auto-indentation methods

SYNOPSIS

0 indent "ind-no" "flags" "look-back"

indent "ind-no" "type" "token" [ "close" [ "ignore" ]] [ "indent" ]

DESCRIPTION

The indent command creates and manages the auto-indenting methods, the process of creating a new indentation method is best described in File Language Templates. The command takes various forms as defined by the arguments. Each of the argument configurations is defined as follows:-

Indentation Method Creation

0 indent "ind-no" "flags" "look-back"

With an argument of 0, indent creates a new indentation method with the integer handle ind-no. The indentation method is assigned to a buffer by setting $buffer-indent(5) to ind-no. ind-no cannot be 0 as setting $buffer-indent to zero disables indentation. If the indentation method with the same ind-no already exists, then the existing method is deleted and a new method may be created.

flags Sets the indent bit flags where:-

0x01


Indent method is case insensitive. Note that indent tokens must be specified in lower case.

look-back specifies the maximum number of lines, prior to the current line, considered when calculating the indentation of a line, i.e. if there are look-back number of lines between the line to be indented and the previous non-blank line then the current indentation is lost.

If look-back is set to 0 then the indentation is effectively disabled as the current indentation can never be found. The value may be specified in the range 0-255, a value of 10 is typically sufficient.

Indentation Rule Creation

indent "ind-no" "type" "token" [ "close" [ "ignore" ]] [ "indent" ]

With the default argument of 1, indent creates a new rule for the indentation method ind-no which must have previously been defined and initialized.

The indentation of a line in a buffer, which is using an indentation method, is affected by the token types matched on the line (type f, o, s) and the current indentation (if line is not of type f).

The current indentation is determined by searching the previous lines (look-back) for the indentation of the last indented line. This may not simply be the indentation of the last non-blank line, the exact indentation is determined by searching for tokens in the line and assessing their effect on the indentation of the current line.

The format of the regex valid in the "token" and "close" arguments are the same as at used by hilight token creation, see hilight(2) for more information.

The indent tokens may be assigned one of the following types, using the type argument. If the type is specified in upper case then the token must be surrounded by non-alpha-numeric characters:

Fixed (type = 'f' or 'F')


A line containing a fixed indent token will be indented to the given indent column from the left-hand edge. indent is the only argument specified. e.g. MicroEmacs macro !goto labels:-

indent .hilight.emf f "*" 0 

producing

    ..... 
*label 
    ..... 

The fixed token must be the first non-white character on the line, the rest of the line is ignored. The indentation of the previous line has no effect.

Indent-from-next-line-onward (type = 'n' or 'N')


The indentation changes by indent from the next line onwards from the current line. indent is the only argument specified. e.g. MicroEmacs macro !if:-

indent .hilight.emf n "!if" 4 

Keeps the indentation of the !if line the same as the previous indentation, change the indentation on the following lines by an extra 4 characters, to produce:

.... 
!if 
    .... 

Indent-from-current-line-onward (type = 'o' or 'O')


Increment the current and following lines indentation by indent. indent is the only argument specified. e.g. MicroEmacs macro !endif

indent .hilight.emf o "!endif" -4 

decrement the indent of the !endif line and following lines by 4 spaces producing:

    .... 
!endif 
.... 

Indent-single (type = 's' or 'S')


Changes the indentation of the current line ONLY by indent. indent is the only argument specified. e.g. MicroEmacs macro !elif:-

indent .hilight.emf o "!elif" -4 

decrements the indentation of the !elif line by 4 characters, but restores the previous indentation after the current line, producing:

    .... 
!elif 
    .... 

Bracket (type = 'b' or 'B')


A bracket should be used when a starting token pairs with a closing token which may span multiple lines. i.e. the opening and closing braces of a programming language. Note that the opening and closing tokens must be different otherwise they cannot be differentiated. A bracket has two main effects:

When the previous line has an unmatched open bracket


In this situation the current line is indented to the right of the mismatched bracket.

When the previous line has an unmatched close bracket


In this situation the matching open bracket is hunted for in previous lines until either the look-back limit (See Indentation Method Creation) is exhausted or the bracket is matched, in which case the indent of that line is used.

For a bracket the only other argument given is the close. e.g. tcl's '(' and ')' brackets

indent .hilight.tcl b "(" ")" 

Which produces:

.... 
.... (.... 
      .... 
      ....) 
.... 

Continue (type = 'c' or 'C')


Indicates that when token is found on the current line, the next line is a continuation of the current line. The indentation of the next line is the indentation of the first continuation line plus the given indent. indent is the only argument specified. e.g. tcl's '\'

indent .hilight.tcl c "\\" 10 

A simple example is

.... 
12345678901234567890      \ 
         .... 
.... 

When used in conjunction with brackets, the following effect is observed:

.... 
12345678901234567890      \ 
          ....(....       \ 
               ....)      \ 
          ....            \ 
          .... 
.... 

This shows why the first continuation line (the 123456... line) must be located and used as the base line from which the indentation is derived; again the look-back limits the search for this line.

Exclusion (type = 'e' or 'E')


Used to exclude text between start token and close token from the indentation calculation, typically used for quotes. The ignore argument is also specified (see hilight(2) type 0x004 type bracket) e.g. MicroEmacs macro quotes:-

indent .hilight.emf e "\"" "\"" "\\" 

e.g. tcl's quotes

indent .hilight.tcl e "\"" "\"" "\\" 

producing:-

.... 
".... ignore { ... \" ... ignore another { token ... " 
.... 

Ignore (type = 'i' or 'I')


Text to the right of a line containing token is to be ignored; typically used for comments. e.g. MicroEmacs macro ';' comment:-

indent .hilight.emf i ";" 

Or tcl's '#' comment

indent .hilight.tcl i "#" 

producing

.... 
# ... ignore this { indent token 
.... 

EXAMPLE

Examples of indentation method creations can be found in macro files hkemf.emf, hktcl.emf and hkvrml.emf. The following example is taken from hkemf.emf:-

!if &sequal .hilight.emf "ERROR" 
    set-variable .hilight.emf &pinc .hilight.next 1 
!endif 

... 

0 indent  .hilight.emf 0 10 
indent .hilight.emf N "define-macro" 4 
indent .hilight.emf n "!if" 4 
indent .hilight.emf s "!eli" -4 
indent .hilight.emf s "!els" -4 
indent .hilight.emf o "!end" -4 
indent .hilight.emf n "!whi" 4 
indent .hilight.emf o "!don" -4 
indent .hilight.emf n "!rep" 4 
indent .hilight.emf o "!until" -4 
indent .hilight.emf o "!ema" -4 
indent .hilight.emf e "\"" "\"" "\\" 
indent .hilight.emf i ";" 
indent .hilight.emf f "*" 0 

SEE ALSO

File Language Templates, $buffer-indent(5), add-file-hook(2), hilight(2).

(c) Copyright JASSPA 1999
Last Modified: 1999/04/26
Generated On: 1999/12/01