1Use in Go {#flatbuffers_guide_use_go} 2========= 3 4## Before you get started 5 6Before diving into the FlatBuffers usage in Go, it should be noted that 7the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide 8to general FlatBuffers usage in all of the supported languages (including Go). 9This page is designed to cover the nuances of FlatBuffers usage, specific to 10Go. 11 12You should also have read the [Building](@ref flatbuffers_guide_building) 13documentation to build `flatc` and should be familiar with 14[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and 15[Writing a schema](@ref flatbuffers_guide_writing_schema). 16 17## FlatBuffers Go library code location 18 19The code for the FlatBuffers Go library can be found at 20`flatbuffers/go`. You can browse the library code on the [FlatBuffers 21GitHub page](https://github.com/google/flatbuffers/tree/master/go). 22 23## Testing the FlatBuffers Go library 24 25The code to test the Go library can be found at `flatbuffers/tests`. 26The test code itself is located in [go_test.go](https://github.com/google/ 27flatbuffers/blob/master/tests/go_test.go). 28 29To run the tests, use the [GoTest.sh](https://github.com/google/flatbuffers/ 30blob/master/tests/GoTest.sh) shell script. 31 32*Note: The shell script requires [Go](https://golang.org/doc/install) to 33be installed.* 34 35## Using the FlatBuffers Go library 36 37*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth 38example of how to use FlatBuffers in Go.* 39 40FlatBuffers supports reading and writing binary FlatBuffers in Go. 41 42To use FlatBuffers in your own code, first generate Go classes from your 43schema with the `--go` option to `flatc`. Then you can include both FlatBuffers 44and the generated code to read or write a FlatBuffer. 45 46For example, here is how you would read a FlatBuffer binary file in Go: First, 47include the library and generated code. Then read a FlatBuffer binary file into 48a `[]byte`, which you pass to the `GetRootAsMonster` function: 49 50~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.go} 51 import ( 52 example "MyGame/Example" 53 flatbuffers "github.com/google/flatbuffers/go" 54 55 io/ioutil 56 ) 57 58 buf, err := ioutil.ReadFile("monster.dat") 59 // handle err 60 monster := example.GetRootAsMonster(buf, 0) 61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 62 63Now you can access values like this: 64 65~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.go} 66 hp := monster.Hp() 67 pos := monster.Pos(nil) 68~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 69 70 71In some cases it's necessary to modify values in an existing FlatBuffer in place (without creating a copy). For this reason, scalar fields of a Flatbuffer table or struct can be mutated. 72 73~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.go} 74 monster := example.GetRootAsMonster(buf, 0) 75 76 // Set table field. 77 if ok := monster.MutateHp(10); !ok { 78 panic("failed to mutate Hp") 79 } 80 81 // Set struct field. 82 monster.Pos().MutateZ(4) 83 84 // This mutation will fail because the mana field is not available in 85 // the buffer. It should be set when creating the buffer. 86 if ok := monster.MutateMana(20); !ok { 87 panic("failed to mutate Hp") 88 } 89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 90 91The term `mutate` is used instead of `set` to indicate that this is a special use case. All mutate functions return a boolean value which is false if the field we're trying to mutate is not available in the buffer. 92 93## Text Parsing 94 95There currently is no support for parsing text (Schema's and JSON) directly 96from Go, though you could use the C++ parser through cgo. Please see the 97C++ documentation for more on text parsing. 98 99<br> 100