Ents Database Save File Protocol (Preliminary) - OpenPatternsInc/EntsDatabase GitHub Wiki

This is a description of the protocol for generating a plain text file containing the properties of the Ents in a database, sufficient to allow them to be loaded back. The protocol is documented here, even in it's inefficient ways, just so people can understand the code. The entire database is loaded into memory for now, just to test the interface and features.

The protocol is implemented in openpatterns.ents_database_library.IO which handles reading and writing to file of the databases.

This is obviously not an efficient implementation of a database, but it's more than enough to accommodate the types of databases which will be initially created with only a few thousand nodes or so. We'll have to see how it scales and then determine proper steps forward form there. It won't be difficult to change this protocol.

Ents have essentially 6 properties in the basic Ents Database protocol.

Each Ent in a database has a unique name, a unique identifier, a description/info, and a list of its direct parents, children and exclusions.

An Ent's name should be unique within the database ignoring case. This encourages descriptive names, even if two distinct concepts happen to go by the same name. A maximum name size of 40 characters seems sufficient.

An Ent's info is the place to describe what a group or entity entails, so a maximum character size of 2000 seems reasonable, but that's arbitrary as well.

Unique Identifiers (UIDs) will be random unsigned integers. This is how parents and children are referenced.

Looks like UTF-8 is a sufficient charset. No real reasoning behind this as of yet, but no reason to use another. We want support for international characters, so perhaps this is insufficient.

The arbitrary separator "@#" (at-hashtag) will act as the separator of variables. Thus this sequence is illegal in a names and info.

Each Ent's properties take up 4 lines of text. The first line is for UID, name and Info. Second line is for parents, 3rd for children, and 4th for exclusions.

Note: Exclusions are not supported yet, so there is just a blank fourth line for now.

Pseudo example:

[UID]#[name]@#[info]@#

p[parentUID1]$[parentUID2]$[parentUID3].......

c[childUID1]$[childUID2]$...

e[exclusionUID1]......

Right now we see that newlines are not supported in info/description text. This isn't intended for long.

Some of the elements, like the leading p, c and e are superfluous, but help make the files human readable at least initially for testing purposes. I expect to leave this protocol soon enough, this is just for documentation purposes.