Facebook Twitter YouTube

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, subarray size, or state data).
kDataBrokenRef 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. Each structure described in the input text was recognized and successfully created.
3. Each structure is valid as indicated by the Structure::ValidateSubstructure function called for its enclosing structure.
4. Each property identifier is valid as indicated by the Structure::ValidateProperty function called for the associated structure, and it has a value of the proper type assigned to it.
5. Any existing subarrays of primitive data have the correct number of elements, matching the number specified in brackets after the primitive type identifier.
See Also

Structure::ProcessData

DataDescription::GetErrorLine