driver

Documentation

Overview

Package driver contains all the logic to build a driver.

Index

• Constants
• Variables
• func JoinErrors(errs []error) error
• type Driver
• type DriverModule
  • func NewDriverFrom(d Native, m *manifest.Manifest, t Transforms) (DriverModule, error)
• type ErrMulti
• type Mode
  • func ParseMode(mode string) (Mode, error)
• type Module
• type Native
• type ParseOptions
• type Transforms
  • func (t Transforms) Do(rctx context.Context, mode Mode, code string, nd nodes.Node) (nodes.Node, error)

Constants

const (
	ModeNative = Mode(1 << iota)
	ModePreprocessed
	ModeAnnotated
	ModeSemantic
)

const ModeDefault = ModeSemantic

Variables

var (
	// ErrDriverFailure is returned when the driver is malfunctioning.
	ErrDriverFailure = derrors.ErrDriverFailure

	// ErrSyntax is returned when driver cannot parse the source file.
	// Can be omitted for native driver implementations.
	ErrSyntax = derrors.ErrSyntax

	// ErrTransformFailure is returned if one of the UAST transformations fails.
	ErrTransformFailure = errors.NewKind("transform failed")

	// ErrModeNotSupported is returned if a UAST transformation mode is not supported by the driver.
	ErrModeNotSupported = errors.NewKind("transform mode not supported")
)

Functions

func JoinErrors

func JoinErrors(errs []error) error

Join multiple errors into a single error value.

Types

type Driver

type Driver interface {
	// Parse reads the input string and constructs an AST representation of it.
	//
	// Language can be specified by providing ParseOptions. If the language is not set,
	// it will be set during the Parse call if implementation supports language detection.
	//
	// Depending on the mode, AST may be transformed to different UAST variants.
	// ErrModeNotSupported is returned for unsupported transformation modes.
	//
	// Syntax errors are indicated by returning ErrSyntax.
	// In this case a non-empty UAST may be returned, if driver supports partial parsing.
	//
	// Native driver failures are indicated by ErrDriverFailure and UAST transformation are indicated by ErrTransformFailure.
	// All other errors indicate a protocol or server failure.
	Parse(ctx context.Context, src string, opts *ParseOptions) (nodes.Node, error)
}

Driver is an interface for a language driver that returns UAST.

type DriverModule

type DriverModule interface {
	Module
	Driver
	Manifest() (manifest.Manifest, error)
}

DriverModule is an interface for a driver instance.

func NewDriverFrom

func NewDriverFrom(d Native, m *manifest.Manifest, t Transforms) (DriverModule, error)

NewDriver returns a new Driver instance based on the given ObjectToNode and list of transformers.

type ErrMulti

type ErrMulti = derrors.ErrMulti

ErrMulti joins multiple errors.

type Mode

type Mode int

func ParseMode

func ParseMode(mode string) (Mode, error)

Parse mode parses a UAST mode string to an enum value.

type Module

type Module interface {
	Start() error
	Close() error
}

Module is an interface for a generic module instance.

type Native

type Native interface {
	Module
	// Parse reads the input string and constructs an AST representation of it.
	// All errors are considered ErrSyntax, unless they are wrapped into ErrDriverFailure.
	Parse(ctx context.Context, src string) (nodes.Node, error)
}

Native is a base interface of a language driver that returns a native AST.

type ParseOptions

type ParseOptions struct {
	Mode     Mode
	Language string
	Filename string
}

type Transforms

type Transforms struct {
	// Namespace for native AST nodes of this language. Only enabled in Semantic mode.
	//
	// Namespace will be set at the end of the pipeline, thus all transforms can
	// use type names without the driver namespace.
	Namespace string

	// Preprocess stage normalizes native AST for both Annotated and Semantic stages.
	//
	// It usually:
	//  * changes type key to uast.KeyType
	//  * restructures positional information
	//  * fixes any issues with native AST structure
	Preprocess []transformer.Transformer

	// PreprocessCode stage runs code-assisted transformations after the Preprocess stage.
	// It can be used to fix node tokens or positional information based on the source.
	PreprocessCode []transformer.CodeTransformer

	// Normalize stage converts a known native AST structures to a canonicalized
	// high-level AST representation (UAST). It is executed after PreprocessCode
	// and before the Annotations stage.
	Normalize []transformer.Transformer

	// Annotations stage applies UAST role annotations and is executed after
	// Semantic stage, or after PreprocessCode if Semantic is disabled.
	//
	// It also changes token key to uast.KeyToken. It should not be done in the
	// Preprocess stage, because Semantic annotations are easier on clean native AST.
	Annotations []transformer.Transformer

	// Code stage is applied directly after annotations and provides a way
	// to extract more information from source files, fix positional info, etc.
	//
	// TODO(dennwc): deprecate and examine drivers; documentation was incorrect
	//               it was described that the stage runs after Native, but it
	//               was always running after all annotation stages
	//
	// Deprecated: see PreprocessCode
	Code []transformer.CodeTransformer
}

Transforms describes a set of AST transformations the driver requires.

The pipeline can be illustrated as:

     ( AST )--------------> ( ModeNative )
        V
  [ Preprocess ]
[ PreprocessCode ]--------> ( ModePreprocessed )
        |
        |----------------\
        |           [ Normalize ]
 [ Annotations ] <-------/
        |
        V
    [ Code ]-------------\
        |           [ Namespace ]
        |                |
        V                V
 ( ModeAnnotated ) ( ModeSemantic )

func (Transforms) Do

func (t Transforms) Do(rctx context.Context, mode Mode, code string, nd nodes.Node) (nodes.Node, error)

Do applies AST transformation pipeline for specified AST subtree.

Mode can be specified to stop the pipeline at a specific abstraction level.