Back to godoc.org

Package ast

v0.0.0-...-1557bcf
Latest Go to latest

The latest major version is .

Published: Aug 13, 2020 | License: Apache-2.0 | Module: github.com/luci/luci-go

Overview

Package ast defines AST relevant for the documentation generation.

It recognizes top-level function declarations, top-level assignments (e.g. for constants and aliases), load(...) statements (to follow imported symbols), and struct(...) declarations.

Index

type Ellipsis

type Ellipsis string

Ellipsis represents a complex expression that we don't care about.

A value of Ellipsis type is usually literally just "...".

type EnumerableNode

type EnumerableNode interface {
	Node

	// EnumNodes returns a list of subnodes. It should not be mutated.
	EnumNodes() []Node
}

EnumerableNode is a node that has a variable number of subnodes.

Used to represents structs, modules and invocations.

type ExternalReference

type ExternalReference struct {
	ExternalName string // name of the symbol in the loaded module
	Module       string // path of the loaded module
	// contains filtered or unexported fields
}

ExternalReference is a node that represents a symbol imported though load(...) statement.

For load statement load("file.star", x="y") we get an ExternalReference with name "x", ExternalName "y" and Module "file.star".

func (*ExternalReference) Comments

func (b *ExternalReference) Comments() string

func (*ExternalReference) Doc

func (b *ExternalReference) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*ExternalReference) Name

func (b *ExternalReference) Name() string

func (*ExternalReference) Span

func (b *ExternalReference) Span() (syntax.Position, syntax.Position)

type Function

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

Function is a node that represents a function definition.

func (*Function) Comments

func (b *Function) Comments() string

func (*Function) Doc

func (n *Function) Doc() string

Doc extracts the documentation from the docstring.

func (*Function) Name

func (b *Function) Name() string

func (*Function) Span

func (b *Function) Span() (syntax.Position, syntax.Position)

type Invocation

type Invocation struct {
	Func []string // e.g. ["ns1, "ns2", "func"]
	Args []Node   // keyword arguments in order of their definition
	// contains filtered or unexported fields
}

Invocation represents `<name> = ns1.ns2.func(arg1=..., arg2=...)` call. Only keyword arguments are recognized.

func (*Invocation) Comments

func (b *Invocation) Comments() string

func (*Invocation) Doc

func (b *Invocation) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Invocation) EnumNodes

func (inv *Invocation) EnumNodes() []Node

EnumNodes returns list of nodes that represent arguments.

func (*Invocation) Name

func (b *Invocation) Name() string

func (*Invocation) Span

func (b *Invocation) Span() (syntax.Position, syntax.Position)

type Module

type Module struct {
	Namespace // all top-level symbols
	// contains filtered or unexported fields
}

Module is a parsed Starlark file.

func ParseModule

func ParseModule(filename, body string) (*Module, error)

ParseModule parses a single Starlark module.

Filename is only used when recording position information.

func (*Module) Comments

func (b *Module) Comments() string

func (*Module) Doc

func (n *Module) Doc() string

Doc extracts the documentation from the docstring.

func (*Module) Name

func (b *Module) Name() string

func (*Module) Span

func (b *Module) Span() (syntax.Position, syntax.Position)

type Namespace

type Namespace struct {
	Nodes []Node // nodes defined in the namespace, in order they were defined
	// contains filtered or unexported fields
}

Namespace is a node that contains a bunch of definitions grouped together.

Examples of namespaces are top-level module dicts and structs.

func (*Namespace) Comments

func (b *Namespace) Comments() string

func (*Namespace) Doc

func (b *Namespace) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Namespace) EnumNodes

func (ns *Namespace) EnumNodes() []Node

EnumNodes returns list of nodes that represent definitions in the namespace.

func (*Namespace) Name

func (b *Namespace) Name() string

func (*Namespace) Span

func (b *Namespace) Span() (syntax.Position, syntax.Position)

type Node

type Node interface {
	// Name is the name of the entity this node defines.
	//
	// E.g. it's the name of a function, variable, constant, etc.
	//
	// It may be a "private" name. Many definitions are defined using their
	// private names first, and then exposed publicly via separate definition
	// (such definitions are represented by Reference or ExternalReference nodes).
	Name() string

	// Span is where this node was defined in the original starlark code.
	Span() (start syntax.Position, end syntax.Position)

	// Comments is a comment block immediately preceding the definition.
	Comments() string

	// Doc is a documentation string for this symbol extracted either from a
	// docstring or from comments.
	Doc() string
	// contains filtered or unexported methods
}

Node is a documentation-relevant declaration of something in a file.

Nodes form a tree. This tree is a reduction of a full AST of the starlark file to a form we care about when generating the documentation.

The top of the tree is represented by a Module node.

type Reference

type Reference struct {
	Path []string // the ref path on the right hand side, e.g. ['a', 'b', 'c'].
	// contains filtered or unexported fields
}

Reference is a node that represents <var> = a.b.c.

It is either a top-level assignment, or a keyword argument in a function call (e.g. when defining struct(...)).

func (*Reference) Comments

func (b *Reference) Comments() string

func (*Reference) Doc

func (b *Reference) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Reference) Name

func (b *Reference) Name() string

func (*Reference) Span

func (b *Reference) Span() (syntax.Position, syntax.Position)

type Var

type Var struct {
	Value interface{} // string | int64 | *big.Int | Ellipsis
	// contains filtered or unexported fields
}

Var is a node that represents '<var> = int|string|<expr>' definition.

This is a "terminal" definition, not a reference to something defined elsewhere. Usually a constant or some computation we replace with '...' in the docs.

func (*Var) Comments

func (b *Var) Comments() string

func (*Var) Doc

func (b *Var) Doc() string

Doc extracts the documentation for the symbol from its comments.

func (*Var) Name

func (b *Var) Name() string

func (*Var) Span

func (b *Var) Span() (syntax.Position, syntax.Position)

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier