Property Markup Syntax

Note that the property markup is only supported for appliances that use the volfix configuration mode.

General Requirements

• it is a plain-text file - that is, a file that can be opened and edited by a text editor.
• if the text file contains multi-byte characters, it uses the UTF-8 encoding, or any similar encoding that, if processed as a stream of bytes, allows interpreting any value in the range of 0-127 as the corresponding latin ASCII character, regardless of context.
• the file format allows for inserting comments that are transparent to the component's code that uses the configuration file; the comment syntax is such that comments can be placed sufficiently close to the property values that are being instrumented.
• within a comment, the characters [ " $ : , -\ ] do not serve as terminators of the comment block and are not interpreted in any other special way.
• no properties need to be configured to have the newline character as part of their value.
• if newline is not the terminator for a comment block, then in the normal text the file format must allow for encodig all characters that are part of a comment terminator in a way that they stop looking like a comment terminator.
• if the file is being read and re-written by anything other than the AppLogic volume fixup utility, the markup comments are preserved and additional newlines are not inserted in the middle of a property value.
• if the file is being read and re-written by anything other than the AppLogic volume fixup utility, there is a way to ensure that during a re-write, no new text is inserted between a markup comment and the property values to which it refers.

The following file formats are known to comply with the above requirements, and are therefore "instrumentable":

• Linux line-oriented configuration files (commonly residing in the /etc/ directory and having the .conf suffix), in which lines beginning with the # character are treated as comments.
• sh/bash and Perl scripts
• source files in C++ (including header files).
• source files in C, when compiled by GCC or another compiler that allows the C++ single-line comments (//).
• HTML and similar SGML files

To handle non-instrumentable files, the recommended approach is to write a bash (or Perl) script that updates the config file on boot and instrument the script itself.

Markup Styles

Inline markup:

The presence of a $$prop: string on a line of text in the configuration file means that this line contains one or more property values. Usually, the "$$prop:" string and the rest of the line of text are made invisible to the application that uses this configuration file by making it appear as a comment, e.g., if the configuration file is a Perl script this might look like:

$port = 3306 # $$prop: 3306:ip_port

The val:name pairs following the markup identifier string are interpreted as follows:

val1:name1 indicates that the first occurrence of the string val1 on this line is to be treated as the value of the property name1 and replaced whenever that property needs to be changed.

val2:name2 indicates that the first occurrence of the string val2 following the first occurrence of val1 is the value of the property name2.

etc.
If the name in a val:name pair is the string '-', the string 'val' is simply ignored. This is used to skip parts of the configuration data that might otherwise match a property value, e.g., a markup like this:

x1 = 1 # $$prop: 1:val

will cause the '1' in x1 to be considered the value of the property 'val'. To make the string '1' that follows the = sign be the property value, the markup has to be:

x1 = 1 # $$prop: 1:-, 1:val

The special '-' property name is also used in case the property value is the empty string, e.g., in the following markup the property is the empty string that follows the "x1 = " string:

x1 = #$$prop: "x1 = ":- , "":val

If a value contains punctuation characters that are part of the markup syntax (colon, comma, space), the value must be quoted, using the double-quote syntax that is defined for the ADL descriptor files.

Next line markup:

This markup is used for configuration files that do not allow comment text to appear on the same line as the value that needs to be exposed as a modifiable property. It is similar to the inline syntax, but it indicates that the text on the line that follows the one on which the markup appears is to be searched for matching strings, not the current line.

Markup for files that are not line-oriented:

This markup is used for configuration files in which the newline character is not considered different from other whitespace and updates of the file may cause newlines to be added or removed at any place where un-quoted whitespace occurs. For this type of markup, a closing $$ sequence is required to indicate the end of the list of val:name pairs. Newlines are allowed between the val:name pairs. All text following the closing $$ mark, regardless of newlines is searched for strings matching the values, until all values are found or until 1K of text is read for each val:name pair (if the latter occurs without finding all values, an error is reported). Note that each property value is still expected to reside on a single line.

Meta-character Quoting in Configuration Files

Whenever a property value contains such "escaped" characters, they must appear in the same exact way both in the markup (which is inside a comment section in the file) and in the actual text, even if these characters need to be "escaped" only in the normal config file text (or only in the comment). For example, the & character doesn't have a special meaning in HTML comments, but it has to be "escaped" in HTML data, i.e.:

<!-- $$propF "&":my_prop $$ --><sometag someattr="text &amp; more text">

is not valid, even though "&" is OK to appear in the comment, and must be re-done this way:

<!-- $$propF "&amp;":my_prop $$ --><sometag someattr="text &amp; more text">

The quoting of the data values may be in different formats, depending on the file type, as specified by the 'quoting=' attribute (see the component descriptor syntax). This quoting is independent of the C-style double quotes used by the markup syntax itself to enclose a property value - the latter is always done with the C-style double quotes and is superimposed on top of the former, e.g., the string 'abc"def', which may be quoted as abc\"def for a C file, will appear as follows in the markup:

p = "abc\"def"; // $$prop "abc\\\"def":p_val

-- VladM - 25 May 2006