1 Use in Go {#flatbuffers_guide_use_go} 2 ========= 3 4 ## Before you get started 5 6 Before diving into the FlatBuffers usage in Go, it should be noted that 7 the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide 8 to general FlatBuffers usage in all of the supported languages (including Go). 9 This page is designed to cover the nuances of FlatBuffers usage, specific to 10 Go. 11 12 You should also have read the [Building](@ref flatbuffers_guide_building) 13 documentation 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 19 The code for the FlatBuffers Go library can be found at 20 `flatbuffers/go`. You can browse the library code on the [FlatBuffers 21 GitHub page](https://github.com/google/flatbuffers/tree/master/go). 22 23 ## Testing the FlatBuffers Go library 24 25 The code to test the Go library can be found at `flatbuffers/tests`. 26 The test code itself is located in [go_test.go](https://github.com/google/ 27 flatbuffers/blob/master/tests/go_test.go). 28 29 To run the tests, use the [GoTest.sh](https://github.com/google/flatbuffers/ 30 blob/master/tests/GoTest.sh) shell script. 31 32 *Note: The shell script requires [Go](https://golang.org/doc/install) to 33 be installed.* 34 35 ## Using the FlatBuffers Go library 36 37 *Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth 38 example of how to use FlatBuffers in Go.* 39 40 FlatBuffers supports reading and writing binary FlatBuffers in Go. 41 42 To use FlatBuffers in your own code, first generate Go classes from your 43 schema with the `--go` option to `flatc`. Then you can include both FlatBuffers 44 and the generated code to read or write a FlatBuffer. 45 46 For example, here is how you would read a FlatBuffer binary file in Go: First, 47 include the library and generated code. Then read a FlatBuffer binary file into 48 a `[]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 63 Now you can access values like this: 64 65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.go} 66 hp := monster.Hp() 67 pos := monster.Pos(nil) 68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 69 70 71 In 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 91 The 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 95 There currently is no support for parsing text (Schema's and JSON) directly 96 from Go, though you could use the C++ parser through cgo. Please see the 97 C++ documentation for more on text parsing. 98 99 <br> 100
