Debian Codegraph @

ogr/ogrsf_frmts/flatgeobuf/flatbuffers/idl.h

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