compiler

Documentation

Overview

Package compiler implements parsing, type checking and emitting of sources.

A program can be compiled using

BuildProgram

while a template is compiled through

BuildTemplate

Index

• Constants
• Variables
• func Disassemble(main *runtime.Function, globals []Global, n int) map[string][]byte
• func DisassembleFunction(fn *runtime.Function, globals []Global, n int) []byte
• func ParseProgram(fsys fs.FS) (*ast.Tree, error)
• func ParseTemplate(fsys fs.FS, name string, noParseShow bool) (*ast.Tree, error)
• func ParseTemplateSource(src []byte, format ast.Format, imported, noParseShow bool) (tree *ast.Tree, unexpanded []ast.Node, err error)
• func ValidTemplatePath(path string) bool
• type CheckingError
  • func (e *CheckingError) Error() string
  • func (e *CheckingError) Message() string
  • func (e *CheckingError) Path() string
  • func (e *CheckingError) Position() ast.Position
• type Code
  • func BuildProgram(fsys fs.FS, opts Options) (*Code, error)
  • func BuildTemplate(fsys fs.FS, name string, opts Options) (*Code, error)
• type Converter
• type CycleError
  • func (e *CycleError) Error() string
  • func (e *CycleError) Message() string
  • func (e *CycleError) Path() string
  • func (e *CycleError) Position() ast.Position
• type Error
• type FormatFS
• type Global
• type GoModError
  • func (e *GoModError) Error() string
  • func (e *GoModError) Message() string
  • func (e *GoModError) Path() string
  • func (e *GoModError) Position() ast.Position
• type LimitExceededError
  • func (e *LimitExceededError) Error() string
  • func (e *LimitExceededError) Message() string
  • func (e *LimitExceededError) Path() string
  • func (e *LimitExceededError) Position() ast.Position
• type Options
• type SyntaxError
  • func (e *SyntaxError) Error() string
  • func (e *SyntaxError) Message() string
  • func (e *SyntaxError) Path() string
  • func (e *SyntaxError) Position() ast.Position

Constants

const BOM rune = 0xfeff

BOM contains a Byte Order Mark.

Variables

var (
	ErrNoGoFiles      = errors.New("no Go files")
	ErrTooManyGoFiles = errors.New("too many Go files")
)

Functions

func Disassemble

func Disassemble(main *runtime.Function, globals []Global, n int) map[string][]byte

Disassemble disassembles the main function fn with the given globals, returning the assembly code for each package. The returned map has a package path as key and its assembly as value.

n determines the maximum length, in runes, of the disassembled text in a Text instruction:

n > 0: at most n runes; leading and trailing white space are removed
n == 0: no text
n < 0: all text

func DisassembleFunction

func DisassembleFunction(fn *runtime.Function, globals []Global, n int) []byte

DisassembleFunction disassembles the function fn with the given globals.

n determines the maximum length, in runes, of the disassembled text in a Text instruction:

n > 0: at most n runes; leading and trailing white space are removed
n == 0: no text
n < 0: all text

func ParseProgram

func ParseProgram(fsys fs.FS) (*ast.Tree, error)

ParseProgram parses a program.

func ParseTemplate

func ParseTemplate(fsys fs.FS, name string, noParseShow bool) (*ast.Tree, error)

ParseTemplate parses the named template file rooted at the given file system. If fsys implements FormatFS, the file format is read from its Format method, otherwise it depends on the extension of the file name. Any error related to the compilation itself is returned as a CompilerError.

If noParseShow is true, short show statements are not parsed.

ParseTemplate expands the nodes Extends, Import and Render parsing the relative trees.

func ParseTemplateSource

func ParseTemplateSource(src []byte, format ast.Format, imported, noParseShow bool) (tree *ast.Tree, unexpanded []ast.Node, err error)

ParseTemplateSource parses a template with content src in the given format and returns its tree and the unexpanded Extends, Import, Render and Assignment nodes.

If parseShebang is true, the shebang line is parsed. If noParseShow is true, short show statements are not parsed.

format can be Text, HTML, CSS, JS, JSON and Markdown. imported indicates whether it is imported.

func ValidTemplatePath

func ValidTemplatePath(path string) bool

ValidTemplatePath indicates whether path is a valid template path. A valid template path is a valid file system path but "." is not valid and it can start with '/' or alternatively can start with one o more ".." elements.

Types

type CheckingError

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

CheckingError records a type checking error with the path and the position where the error occurred.

func (*CheckingError) Error

func (e *CheckingError) Error() string

Error returns a string representation of the type checking error.

func (*CheckingError) Message

func (e *CheckingError) Message() string

Message returns the message of the type checking error, without position and path.

func (*CheckingError) Path

func (e *CheckingError) Path() string

Path returns the path of the type checking error.

func (*CheckingError) Position

func (e *CheckingError) Position() ast.Position

Position returns the position of the checking error.

type Code

type Code struct {
	// Globals is a slice of all globals used in Code.
	Globals []Global
	// Functions is a map of exported functions indexed by name.
	Functions map[string]*runtime.Function
	// Main is the Code entry point.
	Main *runtime.Function
	// TypeOf returns the type of a value, including new types defined in code.
	TypeOf runtime.TypeOfFunc
}

Code is the result of a package emitting process.

func BuildProgram

func BuildProgram(fsys fs.FS, opts Options) (*Code, error)

BuildProgram builds a Go program from the package in the root of fsys with the given options, importing the imported packages from packages.

Current limitation: fsys can contain only one Go file in its root.

If a compilation error occurs, it returns a CompilerError error.

func BuildTemplate

func BuildTemplate(fsys fs.FS, name string, opts Options) (*Code, error)

BuildTemplate builds the named template file rooted at the given file system. If fsys implements FormatFS, the file format is read from its Format method, otherwise it depends on the extension of the file name. Any error related to the compilation itself is returned as a CompilerError.

type Converter

type Converter func(src []byte, out io.Writer) error

Converter is implemented by format converters.

type CycleError

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

CycleError implements an error indicating the presence of a cycle.

func (*CycleError) Error

func (e *CycleError) Error() string

func (*CycleError) Message

func (e *CycleError) Message() string

Message returns the message of cycle error, without position and path.

func (*CycleError) Path

func (e *CycleError) Path() string

Path returns the path of the first referenced file in the cycle.

func (*CycleError) Position

func (e *CycleError) Position() ast.Position

Position returns the position of the extends and import declarations or the render expression referring the second file in the cycle.

type Error

type Error interface {
	error
	Position() ast.Position
	Path() string
	Message() string
}

Error represents an error returned by the compiler. The types that implement the Error interface are four types of the compiler package

*GoModError
*SyntaxError
*CycleError
*CheckingError
*LimitExceededError

type FormatFS

type FormatFS interface {
	fs.FS
	Format(name string) (ast.Format, error)
}

FormatFS is the interface implemented by a file system that can determine the file format from a path name.

type Global

type Global struct {
	Pkg   string
	Name  string
	Type  reflect.Type
	Value reflect.Value
}

Global represents a global variable with a package, name, type (only for not predefined globals) and value (only for predefined globals). Value, if present, must be a pointer to the variable value.

type GoModError

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

GoModError represents an error in a go.mod file.

func (*GoModError) Error

func (e *GoModError) Error() string

Error returns a string representing the error.

func (*GoModError) Message

func (e *GoModError) Message() string

Message returns the message of error, without position and path.

func (*GoModError) Path

func (e *GoModError) Path() string

Path returns the path of the go.mod file.

func (*GoModError) Position

func (e *GoModError) Position() ast.Position

Position returns the position of error in the go.mod file.

type LimitExceededError

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

A LimitExceededError is an error returned by the compiler reporting that the compilation has exceeded a limit imposed by the implementation.

func (*LimitExceededError) Error

func (e *LimitExceededError) Error() string

Error implements the interface error for the LimitError.

func (*LimitExceededError) Message

func (e *LimitExceededError) Message() string

Message returns the error message of the LimitError.

func (*LimitExceededError) Path

func (e *LimitExceededError) Path() string

Path returns the path of the source code that caused the LimitError.

func (*LimitExceededError) Position

func (e *LimitExceededError) Position() ast.Position

Position returns the position of the function that caused the LimitError.

type Options

type Options struct {
	AllowGoStmt          bool
	NoParseShortShowStmt bool

	FormatTypes map[ast.Format]reflect.Type
	Globals     native.Declarations

	// Importer imports the native packages.
	Importer native.Importer

	// MDConverter converts a Markdown source code to HTML.
	MDConverter Converter

	TreeTransformer func(*ast.Tree) error
}

Options represents a set of options used during the compilation.

type SyntaxError

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

SyntaxError records a parsing error with the path and the position where the error occurred.

func (*SyntaxError) Error

func (e *SyntaxError) Error() string

Error returns a string representing the syntax error.

func (*SyntaxError) Message

func (e *SyntaxError) Message() string

Message returns the message of the syntax error, without position and path.

func (*SyntaxError) Path

func (e *SyntaxError) Path() string

Path returns the path of the syntax error.

func (*SyntaxError) Position

func (e *SyntaxError) Position() ast.Position

Position returns the position of the syntax error.