parser

README

docker-parser

A parser for docker commands, based off the moby/buildkit project.

Documentation

Index

• Constants
• Variables
• func BuildEnvs(env []string) map[string]string
• type Command
  • func ParseFile(filename string) ([]Command, error)
  • func ParseReader(file io.Reader) ([]Command, error)
• type Heredoc
  • func MustParseHeredoc(src string) *Heredoc
  • func ParseHeredoc(src string) (*Heredoc, error)
• type Lex
  • func NewLex(escapeToken rune) *Lex
  • func (s *Lex) ProcessWords(word string, env []string) ([]string, error)
• type Node
  • func (node *Node) AddChild(child *Node, startLine, endLine int)
• type Result
  • func Parse(rwc io.Reader) (*Result, error)
  • func (r *Result) PrintWarnings(out io.Writer)

Constants

const (
	Add         = "add"
	Arg         = "arg"
	Cmd         = "cmd"
	Copy        = "copy"
	Entrypoint  = "entrypoint"
	Env         = "env"
	Expose      = "expose"
	From        = "from"
	Healthcheck = "healthcheck"
	Label       = "label"
	Maintainer  = "maintainer"
	Onbuild     = "onbuild"
	Run         = "run"
	Shell       = "shell"
	StopSignal  = "stopsignal"
	User        = "user"
	Volume      = "volume"
	Workdir     = "workdir"
)

Define constants for the command strings

const DefaultEscapeToken = '\\'

DefaultEscapeToken is the default escape token

Variables

var Commands = map[string]struct{}{
	Add:         {},
	Arg:         {},
	Cmd:         {},
	Copy:        {},
	Entrypoint:  {},
	Env:         {},
	Expose:      {},
	From:        {},
	Healthcheck: {},
	Label:       {},
	Maintainer:  {},
	Onbuild:     {},
	Run:         {},
	Shell:       {},
	StopSignal:  {},
	User:        {},
	Volume:      {},
	Workdir:     {},
}

Commands is list of all Dockerfile commands

Functions

func BuildEnvs

func BuildEnvs(env []string) map[string]string

Types

type Command

type Command struct {
	Cmd       string   // lowercased command name (ex: `from`)
	SubCmd    string   // for ONBUILD only this holds the sub-command
	JSON      bool     // whether the value is written in json form
	Original  string   // The original source line
	StartLine int      // The original source line number which starts this command
	EndLine   int      // The original source line number which ends this command
	Flags     []string // Any flags such as `--from=...` for `COPY`.
	Value     []string // The contents of the command (ex: `ubuntu:xenial`)
}

Command stores information about a docker command on a single line

func ParseFile

func ParseFile(filename string) ([]Command, error)

ParseFile parses a Dockerfile from a filename

func ParseReader

func ParseReader(file io.Reader) ([]Command, error)

ParseReader parses a Dockerfile from a reader

type Heredoc

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

func MustParseHeredoc

func MustParseHeredoc(src string) *Heredoc

func ParseHeredoc

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

type Lex

type Lex struct {
	RawQuotes    bool
	RawEscapes   bool
	SkipUnsetEnv bool
	// contains filtered or unexported fields
}

Lex performs shell word splitting and variable expansion.

Lex takes a string and an array of env variables and process all quotes (" and ') as well as $xxx and ${xxx} env variable tokens. Tries to mimic bash shell process. It doesn't support all flavors of ${xx:...} formats but new ones can be added by adding code to the "special ${} format processing" section

func NewLex

func NewLex(escapeToken rune) *Lex

NewLex creates a new Lex which uses escapeToken to escape quotes.

func (*Lex) ProcessWords

func (s *Lex) ProcessWords(word string, env []string) ([]string, error)

ProcessWords will use the 'env' list of environment variables, and replace any env var references in 'word' then it will also return a slice of strings which represents the 'word' split up based on spaces - taking into account quotes. Note that this splitting is done **after** the env var substitutions are done. Note, each one is trimmed to remove leading and trailing spaces (unless they are quoted", but ProcessWord retains spaces between words.

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

type Result

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

Result is the result of parsing a Dockerfile

func Parse

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

Parse reads lines from a Reader, parses the lines into an AST and returns the AST and escape token

func (*Result) PrintWarnings

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

PrintWarnings to the writer