PIRL.Conductor

## Class Reference_Resolver

- java.lang.Object
- - PIRL.Conductor.Reference_Resolver

    public class Reference_Resolver
    extends Object

A Reference_Resolver resolves embedded references in text strings.

A Reference_Resolver recognizes two kinds of references: database field references and parameter source references. All references are enclosed in curly brace ('{' and '}') characters. A leading dollar sign ('$') character indicates a parameter source reference; otherwise it's a database field reference. All field references are resolved against a specified Database, and all parameter references are resolved against a specified list of Parmerters; if no Parameter list is provided the Configuration Parameters from the Database will be used.

The resolved value of a reference replaces the reference in the string being resolved. Replacement occurs depth-wise: the most deeply nested references are resolved first. The substitution of a resolved reference value in a nested reference modifies the reference accordingly. Thus a reference may be constructed from the values of other references.

A field reference is a token that produces a database query: the query is submitted to the Reference_Resolver's Database and then replaced by the first result. Field references have the following form:

> {Catalog.Table.Field:Key}

The components preceding the colon form a fully qualified field name, and the component following the colon is a match (SQL WHERE) criteria. Data are retrieved from the field only when they match the criteria. If more than one result is returned, only the first is used.

A parameter reference is resolved against the Parameter source list. The parameter reference is replaced with the value of the Parameter having the reference name. Parameter references have the following form:

> ${Pathname@Sequence[Index]...}

The Pathname is a simple, relative or absolute Parameter pathname used to `Find` the parameter in the Database Configuration. The Sequence, with its preceeding "at" ('@') delimiter , is optional; if present it indicates which of a multiple sequence parameters that match the Pathname to select (the first parameter is Sequence 0). The Index, with its enclosing square bracket ('[' and ']') characters, is also optional; if present it indicates which element of an Array Value to select (the first element is Index 0). Multiple Array Value element specifiers may be provided to select from multidimensional Array Values. Both the Sequence and Index specifiers may contain nested references. They may also be mathematical expressions that evaluate to any numeric value, which is truncated to an integer for selecting Array Value elements.

References that can not be resolved are replaced with the `Default_Value`. However, if the default is null, then an Unresolved_Reference will be thrown.

Any escaped character - a character preceeded by a backslash ('\') character - is not interpreted with any special meaning. Both the backslash and the special character are left in place.

See Also:
  `PIRL.Database`, `PIRL.Configuration`

### Field Summary

Fields
`static char` `ALTERNATIVE_MARKER` Alternative source parameter reference token character.
`static char` `ARRAY_ELEMENT_END_MARKER` The marker that ends a parameter reference array value index number.
`static char` `ARRAY_ELEMENT_START_MARKER` The marker that starts a parameter reference array value index number.
`static int` `CASE_INSENSITIVE`
`static int` `CASE_SENSITIVE`
`static char` `COMPONENTS_DELIMITER` The delimiter of database field reference components.
`static char` `ESCAPE_MARKER` The marker that escapes any special interpretation of the following character.
`static String` `ID` Class name and version identification.
`static char` `KEY_MARKER` The marker preceeding a key specification of a database field reference.
`static char` `PARAMETER_REFERENCE_MARKER` The marker preceeding an enclosed parameter reference.
`static char` `PARAMETER_SEQUENCE_MARKER` The marker that preceeds a parameter reference sequence number.
`static int` `PATTERN_MATCH`
`static char` `REFERENCE_END_MARKER` The marker that ends an enclosed reference.
`static char` `REFERENCE_START_MARKER` The marker that starts an enclosed reference.

### Constructor Summary

Constructors
Constructor and Description
`Reference_Resolver()` Constructs an empty Reference_Resolver.
`Reference_Resolver(Database database)` Constructs a Reference_Resolver to use a Database.

### Method Summary

Methods
`static int` `Alternative_Marker_Index(String string)` Gets the index of an `ALTERNATIVE_MARKER` in a String.
`static Vector<Integer>` `Array_Indices(String parameter_reference)` Gets the Vector of Array Value element indices from a parameter reference.
`static String` `Catalog_Name(String field_reference)` Gets a catlog name from a field reference.
`Database` `Database()` Gets the Database that will be used when resolving references.
`Reference_Resolver` `Database(Database database)` Sets the Database to use when resolving database references.
`String` `Default_Value()` Gets the default that will be used when a reference can not be resolved.
`Reference_Resolver` `Default_Value(String default_value)` Sets the default to use when a reference can not be resolved.
`static boolean` `Enclosed_Reference(String string)` Tests if a String is an enclosed reference.
`static double` `Evaluate_to_double(String expression)` Resolves a reference to a double value.
`static String` `Field_Name(String field_reference)` Gets a field name from a field reference.
`static String` `Index_Specifiers(String parameter_reference)` Gets the parameter Array Value element index specifiers from a parameter reference.
`static String` `Key(String field_reference)` Gets a key from a field reference.
`int` `Match_Mode()` Gets the parameter match mode.
`Reference_Resolver` `Match_Mode(int match_mode)` Sets the parameter match mode.
`Parameter` `Parameter_Reference_Parameter(String parameter_reference)` Gets the Parameter that resolves a parameter reference.
`Value` `Parameter_Reference_Value(String parameter_reference)` Gets the Value that resolves a parameter reference.
`Parameter` `Parameters()` Gets the Parameters that will be used when resolving parameter references.
`Reference_Resolver` `Parameters(Parameter parameters)` Sets the Parameters to use when resolving parameter references.
`static String` `Pathname(String parameter_reference)` Gets a pathname from a parameter reference.
`String` `Pattern()` Gets the last pattern String that was resolved.
`Vector` `Resolve_Array_Indices(String parameter_reference)` Gets the Vector of Array Value dimension indices from a parameter reference.
`String` `Resolve_Field_Reference(String field_reference)` Resolves a database field reference.
`String` `Resolve_Parameter_Reference(String parameter_reference)` Resolves a parameter source reference.
`double` `Resolve_to_double(String reference)` Resolves a reference to a double value.
`String` `Resolve_to_End_Reference(String pattern)` Resolve references in a pattern String down to their end references.
`Parameter` `Resolve_to_Parameter(String parameter_reference)` Gets the Parameter that resolves a parameter reference.
`Value` `Resolve_to_Value(String parameter_reference)` Gets the Value that resolves a parameter reference.
`String` `Resolve(String pattern)` Resolve references in a pattern String.
`String` `Resolved()` Gets the last resolved String.
`static String` `Sequence(String parameter_reference)` Gets a parameter sequence from a parameter reference.
`static String` `Table_Name(String field_reference)` Gets a table name from a field reference.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### ID

    public static final String ID

Class name and version identification.

See Also:
  Constant Field Values

#### COMPONENTS_DELIMITER

    public static final char COMPONENTS_DELIMITER

The delimiter of database field reference components.

N.B.: This is not necessarily the same as the `Database table reference component delimiter`.

See Also:
  Constant Field Values

#### KEY_MARKER

    public static final char KEY_MARKER

The marker preceeding a key specification of a database field reference.

See Also:
  Constant Field Values

#### PARAMETER_REFERENCE_MARKER

    public static final char PARAMETER_REFERENCE_MARKER

The marker preceeding an enclosed parameter reference.

See Also:
  Constant Field Values

#### REFERENCE_START_MARKER

    public static final char REFERENCE_START_MARKER

The marker that starts an enclosed reference.

See Also:
  Constant Field Values

#### REFERENCE_END_MARKER

    public static final char REFERENCE_END_MARKER

The marker that ends an enclosed reference.

See Also:
  Constant Field Values

#### PARAMETER_SEQUENCE_MARKER

    public static final char PARAMETER_SEQUENCE_MARKER

The marker that preceeds a parameter reference sequence number.

See Also:
  Constant Field Values

#### ARRAY_ELEMENT_START_MARKER

    public static final char ARRAY_ELEMENT_START_MARKER

The marker that starts a parameter reference array value index number.

See Also:
  Constant Field Values

#### ARRAY_ELEMENT_END_MARKER

    public static final char ARRAY_ELEMENT_END_MARKER

The marker that ends a parameter reference array value index number.

See Also:
  Constant Field Values

#### ESCAPE_MARKER

    public static final char ESCAPE_MARKER

The marker that escapes any special interpretation of the following character.

See Also:
  Constant Field Values

#### ALTERNATIVE_MARKER

    public static final char ALTERNATIVE_MARKER

Alternative source parameter reference token character.

See Also:
  Constant Field Values

#### CASE_SENSITIVE

    public static final int CASE_SENSITIVE

See Also:
  Constant Field Values

#### CASE_INSENSITIVE

    public static final int CASE_INSENSITIVE

See Also:
  Constant Field Values

#### PATTERN_MATCH

    public static final int PATTERN_MATCH

See Also:
  Constant Field Values

### Constructor Detail

#### Reference_Resolver

    public Reference_Resolver(Database database)

Constructs a Reference_Resolver to use a Database.

Parameters:
  `database` - The Database to use when resolving embedded references.

#### Reference_Resolver

    public Reference_Resolver()

Constructs an empty Reference_Resolver. Until a `Database` is assigned this Reference_Resolver will not be able to `Resolve` references to their values.

### Method Detail

#### Database

    public Reference_Resolver Database(Database database)

Sets the Database to use when resolving database references.

If no Parameters have been specified, then the Database Configuration parameters will be used to supply them.

Parameters:
  `database` - The Database to use.
Returns:
  This Reference_Resolver.
See Also:
  `Database.Configuration()`

#### Database

    public Database Database()

Gets the Database that will be used when resolving references.

Returns:
  The current Database.

#### Parameters

    public Reference_Resolver Parameters(Parameter parameters)

Sets the Parameters to use when resolving parameter references.

Typically an Aggregate is provided for use. Otherwise an Aggregate is created to contain the Parameter that is provided.

Parameters:
  `parameters` - The Parameters to use. If null an empty Aggregate will be used.
Returns:
  This Reference_Resolver.

#### Parameters

    public Parameter Parameters()

Gets the Parameters that will be used when resolving parameter references.

Returns:
  The current Parameter Aggregate. This may be null if

#### Match_Mode

    public Reference_Resolver Match_Mode(int match_mode)
                                  throws IllegalArgumentException

Sets the parameter match mode. <p. When searching for a parameter to resolve a parameter reference the parameter name will be matched using one of these modes:

`CASE_SENSITIVE`
  A case sensitive comparsion of the parameter name with the reference name will be made.
`CASE_INSENSITIVE`
  A case insensitive comparison of the parameter name with the reference name will be made.
`PATTERN_MATCH`
  The reference name will be treated as a regular expression (regex) pattern for a match with the parameter name.

The default match mode is CASE_SENSITIVE.

Parameters:
  `match_mode` - One of the CASE_SENSITIVE, CASE_INSENSITIVE, or PATTERN_MATCH values.
Returns:
  This Reference_Resolver.
Throws:
  `IllegalArgumentException` - If the match mode is not a valid value.
See Also:
  `Selection`

#### Match_Mode

    public int Match_Mode()

Gets the parameter match mode.

Returns:
  the current parameter match mode code.
See Also:
  `Match_Mode(int)`

#### Default_Value

    public Reference_Resolver Default_Value(String default_value)

Sets the default to use when a reference can not be resolved.

Parameters:
  `default_value` - The String to use as the default. If this is null an Unresolved_Reference will be thrown when a reference can not be resolved.
Returns:
  This Reference_Resolver.

#### Default_Value

    public String Default_Value()

Gets the default that will be used when a reference can not be resolved.

Returns:
  The String to use as the default. This is null if Unresolved_Reference will be thrown when a reference can not be resolved.

#### Pattern

    public String Pattern()

Gets the last pattern String that was resolved.

Returns:
  The last pattern String. This will be null if no previous pattern String was `Resolve`d.

#### Resolved

    public String Resolved()

Gets the last resolved String.

Note: If the last `Pattern` did not fully resolve due to some problem, then the String returned will be the partially resolved result.

Returns:
  The last resolved String. This will be null if no previous pattern String was `Resolve`d.

#### Resolve

    public String Resolve(String pattern)
                   throws ParseException,
                          Database_Exception,
                          Unresolved_Reference

Resolve references in a pattern String.

Parameters:
  `pattern` - The pattern String potentially containing embedded references.
Returns:
  The pattern String with its references resolved.
Throws:
  `ParseException` - if a reference is not correctly formed.
  `Database_Exception` - if there is a problem accessing the Database.
  `Unresolved_Reference` - if the reference is unresolved and the Default_Value is null.

#### Resolve_to_End_Reference

    public String Resolve_to_End_Reference(String pattern)
                                    throws ParseException,
                                           Database_Exception,
                                           Unresolved_Reference

Resolve references in a pattern String down to their end references.

Parameters:
  `pattern` - The pattern String potentially containing embedded references.
Returns:
  The pattern String with its references resolved to end references.
Throws:
  `ParseException` - if a reference is not correctly formed.
  `Database_Exception` - if there is a problem accessing the Database.
  `Unresolved_Reference` - if the reference is unresolved and the Default_Value is null.

#### Resolve_Field_Reference

    public String Resolve_Field_Reference(String field_reference)
                                   throws ParseException,
                                          Database_Exception,
                                          Unresolved_Reference

Resolves a database field reference.

A field reference has the following form:

> Catalog.Table.Field:Key

The components are used to `Select` a Database Field value from a Catalog.Table where the table record matches the Key criteria.

N.B.: The field reference is presumed to have been resolved of any nested references.

Parameters:
  `field_reference` - The field reference String to be resolved by the database.
Returns:
  The resolved String value.
Throws:
  `ParseException` - if the field reference does not have all of the components of the field reference format.
  `Database_Exception` - if there is a problem accessing the Database.
  `Unresolved_Reference` - if the reference is unresolved and the Default_Value is null.

#### Resolve_Parameter_Reference

    public String Resolve_Parameter_Reference(String parameter_reference)
                                       throws ParseException,
                                              Unresolved_Reference

Resolves a parameter source reference.

A parameter reference has the following form:

> Pathname@Sequence[Index]...

The Pathname is used to retrieve a Parameter value from the source Parameters list.

The optional Sequence refers to which of a multiple sequence of Parameters that all match the Pathname is to be selected; the first parameter is Sequence 0.

The Index specifies which element of a Parameter with an Array Value to use; the first element is Index 0. Mulitple Index values access multidimensional Arrays with the left-most specifier accessing an element of the top-most Array, the next specifier accessing an element of the Array Value selected by the previous specifier, etc. If there are less specifiers than the depth of Array Values, then the first non-Array Value of the last Array selected will satisfy the reference (as if [0] had been specified); thus when a parameter reference has no Index specifiers but the referenced Parameter has an Array Value, then the first non-Array Value will be selected regardless of its nesting depth.

N.B.: As a special case, a parameter reference index that is negative results in the Value being returned regardless of whether it is an Array or not. A nested Array value may be selected by providing leading array indices before the negative index in the parameter reference, but any additional array indices provided after a negative index are ignored.

Both the Sequence and Index are subject to mathematical expression evaluation. Any expression that can be evaluated to a numerical value is allowed; the result will be truncated to an integer.

N.B.: The parameter reference is presumed to have been resolved of any nested references.

Parameters:
  `parameter_reference` - The reference String to be resolved by the source Parameters list.
Returns:
  The resolved String value.
Throws:
  `ParseException` - if the reference contains a syntax error such as an unclosed Array Value element specifier, or a Sequence or Index specifier that does not evaluate to a numerical value.
  `Unresolved_Reference` - if the reference is unresolved and the Default_Value is null.
See Also:
  `Parameter_Reference_Value(String)`

#### Resolve_to_Parameter

    public Parameter Resolve_to_Parameter(String parameter_reference)
                                   throws ParseException,
                                          Database_Exception,
                                          Unresolved_Reference

Gets the Parameter that resolves a parameter reference.

A parameter reference has the following form:

> Pathname@Sequence[Index]...

The Pathname is used to retrieve a Parameter value from the source Parameters list.

The optional Sequence refers to which of a multiple sequence of Parameters that all match the Pathname is to be selected; the first parameter is Sequence 0. The Sequence may be a mathematical expression which is cast to an integer value.

The Array Value Index specifiers are not used here.

N.B.: The parameter_reference String argument may contain nested parameter source references (${parameter_reference}) or database field references ({field_reference}). However, the resolved result is expected to be an unenclosed parameter reference which is used to find the resolving Parameter from this Reference_Resolver's `Parameters`.

Parameters:
  `parameter_reference` - The reference String to be resolved by the source Parameters list.
Returns:
  The Parameter that resolves the reference, or null if the reference can not be resolved to a Parameter.
Throws:
  `ParseException` - if the reference contains a syntax error.
  `Database_Exception` - if there is a problem accessing the Database.
  `Unresolved_Reference`

#### Parameter_Reference_Parameter

    public Parameter Parameter_Reference_Parameter(String parameter_reference)
                                            throws ParseException

Gets the Parameter that resolves a parameter reference.

N.B.: The parameter reference is presumed to have been resolved of any nested references.

Parameters:
  `parameter_reference` - The reference String to be resolved by the source Parameters list.
Returns:
  The Parameter that resolves the reference, or null if the reference can not be resolved to a Parameter.
Throws:
  `ParseException` - if the reference contains a syntax error.
See Also:
  `Resolve_to_Parameter(String)`

#### Resolve_to_Value

    public Value Resolve_to_Value(String parameter_reference)
                           throws ParseException,
                                  Database_Exception,
                                  Unresolved_Reference

Gets the Value that resolves a parameter reference.

A parameter reference has the following form:

> Pathname@Sequence[Index]...

The Pathname is used to retrieve a Parameter Value from the source Parameters list.

The optional Sequence refers to which of a multiple sequence of Parameters, that all match the Pathname, is to be selected; the first is Sequence 0. The Sequence may be a mathematical expression which is cast to an integer value.

The optional Array Value Index specifiers are used to select which Value to use from an Array of Values. When no Index specifiers are present, the implicit "[0]" specifier is used. If the specifiers select an Array Value, then the first non-Array Value of that Array Value is selected.

N.B.: As a special case, a parameter reference index that is negative results in the Value being returned regardless of whether it is an Array or not. A nested Array value may be selected by providing leading array indices before the negative index in the parameter reference, but any additional array indices provided after a negative index are ignored.

N.B.: The parameter_reference String argument may contain nested parameter source references (${parameter_reference}) or database field references ({field_reference}). However, the resolved result is expected to be an unenclosed parameter reference which is used to find the resolving Parameter from this Reference_Resolver's `Parameters`.

Parameters:
  `parameter_reference` - The reference String to be resolved by the source Parameters list.
Returns:
  The Value that resolves the reference, or null if the reference can not be resolved to a Value.
Throws:
  `ParseException` - if the reference contains a syntax error.
  `Database_Exception` - if there is a problem accessing the Database.
  `Unresolved_Reference` - if the reference is unresolved and the Default_Value is null.
See Also:
  `Parameter_Reference_Value(String)`

#### Parameter_Reference_Value

    public Value Parameter_Reference_Value(String parameter_reference)
                                    throws ParseException

Gets the Value that resolves a parameter reference.

When the parameter reference resolves to an Array Value, the reference is expected to include array indices that will select a non-Array Value from within the Array. However, if no indices are provided the first non-Array Value is selected, regardless of its Array nesting depth. N.B.: As a special case, a parameter reference index that is negative results in the Value being returned regardless of whether it is an Array or not. A nested Array value may be selected by providing leading array indices before the negative index in the parameter reference, but any additional array indices provided after a negative index are ignored. N.B.: The parameter reference (as described for `Resolve_to_Value(String)`) is presumed to have been resolved of any nested references.

Parameters:
  `parameter_reference` - The parameter reference String.
Returns:
  A Parameter Value selected by the reference, or null if no Value was selected.
Throws:
  `ParseException` - if the reference contains a syntax error.
See Also:
  `Parameter_Reference_Parameter(String)`, `Array_Indices(String)`

#### Resolve_Array_Indices

    public Vector Resolve_Array_Indices(String parameter_reference)
                                 throws Database_Exception,
                                        ParseException,
                                        Unresolved_Reference

Gets the Vector of Array Value dimension indices from a parameter reference.

The parameter reference String may contain zero or more Arrary Value element specifiers enclosed in square brackets ('[' and ']'). The reference String has any nested references `resolved` to their values. Then the substring within each set of square brackets is evaluated as a mathematical `expression`.

Array Value elements are accessed outer-to-inner in left-to-right order: The left-most array element reference applies to the top-most, outer, Value Array; the next array element reference applies to the Value Array selected by the previous reference.

If no Array Value specifier is found an empty indices Vector is returned.

Parameters:
  `parameter_reference` - The String containing zero or more Array Value element specifiers.
Returns:
  A Vector of zero or more element indices.
Throws:
  `ParseException` - if the references contain a syntax error.
  `Database_Exception` - if there is a problem accessing the Database.
  `Unresolved_Reference` - if the reference is unresolved and the Default_Value is null.
See Also:
  `Resolve_to_double(String)`

#### Resolve_to_double

    public double Resolve_to_double(String reference)
                             throws Database_Exception,
                                    ParseException,
                                    Unresolved_Reference

Resolves a reference to a double value.

The reference is fully resolved by an independent Reference_Resolver that shares the Database, source Parameters and Default_Value with this Reference_Resolver. This ensures that the reference will be fully resolved even when the method is not being used by this Reference_Resolver object to resolve its own Pattern; i.e. the Pattern of this Reference_Resolver will not be disturbed.

The resolved reference is parsed by a mathematical expression evaluator to produce a double value.

Parameters:
  `reference` - The reference String to be resolved. A null
Returns:
  The resolved double value. If the reference is null, 0.0 will be returned.
Throws:
  `ParseException` - if the reference contains a syntax error.
  `Database_Exception` - if there is a problem accessing the Database.
  `Unresolved_Reference` - if the reference is unresolved and the Default_Value is null.
See Also:
  `Resolve(String)`, `Parser.Parser()`

#### Catalog_Name

    public static String Catalog_Name(String field_reference)

Gets a catlog name from a field reference.

A field reference has catalog, table, field and optional key components:

> Catalog.Table.Field:Key

Other than the Key component, if only one component is present, it is the Field; if only two components are present, they are the Catalog and Table.

Parameters:
  `field_reference` - The field reference to parse.
Returns:
  The catlog name or null if one is not present.

#### Table_Name

    public static String Table_Name(String field_reference)

Gets a table name from a field reference.

A field reference has catalog, table, field and optional key components:

> Catalog.Table.Field:Key

Other than the Key component, if only one component is present, it is the Field; if only two components are present, they are the Catalog and Table.

Parameters:
  `field_reference` - The field reference to parse.
Returns:
  The table name or null if one is not present.

#### Field_Name

    public static String Field_Name(String field_reference)

Gets a field name from a field reference.

A field reference has catalog, table, field and optional key components:

> Catalog.Table.Field:Key

Other than the Key component, if only one component is present, it is the Field; if only two components are present, they are the Catalog and Table.

Parameters:
  `field_reference` - The field reference to parse.
Returns:
  The field name or null if one is not present.

#### Key

    public static String Key(String field_reference)

Gets a key from a field reference.

A field reference has catalog, table, field and optional key components:

> Catalog.Table.Field:Key

Other than the Key component, if only one component is present, it is the Field; if only two components are present, they are the Catalog and Table.

Parameters:
  `field_reference` - The field reference to parse.
Returns:
  The key or null if one is not present.

#### Pathname

    public static String Pathname(String parameter_reference)

Gets a pathname from a parameter reference.

A parameter reference has a pathname and optional sequence and Array Value element index specifiers:

> Pathname@Sequence[Index]...

Parameters:
  `parameter_reference` - The parameter reference to parse.
Returns:
  The parameter pathname or null if one is not present.

#### Sequence

    public static String Sequence(String parameter_reference)

Gets a parameter sequence from a parameter reference.

A parameter reference has a pathname and optional sequence and Array Value element index specifiers:

> Pathname@Sequence[Index]...

Parameters:
  `parameter_reference` - The parameter reference to parse.
Returns:
  The parameter sequence or null if one is not present.

#### Index_Specifiers

    public static String Index_Specifiers(String parameter_reference)

Gets the parameter Array Value element index specifiers from a parameter reference.

A parameter reference has a pathname and optional sequence and Array Value element index specifiers:

> Pathname@Sequence[Index]...

Parameters:
  `parameter_reference` - The parameter reference to parse.
Returns:
  The element index specifiers or null if none are present. The element index enclosures are included.

#### Array_Indices

    public static Vector<Integer> Array_Indices(String parameter_reference)
                                         throws ParseException

Gets the Vector of Array Value element indices from a parameter reference.

N.B.: The parameter reference is presumed to have been resolved of any nested references.

Parameters:
  `parameter_reference` - The parameter reference String containing zero or more Array Value element specifiers.
Returns:
  A Vector of zero or more element indices.
Throws:
  `ParseException` - if the references contain a syntax error.
  `Database_Exception` - if there is a problem accessing the Database, or a reference is unresolved and the Default_Value is null.
See Also:
  `Evaluate_to_double(String)`

#### Evaluate_to_double

    public static double Evaluate_to_double(String expression)
                                     throws ParseException

Resolves a reference to a double value.

N.B.: The expression is presumed to have been resolved of any nested references.

Parameters:
  `expression` - The expression String to be evaluated.
Throws:
  `ParseException`
See Also:
  `Resolve_to_double(String)`

#### Enclosed_Reference

    public static boolean Enclosed_Reference(String string)

Tests if a String is an enclosed reference.

The reference may be a parameter reference or a database reference, but it must be completely enclosed in reference markers.

N.B.: No check is made to determine if the reference enclosure, if it exits, is properly balanced.

Parameters:
  `string` - A String to be tested.
Returns:
  true if the string is an enclosed reference; false otherwise.

#### Alternative_Marker_Index

    public static int Alternative_Marker_Index(String string)

Gets the index of an `ALTERNATIVE_MARKER` in a String.

The first occurance is found of the `ALTERNATIVE_MARKER` character that is not escaped by a preceeding `ESCAPE_MARKER`, not immediately followed by the same character when this occurs the second character is also skipped), and not contained in a quoted (single or double) sequence.

Parameters:
  `string` - The String to search.
Returns:
  The index of the first `ALTERNATIVE_MARKER` in the string, or -1 if the marker is not found.