Documentation

Overview

Package ast provides types and intefaces representing the abstract syntax tree for a single .thrift file.

Docstrings

Types which have a Doc field support parsing docstrings in the form, "/** ... */". For example, given the following,

/**
 * Name of the user who composed this message.
 *
 * If unset, the comment was posted by an anonymous user.
 */
1: optional string author

The Doc of the parsed Field will be,

Name of the user who composed this message.

If unset, the comment was posted by an anonymous user.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatAnnotations

func FormatAnnotations(anns []*Annotation) string

FormatAnnotations formats a collection of annotations into a string.

func LineNumber

func LineNumber(n Node) int

LineNumber returns the line in the file at which the given node was defined or 0 if the Node does not record its line number.

func Walk

func Walk(v Visitor, n Node)

Walk walks the AST depth-first with the given visitor, starting at the given node. The visitor's Visit function should return a non-nil visitor if it wants to visit the children of the node it was called with.

Types

type Annotation

type Annotation struct {
	Name  string
	Value string
	Line  int
}

Annotation represents a type annotation. Type annotations are key-value pairs in the form,

(foo = "bar", baz = "qux")

They may be used to customize the generated code. Annotations are optional anywhere in the code where they're accepted and may be skipped completely.

func (*Annotation) String

func (ann *Annotation) String() string

type BaseType

type BaseType struct {
	// ID of the base type.
	ID BaseTypeID

	// Type annotations associated with this reference.
	Annotations []*Annotation
	Line        int
}

BaseType is a reference to a Thrift base type.

bool, byte, i16, i32, i64, double, string, binary

All references to base types in the document may be followed by type annotations.

bool (go.type = "int")

func (BaseType) String

func (bt BaseType) String() string

type BaseTypeID

type BaseTypeID int

BaseTypeID is an identifier for primitive types supported by Thrift.

const (
	BoolTypeID   BaseTypeID = iota + 1 // bool
	I8TypeID                           // byte/i8
	I16TypeID                          // i16
	I32TypeID                          // i32
	I64TypeID                          // i64
	DoubleTypeID                       // double
	StringTypeID                       // string
	BinaryTypeID                       // binary
)

IDs of the base types supported by Thrift.

func (BaseTypeID) String

func (i BaseTypeID) String() string

type Constant

type Constant struct {
	Name  string
	Type  Type
	Value ConstantValue
	Line  int
	Doc   string
}

Constant is a constant declared in the Thrift file using a const statement.

const i32 foo = 42

func (*Constant) Info

func (c *Constant) Info() DefinitionInfo

Info for Constant

type ConstantBoolean

type ConstantBoolean bool

ConstantBoolean is a boolean value specified in the Thrift file.

true
false

type ConstantDouble

type ConstantDouble float64

ConstantDouble is a floating point value specified in the Thrift file.

1.234

type ConstantInteger

type ConstantInteger int64

ConstantInteger is an integer value specified in the Thrift file.

42

type ConstantList

type ConstantList struct {
	Items []ConstantValue
	Line  int
}

ConstantList is a list literal from the Thrift file.

[1, 2, 3]

type ConstantMap

type ConstantMap struct {
	Items []ConstantMapItem
	Line  int
}

ConstantMap is a map literal from the Thrift file.

{"a": 1, "b": 2}

Note that map literals can also be used to build structs.

type ConstantMapItem

type ConstantMapItem struct {
	Key, Value ConstantValue
	Line       int
}

ConstantMapItem is a single item in a ConstantMap.

type ConstantReference

type ConstantReference struct {
	// Name of the referenced value.
	Name string

	// Line number on which this reference was made.
	Line int
}

ConstantReference is a reference to another constant value defined in the Thrift file.

foo.bar

type ConstantString

type ConstantString string

ConstantString is a string literal specified in the Thrift file.

"hello world"

type ConstantValue

type ConstantValue interface {
	Node
	// contains filtered or unexported methods
}

ConstantValue unifies the different types representing constant values in Thrift files.

type Definition

type Definition interface {
	Node

	Info() DefinitionInfo
	// contains filtered or unexported methods
}

Definition unifies the different types representing items defined in the Thrift file.

type DefinitionInfo

type DefinitionInfo struct {
	Name string
	Line int
}

DefinitionInfo provides a common way to access name and line information for definitions.

type Enum

type Enum struct {
	Name        string
	Items       []*EnumItem
	Annotations []*Annotation
	Line        int
	Doc         string
}

Enum is a set of named integer values.

enum Status { Enabled, Disabled }

enum Role {
	User = 1,
	Moderator = 2 (py.name = "Mod"),
	Admin = 3
} (go.name = "UserRole")

func (*Enum) Info

func (e *Enum) Info() DefinitionInfo

Info for Enum.

type EnumItem

type EnumItem struct {
	Name string
	// Value of the item. This is nil if the user did not specify anything.
	Value       *int
	Annotations []*Annotation
	Line        int
	Doc         string
}

EnumItem is a single item in an Enum definition.

type Field

type Field struct {
	ID           int
	Name         string
	Type         Type
	Requiredness Requiredness
	Default      ConstantValue
	Annotations  []*Annotation
	Line         int
	Doc          string
}

Field is a single field inside a struct, union, exception, or a single item in the parameter or exception list of a function.

1: required i32 foo = 0
2: optional binary (max_length = "4096") bar
3: i64 baz (go.name = "qux")

type Function

type Function struct {
	Name        string
	Parameters  []*Field
	ReturnType  Type
	Exceptions  []*Field
	OneWay      bool
	Annotations []*Annotation
	Line        int
	Doc         string
}

Function is a single function inside a service.

binary getValue(1: string key)
	throws (1: KeyNotFoundError notFound) (
		ttl.milliseconds = "250"
	)
type Header interface {
	Node

	Info() HeaderInfo
	// contains filtered or unexported methods
}

Header unifies types representing header in the AST.

type HeaderInfo

type HeaderInfo struct {
	Line int
}

HeaderInfo provides a common way to access the line for a header.

type Include

type Include struct {
	Path string
	Name string
	Line int
}

Include is a request to include another Thrift file.

include "shared.thrift"

thriftrw's custom Include-As syntax may be used to change the name under which the file is imported.

include t "shared.thrift"

func (*Include) Info

func (i *Include) Info() HeaderInfo

Info for Include.

type ListType

type ListType struct {
	ValueType   Type
	Annotations []*Annotation
	Line        int
}

ListType is a reference to the Thrift list type.

list<a>

All references to list types may be followed by type annotations.

list<i64> (cpp.type = "vector")

func (ListType) String

func (lt ListType) String() string

type MapType

type MapType struct {
	KeyType, ValueType Type
	Annotations        []*Annotation
	Line               int
}

MapType is a reference to a the Thrift map type.

map<k, v>

All references to map types may be followed by type annotations.

map<string, list<i32>> (java.type = "MultiMap")

func (MapType) String

func (mt MapType) String() string

type Namespace

type Namespace struct {
	Scope string
	Name  string
	Line  int
}

Namespace statements allow users to choose the package name used by the generated code in certain languages.

namespace py foo.bar

func (*Namespace) Info

func (n *Namespace) Info() HeaderInfo

Info for Namespace.

type Node

type Node interface {
	// contains filtered or unexported methods
}

Node is a single element in the Thrift AST.

In addition to all Header, ConstantValue, Type, and Definition types, the following types are also AST nodes: *Annotation, ConstantMapItem, *EnumItem, *Field, *Function, *Program.

type Program

type Program struct {
	Headers     []Header
	Definitions []Definition
}

Program represents the full syntax tree for a single .thrift file.

type Requiredness

type Requiredness int

Requiredness represents whether a field was marked as required or optional, or if the user did not specify either.

const (
	Unspecified Requiredness = iota // unspecified (default)
	Required                        // required
	Optional                        // optional
)

Different requiredness levels that are supported.

type Service

type Service struct {
	Name      string
	Functions []*Function
	// Reference to the parent service if this service inherits another
	// service, nil otherwise.
	Parent      *ServiceReference
	Annotations []*Annotation
	Line        int
	Doc         string
}

Service is a collection of functions.

service KeyValue {
	void setValue(1: string key, 2: binary value)
	binary getValue(1: string key)
} (router.serviceName = "key_value")

func (*Service) Info

func (s *Service) Info() DefinitionInfo

Info for Service.

type ServiceReference

type ServiceReference struct {
	Name string
	Line int
}

ServiceReference is a reference to another service.

type SetType

type SetType struct {
	ValueType   Type
	Annotations []*Annotation
	Line        int
}

SetType is a reference to the Thrift set type.

set<a>

All references to set types may be followed by type annotations.

set<string> (js.type = "list")

func (SetType) String

func (st SetType) String() string

type Struct

type Struct struct {
	Name        string
	Type        StructureType
	Fields      []*Field
	Annotations []*Annotation
	Line        int
	Doc         string
}

Struct is a collection of named fields with different types.

This type encompasses structs, unions, and exceptions.

struct User {
	1: required string name (min_length = "3")
	2: optional Status status = Enabled;
}

struct i128 {
	1: required i64 high
	2: required i64 low
} (py.serializer = "foo.Int128Serializer")

union Contents {
	1: string plainText
	2: binary pdf
}

exception ServiceError { 1: required string message }

func (*Struct) Info

func (s *Struct) Info() DefinitionInfo

Info for Struct.

type StructureType

type StructureType int

StructureType specifies whether a struct-like type is a struct, union, or exception.

const (
	StructType    StructureType = iota + 1 // struct
	UnionType                              // union
	ExceptionType                          // exception
)

Different kinds of struct-like objects supported by us.

type Type

type Type interface {
	Node
	fmt.Stringer
	// contains filtered or unexported methods
}

Type unifies the different types representing Thrift field types.

type TypeReference

type TypeReference struct {
	Name string
	Line int
}

TypeReference references a user-defined type.

func (TypeReference) String

func (tr TypeReference) String() string

type Typedef

type Typedef struct {
	Name        string
	Type        Type
	Annotations []*Annotation
	Line        int
	Doc         string
}

Typedef is used to define an alias for another type.

typedef string UUID
typedef i64 Timestamp (unit = "milliseconds")

func (*Typedef) Info

func (t *Typedef) Info() DefinitionInfo

Info for Typedef.

type Visitor

type Visitor interface {
	Visit(w Walker, n Node) Visitor
}

Visitor walks an AST. The Visit function is called on each node of the AST. If the function returns a non-nil visitor for any node, that visitor is called on the chilren of that node.

func MultiVisitor

func MultiVisitor(visitors ...Visitor) Visitor

MultiVisitor merges the given visitors into a single Visitor.

type VisitorFunc

type VisitorFunc func(Walker, Node)

VisitorFunc is a Visitor which visits all the nodes of the AST.

func (VisitorFunc) Visit

func (f VisitorFunc) Visit(w Walker, n Node) Visitor

Visit the given node and its descendants.

type Walker

type Walker interface {
	// Ancestors returns a copy of a slice containing all the ancestor nodes
	// of the current node. The first node in the slice is the immediate
	// parent of the current node, the node after that its parent, and so on.
	Ancestors() []Node

	// Parent returns the parent node of the current node or nil if this node
	// does not have a parent node.
	Parent() Node
}

Walker provides acccess to information about the state of the AST walker.