pEpACIDgen/gen/data/input/test_data/test_lib.h

#ifndef MAIN_INCLUDE_H
#define MAIN_INCLUDE_H

#include "typedefs.h"
#include "enums.h"
#include "structs.h"
#include "functions.h"
#include "vars.h"

// Gen-CID
// =======
// Gen-CID generates a C Interface Defintion file (json) given the inputs:
// * headerfile
// * list of function names needed
// * list of var names needed
// The generator searches each function/var in the headerfile (recursively) and collects all the
// types needed (var type, return type, parm types).
// As structs can contain further types, these dependent types need to be collected
// recursively.
// Finally, all the collected types will be resolved to their final underlying type.
// If a type is primitive, nothing needs to be done its already defined.
// But types of typekind struct or enum need to be defined.
// Their definition will be searched for in the headerfile and included in the interface definition
// The CID file contains all the information needed to represet:
// * functions
// * vars
// * structs
// * enums
// Well enough so they can be expressed in pyBind11
// use "pyBind11-CID" to generate the pyBind11 code out of the CID file.
//
// Gen-CID test library
// --------------------
// This here is the test main test library for Gen-CID.
// The C language is broken down into its components and common pattern.
// It is a humble attempt to cover all possible combinations that can be created in the
// C language. (like, struct containing` primitive, struct containing struct, typedef chains,
// etc..).
// Please note, that pointer types have not been addressed yet (at all)
//
// The intended use of this test lib is: If you encounter a scenario using Gen-CID that poses problem
// it is most likely that the scenario can be reproduced using this test lib pretty easily.
// lets say you Gen-CID a function with sig:
// TT_E(*)(ACCS), where:
//      TT_E = typedef of typedef of an enum without an alias.
//      ACCS = Alias to a complex struct containing another complex struct
// these types exist already along with a systematic permutation of possible types that amount
// to over 100 of types.
// just write your func/var using these types and debug the generation.


// The CID format deals with items. Everything is an item.
// There are qualifiers that can be used and combined to define an item. (list below)
// e.g PS = primitive struct that possibly has a typedef
//
// Of all the possible combinations, not all are valid (C lang). Its a futile attempt
// trying to cover all the valid ones. But an effort has been made to cover the most
// of the valid combinations.
// Combination of structs, enums and typedefs are systematically explored in the files:
// * structs.h
// * enums.h
// * typedefs.h
//
// For all the types defined the file:
// * vars.h
// contains an instance of each.
//
// for all the possible function signature, well with a 100 types,
// we can create 10000 different sigantures using 1 ret and 1 arg.
// Therefore, no functions have been defined.
// define them when you are interested in the combination, and Gen-CID the defintion.


// Item Qualitfier
// ===============
// V     = Void                                     already defined
// P     = Primitive Type                           already defined
// S     = Struct                                   -> struct.h
// E     = Enum                                     -> enums.h
// A     = Alias                                    -> structs.h/enums.h
// N     = Nested (Structs only, cant be aliased)   -> structs.h
// H     = Hosting (Structs only                    -> structs.h
//         containing the nested struct, cant be primitive)
// T     = typedef                                  -> typedefs.h
// I     = Incomplete / (forward decl)              -> struct.h/enums.h
//
// func_ = function                                 -> functions.h
// var_  = variable                                 -> vars.h
//
// prefixed underline (e.g _E) means no typedef/alias exists for this item (enum in this case)
//
// Alias vs. Typedef
// -----------------
// aliased means direct typedef directly, like
// structs and enums only
/*
 * typedef struct _X {
     int x;
 * } X;
 *
 */

// Typedef means, not typdeffed directly, but anywhere, like
/*
 * typedef _X X;
 *
 */


#endif //MAIN_INCLUDE_H