sdk.v1: Index | Files | Directories

package uast

import ""

Package uast is a generated protocol buffer package.

It is generated from these files:

It has these top-level messages:

Package uast defines a UAST (Universal Abstract Syntax Tree) representation and operations to manipulate them.


Package Files

generated.pb.go iter.go node.go pretty.go role_string.go uast.go


const (
    // IncludeChildren includes all children of the node.
    IncludeChildren IncludeFlag = 1
    // IncludeAnnotations includes UAST annotations.
    IncludeAnnotations = 2
    // IncludePositions includes token positions.
    IncludePositions = 4
    // IncludeTokens includes token contents.
    IncludeTokens = 8
    // IncludeInternalType includes internal type.
    IncludeInternalType = 16
    // IncludeProperties includes properties.
    IncludeProperties = 32
    // IncludeOriginalAST includes all properties that are present
    // in the original AST.
    IncludeOriginalAST = IncludeChildren |
        IncludePositions |
        IncludeTokens |
        IncludeInternalType |
    // IncludeAll includes all fields.
    IncludeAll = IncludeOriginalAST | IncludeAnnotations
const (
    // InternalRoleKey is a key string uses in properties to use the internal
    // role of a node in the AST, if any.
    InternalRoleKey = "internalRole"


var (
    ErrInvalidLengthGenerated = fmt.Errorf("proto: negative length found during unmarshaling")
    ErrIntOverflowGenerated   = fmt.Errorf("proto: integer overflow")
var (
    ErrEmptyAST             = errors.NewKind("empty AST given")
    ErrTwoTokensSameNode    = errors.NewKind("token was already set (%s != %s)")
    ErrTwoTypesSameNode     = errors.NewKind("internal type was already set (%s != %s)")
    ErrUnexpectedObject     = errors.NewKind("expected object of type %s, got: %#v")
    ErrUnexpectedObjectSize = errors.NewKind("expected object of size %d, got %d")
    ErrUnsupported          = errors.NewKind("unsupported: %s")
var Role_name = map[int32]string{ /* 118 elements not displayed */


Role is the main UAST annotation. It indicates that a node in an AST can be interpreted as acting with certain language-independent role.

go:generate stringer -type=Role

var Role_value = map[string]int32{ /* 118 elements not displayed */


func Pretty Uses

func Pretty(n *Node, w io.Writer, includes IncludeFlag) error

Pretty writes a pretty string representation of the *Node to a writer.

func Tokens Uses

func Tokens(n *Node) []string

type Hash Uses

type Hash uint32

Hash is a hash value.

type IncludeFlag Uses

type IncludeFlag int64

IncludeFlag represents a set of fields to be included in a Hash or String.

func (IncludeFlag) Is Uses

func (f IncludeFlag) Is(of IncludeFlag) bool

type Node Uses

type Node struct {
    // InternalType is the internal type of the node in the AST, in the source
    // language.
    InternalType string `json:",omitempty"`
    // Properties are arbitrary, language-dependent, metadata of the
    // original AST.
    Properties map[string]string `json:",omitempty"`
    // Children are the children nodes of this node.
    Children []*Node `json:",omitempty"`
    // Token is the token content if this node represents a token from the
    // original source file. If it is empty, there is no token attached.
    Token string `json:",omitempty"`
    // StartPosition is the position where this node starts in the original
    // source code file.
    StartPosition *Position `json:",omitempty"`
    // EndPosition is the position where this node ends in the original
    // source code file.
    EndPosition *Position `json:",omitempty"`
    // Roles is a list of Role that this node has. It is a language-independent
    // annotation.
    Roles []Role `json:",omitempty"`

Node is a node in a UAST.


func NewNode Uses

func NewNode() *Node

NewNode creates a new empty *Node.

func (*Node) Descriptor Uses

func (*Node) Descriptor() ([]byte, []int)

func (*Node) Hash Uses

func (n *Node) Hash() Hash

Hash returns the hash of the node.

func (*Node) HashWith Uses

func (n *Node) HashWith(includes IncludeFlag) Hash

HashWith returns the hash of the node, computed with the given set of fields.

func (*Node) Marshal Uses

func (m *Node) Marshal() (dAtA []byte, err error)

func (*Node) MarshalTo Uses

func (m *Node) MarshalTo(dAtA []byte) (int, error)

func (*Node) ProtoMessage Uses

func (*Node) ProtoMessage()

func (*Node) ProtoSize Uses

func (m *Node) ProtoSize() (n int)

func (*Node) Reset Uses

func (m *Node) Reset()

func (*Node) String Uses

func (n *Node) String() string

String converts the *Node to a string using pretty printing.

func (*Node) Unmarshal Uses

func (m *Node) Unmarshal(dAtA []byte) error

type ObjectToNode Uses

type ObjectToNode struct {
    // IsNode is used to identify witch map[string]interface{} are nodes, if
    // nil, any map[string]interface{} is considered a node.
    IsNode func(map[string]interface{}) bool
    // InternalTypeKey is the name of the key that the native AST uses
    // to differentiate the type of the AST nodes. This internal key will then be
    // checkable in the AnnotationRules with the `HasInternalType` predicate. This
    // field is mandatory.
    InternalTypeKey string
    // OffsetKey is the key used in the native AST to indicate the absolute offset,
    // from the file start position, where the code mapped to the AST node starts.
    OffsetKey string
    // EndOffsetKey is the key used in the native AST to indicate the absolute offset,
    // from the file start position, where the code mapped to the AST node ends.
    EndOffsetKey string
    // LineKey is the key used in the native AST to indicate
    // the line number where the code mapped to the AST node starts.
    LineKey string
    // EndLineKey is the key used in the native AST to indicate
    // the line number where the code mapped to the AST node ends.
    EndLineKey string
    // ColumnKey is a key that indicates the column inside the line
    ColumnKey string
    // EndColumnKey is a key that indicates the column inside the line where the node ends.
    EndColumnKey string
    // TokenKeys establishes what properties (as in JSON
    // keys) in the native AST nodes can be mapped to Tokens in the UAST. If the
    // InternalTypeKey is the "type" of a node, the Token could be tough of as the
    // "value" representation; this could be a specific value for string/numeric
    // literals or the symbol name for others.  E.g.: if a native AST represents a
    // numeric literal as: `{"ast_type": NumLiteral, "value": 2}` then you should have
    // to add `"value": true` to the TokenKeys map.  Some native ASTs will use several
    // different fields as tokens depending on the node type; in that case, all should
    // be added to this map to ensure a correct UAST generation.
    TokenKeys map[string]bool
    // SpecificTokenKeys allow to map specific nodes, by their internal type, to a
    // concrete field of the node. This can solve conflicts on some nodes that the token
    // represented by a very unique field or have more than one of the fields specified in
    // TokenKeys.
    SpecificTokenKeys map[string]string
    // SyntheticTokens is a map of InternalType to string used to add
    // synthetic tokens to nodes depending on its InternalType; sometimes native ASTs just use an
    // InternalTypeKey for some node but we need to add a Token to the UAST node to
    // improve the representation. In this case we can add both the InternalKey and
    // what token it should generate. E.g.: an InternalTypeKey called "NullLiteral" in
    // Java should be mapped using this map to "null" adding ```"NullLiteral":
    // "null"``` to this map.
    SyntheticTokens map[string]string
    // PromotedPropertyLists allows to convert some properties in the native AST with a list value
    // to its own node with the list elements as children. 	By default the UAST
    // generation will set as children of a node any uast. that hangs from any of the
    // original native AST node properties. In this process, object key serving as
    // the parent is lost and its name is added as the "internalRole" key of the children.
    // This is usually fine since the InternalTypeKey of the parent AST node will
    // usually provide enough context and the node won't any other children. This map
    // allows you to change this default behavior for specific nodes so the properties
    // are "promoted" to a new node (with an InternalTypeKey named "Parent.KeyName")
    // and the objects in its list will be shown in the UAST as children. E.g.: if you
    // have a native AST where an "If" node has the JSON keys "body", "else" and
    // "condition" each with its own list of children, you could add an entry to
    // PromotedPropertyLists like
    // "If": {"body": true, "orelse": true, "condition": true},
    // In this case, the new nodes will have the InternalTypeKey "If.body", "If.orelse"
    // and "If.condition" and with these names you should be able to write specific
    // matching rules in the annotation.go file.
    PromotedPropertyLists map[string]map[string]bool
    // If this option is set, all properties mapped to a list will be promoted to its own node. Setting
    // this option to true will ignore the PromotedPropertyLists settings.
    PromoteAllPropertyLists bool
    // PromotedPropertyStrings allows to convert some properties which value is a string
    // in the native AST as a full node with the string value as Token like:
    // "SomeKey": "SomeValue"
    // that would be converted to a child node like:
    // {"internalType": "SomeKey", "Token": "SomeValue"}
    PromotedPropertyStrings map[string]map[string]bool
    // TopLevelIsRootNode tells ToNode where to find the root node of
    // the AST.  If true, the root will be its input argument. If false,
    // the root will be the value of the only key present in its input
    // argument.
    TopLevelIsRootNode bool
    // OnToNode is called, if defined, just before the method ToNode is called,
    // allowing any modification or alteration of the AST before being
    // processed.
    OnToNode func(interface{}) (interface{}, error)
    //Modifier function is called, if defined, to modify a
    // map[string]interface{} (which normally would be converted to a Node)
    // before it's processed.
    Modifier func(map[string]interface{}) error

ObjectToNode transform trees that are represented as nested JSON objects. That is, an interface{} containing maps, slices, strings and integers. It then converts from that structure to *Node.

func (*ObjectToNode) ToNode Uses

func (c *ObjectToNode) ToNode(v interface{}) (*Node, error)

type Path Uses

type Path []*Node

Path represents a Node with its path in a tree. It is a slice with every token in the path, where the last one is the node itself. The empty path is is the zero value (e.g. parent of the root node).

func NewPath Uses

func NewPath(nodes ...*Node) Path

NewPath creates a new Path from a slice of nodes.

func (Path) Child Uses

func (p Path) Child(n *Node) Path

Child creates a Path for a given child.

func (Path) IsEmpty Uses

func (p Path) IsEmpty() bool

IsEmpty returns true if the path is empty.

func (Path) Node Uses

func (p Path) Node() *Node

Node returns the node. If the path is empty, the result is nil.

func (Path) Parent Uses

func (p Path) Parent() Path

Parent returns the path of the parent of this node.

type PathIter Uses

type PathIter interface {
    // Next returns the next node path or nil if the are no more nodes.
    Next() Path

PathIter iterates node paths.

type PathStepIter Uses

type PathStepIter interface {
    // If Step is called, children of the last node returned by Next() will
    // not be visited.

PathIter iterates node paths, optionally stepping to avoid visiting children of some nodes.

func NewOrderPathIter Uses

func NewOrderPathIter(p Path) PathStepIter

NewOrderPathIter creates an iterator that iterates all tree nodes (by default it will use preorder traversal but will switch to inorder or postorder if the Infix and Postfix roles are found).

type Position Uses

type Position struct {
    // Offset is the position as an absolute byte offset. It is a 0-based
    // index.
    Offset uint32
    // Line is the line number. It is a 1-based index.
    Line uint32
    // Col is the column number (the byte offset of the position relative to
    // a line. It is a 1-based index.
    Col uint32

Position represents a position in a source code file.

func (*Position) Descriptor Uses

func (*Position) Descriptor() ([]byte, []int)

func (*Position) Marshal Uses

func (m *Position) Marshal() (dAtA []byte, err error)

func (*Position) MarshalTo Uses

func (m *Position) MarshalTo(dAtA []byte) (int, error)

func (*Position) ProtoMessage Uses

func (*Position) ProtoMessage()

func (*Position) ProtoSize Uses

func (m *Position) ProtoSize() (n int)

func (*Position) Reset Uses

func (m *Position) Reset()

func (*Position) String Uses

func (m *Position) String() string

func (*Position) Unmarshal Uses

func (m *Position) Unmarshal(dAtA []byte) error

type Role Uses

type Role int16

Role is the main UAST annotation. It indicates that a node in an AST can be interpreted as acting with certain language-independent role.

proteus:generate go:generate stringer -type=Role

const (
    // Invalid Role is assigned as a zero value since protobuf enum definition must start at 0.
    Invalid Role = iota

    // Identifier is any form of identifier, used for variable names, functions, packages, etc.

    // Qualified is a kind of property identifiers may have, when it's composed
    // of multiple simple identifiers.

    // Operator is any form of operator.

    // Binary is any form of binary operator, in contrast with unary operators.

    // Unary is any form of unary operator, in contrast with binary operators.

    // Left is a left hand side in a binary expression.

    // Right is a right hand side if a binary expression.

    // Infix should mark the nodes which are parents of expression nodes using infix notation, e.g.: a+b.
    // Nodes without Infix or Postfix mark are considered in prefix order by default.

    // Postfix should mark the nodes which are parents of nodes using postfix notation, e.g.: ab+.
    // Nodes without Infix or Postfix mark are considered in prefix order by default.

    // Bitwise is any form of bitwise operation.

    // Boolean is any form of boolean operation.

    // Unsigned is an form of unsigned operation.

    // LeftShift is a left shift operation (i.e. `<<`, `rol`, etc.)

    // RightShift is a right shift operation (i.e. `>>`, `ror`, etc.)

    // Or is an OR operation (i.e. `||`, `or`, `|`, etc.)

    // Xor is an exclusive OR operation  (i.e. `~`, `^`, etc.)

    // And is an AND operation (i.e. `&&`, `&`, `and`, etc.)

    // Expression is a construct computed to produce some value.

    // Statement is some action to be carried out.

    // Equal is an eaquality predicate (i.e. `=`, `==`, etc.)

    // Not is a negation operation. It may be used to annotate a complement of an operator.

    // LessThan is a comparison predicate that checks if the lhs value is smaller than the rhs value (i. e. `<`.)

    // LessThanOrEqual is a comparison predicate that checks if the lhs value is smaller or equal to the rhs value (i.e. `<=`.)

    // GreaterThan is a comparison predicate that checks if the lhs value is greather than the rhs value (i. e. `>`.)

    // GreaterThanOrEqual is a comparison predicate that checks if the lhs value is greather than or equal to the rhs value (i.e. 1>=`.)

    // Identical is an identity predicate (i. e. `===`, `is`, etc.)

    // Contains is a membership predicate that checks if the lhs value is a member of the rhs container (i.e. `in` in Python.)

    // Increment is an arithmetic operator that increments a value (i. e. `++i`.)

    // Decrement is an arithmetic operator that decrements a value (i. e. `--i`.)

    // Negative is an arithmetic operator that negates a value (i.e. `-x`.)

    // Positive is an arithmetic operator that makes a value positive. It's usually redundant (i.e. `+x`.)

    // Dereference is an operation that gets the actual value of a pointer or reference (i.e. `*x`.)

    // TakeAddress is an operation that gets the memory address of a value (i. e. `&x`.)

    // File is the root node of a single file AST.

    // Add is an arithmetic operator (i.e. `+`.)

    // Substract in an arithmetic operator (i.e. `-`.)

    // Multiply is an arithmetic operator (i.e. `*`.)

    // Divide is an arithmetic operator (i.e. `/`.)

    // Modulo is an arithmetic operator (i.e. `%`, `mod`, etc.)

    // Package indicates that a package level property.

    // Declaration is a construct to specify properties of an identifier.

    // Import indicates an import level property.

    // Pathname is a qualified name of some construct.

    // Alias is an alternative name for some construct.

    // Function is a sequence of instructions packaged as a unit.

    // Body is a sequence of instructions in a block.

    // Name is an identifier used to reference a value.

    // Receiver is the target of a construct (message, function, etc.)

    // Argument is variable used as input/output in a function.

    // Value is an expression that cannot be evaluated any further.

    // ArgsList is variable number of arguments (i.e. `...`, `Object...`, `*args`, etc.)

    // Base is the parent type of which another type inherits.

    // Implements is the type (usually an interface) that another type implements.

    // Instance is a concrete occurrence of an object.

    // Subtype is a type that can be used to substitute another type.

    // Subpackage is a package that is below another package in the hierarchy.

    // Module is a set of funcitonality grouped.

    // Friend is an access granter for some private resources.

    // World is a set of every component.

    // If is used for if-then[-else] statements or expressions.
    // An if-then tree will look like:
    // 	If, Statement {
    //		**[non-If nodes] {
    //			If, Condition {
    //				[...]
    //                      }
    //		}
    //		**[non-If* nodes] {
    //			If, Then {
    //				[...]
    //			}
    //		}
    //		**[non-If* nodes] {
    //			If, Else {
    //				[...]
    //			}
    //		}
    //	}
    // The Else node is optional. The order of Condition, Then and
    // Else is not defined.

    // Condition is a condition in an IfStatement or IfExpression.

    // Then is the clause executed when the Condition is true.

    // Else is the clause executed when the Condition is false.

    // Switch is used to represent a broad of switch flavors. An expression
    // is evaluated and then compared to the values returned by different
    // case expressions, executing a body associated to the first case that
    // matches. Similar constructions that go beyond expression comparison
    // (such as pattern matching in Scala's match) should not be annotated
    // with Switch.

    // Case is a clause whose expression is compared with the condition.

    // Default is a clause that is called when no other clause is matches.

    // For is a loop with an initialization, a condition, an update and a body.

    // Initialization is the assignment of an initial value to a variable
    // (i.e. a for loop variable initialization.)

    // Update is the assignment of a new value to a variable
    // (i.e. a for loop variable update.)

    // Iterator is the element that iterates over something.

    // While is a loop construct with a condition and a body.

    // DoWhile is a loop construct with a body and a condition.

    // Break is a construct for early exiting a block.

    // Continue is a construct for continuation with the next iteration of a loop.

    // Goto is an unconditional transfer of control statement.

    // Block is a group of statements. If the source language has block scope,
    // it should be annotated both with Block and BlockScope.

    // Scope is a range in which a variable can be referred.

    // Return is a return statement. It might have a child expression or not
    // as with naked returns in Go or return in void methods in Java.

    // Try is a statement for exception handling.

    // Catch is a clause to capture exceptions.

    // Finally is a clause for a block executed after a block with exception handling.

    // Throw is a statement that creates an exception.

    // Assert checks if an expression is true and if it is not, it signals
    // an error/exception, possibly stopping the execution.

    // Call is any call, whether it is a function, procedure, method or macro.
    // In its simplest form, a call will have a single child with a function
    // name (callee). Arguments are marked with Argument and Positional or Name.
    // In OO languages there is usually a Receiver too.

    // Callee is the callable being called. It might be the name of a
    // function or procedure, it might be a method, it might a simple name
    // or qualified with a namespace.

    // Positional is an element which position has meaning (i.e. a positional argument in a call).

    // Noop is a construct that does nothing.

    // Literal is a literal value.

    // Byte is a single-byte element.

    // ByteString is a raw byte string.

    // Character is an encoded character.

    // List is a sequence.

    // Map is a collection of key, value pairs.

    // Null is an empty value.

    // Number is a numeric value. This applies to any numeric value
    // whether it is integer or float, any base, scientific notation or not,
    // etc.

    // Regexp is a regular expression.

    // Set is a collection of values.

    // String is a sequence of characters.

    // Tuple is an finite ordered sequence of elements.

    // Type is a classification of data.

    // Entry is a collection element.

    // Key is the index value of a map.

    // Primitive is a language builtin.

    // Assignment is an assignment operator.

    // This represents the self-reference of an object instance in
    // one of its methods. This corresponds to the `this` keyword
    // (e.g. Java, C++, PHP), `self` (e.g. Smalltalk, Perl, Swift) and `Me`
    // (e.g. Visual Basic).

    // Comment is a code comment.

    // Documentation is a node that represents documentation of another node,
    // such as function or package. Documentation is usually in the form of
    // a string in certain position (e.g. Python docstring) or comment
    // (e.g. Javadoc, godoc).

    // Whitespace.

    // Incomplete express that the semantic meaning of the node roles doesn't express
    // the full semantic information. Added in BIP-002.

    // Unannotated will be automatically added by the SDK for nodes that did not receive
    // any annotations with the current version of the driver's `annotations.go` file.
    // Added in BIP-002.

    // Visibility is an access granter role, usually together with an specifier role

    // Annotation is syntactic metadata

    // Anonymous is an unbound construct

    // Enumeration is a distinct type that represents a set of named constants

    // Arithmetic is a type of operation

    // Relational is a type of operation

    // Variable is a symbolic name associatend with a value

func (Role) EnumDescriptor Uses

func (Role) EnumDescriptor() ([]byte, []int)

func (Role) String Uses

func (i Role) String() string


annPackage ann provides a DSL to annotate UAST.

Package uast imports 13 packages (graph) and is imported by 31 packages. Updated 2019-03-29. Refresh now. Tools for package owners.