fig

README

fig

todos/nice to have

• expression evaluation: TBD
• user defined functions inside fig file: TBD

spec

comment

fig has two kind of comments:

• single line comment: a # symbol marks the rest of the line as a comment.
• multiline line comment: everything between /* and */ is a comment. nesting multiline comments is allowed but is not recommended.

types

fig supports the following primitive types:

• string
• literal
• integer
• float
• boolean

options

options are defined as a pair key/value pair separated by a = symbol. Each option is defined on its own line. A line ends with with a \n or, optionally, with a ; symbol followed by \n.

values can be of any of the primitive types defined above and can also be an array of these values.

key = value

an option without value is allowed. if such an option is present in a document, the parser/decoder should choose the more suitable zero-value for this field.

key = # empty value is allowed

repeating multiple times the same key is also allowed. it has as effect to create an option with the given key as identifier and an array as value with the defined values. there is no check on the type of values set in the created array.

key = 1
key = 2
key = true
key = foobar
# is equivalent to
key = [1, 2, true, foobar]

objects

arrays

variables

in fig, variables can take two forms:

• local variables are identifier that reference an option defined in an object at the higher level that the object that used the variable
• environment variables are variable that are defined outside the document and pass to the parser/decoder in order to be available in the document (in its "environment")

example

answer = 42
hitchhiker {
    answer   = $answer # a local variable
    question = @question # an environmnet variable
}

functions

macros

macros are a simple way to modify the parsed document. The supported macros can created new options from an external file, repeated the same objects multiple times, include another fig file into the current one,...

macros in fig are a bit like function called in other programming language. Indeed, some take positional arguments (but can also be defined as keyword arguments), some not. Some macros needs an object (like the body of function), some not.

the following section describes each macros supported currently by fig as well as their arguments.

include

define

apply

extend

repeat

readfile

register

the register macro allows to register a variable that will be given to the decoder.

ifeq

ifneq

ifdef

ifndef

Documentation

Index

• Constants
• Variables
• func Apply(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error
• func Debug(r io.Reader, w io.Writer) error
• func Define(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error
• func Extend(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error
• func IfDef(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error
• func IfEq(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error
• func IfNotDef(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error
• func IfNotEq(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error
• func Include(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error
• func ReadFile(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error
• func Register(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error
• func Repeat(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error
• func Script(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error
• type Argument
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
  • func (d *Decoder) Decode(v interface{}) error
  • func (d *Decoder) Define(ident string, value interface{})
  • func (d *Decoder) Funcs(set FuncMap)
• type Env
  • func EmptyEnv() *Env
  • func EnclosedEnv(parent *Env) *Env
  • func (e *Env) Define(ident string, value interface{})
  • func (e *Env) Resolve(ident string) (interface{}, error)
• type FuncMap
• type Node
  • func Parse(r io.Reader) (Node, error)
  • func ParseWithEnv(r io.Reader, env *Env) (Node, error)
• type NodeType
• type Parser
  • func NewParser(r io.Reader) (*Parser, error)
  • func (p *Parser) Parse() (Node, error)
• type Position
  • func (p Position) String() string
• type Resolver
• type Scanner
  • func Scan(r io.Reader) (*Scanner, error)
  • func (s *Scanner) Scan() Token
• type Setter
• type Token
  • func (t Token) Equal(other Token) bool
  • func (t Token) String() string
• type Updater

Constants

const (
	EOF rune = -(iota + 1)
	Ident
	Comment
	Macro
	Boolean
	Heredoc
	String
	Template
	Integer
	Float
	LocalVar
	EnvVar
	BegArr
	EndArr
	BegObj
	EndObj
	BegGrp
	EndGrp
	Comma
	Slice
	Assign
	EOL
	Invalid
)

Variables

var (
	ErrUnexpected = errors.New("unexpected token")
	ErrSyntax     = errors.New("syntax error")
	ErrAllow      = errors.New("not allowed")
)

Functions

func Apply

func Apply(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error

func Debug

func Debug(r io.Reader, w io.Writer) error

func Define

func Define(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error

func Extend

func Extend(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error

func IfDef

func IfDef(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error

func IfEq

func IfEq(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error

func IfNotDef

func IfNotDef(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error

func IfNotEq

func IfNotEq(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error

func Include

func Include(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error

func ReadFile

func ReadFile(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error

func Register

func Register(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error

func Repeat

func Repeat(root, nest Node, env *Env, args []Node, kwargs map[string]Node) error

func Script

func Script(root, _ Node, env *Env, args []Node, kwargs map[string]Node) error

Types

type Argument

type Argument interface {
	GetString() (string, error)
	GetFloat() (float64, error)
	GetInt() (int64, error)
	GetUint() (uint64, error)
	GetBool() (bool, error)
}

type Decoder

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

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

func (*Decoder) Decode

func (d *Decoder) Decode(v interface{}) error

func (*Decoder) Define

func (d *Decoder) Define(ident string, value interface{})

func (*Decoder) Funcs

func (d *Decoder) Funcs(set FuncMap)

type Env

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

func EmptyEnv

func EmptyEnv() *Env

func EnclosedEnv

func EnclosedEnv(parent *Env) *Env

func (*Env) Define

func (e *Env) Define(ident string, value interface{})

func (*Env) Resolve

func (e *Env) Resolve(ident string) (interface{}, error)

type FuncMap

type FuncMap map[string]interface{}

type Node

type Node interface {
	fmt.Stringer
	Type() NodeType
	// contains filtered or unexported methods
}

func Parse

func Parse(r io.Reader) (Node, error)

func ParseWithEnv

func ParseWithEnv(r io.Reader, env *Env) (Node, error)

type NodeType

type NodeType int8

const (
	TypeLiteral NodeType = iota
	TypeTemplate
	TypeVariable
	TypeSlice
	TypeOption
	TypeArray
	TypeObject
	TypeEqual
	TypeCall
)

type Parser

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

func NewParser

func NewParser(r io.Reader) (*Parser, error)

func (*Parser) Parse

func (p *Parser) Parse() (Node, error)

type Position

type Position struct {
	Line int
	Col  int
}

func (Position) String

func (p Position) String() string

type Resolver

type Resolver interface {
	Resolve(string) (interface{}, error)
}

type Scanner

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

func Scan

func Scan(r io.Reader) (*Scanner, error)

func (*Scanner) Scan

func (s *Scanner) Scan() Token

type Setter

type Setter interface {
	Set(string) error
}

type Token

type Token struct {
	Literal     string
	Type        rune
	Interpolate bool
	Position
}

func (Token) Equal

func (t Token) Equal(other Token) bool

func (Token) String

func (t Token) String() string

type Updater

type Updater interface {
	Update(Resolver) error
}