build

package
v0.0.0-...-5d63770 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 24, 2020 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package build implements parsing and printing of BUILD files.

Index

Constants

View Source 
const ShiftInstead = 57378

Variables

View Source 
var AllowSort []string

For debugging: allow sorting of these lists even with sorting otherwise disabled.

View Source 
var DisableRewrites []string

For debugging: flag to disable certain rewrites.

Functions

func EditChildren 

func EditChildren(v Expr, f func(x Expr, stk []Expr) Expr)

EditChildren is similar to Edit but doesn't visit the initial node, instead goes directly to its children.

func Format 

func Format(f *File) []byte

Format returns the formatted form of the given BUILD or bzl file.

func FormatString 

func FormatString(x Expr) string

FormatString returns the string form of the given expression.

func IsCorrectEscaping 

func IsCorrectEscaping(value string) bool

IsCorrectEscaping reports whether a string doesn't contain any incorrectly escaped sequences such as "\a".

func Rewrite 

func Rewrite(f *File, info *RewriteInfo)

Rewrite applies the high-level Buildifier rewrites to f, modifying it in place. If info is non-nil, Rewrite updates it with information about the rewrite.

func SetIndentation 

func SetIndentation(indent int)

func SortLoadArgs 

func SortLoadArgs(load *LoadStmt) bool

SortLoadArgs sorts a load statement arguments (lexicographically, but positional first)

func SortStringList 

func SortStringList(x Expr)

SortStringList sorts x, a list of strings.

func Strings 

func Strings(expr Expr) []string

Strings returns expr as a []string. If expr is not a list of string literals, Strings returns a nil slice instead. If expr is an empty list of string literals, returns a non-nil empty slice. (this allows differentiating between these two cases)

func Unquote 

func Unquote(quoted string) (s string, triple bool, err error)

Unquote unquotes the quoted string, returning the actual string value, whether the original was triple-quoted, and an error describing invalid input.

func Walk 

func Walk(v Expr, f func(x Expr, stk []Expr))

Walk walks the expression tree v, calling f on all subexpressions in a preorder traversal.

The stk argument is the stack of expressions in the recursion above x, from outermost to innermost.

func WalkOnce 

func WalkOnce(v Expr, f func(x *Expr))

WalkOnce calls f on every child of v.

func WalkPointers 

func WalkPointers(v Expr, f func(x *Expr, stk []Expr))

WalkPointers is the same as Walk but calls the callback function with pointers to nodes.

func WalkStatements 

func WalkStatements(v Expr, f func(x Expr, stk []Expr))

WalkStatements traverses sub statements (not all nodes)

Types

type AssignExpr 

type AssignExpr struct {
	Comments
	LHS       Expr
	OpPos     Position
	Op        string
	LineBreak bool // insert line break between Op and RHS
	RHS       Expr
}

An AssignExpr represents a binary expression with `=`: LHS = RHS.

func (*AssignExpr) Span 

func (x *AssignExpr) Span() (start, end Position)

type BinaryExpr 

type BinaryExpr struct {
	Comments
	X         Expr
	OpStart   Position
	Op        string
	LineBreak bool // insert line break between Op and Y
	Y         Expr
}

A BinaryExpr represents a binary expression: X Op Y.

func (*BinaryExpr) Span 

func (x *BinaryExpr) Span() (start, end Position)

type BranchStmt 

type BranchStmt struct {
	Comments
	Token    string // pass, break, continue
	TokenPos Position
}

BranchStmt represents a `pass`, `break`, or `continue` statement.

func (*BranchStmt) Span 

func (x *BranchStmt) Span() (start, end Position)

type CallExpr 

type CallExpr struct {
	Comments
	X              Expr
	ListStart      Position // position of (
	List           []Expr
	End                 // position of )
	ForceCompact   bool // force compact (non-multiline) form when printing
	ForceMultiLine bool // force multiline form when printing
}

A CallExpr represents a function call expression: X(List).

func (*CallExpr) Span 

func (x *CallExpr) Span() (start, end Position)

type Comment 

type Comment struct {
	Start Position
	Token string // without trailing newline
}

A Comment represents a single # comment.

type CommentBlock 

type CommentBlock struct {
	Comments
	Start Position
}

A CommentBlock represents a top-level block of comments separate from any rule.

func (*CommentBlock) Span 

func (x *CommentBlock) Span() (start, end Position)

type Comments 

type Comments struct {
	Before []Comment // whole-line comments before this expression
	Suffix []Comment // end-of-line comments after this expression

	// For top-level expressions only, After lists whole-line
	// comments following the expression.
	After []Comment
}

Comments collects the comments associated with an expression.

func (*Comments) Comment 

func (c *Comments) Comment() *Comments

Comment returns the receiver. This isn't useful by itself, but a Comments struct is embedded into all the expression implementation types, and this gives each of those a Comment method to satisfy the Expr interface.

type Comprehension 

type Comprehension struct {
	Comments
	Curly          bool // curly braces (as opposed to square brackets)
	Lbrack         Position
	Body           Expr
	Clauses        []Expr // = *ForClause | *IfClause
	ForceMultiLine bool   // split expression across multiple lines
	End
}

A Comprehension represents a list comprehension expression: [X for ... if ...].

func (*Comprehension) Span 

func (x *Comprehension) Span() (start, end Position)

type ConditionalExpr 

type ConditionalExpr struct {
	Comments
	Then      Expr
	IfStart   Position
	Test      Expr
	ElseStart Position
	Else      Expr
}

ConditionalExpr represents the conditional: X if TEST else ELSE.

func (*ConditionalExpr) Span 

func (x *ConditionalExpr) Span() (start, end Position)

Span returns the start and end position of the expression, excluding leading or trailing comments.

type DefStmt 

type DefStmt struct {
	Comments
	Function
	Name           string
	ColonPos       Position // position of the ":"
	ForceCompact   bool     // force compact (non-multiline) form when printing the arguments
	ForceMultiLine bool     // force multiline form when printing the arguments
}

A DefStmt represents a function definition expression: def foo(List):.

func (*DefStmt) HeaderSpan 

func (x *DefStmt) HeaderSpan() (start, end Position)

HeaderSpan returns the span of the function header `def f(...):`

func (*DefStmt) Span 

func (x *DefStmt) Span() (start, end Position)

type DictExpr 

type DictExpr struct {
	Comments
	Start Position
	List  []Expr // all *KeyValueExprs
	End
	ForceMultiLine bool // force multiline form when printing
}

A DictExpr represents a dictionary literal: { List }.

func (*DictExpr) Span 

func (x *DictExpr) Span() (start, end Position)

type DotExpr 

type DotExpr struct {
	Comments
	X       Expr
	Dot     Position
	NamePos Position
	Name    string
}

A DotExpr represents a field selector: X.Name.

func (*DotExpr) Span 

func (x *DotExpr) Span() (start, end Position)

type End 

type End struct {
	Comments
	Pos Position
}

An End represents the end of a parenthesized or bracketed expression. It is a place to hang comments.

func (*End) Span 

func (x *End) Span() (start, end Position)

type Expr 

type Expr interface {
	// Span returns the start and end position of the expression,
	// excluding leading or trailing comments.
	Span() (start, end Position)

	// Comment returns the comments attached to the expression.
	// This method would normally be named 'Comments' but that
	// would interfere with embedding a type of the same name.
	Comment() *Comments
}

An Expr represents an input element.

func Edit 

func Edit(v Expr, f func(x Expr, stk []Expr) Expr) Expr

Edit walks the expression tree v, calling f on all subexpressions in a preorder traversal. If f returns a non-nil value, the tree is mutated. The new value replaces the old one.

The stk argument is the stack of expressions in the recursion above x, from outermost to innermost.

type File 

type File struct {
	Path string // file path, relative to workspace directory
	Pkg  string // optional; the package of the file
	Type FileType
	Comments
	Stmt []Expr
}

A File represents an entire BUILD or .bzl file.

func Parse 

func Parse(filename string, data []byte) (*File, error)

Parse parses the input data and returns the corresponding parse tree.

Uses the filename to detect the formatting type (build, workspace, or default) and calls ParseBuild, ParseWorkspace, or ParseDefault correspondingly.

func ParseBuild 

func ParseBuild(filename string, data []byte) (*File, error)

ParseBuild parses a file, marks it as a BUILD file and returns the corresponding parse tree.

The filename is used only for generating error messages.

func ParseBzl 

func ParseBzl(filename string, data []byte) (*File, error)

ParseBzl parses a file, marks it as a .bzl file and returns the corresponding parse tree.

The filename is used only for generating error messages.

func ParseDefault 

func ParseDefault(filename string, data []byte) (*File, error)

ParseDefault parses a file, marks it as a generic Starlark file and returns the corresponding parse tree.

The filename is used only for generating error messages.

func ParseWorkspace 

func ParseWorkspace(filename string, data []byte) (*File, error)

ParseWorkspace parses a file, marks it as a WORKSPACE file and returns the corresponding parse tree.

The filename is used only for generating error messages.

func (*File) DelRules 

func (f *File) DelRules(kind, name string) int

DelRules removes rules with the given kind and name from the file. An empty kind matches all kinds; an empty name matches all names. It returns the number of rules that were deleted.

func (*File) DisplayPath 

func (f *File) DisplayPath() string

DisplayPath returns the filename if it's not empty, "<stdin>" otherwise

func (*File) Rule 

func (f *File) Rule(call *CallExpr) *Rule

func (*File) RuleAt 

func (f *File) RuleAt(linenum int) *Rule

RuleAt returns the rule in the file that starts at the specified line, or null if no such rule.

func (*File) Rules 

func (f *File) Rules(kind string) []*Rule

Rules returns the rules in the file of the given kind (such as "go_library"). If kind == "", Rules returns all rules in the file.

func (*File) Span 

func (f *File) Span() (start, end Position)

type FileType 

type FileType int

FileType represents a type of a file (default (for .bzl files), BUILD, or WORKSPACE). Certain formatting or refactoring rules can be applied to several file types, so they support bitwise operations: `type1 | type2` can represent a scope (e.g. BUILD and WORKSPACE files) and `scope & fileType` can be used to check whether a file type belongs to a scope. 

const (
	// TypeDefault represents general Starlark files
	TypeDefault FileType = 1 << iota
	// TypeBuild represents BUILD files
	TypeBuild
	// TypeWorkspace represents WORKSPACE files
	TypeWorkspace
	// TypeBzl represents .bzl files
	TypeBzl
)

func (FileType) String 

func (t FileType) String() string

type ForClause 

type ForClause struct {
	Comments
	For  Position
	Vars Expr
	In   Position
	X    Expr
}

A ForClause represents a for clause in a list comprehension: for Var in Expr.

func (*ForClause) Span 

func (x *ForClause) Span() (start, end Position)

type ForStmt 

type ForStmt struct {
	Comments
	Function
	For  Position // position of for
	Vars Expr
	X    Expr
	Body []Expr
}

A ForStmt represents a for loop block: for x in range(10):.

func (*ForStmt) Span 

func (x *ForStmt) Span() (start, end Position)

type Function 

type Function struct {
	Comments
	StartPos Position // position of DEF or LAMBDA token
	Params   []Expr
	Body     []Expr
}

A Function represents the common parts of LambdaExpr and DefStmt

func (*Function) Span 

func (x *Function) Span() (start, end Position)

type Ident 

type Ident struct {
	Comments
	NamePos Position
	Name    string
}

An Ident represents an identifier.

func (*Ident) Span 

func (x *Ident) Span() (start, end Position)

type IfClause 

type IfClause struct {
	Comments
	If   Position
	Cond Expr
}

An IfClause represents an if clause in a list comprehension: if Cond.

func (*IfClause) Span 

func (x *IfClause) Span() (start, end Position)

type IfStmt 

type IfStmt struct {
	Comments
	If      Position // position of if
	Cond    Expr
	True    []Expr
	ElsePos End    // position of else or elif
	False   []Expr // optional
}

An IfStmt represents an if-else block: if x: ... else: ... . `elif`s are treated as a chain of `IfStmt`s.

func (*IfStmt) Span 

func (x *IfStmt) Span() (start, end Position)

type IndexExpr 

type IndexExpr struct {
	Comments
	X          Expr
	IndexStart Position
	Y          Expr
	End        Position
}

An IndexExpr represents an index expression: X[Y].

func (*IndexExpr) Span 

func (x *IndexExpr) Span() (start, end Position)

type KeyValueExpr 

type KeyValueExpr struct {
	Comments
	Key   Expr
	Colon Position
	Value Expr
}

A KeyValueExpr represents a dictionary entry: Key: Value.

func (*KeyValueExpr) Span 

func (x *KeyValueExpr) Span() (start, end Position)

type LambdaExpr 

type LambdaExpr struct {
	Comments
	Function
}

A LambdaExpr represents a lambda expression: lambda Var: Expr.

func (*LambdaExpr) Span 

func (x *LambdaExpr) Span() (start, end Position)

type ListExpr 

type ListExpr struct {
	Comments
	Start Position
	List  []Expr
	End
	ForceMultiLine bool // force multiline form when printing
}

A ListExpr represents a list literal: [ List ].

func (*ListExpr) Span 

func (x *ListExpr) Span() (start, end Position)

type LiteralExpr 

type LiteralExpr struct {
	Comments
	Start Position
	Token string // identifier token
}

A LiteralExpr represents a literal number.

func (*LiteralExpr) Span 

func (x *LiteralExpr) Span() (start, end Position)

type LoadStmt 

type LoadStmt struct {
	Comments
	Load         Position
	Module       *StringExpr
	From         []*Ident // name defined in loading module
	To           []*Ident // name in loaded module
	Rparen       End
	ForceCompact bool // force compact (non-multiline) form when printing
}

A LoadStmt loads another module and binds names from it: load(Module, "x", y="foo").

The AST is slightly unfaithful to the concrete syntax here because Skylark's load statement, so that it can be implemented in Python, binds some names (like y above) with an identifier and some (like x) without. For consistency we create fake identifiers for all the strings.

func (*LoadStmt) Span 

func (x *LoadStmt) Span() (start, end Position)

type ParenExpr 

type ParenExpr struct {
	Comments
	Start Position
	X     Expr
	End
	ForceMultiLine bool // insert line break after opening ( and before closing )
}

A ParenExpr represents a parenthesized expression: (X).

func (*ParenExpr) Span 

func (x *ParenExpr) Span() (start, end Position)

type ParseError 

type ParseError struct {
	Message  string
	Filename string
	Pos      Position
}

ParseError contains information about the error encountered during parsing.

func (ParseError) Error 

func (e ParseError) Error() string

Error returns a string representation of the parse error.

type Position 

type Position struct {
	Line     int // line in input (starting at 1)
	LineRune int // rune in line (starting at 1)
	Byte     int // byte in input (starting at 0)
}

A Position describes the position between two bytes of input.

type ReturnStmt 

type ReturnStmt struct {
	Comments
	Return Position
	Result Expr // may be nil
}

A ReturnStmt represents a return statement: return f(x).

func (*ReturnStmt) Span 

func (x *ReturnStmt) Span() (start, end Position)

type RewriteInfo 

type RewriteInfo struct {
	EditLabel        int      // number of label strings edited
	NameCall         int      // number of calls with argument names added
	SortCall         int      // number of call argument lists sorted
	SortStringList   int      // number of string lists sorted
	UnsafeSort       int      // number of unsafe string lists sorted
	SortLoad         int      // number of load argument lists sorted
	FormatDocstrings int      // number of reindented docstrings
	ReorderArguments int      // number of reordered function call arguments
	EditOctal        int      // number of edited octals
	Log              []string // log entries - may change
}

RewriteInfo collects information about what Rewrite did.

func (*RewriteInfo) Stats 

func (info *RewriteInfo) Stats() map[string]int

Stats returns a map with statistics about applied rewrites

type Rule 

type Rule struct {
	Call         *CallExpr
	ImplicitName string // The name which should be used if the name attribute is not set. See the comment on File.implicitRuleName.
}

A Rule represents a single BUILD rule.

func NewRule 

func NewRule(call *CallExpr) *Rule

NewRule is a simple constructor for Rule.

func (*Rule) Attr 

func (r *Rule) Attr(key string) Expr

Attr returns the value of the rule's attribute with the given key (such as "name" or "deps"). If the rule has no such attribute, Attr returns nil.

func (*Rule) AttrDefn 

func (r *Rule) AttrDefn(key string) *AssignExpr

AttrDefn returns the AssignExpr defining the rule's attribute with the given key. If the rule has no such attribute, AttrDefn returns nil.

func (*Rule) AttrKeys 

func (r *Rule) AttrKeys() []string

AttrKeys returns the keys of all the rule's attributes.

func (*Rule) AttrLiteral 

func (r *Rule) AttrLiteral(key string) string

AttrLiteral returns the literal form of the rule's attribute with the given key (such as "cc_api_version"), only when that value is an identifier or number. If the rule has no such attribute or the attribute is not an identifier or number, AttrLiteral returns "".

func (*Rule) AttrString 

func (r *Rule) AttrString(key string) string

AttrString returns the value of the rule's attribute with the given key (such as "name"), as a string. If the rule has no such attribute or the attribute has a non-string value, Attr returns the empty string.

func (*Rule) AttrStrings 

func (r *Rule) AttrStrings(key string) []string

AttrStrings returns the value of the rule's attribute with the given key (such as "srcs"), as a []string. If the rule has no such attribute or the attribute is not a list of strings, AttrStrings returns a nil slice.

func (*Rule) DelAttr 

func (r *Rule) DelAttr(key string) Expr

DelAttr deletes the rule's attribute with the named key. It returns the old value of the attribute, or nil if the attribute was not found.

func (*Rule) ExplicitName 

func (r *Rule) ExplicitName() string

ExplicitName returns the rule's target name if it's explicitly provided as a string value, "" otherwise.

func (*Rule) Kind 

func (r *Rule) Kind() string

Kind returns the rule's kind (such as "go_library"). The kind of the rule may be given by a literal or it may be a sequence of dot expressions that begins with a literal, if the call expression does not conform to either of these forms, an empty string will be returned

func (*Rule) Name 

func (r *Rule) Name() string

Name returns the rule's target name. If the rule has no explicit target name, Name returns the implicit name if there is one, else the empty string.

func (*Rule) SetAttr 

func (r *Rule) SetAttr(key string, val Expr)

SetAttr sets the rule's attribute with the given key to value. If the rule has no attribute with the key, SetAttr appends one to the end of the rule's attribute list.

func (*Rule) SetKind 

func (r *Rule) SetKind(kind string)

SetKind changes rule's kind (such as "go_library").

type SetExpr 

type SetExpr struct {
	Comments
	Start Position
	List  []Expr
	End
	ForceMultiLine bool // force multiline form when printing
}

A SetExpr represents a set literal: { List }.

func (*SetExpr) Span 

func (x *SetExpr) Span() (start, end Position)

type SliceExpr 

type SliceExpr struct {
	Comments
	X           Expr
	SliceStart  Position
	From        Expr
	FirstColon  Position
	To          Expr
	SecondColon Position
	Step        Expr
	End         Position
}

A SliceExpr represents a slice expression: expr[from:to] or expr[from:to:step] .

func (*SliceExpr) Span 

func (x *SliceExpr) Span() (start, end Position)

type StringExpr 

type StringExpr struct {
	Comments
	Start       Position
	Value       string // string value (decoded)
	TripleQuote bool   // triple quote output
	End         Position

	// To allow specific formatting of string literals,
	// at least within our requirements, record the
	// preferred form of Value. This field is a hint:
	// it is only used if it is a valid quoted form for Value.
	Token string
}

A StringExpr represents a single literal string.

func (*StringExpr) Span 

func (x *StringExpr) Span() (start, end Position)

type TupleExpr 

type TupleExpr struct {
	Comments
	NoBrackets bool // true if a tuple has no brackets, e.g. `a, b = x`
	Start      Position
	List       []Expr
	End
	ForceCompact   bool // force compact (non-multiline) form when printing
	ForceMultiLine bool // force multiline form when printing
}

A TupleExpr represents a tuple literal: (List)

func (*TupleExpr) Span 

func (x *TupleExpr) Span() (start, end Position)

type UnaryExpr 

type UnaryExpr struct {
	Comments
	OpStart Position
	Op      string
	X       Expr
}

A UnaryExpr represents a unary expression: Op X.

func (*UnaryExpr) Span 

func (x *UnaryExpr) Span() (start, end Position)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.