2.2 Named Definitions

A name is a sequence of characters beginning with an alphabetic character (a through z) followed by zero or more alpha-numeric characters and/or separator characters: hyphen (-), underscore (_) or carat (^). Names are case insensitive.

Any name may have multiple values associated with it. Every name may be considered a sparse array of one or more elements. If there is more than one value, the values my be accessed by indexing the value with [index] or by iterating over them using the FOR (see section FOR - Emit a template block multiple times) AutoGen macro on it, as described in the next chapter. Sparse arrays are specified by specifying an index when defining an entry (see section Assigning an Index to a Definition).

There are two kinds of definitions, ‘simple’ and ‘compound’. They are defined thus (see section Finite State Machine Grammar):

compound_name '=' '{' definition-list '}' ';'

simple-name[2] '=' string ';'

no^text^name ';'

simple-name has the third index (index number 2) defined here. No^text^name is a simple definition with a shorthand empty string value. The string values for definitions may be specified in any of several formation rules.

2.2.1 Definition List

definition-list is a list of definitions that may or may not contain nested compound definitions. Any such definitions may only be expanded within a FOR block iterating over the containing compound definition. See section FOR - Emit a template block multiple times.

Here is, again, the example definitions from the previous chapter, with three additional name value pairs. Two with an empty value assigned (first and last), and a "global" group_name.

autogen definitions list;
group_name = example;
list = { list_element = alpha;  first;
         list_info    = "some alpha stuff"; };
list = { list_info    = "more beta stuff";
         list_element = beta; };
list = { list_element = omega;  last;
         list_info    = "final omega stuff"; };

2.2.2 Double Quote String

The string follows the C-style escaping, using the backslash to quote (escape) the following character(s). Certain letters are translated to various control codes (e.g. \n, \f, \t, etc.). x introduces a two character hex code. 0 (the digit zero) introduces a one to three character octal code (note: an octal byte followed by a digit must be represented with three octal digits, thus: "\0001" yielding a NUL byte followed by the ASCII digit 1). Any other character following the backslash escape is simply inserted, without error, into the string being formed.

Like ANSI "C", a series of these strings, possibly intermixed with single quote strings, will be concatenated together.

2.2.3 Single Quote String

This is similar to the shell single-quote string. However, escapes \ are honored before another escape, single quotes ' and hash characters #. This latter is done specifically to disambiguate lines starting with a hash character inside of a quoted string. In other words,

fumble = '
#endif
';

could be misinterpreted by the definitions scanner, whereas this would not:

fumble = '
\#endif
';

As with the double quote string, a series of these, even intermixed with double quote strings, will be concatenated together.

2.2.4 An Unquoted String

A simple string that does not contain white space may be left unquoted. The string must not contain any of the characters special to the definition text (i.e., ", #, ', (, ), ,, ;, <, =, >, [, ], `, {, or }). This list is subject to change, but it will never contain underscore (_), period (.), slash (/), colon (:), hyphen (-) or backslash (\\). Basically, if the string looks like it is a normal DOS or UNIX file or variable name, and it is not one of two keywords (‘autogen’ or ‘definitions’) then it is OK to not quote it, otherwise you should.

2.2.5 Shell Output String

This is assembled according to the same rules as the double quote string, except that there is no concatenation of strings and the resulting string is written to a shell server process. The definition takes on the value of the output string.

NB The text is interpreted by a server shell. There may be left over state from previous server shell processing. This scriptlet may also leave state for subsequent processing. However, a cd to the original directory is always issued before the new command is issued.

2.2.6 Scheme Result String

A scheme result string must begin with an open parenthesis (. The scheme expression will be evaluated by Guile and the value will be the result. The AutoGen expression functions are disabled at this stage, so do not use them.

2.2.7 A Here String

A ‘here string’ is formed in much the same way as a shell here doc. It is denoted with two less than characters(<<) and, optionally, a hyphen. This is followed by optional horizontal white space and an ending marker-identifier. This marker must follow the syntax rules for identifiers. Unlike the shell version, however, you must not quote this marker.

The resulting string will start with the first character on the next line and continue up to but not including the newline that precedes the line that begins with the marker token. The characters are copied directly into the result string. Mostly.

If a hyphen follows the less than characters, then leading tabs will be stripped and the terminating marker will be recognized even if preceded by tabs. Also, if the first character on the line (after removing tabs) is a backslash and the next character is a tab or space, then the backslash will be removed as well. No other kind of processing is done on this string.

Here are three examples:

str1 = <<-  STR_END
        $quotes = " ' `
        STR_END;

str2 = <<   STR_END
        $quotes = " ' `
        STR_END;
STR_END;

str3 = <<-  STR_END
        \	$quotes = " ' `
        STR_END;

The first string contains no new line characters. The first character is the dollar sign, the last the back quote.

The second string contains one new line character. The first character is the tab character preceding the dollar sign. The last character is the semicolon after the STR_END. That STR_END does not end the string because it is not at the beginning of the line. In the preceding case, the leading tab was stripped.

The third string is almost identical to the first, except that the first character is a tab. That is, it exactly matches the first line of the second string.

2.2.8 Concatenated Strings

If single or double quote characters are used, then you also have the option, a la ANSI-C syntax, of implicitly concatenating a series of them together, with intervening white space ignored.

NB You cannot use directives to alter the string content. That is,

str = "fumble"
#ifdef LATER
      "stumble"
#endif
      ;

will result in a syntax error. The preprocessing directives are not carried out by the C preprocessor. However,

str = '"fumble\n"
#ifdef LATER
"     stumble\n"
#endif
';

Will work. It will enclose the ‘#ifdef LATER’ and ‘#endif’ in the string. But it may also wreak havoc with the definition processing directives. The hash characters in the first column should be disambiguated with an escape \ or join them with previous lines: "fumble\n#ifdef LATER....

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.