flatcc.h (9060B)
1 #ifndef FLATCC_H 2 #define FLATCC_H 3 4 #ifdef __cplusplus 5 extern "C" { 6 #endif 7 8 /* 9 * This is the primary `flatcc` interface when compiling `flatcc` as a 10 * library. Functions and types in the this interface will be kept 11 * stable to the extend possible or reasonable, but do not rely on other 12 * interfaces except "config.h" used to set default options for this 13 * interface. 14 * 15 * This interface is unrelated to the standalone flatbuilder library 16 * which has a life of its own. 17 */ 18 19 #include <stddef.h> 20 21 #ifndef UINT8_MAX 22 #include <stdint.h> 23 #endif 24 25 #ifdef _MSC_VER 26 #pragma warning(push) 27 #pragma warning(disable: 4820) /* x bytes padding added in struct */ 28 #endif 29 30 typedef struct flatcc_options flatcc_options_t; 31 typedef void (*flatcc_error_fun) (void *err_ctx, const char *buf, size_t len); 32 33 struct flatcc_options { 34 size_t max_schema_size; 35 int max_include_depth; 36 int max_include_count; 37 int disable_includes; 38 int allow_boolean_conversion; 39 int allow_enum_key; 40 int allow_enum_struct_field; 41 int allow_multiple_key_fields; 42 int allow_primary_key; 43 int allow_scan_for_all_fields; 44 int allow_string_key; 45 int allow_struct_field_deprecate; 46 int allow_struct_field_key; 47 int allow_struct_root; 48 int ascending_enum; 49 int hide_later_enum; 50 int hide_later_struct; 51 int offset_size; 52 int voffset_size; 53 int utype_size; 54 int bool_size; 55 int require_root_type; 56 int strict_enum_init; 57 uint64_t vt_max_count; 58 59 const char *default_schema_ext; 60 const char *default_bin_schema_ext; 61 const char *default_bin_ext; 62 63 /* Code Generator specific options. */ 64 int gen_stdout; 65 int gen_dep; 66 67 const char *gen_depfile; 68 const char *gen_deptarget; 69 const char *gen_outfile; 70 71 int gen_append; 72 73 int cgen_pad; 74 int cgen_sort; 75 int cgen_pragmas; 76 77 int cgen_common_reader; 78 int cgen_common_builder; 79 int cgen_reader; 80 int cgen_builder; 81 int cgen_verifier; 82 int cgen_json_parser; 83 int cgen_json_printer; 84 int cgen_recursive; 85 int cgen_spacing; 86 int cgen_no_conflicts; 87 88 89 int bgen_bfbs; 90 int bgen_qualify_names; 91 int bgen_length_prefix; 92 93 /* Namespace args - these can override defaults so are null by default. */ 94 const char *ns; 95 const char *nsc; 96 97 const char **inpaths; 98 const char **srcpaths; 99 int inpath_count; 100 int srcpath_count; 101 const char *outpath; 102 }; 103 104 /* Runtime configurable optoins. */ 105 void flatcc_init_options(flatcc_options_t *opts); 106 107 typedef void *flatcc_context_t; 108 109 /* 110 * Call functions below in order listed one at a time. 111 * Each parse requires a new context. 112 * 113 * A reader file is named after the source base name, e.g. 114 * `monster.fbs` becomes `monster.h`. Builders are optional and created 115 * as `monster_builder.h`. A reader require a common header 116 * `flatbuffers_commoner.h` and a builder requires 117 * `flatbuffers_common_builder.h` in addition to the reader filers. A 118 * reader need no other source, but builders must link with the 119 * `flatbuilder` library and include files in `include/flatbuffers`. 120 * 121 * All the files may also be concatenated into one single file and then 122 * files will not be attempted included externally. This can be used 123 * with stdout output. The common builder can follow the common 124 * reader immediately, or at any later point before the first builder. 125 * The common files should only be included once, but not harm is done 126 * if duplication occurs. 127 * 128 * The outpath is prefixed every output filename. The containing 129 * directory must exist, but the prefix may have text following 130 * the directory, for example the namespace. If outpath = "stdout", 131 * files are generated to stdout. 132 * 133 * Note that const char * options must remain valid for the lifetime 134 * of the context since they are not copied. The options object itself 135 * is not used after initialization and may be reused. 136 */ 137 138 /* 139 * `name` is the name of the schema file or buffer. If it is path, the 140 * basename is extracted (leading path stripped), and the default schema 141 * extension is stripped if present. The resulting name is used 142 * internally when generating output files. Typically the `name` 143 * argument will be the same as a schema file path given to 144 * `flatcc_parse_file`, but it does not have to be. 145 * 146 * `name` may be null if only common files are generated. 147 * 148 * `error_out` is an optional error handler. If null output is truncated 149 * to a reasonable size and sent to stderr. `error_ctx` is provided as 150 * first argument to `error_out` if `error_out` is non-zero, otherwise 151 * it is ignored. 152 * 153 * Returns context or null on error. 154 */ 155 flatcc_context_t flatcc_create_context(flatcc_options_t *options, const char *name, 156 flatcc_error_fun error_out, void *error_ctx); 157 158 /* Like `flatcc_create_context`, but with length argument for name. */ 159 /* 160 * Parse is optional - not needed for common files. If the input buffer version 161 * is called, the buffer must be zero terminated, otherwise an input 162 * path can be specified. The output path can be null. 163 * 164 * Only one parse can be called per context. 165 * 166 * The buffer size is limited to the max_schema_size option unless it is 167 * 0. The default is reasonable size like 64K depending on config flags. 168 * 169 * The buffer must remain valid for the duration of the context. 170 * 171 * The schema cannot contain include statements when parsed as a buffer. 172 * 173 * Returns 0 on success. 174 */ 175 int flatcc_parse_buffer(flatcc_context_t ctx, const char *buf, size_t buflen); 176 177 /* 178 * If options contain a non-zero `inpath` option, the resulting filename is 179 * prefixed with that path unless the filename is an absolute path. 180 * 181 * Errors are sent to the error handler given during initialization, 182 * or to stderr. 183 * 184 * The file size is limited to the max_schema_size option unless it is 185 * 0. The default is reasonable size like 64K depending on config flags. 186 * 187 * Returns 0 on success. 188 */ 189 int flatcc_parse_file(flatcc_context_t ctx, const char *filename); 190 191 /* 192 * Generate output files. The basename derived when the context was 193 * created is used used to name the output files with respective 194 * extensions. If the outpath option is not null it is prefixed the 195 * output files. The `cgen_common_reader, cgen_common_builder, 196 * cgen_reader, and cgen_builder` must be set or reset depending on what 197 * is to be generated. The common files do not require a parse, and the 198 * non-common files require a successfull parse or the result is 199 * undefined. 200 * 201 * Unlinke the parser, the code generator produce errors to stderr 202 * always. These errors are rare, such as using too long namespace 203 * names. 204 * 205 * If the `gen_stdout` option is set, all files are generated to stdout. 206 * In this case it is unwise to mix C and binary schema output options. 207 * 208 * If `bgen_bfbs` is set, a binary schema is generated to a file with 209 * the `.bfbs` extension. See also `flatcc_generate_binary_schema` for 210 * further details. Only `flatcc_generate_files` is called via the 211 * `flatcc` cli command. 212 * 213 * The option `bgen_length_prefix` option will cause a length prefix to be 214 * written to the each output binary schema. This option is only 215 * understood when writing to files. 216 * 217 * Returns 0 on success. 218 */ 219 int flatcc_generate_files(flatcc_context_t ctx); 220 221 /* 222 * Returns a buffer with a binary schema for a previous parse. 223 * The user is responsible for calling `free` on the returned buffer 224 * unless it returns 0 on error. 225 * 226 * Can be called instead of generate files, before, or after, but a 227 * schema must be parsed first. 228 * 229 * Returns a binary schema in `reflection.fbs` format. Any included 230 * files will be contained in the schema and there are no separate 231 * schema files for included schema. 232 * 233 * All type names are scoped, mening that they are refixed their 234 * namespace using `.` as the namespace separator, for example: 235 * "MyGame.Example.Monster". Note that the this differs from the current 236 * `flatc` compiler which does not prefix names. Enum names are not 237 * scoped, but the scope is implied by the containing enum type. 238 * The option `bgen_qualify_names=0` changes this behavior. 239 * 240 * If the default option `ascending_enum` is disabled, the `flatcc` will 241 * accept duplicate values and overlapping ranges like the C programming 242 * language. In this case enum values in the binary schema will not be 243 * searchable. At any rate enum names are not searchable in the current 244 * schema format. 245 * 246 */ 247 void *flatcc_generate_binary_schema(flatcc_context_t ctx, size_t *size); 248 249 /* 250 * Similar to `flatcc_generate_binary_schema` but copies the binary 251 * schema into a user supplied buffer. If the buffer is too small 252 * the return value will be negative and the buffer content undefined. 253 */ 254 int flatcc_generate_binary_schema_to_buffer(flatcc_context_t ctx, void *buf, size_t bufsiz); 255 256 /* Must be called to deallocate resources eventually - it valid but 257 * without effect to call with a null context. */ 258 void flatcc_destroy_context(flatcc_context_t ctx); 259 260 #ifdef _MSC_VER 261 #pragma warning(pop) 262 #endif 263 264 #ifdef __cplusplus 265 } 266 #endif 267 268 #endif /* FLATCC_H */