Knarvik

Reference

Database schema

Knarvik generates C++ code from an XML file containing the database schema. Here is the structure of the XML elements in the schema:

<Base>
    <Records>
        <Record>
            <Field>
            ...
        ...
    <Indices>
        <Index>
            <IndexField>
            ...
        ...
    <Includes>
        <Include>
        ...
    <Types>
        <Type>

See an example: Saving.xml

Elements reference

Base

Required. The root element.

Attributes:

Name. Required. The name of the database class.
Namespace. Required. The namespace of the generated source files.
Asserts. Required. Specifies whether the runtime checks should be added.
Save. Optional. Specifies whether serialization code should be generated.

Records

Required. Contains one or more Record as child elements.

Record

Required. Describes a table and its fields. Contains one or more Field as child element. A database must have at least one table.

Attributes:

Name. Required. The name of the table class. Instances of the table class represent individual rows. Static methods of the table class perform operations related to the whole table.
BlockSize. Optional. Memory for table rows is allocated in blocks. BlockSize tells how many rows should fit in a single block.

Field

Required. Describes a table field. A table must have at least one field.

Attributes:

Name. Required. The field name.
Type. Required. Type should be either a built-in type (string, int, float, bool, link, link[]) or a type specified in the Types section. Type link means this field is a reference to another row. Type link[] means this field is a collection of references to other rows.
Optional. Optional. Specifies whether this field should receive a default value when the record is inserted into the table. The default value is 0. Struct fields must be marked as optional. Values for fields marked as not optional must be provided during the insert. Default value: no.
Target. Required for fields of types link and link[]. For a one-way link, this attribute must be the name of the target record (possibly the record this field belongs to). For a two-way link, this attribute must be in the form <record>.<field> where <record> is the name of the target record and <field> is the name of the field in the target record that points at the current record.
Save. Optional. If the database is serializable, specifies whether to serialize the field. Only fields of built-in types (including links) and structs can be serialized. For the SomeStruct struct to be serialized, the program must have methods with signatures like
```
void WriteSomeStruct(const SomeStruct* str, Knarvik::BinaryWriter* writer);
Knarvik::KnErrorCode ReadSomeStruct(SomeStruct* str, Knarvik::BinaryReader* reader).
```

Includes

Optional. Contains one or more Include as child elements.

Include

Tells Knarvik to add an #include statement in the generated header file.

Attributes:

Path. Required. The path to the file to include.
ProjectInclude. Required. Specifies which kind of brackets to use in the #include statement. yes results in #include "Somefile.h". no results in #include <math.h>.

Types

Optional. Contains one or more Type as child elemets.

Type

Describes a user-defined field type.

Attributes:

Name. Required. A C++ class name or a typedef.
Category. Required. The type category.

There can be several categories:

ptr - This is a pointer to an instance of some struct or class defined and maintained somewhere outside the database.
class - This is an instance of some class that is defined outside of the database, but is managed by the database. class fields carry ownership which means that the instance of a class field is deleted when the database is shut down, or when the field is overwritten with a pointer to another instance. Thus, the Create method and the field setter receive the ownership to the instance that the new field value points to. Do not manually delete the instance of a class that is managed by the database.
struct - This is a C struct that can be safely copied by bitwise copy and does not have a destructor.
byvalue - This is either a C struct that is passed by value or a function pointer.

Indices

Optional. Contains one or more Index as child elements.

Index

Describes a hash-based index on a table. Contains one or more IndexField as child elements. The collection of IndexFields defines which table fields are indexed by this index.

Attributes:

Name. Required. The name of the index class.
Record. Required. The name of the table (Record) that this index applies to.

IndexField

Adds a table field to the index.

Attributes:

Field. Required. The name of the indexed table field. Indexed table fields are immutable and cannot be optional.