Unlike C++, Go does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the Vec3 is an inline component of Monster, it has to be created right where it is added, whereas the name and the inventory are not inline). Structs do have convenient methods that allow you to construct them in one call. These also have arguments for nested structs, e.g. if a struct has a field a and a nested struct field b (which has fields c and d), then the arguments will be a, c and d.
Unlike C++, Go does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the Vec3 is an inline component of Monster, it has to be created right where it is added, whereas the name and the inventory are not inline, and must be created outside of the table creation sequence). Structs do have convenient methods that allow you to construct them in one call. These also have arguments for nested structs, e.g. if a struct has a field a and a nested struct field b (which has fields c and d), then the arguments will be a, c and d.
Vectors also use this start/end pattern to allow vectors of both scalar types and structs:
The generated method 'StartInventoryVector' is provided as a convenience function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front.
+The generated method 'StartInventoryVector' is provided as a convenience function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front. You then pass inv to the corresponding Add call when you construct the table containing it afterwards.
There are Prepend functions for all the scalar types. You use PrependUOffset for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate create function in-line, as shown above in the Monster example.
Once you're done constructing a buffer, you call Finish with the root object offset (mon in the example above). Your data now resides in Builder.Bytes. Important to note is that the real data starts at the index indicated by Head(), for Offset() bytes (this is because the buffer is constructed backwards). If you wanted to read the buffer right after creating it (using GetRootAsMonster above), the second argument, instead of 0 would thus also be Head().
There currently is no support for parsing text (Schema's and JSON) directly from Go, though you could use the C++ parser through cgo. Please see the C++ documentation for more on text parsing.
diff --git a/docs/html/md__java_usage.html b/docs/html/md__java_usage.html index 161d0378a..9e3f2a620 100644 --- a/docs/html/md__java_usage.html +++ b/docs/html/md__java_usage.html @@ -94,7 +94,7 @@ $(document).ready(function(){initNavTree('md__java_usage.html','');});You can use the generated method startInventoryVector to conveniently call startVector with the right element size. You pass the number of elements you want to write. Note how you write the elements backwards since the buffer is being constructed back to front.
You can use the generated method startInventoryVector to conveniently call startVector with the right element size. You pass the number of elements you want to write. Note how you write the elements backwards since the buffer is being constructed back to front. You then pass inv to the corresponding Add call when you construct the table containing it afterwards.
There are add functions for all the scalar types. You use addOffset for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate create function in-line, as shown above in the Monster example.
To finish the buffer, call:
These will generate the corresponding namespace in C++ for all helper code, and packages in Java. You can use . to specify nested namespaces / packages.
You can include other schemas files in your current one, e.g.:
include "mydefinitions.fbs" +You can include other schemas files in your current one, e.g.:
include "mydefinitions.fbs";This makes it easier to refer to types defined elsewhere.
includeautomatically ensures each file is parsed just once, even when referred to more than once.When using the
flatccompiler to generate code for schema definitions, only definitions in the current file will be generated, not those from the included files (those you still generate separately).Root type
@@ -128,7 +128,7 @@ root_type Monster;
May be written as in most C-based languages. Additionally, a triple comment (///) on a line by itself signals that a comment is documentation for whatever is declared on the line after it (table/struct/field/enum/union/element), and the comment is output in the corresponding C++ code. Multiple such lines per item are allowed.
Attributes may be attached to a declaration, behind a field, or after the name of a table/struct/enum/union. These may either have a value or not. Some attributes like deprecated are understood by the compiler, others are simply ignored (like priority), but are available to query if you parse the schema at runtime. This is useful if you write your own code generators/editors etc., and you wish to add additional information specific to your tool (such as a help text).
Attributes may be attached to a declaration, behind a field, or after the name of a table/struct/enum/union. These may either have a value or not. Some attributes like deprecated are understood by the compiler, others are simply ignored (like priority in the example above), but are available to query if you parse the schema at runtime. This is useful if you write your own code generators/editors etc., and you wish to add additional information specific to your tool (such as a help text).
Current understood attributes:
id: n (on a table field): manually set the field identifier to n. If you use this attribute, you must use it on ALL fields of this table, and the numbers must be a contiguous range from 0 onwards. Additionally, since a union type effectively adds two fields, its id must be that of the second field (the first field is the type field and not explicitly declared in the schema). For example, if the last field before the union field had id 6, the union field should have id 8, and the unions type field will implicitly be 7. IDs allow the fields to be placed in any order in the schema. When a new field is added to the schema is must use the next available ID.original_order (on a table): since elements in a table do not need to be stored in any particular order, they are often optimized for space by sorting them to size. This attribute stops that from happening.force_align: size (on a struct): force the alignment of this struct to be something higher than what it is naturally aligned to. Causes these structs to be aligned to that amount inside a buffer, IF that buffer is allocated with that alignment (which is not necessarily the case for buffers accessed directly inside a FlatBufferBuilder).bit_flags (on an enum): the values of this field indicate bits, meaning that any value N specified in the schema will end up representing 1<<N, or if you don't specify values at all, you'll get the sequence 1, 2, 4, 8, ...nested_flatbuffer: table_name (on a field): this indicates that the field (which must be a vector of ubyte) contains flatbuffer data, for which the root type is given by table_name. The generated code will then produce a convenient accessor for the nested FlatBuffer.The same parser that parses the schema declarations above is also able to parse JSON objects that conform to this schema. So, unlike other JSON parsers, this parser is strongly typed, and parses directly into a FlatBuffer (see the compiler documentation on how to do this from the command line, or the C++ documentation on how to do this at runtime).
diff --git a/docs/source/GoUsage.md b/docs/source/GoUsage.md index d70fc28b5..10dbd5ed2 100644 --- a/docs/source/GoUsage.md +++ b/docs/source/GoUsage.md @@ -75,7 +75,8 @@ Unlike C++, Go does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the `Vec3` is an inline component of `Monster`, it has to be created right where it is added, whereas the name and -the inventory are not inline). +the inventory are not inline, and **must** be created outside of the table +creation sequence). Structs do have convenient methods that allow you to construct them in one call. These also have arguments for nested structs, e.g. if a struct has a field `a` and a nested struct field `b` (which has fields `c` and `d`), then the arguments @@ -97,13 +98,22 @@ function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer -is being constructed back to front. +is being constructed back to front. You then pass `inv` to the corresponding +`Add` call when you construct the table containing it afterwards. There are `Prepend` functions for all the scalar types. You use `PrependUOffset` for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate `create` function in-line, as shown above in the `Monster` example. +Once you're done constructing a buffer, you call `Finish` with the root object +offset (`mon` in the example above). Your data now resides in Builder.Bytes. +Important to note is that the real data starts at the index indicated by Head(), +for Offset() bytes (this is because the buffer is constructed backwards). +If you wanted to read the buffer right after creating it (using +`GetRootAsMonster` above), the second argument, instead of `0` would thus +also be `Head()`. + ## Text Parsing There currently is no support for parsing text (Schema's and JSON) directly diff --git a/docs/source/JavaUsage.md b/docs/source/JavaUsage.md index 210cd87cd..e6321b655 100755 --- a/docs/source/JavaUsage.md +++ b/docs/source/JavaUsage.md @@ -125,7 +125,8 @@ does not sit in an array, you can also use the start/end pattern: You can use the generated method `startInventoryVector` to conveniently call `startVector` with the right element size. You pass the number of elements you want to write. Note how you write the elements backwards since -the buffer is being constructed back to front. +the buffer is being constructed back to front. You then pass `inv` to the +corresponding `Add` call when you construct the table containing it afterwards. There are `add` functions for all the scalar types. You use `addOffset` for any previously constructed objects (such as other tables, strings, vectors). diff --git a/docs/source/Schemas.md b/docs/source/Schemas.md index d7b905f8b..650e74db8 100755 --- a/docs/source/Schemas.md +++ b/docs/source/Schemas.md @@ -145,7 +145,7 @@ packages. You can include other schemas files in your current one, e.g.: - include "mydefinitions.fbs" + include "mydefinitions.fbs"; This makes it easier to refer to types defined elsewhere. `include` automatically ensures each file is parsed just once, even when referred to @@ -211,8 +211,8 @@ in the corresponding C++ code. Multiple such lines per item are allowed. Attributes may be attached to a declaration, behind a field, or after the name of a table/struct/enum/union. These may either have a value or not. Some attributes like `deprecated` are understood by the compiler, -others are simply ignored (like `priority`), but are available to query -if you parse the schema at runtime. +others are simply ignored (like `priority` in the example above), but are +available to query if you parse the schema at runtime. This is useful if you write your own code generators/editors etc., and you wish to add additional information specific to your tool (such as a help text). @@ -254,6 +254,10 @@ Current understood attributes: meaning that any value N specified in the schema will end up representing 1<