CML regular option attributes

CML attributes define and control the semantics of a CML tag. This section defines the possible option attributes you can use in a CML template. Regular options can be use either as Instruction tags or as Option attributes in other tag types.

The @! unordered-lines and @!ordered-lines attributes

Instruction tag syntax

@!unordered-lines@
@!ordered-lines@

unordered-lines is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;unordered-lines[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;ordered-lines[;{option}]...]]]]@

Valid for groups.

Description

unordered-lines allows child tags of a template to appear in any order; however, position of items within ordered sequence elements is preserved. unordered-lines is the default behavior.

ordered-lines instructs the parser that child tags of the template object (lines, loops, conditionals, and so on) must appear in the file in the ordered they are specified in the template.

The unordered-elements and ordered-elements attributes

Instruction tag syntax

@!unordered-elements@
@!ordered-elements@

unordered-elements is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;unordered-elements[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;ordered-elements[;{option}]...]]]]@

Valid for groups.

Description

unordered-elements allows child tags of of the current group to appear in any order; however, position of items within ordered sequence elements is preserved. unordered-elements is the default behavior.

ordered-elements instructs the parser that child tags of the group object (loops, conditionals, elements, and so on) must appear in the file in the ordered they are specified in the template.

The relaxed-whitespace and strict-whitespace attributes

Instruction tag syntax

@!relaxed-whitespace@
@!strict-whitespace@

relaxed-whitespace is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;relaxed-whitespace[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;strict-whitespace[;{option}]...]]]]@

Valid for groups.

Description

relaxed-whitespace allows whitespace in the template to be matched by any combination of tabs and spaces. relaxed-whitespace is the default behavior.

strict-whitespace requires that whitespace in the template be matched exactly in the file.

The required-whitespace and optional-whitespace attributes

Instruction tag syntax

@!required-whitespace@
@!optional-whitespace@

required-whitespace is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;required-whitespace[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;optional-whitespace[;{option}]...]]]]@

Valid for groups.

Description

required-whitespace requires that whitespace in the template be in the file. optional-whitespace makes the presence of non-significant whitespace in the file optional.

The missing-values-are-null and missing-values-are-error attributes

Instruction tag syntax

@!missing-values-are-null@

@!missing-values-are-error@

missing-values-are-null is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;missing-values-are-null[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;missing-values-are-error[;{option}]...]]]]@

Description

missing-values-are-null instructs that values that are not found in the file are null, and therefore not provided in the Value Set.

missing-values-are-error throws an error if all values specified in a template are not found in a file or Value Set.

The case-insensitive-keywords and case-sensitive-keywords attributes

Instruction tag syntax

@!case-insensitive-keywords@
@!case-sensitive-keywords@

case-insensitive-keywords is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;case-insensitive-keywords[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;case-sensitive-keywords[;{option}]...]]]]@

Description

case-insensitive-keywords match literal text in the file ignoring case. case-insensitive-keywords is the default behavior.

case-sensitive-keywords instructs that literal text in the template must be matched in a case-sensitive basis in the file.

The reluctant attribute

Instruction tag syntax

@!reluctant@

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;reluctant[;{option}]...]]]]@

Description

reluctant specifies that a specific loop or sequence will try to match as few elements as possible from the configuration file. This is not the default behavior of loops and sequences.

The required and optional attributes

Instruction tag syntax

@!required@
@!optional@

required is the default behavior.

Using optional in an instruction tag may have unintended consequences.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;required[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;optional[;{option}]...]]]]@

Description

required elements must be matched (unless nested inside optional groups). required is the default behavior.

optional elements are optional.

Using optional as an option attribute is valid for any tag, except an instruction tag. Using optional in an instruction tag may have unintended consequences.

The skip-lines-without-values and show-lines-without-values attributes

Instruction tag syntax

@!skip-lines-without-values@
@!show-lines-without-values@

skip-lines-without-values is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;skip-lines-without-values[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;show-lines-without-values[;{option}]...]]]]@

Description

skip-lines-without-values instructs when a line has replace elements, and all values for those elements are null, that line should be suppressed from the output. skip-lines-without-values is the default behavior.

show-lines-without-values instructs that all lines should be shown, regardless of the presence or absence of null values.

The skip-groups-without-values and show-groups-without-values attributes

Instruction tag syntax

@!skip-groups-without-values@
@!show-groups-without-values@

skip-groups-without-values is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;skip-groups-without-values[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;show-groups-without-values[;{option}]...]]]]@

Description

skip-groups-without-values instructs when a group has replace elements, and all values for those elements are null, that groups should be suppressed from the output. skip-groups-without-values is the default behavior.

show-groups-without-values instructs that all groups should be shown, regardless of the presence or absence of null values.

The sequence-append, sequence-replace and sequence-prepend attributes

Instruction tag syntax

@!sequence-append@
@!sequence-replace@
@!sequence-prepend@

sequence-append is the default behavior.

Valid for loops and sequences.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-append[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-replace[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-prepend[;{option}]...]]]]@

Description

sequence-append sequence elements child scopes are appended to sequence elements in parent scopes. sequence-append is the default behavior.

sequence-replace indicates that sequence elements child scopes replace sequence elements in parent scopes.

sequence-prepend sequence elements child scopes are prepended to sequence elements in parent scopes.

The not-primary-field and primary-field attributes

Instruction tag syntax

@!not-primary-field@
@!primary-field@

not-primary-field is the default behavior.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;not-primary-field[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;primary-field[;{option}]...]]]]@

Description

not-primary-field indicates this field should not be used for the purposes of identifying duplicate items when performing list aggregation.

not-primary-field is the default behavior.

primary-field indicates this field should be used for the purposes of identifying duplicate items when performing list aggregation.

Valid for sequence and replace tags inside a sequence.

The namespace attribute

Instruction tag syntax

@!namespace={namespace}@

The default value for {namespace} is “/” (the root name space).

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;namespace={namespace}[;{option}]...]]]]@

The default value for {namespace} is “/” (the root name space).

Description

namespace is a string that identifies the name space within which elements with unqualified names (names without a preceding slash or period) will be stored.

The default value for {namespace} is the root name space, represented by the string “/” (forward-slash).

The name space value is a path name. It must start with a slash (/).

The boolean-no-format attribute

Instruction tag syntax

@!boolean-no-format={string}@

The default value for {string} is “no”

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;boolean-no-format={string}[;{option}]...]]]]@

The default value for {string} is “no”

Description

boolean-no-format identifies the string that will be used to match false Boolean elements. Valid for Boolean replace tags.

The boolean-yes-format attribute

Instruction tag syntax

@!boolean-yes-format={string}@

The default value for {string} is “yes”

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;boolean-yes-format={string}[;{option}]...]]]]@

The default value for {string} is “yes”

Description

boolean-yes-format and boolean-no-format identifies the strings that will be used to match boolean elements. The default value for {string} is “yes”

Valid for boolean replace tags.

The delimiter attribute

whitespace-delimited
comma-delimited
semicolon-delimited
tab-delimited
quote-delimited
delimiter

Instruction tag syntax

@!whitespace-delimited@
@!comma-delimited@
@!semicolon-delimited@
@!tab-delimited@
@!quote-delimited@
@!delimiter={string}@

whitespace-delimited is the default behavior

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;whitespace-delimited[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;comma-delimited[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;semicolon-delimited[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;tab-delimited[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;quote-delimited[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;delimiter={string}[;{option}]...]]]]@

whitespace-delimited is the default behavior.

Description

delimiter sets the default delimiter character. If not explicitly specified, sequence-delimiter and field-delimiter will inherit this value.

Valid for replace and sequence tags.

The line-comment attributes

line-comment-is-comma
line-comment-is-semicolon
line-comment-is-tab
line-comment-is-whitespace
line-comment

Instruction tag syntax

@!line-comment-is-comma@
@!line-comment-is-semicolon@
@!line-comment-is-tab@
@!line-comment-is-whitespace@
@!line-comment={string}@

There is no default value for {string}.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;line-comment-is-comma[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;line-comment-is-semicolon[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;line-comment-is-tab[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;line-comment-is-whitespace[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;line-comment={string}[;{option}]...]]]]@

There is no default value for {string}.

Description

line-comment sets the character that indicates that the remainder of the line will be parsed as a comment.

The sequence-delimiter attribute

sequence-delimiter-is-comma
sequence-delimiter-is-semicolon
sequence-delimiter-is-tab
sequence-delimiter-is-whitespace
sequence-delimiter-is-quote
sequence-delimiter

Instruction tag syntax

@!sequence-delimiter-is-comma@
@!sequence-delimiter-is-semicolon@
@!sequence-delimiter-is-tab@
@!sequence-delimiter-is-whitespace@
@!sequence-delimiter-is-quote@
@!sequence-delimiter={string}@

By default, sequence-delimiter uses the value of  delimiter. The default for the latter is whitespace-delimited.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-delimiter-is-comma[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-delimiter-issemicolon[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-delimiter-is-tab[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-delimiter-is-whitespace[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-delimiter-is-quote[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;sequence-delimiter={string}[;{option}]...]]]]@

By default, sequence-delimiter uses the value of  delimiter. The default for the latter is whitespace-delimited.

Description

sequence-delimiter sets the character that separates items within a sequence. By default, sequence-delimiter uses the value of  delimiter. The default for the latter is whitespace-delimited.

Valid for sequences.

The field-delimiter attribute

field-delimiter-is-comma
field-delimiter-is-semicolon
field-delimiter-is-tab
field-delimiter-is-eol
field-delimiter-is-whitespace
field-delimiter-is-quote
field-delimiter

Instruction tag syntax

@!field-delimiter-is-comma@
@!field-delimiter-is-semicolon@
@!field-delimiter-is-tab@
@!field-delimiter-is-whitespace@
@!field-delimiter-is-quote@
@!field-delimiter={string}@

By default, field-delimiter uses the value of  delimiter. The default for the latter is whitespace-delimited.

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;field-delimiter-is-comma[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;field-delimiter-is-semicolon[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;field-delimiter-is-tab[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;field-delimiter-is-whitespace[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;field-delimiter-is-quote[;{option}]...]]]]@
@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;field-delimiter={string}[;{option}]...]]]]@

By default, field-delimiter uses the value of  delimiter. The default for the latter is whitespace-delimited.

Description

field-delimiter sets a character that will be used to terminate parsing for a replace element value. By default, field-delimiter uses the value of  delimiter. The default for the latter is whitespace-delimited.

Valid for replace tags and sequence tags.

The line-continuation attribute

Instruction tag syntax

@!line-continuation={string}@

Option attribute syntax

@[{level}]{tag-type}[[{source}][;[{type}][;[{range}][;line-continuation={string}[;{option}]...]]]]@

Description

line-continuation sets a character that will be used to indicate that the current line in a config file should be wrapped to the subsequent line.