ast

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 1, 2016 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package ast declares Rego syntax tree types and also includes a parser and compiler for preparing policies for execution in the policy engine.

Rego policies are defined using a relatively small set of types: modules, package and import declarations, rules, expressions, and terms. At their core, policies consist of rules that are defined by one or more expressions over documents available to the policy engine. The expressions are defined by intrinsic values (terms) such as strings, objects, variables, etc.

Rego policies are typically defined in text files and then parsed and compiled by the policy engine at runtime. The parsing stage takes the text or string representation of the policy and converts it into an abstract syntax tree (AST) that consists of the types mentioned above. The AST is organized as follows:

Module
 |
 +--- Package (Reference)
 |
 +--- Imports
 |     |
 |     +--- Import (Term)
 |
 +--- Rules
       |
       +--- Rule
             |
             +--- Head
             |     |
             |     +--- Name (Variable)
             |     |
             |     +--- Key (Term)
             |     |
             |     +--- Value (Term)
             |
             +--- Body
                   |
                   +--- Expression (Term | Terms)

At query time, the policy engine expects policies to have been compiled. The compilation stage takes one or more modules and compiles them into a format that the policy engine supports.

Index

Examples

Constants

View Source
const (
	// ParseErr indicates an unclassified parse error occurred.
	ParseErr = iota

	// CompileErr indicates an unclassified compile error occurred.
	CompileErr = iota

	// UnsafeVarErr indicates an unsafe variable was found during compilation.
	UnsafeVarErr = iota

	// RecursionErr indicates recursion was found during compilation.
	RecursionErr = iota
)
View Source
const (
	// CompleteDoc represents a document that is completely defined by the rule.
	CompleteDoc = iota

	// PartialSetDoc represents a set document that is partially defined by the rule.
	PartialSetDoc = iota

	// PartialObjectDoc represents an object document that is partially defined by the rule.
	PartialObjectDoc = iota
)

Variables

View Source
var Abs = &Builtin{
	Name:      Var("abs"),
	NumArgs:   2,
	TargetPos: []int{1},
}

Abs returns the number without its sign.

View Source
var BuiltinMap map[Var]*Builtin

BuiltinMap provides a convenient mapping of built-in names to built-in definitions.

View Source
var Builtins []*Builtin

Builtins is the registry of built-in functions supported by OPA. Call RegisterBuiltin to add a new built-in.

View Source
var Concat = &Builtin{
	Name:      Var("concat"),
	NumArgs:   3,
	TargetPos: []int{2},
}

Concat joins an array of strings to with an input string.

View Source
var Contains = &Builtin{
	Name:    Var("contains"),
	NumArgs: 2,
}

Contains returns true if the search string is included in the base string

View Source
var Count = &Builtin{
	Name:      Var("count"),
	NumArgs:   2,
	TargetPos: []int{1},
}

Count takes a collection and counts the number of elements in it.

DefaultBuiltins is the registry of built-in functions supported in OPA by default. When adding a new built-in function to OPA, update this list.

View Source
var DefaultRootDocument = VarTerm("data")

DefaultRootDocument is the default root document.

All package directives inside source files are implicitly prefixed with the DefaultRootDocument value.

View Source
var DefaultRootRef = Ref{DefaultRootDocument}

DefaultRootRef is a reference to the root of the default document.

All refs to data in the policy engine's storage layer are prefixed with this ref.

View Source
var Divide = &Builtin{
	Name:      Var("div"),
	NumArgs:   3,
	TargetPos: []int{2},
}

Divide divides the first number by the second number.

View Source
var EndsWith = &Builtin{
	Name:    Var("endswith"),
	NumArgs: 2,
}

EndsWith returns true if the search string begins with the base string

View Source
var Equality = &Builtin{
	Name:      Var("eq"),
	Infix:     Var("="),
	NumArgs:   2,
	TargetPos: []int{0, 1},
}

Equality represents the "=" operator.

View Source
var FormatInt = &Builtin{
	Name:      Var("format_int"),
	NumArgs:   3,
	TargetPos: []int{2},
}

FormatInt returns the string representation of the number in the given base after converting it to an integer value.

View Source
var GreaterThan = &Builtin{
	Name:    Var("gt"),
	Infix:   Var(">"),
	NumArgs: 2,
}

GreaterThan represents the ">" comparison operator.

View Source
var GreaterThanEq = &Builtin{
	Name:    Var("gte"),
	Infix:   Var(">="),
	NumArgs: 2,
}

GreaterThanEq represents the ">=" comparison operator.

View Source
var IndexOf = &Builtin{
	Name:      Var("indexof"),
	NumArgs:   3,
	TargetPos: []int{2},
}

IndexOf returns the index of a substring contained inside a string

View Source
var Keywords = [...]string{
	"not",
	"package",
	"import",
	"null",
	"true",
	"false",
}

Keywords contains strings that map to language keywords.

View Source
var LessThan = &Builtin{
	Name:    Var("lt"),
	Infix:   Var("<"),
	NumArgs: 2,
}

LessThan represents the "<" comparison operator.

View Source
var LessThanEq = &Builtin{
	Name:    Var("lte"),
	Infix:   Var("<="),
	NumArgs: 2,
}

LessThanEq represents the "<=" comparison operator.

View Source
var Lower = &Builtin{
	Name:      Var("lower"),
	NumArgs:   2,
	TargetPos: []int{1},
}

Lower returns the input string but with all characters in lower-case

View Source
var Max = &Builtin{
	Name:      Var("max"),
	NumArgs:   2,
	TargetPos: []int{1},
}

Max returns the maximum value in a collection.

View Source
var Minus = &Builtin{
	Name:      Var("minus"),
	NumArgs:   3,
	TargetPos: []int{2},
}

Minus subtracts the second number from the first number.

View Source
var Multiply = &Builtin{
	Name:      Var("mul"),
	NumArgs:   3,
	TargetPos: []int{2},
}

Multiply multiplies two numbers together.

View Source
var NotEqual = &Builtin{
	Name:    Var("neq"),
	Infix:   Var("!="),
	NumArgs: 2,
}

NotEqual represents the "!=" comparison operator.

View Source
var Plus = &Builtin{
	Name:      Var("plus"),
	NumArgs:   3,
	TargetPos: []int{2},
}

Plus adds two numbers together.

View Source
var RegexMatch = &Builtin{
	Name:    Var("re_match"),
	NumArgs: 2,
}

RegexMatch takes two strings and evaluates to true if the string in the second position matches the pattern in the first position.

View Source
var ReservedVars = NewVarSet(DefaultRootDocument.Value.(Var))

ReservedVars is the set of reserved variable names.

View Source
var Round = &Builtin{
	Name:      Var("round"),
	NumArgs:   2,
	TargetPos: []int{1},
}

Round rounds the number up to the nearest integer.

View Source
var SetDiff = &Builtin{
	Name:      Var("set_diff"),
	NumArgs:   3,
	TargetPos: []int{2},
}

SetDiff returns the difference between two sets. The difference is all of the elements in the first set that are not in the second set.

View Source
var StartsWith = &Builtin{
	Name:    Var("startswith"),
	NumArgs: 2,
}

StartsWith returns true if the search string begins with the base string

View Source
var Substring = &Builtin{
	Name:      Var("substring"),
	NumArgs:   4,
	TargetPos: []int{3},
}

Substring returns the portion of a string for a given start index and a length.

If the length is less than zero, then substring returns the remainder of the string.
View Source
var Sum = &Builtin{
	Name:      Var("sum"),
	NumArgs:   2,
	TargetPos: []int{1},
}

Sum takes an array of numbers and sums them.

View Source
var ToNumber = &Builtin{
	Name:      Var("to_number"),
	NumArgs:   2,
	TargetPos: []int{1},
}

ToNumber takes a string, bool, or number value and converts it to a number. Strings are converted to numbers using strconv.Atoi. Boolean false is converted to 0 and boolean true is converted to 1.

View Source
var Upper = &Builtin{
	Name:      Var("upper"),
	NumArgs:   2,
	TargetPos: []int{1},
}

Upper returns the input string but with all characters in upper-case

View Source
var Wildcard = &Term{Value: Var("_")}

Wildcard represents the wildcard variable as defined in the language.

View Source
var WildcardPrefix = "$"

WildcardPrefix is the special character that all wildcard variables are prefixed with when the statement they are contained in is parsed.

Functions

func Compare added in v0.2.0

func Compare(a, b interface{}) int

Compare returns an integer indicating whether two AST values are less than, equal to, or greater than each other.

If a is less than b, the return value is negative. If a is greater than b, the return value is positive. If a is equal to b, the return value is zero.

Different types are never equal to each other. For comparison purposes, types are sorted as follows:

nil < Null < Boolean < Number < String < Var < Ref < Array < Object < Set < ArrayComprehension < Expr < Body < Rule < Import < Package < Module.

Arrays and Refs are equal iff both a and b have the same length and all corresponding elements are equal. If one element is not equal, the return value is the same as for the first differing element. If all elements are equal but a and b have different lengths, the shorter is considered less than the other.

Objects are considered equal iff both a and b have the same sorted (key, value) pairs and are of the same length. Other comparisons are consistent but not defined.

Sets are considered equal iff the symmetric difference of a and b is empty. Other comparisons are consistent but not defined.

func IsKeyword added in v0.2.2

func IsKeyword(s string) bool

IsKeyword returns true if s is a language keyword.

func IsScalar added in v0.2.0

func IsScalar(v Value) bool

IsScalar returns true if the AST value is a scalar.

func MustParseStatement

func MustParseStatement(input string) interface{}

MustParseStatement returns exactly one statement. If an error occurs during parsing, panic.

func MustParseStatements

func MustParseStatements(input string) []interface{}

MustParseStatements returns a slice of parsed statements. If an error occurs during parsing, panic.

func Parse

func Parse(filename string, b []byte, opts ...Option) (interface{}, error)

Parse parses the data from b using filename as information in the error messages.

func ParseFile

func ParseFile(filename string, opts ...Option) (interface{}, error)

ParseFile parses the file identified by filename.

func ParseReader

func ParseReader(filename string, r io.Reader, opts ...Option) (interface{}, error)

ParseReader parses the data from r using filename as information in the error messages.

func ParseStatement

func ParseStatement(input string) (interface{}, error)

ParseStatement returns exactly one statement. A statement might be a term, expression, rule, etc. Regardless, this function expects *exactly* one statement. If multiple statements are parsed, an error is returned.

func ParseStatements

func ParseStatements(filename, input string) ([]interface{}, error)

ParseStatements returns a slice of parsed statements. This is the default return value from the parser.

func RegisterBuiltin

func RegisterBuiltin(b *Builtin)

RegisterBuiltin adds a new built-in function to the registry.

func Transform added in v0.2.0

func Transform(t Transformer, x interface{}) (interface{}, error)

Transform iterates the AST and calls the Transform function on the Transformer t for x before recursing.

func TransformRefs added in v0.2.0

func TransformRefs(x interface{}, f func(Ref) (Value, error)) (interface{}, error)

TransformRefs calls the function f on all references under x.

func Walk

func Walk(v Visitor, x interface{})

Walk iterates the AST by calling the Visit function on the Visitor v for x before recursing.

func WalkBodies added in v0.2.0

func WalkBodies(x interface{}, f func(Body) bool)

WalkBodies calls the function f on all bodies under x. If the function f returns true, AST nodes under the last node will not be visited.

func WalkClosures

func WalkClosures(x interface{}, f func(interface{}) bool)

WalkClosures calls the function f on all closures under x. If the function f returns true, AST nodes under the last node will not be visited.

func WalkRefs

func WalkRefs(x interface{}, f func(Ref) bool)

WalkRefs calls the function f on all references under x. If the function f returns true, AST nodes under the last node will not be visited.

func WalkVars added in v0.2.1

func WalkVars(x interface{}, f func(Var) bool)

WalkVars calls the function f on all vars under x. If the function f returns true, AST nodes under the last node will not be visited.

Types

type Array

type Array []*Term

Array represents an array as defined by the language. Arrays are similar to the same types as defined by JSON with the exception that they can contain Vars and References.

func (Array) Copy added in v0.2.2

func (arr Array) Copy() Array

Copy returns a deep copy of arr.

func (Array) Equal

func (arr Array) Equal(other Value) bool

Equal returns true if arr is equal to other.

func (Array) Hash

func (arr Array) Hash() int

Hash returns the hash code for the Value.

func (Array) IsGround

func (arr Array) IsGround() bool

IsGround returns true if all of the Array elements are ground.

func (Array) String

func (arr Array) String() string

type ArrayComprehension

type ArrayComprehension struct {
	Term *Term
	Body Body
}

ArrayComprehension represents an array comprehension as defined in the language.

func (*ArrayComprehension) Copy added in v0.2.2

Copy returns a deep copy of ac.

func (*ArrayComprehension) Equal

func (ac *ArrayComprehension) Equal(other Value) bool

Equal returns true if ac is equal to other.

func (*ArrayComprehension) Hash

func (ac *ArrayComprehension) Hash() int

Hash returns the hash code of the Value.

func (*ArrayComprehension) IsGround

func (ac *ArrayComprehension) IsGround() bool

IsGround returns true if the Term and Body are ground.

func (*ArrayComprehension) String

func (ac *ArrayComprehension) String() string

type Body

type Body []*Expr

Body represents one or more expressios contained inside a rule.

func MustParseBody

func MustParseBody(input string) Body

MustParseBody returns a parsed body. If an error occurs during parsing, panic.

func NewBody added in v0.2.0

func NewBody(exprs ...*Expr) Body

NewBody returns a new Body containing the given expressions. The indices of the immediate expressions will be reset.

func ParseBody

func ParseBody(input string) (Body, error)

ParseBody returns exactly one body. If multiple bodies are parsed, an error is returned.

func (Body) Compare added in v0.2.0

func (body Body) Compare(other Body) int

Compare returns an integer indicating whether body is less than, equal to, or greater than other.

If body is a subset of other, it is considered less than (and vice versa).

func (Body) Contains

func (body Body) Contains(x *Expr) bool

Contains returns true if this body contains the given expression.

func (Body) Copy added in v0.2.2

func (body Body) Copy() Body

Copy returns a deep copy of body.

func (Body) Equal

func (body Body) Equal(other Body) bool

Equal returns true if this Body is equal to the other Body.

func (Body) Hash

func (body Body) Hash() int

Hash returns the hash code for the Body.

func (Body) IsGround

func (body Body) IsGround() bool

IsGround returns true if all of the expressions in the Body are ground.

func (Body) Loc

func (body Body) Loc() *Location

Loc returns the location of the Body in the definition.

func (Body) OutputVars

func (body Body) OutputVars(safe VarSet) VarSet

OutputVars returns a VarSet containing the variables that would be bound by evaluating the body.

func (Body) String

func (body Body) String() string

func (Body) Vars

func (body Body) Vars(skipClosures bool) VarSet

Vars returns a VarSet containing all of the variables in the body. If skipClosures is true, variables contained inside closures within the body will be ignored.

type Boolean

type Boolean bool

Boolean represents a boolean value defined by JSON.

func (Boolean) Equal

func (bol Boolean) Equal(other Value) bool

Equal returns true if the other Value is a Boolean and is equal.

func (Boolean) Hash

func (bol Boolean) Hash() int

Hash returns the hash code for the Value.

func (Boolean) IsGround

func (bol Boolean) IsGround() bool

IsGround always returns true.

func (Boolean) String

func (bol Boolean) String() string

type Builtin

type Builtin struct {
	Name      Var   // Unique name of built-in function, e.g., <Name>(term,term,...,term)
	Infix     Var   // Unique name of infix operator. Default should be unset.
	NumArgs   int   // Total number of args required by built-in.
	TargetPos []int // Argument positions that bind outputs. Indexing is zero-based.
}

Builtin represents a built-in function supported by OPA. Every built-in function is uniquely identified by a name.

func (*Builtin) Expr

func (b *Builtin) Expr(terms ...*Term) *Expr

Expr creates a new expression for the built-in with the given terms.

func (*Builtin) IsTargetPos

func (b *Builtin) IsTargetPos(i int) bool

IsTargetPos returns true if a variable in the i-th position will be bound when the expression is evaluated.

type Compiler

type Compiler struct {

	// Errors contains errors that occurred during the compilation process.
	// If there are one or more errors, the compilation process is considered
	// "failed".
	Errors Errors

	// Modules contains the compiled modules. The compiled modules are the
	// output of the compilation process. If the compilation process failed,
	// there is no guarantee about the state of the modules.
	Modules map[string]*Module

	// ModuleTree organizes the modules into a tree where each node is keyed
	// by an element in the module's package path. E.g., given modules containg
	// the following package directives: "a", "a.b", "a.c", and "a.b", the
	// resulting module tree would be:
	//
	//  root
	//    |
	//    +--- data (no modules)
	//           |
	//           +--- a (1 module)
	//                |
	//                +--- b (2 modules)
	//                |
	//                +--- c (1 module)
	//
	ModuleTree *ModuleTreeNode

	// RuleTree organizes rules into a tree where each node is keyed by an
	// element in the rule's path. The rule path is the concatenation of the
	// containing package and the stringified rule name. E.g., given the following module:
	//
	//  package ex
	//  p[1] :- true
	//  p[2] :- true
	//  q :- true
	//
	//  root
	//    |
	//    +--- data (no rules)
	//           |
	//           +--- ex (no rules)
	//                |
	//                +--- p (2 rules)
	//                |
	//                +--- q (1 rule)
	RuleTree *RuleTreeNode

	// RuleGraph represents the rule dependencies.
	// An edge (u, v) is added to the graph if rule "u" depends on rule "v".
	// A rule depends on another rule if it refers to it.
	RuleGraph map[*Rule]map[*Rule]struct{}
	// contains filtered or unexported fields
}

Compiler contains the state of a compilation process.

func NewCompiler

func NewCompiler() *Compiler

NewCompiler returns a new empty compiler.

func (*Compiler) Compile

func (c *Compiler) Compile(modules map[string]*Module)

Compile runs the compilation process on the input modules. The compiled version of the modules and associated data structures are stored on the compiler. If the compilation process fails for any reason, the compiler will contain a slice of errors.

Example
package main

import (
	"fmt"

	"github.com/open-policy-agent/opa/ast"
)

func main() {

	// Define an input module that will be compiled.
	exampleModule := `

		package opa.example

		import data.foo
		import bar

		p[x] :- foo[x], not bar[x], x >= min_x

		min_x = 100

	`

	// Parse the input module to obtain the AST representation.
	mod, err := ast.ParseModule("my_module", exampleModule)
	if err != nil {
		fmt.Println("Parse error:", err)
	}

	// Create a new compiler instance and compile the module.
	c := ast.NewCompiler()

	mods := map[string]*ast.Module{
		"my_module": mod,
	}

	if c.Compile(mods); c.Failed() {
		fmt.Println("Compile error:", c.Errors)
	}

	fmt.Println("Expr 1:", c.Modules["my_module"].Rules[0].Body[0])
	fmt.Println("Expr 2:", c.Modules["my_module"].Rules[0].Body[1])
	fmt.Println("Expr 3:", c.Modules["my_module"].Rules[0].Body[2])

}
Output:


Expr 1: data.foo[x]
Expr 2: not bar[x]
Expr 3: gte(x, data.opa.example.min_x)

func (*Compiler) Failed

func (c *Compiler) Failed() bool

Failed returns true if a compilation error has been encountered.

func (*Compiler) GetRulesExact added in v0.2.0

func (c *Compiler) GetRulesExact(ref Ref) (rules []*Rule)

GetRulesExact returns a slice of rules referred to by the reference.

E.g., given the following module:

	package a.b.c

	p[k] = v :- ...    # rule1
 p[k1] = v1 :- ...  # rule2

The following calls yield the rules on the right.

GetRulesExact("data.a.b.c.p")   => [rule1, rule2]
GetRulesExact("data.a.b.c.p.x") => nil
GetRulesExact("data.a.b.c")     => nil

func (*Compiler) GetRulesForVirtualDocument added in v0.2.0

func (c *Compiler) GetRulesForVirtualDocument(ref Ref) (rules []*Rule)

GetRulesForVirtualDocument returns a slice of rules that produce the virtual document referred to by the reference.

E.g., given the following module:

	package a.b.c

	p[k] = v :- ...    # rule1
 p[k1] = v1 :- ...  # rule2

The following calls yield the rules on the right.

GetRulesForVirtualDocument("data.a.b.c.p")   => [rule1, rule2]
GetRulesForVirtualDocument("data.a.b.c.p.x") => [rule1, rule2]
GetRulesForVirtualDocument("data.a.b.c")     => nil

func (*Compiler) GetRulesWithPrefix added in v0.2.0

func (c *Compiler) GetRulesWithPrefix(ref Ref) (rules []*Rule)

GetRulesWithPrefix returns a slice of rules that share the prefix ref.

E.g., given the following module:

package a.b.c

p[x] = y :- ...  # rule1
p[k] = v :- ...  # rule2
q :- ...         # rule3

The following calls yield the rules on the right.

GetRulesWithPrefix("data.a.b.c.p")   => [rule1, rule2]
GetRulesWithPrefix("data.a.b.c.p.a") => nil
GetRulesWithPrefix("data.a.b.c")     => [rule1, rule2, rule3]

func (*Compiler) QueryCompiler added in v0.2.2

func (c *Compiler) QueryCompiler() QueryCompiler

QueryCompiler returns a new QueryCompiler object.

type DocKind

type DocKind int

DocKind represents the collection of document types that can be produced by rules.

type ErrCode added in v0.2.0

type ErrCode int

ErrCode defines the types of errors returned during parsing, compiling, etc.

type Error added in v0.2.0

type Error struct {
	Code     ErrCode
	Location *Location
	Message  string
}

Error represents a single error caught during parsing, compiling, etc.

func NewError added in v0.2.0

func NewError(code ErrCode, loc *Location, f string, a ...interface{}) *Error

NewError returns a new Error object.

func (*Error) Error added in v0.2.0

func (e *Error) Error() string

type Errors added in v0.2.0

type Errors []*Error

Errors represents a series of errors encountered during parsing, compiling, etc.

func (Errors) Error added in v0.2.0

func (e Errors) Error() string

type Expr

type Expr struct {
	Location *Location `json:"-"`
	Index    int
	Negated  bool `json:",omitempty"`
	Terms    interface{}
}

Expr represents a single expression contained inside the body of a rule.

func MustParseExpr added in v0.2.0

func MustParseExpr(input string) *Expr

MustParseExpr returns a parsed expression. If an error occurs during parsing, panic.

func NewBuiltinExpr

func NewBuiltinExpr(terms ...*Term) *Expr

NewBuiltinExpr creates a new Expr object with the supplied terms. The builtin operator must be the first term.

func NewExpr added in v0.2.1

func NewExpr(terms interface{}) *Expr

NewExpr returns a new Expr object.

func ParseExpr added in v0.2.0

func ParseExpr(input string) (*Expr, error)

ParseExpr returns exactly one expression. If multiple expressions are parsed, an error is returned.

func (*Expr) Compare added in v0.2.0

func (expr *Expr) Compare(other *Expr) int

Compare returns an integer indicating whether expr is less than, equal to, or greater than other.

Expressions are compared as follows:

1. Negated expressions are always greater than than non-negated expressions. 2. Preceding expression (by Index) is always less than the other expression. 3. Single term expressions are always less than built-in expressions.

Otherwise, the expression terms are compared normally.

func (*Expr) Complement

func (expr *Expr) Complement() *Expr

Complement returns a copy of this expression with the negation flag flipped.

func (*Expr) Copy added in v0.2.2

func (expr *Expr) Copy() *Expr

Copy returns a deep copy of expr.

func (*Expr) Equal

func (expr *Expr) Equal(other *Expr) bool

Equal returns true if this Expr equals the other Expr.

func (*Expr) Hash

func (expr *Expr) Hash() int

Hash returns the hash code of the Expr.

func (*Expr) IsEquality

func (expr *Expr) IsEquality() bool

IsEquality returns true if this is an equality expression.

func (*Expr) IsGround

func (expr *Expr) IsGround() bool

IsGround returns true if all of the expression terms are ground.

func (*Expr) OutputVars

func (expr *Expr) OutputVars(safe VarSet) VarSet

OutputVars returns a VarSet containing variables that would be bound by evaluating this expression.

func (*Expr) String

func (expr *Expr) String() string

func (*Expr) UnmarshalJSON

func (expr *Expr) UnmarshalJSON(bs []byte) error

UnmarshalJSON parses the byte array and stores the result in expr.

func (*Expr) Vars

func (expr *Expr) Vars(skipClosures bool) VarSet

Vars returns a VarSet containing all of the variables in the expression. If skipClosures is true then variables contained inside closures within this expression will not be included in the VarSet.

type GenericTransformer added in v0.2.0

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

GenericTransformer implements the Transformer interface to provide a utility to transform AST nodes using a closure.

func (*GenericTransformer) Transform added in v0.2.0

func (t *GenericTransformer) Transform(x interface{}) (interface{}, error)

Transform calls the function f on the GenericTransformer.

type GenericVisitor

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

GenericVisitor implements the Visitor interface to provide a utility to walk over AST nodes using a closure. If the closure returns true, the visitor will not walk over AST nodes under x.

func (*GenericVisitor) Visit

func (vis *GenericVisitor) Visit(x interface{}) Visitor

Visit calls the function f on the GenericVisitor.

type Head struct {
	Name  Var
	Key   *Term
	Value *Term
}

Head represents the head of a rule. TODO(tsandall): refactor Rule to contain a Head.

func (*Head) String added in v0.2.0

func (head *Head) String() string

type Import

type Import struct {
	Location *Location `json:"-"`
	Path     *Term
	Alias    Var `json:",omitempty"`
}

Import represents a dependency on a document outside of the policy namespace. Imports are optional.

func MustParseImports added in v0.2.2

func MustParseImports(input string) []*Import

MustParseImports returns a slice of imports. If an error occurs during parsing, panic.

func ParseImports added in v0.2.2

func ParseImports(input string) ([]*Import, error)

ParseImports returns a slice of Import objects.

func (*Import) Compare added in v0.2.0

func (imp *Import) Compare(other *Import) int

Compare returns an integer indicating whether imp is less than, equal to, or greater than other.

func (*Import) Copy added in v0.2.2

func (imp *Import) Copy() *Import

Copy returns a deep copy of imp.

func (*Import) Equal

func (imp *Import) Equal(other *Import) bool

Equal returns true if imp is equal to other.

func (*Import) Loc

func (imp *Import) Loc() *Location

Loc returns the location of the Import in the definition.

func (*Import) Name added in v0.2.2

func (imp *Import) Name() Var

Name returns the variable that is used to refer to the imported virtual document. This is the alias if defined otherwise the last element in the path.

func (*Import) String

func (imp *Import) String() string

type Location

type Location struct {
	Text []byte `json:"-"` // The original text fragment from the source.
	File string // The name of the source file (which may be empty).
	Row  int    // The line in the source.
	Col  int    // The column in the row.
}

Location records a position in source code

func NewLocation

func NewLocation(text []byte, file string, row int, col int) *Location

NewLocation returns a new Location object.

func (*Location) Errorf

func (loc *Location) Errorf(f string, a ...interface{}) error

Errorf returns a new error value with a message formatted to include the location info (e.g., line, column, filename, etc.)

func (*Location) Format added in v0.2.0

func (loc *Location) Format(f string, a ...interface{}) string

Format returns a formatted string prefixed with the location information.

func (*Location) String added in v0.2.2

func (loc *Location) String() string

func (*Location) Wrapf

func (loc *Location) Wrapf(err error, f string, a ...interface{}) error

Wrapf returns a new error value that wraps an existing error with a message formatted to include the location info (e.g., line, column, filename, etc.)

type Module

type Module struct {
	Package *Package
	Imports []*Import
	Rules   []*Rule
}

Module represents a collection of policies (defined by rules) within a namespace (defined by the package) and optional dependencies on external documents (defined by imports).

func MustParseModule

func MustParseModule(input string) *Module

MustParseModule returns a parsed module. If an error occurs during parsing, panic.

func ParseModule

func ParseModule(filename, input string) (*Module, error)

ParseModule returns a parsed Module object. For details on Module objects and their fields, see policy.go. Empty input will return nil, nil.

func (*Module) Compare added in v0.2.0

func (mod *Module) Compare(other *Module) int

Compare returns an integer indicating whether mod is less than, equal to, or greater than other.

func (*Module) Copy added in v0.2.2

func (mod *Module) Copy() *Module

Copy returns a deep copy of mod.

func (*Module) Equal

func (mod *Module) Equal(other *Module) bool

Equal returns true if mod equals other.

func (*Module) String added in v0.2.0

func (mod *Module) String() string

type ModuleTreeNode

type ModuleTreeNode struct {
	Key      Value
	Modules  []*Module
	Children map[Value]*ModuleTreeNode
}

ModuleTreeNode represents a node in the module tree. The module tree is keyed by the package path.

func NewModuleTree

func NewModuleTree(mods map[string]*Module) *ModuleTreeNode

NewModuleTree returns a new ModuleTreeNode that represents the root of the module tree populated with the given modules.

func (*ModuleTreeNode) DepthFirst added in v0.2.2

func (n *ModuleTreeNode) DepthFirst(f func(node *ModuleTreeNode) bool)

DepthFirst performs a depth-first traversal of the module tree rooted at n. If f returns true, traversal will not continue to the children of n.

func (*ModuleTreeNode) Size

func (n *ModuleTreeNode) Size() int

Size returns the number of modules in the tree.

type Null

type Null struct{}

Null represents the null value defined by JSON.

func (Null) Equal

func (null Null) Equal(other Value) bool

Equal returns true if the other term Value is also Null.

func (Null) Hash

func (null Null) Hash() int

Hash returns the hash code for the Value.

func (Null) IsGround

func (null Null) IsGround() bool

IsGround always returns true.

func (Null) String

func (null Null) String() string

type Number

type Number float64

Number represents a numeric value as defined by JSON.

func (Number) Equal

func (num Number) Equal(other Value) bool

Equal returns true if the other Value is a Number and is equal.

func (Number) Hash

func (num Number) Hash() int

Hash returns the hash code for the Value.

func (Number) IsGround

func (num Number) IsGround() bool

IsGround always returns true.

func (Number) String

func (num Number) String() string

type Object

type Object [][2]*Term

Object represents an object as defined by the language. Objects are similar to the same types as defined by JSON with the exception that they can contain Vars and References.

func (Object) Copy added in v0.2.2

func (obj Object) Copy() Object

Copy returns a deep copy of obj.

func (Object) Diff

func (obj Object) Diff(other Object) Object

Diff returns a new Object that contains only the key/value pairs that exist in obj.

func (Object) Equal

func (obj Object) Equal(other Value) bool

Equal returns true if obj is equal to other.

func (Object) Get added in v0.2.0

func (obj Object) Get(k *Term) *Term

Get returns the value of k in obj if k exists, otherwise nil.

func (Object) Hash

func (obj Object) Hash() int

Hash returns the hash code for the Value.

func (Object) Intersect

func (obj Object) Intersect(other Object) [][3]*Term

Intersect returns a slice of term triplets that represent the intersection of keys between obj and other. For each intersecting key, the values from obj and other are included as the last two terms in the triplet (respectively).

func (Object) IsGround

func (obj Object) IsGround() bool

IsGround returns true if all of the Object key/value pairs are ground.

func (Object) Keys added in v0.2.0

func (obj Object) Keys() []*Term

Keys returns the keys of obj.

func (Object) Merge

func (obj Object) Merge(other Object) (Object, bool)

Merge returns a new Object containing the non-overlapping keys of obj and other. If there are overlapping keys between obj and other, the values of associated with the keys are merged. Only objects can be merged with other objects. If the values cannot be merged, the second turn value will be false.

func (Object) String

func (obj Object) String() string

type Option

type Option func(*parser) Option

Option is a function that can set an option on the parser. It returns the previous setting as an Option.

func Debug

func Debug(b bool) Option

Debug creates an Option to set the debug flag to b. When set to true, debugging information is printed to stdout while parsing.

The default is false.

func Memoize

func Memoize(b bool) Option

Memoize creates an Option to set the memoize flag to b. When set to true, the parser will cache all results so each expression is evaluated only once. This guarantees linear parsing time even for pathological cases, at the expense of more memory and slower times for typical cases.

The default is false.

func Recover

func Recover(b bool) Option

Recover creates an Option to set the recover flag to b. When set to true, this causes the parser to recover from panics and convert it to an error. Setting it to false can be useful while debugging to access the full stack trace.

The default is true.

type Package

type Package struct {
	Location *Location `json:"-"`
	Path     Ref
}

Package represents the namespace of the documents produced by rules inside the module.

func MustParsePackage added in v0.2.2

func MustParsePackage(input string) *Package

MustParsePackage returns a Package. If an error occurs during parsing, panic.

func ParsePackage added in v0.2.2

func ParsePackage(input string) (*Package, error)

ParsePackage returns exactly one Package. If multiple statements are parsed, an error is returned.

func (*Package) Compare added in v0.2.0

func (pkg *Package) Compare(other *Package) int

Compare returns an integer indicating whether pkg is less than, equal to, or greater than other.

func (*Package) Copy added in v0.2.2

func (pkg *Package) Copy() *Package

Copy returns a deep copy of pkg.

func (*Package) Equal

func (pkg *Package) Equal(other *Package) bool

Equal returns true if pkg is equal to other.

func (*Package) Loc

func (pkg *Package) Loc() *Location

Loc returns the location of the Package in the definition.

func (*Package) String

func (pkg *Package) String() string

type QueryCompiler added in v0.2.2

type QueryCompiler interface {

	// Compile should be called to compile ad-hoc queries. The return value is
	// the compiled version of the query.
	Compile(q Body) (Body, error)

	// WithContext sets the QueryContext on the QueryCompiler. Subsequent calls
	// to Compile will take the QUeryContext into account.
	WithContext(qctx *QueryContext) QueryCompiler
}

QueryCompiler defines the interface for compiling ad-hoc queries.

type QueryContext added in v0.2.2

type QueryContext struct {
	Package *Package
	Imports []*Import
}

QueryContext contains contextual information for running an ad-hoc query.

Ad-hoc queries can be run in the context of a package and imports may be included to provide concise access to data.

func NewQueryContext added in v0.2.2

func NewQueryContext(pkg *Package, imports []*Import) *QueryContext

NewQueryContext returns a new QueryContext object.

func NewQueryContextForModule added in v0.2.2

func NewQueryContextForModule(mod *Module) *QueryContext

NewQueryContextForModule returns a new QueryContext object based on the provided module.

func (*QueryContext) Copy added in v0.2.2

func (qc *QueryContext) Copy() *QueryContext

Copy returns a deep copy of qc.

type QueryIterator

type QueryIterator func(map[Var]Value, Value) error

QueryIterator defines the interface for querying AST documents with references.

type Ref

type Ref []*Term

Ref represents a reference as defined by the language.

func EmptyRef

func EmptyRef() Ref

EmptyRef returns a new, empty reference.

func MustParseRef

func MustParseRef(input string) Ref

MustParseRef returns a parsed reference. If an error occurs during parsing, panic.

func ParseRef

func ParseRef(input string) (Ref, error)

ParseRef returns exactly one reference.

func (Ref) Append added in v0.2.0

func (ref Ref) Append(term *Term) Ref

Append returns a copy of ref with the term appended to the end.

func (Ref) Copy added in v0.2.2

func (ref Ref) Copy() Ref

Copy returns a deep copy of ref.

func (Ref) Equal

func (ref Ref) Equal(other Value) bool

Equal returns true if ref is equal to other.

func (Ref) GroundPrefix added in v0.2.0

func (ref Ref) GroundPrefix() Ref

GroundPrefix returns the ground portion of the ref starting from the head. By definition, the head of the reference is always ground.

func (Ref) HasPrefix added in v0.2.0

func (ref Ref) HasPrefix(other Ref) bool

HasPrefix returns true if the other ref is a prefix of this ref.

func (Ref) Hash

func (ref Ref) Hash() int

Hash returns the hash code for the Value.

func (Ref) IsGround

func (ref Ref) IsGround() bool

IsGround returns true if all of the parts of the Ref are ground.

func (Ref) IsNested

func (ref Ref) IsNested() bool

IsNested returns true if this ref contains other Refs.

func (Ref) OutputVars

func (ref Ref) OutputVars() VarSet

OutputVars returns a VarSet containing variables that would be bound by evaluating

this expression in isolation.

func (Ref) String

func (ref Ref) String() string

func (Ref) Underlying

func (ref Ref) Underlying() ([]interface{}, error)

Underlying returns a slice of underlying Go values. If the slice is not ground, an error is returned.

type Rule

type Rule struct {
	Location *Location `json:"-"`
	Name     Var
	Key      *Term `json:",omitempty"`
	Value    *Term `json:",omitempty"`
	Body     Body
}

Rule represents a rule as defined in the language. Rules define the content of documents that represent policy decisions.

func MustParseRule

func MustParseRule(input string) *Rule

MustParseRule returns a parsed rule. If an error occurs during parsing, panic.

func ParseConstantRule

func ParseConstantRule(body Body) *Rule

ParseConstantRule attempts to return a rule from a body. Equality expressions of the form <var> = <ground term> can be converted into rules of the form <var> = <ground term> :- true. This is a concise way of defining constants inside modules.

func ParseRule

func ParseRule(input string) (*Rule, error)

ParseRule returns exactly one rule. If multiple rules are parsed, an error is returned.

func (*Rule) Compare added in v0.2.0

func (rule *Rule) Compare(other *Rule) int

Compare returns an integer indicating whether rule is less than, equal to, or greater than other.

func (*Rule) Copy added in v0.2.2

func (rule *Rule) Copy() *Rule

Copy returns a deep copy of rule.

func (*Rule) DocKind

func (rule *Rule) DocKind() DocKind

DocKind returns the type of document produced by this rule.

func (*Rule) Equal

func (rule *Rule) Equal(other *Rule) bool

Equal returns true if rule is equal to other.

func (*Rule) Head added in v0.2.0

func (rule *Rule) Head() *Head

Head returns the rule's head.

func (*Rule) HeadVars

func (rule *Rule) HeadVars() VarSet

HeadVars returns map where keys represent all of the variables found in the head of the rule. The values of the map are ignored.

func (*Rule) Loc

func (rule *Rule) Loc() *Location

Loc returns the location of the Rule in the definition.

func (*Rule) Path added in v0.2.0

func (rule *Rule) Path(ns Ref) Ref

Path returns a reference that identifies the rule under ns.

func (*Rule) String

func (rule *Rule) String() string

type RuleTreeNode added in v0.2.0

type RuleTreeNode struct {
	Key      Value
	Rules    []*Rule
	Children map[Value]*RuleTreeNode
}

RuleTreeNode represents a node in the rule tree. The rule tree is keyed by rule path.

func NewRuleTree added in v0.2.0

func NewRuleTree(mods map[string]*Module) *RuleTreeNode

NewRuleTree returns a new RuleTreeNode that represents the root of the rule tree populated with the given rules.

func (*RuleTreeNode) DepthFirst added in v0.2.2

func (n *RuleTreeNode) DepthFirst(f func(node *RuleTreeNode) bool)

DepthFirst performs a depth-first traversal of the rule tree rooted at n. If f returns true, traversal will not continue to the children of n.

func (*RuleTreeNode) Size added in v0.2.0

func (n *RuleTreeNode) Size() int

Size returns the number of rules in the tree.

type Set added in v0.2.0

type Set []*Term

Set represents a set as defined by the language.

func (*Set) Add added in v0.2.0

func (s *Set) Add(t *Term)

Add updates s to include t.

func (Set) Contains added in v0.2.0

func (s Set) Contains(t *Term) bool

Contains returns true if t is in s.

func (*Set) Copy added in v0.2.2

func (s *Set) Copy() *Set

Copy returns a deep copy of s.

func (*Set) Diff added in v0.2.0

func (s *Set) Diff(other *Set) *Set

Diff returns elements in s that are not in other.

func (*Set) Equal added in v0.2.0

func (s *Set) Equal(v Value) bool

Equal returns true if s is equal to v.

func (*Set) Hash added in v0.2.0

func (s *Set) Hash() int

Hash returns a hash code for s.

func (*Set) IsGround added in v0.2.0

func (s *Set) IsGround() bool

IsGround returns true if all terms in s are ground.

func (*Set) Map added in v0.2.0

func (s *Set) Map(f func(*Term) (*Term, error)) (*Set, error)

Map returns a new Set obtained by applying f to each value in s.

func (*Set) String added in v0.2.0

func (s *Set) String() string

type Statement

type Statement interface {
	Loc() *Location
}

Statement represents a single statement within a module.

type String

type String string

String represents a string value as defined by JSON.

func (String) Equal

func (str String) Equal(other Value) bool

Equal returns true if the other Value is a String and is equal.

func (String) Hash

func (str String) Hash() int

Hash returns the hash code for the Value.

func (String) IsGround

func (str String) IsGround() bool

IsGround always returns true.

func (String) String

func (str String) String() string

type Term

type Term struct {
	Value    Value     // the value of the Term as represented in Go
	Location *Location `json:"-"` // the location of the Term in the source
}

Term is an argument to a function.

func ArrayComprehensionTerm

func ArrayComprehensionTerm(term *Term, body Body) *Term

ArrayComprehensionTerm creates a new Term with an ArrayComprehension value.

func ArrayTerm

func ArrayTerm(a ...*Term) *Term

ArrayTerm creates a new Term with an Array value.

func BooleanTerm

func BooleanTerm(b bool) *Term

BooleanTerm creates a new Term with a Boolean value.

func Item

func Item(key, value *Term) [2]*Term

Item is a helper for constructing an tuple containing two Terms representing a key/value pair in an Object.

func MustParseTerm

func MustParseTerm(input string) *Term

MustParseTerm returns a parsed term. If an error occurs during parsing, panic.

func NewTerm added in v0.2.1

func NewTerm(v Value) *Term

NewTerm returns a new Term object.

func NullTerm

func NullTerm() *Term

NullTerm creates a new Term with a Null value.

func NumberTerm

func NumberTerm(n float64) *Term

NumberTerm creates a new Term with a Number value.

func ObjectTerm

func ObjectTerm(o ...[2]*Term) *Term

ObjectTerm creates a new Term with an Object value.

func ParseTerm

func ParseTerm(input string) (*Term, error)

ParseTerm returns exactly one term. If multiple terms are parsed, an error is returned.

func RefTerm

func RefTerm(r ...*Term) *Term

RefTerm creates a new Term with a Ref value.

func SetTerm added in v0.2.0

func SetTerm(t ...*Term) *Term

SetTerm returns a new Term representing a set containing terms t.

func StringTerm

func StringTerm(s string) *Term

StringTerm creates a new Term with a String value.

func VarTerm

func VarTerm(v string) *Term

VarTerm creates a new Term with a Variable value.

func (*Term) Copy added in v0.2.2

func (term *Term) Copy() *Term

Copy returns a deep copy of term.

func (*Term) Equal

func (term *Term) Equal(other *Term) bool

Equal returns true if this term equals the other term. Equality is defined for each kind of term.

func (*Term) Hash

func (term *Term) Hash() int

Hash returns the hash code of the Term's value.

func (*Term) IsGround

func (term *Term) IsGround() bool

IsGround returns true if this terms' Value is ground.

func (*Term) MarshalJSON

func (term *Term) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON encoding of the term. Specialized marshalling logic is required to include a type hint for Value.

func (*Term) String

func (term *Term) String() string

func (*Term) UnmarshalJSON

func (term *Term) UnmarshalJSON(bs []byte) error

UnmarshalJSON parses the byte array and stores the result in term. Specialized unmarshalling is required to handle Value.

func (*Term) Vars

func (term *Term) Vars() VarSet

Vars returns a VarSet with variables contained in this term.

type Transformer added in v0.2.0

type Transformer interface {
	Transform(v interface{}) (interface{}, error)
}

Transformer defines the interface for transforming AST elements. If the transformer returns nil and does not indicate an error, the AST element will be set to nil and no transformations will be applied to children of the element.

type Value

type Value interface {
	// Equal returns true if this value equals the other value.
	Equal(other Value) bool

	// IsGround returns true if this value is not a variable or contains no variables.
	IsGround() bool

	// String returns a human readable string representation of the value.
	String() string

	// Returns hash code of the value.
	Hash() int
}

Value declares the common interface for all Term values. Every kind of Term value in the language is represented as a type that implements this interface:

- Null, Boolean, Number, String - Object, Array - Variables - References - Array Comprehensions

func InterfaceToValue

func InterfaceToValue(x interface{}) (Value, error)

InterfaceToValue converts a native Go value x to a Value.

type ValueMap added in v0.2.0

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

ValueMap represents a key/value map between AST term values. Any type of term can be used as a key in the map.

func NewValueMap added in v0.2.0

func NewValueMap() *ValueMap

NewValueMap returns a new ValueMap.

func (*ValueMap) Copy added in v0.2.0

func (vs *ValueMap) Copy() *ValueMap

Copy returns a shallow copy of the ValueMap.

func (*ValueMap) Delete added in v0.2.0

func (vs *ValueMap) Delete(k Value)

Delete removes a key k from the map.

func (*ValueMap) Equal added in v0.2.0

func (vs *ValueMap) Equal(other *ValueMap) bool

Equal returns true if this ValueMap equals the other.

func (*ValueMap) Get added in v0.2.0

func (vs *ValueMap) Get(k Value) Value

Get returns the value in the map for k.

func (*ValueMap) Hash added in v0.2.0

func (vs *ValueMap) Hash() int

Hash returns a hash code for this ValueMap.

func (*ValueMap) Iter added in v0.2.0

func (vs *ValueMap) Iter(iter func(Value, Value) bool) bool

Iter calls the iter function for each key/value pair in the map. If the iter function returns true, iteration stops.

func (*ValueMap) Len added in v0.2.0

func (vs *ValueMap) Len() int

Len returns the number of elements in the map.

func (*ValueMap) Put added in v0.2.0

func (vs *ValueMap) Put(k, v Value)

Put inserts a key k into the map with value v.

func (*ValueMap) String added in v0.2.0

func (vs *ValueMap) String() string

type Var

type Var string

Var represents a variable as defined by the language.

func (Var) Equal

func (v Var) Equal(other Value) bool

Equal returns true if the other Value is a Variable and has the same value (name).

func (Var) Hash

func (v Var) Hash() int

Hash returns the hash code for the Value.

func (Var) IsGround

func (v Var) IsGround() bool

IsGround always returns false.

func (Var) IsWildcard added in v0.2.0

func (v Var) IsWildcard() bool

IsWildcard returns true if this is a wildcard variable.

func (Var) String

func (v Var) String() string

type VarSet

type VarSet map[Var]struct{}

VarSet represents a set of variables.

func NewVarSet

func NewVarSet(vs ...Var) VarSet

NewVarSet returns a new VarSet containing the specified variables.

func Unify

func Unify(safe VarSet, a *Term, b *Term) VarSet

Unify returns a set of variables that will be unified when the equality expression defined by terms a and b is evaluated. The unifier assumes that variables in the VarSet safe are already unified.

func (VarSet) Add

func (s VarSet) Add(v Var)

Add updates the set to include the variable "v".

func (VarSet) Contains

func (s VarSet) Contains(v Var) bool

Contains returns true if the set contains the variable "v".

func (VarSet) Copy

func (s VarSet) Copy() VarSet

Copy returns a shallow copy of the VarSet.

func (VarSet) Diff

func (s VarSet) Diff(vs VarSet) VarSet

Diff returns a VarSet containing variables in s that are not in vs.

func (VarSet) Equal added in v0.2.1

func (s VarSet) Equal(vs VarSet) bool

Equal returns true if s contains exactly the same elements as vs.

func (VarSet) Intersect

func (s VarSet) Intersect(vs VarSet) VarSet

Intersect returns a VarSet containing variables in s that are in vs.

func (VarSet) String

func (s VarSet) String() string

func (VarSet) Update

func (s VarSet) Update(vs VarSet)

Update merges the other VarSet into this VarSet.

type Visitor

type Visitor interface {
	Visit(v interface{}) (w Visitor)
}

Visitor defines the interface for iterating AST elements. The Visit function can return a Visitor w which will be used to visit the children of the AST element v. If the Visit function returns nil, the children will not be visited.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL