Tombstone Engine

Facebook Twitter YouTube IndieDB

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.
kDataSyntaxError The syntax is invalid.
kDataIdentifierEmpty No identifier was found where one was expected.
kDataIdentifierIllegalChar An identifier contains an illegal character.
kDataStringInvalid A string literal is invalid.
kDataStringIllegalChar A string literal contains an illegal character.
kDataStringIllegalEscape A string literal contains an illegal escape sequence.
kDataStringEndOfFile The end of file was reached inside a string literal.
kDataCharIllegalChar A character literal contains an illegal character.
kDataCharIllegalEscape A character literal contains an illegal escape sequence.
kDataCharEndOfFile The end of file was reached inside a character literal.
kDataBoolInvalid A boolean value is not "true" or "false".
kDataTypeInvalid A data type value does not name a primitive type.
kDataIntegerOverflow An integer value lies outside the range of representable values for the number of bits in its underlying type.
kDataFloatOverflow A hexadecimal or binary literal used to represent a floating-point value contains more bits than the underlying type.
kDataFloatInvalid A floating-point literal has an invalid format.
kDataReferenceInvalid A reference uses an invalid syntax.
kDataStructUndefined An undefined structure type was encountered.
kDataStructNameExists A structure name is equal to a previously used structure name.
kDataPropertySyntaxError A property list contains a syntax error.
kDataPropertyUndefined An undefined property was encountered. This error is generated when the Structure::ValidateProperty function returns false.
kDataPropertyInvalidType A property has specified an invalid type. This error is generated if the Structure::ValidateProperty function does not specify a recognized data type.
kDataPrimitiveSyntaxError A primitive data structure contains a syntax error.
kDataPrimitiveIllegalArraySize A primitive data array size is too large.
kDataPrimitiveInvalidFormat A primitive data structure contains data in an invalid format.
kDataPrimitiveArrayUnderSize A primitive array contains too few elements.
kDataPrimitiveArrayOverSize A primitive array contains too many elements.
kDataInvalidStructure A structure contains a substructure of an invalid type, or a structure of an invalid type appears at the top level of the file. This error is generated when either the Structure::ValidateSubstructure function or DataDescription::ValidateTopLevelStructure function returns false.
During the parsing stage, the DataDescription::CreateStructure 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 or subarray size).
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