The C-Specific Core

The API of the C-specific core is meant to aid in generating glue code in the C language for the represented types. Method naming roughly follows the convention:

• <name>: utility function. One should check the type signature and documentation to find out its purpose.

• gen_<name>: method that generates a list of “naked” C statements in the sense that the caller needs to properly format them and add separators.

• gen_<name>_expr: method that generates a (sub-)expression of a statement. Used by the caller in building statements.

class FtnDb(*args, **kwargs)

Bases: FtnDb

FTN_GETTER_PREFIX = 'FTNC_get__'

FTN_SETTER_PREFIX = 'FTNC_put__'

requirements(types: List[Uid] = []) → List[str]

Parses through a list of given types and returns a set of their include requirements. If types not provided it searches through all defined types.

gen_typename_expr(entry: Uid) → str

Generates the (prefix) type name for a loaded type. If the type is local, generates the C expression for that type.

gen_decl(entry: Entry, var: str, usage=None, static=False) → List[str]

Generates the statements for declaring (and eventually initializing) a type.

Parameters:

• usage – overrides the generated expression

• static – prefixes the definition with the ‘static’ keyword

gen_typedef(entry: Uid, allow_void=False)

Generates a statement for a typedef expression.

gen_access_macros_expr(entry: Uid, read_only: bool = False) → List[str]

Generates access macros for all elements of this type as newline-separated expressions (not statements).

access_dict(uid: TypeABC | Uid, read_only: bool = False) → Dict

Returns the access expressions for each element in this type as a dictionary tree (i.e., JSON object) accessible, e.g., from within a template expander.

add_source(module: str, name: str, src: Dict) → None

Adds a user-provided raw source in the database.

static clear_instance()

Static destructor. Allows the subsequent creation of a new handler.

dump(uid: Uid | str) → Dict

Serializes a previously loaded type.

get(what: Uid | str | TypeABC) → TypeABC

Returns a fully-built and loaded type definition. If not found it searches for its source module, deserializes using a corresponding base type schema and stores it in the database for future use.

static instance()

Static access method.

loaded_types() → List[Uid]

Returns UIDs of all constructed and stored types

make_entry(name: str | None = None, from_ftn: str | None = None, from_spec: Dict | None = None, value: str | None = None) → Entry

(Possibly constructs and) stores a FTN data type into the current database and returns an Entry object pointing to it.

Parameters:

• name – (mutually exclusive with from_ftn, from_spec) qualified name to previously loaded type (calls get() for good measure)

• from_ftn – (mutually exclusive with name, from_spec) string with binding or expression in the FTN language.

• from_spec – (mutually exclusive with name, from_ftn) string with binding or expression in raw format.

• value – initialization value.

parse(src) → TypeABC

Returns a base FTN type from a raw source expression without adding it to the database.

schema(base_type_name: str) → Schema

Returns the JSON schema used to parse a raw source expression into a base type.

to_raw()

Returns the dictionaries of raw JSON/AST sources.

type_dependency_graph() → DiGraph

Builds a NetworkX graph representing the type dependencies of all constructed and stored types.

class TypeRef(type: str, readonly: bool, _info: dict | None, ref: Uid, range_mod: Range | None = None, endian_mod: Endian | None = None, bit_size: IntBase | None = None)

Bases: TypeRef, TypeABC

Qualified reference to another (defined) type.

requirements() → Set[str]

Returns the include requirements of the referred type

has_subscript() → bool

Checks if referred type needs to be indexed.

gen_ctype_expr(name, allow_void=False) → str

Returns the name of the referred type.

Returns:

(prefix, “”)

gen_access_expr(src_expr: str, iter_lvl: int) → List[Tuple[List, List, str, str]]

Returns the components to build the access expression for the referred type.

Parameters:

• src_expr – arbitrary name for the variable in the access macro.

• iter_lvl – how deep the current index level is.

Returns:

list of 4-tuples (field-path, access-args, access-expr, read-only)

gen_subscript_expr(arr_expr: str) → Tuple[str, str]

Returns the components for generating an eventual subscript expression for the referred type.

Parameters:

arr_expr – expression which evauates to an array type.

gen_length_expr(arr_expr: str) → Tuple[str, bool]

Returns the components to build the length expression for the referred type

Parameters:

arr_expr – expression which evauates to an array type.

need_malloc() → bool

Checks if the referred type needs memory allocation.

bit_size: IntBase | None = None

derefer() → TypeABC

Overloads the base method. Recurs into the referenced type.

endian_mod: Endian | None = None

gen_base_size_expr(acc_expr: str) → str

Generates an expression that calculates the header size for this type (i.e., the first element)

Parameters:

acc_expr – data access expression.

gen_copy(dst_ptr: str, dst_acc_expr: str, src_ptr: str, src_acc_expr: str) → List[str]

Generates the statements for a copy expressions.

Parameters:

• dst_ptr – name of the destination buffer.

• dst_acc_expr – access expression for the data in dst_ptr

• src_ptr – name of the source buffer.

• src_acc_expr – access expression for the data in src_ptr

gen_ctor(buf_var: str, acc_expr: str, ptr_fixup: bool = True) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a constructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable.

• acc_expr – access expression for data in buf_var (e.g., pointer notation)

• prt_fixup – true if it needs a pointer fixup expression after construction (i.e., update the pointer).

gen_desctor(buf_var: str, buf_val: str | None = None) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a destructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable

• buf_val – initial (reset) value for the buffer.

gen_marshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

gen_size_expr(acc_expr: str) → str

Generates an expression that calculates the total size of the data contained by this type.

Parameters:

acc_expr – data access expression.

gen_unmarshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

get_referred_type() → TypeABC

Retrieves the (previously loaded) referenced type from the current FtnDb singleton.

range_mod: Range | None = None

select_types(of_class=None) → List[TypeABC]

Predicate selection function. Recurs into the referenced type.

set_readonly(value: bool)

ref: Uid

type: str

readonly: bool

class Structure(type: str, readonly: bool, _info: dict | None, field: Dict[str, TypeABC])

Bases: Structure, TypeABC

A structure type is represented as a dictionary of other types.

requirements() → Set[str]

Returns the set of include requirements for all fields.

gen_ctype_expr(name: str, allow_void: bool = False) → Tuple[str, str]

Generates the full C expression for defining this struct type. Structure definitions do not have a suffix, hence the second element of the tupe is an empty string.

Returns:

(prefix, “”)

gen_access_expr(src_expr: str, iter_lvl: int) → List[Tuple[List, List, str, str]]

Returns the components to build the access expression every field in this structure.

Parameters:

• src_expr – arbitrary name for the variable in the access macro.

• iter_lvl – how deep the current index level is.

Returns:

list of 4-tuples (field-path, access-args, access-expr, read-only)

need_malloc() → bool

Checks if any of the fields needs memory allocation

derefer() → TypeABC

Returns ‘self’. Possibly overloaded by instances.

gen_base_size_expr(acc_expr: str) → str

Generates an expression that calculates the header size for this type (i.e., the first element)

Parameters:

acc_expr – data access expression.

gen_copy(dst_ptr: str, dst_acc_expr: str, src_ptr: str, src_acc_expr: str) → List[str]

Generates the statements for a copy expressions.

Parameters:

• dst_ptr – name of the destination buffer.

• dst_acc_expr – access expression for the data in dst_ptr

• src_ptr – name of the source buffer.

• src_acc_expr – access expression for the data in src_ptr

gen_ctor(buf_var: str, acc_expr: str, ptr_fixup: bool = True) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a constructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable.

• acc_expr – access expression for data in buf_var (e.g., pointer notation)

• prt_fixup – true if it needs a pointer fixup expression after construction (i.e., update the pointer).

gen_desctor(buf_var: str, buf_val: str | None = None) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a destructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable

• buf_val – initial (reset) value for the buffer.

gen_length_expr(arr_expr: str) → Tuple[str | None, bool | None]

Returns a tuple of None. This type does not have a length expression.

gen_marshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

gen_size_expr(acc_expr: str) → str

Generates an expression that calculates the total size of the data contained by this type.

Parameters:

acc_expr – data access expression.

gen_unmarshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

has_subscript() → bool

Returns false this type does not need indexing.

select_types(of_class=None) → List[TypeABC]

Predicate selection function. Recurs into all contained types.

set_readonly(value: bool)

field: Dict[str, TypeABC]

type: str

readonly: bool

class Array(type: str, readonly: bool, _info: dict | None, range: Range, element_type: TypeABC, len_field: str | None = None)

Bases: Array, TypeABC

Array type.

requirements() → Set[str]

Returns the requirements of the base type.

has_subscript() → bool

Returns true. An array needs indexing.

gen_ctype_expr(name, allow_void=False) → Tuple[str, str]

Generates the C expression defining this array. If its range is fixed (i.e., range.low = range.high) then it is defined as a statically-allocated C array. Otherwise, it is defined as a structure with inferred elements such as pointer, offset and length.

Returns:

(prefix, suffix)

gen_access_expr(src_expr: str, iter_lvl: int) → List[Tuple[List, List, str, str]]

Returns the components to build the access expression for everything contained in the element with an appended static LEN field.

Parameters:

• src_expr – arbitrary name for the variable in the access macro.

• iter_lvl – how deep the current index level is.

Returns:

list of 4-tuples (field-path, access-args, access-expr, read-only)

gen_subscript_expr(arr_expr: str) → Tuple[str, str]

Generates an indexing expression.

Returns:

(“<expr>[”, “]”)

gen_length_expr(arr_expr: str) → Tuple[str, bool]

Generates a lenghth expression, together with a bool representing whether the length is fixed or not.

need_malloc() → bool

Returns true if the length is not fixed or if the element needs memory allocation; otherwise false.

derefer() → TypeABC

Returns ‘self’. Possibly overloaded by instances.

gen_base_size_expr(acc_expr: str) → str

Generates an expression that calculates the header size for this type (i.e., the first element)

Parameters:

acc_expr – data access expression.

gen_copy(dst_ptr: str, dst_acc_expr: str, src_ptr: str, src_acc_expr: str) → List[str]

Generates the statements for a copy expressions.

Parameters:

• dst_ptr – name of the destination buffer.

• dst_acc_expr – access expression for the data in dst_ptr

• src_ptr – name of the source buffer.

• src_acc_expr – access expression for the data in src_ptr

gen_ctor(buf_var: str, acc_expr: str, ptr_fixup: bool = True) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a constructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable.

• acc_expr – access expression for data in buf_var (e.g., pointer notation)

• prt_fixup – true if it needs a pointer fixup expression after construction (i.e., update the pointer).

gen_desctor(buf_var: str, buf_val: str | None = None) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a destructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable

• buf_val – initial (reset) value for the buffer.

gen_marshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

gen_size_expr(acc_expr: str) → str

Generates an expression that calculates the total size of the data contained by this type.

Parameters:

acc_expr – data access expression.

gen_unmarshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

len_field: str | None = None

select_types(of_class=None) → List[TypeABC]

Predicate selection function. Recurs into the contained type.

set_readonly(value: bool)

range: Range

element_type: TypeABC

type: str

readonly: bool

class Void(type: str, readonly: bool, _info: dict | None)

Bases: Void, TypeABC

gen_ctype_expr(name, allow_void=False) → Tuple[str, str]

If allow_void is false, throws an error.

Returns:

(“void”, “”)

gen_access_expr(src_expr, iter_lvl) → None

A void element has no access expresison.

derefer() → TypeABC

Returns ‘self’. Possibly overloaded by instances.

gen_base_size_expr(acc_expr: str) → str

Generates an expression that calculates the header size for this type (i.e., the first element)

Parameters:

acc_expr – data access expression.

gen_copy(dst_ptr: str, dst_acc_expr: str, src_ptr: str, src_acc_expr: str) → List[str]

Generates the statements for a copy expressions.

Parameters:

• dst_ptr – name of the destination buffer.

• dst_acc_expr – access expression for the data in dst_ptr

• src_ptr – name of the source buffer.

• src_acc_expr – access expression for the data in src_ptr

gen_ctor(buf_var: str, acc_expr: str, ptr_fixup: bool = True) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a constructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable.

• acc_expr – access expression for data in buf_var (e.g., pointer notation)

• prt_fixup – true if it needs a pointer fixup expression after construction (i.e., update the pointer).

gen_desctor(buf_var: str, buf_val: str | None = None) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a destructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable

• buf_val – initial (reset) value for the buffer.

gen_length_expr(arr_expr: str) → Tuple[str | None, bool | None]

Returns a tuple of None. This type does not have a length expression.

gen_marshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

gen_size_expr(acc_expr: str) → str

Generates an expression that calculates the total size of the data contained by this type.

Parameters:

acc_expr – data access expression.

gen_unmarshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

has_subscript() → bool

Returns false this type does not need indexing.

need_malloc() → bool

Returns false. This type does not need memory allocation.

requirements() → Set[str]

This type has no include requirement.

select_types(of_class=None) → List[TypeABC]

Predicate selection function.

set_readonly(value: bool)

type: str

readonly: bool

class Integer(type: str, readonly: bool, _info: dict | None, range: Range, endian: Endian | None = None, bit_size: IntBase | None = None)

Bases: Integer, TypeABC

C integer type.

requirements() → Set[str]

This representation uses explicit integer types as defined in <inttypes.h>. Bit-swap functions are defined in the in-house header file ‘DFL_util.h’ found in the ‘assets’ folder.

gen_ctype_expr(name: str, allow_void=False) → Tuple[str, str]

Chooses an appropriate type representation for this integer based on its properties.

Returns:

(“<expr>”, “”)

gen_c_value(value) → str

Normalizes a given value to a C integer value representation.

gen_access_expr(src_expr: str, iter_lvl: int) → List[Tuple[List, List, str, str]]

Generates the appropriate access expression for this integer based on its properties (e.g., endianness).

Parameters:

• src_expr – arbitrary name for the variable in the access macro.

• iter_lvl – how deep the current index level is.

Returns:

singleton list witn a 4-tuple ([], [], access-expr, read-only)

bit_size: IntBase | None = None

derefer() → TypeABC

Returns ‘self’. Possibly overloaded by instances.

endian: Endian | None = None

gen_base_size_expr(acc_expr: str) → str

Generates an expression that calculates the header size for this type (i.e., the first element)

Parameters:

acc_expr – data access expression.

gen_copy(dst_ptr: str, dst_acc_expr: str, src_ptr: str, src_acc_expr: str) → List[str]

Generates the statements for a copy expressions.

Parameters:

• dst_ptr – name of the destination buffer.

• dst_acc_expr – access expression for the data in dst_ptr

• src_ptr – name of the source buffer.

• src_acc_expr – access expression for the data in src_ptr

gen_ctor(buf_var: str, acc_expr: str, ptr_fixup: bool = True) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a constructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable.

• acc_expr – access expression for data in buf_var (e.g., pointer notation)

• prt_fixup – true if it needs a pointer fixup expression after construction (i.e., update the pointer).

gen_desctor(buf_var: str, buf_val: str | None = None) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a destructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable

• buf_val – initial (reset) value for the buffer.

gen_length_expr(arr_expr: str) → Tuple[str | None, bool | None]

Returns a tuple of None. This type does not have a length expression.

gen_marshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

gen_size_expr(acc_expr: str) → str

Generates an expression that calculates the total size of the data contained by this type.

Parameters:

acc_expr – data access expression.

gen_unmarshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

has_subscript() → bool

Returns false this type does not need indexing.

need_malloc() → bool

Returns false. This type does not need memory allocation.

normalize_value(value) → int | None

Tries to convert a value to a Python int. Returns None if unsuccessful.

select_types(of_class=None) → List[TypeABC]

Predicate selection function.

set_readonly(value: bool)

range: Range

type: str

readonly: bool

class Boolean(type: str, readonly: bool, _info: dict | None, bit_size: IntBase | None = None)

Bases: Boolean, TypeABC

Boolean C type.

requirements() → Set[str]

This representation uses the “bool” type as defined in <stdbool.h>

gen_ctype_expr(name, allow_void=False) → Tuple[str, str]

Returns:

(“bool”, “”)

gen_c_value(value) → str

Normalizes a given value to a C bool representation.

gen_access_expr(src_expr: str, iter_lvl: int) → List[Tuple[List, List, str, str]]

Returns access expression. Relevant for complex caller types.

bit_size: IntBase | None = None

derefer() → TypeABC

Returns ‘self’. Possibly overloaded by instances.

gen_base_size_expr(acc_expr: str) → str

Generates an expression that calculates the header size for this type (i.e., the first element)

Parameters:

acc_expr – data access expression.

gen_copy(dst_ptr: str, dst_acc_expr: str, src_ptr: str, src_acc_expr: str) → List[str]

Generates the statements for a copy expressions.

Parameters:

• dst_ptr – name of the destination buffer.

• dst_acc_expr – access expression for the data in dst_ptr

• src_ptr – name of the source buffer.

• src_acc_expr – access expression for the data in src_ptr

gen_ctor(buf_var: str, acc_expr: str, ptr_fixup: bool = True) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a constructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable.

• acc_expr – access expression for data in buf_var (e.g., pointer notation)

• prt_fixup – true if it needs a pointer fixup expression after construction (i.e., update the pointer).

gen_desctor(buf_var: str, buf_val: str | None = None) → List[str]

If the type needs memory allocation (see need_malloc()) it generates the statements for a destructor and returns it. Otherwise it returns an empty list.

Parameters:

• buf_var – name of the buffer variable

• buf_val – initial (reset) value for the buffer.

gen_length_expr(arr_expr: str) → Tuple[str | None, bool | None]

Returns a tuple of None. This type does not have a length expression.

gen_marshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

gen_size_expr(acc_expr: str) → str

Generates an expression that calculates the total size of the data contained by this type.

Parameters:

acc_expr – data access expression.

gen_unmarshal(buf_ptr: str, acc_expr: str) → List[str]

Generates the statements for type marshalling.

Parameters:

• buf_ptr – name of the destination buffer.

• acc_expr – access expression for the data at buf_ptr

has_subscript() → bool

Returns false this type does not need indexing.

need_malloc() → bool

Returns false. This type does not need memory allocation.

normalize_value(value) → bool | None

Tries to convert a value to a Python bool. Returns None if unsuccessful.

select_types(of_class=None) → List[TypeABC]

Predicate selection function.

set_readonly(value: bool)

type: str

readonly: bool