include/flatbuffers/idl.h

   1 /*
   2  * Copyright 2014 Google Inc. All rights reserved.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef FLATBUFFERS_IDL_H_
  18 #define FLATBUFFERS_IDL_H_
  19
  20 #include <map>
  21 #include <memory>
  22 #include <stack>
  23
  24 #include "flatbuffers/base.h"
  25 #include "flatbuffers/flatbuffers.h"
  26 #include "flatbuffers/flexbuffers.h"
  27 #include "flatbuffers/hash.h"
  28 #include "flatbuffers/reflection.h"
  29
  30 #if !defined(FLATBUFFERS_CPP98_STL)
  31 #  include <functional>
  32 #endif  // !defined(FLATBUFFERS_CPP98_STL)
  33
  34 // This file defines the data types representing a parsed IDL (Interface
  35 // Definition Language) / schema file.
  36
  37 // Limits maximum depth of nested objects.
  38 // Prevents stack overflow while parse flatbuffers or json.
  39 #if !defined(FLATBUFFERS_MAX_PARSING_DEPTH)
  40 #  define FLATBUFFERS_MAX_PARSING_DEPTH 64
  41 #endif
  42
  43 namespace flatbuffers {
  44
  45 // The order of these matters for Is*() functions below.
  46 // Additionally, Parser::ParseType assumes bool..string is a contiguous range
  47 // of type tokens.
  48 // clang-format off
  49 #define FLATBUFFERS_GEN_TYPES_SCALAR(TD) \
  50   TD(NONE,   "",       uint8_t,  byte,   byte,    byte,   uint8,   u8,   UByte) \
  51   TD(UTYPE,  "",       uint8_t,  byte,   byte,    byte,   uint8,   u8,   UByte) /* begin scalar/int */ \
  52   TD(BOOL,   "bool",   uint8_t,  boolean,bool,    bool,   bool,    bool, Boolean) \
  53   TD(CHAR,   "byte",   int8_t,   byte,   int8,    sbyte,  int8,    i8,   Byte) \
  54   TD(UCHAR,  "ubyte",  uint8_t,  byte,   byte,    byte,   uint8,   u8,   UByte) \
  55   TD(SHORT,  "short",  int16_t,  short,  int16,   short,  int16,   i16,  Short) \
  56   TD(USHORT, "ushort", uint16_t, short,  uint16,  ushort, uint16,  u16,  UShort) \
  57   TD(INT,    "int",    int32_t,  int,    int32,   int,    int32,   i32,  Int) \
  58   TD(UINT,   "uint",   uint32_t, int,    uint32,  uint,   uint32,  u32,  UInt) \
  59   TD(LONG,   "long",   int64_t,  long,   int64,   long,   int64,   i64,  Long) \
  60   TD(ULONG,  "ulong",  uint64_t, long,   uint64,  ulong,  uint64,  u64,  ULong) /* end int */ \
  61   TD(FLOAT,  "float",  float,    float,  float32, float,  float32, f32,  Float) /* begin float */ \
  62   TD(DOUBLE, "double", double,   double, float64, double, float64, f64,  Double) /* end float/scalar */
  63 #define FLATBUFFERS_GEN_TYPES_POINTER(TD) \
  64   TD(STRING, "string", Offset<void>, int, int, StringOffset, int, unused, Int) \
  65   TD(VECTOR, "",       Offset<void>, int, int, VectorOffset, int, unused, Int) \
  66   TD(STRUCT, "",       Offset<void>, int, int, int,          int, unused, Int) \
  67   TD(UNION,  "",       Offset<void>, int, int, int,          int, unused, Int)
  68 #define FLATBUFFERS_GEN_TYPE_ARRAY(TD) \
  69   TD(ARRAY,  "",       int,          int, int, int,          int, unused, Int)
  70 // The fields are:
  71 // - enum
  72 // - FlatBuffers schema type.
  73 // - C++ type.
  74 // - Java type.
  75 // - Go type.
  76 // - C# / .Net type.
  77 // - Python type.
  78 // - Rust type.
  79 // - Kotlin type.
  80
  81 // using these macros, we can now write code dealing with types just once, e.g.
  82
  83 /*
  84 switch (type) {
  85   #define FLATBUFFERS_TD(ENUM, IDLTYPE, CTYPE, JTYPE, GTYPE, NTYPE, PTYPE, \
  86                          RTYPE, KTYPE) \
  87     case BASE_TYPE_ ## ENUM: \
  88       // do something specific to CTYPE here
  89     FLATBUFFERS_GEN_TYPES(FLATBUFFERS_TD)
  90   #undef FLATBUFFERS_TD
  91 }
  92 */
  93
  94 // If not all FLATBUFFERS_GEN_() arguments are necessary for implementation
  95 // of FLATBUFFERS_TD, you can use a variadic macro (with __VA_ARGS__ if needed).
  96 // In the above example, only CTYPE is used to generate the code, it can be rewritten:
  97
  98 /*
  99 switch (type) {
 100   #define FLATBUFFERS_TD(ENUM, IDLTYPE, CTYPE, ...) \
 101     case BASE_TYPE_ ## ENUM: \
 102       // do something specific to CTYPE here
 103     FLATBUFFERS_GEN_TYPES(FLATBUFFERS_TD)
 104   #undef FLATBUFFERS_TD
 105 }
 106 */
 107
 108 #define FLATBUFFERS_GEN_TYPES(TD) \
 109         FLATBUFFERS_GEN_TYPES_SCALAR(TD) \
 110         FLATBUFFERS_GEN_TYPES_POINTER(TD) \
 111         FLATBUFFERS_GEN_TYPE_ARRAY(TD)
 112
 113 // Create an enum for all the types above.
 114 #ifdef __GNUC__
 115 __extension__  // Stop GCC complaining about trailing comma with -Wpendantic.
 116 #endif
 117 enum BaseType {
 118   #define FLATBUFFERS_TD(ENUM, ...) \
 119     BASE_TYPE_ ## ENUM,
 120     FLATBUFFERS_GEN_TYPES(FLATBUFFERS_TD)
 121   #undef FLATBUFFERS_TD
 122 };
 123
 124 #define FLATBUFFERS_TD(ENUM, IDLTYPE, CTYPE, ...) \
 125   static_assert(sizeof(CTYPE) <= sizeof(largest_scalar_t), \
 126                 "define largest_scalar_t as " #CTYPE);
 127   FLATBUFFERS_GEN_TYPES(FLATBUFFERS_TD)
 128 #undef FLATBUFFERS_TD
 129
 130 inline bool IsScalar (BaseType t) { return t >= BASE_TYPE_UTYPE &&
 131                                            t <= BASE_TYPE_DOUBLE; }
 132 inline bool IsInteger(BaseType t) { return t >= BASE_TYPE_UTYPE &&
 133                                            t <= BASE_TYPE_ULONG; }
 134 inline bool IsFloat  (BaseType t) { return t == BASE_TYPE_FLOAT ||
 135                                            t == BASE_TYPE_DOUBLE; }
 136 inline bool IsLong   (BaseType t) { return t == BASE_TYPE_LONG ||
 137                                            t == BASE_TYPE_ULONG; }
 138 inline bool IsBool   (BaseType t) { return t == BASE_TYPE_BOOL; }
 139 inline bool IsOneByte(BaseType t) { return t >= BASE_TYPE_UTYPE &&
 140                                            t <= BASE_TYPE_UCHAR; }
 141
 142 inline bool IsUnsigned(BaseType t) {
 143   return (t == BASE_TYPE_UTYPE)  || (t == BASE_TYPE_UCHAR) ||
 144          (t == BASE_TYPE_USHORT) || (t == BASE_TYPE_UINT)  ||
 145          (t == BASE_TYPE_ULONG);
 146 }
 147
 148 // clang-format on
 149
 150 extern const char *const kTypeNames[];
 151 extern const char kTypeSizes[];
 152
 153 inline size_t SizeOf(BaseType t) { return kTypeSizes[t]; }
 154
 155 struct StructDef;
 156 struct EnumDef;
 157 class Parser;
 158
 159 // Represents any type in the IDL, which is a combination of the BaseType
 160 // and additional information for vectors/structs_.
 161 struct Type {
 162   explicit Type(BaseType _base_type = BASE_TYPE_NONE, StructDef *_sd = nullptr,
 163                 EnumDef *_ed = nullptr, uint16_t _fixed_length = 0)
 164       : base_type(_base_type),
 165         element(BASE_TYPE_NONE),
 166         struct_def(_sd),
 167         enum_def(_ed),
 168         fixed_length(_fixed_length) {}
 169
 170   bool operator==(const Type &o) {
 171     return base_type == o.base_type && element == o.element &&
 172            struct_def == o.struct_def && enum_def == o.enum_def;
 173   }
 174
 175   Type VectorType() const {
 176     return Type(element, struct_def, enum_def, fixed_length);
 177   }
 178
 179   Offset<reflection::Type> Serialize(FlatBufferBuilder *builder) const;
 180
 181   bool Deserialize(const Parser &parser, const reflection::Type *type);
 182
 183   BaseType base_type;
 184   BaseType element;       // only set if t == BASE_TYPE_VECTOR
 185   StructDef *struct_def;  // only set if t or element == BASE_TYPE_STRUCT
 186   EnumDef *enum_def;      // set if t == BASE_TYPE_UNION / BASE_TYPE_UTYPE,
 187                           // or for an integral type derived from an enum.
 188   uint16_t fixed_length;  // only set if t == BASE_TYPE_ARRAY
 189 };
 190
 191 // Represents a parsed scalar value, it's type, and field offset.
 192 struct Value {
 193   Value()
 194       : constant("0"),
 195         offset(static_cast<voffset_t>(~(static_cast<voffset_t>(0U)))) {}
 196   Type type;
 197   std::string constant;
 198   voffset_t offset;
 199 };
 200
 201 // Helper class that retains the original order of a set of identifiers and
 202 // also provides quick lookup.
 203 template<typename T> class SymbolTable {
 204  public:
 205   ~SymbolTable() {
 206     for (auto it = vec.begin(); it != vec.end(); ++it) { delete *it; }
 207   }
 208
 209   bool Add(const std::string &name, T *e) {
 210     vector_emplace_back(&vec, e);
 211     auto it = dict.find(name);
 212     if (it != dict.end()) return true;
 213     dict[name] = e;
 214     return false;
 215   }
 216
 217   void Move(const std::string &oldname, const std::string &newname) {
 218     auto it = dict.find(oldname);
 219     if (it != dict.end()) {
 220       auto obj = it->second;
 221       dict.erase(it);
 222       dict[newname] = obj;
 223     } else {
 224       FLATBUFFERS_ASSERT(false);
 225     }
 226   }
 227
 228   T *Lookup(const std::string &name) const {
 229     auto it = dict.find(name);
 230     return it == dict.end() ? nullptr : it->second;
 231   }
 232
 233  public:
 234   std::map<std::string, T *> dict;  // quick lookup
 235   std::vector<T *> vec;             // Used to iterate in order of insertion
 236 };
 237
 238 // A name space, as set in the schema.
 239 struct Namespace {
 240   Namespace() : from_table(0) {}
 241
 242   // Given a (potentally unqualified) name, return the "fully qualified" name
 243   // which has a full namespaced descriptor.
 244   // With max_components you can request less than the number of components
 245   // the current namespace has.
 246   std::string GetFullyQualifiedName(const std::string &name,
 247                                     size_t max_components = 1000) const;
 248
 249   std::vector<std::string> components;
 250   size_t from_table;  // Part of the namespace corresponds to a message/table.
 251 };
 252
 253 inline bool operator<(const Namespace &a, const Namespace &b) {
 254   size_t min_size = std::min(a.components.size(), b.components.size());
 255   for (size_t i = 0; i < min_size; ++i) {
 256     if (a.components[i] != b.components[i])
 257       return a.components[i] < b.components[i];
 258   }
 259   return a.components.size() < b.components.size();
 260 }
 261
 262 // Base class for all definition types (fields, structs_, enums_).
 263 struct Definition {
 264   Definition()
 265       : generated(false),
 266         defined_namespace(nullptr),
 267         serialized_location(0),
 268         index(-1),
 269         refcount(1) {}
 270
 271   flatbuffers::Offset<
 272       flatbuffers::Vector<flatbuffers::Offset<reflection::KeyValue>>>
 273   SerializeAttributes(FlatBufferBuilder *builder, const Parser &parser) const;
 274
 275   bool DeserializeAttributes(Parser &parser,
 276                              const Vector<Offset<reflection::KeyValue>> *attrs);
 277
 278   std::string name;
 279   std::string file;
 280   std::vector<std::string> doc_comment;
 281   SymbolTable<Value> attributes;
 282   bool generated;  // did we already output code for this definition?
 283   Namespace *defined_namespace;  // Where it was defined.
 284
 285   // For use with Serialize()
 286   uoffset_t serialized_location;
 287   int index;  // Inside the vector it is stored.
 288   int refcount;
 289 };
 290
 291 struct FieldDef : public Definition {
 292   FieldDef()
 293       : deprecated(false),
 294         required(false),
 295         key(false),
 296         shared(false),
 297         native_inline(false),
 298         flexbuffer(false),
 299         nested_flatbuffer(NULL),
 300         padding(0) {}
 301
 302   Offset<reflection::Field> Serialize(FlatBufferBuilder *builder, uint16_t id,
 303                                       const Parser &parser) const;
 304
 305   bool Deserialize(Parser &parser, const reflection::Field *field);
 306
 307   Value value;
 308   bool deprecated;  // Field is allowed to be present in old data, but can't be.
 309                     // written in new data nor accessed in new code.
 310   bool required;    // Field must always be present.
 311   bool key;         // Field functions as a key for creating sorted vectors.
 312   bool shared;  // Field will be using string pooling (i.e. CreateSharedString)
 313                 // as default serialization behavior if field is a string.
 314   bool native_inline;  // Field will be defined inline (instead of as a pointer)
 315                        // for native tables if field is a struct.
 316   bool flexbuffer;     // This field contains FlexBuffer data.
 317   StructDef *nested_flatbuffer;  // This field contains nested FlatBuffer data.
 318   size_t padding;                // Bytes to always pad after this field.
 319 };
 320
 321 struct StructDef : public Definition {
 322   StructDef()
 323       : fixed(false),
 324         predecl(true),
 325         sortbysize(true),
 326         has_key(false),
 327         minalign(1),
 328         bytesize(0) {}
 329
 330   void PadLastField(size_t min_align) {
 331     auto padding = PaddingBytes(bytesize, min_align);
 332     bytesize += padding;
 333     if (fields.vec.size()) fields.vec.back()->padding = padding;
 334   }
 335
 336   Offset<reflection::Object> Serialize(FlatBufferBuilder *builder,
 337                                        const Parser &parser) const;
 338
 339   bool Deserialize(Parser &parser, const reflection::Object *object);
 340
 341   SymbolTable<FieldDef> fields;
 342
 343   bool fixed;       // If it's struct, not a table.
 344   bool predecl;     // If it's used before it was defined.
 345   bool sortbysize;  // Whether fields come in the declaration or size order.
 346   bool has_key;     // It has a key field.
 347   size_t minalign;  // What the whole object needs to be aligned to.
 348   size_t bytesize;  // Size if fixed.
 349
 350   flatbuffers::unique_ptr<std::string> original_location;
 351 };
 352
 353 struct EnumDef;
 354 struct EnumValBuilder;
 355
 356 struct EnumVal {
 357   Offset<reflection::EnumVal> Serialize(FlatBufferBuilder *builder,
 358                                         const Parser &parser) const;
 359
 360   bool Deserialize(const Parser &parser, const reflection::EnumVal *val);
 361
 362   uint64_t GetAsUInt64() const { return static_cast<uint64_t>(value); }
 363   int64_t GetAsInt64() const { return value; }
 364   bool IsZero() const { return 0 == value; }
 365   bool IsNonZero() const { return !IsZero(); }
 366
 367   std::string name;
 368   std::vector<std::string> doc_comment;
 369   Type union_type;
 370
 371  private:
 372   friend EnumDef;
 373   friend EnumValBuilder;
 374   friend bool operator==(const EnumVal &lhs, const EnumVal &rhs);
 375
 376   EnumVal(const std::string &_name, int64_t _val) : name(_name), value(_val) {}
 377   EnumVal() : value(0) {}
 378
 379   int64_t value;
 380 };
 381
 382 struct EnumDef : public Definition {
 383   EnumDef() : is_union(false), uses_multiple_type_instances(false) {}
 384
 385   Offset<reflection::Enum> Serialize(FlatBufferBuilder *builder,
 386                                      const Parser &parser) const;
 387
 388   bool Deserialize(Parser &parser, const reflection::Enum *values);
 389
 390   template<typename T> void ChangeEnumValue(EnumVal *ev, T new_val);
 391   void SortByValue();
 392   void RemoveDuplicates();
 393
 394   std::string AllFlags() const;
 395   const EnumVal *MinValue() const;
 396   const EnumVal *MaxValue() const;
 397   // Returns the number of integer steps from v1 to v2.
 398   uint64_t Distance(const EnumVal *v1, const EnumVal *v2) const;
 399   // Returns the number of integer steps from Min to Max.
 400   uint64_t Distance() const { return Distance(MinValue(), MaxValue()); }
 401
 402   EnumVal *ReverseLookup(int64_t enum_idx,
 403                          bool skip_union_default = false) const;
 404   EnumVal *FindByValue(const std::string &constant) const;
 405
 406   std::string ToString(const EnumVal &ev) const {
 407     return IsUInt64() ? NumToString(ev.GetAsUInt64())
 408                       : NumToString(ev.GetAsInt64());
 409   }
 410
 411   size_t size() const { return vals.vec.size(); }
 412
 413   const std::vector<EnumVal *> &Vals() const {
 414     FLATBUFFERS_ASSERT(false == vals.vec.empty());
 415     return vals.vec;
 416   }
 417
 418   const EnumVal *Lookup(const std::string &enum_name) const {
 419     return vals.Lookup(enum_name);
 420   }
 421
 422   bool is_union;
 423   // Type is a union which uses type aliases where at least one type is
 424   // available under two different names.
 425   bool uses_multiple_type_instances;
 426   Type underlying_type;
 427
 428  private:
 429   bool IsUInt64() const {
 430     return (BASE_TYPE_ULONG == underlying_type.base_type);
 431   }
 432
 433   friend EnumValBuilder;
 434   SymbolTable<EnumVal> vals;
 435 };
 436
 437 inline bool IsStruct(const Type &type) {
 438   return type.base_type == BASE_TYPE_STRUCT && type.struct_def->fixed;
 439 }
 440
 441 inline bool IsUnion(const Type &type) {
 442   return type.enum_def != nullptr && type.enum_def->is_union;
 443 }
 444
 445 inline bool IsVector(const Type &type) {
 446   return type.base_type == BASE_TYPE_VECTOR;
 447 }
 448
 449 inline bool IsArray(const Type &type) {
 450   return type.base_type == BASE_TYPE_ARRAY;
 451 }
 452
 453 inline bool IsSeries(const Type &type) {
 454   return IsVector(type) || IsArray(type);
 455 }
 456
 457 inline bool IsEnum(const Type &type) {
 458   return type.enum_def != nullptr && IsInteger(type.base_type);
 459 }
 460
 461 inline size_t InlineSize(const Type &type) {
 462   return IsStruct(type)
 463              ? type.struct_def->bytesize
 464              : (IsArray(type)
 465                     ? InlineSize(type.VectorType()) * type.fixed_length
 466                     : SizeOf(type.base_type));
 467 }
 468
 469 inline size_t InlineAlignment(const Type &type) {
 470   if (IsStruct(type)) {
 471     return type.struct_def->minalign;
 472   } else if (IsArray(type)) {
 473     return IsStruct(type.VectorType()) ? type.struct_def->minalign
 474                                        : SizeOf(type.element);
 475   } else {
 476     return SizeOf(type.base_type);
 477   }
 478 }
 479 inline bool operator==(const EnumVal &lhs, const EnumVal &rhs) {
 480   return lhs.value == rhs.value;
 481 }
 482 inline bool operator!=(const EnumVal &lhs, const EnumVal &rhs) {
 483   return !(lhs == rhs);
 484 }
 485
 486 inline bool EqualByName(const Type &a, const Type &b) {
 487   return a.base_type == b.base_type && a.element == b.element &&
 488          (a.struct_def == b.struct_def ||
 489           a.struct_def->name == b.struct_def->name) &&
 490          (a.enum_def == b.enum_def || a.enum_def->name == b.enum_def->name);
 491 }
 492
 493 struct RPCCall : public Definition {
 494   Offset<reflection::RPCCall> Serialize(FlatBufferBuilder *builder,
 495                                         const Parser &parser) const;
 496
 497   bool Deserialize(Parser &parser, const reflection::RPCCall *call);
 498
 499   StructDef *request, *response;
 500 };
 501
 502 struct ServiceDef : public Definition {
 503   Offset<reflection::Service> Serialize(FlatBufferBuilder *builder,
 504                                         const Parser &parser) const;
 505   bool Deserialize(Parser &parser, const reflection::Service *service);
 506
 507   SymbolTable<RPCCall> calls;
 508 };
 509
 510 // Container of options that may apply to any of the source/text generators.
 511 struct IDLOptions {
 512   // Use flexbuffers instead for binary and text generation
 513   bool use_flexbuffers;
 514   bool strict_json;
 515   bool skip_js_exports;
 516   bool use_goog_js_export_format;
 517   bool use_ES6_js_export_format;
 518   bool output_default_scalars_in_json;
 519   int indent_step;
 520   bool output_enum_identifiers;
 521   bool prefixed_enums;
 522   bool scoped_enums;
 523   bool include_dependence_headers;
 524   bool mutable_buffer;
 525   bool one_file;
 526   bool proto_mode;
 527   bool proto_oneof_union;
 528   bool generate_all;
 529   bool skip_unexpected_fields_in_json;
 530   bool generate_name_strings;
 531   bool generate_object_based_api;
 532   bool gen_compare;
 533   std::string cpp_object_api_pointer_type;
 534   std::string cpp_object_api_string_type;
 535   bool cpp_object_api_string_flexible_constructor;
 536   bool gen_nullable;
 537   bool java_checkerframework;
 538   bool gen_generated;
 539   std::string object_prefix;
 540   std::string object_suffix;
 541   bool union_value_namespacing;
 542   bool allow_non_utf8;
 543   bool natural_utf8;
 544   std::string include_prefix;
 545   bool keep_include_path;
 546   bool binary_schema_comments;
 547   bool binary_schema_builtins;
 548   bool skip_flatbuffers_import;
 549   std::string go_import;
 550   std::string go_namespace;
 551   bool reexport_ts_modules;
 552   bool js_ts_short_names;
 553   bool protobuf_ascii_alike;
 554   bool size_prefixed;
 555   std::string root_type;
 556   bool force_defaults;
 557   bool java_primitive_has_method;
 558   std::vector<std::string> cpp_includes;
 559   std::string cpp_std;
 560   std::string proto_namespace_suffix;
 561
 562   // Possible options for the more general generator below.
 563   enum Language {
 564     kJava = 1 << 0,
 565     kCSharp = 1 << 1,
 566     kGo = 1 << 2,
 567     kCpp = 1 << 3,
 568     kJs = 1 << 4,
 569     kPython = 1 << 5,
 570     kPhp = 1 << 6,
 571     kJson = 1 << 7,
 572     kBinary = 1 << 8,
 573     kTs = 1 << 9,
 574     kJsonSchema = 1 << 10,
 575     kDart = 1 << 11,
 576     kLua = 1 << 12,
 577     kLobster = 1 << 13,
 578     kRust = 1 << 14,
 579     kKotlin = 1 << 15,
 580     kMAX
 581   };
 582
 583   Language lang;
 584
 585   enum MiniReflect { kNone, kTypes, kTypesAndNames };
 586
 587   MiniReflect mini_reflect;
 588
 589   // The corresponding language bit will be set if a language is included
 590   // for code generation.
 591   unsigned long lang_to_generate;
 592
 593   // If set (default behavior), empty string fields will be set to nullptr to make
 594   // the flatbuffer more compact.
 595   bool set_empty_strings_to_null;
 596
 597   // If set (default behavior), empty vector fields will be set to nullptr to make
 598   // the flatbuffer more compact.
 599   bool set_empty_vectors_to_null;
 600
 601   IDLOptions()
 602       : use_flexbuffers(false),
 603         strict_json(false),
 604         skip_js_exports(false),
 605         use_goog_js_export_format(false),
 606         use_ES6_js_export_format(false),
 607         output_default_scalars_in_json(false),
 608         indent_step(2),
 609         output_enum_identifiers(true),
 610         prefixed_enums(true),
 611         scoped_enums(false),
 612         include_dependence_headers(true),
 613         mutable_buffer(false),
 614         one_file(false),
 615         proto_mode(false),
 616         proto_oneof_union(false),
 617         generate_all(false),
 618         skip_unexpected_fields_in_json(false),
 619         generate_name_strings(false),
 620         generate_object_based_api(false),
 621         gen_compare(false),
 622         cpp_object_api_pointer_type("std::unique_ptr"),
 623         cpp_object_api_string_flexible_constructor(false),
 624         gen_nullable(false),
 625         java_checkerframework(false),
 626         gen_generated(false),
 627         object_suffix("T"),
 628         union_value_namespacing(true),
 629         allow_non_utf8(false),
 630         natural_utf8(false),
 631         keep_include_path(false),
 632         binary_schema_comments(false),
 633         binary_schema_builtins(false),
 634         skip_flatbuffers_import(false),
 635         reexport_ts_modules(true),
 636         js_ts_short_names(false),
 637         protobuf_ascii_alike(false),
 638         size_prefixed(false),
 639         force_defaults(false),
 640         java_primitive_has_method(false),
 641         lang(IDLOptions::kJava),
 642         mini_reflect(IDLOptions::kNone),
 643         lang_to_generate(0),
 644         set_empty_strings_to_null(true),
 645         set_empty_vectors_to_null(true) {}
 646 };
 647
 648 // This encapsulates where the parser is in the current source file.
 649 struct ParserState {
 650   ParserState()
 651       : cursor_(nullptr),
 652         line_start_(nullptr),
 653         line_(0),
 654         token_(-1),
 655         attr_is_trivial_ascii_string_(true) {}
 656
 657  protected:
 658   void ResetState(const char *source) {
 659     cursor_ = source;
 660     line_ = 0;
 661     MarkNewLine();
 662   }
 663
 664   void MarkNewLine() {
 665     line_start_ = cursor_;
 666     line_ += 1;
 667   }
 668
 669   int64_t CursorPosition() const {
 670     FLATBUFFERS_ASSERT(cursor_ && line_start_ && cursor_ >= line_start_);
 671     return static_cast<int64_t>(cursor_ - line_start_);
 672   }
 673
 674   const char *cursor_;
 675   const char *line_start_;
 676   int line_;  // the current line being parsed
 677   int token_;
 678
 679   // Flag: text in attribute_ is true ASCII string without escape
 680   // sequences. Only printable ASCII (without [\t\r\n]).
 681   // Used for number-in-string (and base64 string in future).
 682   bool attr_is_trivial_ascii_string_;
 683   std::string attribute_;
 684   std::vector<std::string> doc_comment_;
 685 };
 686
 687 // A way to make error propagation less error prone by requiring values to be
 688 // checked.
 689 // Once you create a value of this type you must either:
 690 // - Call Check() on it.
 691 // - Copy or assign it to another value.
 692 // Failure to do so leads to an assert.
 693 // This guarantees that this as return value cannot be ignored.
 694 class CheckedError {
 695  public:
 696   explicit CheckedError(bool error)
 697       : is_error_(error), has_been_checked_(false) {}
 698
 699   CheckedError &operator=(const CheckedError &other) {
 700     is_error_ = other.is_error_;
 701     has_been_checked_ = false;
 702     other.has_been_checked_ = true;
 703     return *this;
 704   }
 705
 706   CheckedError(const CheckedError &other) {
 707     *this = other;  // Use assignment operator.
 708   }
 709
 710   ~CheckedError() { FLATBUFFERS_ASSERT(has_been_checked_); }
 711
 712   bool Check() {
 713     has_been_checked_ = true;
 714     return is_error_;
 715   }
 716
 717  private:
 718   bool is_error_;
 719   mutable bool has_been_checked_;
 720 };
 721
 722 // Additionally, in GCC we can get these errors statically, for additional
 723 // assurance:
 724 // clang-format off
 725 #ifdef __GNUC__
 726 #define FLATBUFFERS_CHECKED_ERROR CheckedError \
 727           __attribute__((warn_unused_result))
 728 #else
 729 #define FLATBUFFERS_CHECKED_ERROR CheckedError
 730 #endif
 731 // clang-format on
 732
 733 class Parser : public ParserState {
 734  public:
 735   explicit Parser(const IDLOptions &options = IDLOptions())
 736       : current_namespace_(nullptr),
 737         empty_namespace_(nullptr),
 738         flex_builder_(256, flexbuffers::BUILDER_FLAG_SHARE_ALL),
 739         root_struct_def_(nullptr),
 740         opts(options),
 741         uses_flexbuffers_(false),
 742         source_(nullptr),
 743         anonymous_counter(0),
 744         recurse_protection_counter(0) {
 745     if (opts.force_defaults) { builder_.ForceDefaults(true); }
 746     // Start out with the empty namespace being current.
 747     empty_namespace_ = new Namespace();
 748     namespaces_.push_back(empty_namespace_);
 749     current_namespace_ = empty_namespace_;
 750     known_attributes_["deprecated"] = true;
 751     known_attributes_["required"] = true;
 752     known_attributes_["key"] = true;
 753     known_attributes_["shared"] = true;
 754     known_attributes_["hash"] = true;
 755     known_attributes_["id"] = true;
 756     known_attributes_["force_align"] = true;
 757     known_attributes_["bit_flags"] = true;
 758     known_attributes_["original_order"] = true;
 759     known_attributes_["nested_flatbuffer"] = true;
 760     known_attributes_["csharp_partial"] = true;
 761     known_attributes_["streaming"] = true;
 762     known_attributes_["idempotent"] = true;
 763     known_attributes_["cpp_type"] = true;
 764     known_attributes_["cpp_ptr_type"] = true;
 765     known_attributes_["cpp_ptr_type_get"] = true;
 766     known_attributes_["cpp_str_type"] = true;
 767     known_attributes_["cpp_str_flex_ctor"] = true;
 768     known_attributes_["native_inline"] = true;
 769     known_attributes_["native_custom_alloc"] = true;
 770     known_attributes_["native_type"] = true;
 771     known_attributes_["native_default"] = true;
 772     known_attributes_["flexbuffer"] = true;
 773     known_attributes_["private"] = true;
 774   }
 775
 776   ~Parser() {
 777     for (auto it = namespaces_.begin(); it != namespaces_.end(); ++it) {
 778       delete *it;
 779     }
 780   }
 781
 782   // Parse the string containing either schema or JSON data, which will
 783   // populate the SymbolTable's or the FlatBufferBuilder above.
 784   // include_paths is used to resolve any include statements, and typically
 785   // should at least include the project path (where you loaded source_ from).
 786   // include_paths must be nullptr terminated if specified.
 787   // If include_paths is nullptr, it will attempt to load from the current
 788   // directory.
 789   // If the source was loaded from a file and isn't an include file,
 790   // supply its name in source_filename.
 791   // All paths specified in this call must be in posix format, if you accept
 792   // paths from user input, please call PosixPath on them first.
 793   bool Parse(const char *_source, const char **include_paths = nullptr,
 794              const char *source_filename = nullptr);
 795
 796   // Set the root type. May override the one set in the schema.
 797   bool SetRootType(const char *name);
 798
 799   // Mark all definitions as already having code generated.
 800   void MarkGenerated();
 801
 802   // Get the files recursively included by the given file. The returned
 803   // container will have at least the given file.
 804   std::set<std::string> GetIncludedFilesRecursive(
 805       const std::string &file_name) const;
 806
 807   // Fills builder_ with a binary version of the schema parsed.
 808   // See reflection/reflection.fbs
 809   void Serialize();
 810
 811   // Deserialize a schema buffer
 812   bool Deserialize(const uint8_t *buf, const size_t size);
 813
 814   // Fills internal structure as if the schema passed had been loaded by parsing
 815   // with Parse except that included filenames will not be populated.
 816   bool Deserialize(const reflection::Schema *schema);
 817
 818   Type *DeserializeType(const reflection::Type *type);
 819
 820   // Checks that the schema represented by this parser is a safe evolution
 821   // of the schema provided. Returns non-empty error on any problems.
 822   std::string ConformTo(const Parser &base);
 823
 824   // Similar to Parse(), but now only accepts JSON to be parsed into a
 825   // FlexBuffer.
 826   bool ParseFlexBuffer(const char *source, const char *source_filename,
 827                        flexbuffers::Builder *builder);
 828
 829   StructDef *LookupStruct(const std::string &id) const;
 830
 831   std::string UnqualifiedName(const std::string &fullQualifiedName);
 832
 833   FLATBUFFERS_CHECKED_ERROR Error(const std::string &msg);
 834
 835  private:
 836   void Message(const std::string &msg);
 837   void Warning(const std::string &msg);
 838   FLATBUFFERS_CHECKED_ERROR ParseHexNum(int nibbles, uint64_t *val);
 839   FLATBUFFERS_CHECKED_ERROR Next();
 840   FLATBUFFERS_CHECKED_ERROR SkipByteOrderMark();
 841   bool Is(int t) const;
 842   bool IsIdent(const char *id) const;
 843   FLATBUFFERS_CHECKED_ERROR Expect(int t);
 844   std::string TokenToStringId(int t) const;
 845   EnumDef *LookupEnum(const std::string &id);
 846   FLATBUFFERS_CHECKED_ERROR ParseNamespacing(std::string *id,
 847                                              std::string *last);
 848   FLATBUFFERS_CHECKED_ERROR ParseTypeIdent(Type &type);
 849   FLATBUFFERS_CHECKED_ERROR ParseType(Type &type);
 850   FLATBUFFERS_CHECKED_ERROR AddField(StructDef &struct_def,
 851                                      const std::string &name, const Type &type,
 852                                      FieldDef **dest);
 853   FLATBUFFERS_CHECKED_ERROR ParseField(StructDef &struct_def);
 854   FLATBUFFERS_CHECKED_ERROR ParseString(Value &val);
 855   FLATBUFFERS_CHECKED_ERROR ParseComma();
 856   FLATBUFFERS_CHECKED_ERROR ParseAnyValue(Value &val, FieldDef *field,
 857                                           size_t parent_fieldn,
 858                                           const StructDef *parent_struct_def,
 859                                           uoffset_t count,
 860                                           bool inside_vector = false);
 861   template<typename F>
 862   FLATBUFFERS_CHECKED_ERROR ParseTableDelimiters(size_t &fieldn,
 863                                                  const StructDef *struct_def,
 864                                                  F body);
 865   FLATBUFFERS_CHECKED_ERROR ParseTable(const StructDef &struct_def,
 866                                        std::string *value, uoffset_t *ovalue);
 867   void SerializeStruct(const StructDef &struct_def, const Value &val);
 868   void SerializeStruct(FlatBufferBuilder &builder, const StructDef &struct_def,
 869                        const Value &val);
 870   template<typename F>
 871   FLATBUFFERS_CHECKED_ERROR ParseVectorDelimiters(uoffset_t &count, F body);
 872   FLATBUFFERS_CHECKED_ERROR ParseVector(const Type &type, uoffset_t *ovalue,
 873                                         FieldDef *field, size_t fieldn);
 874   FLATBUFFERS_CHECKED_ERROR ParseArray(Value &array);
 875   FLATBUFFERS_CHECKED_ERROR ParseNestedFlatbuffer(
 876       Value &val, FieldDef *field, size_t fieldn,
 877       const StructDef *parent_struct_def);
 878   FLATBUFFERS_CHECKED_ERROR ParseMetaData(SymbolTable<Value> *attributes);
 879   FLATBUFFERS_CHECKED_ERROR TryTypedValue(const std::string *name, int dtoken,
 880                                           bool check, Value &e, BaseType req,
 881                                           bool *destmatch);
 882   FLATBUFFERS_CHECKED_ERROR ParseHash(Value &e, FieldDef *field);
 883   FLATBUFFERS_CHECKED_ERROR TokenError();
 884   FLATBUFFERS_CHECKED_ERROR ParseSingleValue(const std::string *name, Value &e,
 885                                              bool check_now);
 886   FLATBUFFERS_CHECKED_ERROR ParseEnumFromString(const Type &type,
 887                                                 std::string *result);
 888   StructDef *LookupCreateStruct(const std::string &name,
 889                                 bool create_if_new = true,
 890                                 bool definition = false);
 891   FLATBUFFERS_CHECKED_ERROR ParseEnum(bool is_union, EnumDef **dest);
 892   FLATBUFFERS_CHECKED_ERROR ParseNamespace();
 893   FLATBUFFERS_CHECKED_ERROR StartStruct(const std::string &name,
 894                                         StructDef **dest);
 895   FLATBUFFERS_CHECKED_ERROR StartEnum(const std::string &name, bool is_union,
 896                                       EnumDef **dest);
 897   FLATBUFFERS_CHECKED_ERROR ParseDecl();
 898   FLATBUFFERS_CHECKED_ERROR ParseService();
 899   FLATBUFFERS_CHECKED_ERROR ParseProtoFields(StructDef *struct_def,
 900                                              bool isextend, bool inside_oneof);
 901   FLATBUFFERS_CHECKED_ERROR ParseProtoOption();
 902   FLATBUFFERS_CHECKED_ERROR ParseProtoKey();
 903   FLATBUFFERS_CHECKED_ERROR ParseProtoDecl();
 904   FLATBUFFERS_CHECKED_ERROR ParseProtoCurliesOrIdent();
 905   FLATBUFFERS_CHECKED_ERROR ParseTypeFromProtoType(Type *type);
 906   FLATBUFFERS_CHECKED_ERROR SkipAnyJsonValue();
 907   FLATBUFFERS_CHECKED_ERROR ParseFlexBufferValue(flexbuffers::Builder *builder);
 908   FLATBUFFERS_CHECKED_ERROR StartParseFile(const char *source,
 909                                            const char *source_filename);
 910   FLATBUFFERS_CHECKED_ERROR ParseRoot(const char *_source,
 911                                       const char **include_paths,
 912                                       const char *source_filename);
 913   FLATBUFFERS_CHECKED_ERROR DoParse(const char *_source,
 914                                     const char **include_paths,
 915                                     const char *source_filename,
 916                                     const char *include_filename);
 917   FLATBUFFERS_CHECKED_ERROR CheckClash(std::vector<FieldDef *> &fields,
 918                                        StructDef *struct_def,
 919                                        const char *suffix, BaseType baseType);
 920
 921   bool SupportsAdvancedUnionFeatures() const;
 922   bool SupportsAdvancedArrayFeatures() const;
 923   Namespace *UniqueNamespace(Namespace *ns);
 924
 925   FLATBUFFERS_CHECKED_ERROR RecurseError();
 926   template<typename F> CheckedError Recurse(F f);
 927
 928  public:
 929   SymbolTable<Type> types_;
 930   SymbolTable<StructDef> structs_;
 931   SymbolTable<EnumDef> enums_;
 932   SymbolTable<ServiceDef> services_;
 933   std::vector<Namespace *> namespaces_;
 934   Namespace *current_namespace_;
 935   Namespace *empty_namespace_;
 936   std::string error_;  // User readable error_ if Parse() == false
 937
 938   FlatBufferBuilder builder_;  // any data contained in the file
 939   flexbuffers::Builder flex_builder_;
 940   flexbuffers::Reference flex_root_;
 941   StructDef *root_struct_def_;
 942   std::string file_identifier_;
 943   std::string file_extension_;
 944
 945   std::map<std::string, std::string> included_files_;
 946   std::map<std::string, std::set<std::string>> files_included_per_file_;
 947   std::vector<std::string> native_included_files_;
 948
 949   std::map<std::string, bool> known_attributes_;
 950
 951   IDLOptions opts;
 952   bool uses_flexbuffers_;
 953
 954  private:
 955   const char *source_;
 956
 957   std::string file_being_parsed_;
 958
 959   std::vector<std::pair<Value, FieldDef *>> field_stack_;
 960
 961   int anonymous_counter;
 962   int recurse_protection_counter;
 963 };
 964
 965 // Utility functions for multiple generators:
 966
 967 extern std::string MakeCamel(const std::string &in, bool first = true);
 968
 969 extern std::string MakeScreamingCamel(const std::string &in);
 970
 971 // Generate text (JSON) from a given FlatBuffer, and a given Parser
 972 // object that has been populated with the corresponding schema.
 973 // If ident_step is 0, no indentation will be generated. Additionally,
 974 // if it is less than 0, no linefeeds will be generated either.
 975 // See idl_gen_text.cpp.
 976 // strict_json adds "quotes" around field names if true.
 977 // If the flatbuffer cannot be encoded in JSON (e.g., it contains non-UTF-8
 978 // byte arrays in String values), returns false.
 979 extern bool GenerateTextFromTable(const Parser &parser, const void *table,
 980                                   const std::string &tablename,
 981                                   std::string *text);
 982 extern bool GenerateText(const Parser &parser, const void *flatbuffer,
 983                          std::string *text);
 984 extern bool GenerateTextFile(const Parser &parser, const std::string &path,
 985                              const std::string &file_name);
 986
 987 // Generate binary files from a given FlatBuffer, and a given Parser
 988 // object that has been populated with the corresponding schema.
 989 // See code_generators.cpp.
 990 extern bool GenerateBinary(const Parser &parser, const std::string &path,
 991                            const std::string &file_name);
 992
 993 // Generate a C++ header from the definitions in the Parser object.
 994 // See idl_gen_cpp.
 995 extern bool GenerateCPP(const Parser &parser, const std::string &path,
 996                         const std::string &file_name);
 997
 998 // Generate C# files from the definitions in the Parser object.
 999 // See idl_gen_csharp.cpp.
1000 extern bool GenerateCSharp(const Parser &parser, const std::string &path,
1001                            const std::string &file_name);
1002
1003 extern bool GenerateDart(const Parser &parser, const std::string &path,
1004                          const std::string &file_name);
1005
1006 // Generate Java files from the definitions in the Parser object.
1007 // See idl_gen_java.cpp.
1008 extern bool GenerateJava(const Parser &parser, const std::string &path,
1009                          const std::string &file_name);
1010
1011 // Generate JavaScript or TypeScript code from the definitions in the Parser
1012 // object. See idl_gen_js.
1013 extern bool GenerateJSTS(const Parser &parser, const std::string &path,
1014                          const std::string &file_name);
1015
1016 // Generate Go files from the definitions in the Parser object.
1017 // See idl_gen_go.cpp.
1018 extern bool GenerateGo(const Parser &parser, const std::string &path,
1019                        const std::string &file_name);
1020
1021 // Generate Php code from the definitions in the Parser object.
1022 // See idl_gen_php.
1023 extern bool GeneratePhp(const Parser &parser, const std::string &path,
1024                         const std::string &file_name);
1025
1026 // Generate Python files from the definitions in the Parser object.
1027 // See idl_gen_python.cpp.
1028 extern bool GeneratePython(const Parser &parser, const std::string &path,
1029                            const std::string &file_name);
1030
1031 // Generate Lobster files from the definitions in the Parser object.
1032 // See idl_gen_lobster.cpp.
1033 extern bool GenerateLobster(const Parser &parser, const std::string &path,
1034                             const std::string &file_name);
1035
1036 // Generate Lua files from the definitions in the Parser object.
1037 // See idl_gen_lua.cpp.
1038 extern bool GenerateLua(const Parser &parser, const std::string &path,
1039                         const std::string &file_name);
1040
1041 // Generate Rust files from the definitions in the Parser object.
1042 // See idl_gen_rust.cpp.
1043 extern bool GenerateRust(const Parser &parser, const std::string &path,
1044                          const std::string &file_name);
1045
1046 // Generate Json schema file
1047 // See idl_gen_json_schema.cpp.
1048 extern bool GenerateJsonSchema(const Parser &parser, const std::string &path,
1049                                const std::string &file_name);
1050
1051 extern bool GenerateKotlin(const Parser &parser, const std::string &path,
1052                            const std::string &file_name);
1053
1054 // Generate a schema file from the internal representation, useful after
1055 // parsing a .proto schema.
1056 extern std::string GenerateFBS(const Parser &parser,
1057                                const std::string &file_name);
1058 extern bool GenerateFBS(const Parser &parser, const std::string &path,
1059                         const std::string &file_name);
1060
1061 // Generate a make rule for the generated JavaScript or TypeScript code.
1062 // See idl_gen_js.cpp.
1063 extern std::string JSTSMakeRule(const Parser &parser, const std::string &path,
1064                                 const std::string &file_name);
1065
1066 // Generate a make rule for the generated C++ header.
1067 // See idl_gen_cpp.cpp.
1068 extern std::string CPPMakeRule(const Parser &parser, const std::string &path,
1069                                const std::string &file_name);
1070
1071 // Generate a make rule for the generated Dart code
1072 // see idl_gen_dart.cpp
1073 extern std::string DartMakeRule(const Parser &parser, const std::string &path,
1074                                 const std::string &file_name);
1075
1076 // Generate a make rule for the generated Rust code.
1077 // See idl_gen_rust.cpp.
1078 extern std::string RustMakeRule(const Parser &parser, const std::string &path,
1079                                 const std::string &file_name);
1080
1081 // Generate a make rule for generated Java or C# files.
1082 // See code_generators.cpp.
1083 extern std::string JavaCSharpMakeRule(const Parser &parser,
1084                                       const std::string &path,
1085                                       const std::string &file_name);
1086
1087 // Generate a make rule for the generated text (JSON) files.
1088 // See idl_gen_text.cpp.
1089 extern std::string TextMakeRule(const Parser &parser, const std::string &path,
1090                                 const std::string &file_names);
1091
1092 // Generate a make rule for the generated binary files.
1093 // See code_generators.cpp.
1094 extern std::string BinaryMakeRule(const Parser &parser, const std::string &path,
1095                                   const std::string &file_name);
1096
1097 // Generate GRPC Cpp interfaces.
1098 // See idl_gen_grpc.cpp.
1099 bool GenerateCppGRPC(const Parser &parser, const std::string &path,
1100                      const std::string &file_name);
1101
1102 // Generate GRPC Go interfaces.
1103 // See idl_gen_grpc.cpp.
1104 bool GenerateGoGRPC(const Parser &parser, const std::string &path,
1105                     const std::string &file_name);
1106
1107 // Generate GRPC Java classes.
1108 // See idl_gen_grpc.cpp
1109 bool GenerateJavaGRPC(const Parser &parser, const std::string &path,
1110                       const std::string &file_name);
1111
1112 // Generate GRPC Python interfaces.
1113 // See idl_gen_grpc.cpp.
1114 bool GeneratePythonGRPC(const Parser &parser,
1115                     const std::string &path,
1116                     const std::string &file_name);
1117
1118 }  // namespace flatbuffers
1119
1120 #endif  // FLATBUFFERS_IDL_H_