Directory

Directory with names, types and buffer offsets.

The directory is a description in binary. While parsing the pointer starts at the beginning of the directory and scans over the bytes. While scanning, a name is searched. In principle, the directory is a binary tree of characters the name must match.

It is using the following grammar:

directory ::= expr

expr ::=
     # Hierarchy separator: skip all characters of the name until a '/' is encountered.
     '/' expr |
     # Match current char in the name. If it compress less or greater, add the jmp_l or
     # jmp_g to the pointer. Otherwise continue with the first expression.
     # If there is no object for a specific jump, jmp_* can be 0, in which case the
     # expr_* is omitted.
     char jmp_l jmp_g expr expr_l ? expr_g ? |
     # Skip the next n non-/ characters of the name.
     skip expr |
     # A variable has been reached for the given name.
     var |
     # No variable exists with the given name.
     end
     # Note that expr does never start with \x7f (DEL).
     # Let's say, it is reserved for now.

char ::= [\x20..\x2e,\x30..\x7e]     # printable ASCII, except '/'
int ::= bytehigh * bytelow           # Unsigned VLQ
byte ::= [0..0xff]
bytehigh ::= [0x80..0xff]            # 7 lsb carry data
bytelow ::= [0..0x7f]                # 7 lsb carry data

# End of directory marker.
end ::= 0

# The jmp is added to the pointer at the position of the last byte of the int.
# So, a jmp value of 0 effectively results in end.
jmp ::= int

var ::= (String | Blob) size offset | type offset
type ::= [0x80..0xff]                # This is stored::Type::type with 0x80 or'ed into it.
size ::= int
offset ::= int

skip ::= [1..0x1f]

stored::find()

template<typename Container>
inline Variant<Container> stored::find(Container &container, uint8_t const *directory, char const *name, size_t len = std::numeric_limits<size_t>::max()) noexcept

Finds an object in a directory.

Parameters:

  • container – the container that has the buffer and directory. Specify the actual (lowest) subclass of the store.

  • directory – the binary directory description

  • name – the name to find, can be abbreviated as long as it is unambiguous

  • len – the maximum length of name to parse

Returns:

a variant, which is not valid when not found

stored::list()

void stored::list(void *container, void *buffer, uint8_t const *directory, ListCallbackArg *f, void *arg, char const *prefix)

Iterates over all objects in the directory and invoke a callback for every object.

This function is not reentrant. Do not call it recursively.

Parameters:

  • container – the container that contains buffer and directory

  • buffer – the buffer that holds the data of all variables

  • directory – the binary directory, to be parsed

  • f – the callback function

  • arg – an arbitrary argument to be passed to f

  • prefix – when not nullptr, a string that is prepended for the name that is supplied to f