From 57b9d4a47468cc2217f75820dc020fd9ba410d89 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sat, 8 Nov 2014 23:33:13 +0100 Subject: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- src/mds-kbdc/tree.h | 401 +++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 364 insertions(+), 37 deletions(-) (limited to 'src/mds-kbdc/tree.h') diff --git a/src/mds-kbdc/tree.h b/src/mds-kbdc/tree.h index 1ab69d7..e87f159 100644 --- a/src/mds-kbdc/tree.h +++ b/src/mds-kbdc/tree.h @@ -23,24 +23,99 @@ +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_information_t` + */ #define MDS_KBDC_TREE_TYPE_INFORMATION 0 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_information_language_t` + */ #define MDS_KBDC_TREE_TYPE_INFORMATION_LANGUAGE 1 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_information_country_t` + */ #define MDS_KBDC_TREE_TYPE_INFORMATION_COUNTRY 2 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_information_variant_t` + */ #define MDS_KBDC_TREE_TYPE_INFORMATION_VARIANT 3 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_include_t` + */ #define MDS_KBDC_TREE_TYPE_INCLUDE 4 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_function_t` + */ #define MDS_KBDC_TREE_TYPE_FUNCTION 5 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_macro_t` + */ #define MDS_KBDC_TREE_TYPE_MACRO 6 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_assumption` + */ #define MDS_KBDC_TREE_TYPE_ASSUMPTION 7 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_assumption_have_t` + */ #define MDS_KBDC_TREE_TYPE_ASSUMPTION_HAVE 8 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_assumption_have_chars_t` + */ #define MDS_KBDC_TREE_TYPE_ASSUMPTION_HAVE_CHARS 9 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_assumption_have_range_t` + */ #define MDS_KBDC_TREE_TYPE_ASSUMPTION_HAVE_RANGE 10 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_for_t` + */ #define MDS_KBDC_TREE_TYPE_FOR 11 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_if_t` + */ #define MDS_KBDC_TREE_TYPE_IF 12 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_let_t` + */ #define MDS_KBDC_TREE_TYPE_LET 13 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_map_t` + */ #define MDS_KBDC_TREE_TYPE_MAP 15 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_array_t` + */ #define MDS_KBDC_TREE_TYPE_ARRAY 16 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_keys_t` + */ #define MDS_KBDC_TREE_TYPE_KEYS 17 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_string_t` + */ #define MDS_KBDC_TREE_TYPE_STRING 18 + +/** + * Value of `mds_kbdc_tree_t.type` for `mds_kbdc_tree_type_macro_call_t` + */ #define MDS_KBDC_TREE_TYPE_MACRO_CALL 19 @@ -49,163 +124,409 @@ * Keyboard layout syntax tree */ union mds_kbdc_tree __attribute__((transparent)); + +/** + * Keyboard layout syntax tree + */ typedef union mds_kbdc_tree mds_kbdc_tree_t; -struct mds_kbdc_tree_simple +/** + * This macro is used in this header file, and is then + * undefined. It defined the common members for these + * tree structures. + * + * It defines: + * - int type; -- Integer that specifies which structure is used + * - mds_kbdc_tree_t*; -- The next node in the tree, at the same level; a sibling + */ +#define MDS_KBDC_TREE_COMMON int type; mds_kbdc_tree_t* next + +/** + * This macro is used in this header file, and is then + * undefined. It defined padding of a tree structure. + * + * @param S:size_t The size of the data structure excluding this padding and + * the members defined by the macro `MDS_KBDC_TREE_COMMON` + */ +#define MDS_KBDC_TREE_PADDING_(S) char _padding[(5 * sizeof(void*) - (S)) / sizeof(char)] + +/** + * This macro is used in this header file, and is then + * undefined. It defined padding of a tree structure. + * + * @param N The number of sizeof(void*) sized memebers defined data + * structure excluding this padding and the members defined + * by the macro `MDS_KBDC_TREE_COMMON` + */ +#define MDS_KBDC_TREE_PADDING(N) MDS_KBDC_TREE_PADDING((N) * sizeof(void*)) + + + +/** + * This datastructure is not meant to be + * used directly, it is a common definition + * for tree structurs that only have, beside + * the common members, a pointer to the first + * node on next level in the tree + */ +struct mds_kbdc_tree_nesting { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The first child node, `.inner.next` + * is used to access the second child node. + */ mds_kbdc_tree_t* inner; + + MDS_KBDC_TREE_PADDING(1); }; -typedef struct mds_kbdc_tree_simple mds_kbdc_tree_information_t; +/** + * Tree structure for the "information"-keyword + */ +typedef struct mds_kbdc_tree_nesting mds_kbdc_tree_information_t; +/** + * This datastructure is not meant to be + * used directly, it is a common definition + * for the tree structurs for the information + * entries: the children of `mds_kbdc_tree_information_t` + */ struct mds_kbdc_tree_information_data { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The value of the information entry + */ char* data; + + MDS_KBDC_TREE_PADDING(1); }; +/** + * Declaration of one of the languages for which the layout is designed + */ typedef struct mds_kbdc_tree_information_data mds_kbdc_tree_information_language_t; + +/** + * Declaration of one of the country for which the layout is designed + */ typedef struct mds_kbdc_tree_information_data mds_kbdc_tree_information_country_t; + +/** + * Declaration of which variant of the language–country the layout is + */ typedef struct mds_kbdc_tree_information_data mds_kbdc_tree_information_variant_t; +/** + * Leaf structure for inclusion of a file + */ typedef struct mds_kbdc_tree_include { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The filename of the file to include + */ char* filename; + MDS_KBDC_TREE_PADDING(1); + } mds_kbdc_tree_include_t; +/** + * This datastructure is not meant to be + * used directly, it is a common definition + * for tree structurs that define a callable + * element + */ struct mds_kbdc_tree_callable { - int type; - mds_kbdc_tree_t* next; - char* data; + MDS_KBDC_TREE_COMMON; + + /** + * The name of the callable + */ + char* name; + + /** + * The first child node, `.inner.next` + * is used to access the second child node + */ mds_kbdc_tree_t* inner; + + MDS_KBDC_TREE_PADDING(2); }; +/** + * Tree structure for a function + */ typedef struct mds_kbdc_tree_callable mds_kbdc_tree_function_t; + +/** + * Tree structure for a macro + */ typedef struct mds_kbdc_tree_callable mds_kbdc_tree_macro_t; -typedef struct mds_kbdc_tree_simple mds_kbdc_tree_assumption_t; +/** + * Tree structure for the "assumption"-keyword + */ +typedef struct mds_kbdc_tree_nesting mds_kbdc_tree_assumption_t; +/** + * Treeu structure for making the assumption + * that there is a mapping to a key or string + */ typedef struct mds_kbdc_tree_assumption_have { - int type; - mds_kbdc_tree_t* next; - char* keys; + MDS_KBDC_TREE_COMMON; + + /** + * The key or string + */ + mds_kbdc_tree_t* data; + + MDS_KBDC_TREE_PADDING(1); } mds_kbdc_tree_assumption_have_t; +/** + * Leaf structure for making the assumption + * that there are mappings to a set of characters + */ typedef struct mds_kbdc_tree_assumption_have_chars { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The characters + */ char* chars; + MDS_KBDC_TREE_PADDING(1); + } mds_kbdc_tree_assumption_have_chars_t; +/** + * Leaf structure for making the assumption + * that there are mappings to a range of characters + */ typedef struct mds_kbdc_tree_assumption_have_range { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The first character, inclusive + */ char* first; + + /** + * The last character, inclusive + */ char* last; + MDS_KBDC_TREE_PADDING(2); + } mds_kbdc_tree_assumption_have_range_t; +/** + * Tree structure for a "for"-loop + */ typedef struct mds_kbdc_tree_for { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The first value to variable should take, inclusive + */ char* first; + + /** + * The last value the variable should take, inclusive + */ char* last; + + /** + * The variable + */ char* variable; + /** + * The first child node, `.inner.next` is + * used to access the second child node. + * This is what should be done inside the loop. + */ + mds_kbdc_tree_t* inner; + + MDS_KBDC_TREE_PADDING(4); + } mds_kbdc_tree_for_t; +/** + * Tree structure for a "if"-statement + */ typedef struct mds_kbdc_tree_if { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The condition + */ char* condition; + + /** + * This is what should be done inside + * if the condition is satisfied + */ mds_kbdc_tree_t* inner; + + /** + * This is what should be done inside + * if the condition is not satisfied + */ mds_kbdc_tree_t* otherwise; + MDS_KBDC_TREE_PADDING(3); + } mds_kbdc_tree_if_t; +/** + * Tree structure for assigning a value to a variable, + * possibly declaring the variable in the process + */ typedef struct mds_kbdc_tree_let { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The variable + */ char* variable; + + /** + * The value to assign to the variable + */ mds_kbdc_tree_t* value; + MDS_KBDC_TREE_PADDING(2); + } mds_kbdc_tree_let_t; +/** + * Tree structure for mapping a (possible single element) + * sequence of key combinations or strings to another + * combination or string or sequence there of + */ typedef struct mds_kbdc_tree_map { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The input sequence + */ mds_kbdc_tree_t* sequence; + + /** + * The output sequence + */ mds_kbdc_tree_t* result; + MDS_KBDC_TREE_PADDING(2); + } mds_kbdc_tree_map_t; +/** + * Tree structure for an array of values + */ typedef struct mds_kbdc_tree_array { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The first value, `.elements.next` + * is used to access the second value. + */ mds_kbdc_tree_t* elements; + MDS_KBDC_TREE_PADDING(1); + } mds_kbdc_tree_array_t; +/** + * Leaf structure for a key combination + */ typedef struct mds_kbdc_tree_keys { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The key combination + */ char* keys; + MDS_KBDC_TREE_PADDING(1); + } mds_kbdc_trees_key_t; +/** + * Leaf structure for a string + */ typedef struct mds_kbdc_tree_string { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The string + */ char* string; + MDS_KBDC_TREE_PADDING(1); + } mds_kbdc_tree_string_t; +/** + * Tree structure for a macro call + */ typedef struct mds_kbdc_tree_macro_call { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + + /** + * The name of the macro + */ char* name; + + /** + * The first input argument for the + * macro call, the second is accessed + * using `.arguments.next` + */ mds_kbdc_tree_t* arguments; + MDS_KBDC_TREE_PADDING(2); + } mds_kbdc_tree_macro_call_t; @@ -217,9 +538,10 @@ union mds_kbdc_tree { struct { - int type; - mds_kbdc_tree_t* next; + MDS_KBDC_TREE_COMMON; + MDS_KBDC_TREE_PADDING(0); }; + mds_kbdc_tree_information_t information; mds_kbdc_tree_information_language_t language; mds_kbdc_tree_information_country_t country; @@ -242,5 +564,10 @@ union mds_kbdc_tree }; + +#undef MDS_KBDC_TREE_PADDING +#undef MDS_KBDC_TREE_PADDING_ +#undef MDS_KBDC_TREE_COMMON + #endif -- cgit v1.2.3-70-g09d2