parser

Documentation

Overview

The parser package implements a parser that transforms a raw byte-stream into a low-level Abstract Syntax Tree.

Index

• Constants
• func ChompHeredocContent(src string) string
• func SetLocation(err error, location []Range) error
• func WithLocation(err error, location []Range) error
• type Directive
• type DirectiveParser
  • func (d *DirectiveParser) ParseAll(data []byte) ([]*Directive, error)
  • func (d *DirectiveParser) ParseLine(line []byte) (*Directive, error)
• type ErrorLocation
  • func (e *ErrorLocation) Unwrap() error
• type Heredoc
  • func MustParseHeredoc(src string) *Heredoc
  • func ParseHeredoc(src string) (*Heredoc, error)
• type Node
  • func (node *Node) AddChild(child *Node, startLine, endLine int)
  • func (node *Node) Dump() string
  • func (node *Node) Location() []Range
• type Position
• type Range
  • func DetectSyntax(dt []byte) (string, string, []Range, bool)
  • func ParseDirective(key string, dt []byte) (string, string, []Range, bool)
• type Result
  • func Parse(rwc io.Reader) (*Result, error)
  • func (r *Result) PrintWarnings(out io.Writer)
• type Warning

Constants

const DefaultEscapeToken = '\\'

DefaultEscapeToken is the default escape token

Functions

func ChompHeredocContent

func ChompHeredocContent(src string) string

ChompHeredocContent chomps leading tabs from the heredoc.

func SetLocation

func SetLocation(err error, location []Range) error

func WithLocation

func WithLocation(err error, location []Range) error

WithLocation extends an error with a source code location

Types

type Directive

type Directive struct {
	Name     string
	Value    string
	Location []Range
}

type DirectiveParser

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

DirectiveParser is a parser for Dockerfile directives that enforces the quirks of the directive parser.

func (*DirectiveParser) ParseAll

func (d *DirectiveParser) ParseAll(data []byte) ([]*Directive, error)

func (*DirectiveParser) ParseLine

func (d *DirectiveParser) ParseLine(line []byte) (*Directive, error)

type ErrorLocation

type ErrorLocation struct {
	Locations [][]Range
	// contains filtered or unexported fields
}

ErrorLocation gives a location in source code that caused the error

func (*ErrorLocation) Unwrap

func (e *ErrorLocation) Unwrap() error

Unwrap unwraps to the next error

type Heredoc

type Heredoc struct {
	Name           string
	FileDescriptor uint
	Expand         bool
	Chomp          bool
	Content        string
}

func MustParseHeredoc

func MustParseHeredoc(src string) *Heredoc

MustParseHeredoc is a variant of ParseHeredoc that discards the error, if there was one present.

func ParseHeredoc

func ParseHeredoc(src string) (*Heredoc, error)

ParseHeredoc parses a heredoc word from a target string, returning the components from the doc.

type Node

type Node struct {
	Value       string          // actual content
	Next        *Node           // the next item in the current sexp
	Children    []*Node         // the children of this sexp
	Heredocs    []Heredoc       // extra heredoc content attachments
	Attributes  map[string]bool // special attributes for this node
	Original    string          // original line used before parsing
	Flags       []string        // only top Node should have this set
	StartLine   int             // the line in the original dockerfile where the node begins
	EndLine     int             // the line in the original dockerfile where the node ends
	PrevComment []string
}

Node is a structure used to represent a parse tree.

In the node there are three fields, Value, Next, and Children. Value is the current token's string value. Next is always the next non-child token, and children contains all the children. Here's an example:

(value next (child child-next child-next-next) next-next)

This data structure is frankly pretty lousy for handling complex languages, but lucky for us the Dockerfile isn't very complicated. This structure works a little more effectively than a "proper" parse tree for our needs.

func (*Node) AddChild

func (node *Node) AddChild(child *Node, startLine, endLine int)

AddChild adds a new child node, and updates line information

func (*Node) Dump

func (node *Node) Dump() string

Dump dumps the AST defined by `node` as a list of sexps. Returns a string suitable for printing.

func (*Node) Location

func (node *Node) Location() []Range

Location return the location of node in source code

type Position

type Position struct {
	Line      int
	Character int
}

Position is a point in source code

type Range

type Range struct {
	Start Position
	End   Position
}

Range is a code section between two positions

func DetectSyntax

func DetectSyntax(dt []byte) (string, string, []Range, bool)

DetectSyntax returns the syntax of provided input.

The traditional dockerfile directives '# syntax = ...' are used by default, however, the function will also fallback to c-style directives '// syntax = ...' and json-encoded directives '{ "syntax": "..." }'. Finally, starting lines with '#!' are treated as shebangs and ignored.

This allows for a flexible range of input formats, and appropriate syntax selection.

func ParseDirective

func ParseDirective(key string, dt []byte) (string, string, []Range, bool)

type Result

type Result struct {
	AST         *Node
	EscapeToken rune
	Warnings    []Warning
}

Result contains the bundled outputs from parsing a Dockerfile.

func Parse

func Parse(rwc io.Reader) (*Result, error)

Parse consumes lines from a provided Reader, parses each line into an AST and returns the results of doing so.

func (*Result) PrintWarnings

func (r *Result) PrintWarnings(out io.Writer)

PrintWarnings to the writer

type Warning

type Warning struct {
	Short    string
	Detail   [][]byte
	URL      string
	Location *Range
}

Warning contains information to identify and locate a warning generated during parsing.