driver

Documentation

Overview

Package driver contains all the logic to build a driver.

Index

• Constants
• Variables
• func IsMissingDriver(err error) bool
• func JoinErrors(errs []error) error
• type Driver
• type DriverModule
  • func NewDriverFrom(d Native, m *manifest.Manifest, t Transforms) (DriverModule, error)
• type ErrMissingDriver
  • func (e *ErrMissingDriver) Error() string
• 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)
• type Version

Constants

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

const (
	// ManifestLocation is the path of the manifest file in the driver image.
	ManifestLocation = "/opt/driver/etc/" + manifest.Filename
)

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")

	// ErrLanguageDetection indicates that language was not detected by Enry.
	ErrLanguageDetection = errors.NewKind("could not autodetect language")

	// ErrUnknownEncoding is returned for parse requests with a file content in a non-UTF8 encoding.
	ErrUnknownEncoding = errors.NewKind("unknown source file encoding (expected UTF-8)")
)

Functions

func IsMissingDriver

func IsMissingDriver(err error) bool

IsMissingDriver checks if an error is ErrMissingDriver.

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)

	// Version returns a version of the driver or the server, depending where is this interface is implemented.
	Version(ctx context.Context) (Version, error)

	// Languages returns a list of manifests for languages supported by this driver or the server.
	Languages(ctx context.Context) ([]manifest.Manifest, error)
}

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

type DriverModule

type DriverModule interface {
	Module
	Driver
}

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 ErrMissingDriver

type ErrMissingDriver struct {
	Language string
}

ErrMissingDriver indicates that a driver image for the given language cannot be found.

func (*ErrMissingDriver) Error

func (e *ErrMissingDriver) Error() string

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
}

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.

type Version

type Version struct {
	Version string    // the version label for the driver, e.g., 'v1.2.3-tag' or 'undefined'
	Build   time.Time // the timestamp when the driver was built
}

Version information for driver or the server.