The following defines the standard string form of XFN composite names in Backus-Naur Form (BNF). All the characters of the string representation of one name must uniformly use the same encoding and locale information. The notations used are as shown in Table A-2:
Table A-2 Backus-Naur Notation
Symbol |
Meaning |
---|---|
Is defined to be |
|
Alternatively |
|
<text> |
Nonterminal element |
Literal expression |
|
The preceding syntactic unit can appear 0 or more times. |
|
The preceding syntactic unit can appear 1 or more times. |
|
The enclosed syntactic units are grouped as a single syntactic unit (can be nested). |
The XFN composite name syntax in BNF is shown in Table A-3:
Table A-3 XFN Composite Name Syntax Using BNF
The function fn_composite_name_from_string() returns an XFN composite name in its structural form, FN_composite_name_t, given the composite name's string representation. The syntax rules used by fn_composite_name_from_string() are as follows:
An XFN composite name is decomposed into an ordered set of components (<Component>).
Each component represents a compound name, or a single atomic name of a compound name if the compound name's syntax uses the XFN component separator (/) as a separator for its atomic parts and the compound name is not quoted.
The following are the rules for parsing a composite name.
Any <ComponentSep> character that is neither escaped nor enclosed in quoted strings is considered to be a component separator.
Any string enclosed by component separators is a component (<Component>).
A composite name is parsed and decomposed into components from left to right:
The first component is the string preceding the first occurrence of a component separator.
Empty components are processed as follows:
A leading component separator (the composite name begins with a component separator) means a leading null component.
A trailing component separator (the composite name ends with a component separator) means a trailing null component.
Two consecutive component separators mean a null component.
The name string that immediately follows the last component separator of the composite name is the final component.
A component string is evaluated from left to right and converted into its standard form according to the following rules:
A component string is considered to be quoted if it is enclosed in a pair of matching unescaped quote characters (either a <Quote1> or a <Quote2> pair). The quoted string must represent the full component; that is, a begin quote must immediately be preceded by a component separator or no character, and the end quote must immediately be followed by a component separator or no character.
If a component does not contain a valid begin quote (a <Quote1> or <Quote2> immediately preceded by either a component separator or no character), any occurrence of <Quote1> or <Quote2> within that component is treated just as any other <SimpleChar>.
An unmatched begin quote (missing or misplaced end quote) fails with an FN_E_ILLEGAL_NAME status.
Quotes are considered to be escaped in quoted strings if a matching quote character is preceded immediately by the unescaped <EscapeChar>.
Quoted components are resolved by eliminating the quote characters from the component name and substituting possibly escaped quotes by simple quote characters. <MetaChar>s and the nonmatching quote characters enclosed in quoted strings are treated just as any other <SimpleChar>.
Any of the defined metacharacters (<ComponentSep> and <EscapeChar>) is considered to be escaped in an unquoted component name string if preceded immediately by the unescaped <EscapeChar> (for instance, the sequence <EscapeChar> <EscapeChar> <ComponentSep> denotes an escaped <EscapeChar> but an unescaped <ComponentSep>).
<Quote1> and <Quote2> are considered to be escaped in an unquoted component if and only if <EscapeChar> is preceded by a component separator (that is, sequences <ComponentSep> <EscapeChar> <Quote1> or <ComponentSep> <EscapeChar> <Quote2>). Other occurrences of <Quote1> and <Quote2> in an unquoted component are treated just as any other <SimpleChar>.
Any occurrence of escaped <MetaChar>, escaped <Quote1>, or escaped <Quote2> in unquoted components is substituted by the corresponding unescaped character.
No substitution is done for <EscapeChar> <SimpleChar>. <EscapeChar> <SimpleChar> maps to <EscapeChar> <SimpleChar>.
The function fn_string_from_composite_name() returns the string representation of an XFN composite name given its structural form (FN_composite_name_t). The following are the rules used by fn_string_from_composite_name().
The components are added to the composite name string in left to right order (that is, rightmost is the tail).
Successive components are separated by the component separator (<ComponentSep>).
Empty components are handled in the following way:
A leading empty component is represented by a leading <ComponentSep>.
A trailing empty component is represented by a trailing <ComponentSep>.
An empty component occurring within a composite name is represented by two consecutive <ComponentSep>s.
A composite name denoting a single non-empty component does not contain any unescaped component separator.
Any occurrence of <ComponentSep> in a component is escaped by inserting <EscapeChar> immediately preceding <ComponentSep>.
If the first character of a component is either <Quote1> or <Quote2>, it will be escaped by inserting <EscapeChar> immediately preceding the quote.
Any occurrence of <EscapeChar> before <ComponentSep> in a component is escaped by inserting <EscapeChar> immediately preceding the <EscapeChar>.
Any occurrence of <EscapeChar> as the first character of a component with <Quote1> or <Quote2> as the second character in a component is escaped by inserting <EscapeChar> immediately preceding the <EscapeChar>. Subsequent <EscapeChar> occurring before any matching quote character is also escaped by inserting <EscapeChar> immediately preceding the <EscapeChar>.