oracle

Documentation

Overview

Package oracle contains the implementation of the oracle tool whose command-line is provided by golang.org/x/tools/cmd/oracle.

http://golang.org/s/oracle-design http://golang.org/s/oracle-user-manual

Index

• type Oracle
  • func New(iprog *loader.Program, ptalog io.Writer, reflection bool) (*Oracle, error)
  • func (o *Oracle) Query(mode string, qpos *QueryPos) (*Result, error)
• type QueryPos
  • func ParseQueryPos(iprog *loader.Program, posFlag string, needExact bool) (*QueryPos, error)
  • func (qpos *QueryPos) ObjectString(obj types.Object) string
  • func (qpos *QueryPos) SelectionString(sel *types.Selection) string
  • func (qpos *QueryPos) TypeString(T types.Type) string
• type Result
  • func Query(args []string, mode, pos string, ptalog io.Writer, buildContext *build.Context, ...) (*Result, error)
  • func (res *Result) Serial() *serial.Result
  • func (res *Result) WriteTo(out io.Writer)

Types

type Oracle

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

An Oracle holds the program state required for one or more queries.

func New

func New(iprog *loader.Program, ptalog io.Writer, reflection bool) (*Oracle, error)

New constructs a new Oracle that can be used for a sequence of queries.

iprog specifies the program to analyze. ptalog is the (optional) pointer-analysis log file. reflection determines whether to model reflection soundly (currently slow).

func (*Oracle) Query

func (o *Oracle) Query(mode string, qpos *QueryPos) (*Result, error)

Query runs the query of the specified mode and selection.

TODO(adonovan): fix: this function does not currently support the "what" query, which needs to access the go/build.Context.

type QueryPos

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

A QueryPos represents the position provided as input to a query: a textual extent in the program's source code, the AST node it corresponds to, and the package to which it belongs. Instances are created by ParseQueryPos.

func ParseQueryPos

func ParseQueryPos(iprog *loader.Program, posFlag string, needExact bool) (*QueryPos, error)

ParseQueryPos parses the source query position pos. If needExact, it must identify a single AST subtree; this is appropriate for queries that allow fairly arbitrary syntax, e.g. "describe".

func (*QueryPos) ObjectString

func (qpos *QueryPos) ObjectString(obj types.Object) string

ObjectString prints object obj relative to the query position.

func (*QueryPos) SelectionString

func (qpos *QueryPos) SelectionString(sel *types.Selection) string

SelectionString prints selection sel relative to the query position.

func (*QueryPos) TypeString

func (qpos *QueryPos) TypeString(T types.Type) string

TypeString prints type T relative to the query position.

type Result

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

A Result encapsulates the result of an oracle.Query.

func Query

func Query(args []string, mode, pos string, ptalog io.Writer, buildContext *build.Context, reflection bool) (*Result, error)

Query runs a single oracle query.

args specify the main package in (*loader.Config).FromArgs syntax. mode is the query mode ("callers", etc). ptalog is the (optional) pointer-analysis log file. buildContext is the go/build configuration for locating packages. reflection determines whether to model reflection soundly (currently slow).

Clients that intend to perform multiple queries against the same analysis scope should use this pattern instead:

conf := loader.Config{Build: buildContext}
... populate config, e.g. conf.FromArgs(args) ...
iprog, err := conf.Load()
if err != nil { ... }
o, err := oracle.New(iprog, nil, false)
if err != nil { ... }
for ... {
	qpos, err := oracle.ParseQueryPos(imp, pos, needExact)
	if err != nil { ... }

	res, err := o.Query(mode, qpos)
	if err != nil { ... }

	// use res
}

TODO(adonovan): the ideal 'needsExact' parameter for ParseQueryPos depends on the query mode; how should we expose this?

func (*Result) Serial

func (res *Result) Serial() *serial.Result

Serial returns an instance of serial.Result, which implements the {xml,json}.Marshaler interfaces so that query results can be serialized as JSON or XML.

func (*Result) WriteTo

func (res *Result) WriteTo(out io.Writer)

WriteTo writes the oracle query result res to out in a compiler diagnostic format.