const ShiftInstead = 57379
AllowSort allows sorting of these lists even with sorting otherwise disabled (for debugging).
var AllowSort []string
DisableRewrites disables certain rewrites (for debugging).
var DisableRewrites []string
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(f *File) []byte
Format rewrites the file and returns the formatted form of it.
func FormatString(x Expr) string
FormatString returns the string form of the given expression.
func FormatWithRewriter(w *Rewriter, f *File) []byte
FormatWithRewriter rewites the file with custom rewriter and returns the formatted form of it
func FormatWithoutRewriting(f *File) []byte
FormatWithoutRewriting returns the formatted form of the given Starlark file. This function is mostly useful for tests only, please consider using `Format` instead.
func GetParamName(param Expr) (name, op string)
GetParamName extracts the param name from an item of function params.
func GetTypes(t Expr) []string
GetTypes returns the list of types defined by the a given expression. Examples:
List[tuple[bool, int]] should return [List, Tuple, bool, int] str should return str
func IsCorrectEscaping(value string) bool
IsCorrectEscaping reports whether a string doesn't contain any incorrectly escaped sequences such as "\a".
func Rewrite(f *File)
Rewrite applies rewrites to a file
func SortLoadArgs(load *LoadStmt) bool
SortLoadArgs sorts a load statement arguments (lexicographically, but positional first)
func SortStringList(x Expr)
SortStringList sorts x, a list of strings. The list is broken by non-strings and by blank lines and comments into chunks. Each chunk is sorted in place.
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(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(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 WalkInterruptable(v Expr, f func(x Expr, stk []Expr) error)
WalkInterruptable is the same as Walk but allows traversal to be interrupted.
func WalkOnce(v Expr, f func(x *Expr))
WalkOnce calls f on every child of v.
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(v Expr, f func(x Expr, stk []Expr) error)
WalkStatements traverses sub statements (not all nodes)
An AssignExpr represents a binary expression with `=`: LHS = RHS.
type AssignExpr struct {
Comments
LHS Expr
OpPos Position
Op string
LineBreak bool // insert line break between Op and RHS
RHS Expr
}
func (x *AssignExpr) Copy() Expr
Copy creates and returns a non-deep copy of AssignExpr
func (x *AssignExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A BinaryExpr represents a binary expression: X Op Y.
type BinaryExpr struct {
Comments
X Expr
OpStart Position
Op string
LineBreak bool // insert line break between Op and Y
Y Expr
}
func (x *BinaryExpr) Copy() Expr
Copy creates and returns a non-deep copy of BinaryExpr
func (x *BinaryExpr) Span() (start, end Position)
Span returns the start and end positions of the node
BranchStmt represents a `pass`, `break`, or `continue` statement.
type BranchStmt struct {
Comments
Token string // pass, break, continue
TokenPos Position
}
func (x *BranchStmt) Copy() Expr
Copy creates and returns a non-deep copy of BranchStmt
func (x *BranchStmt) Span() (start, end Position)
Span returns the start and end positions of the node
A CallExpr represents a function call expression: X(List).
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
}
func (x *CallExpr) Copy() Expr
Copy creates and returns a non-deep copy of CallExpr
func (x *CallExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A Comment represents a single # comment.
type Comment struct {
Start Position
Token string // without trailing newline
}
func (c Comment) Span() (start, end Position)
Span returns the start and end positions of the node
A CommentBlock represents a top-level block of comments separate from any rule.
type CommentBlock struct {
Comments
Start Position
}
func (x *CommentBlock) Copy() Expr
Copy creates and returns a non-deep copy of CommentBlock
func (x *CommentBlock) Span() (start, end Position)
Span returns the start and end positions of the node
Comments collects the comments associated with an expression.
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
}
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.
A Comprehension represents a list comprehension expression: [X for ... if ...].
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
}
func (x *Comprehension) Copy() Expr
Copy creates and returns a non-deep copy of Comprehension
func (x *Comprehension) Span() (start, end Position)
Span returns the start and end positions of the node
ConditionalExpr represents the conditional: X if TEST else ELSE.
type ConditionalExpr struct {
Comments
Then Expr
IfStart Position
Test Expr
ElseStart Position
Else Expr
}
func (x *ConditionalExpr) Copy() Expr
Copy creates and returns a non-deep copy of ConditionalExpr
func (x *ConditionalExpr) Span() (start, end Position)
Span returns the start and end position of the expression, excluding leading or trailing comments. Span returns the start and end positions of the node
A DefStmt represents a function definition expression: def foo(List):.
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
Type Expr // type annotation
}
func (x *DefStmt) Copy() Expr
Copy creates and returns a non-deep copy of DefStmt
func (x *DefStmt) HeaderSpan() (start, end Position)
HeaderSpan returns the span of the function header `def f(...):`
func (x *DefStmt) Span() (start, end Position)
Span returns the start and end positions of the node
A DictExpr represents a dictionary literal: { List }.
type DictExpr struct {
Comments
Start Position
List []*KeyValueExpr
End
ForceMultiLine bool // force multiline form when printing
}
func (x *DictExpr) Copy() Expr
Copy creates and returns a non-deep copy of DictExpr
func (x *DictExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A DotExpr represents a field selector: X.Name.
type DotExpr struct {
Comments
X Expr
Dot Position
NamePos Position
Name string
}
func (x *DotExpr) Copy() Expr
Copy creates and returns a non-deep copy of DotExpr
func (x *DotExpr) Span() (start, end Position)
Span returns the start and end positions of the node
An End represents the end of a parenthesized or bracketed expression. It is a place to hang comments.
type End struct {
Comments
Pos Position
}
func (x *End) Copy() Expr
Copy creates and returns a non-deep copy of End
func (x *End) Span() (start, end Position)
Span returns the start and end positions of the node
An Expr represents an input element.
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
// Copy returns a non-deep copy of the node. Can be useful if
// the actual node type is hidden by the Expr interface and
// not relevant.
Copy() Expr
}
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.
A File represents an entire BUILD or .bzl file.
type File struct {
Path string // absolute file path
Pkg string // optional; the package of the file (always forward slashes)
Label string // optional; file path relative to the package name (always forward slashes)
WorkspaceRoot string // optional; path to the directory containing the WORKSPACE file
Type FileType
Comments
Stmt []Expr
}
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(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(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(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 ParseModule(filename string, data []byte) (*File, error)
ParseModule parses a file, marks it as a MODULE.bazel file and returns the corresponding parse tree.
The filename is used only for generating error messages.
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 (f *File) CanonicalPath() string
CanonicalPath returns the path of a file relative to the workspace root with forward slashes only
func (f *File) Copy() Expr
Copy creates and returns a non-deep copy of File
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 (f *File) DisplayPath() string
DisplayPath returns the filename if it's not empty, "<stdin>" otherwise
func (f *File) Rule(call *CallExpr) *Rule
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 (f *File) RuleNamed(name string) *Rule
RuleNamed returns the rule in the file that has the specified name, or null if no such rule.
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 (f *File) Span() (start, end Position)
Span returns the start and end positions of the node
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.
type FileType int
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
//TypeModule represents MODULE.bazel files
TypeModule
)
func (t FileType) String() string
A ForClause represents a for clause in a list comprehension: for Var in Expr.
type ForClause struct {
Comments
For Position
Vars Expr
In Position
X Expr
}
func (x *ForClause) Copy() Expr
Copy creates and returns a non-deep copy of ForClause
func (x *ForClause) Span() (start, end Position)
Span returns the start and end positions of the node
A ForStmt represents a for loop block: for x in range(10):.
type ForStmt struct {
Comments
Function
For Position // position of for
Vars Expr
X Expr
Body []Expr
}
func (x *ForStmt) Copy() Expr
Copy creates and returns a non-deep copy of ForStmt
func (x *ForStmt) Span() (start, end Position)
Span returns the start and end positions of the node
A Function represents the common parts of LambdaExpr and DefStmt
type Function struct {
Comments
StartPos Position // position of DEF or LAMBDA token
Params []Expr
Body []Expr
}
func (x *Function) Copy() Expr
Copy creates and returns a non-deep copy of Function
func (x *Function) Span() (start, end Position)
Span returns the start and end positions of the node
An Ident represents an identifier.
type Ident struct {
Comments
NamePos Position
Name string
}
func GetParamIdent(param Expr) (ident *Ident, op string)
GetParamIdent extracts the param identifier from an item of function params.
func (x *Ident) Copy() Expr
Copy creates and returns a non-deep copy of Ident
func (x *Ident) Span() (start, end Position)
Span returns the start and end positions of the node
An IfClause represents an if clause in a list comprehension: if Cond.
type IfClause struct {
Comments
If Position
Cond Expr
}
func (x *IfClause) Copy() Expr
Copy creates and returns a non-deep copy of IfClause
func (x *IfClause) Span() (start, end Position)
Span returns the start and end positions of the node
An IfStmt represents an if-else block: if x: ... else: ... . `elif`s are treated as a chain of `IfStmt`s.
type IfStmt struct {
Comments
If Position // position of if
Cond Expr
True []Expr
ElsePos End // position of else or elif
False []Expr // optional
}
func (x *IfStmt) Copy() Expr
Copy creates and returns a non-deep copy of IfStmt
func (x *IfStmt) Span() (start, end Position)
Span returns the start and end positions of the node
An IndexExpr represents an index expression: X[Y].
type IndexExpr struct {
Comments
X Expr
IndexStart Position
Y Expr
End Position
}
func (x *IndexExpr) Copy() Expr
Copy creates and returns a non-deep copy of IndexExpr
func (x *IndexExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A KeyValueExpr represents a dictionary entry: Key: Value.
type KeyValueExpr struct {
Comments
Key Expr
Colon Position
Value Expr
}
func (x *KeyValueExpr) Copy() Expr
Copy creates and returns a non-deep copy of KeyValueExpr
func (x *KeyValueExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A LambdaExpr represents a lambda expression: lambda Var: Expr.
type LambdaExpr struct {
Comments
Function
}
func (x *LambdaExpr) Copy() Expr
Copy creates and returns a non-deep copy of LambdaExpr
func (x *LambdaExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A ListExpr represents a list literal: [ List ].
type ListExpr struct {
Comments
Start Position
List []Expr
End
ForceMultiLine bool // force multiline form when printing
}
func (x *ListExpr) Copy() Expr
Copy creates and returns a non-deep copy of ListExpr
func (x *ListExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A LiteralExpr represents a literal number.
type LiteralExpr struct {
Comments
Start Position
Token string // identifier token
}
func (x *LiteralExpr) Copy() Expr
Copy creates and returns a non-deep copy of LiteralExpr
func (x *LiteralExpr) Span() (start, end Position)
Span returns the start and end positions of the node
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.
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
}
func (x *LoadStmt) Copy() Expr
Copy creates and returns a non-deep copy of LoadStmt
func (x *LoadStmt) Span() (start, end Position)
Span returns the start and end positions of the node
A ParenExpr represents a parenthesized expression: (X).
type ParenExpr struct {
Comments
Start Position
X Expr
End
ForceMultiLine bool // insert line break after opening ( and before closing )
}
func (x *ParenExpr) Copy() Expr
Copy creates and returns a non-deep copy of ParenExpr
func (x *ParenExpr) Span() (start, end Position)
Span returns the start and end positions of the node
ParseError contains information about the error encountered during parsing.
type ParseError struct {
Message string
Filename string
Pos Position
}
func (e ParseError) Error() string
Error returns a string representation of the parse error.
A Position describes the position between two bytes of input.
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 ReturnStmt represents a return statement: return f(x).
type ReturnStmt struct {
Comments
Return Position
Result Expr // may be nil
}
func (x *ReturnStmt) Copy() Expr
Copy creates and returns a non-deep copy of ReturnStmt
func (x *ReturnStmt) Span() (start, end Position)
Span returns the start and end positions of the node
Rewriter controls the rewrites to be applied.
If non-nil, the rewrites with the specified names will be run. If nil, a default set of rewrites will be used that is determined by the type (BUILD vs default starlark) of the file being rewritten.
type Rewriter struct {
RewriteSet []string
IsLabelArg map[string]bool
LabelDenyList map[string]bool
IsSortableListArg map[string]bool
SortableDenylist map[string]bool
SortableAllowlist map[string]bool
NamePriority map[string]int
StripLabelLeadingSlashes bool
ShortenAbsoluteLabelsToRelative bool
}
func (w *Rewriter) Rewrite(f *File)
Rewrite applies the rewrites to a file
A Rule represents a single BUILD 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.
}
func NewRule(call *CallExpr) *Rule
NewRule is a simple constructor for Rule.
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 (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 (r *Rule) AttrKeys() []string
AttrKeys returns the keys of all the rule's attributes.
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 (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 (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 (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 (r *Rule) ExplicitName() string
ExplicitName returns the rule's target name if it's explicitly provided as a string value, "" otherwise.
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 (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 (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 (r *Rule) SetKind(kind string)
SetKind changes rule's kind (such as "go_library").
A SetExpr represents a set literal: { List }.
type SetExpr struct {
Comments
Start Position
List []Expr
End
ForceMultiLine bool // force multiline form when printing
}
func (x *SetExpr) Copy() Expr
Copy creates and returns a non-deep copy of SetExpr
func (x *SetExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A SliceExpr represents a slice expression: expr[from:to] or expr[from:to:step] .
type SliceExpr struct {
Comments
X Expr
SliceStart Position
From Expr
FirstColon Position
To Expr
SecondColon Position
Step Expr
End Position
}
func (x *SliceExpr) Copy() Expr
Copy creates and returns a non-deep copy of SliceExpr
func (x *SliceExpr) Span() (start, end Position)
Span returns the start and end positions of the node
StopTraversalError is a special error that tells the walker to not traverse further and visit child nodes of the current node.
type StopTraversalError struct{}
func (m *StopTraversalError) Error() string
A StringExpr represents a single literal string.
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
}
func (x *StringExpr) Copy() Expr
Copy creates and returns a non-deep copy of StringExpr
func (x *StringExpr) Span() (start, end Position)
Span returns the start and end positions of the node
A TupleExpr represents a tuple literal: (List)
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
}
func (x *TupleExpr) Copy() Expr
Copy creates and returns a non-deep copy of TupleExpr
func (x *TupleExpr) Span() (start, end Position)
Span returns the start and end positions of the node
An TypedIdent represents an identifier with type annotation: "foo: int".
type TypedIdent struct {
Comments
Ident *Ident
Type Expr
}
func (x *TypedIdent) Copy() Expr
Copy creates and returns a non-deep copy of TypedIdent
func (x *TypedIdent) Span() (start, end Position)
Span returns the start and end positions of the node
A UnaryExpr represents a unary expression: Op X.
type UnaryExpr struct {
Comments
OpStart Position
Op string
X Expr
}
func (x *UnaryExpr) Copy() Expr
Copy creates and returns a non-deep copy of UnaryExpr
func (x *UnaryExpr) Span() (start, end Position)
Span returns the start and end positions of the node