text

Documentation

Overview

Package text implements the text format for protocol buffers. This package has no semantic understanding for protocol buffers and is only a parser and composer for the format.

There is no formal specification for the protobuf text format, as such the C++ implementation (see google::protobuf::TextFormat) is the reference implementation of the text format.

This package is neither a superset nor a subset of the C++ implementation. This implementation permits a more liberal grammar in some cases to be backwards compatible with the historical Go implementation. Future parsings unique to Go should not be added. Some grammars allowed by the C++ implementation are deliberately not implemented here because they are considered a bug by the protobuf team and should not be replicated.

The Go implementation should implement a sufficient amount of the C++ grammar such that the default text serialization by C++ can be parsed by Go. However, just because the C++ parser accepts some input does not mean that the Go implementation should as well.

The text format is almost a superset of JSON except:

• message keys are not quoted strings, but identifiers
• the top-level value must be a message without the delimiters

Index

• Variables
• func AppendString(b []byte, s string) []byte
• func TokenEquals(x, y Token) bool
• func UnmarshalString(s string) (string, error)
• type Decoder
  • func NewDecoder(b []byte) *Decoder
  • func (d *Decoder) Peek() (Token, error)
  • func (d *Decoder) Position(idx int) (line int, column int)
  • func (d *Decoder) Read() (Token, error)
• type Encoder
  • func NewEncoder(buf []byte, indent string, delims [2]byte, outputASCII bool) (*Encoder, error)
  • func (e *Encoder) Bytes() []byte
  • func (e *Encoder) EndMessage()
  • func (e *Encoder) Reset(es encoderState)
  • func (e *Encoder) Snapshot() encoderState
  • func (e *Encoder) StartMessage()
  • func (e *Encoder) WriteBool(b bool)
  • func (e *Encoder) WriteFloat(n float64, bitSize int)
  • func (e *Encoder) WriteInt(n int64)
  • func (e *Encoder) WriteLiteral(s string)
  • func (e *Encoder) WriteName(s string)
  • func (e *Encoder) WriteString(s string)
  • func (e *Encoder) WriteUint(n uint64)
• type Kind
  • func (t Kind) String() string
• type NameKind
  • func (t NameKind) String() string
• type Token
  • func (t Token) Bool() (bool, bool)
  • func (t Token) Enum() (string, bool)
  • func (t Token) FieldNumber() int32
  • func (t Token) Float32() (float32, bool)
  • func (t Token) Float64() (float64, bool)
  • func (t Token) HasSeparator() bool
  • func (t Token) IdentName() string
  • func (t Token) Int32() (int32, bool)
  • func (t Token) Int64() (int64, bool)
  • func (t Token) Kind() Kind
  • func (t Token) NameKind() NameKind
  • func (t Token) Pos() int
  • func (t Token) RawString() string
  • func (t Token) String() (string, bool)
  • func (t Token) TypeName() string
  • func (t Token) Uint32() (uint32, bool)
  • func (t Token) Uint64() (uint64, bool)

Variables

var ErrUnexpectedEOF = errors.New("%v", io.ErrUnexpectedEOF)

ErrUnexpectedEOF means that EOF was encountered in the middle of the input.

Functions

func AppendString

func AppendString(b []byte, s string) []byte

AppendString appends the escaped form of the input string to b.

func TokenEquals

func TokenEquals(x, y Token) bool

TokenEquals returns true if given Tokens are equal, else false.

func UnmarshalString

func UnmarshalString(s string) (string, error)

UnmarshalString returns an unescaped string given a textproto string value. String value needs to contain single or double quotes. This is only used by internal/encoding/defval package for unmarshaling bytes.

Types

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder is a token-based textproto decoder.

func NewDecoder

func NewDecoder(b []byte) *Decoder

NewDecoder returns a Decoder to read the given []byte.

func (*Decoder) Peek

func (d *Decoder) Peek() (Token, error)

Peek looks ahead and returns the next token and error without advancing a read.

func (*Decoder) Position

func (d *Decoder) Position(idx int) (line int, column int)

Position returns line and column number of given index of the original input. It will panic if index is out of range.

func (*Decoder) Read

func (d *Decoder) Read() (Token, error)

Read returns the next token. It will return an error if there is no valid token.

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder provides methods to write out textproto constructs and values. The user is responsible for producing valid sequences of constructs and values.

func NewEncoder

func NewEncoder(buf []byte, indent string, delims [2]byte, outputASCII bool) (*Encoder, error)

NewEncoder returns an Encoder.

If indent is a non-empty string, it causes every entry in a List or Message to be preceded by the indent and trailed by a newline.

If delims is not the zero value, it controls the delimiter characters used for messages (e.g., "{}" vs "<>").

If outputASCII is true, strings will be serialized in such a way that multi-byte UTF-8 sequences are escaped. This property ensures that the overall output is ASCII (as opposed to UTF-8).

func (*Encoder) Bytes

func (e *Encoder) Bytes() []byte

Bytes returns the content of the written bytes.

func (*Encoder) EndMessage

func (e *Encoder) EndMessage()

EndMessage writes out the '}' or '>' symbol.

func (*Encoder) Reset

func (e *Encoder) Reset(es encoderState)

Reset resets the Encoder to the given encoderState from a Snapshot.

func (*Encoder) Snapshot

func (e *Encoder) Snapshot() encoderState

Snapshot returns the current snapshot for use in Reset.

func (*Encoder) StartMessage

func (e *Encoder) StartMessage()

StartMessage writes out the '{' or '<' symbol.

func (*Encoder) WriteBool

func (e *Encoder) WriteBool(b bool)

WriteBool writes out the given boolean value.

func (*Encoder) WriteFloat

func (e *Encoder) WriteFloat(n float64, bitSize int)

WriteFloat writes out the given float value for given bitSize.

func (*Encoder) WriteInt

func (e *Encoder) WriteInt(n int64)

WriteInt writes out the given signed integer value.

func (*Encoder) WriteLiteral

func (e *Encoder) WriteLiteral(s string)

WriteLiteral writes out the given string as a literal value without quotes. This is used for writing enum literal strings.

func (*Encoder) WriteName

func (e *Encoder) WriteName(s string)

WriteName writes out the field name and the separator ':'.

func (*Encoder) WriteString

func (e *Encoder) WriteString(s string)

WriteString writes out the given string value.

func (*Encoder) WriteUint

func (e *Encoder) WriteUint(n uint64)

WriteUint writes out the given unsigned integer value.

type Kind

type Kind uint8

Kind represents a token kind expressible in the textproto format.

const (
	Invalid Kind = iota
	EOF
	Name   // Name indicates the field name.
	Scalar // Scalar are scalar values, e.g. "string", 47, ENUM_LITERAL, true.
	MessageOpen
	MessageClose
	ListOpen
	ListClose
)

Kind values.

func (Kind) String

func (t Kind) String() string

type NameKind

type NameKind uint8

NameKind represents different types of field names.

const (
	IdentName NameKind = iota + 1
	TypeName
	FieldNumber
)

NameKind values.

func (NameKind) String

func (t NameKind) String() string

type Token

type Token struct {
	// contains filtered or unexported fields
}

Token provides a parsed token kind and value. Values are provided by the different accessor methods.

func (Token) Bool

func (t Token) Bool() (bool, bool)

Bool returns the bool value for a Scalar type.

func (Token) Enum

func (t Token) Enum() (string, bool)

Enum returns the literal value for a Scalar type for use as enum literals.

func (Token) FieldNumber

func (t Token) FieldNumber() int32

FieldNumber returns the value for FieldNumber type. It returns a non-negative int32 value. Caller will still need to validate for the correct field number range.

func (Token) Float32

func (t Token) Float32() (float32, bool)

Float32 returns the float32 value for a Scalar type.

func (Token) Float64

func (t Token) Float64() (float64, bool)

Float64 returns the float64 value for a Scalar type.

func (Token) HasSeparator

func (t Token) HasSeparator() bool

HasSeparator returns true if the field name is followed by the separator char ':', else false. It panics if type is not Name.

func (Token) IdentName

func (t Token) IdentName() string

IdentName returns the value for IdentName type.

func (Token) Int32

func (t Token) Int32() (int32, bool)

Int32 returns the int32 value for a Scalar type.

func (Token) Int64

func (t Token) Int64() (int64, bool)

Int64 returns the int64 value for a Scalar type.

func (Token) Kind

func (t Token) Kind() Kind

Kind returns the token kind.

func (Token) NameKind

func (t Token) NameKind() NameKind

NameKind returns IdentName, TypeName or FieldNumber. It panics if type is not Name.

func (Token) Pos

func (t Token) Pos() int

Pos returns the token position from the input.

func (Token) RawString

func (t Token) RawString() string

RawString returns the read value in string.

func (Token) String

func (t Token) String() (string, bool)

String returns the string value for a Scalar type.

func (Token) TypeName

func (t Token) TypeName() string

TypeName returns the value for TypeName type.

func (Token) Uint32

func (t Token) Uint32() (uint32, bool)

Uint32 returns the uint32 value for a Scalar type.

func (Token) Uint64

func (t Token) Uint64() (uint64, bool)

Uint64 returns the uint64 value for a Scalar type.