parser

Documentation

Overview

Package parser contains a GraphQL parser. Based on GraphQL spec June 2018.

Lexer for Source Text - @spec 2.1

Lex() is a lexer function to convert a given search query into a list of tokens.

Based on a talk by Rob Pike: Lexical Scanning in Go

https://www.youtube.com/watch?v=HxaD_trXwRE

The lexer's output is pushed into a channel which is consumed by the parser. This design enables the concurrent processing of the input text by lexer and parser.

Parser

Parse() is a parser which produces a parse tree from a given set of lexer tokens.

Based on an article by Douglas Crockford: Top Down Operator Precedence

http://crockford.com/javascript/tdop/tdop.html

which is based on the ideas of Vaughan Pratt and his paper: Top Down Operator Precedence

http://portal.acm.org/citation.cfm?id=512931 https://tdop.github.io/

ParseWithRuntime() parses a given input and decorates the resulting parse tree with runtime components which can be used to interpret the parsed query.

Index

• Constants
• Variables
• func Lex(name string, input string) chan LexToken
• func PrettyPrint(ast *ASTNode) (string, error)
• type ASTNode
  • func ASTFromPlain(plainAST map[string]interface{}) (*ASTNode, error)
  • func Parse(name string, input string) (*ASTNode, error)
  • func ParseWithRuntime(name string, input string, rp RuntimeProvider) (*ASTNode, error)
  • func (n *ASTNode) Plain() map[string]interface{}
  • func (n *ASTNode) String() string
• type Error
  • func (pe *Error) Error() string
• type LexToken
  • func LexToList(name string, input string) []LexToken
  • func (t LexToken) PosString() string
  • func (t LexToken) String() string
• type LexTokenID
• type Runtime
• type RuntimeProvider

Constants

const (
	NodeAlias                = "Alias"
	NodeArgument             = "Argument"
	NodeArguments            = "Arguments"
	NodeDefaultValue         = "DefaultValue"
	NodeDirective            = "Directive"
	NodeDirectives           = "Directives"
	NodeDocument             = "Document"
	NodeEnumValue            = "EnumValue"
	NodeEOF                  = "EOF"
	NodeExecutableDefinition = "ExecutableDefinition"
	NodeField                = "Field"
	NodeFragmentDefinition   = "FragmentDefinition"
	NodeFragmentName         = "FragmentName"
	NodeFragmentSpread       = "FragmentSpread"
	NodeInlineFragment       = "InlineFragment"
	NodeListValue            = "ListValue"
	NodeName                 = "Name"
	NodeObjectField          = "ObjectField"
	NodeObjectValue          = "ObjectValue"
	NodeOperationDefinition  = "OperationDefinition"
	NodeOperationType        = "OperationType"
	NodeSelectionSet         = "SelectionSet"
	NodeType                 = "Type"
	NodeTypeCondition        = "TypeCondition"
	NodeValue                = "Value"
	NodeVariable             = "Variable"
	NodeVariableDefinition   = "VariableDefinition"
	NodeVariableDefinitions  = "VariableDefinitions"
)

Available parser AST node types

const IndentationLevel = 2

IndentationLevel is the level of indentation which the pretty printer should use

const RuneComma = ','

RuneComma is the rune for a comma

const RuneEOF = -1

RuneEOF is a special rune which represents the end of the input

Variables

var (
	ErrImpossibleLeftDenotation = errors.New("Term can only start an expression")
	ErrImpossibleNullDenotation = errors.New("Term cannot start an expression")
	ErrLexicalError             = errors.New("Lexical error")
	ErrNameExpected             = errors.New("Name expected")
	ErrOnExpected               = errors.New("Type condition starting with 'on' expected")
	ErrSelectionSetExpected     = errors.New("Selection Set expected")
	ErrMultipleShorthand        = errors.New("Query shorthand only allowed for one query operation")
	ErrUnexpectedEnd            = errors.New("Unexpected end")
	ErrUnexpectedToken          = errors.New("Unexpected term")
	ErrUnknownToken             = errors.New("Unknown term")
	ErrValueOrVariableExpected  = errors.New("Value or variable expected")
	ErrVariableExpected         = errors.New("Variable expected")
)

Parser related error types

var SymbolMap = map[string]LexTokenID{
	"!": TokenPunctuator,
	"$": TokenPunctuator,
	"(": TokenPunctuator,
	")": TokenPunctuator,
	":": TokenPunctuator,
	"=": TokenPunctuator,
	"@": TokenPunctuator,
	"[": TokenPunctuator,
	"]": TokenPunctuator,
	"{": TokenPunctuator,
	"|": TokenPunctuator,
	"}": TokenPunctuator,
}

SymbolMap is a map of special symbols

var ValueNodes = []string{
	NodeAlias,
	NodeDefaultValue,
	NodeEnumValue,
	NodeFragmentName,
	NodeFragmentSpread,
	NodeName,
	NodeObjectField,
	NodeOperationType,
	NodeType,
	NodeTypeCondition,
	NodeValue,
	NodeVariable,
}

ValueNodes are AST nodes which contain a significant value

Functions

func Lex

func Lex(name string, input string) chan LexToken

Lex lexes a given input. Returns a channel which contains tokens.

func PrettyPrint

func PrettyPrint(ast *ASTNode) (string, error)

PrettyPrint produces a pretty printed EQL query from a given AST.

Types

type ASTNode

type ASTNode struct {
	Name     string     // Name of the node
	Token    *LexToken  // Lexer token of this ASTNode
	Children []*ASTNode // Child nodes
	Runtime  Runtime    // Runtime component for this ASTNode
	// contains filtered or unexported fields
}

ASTNode models a node in the AST

func ASTFromPlain

func ASTFromPlain(plainAST map[string]interface{}) (*ASTNode, error)

ASTFromPlain creates an AST from a plain AST. A plain AST is a nested map structure like this:

{
	name     : <name of node>
	value    : <value of node>
	children : [ <child nodes> ]
}

func Parse

func Parse(name string, input string) (*ASTNode, error)

Parse parses a given input string and returns an AST.

func ParseWithRuntime

func ParseWithRuntime(name string, input string, rp RuntimeProvider) (*ASTNode, error)

ParseWithRuntime parses a given input string and returns an AST decorated with runtime components.

func (*ASTNode) Plain

func (n *ASTNode) Plain() map[string]interface{}

Plain returns this ASTNode and all its children as plain AST. A plain AST only contains map objects, lists and primitive types which can be serialized with JSON.

func (*ASTNode) String

func (n *ASTNode) String() string

String returns a string representation of this token.

type Error

type Error struct {
	Source string // Name of the source which was given to the parser
	Type   error  // Error type (to be used for equal checks)
	Detail string // Details of this error
	Line   int    // Line of the error
	Pos    int    // Position of the error
}

Error models a parser related error

func (*Error) Error

func (pe *Error) Error() string

Error returns a human-readable string representation of this error.

type LexToken

type LexToken struct {
	ID    LexTokenID // Token kind
	Pos   int        // Starting position (in runes)
	Val   string     // Token value
	Lline int        // Line in the input this token appears
	Lpos  int        // Position in the input line this token appears
}

LexToken represents a token which is returned by the lexer.

func LexToList

func LexToList(name string, input string) []LexToken

LexToList lexes a given input. Returns a list of tokens.

func (LexToken) PosString

func (t LexToken) PosString() string

PosString returns the position of this token in the origianl input as a string.

func (LexToken) String

func (t LexToken) String() string

String returns a string representation of a token.

type LexTokenID

type LexTokenID int

LexTokenID represents a unique lexer token ID

const (
	TokenError LexTokenID = iota // Lexing error token with a message as val
	TokenEOF                     // End-of-file token

	TokenPunctuator

	TokenName

	TokenIntValue

	TokenFloatValue

	TokenStringValue

	TokenGeneral
)

Available lexer token types

type Runtime

type Runtime interface {

	/*
	   Validate this runtime component and all its child components.
	*/
	Validate() error

	/*
		Eval evaluate this runtime component.
	*/
	Eval() (map[string]interface{}, error)
}

Runtime provides the runtime for an ASTNode.

type RuntimeProvider

type RuntimeProvider interface {

	/*
	   Runtime returns a runtime component for a given ASTNode.
	*/
	Runtime(node *ASTNode) Runtime
}

RuntimeProvider provides runtime components for a parse tree.