parser

Documentation

Overview

Package parser edits text proto files, applies standard formatting and preserves comments. See also: https://github.com/golang/protobuf/blob/master/proto/text_parser.go

To disable a specific file from getting formatted, add '# txtpbfmt: disable' at the top of the file.

Index

• Constants
• func ByFieldOrder(name string, fieldOrder []string, unsortedCollector UnsortedFieldCollectorFunc) ast.NodeLess
• func DebugFormat(nodes []*ast.Node, depth int) string
• func Format(in []byte) ([]byte, error)
• func FormatWithConfig(in []byte, c Config) ([]byte, error)
• func Parse(in []byte) ([]*ast.Node, error)
• func ParseWithConfig(in []byte, c Config) ([]*ast.Node, error)
• func Pretty(nodes []*ast.Node, depth int) string
• func PrettyBytes(nodes []*ast.Node, depth int) []byte
• func RemoveDuplicates(nodes []*ast.Node)
• type Config
  • func (c *Config) AddFieldSortOrder(nodeName string, fieldOrder ...string)
• type Logger
• type NodeFilterFunction
• type NodeSortFunction
• type UnsortedField
• type UnsortedFieldCollector
• type UnsortedFieldCollectorFunc
• type UnsortedFieldsError
  • func (e *UnsortedFieldsError) Error() string
• type ValuesSortFunction

Constants

const RootName = "__ROOT__"

RootName contains a constant that can be used to identify the root of all Nodes.

Functions

func ByFieldOrder

func ByFieldOrder(name string, fieldOrder []string, unsortedCollector UnsortedFieldCollectorFunc) ast.NodeLess

ByFieldOrder returns a NodeLess function that orders fields within a node named name by the order specified in fieldOrder. Nodes sorted but not specified by the field order are bubbled to the top and reported to unsortedCollector.

func DebugFormat

func DebugFormat(nodes []*ast.Node, depth int) string

DebugFormat returns a textual representation of the specified nodes for consumption by humans when debugging (e.g. in test failures). No guarantees are made about the specific output.

func Format

func Format(in []byte) ([]byte, error)

Format formats a text proto file preserving comments.

func FormatWithConfig

func FormatWithConfig(in []byte, c Config) ([]byte, error)

FormatWithConfig functions similar to format, but allows the user to pass in additional configuration options.

func Parse

func Parse(in []byte) ([]*ast.Node, error)

Parse returns a tree representation of a textproto file.

func ParseWithConfig

func ParseWithConfig(in []byte, c Config) ([]*ast.Node, error)

ParseWithConfig functions similar to Parse, but allows the user to pass in additional configuration options.

func Pretty

func Pretty(nodes []*ast.Node, depth int) string

Pretty formats the nodes at the given indentation depth (0 = top-level).

func PrettyBytes

func PrettyBytes(nodes []*ast.Node, depth int) []byte

PrettyBytes returns formatted nodes at the given indentation depth (0 = top-level) as bytes.

func RemoveDuplicates

func RemoveDuplicates(nodes []*ast.Node)

RemoveDuplicates marks duplicate key:value pairs from nodes as Deleted.

Types

type Config

type Config struct {
	// Do not apply any reformatting to this file.
	Disable bool

	// Expand all children irrespective of the initial state.
	ExpandAllChildren bool

	// Skip colons whenever possible.
	SkipAllColons bool

	// Allow unnamed nodes everywhere.
	// Default is to allow only top-level nodes to be unnamed.
	AllowUnnamedNodesEverywhere bool

	// Sort fields by field name.
	SortFieldsByFieldName bool

	// Sort adjacent scalar fields of the same field name by their contents.
	SortRepeatedFieldsByContent bool

	// Sort adjacent message fields of the given field name by the contents of the given subfield.
	// Format: either "field_name.subfield_name" or just "subfield_name" (applies to all field names).
	SortRepeatedFieldsBySubfield []string

	// RequireFieldSortOrderToMatchAllFieldsInNode will cause parsing to fail if a node was added via
	// AddFieldSortOrder() but 1+ fields under that node in the textproto aren't specified in the
	// field order. This won't fail for nodes that don't have a field order specified at all. Use this
	// to strictly enforce that your field order config always orders ALL the fields, and you're
	// willing for new fields in the textproto to break parsing in order to enforce it.
	RequireFieldSortOrderToMatchAllFieldsInNode bool

	// Remove lines that have the same field name and scalar value as another.
	RemoveDuplicateValuesForRepeatedFields bool

	// Permit usage of Python-style """ or ”' delimited strings.
	AllowTripleQuotedStrings bool

	// Max columns for string field values. If zero, no string wrapping will occur.
	// Strings that may contain HTML tags will never be wrapped.
	WrapStringsAtColumn int

	// Whether strings that appear to contain HTML tags should be wrapped
	// (requires WrapStringsAtColumn to be set).
	WrapHTMLStrings bool

	// Wrap string field values after each newline.
	// Should not be used with other Wrap* options.
	WrapStringsAfterNewlines bool

	// Whether angle brackets used instead of curly braces should be preserved
	// when outputting a formatted textproto.
	PreserveAngleBrackets bool

	// Use single quotes around strings that contain double but not single quotes.
	SmartQuotes bool

	// Logger enables logging when it is non-nil.
	// If the log messages aren't going to be useful, it's best to leave Logger
	// set to nil, as otherwise log messages will be constructed.
	Logger Logger
	// contains filtered or unexported fields
}

Config can be used to pass additional config parameters to the formatter at the time of the API call.

func (*Config) AddFieldSortOrder

func (c *Config) AddFieldSortOrder(nodeName string, fieldOrder ...string)

AddFieldSortOrder adds a config rule for the given Node.Name, so that all contained field names are output in the provided order. To specify an order for top-level Nodes, use RootName as the nodeName.

type Logger

type Logger interface {
	// Infof is used for informative messages, for testing or debugging.
	Infof(format string, args ...any)
}

Logger is a small glog-like interface.

type NodeFilterFunction

type NodeFilterFunction func(nodes []*ast.Node)

NodeFilterFunction filters the given nodes.

type NodeSortFunction

type NodeSortFunction func(parent *ast.Node, nodes []*ast.Node) error

NodeSortFunction sorts the given nodes, using the parent node as context. parent can be nil.

type UnsortedField

type UnsortedField struct {
	FieldName       string
	Line            int32
	ParentFieldName string
}

UnsortedField records details about a single unsorted field.

type UnsortedFieldCollector

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

UnsortedFieldCollector collects UnsortedFields during parsing.

type UnsortedFieldCollectorFunc

type UnsortedFieldCollectorFunc func(name string, line int32, parent string)

UnsortedFieldCollectorFunc collects UnsortedFields during parsing.

type UnsortedFieldsError

type UnsortedFieldsError struct {
	UnsortedFields []UnsortedField
}

UnsortedFieldsError will be returned by ParseWithConfig if Config.RequireFieldSortOrderToMatchAllFieldsInNode is set, and an unrecognized field is found while parsing.

func (*UnsortedFieldsError) Error

func (e *UnsortedFieldsError) Error() string

type ValuesSortFunction

type ValuesSortFunction func(values []*ast.Value)

ValuesSortFunction sorts the given values.