libtcoddocumentation

10.2. Defining the file syntax

Creating a parser

Use this function to create a generic parser. Then you'll specialize this parser by defining the structures it can read.

TCODParser::TCODParser()

TCOD_parser_t TCOD_parser_new()

parser_new()

Registering a new structure type

TCODParserStruct *TCODParser::newStructure(const char *name)

TCOD_parser_struct_t TCOD_parser_new_struct(TCOD_parser_t parser, char *name)

parser_new_struct(parser, name)

ParameterDescription
parserIn the C version, the parser handler, returned by TCOD_parser_new.
nameThe name of the structure type (in the example, this would be "item_type").
Example:

TCODParser parser();
TCODParserStruct *itemTypeStruct = parser.newStructrue("item_type");

TCOD_parser_t parser = TCOD_parser_new();
TCOD_parser_struct_t
item_type_struct = TCOD_parser_new_struct(parser, "item_type");

parser=libtcod.parser_new()
item_type_struct = libtcod.parser_new_struct(parser, "item_type")


Adding a new flag

Use this function to add a flag property to a structure type. A flag is a simplified boolean property. It cannot be mandatory : either it's present and it's true, or it's absent and it's false.

void TCODParserStruct::addFlag(const char *name)

void TCOD_struct_add_flag(TCOD_parser_struct_t str,char *name)

struct_add_flag(str,name)

ParameterDescription
strIn the C version, the structure handler, returned by TCOD_parser_new_struct.
nameThe name of the flag (in the example, this would be "abstract").
Example:

itemTypeStruct->addFlag("abstract");

TCOD_struct_add_flag(item_type_struct, "abstract");

libtcod.struct_add_flag(item_type_struct, "abstract")


Adding a new property

Use this function to add a standard property to a structure type. Check standard property types here.

void TCODParserStruct::addProperty(const char *name, TCOD_value_type_t type, bool mandatory)

void TCOD_struct_add_property(TCOD_parser_struct_t str, char *name, TCOD_value_type_t type, bool mandatory)

struct_add_property(str, name, type, mandatory)

ParameterDescription
strIn the C version, the structure handler, returned by TCOD_parser_new_struct.
nameThe name of the property (in the example, this would be "cost" or "damages" or ...).
typeThe type of the property. It can be a standard type (see this).
mandatoryIs this property mandatory ? If true and the property is not defined in the file, the parser will raise an error.
Example:

itemTypeStruct->addProperty("cost",TCOD_TYPE_INT,true);
itemTypeStruct->addProperty("weight",TCOD_TYPE_FLOAT,true);
itemTypeStruct->addProperty("deal_damage",TCOD_TYPE_BOOL,true);
itemTypeStruct->addProperty("damaged_color",TCOD_TYPE_COLOR,true);

TCOD_struct_add_property(item_type_struct, "cost", TCOD_TYPE_INT, true);
TCOD_struct_add_property(item_type_struct, "damages", TCOD_TYPE_DICE, true);
TCOD_struct_add_property(item_type_struct, "color", TCOD_TYPE_COLOR, true);
TCOD_struct_add_property(item_type_struct, "damaged_color", TCOD_TYPE_COLOR, true);

libtcod.struct_add_property(item_type_struct, "cost", libtcod.TYPE_INT, True)
libtcod.struct_add_property(item_type_struct, "damages", libtcod.TYPE_DICE, True)
libtcod.struct_add_property(item_type_struct, "color", libtcod.TYPE_COLOR, True)
libtcod.struct_add_property(item_type_struct, "damaged_color", libtcod.TYPE_COLOR, True)


Adding a new value-list property

A value-list property is a string property for which we define the list of allowed values. The parser will raise an error if the file contains an unauthorized value for this property.
The first value-list property that you add to a structure type will have the TCOD_TYPE_VALUELIST00 type. The next TCOD_TYPE_VALUELIST01. You can define up to 16 value list property for each structure type. The last one has the type TCOD_TYPE_VALUELIST15.
You must provide a value list as a NULL terminated array of strings.

void TCODParserStruct::addValueList(const char *name, const char **value_list, bool mandatory)

void TCOD_struct_add_value_list(TCOD_parser_struct_t str, char *name, char **value_list, bool mandatory)

struct_add_value_list(str, name, value_list, mandatory)

ParameterDescription
strIn the C version, the structure handler, returned by TCOD_parser_new_struct.
nameThe name of the property (in the example, this would be "damage_type").
value_listThe list of allowed strings.
mandatoryIs this property mandatory ? If true and the property is not defined in the file, the parser will raise an error.
Example:

static const char *damageTypes[] = { "slash", "pierce", "bludgeon", NULL }; // note the ending NULL
itemTypeStruct->addValueList("damage_type", damageTypes, true);

static const char *damage_types[] = { "slash", "pierce", "bludgeon", NULL };
TCOD_struct_add_value_list(item_type_struct, "damage_type", damage_types, true);

damage_types = [ "slash", "pierce", "bludgeon" ]
litbcod.struct_add_value_list(item_type_struct, "damage_type", damage_types, True)


Adding a new list property

Use this function to add a list property to a structure type.

void TCODParserStruct::addListProperty(const char *name, TCOD_value_type_t type, bool mandatory)

void TCOD_struct_add_list_property(TCOD_parser_struct_t str, char *name, TCOD_value_type_t type, bool mandatory)

struct_add_list_property(str, name, type, mandatory)

ParameterDescription
strIn the C version, the structure handler, returned by TCOD_parser_new_struct.
nameThe name of the property (in the example, this would be "cost" or "damages" or ...).
typeThe type of the list elements. It must be a standard type (see this). It cannot be TCOD_TYPE_LIST.
mandatoryIs this property mandatory ? If true and the property is not defined in the file, the parser will raise an error.
Example:

itemTypeStruct->addListProperty("intList",TCOD_TYPE_INT,true);
itemTypeStruct->addListProperty("floatList",TCOD_TYPE_FLOAT,true);
itemTypeStruct->addListProperty("stringList",TCOD_TYPE_STRING,true);

TCOD_struct_add_list_property(item_type_struct, "intList", TCOD_TYPE_INT, true);
TCOD_struct_add_list_property(item_type_struct, "floatList", TCOD_TYPE_FLOAT, true);
TCOD_struct_add_list_property(item_type_struct, "stringList", TCOD_TYPE_STRING, true);

libtcod.struct_add_list_property(item_type_struct, "intList", libtcod.TYPE_INT, True)
libtcod.struct_add_list_property(item_type_struct, "floatList", libtcod.TYPE_FLOAT, True)
libtcod.struct_add_list_property(item_type_struct, "stringList", libtcod.TYPE_STRING, True)


Adding a sub-structure

A structure can contain others structures. You can tell the parser which structures are allowed inside one structure type with this function.

void TCODParserStruct::addStructure(TCODParserStruct *sub_structure)

void TCOD_struct_add_structure(TCOD_parser_struct_t str, TCOD_parser_struct_t sub_structure)

struct_add_structure(str, sub_structure)

ParameterDescription
strIn the C version, the structure handler, returned by TCOD_parser_new_struct.
sub_structureThe structure type that can be embedded.
Example:

// The item_type structure can contain itself
itemTypeStruct->addStructure(itemTypeStruct);

TCOD_struct_add_value_list(item_type_struct, item_type_struct);

libtcod.struct_add_value_list(item_type_struct, item_type_struct)


Getting a structure type's name

You can retrieve the name of the structure type with these functions. Warning ! Do not confuse the structure type's name with the structure's name :

item_type "sword" { ... }


Here, the structure type's name is "item_type", the structure name is "sword". Obviously, the structure name cannot be retrieved from the TCODParserStruct object because it's only known at "runtime" (while parsing the file).

const char *TCODParserStruct::getName() const

const char *TCOD_struct_get_name(TCOD_parser_struct_t str)

struct_get_name(str)

ParameterDescription
strIn the C version, the structure handler, returned by TCOD_parser_new_struct.
Example:

const char *structName = itemTypeStruct->getName();

const char *struct_name = TCOD_struct_get_name(item_type_struct);

struct_name = libtcod.struct_get_name(item_type_struct)


Checking if a property is mandatory

You can know if a property is mandatory :

bool TCODParserStruct::isPropertyMandatory(const char *name) const

bool TCOD_struct_is_mandatory(TCOD_parser_struct_t str,const char *name)

struct_is_mandatory(str,name)

ParameterDescription
strIn the C version, the structure handler, returned by TCOD_parser_new_struct.
nameThe name of the property, as defined when you called addProperty or addValueList or addListProperty.
Example:

bool costMandatory = itemTypeStruct->isPropertyMandatory("cost");

bool cost_mandatory = TCOD_struct_is_mandatory(item_type_struct, "cost");

cost_mandatory = libtcod.struct_is_mandatory(item_type_struct, "cost")


Retrieving the type of a property

You get the type of a property :
In the case of a list property, the value returned is a bitwise or of TCOD_TYPE_LIST and the list element's type. For example, for a list of int, it will return TCOD_TYPE_LIST | TCOD_TYPE_INT.

TCOD_value_type_t TCODParserStruct::getPropertyType(const char *name) const

TCOD_value_type_t TCOD_struct_get_type(TCOD_parser_struct_t str, const char *name)

struct_get_type(str, name)

ParameterDescription
strIn the C version, the structure handler, returned by TCOD_parser_new_struct.
nameThe name of the property, as defined when you called addProperty or addValueList or addListProperty.
Example:

TCOD_value_type_t costType = itemTypeStruct->getPropertyType("cost"); // returns TCOD_TYPE_INT
TCOD_value_type_t intListType = itemTypeStruct->getPropertyType("intList");

TCOD_value_type_t cost_type = TCOD_struct_get_type(item_type_struct, "cost");

cost_type = libtcod.struct_get_type(item_type_struct, "cost")