indent(2)

NAME

indent - Manage the auto-indentation methods

SYNOPSIS

0 indent "ind-no" "flags" [ "look-back" ] [ "indent-scheme" ]

indent "ind-no" "type" "token" [ "close" "ignore" ] [ "indent" ]
indent "ind-no" "t" "token" [ "token" ] "indent-scheme"
indent "ind-no" "x" | "w" "token" "indent" "indent-scheme"

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" [ "indent-scheme" ]

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.

0x02


Defines a fast look-back indentation scheme to be used in conjunction with the current indentation scheme. The fast look-back scheme is used to identify a change in the current buffer's indent scheme, for example the starting of embedded script in html. The indent-scheme argument is required when this flag bit is set and identifies the handle of the fast look-back indentation scheme to be used.

This feature is only used when indent is required to support multiple complex indentation schemes within a single file, for example indentation of scripts within html, asp or php pages etc. When defined the given indent-scheme must also be defined using indent, the scheme's look-back argument is typically set to look back a long way to ensure correctness, i.e. 500 lines, but it should therefore contain few tokens to maintain performance.

0x04


Defines C mode of indentation. C styling is built into the editor and is enabled through the indent command. The C form is discussed in more detail in the next section.

0x08


Ring the bell if goto-matching-fence(2) fails.

0x10


Comment continuation mode. This is only valid when C mode is defined and is defined further in the next section.

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 maximum value has been increase as of January 2004 from 255 to an integer (large number), a value of 10 is typically sufficient for a normal indent scheme and 500 for a fast look-back scheme.

C Indentation

0 indent "ind-no" "flags"
indent "ind-no" s "statement"
indent "ind-no" c "continue"
indent "ind-no" x "max"
indent "ind-no" b "brace"
indent "ind-no" e "braceStatement"
indent "ind-no" w "switch"
indent "ind-no" a "case"
indent "ind-no" m "margin"
indent "ind-no" u "comcont"

C mode is built into the editor by default and is enabled by setting the indent intialization flag bit 0x04. With this bit enabled then the indentation for 'C' mode is defined through the additional arguments. ind-no and flags have the same meaning as defined in the previous section. C mode is typically initialized with the value 12. The remaining C arguments are defined as follows:

indent "ind-no" "s" "statement" (=t)


The indent of the current line is derived from statement value plus the indent of the last c token (if, else, while etc.) or the last '{' (which ever was found first). i.e. if the last '{' was found at column 16 then the current line will be indented to 20:-

        { 
            xxxxxxxxxx 
            xxxxxxxxxx 

or

        if(xxxxx) 
            xxxxxxxxxx 

C tokens are only used to indent the next line, whereas '{' are used in indenting every line to it's partnering '}'.

indent "ind-no" "c" "continue" (=3/2t)


continue sets the indent to be added to a split line, i.e. for an indent of 20, a continued statement would be indented to 30. A continued statement is a single c statement which is spread over 2 or more lines, the 2nd and any following lines would be indented to 30. For example

        thisIsAVeryLongVariableWhichMeansAssignmentsAreSplit = 
                  ThisIsTheFirstContinuedStatementLine + 
                  ThisIsTheSecondContinuedStatementLine + etc ; 

The indent is changed if there is an open bracket, continued statements are indented to the depth of the open bracket plus one, e.g.

        func(firstFuncArg, 
             secondFuncArg, 
             anotherBracketForFun(firstAnotherBracketForFunArg, 
                                  secondAnotherBracketForFunArg), 
             thirdFuncArg) ; 

indent "ind-no" "x" "max"


max sets an upper limit of the indentation where an open bracket is encountered, in the case where the leading indent of the function name and open bracket exceeds max, then the continuation is reduced to the continuation indent.

The effect of max is described as follows; if max is set to a large value then the default open brace offset appearence is:-

longVariable = LongFunctionNameWhichMeans(isSoFar, 
                                          OverAndYouRunOutOfRoom) ; 

Setting max to 16 gives:

longVariable = LongFunctionNameWhichMeans(isSoFar, 
                overAndYouRunOutOfRoom) ; 

Where by the second argument indent has been artificially reduced because of it's length.

indent "ind-no" "b" "brace" (=0)


Sets the indent of a '{' and a '}' on a new line from the current statement indent. For example, a value of 0 results in the following

                if(xxxxxx) 
                { 
                    xxxxxxxxxx 
                    xxxxxxxxxx 
                } 

With a setting of 2, this would become:-

                if(xxxxxx) 
                  { 
                    xxxxxxxxxx 
                    xxxxxxxxxx 
                  } 

This works in conjunction with statement and braceStatement a change to statement will change the position of '{'s. In summary:

if (condition)      if (condition)     if (condition) 
{                       {                { 
    statement;          statement;         statement; 
}                       }                } 

brace = 0             brace = 4         brace = 2 

indent "ind-no" "e" "braceStatement" (t)


The braceStatement defines the indentation following a curly brace '{' which follows a statement.

indent "ind-no" "w" "switch" (=0)


The additional indent to be applied after a switch statement, the statement indent is applied in addition to the switch indent. See the case argument.

indent "ind-no" "a" "case" (=-t)


switch value sets the offset of a "case" entry statement from the opening brace left margin position. The default value is zero. e.g.

                switch(xxxxxxxxx) 
                { 
                case 1: 
                    xxxxxxxxxx 
                    xxxxxxxxxx 
                case 2: 
                    xxxxxxxxxx 
                } 

Setting the value to 4, increases the leading space on the "case" statement, e.g.

                switch(xxxxxxxxx) 
                { 
                    case 1: 
                        xxxxxxxxxx 
                        xxxxxxxxxx 
                    case 2: 
                        xxxxxxxxxx 
                } 

case sets the offset of the lines following a "case" statement, from the current indent. For example, using the default settings, if the current indent was 20 then a line starting with a "case" would be indented to 16, i.e.

                    xxxxxxxxxx 
                case xxxxxxxxxx 
                    xxxxxxxxxx 

This is used inside "switch" statements, the default setting give the following lay-out:-

                switch(xxxxxxxxxx) 
                { 
                case 1: 
                    xxxxxxxxxx 
                    xxxxxxxxxx 
                case 2: 

This works in conjunction with the statement variable, a change to statement will change the position of '{'s.

In summary:

switch (variable)   switch (variable) 
{                   { 
case 1:                 case 1: 
    break;                  break; 
default:                default: 
    break;                  break; 
}                    } 

  switch = 0           switch = t 
  case = -t            case = -t 

indent "ind-no" "m" "margin" (=-1)


If inserting a comment at the end of a C line, it is tedious typing x number of spaces to the comment column (by default tab does not insert a tab when indent(2) is enabled, it reformats the indentation of the line regardless of the cursor position). This variable sets the indent column of these comments. So with the default settings and the following line,

        xxxxxx ;/ 

when a '*' is entered the line becomes

        xxxxxx ;                /* 

The indenting of the "/*" occurs only if there is text on the line before it, and none after it. If the current column is already past margin then it is indented to the next tab stop.

A value of -1 disables this feature.

In summary:

    statement;        /* Comment */      statement; /* Comment */ 

    margin = 40                          margin = -1 

indent "ind-no" "u" "comcont" (" * ")


This argument is only specified if flags bit 0x10 is set. This defines the string which is inserted when a new line is started while in a comment. The string is only inserted if the cursor is at the end of the line when the newline(2) command is given. For example, for the default settings, if a newline was entered at the end of the first line, the second line would initialize to:-

                /* xxxxxxxxxx 
                   @ 

where '@' is the current cursor position. With a setting of " * ", then:-

                /* xxxxxxxxxx 
                 * @ 

In summary:

/*                  /*               /* Comment 
 * Comment          ** Comment          Comment */ 
 * Comment          ** Comment 
 */                 */ 
 comcont = " * "    comcont = "** "   comcont = "   " 

The standard indent rule for setting up C and Java is defined as:-

    0 indent .hilight.c 12 
    indent .hilight.c "s" t     ; Default may be omitted 
    indent .hilight.c "e" t     ; Default may be omitted 
    indent .hilight.c "c" 3/2t  ; Default may be omitted 
    indent .hilight.c "x" 0     ; Default may be omitted 
    indent .hilight.c "b" 0     ; Default may be omitted 
    indent .hilight.c "w" 0     ; Default may be omitted 
    indent .hilight.c "a" -t    ; Default may be omitted 
    indent .hilight.c "m" -1    ; Default may be omitted 
    indent .hilight.c "u" " * " 

This is typically written with the defaults omitted.

    0 indent .hilight.c 12 
    indent .hilight.c "u" " * " 

If GNU Emacs indentation is required then the following definition may be used:-

    0 indent .hilight.c 12            ; if (a == b) 
    indent .hilight.c "e" t           ;   { 
    indent .hilight.c "b" t           ;     c = d; 
    indent .hilight.c "s" t           ;   } 
    indent .hilight.c "u" " * " 

The default configuration scheme is defined as:-

    0 indent .hilight.c 12            ; if (a == b) 
    indent .hilight.c "e" t           ; { 
    indent .hilight.c "b" 0           ;   c = d; 
    indent .hilight.c "s" t           ; } 
    indent .hilight.c "u" " * " 

Where comments are to be aligned at the end of a statement then the margin parameter may be defined in <user>.emf.

    indent .hilight.c "m" 40 

Indentation Rule Creation

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

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 argument specifies the indent to apply in characters. The indent may be specified as a literal integer value, a positive value increases the indent a negative value reduces the indent. The indent may be specified in terms of buffer specific generic value $buffer-indent-width(5) using the value t, indicating a tab width. The value of t may be prefixed with a signed integer or vulgar fraction which adjusts the size of the indentation width by the appropriate amount. Modifying the value of $buffer-indent-width modifies the indent width that is applied allowing the indentation method to be specified independently of the indentation width.

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" t 

Keeps the indentation of the !if line the same as the previous indentation, change the indentation on the following lines by an extra $buffer-indent-width 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" -t 

decrement the indent of the !endif line and following lines by $buffer-indent-width spaces producing:

    .... 
!endif 
.... 

Universal-indent (type = 'u' or 'U')


Independent control of the current line and next line indent. Increment the current line indentation by indent and the following line indentation by indent2. Where indent represents indent with the o option and indent2 represents indent with the n option. This command is useful where the indentation of both the current and next line need to be controlled independently given a single token.

indent .hilight.emf u "<cfelse" -t 3/2t 

This has been used in the ColdFusion indentation to control the <cfelse> condition which requires control of both the current line and next line with different values from the same token. Note that a Indent-single could be implemented with this command using an argument of -t t.

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" -t 

decrements the indentation of the !elif line by $buffer-indent-width 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 "\\" 3/2t 

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 
.... 

Type (type = 't' or 'T')


Used in a fast look-back indentation scheme (see bit 0x02 of 0 indent above) to define the scheme change tokens. The fast look-back token typically shadows the x and w types and identifies the indentation scheme. The token itself does not change the indentation, it simply identifies the indentation scheme. The 'x' or 'w' types are used to perform the actual indentation of the line if required.

If the indent-scheme is defined as zero (0) then the indentation scheme is set to the same value as the $buffer-indent(5) variable.

The following example is taken from the XML language definition . A fast-look back scheme is used (hilight.xmlT) to search for the alternative indentation schemes for javascript and vbscript. The t indent type defines the start of script tokens and to switch the indentation to the new indent type.

; Fast look-back indentation scheme 
0 indent .hilight.xmlT 1 500 
; Indentation scheme 
0 indent .hilight.xml 3 20 .hilight.xmlT 

!if &exist .indent.javascript 
    indent .hilight.xmlT t "<script ... javascript>"   .indent.javascript 
    indent .hilight.xml  x "<script ... javascript>" 2 .indent.javascript 
    indent .indent.javascript w "</script>" -2 0 
!endif 
!if &exist .indent.vbscript 
    indent .hilight.xmlT t "<script ... vbscript>"   .indent.vbscript 
    indent .hilight.xml  x "<script ... vbscript>" 2 .indent.vbscript 
    indent .indent.vbscript w "</script>" -2 0 
!endif 
indent .hilight.xmlT t "</script>" 0 
indent .hilight.xml  o "</script>" -2 
; Define the indentation tokens. XML is well defined so there are 
; always opening and closing brackets. 
indent .hilight.xml e "\"" "\"" "\\" 
indent .hilight.xml b "<!--" "-->" 
indent .hilight.xml b "<\\?" "\\?>" 
indent .hilight.xml n "<[^/!]" 2 
indent .hilight.xml o "</"    -2 
indent .hilight.xml o "/>"    -2 

Change (type = [x|X|w|W|v|V])


Change the indentation scheme from the current scheme to the new indent-scheme. If the indent-scheme is specified as zero (0) then the indentation scheme is set to the same handle value as the $buffer-indent(5) variable. indent specifies the indent value, when the type is w then the current line onwards is indented (similar to o), a type of x indents the next line onwards (similar to n), a type of v indents both the current line and next time onwards (similar to u).

Refer the the type=t for an example of indentation switching.

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 &not &exist .hilight.emf 
    set-variable .hilight.emf &pinc .hilight.next 1 
!endif 

... 

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

Note that a .hilight command variable is typically used as a buffer with indentation rules will almost certainly have hilighting and the same variable is used to define the hilighting scheme.

NOTES

The variables $indent-width(5), $buffer-indent-width(5) and the t indent notation were introduced in the November 2004 version of MicroEmacs.

The electric C mode cmode(2m) was removed in December 2004, as were the variables $c-brace(5), $c-case(5), $c-contcomm(5), $c-continue(5), $c-margin(5) and $c-statement(5). All replaced by the C Indent initialisation method.

The Universal indent (u) was introduced in the 2006 release.

SEE ALSO

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

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12