ceph/src/jaegertracing/thrift/lib/go/README.md

   1 Thrift Go Software Library
   2
   3 License
   4 =======
   5
   6 Licensed to the Apache Software Foundation (ASF) under one
   7 or more contributor license agreements. See the NOTICE file
   8 distributed with this work for additional information
   9 regarding copyright ownership. The ASF licenses this file
  10 to you under the Apache License, Version 2.0 (the
  11 "License"); you may not use this file except in compliance
  12 with the License. You may obtain a copy of the License at
  13
  14   http://www.apache.org/licenses/LICENSE-2.0
  15
  16 Unless required by applicable law or agreed to in writing,
  17 software distributed under the License is distributed on an
  18 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  19 KIND, either express or implied. See the License for the
  20 specific language governing permissions and limitations
  21 under the License.
  22
  23
  24 Using Thrift with Go
  25 ====================
  26
  27 Thrift supports Go 1.7+
  28
  29 In following Go conventions, we recommend you use the 'go' tool to install
  30 Thrift for go.
  31
  32     $ go get github.com/apache/thrift/lib/go/thrift/...
  33
  34 Will retrieve and install the most recent version of the package.
  35
  36
  37 A note about optional fields
  38 ============================
  39
  40 The thrift-to-Go compiler tries to represent thrift IDL structs as Go structs.
  41 We must be able to distinguish between optional fields that are set to their
  42 default value and optional values which are actually unset, so the generated
  43 code represents optional fields via pointers.
  44
  45 This is generally intuitive and works well much of the time, but Go does not
  46 have a syntax for creating a pointer to a constant in a single expression. That
  47 is, given a struct like
  48
  49     struct SomeIDLType {
  50         OptionalField *int32
  51     }
  52
  53 , the following will not compile:
  54
  55     x := &SomeIDLType{
  56         OptionalField: &(3),
  57     }
  58
  59 (Nor is there any other syntax that's built in to the language)
  60
  61 As such, we provide some helpers that do just this under lib/go/thrift/. E.g.,
  62
  63     x := &SomeIDLType{
  64         OptionalField: thrift.Int32Ptr(3),
  65     }
  66
  67 And so on. The code generator also creates analogous helpers for user-defined
  68 typedefs and enums.
  69
  70 Adding custom tags to generated Thrift structs
  71 ==============================================
  72
  73 You can add tags to the auto-generated thrift structs using the following format:
  74
  75     struct foo {
  76       1: required string Bar (go.tag = "some_tag:\"some_tag_value\"")
  77     }
  78
  79 which will generate:
  80
  81     type Foo struct {
  82       Bar string `thrift:"bar,1,required" some_tag:"some_tag_value"`
  83     }