DataDescription::ProcessText

Defined in: TSOpenDDL.h

Parses an OpenDDL file and processes the top-level data structures.

Prototype

DataResult ProcessText(const char *text);

Parameters

text The full contents of an OpenDDL file with a terminating zero byte.

Description

The ProcessText function parses the entire OpenDDL file specified by the text parameter. If the file is successfully parsed, then the data is processed as described below. If an error occurs during the parsing stage, then the ProcessText function returns one of the following values, and the DataDescription object contains no data. During the parsing stage, the DataDescription::CreateStructure function is called for each custom data structure that is encountered in order to construct an object whose type is the proper subclass of the Structure class. After a successful parse, the ProcessText function iterates through all of the top-level data structures in the file (which are the direct subnodes of the root structure returned by the DataDescription::GetRootStructure function) and calls the Structure::ProcessData function for each one. If an error is returned by any of the calls to the Structure::ProcessData function, then the processing stops, and the same error is returned by the DataDescription::ProcessText function. If all of the top-level data structures are processed without error, then the DataDescription::ProcessText function returns kDataOkay. The error returned during the processing stage can be one of the following values or a value defined by a derivative data format.

`kDataMissingSubstructure`	A structure is missing a substructure of a required type.
`kDataExtraneousSubstructure`	A structure contains too many substructures of a legal type.
`kDataInvalidDataFormat`	The primitive data contained in a structure uses an invalid format (type, element count, subarray size, or state data).
`kDataBrokenReference`	The target of a reference does not exist.

If an error is returned for either the parsing stage or the processing stage, then the line number where the error occurred can be retrieved by calling the DataDescription::GetErrorLine function.

The default implementation of the Structure::ProcessData function iterates over the direct subnodes of a data structure and calls the ProcessData function for each one. If all overrides call the base class implementation, then the entire tree of data structures will be visited during the processing stage.

Any implementation of the Structure::ProcessData function may make the following assumptions about the data:

1. The input text is syntactically valid.
2. If an unrecognized structure was encountered in the input text, then it was removed along with all of its substructures.
3. Each recognized structure is valid as indicated by the Structure::ValidateSubstructure function called for its enclosing structure.
4. If a property was valid as indicated by the Structure::ValidateProperty function called for the associated structure, then it has a value of the proper type assigned to it. Unrecognized properties were ignored.
5. Any existing subarrays of primitive data have the correct number of elements, matching the number specified in brackets after the primitive type identifier.
6. Any existing state identifiers associated with primitive data subarrays are valid as indicated by the Structure::GetStateValue function.