package ast

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

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 

const (
	// ParseErr indicates an unclassified parse error occurred.
	ParseErr = "rego_parse_error"

	// CompileErr indicates an unclassified compile error occurred.
	CompileErr = "rego_compile_error"

	// TypeErr indicates a type error was caught.
	TypeErr = "rego_type_error"

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

	// RecursionErr indicates recursion was found during compilation.
	RecursionErr = "rego_recursion_error"

	// InputErr indicates the query depends on input but no input or conflicting
	// input was provided.
	InputErr = "rego_input_error"
)
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
)
const (
	NullTypeName               = "null"
	BooleanTypeName            = "boolean"
	StringTypeName             = "string"
	NumberTypeName             = "number"
	VarTypeName                = "var"
	RefTypeName                = "ref"
	ArrayTypeName              = "array"
	ObjectTypeName             = "object"
	SetTypeName                = "set"
	ArrayComprehensionTypeName = "arraycomprehension"
	ExprTypeName               = "expr"
	WithTypeName               = "with"
	BodyTypeName               = "body"
	HeadTypeName               = "head"
	RuleTypeName               = "rule"
	ImportTypeName             = "import"
	PackageTypeName            = "package"
)

The type names provide consistent strings for types in error messages.

Variables 

var Abs = &Builtin{
	Name: String("abs"),
	Args: []types.Type{
		types.N,
		types.N,
	},
	TargetPos: []int{1},
}

Abs returns the number without its sign. 

var And = &Builtin{
	Name:  String("and"),
	Infix: String("&"),
	Args: []types.Type{
		types.NewSet(types.A),
		types.NewSet(types.A),
		types.NewSet(types.A),
	},
	TargetPos: []int{2},
}

And performs an intersection operation on sets. 

var Base64UrlDecode = &Builtin{
	Name: String("base64url.decode"),
	Args: []types.Type{
		types.S,
		types.S,
	},
	TargetPos: []int{1},
}

Base64UrlDecode deserializes the base64url encoded input string. 

var Base64UrlEncode = &Builtin{
	Name: String("base64url.encode"),
	Args: []types.Type{
		types.S,
		types.S,
	},
	TargetPos: []int{1},
}

Base64UrlEncode serializes the input string into base64url encoding. 

var BuiltinMap map[String]*Builtin

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

var Builtins []*Builtin

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

var Concat = &Builtin{
	Name: String("concat"),
	Args: []types.Type{
		types.S,
		types.NewAny(
			types.NewSet(types.S),
			types.NewArray(nil, types.S),
		),
		types.S,
	},
	TargetPos: []int{2},
}

Concat joins an array of strings with an input string. 

var Contains = &Builtin{
	Name: String("contains"),
	Args: []types.Type{
		types.S,
		types.S,
	},
}

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

var Count = &Builtin{
	Name: String("count"),
	Args: []types.Type{
		types.NewAny(
			types.NewSet(types.A),
			types.NewArray(nil, types.A),
			types.NewObject(nil, types.A),
			types.S,
		),
		types.N,
	},
	TargetPos: []int{1},
}

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

var DefaultBuiltins = [...]*Builtin{

	Equality,

	GreaterThan, GreaterThanEq, LessThan, LessThanEq, NotEqual,

	Plus, Minus, Multiply, Divide, Round, Abs,

	And, Or,

	Count, Sum, Max, Min,

	ToNumber,

	RegexMatch,

	SetDiff,

	Concat, FormatInt, IndexOf, Substring, Lower, Upper, Contains, StartsWith, EndsWith, Split, Replace, Trim, Sprintf,

	JSONMarshal, JSONUnmarshal, Base64UrlEncode, Base64UrlDecode,

	JWTDecode,
}

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. 

var DefaultRootDocument = VarTerm("data")

DefaultRootDocument is the default root document.

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

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. 

var Divide = &Builtin{
	Name:  String("div"),
	Infix: String("/"),
	Args: []types.Type{
		types.N,
		types.N,
		types.N,
	},
	TargetPos: []int{2},
}

Divide divides the first number by the second number. 

var EndsWith = &Builtin{
	Name: String("endswith"),
	Args: []types.Type{
		types.S,
		types.S,
	},
}

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

var Equality = &Builtin{
	Name:  String("eq"),
	Infix: String("="),
	Args: []types.Type{
		types.A,
		types.A,
	},
	TargetPos: []int{0, 1},
}

Equality represents the "=" operator. 

var FormatInt = &Builtin{
	Name: String("format_int"),
	Args: []types.Type{
		types.N,
		types.N,
		types.S,
	},
	TargetPos: []int{2},
}

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

var GreaterThan = &Builtin{
	Name:  String("gt"),
	Infix: String(">"),
	Args: []types.Type{
		types.A,
		types.A,
	},
}

GreaterThan represents the ">" comparison operator. 

var GreaterThanEq = &Builtin{
	Name:  String("gte"),
	Infix: String(">="),
	Args: []types.Type{
		types.A,
		types.A,
	},
}

GreaterThanEq represents the ">=" comparison operator. 

var IndexOf = &Builtin{
	Name: String("indexof"),
	Args: []types.Type{
		types.S,
		types.S,
		types.N,
	},
	TargetPos: []int{2},
}

IndexOf returns the index of a substring contained inside a string 

var InputRootDocument = VarTerm("input")

InputRootDocument names the document containing query arguments. 

var InputRootRef = Ref{InputRootDocument}

InputRootRef is a reference to the root of the input document.

All refs to query arguments are prefixed with this ref. 

var JSONMarshal = &Builtin{
	Name: String("json.marshal"),
	Args: []types.Type{
		types.A,
		types.S,
	},
	TargetPos: []int{1},
}

JSONMarshal serializes the input term. 

var JSONUnmarshal = &Builtin{
	Name: String("json.unmarshal"),
	Args: []types.Type{
		types.S,
		types.A,
	},
	TargetPos: []int{1},
}

JSONUnmarshal deserializes the input string. 

var JWTDecode = &Builtin{
	Name: String("io.jwt.decode"),
	Args: []types.Type{
		types.S,
		types.NewObject(nil, types.A),
		types.NewObject(nil, types.A),
		types.S,
	},
	TargetPos: []int{1, 2, 3},
}

JWTDecode decodes a JSON Web Token and outputs it as an Object. 

var Keywords = [...]string{
	"not",
	"package",
	"import",
	"as",
	"default",
	"else",
	"with",
	"null",
	"true",
	"false",
}

Keywords contains strings that map to language keywords. 

var LessThan = &Builtin{
	Name:  String("lt"),
	Infix: String("<"),
	Args: []types.Type{
		types.A,
		types.A,
	},
}

LessThan represents the "<" comparison operator. 

var LessThanEq = &Builtin{
	Name:  String("lte"),
	Infix: String("<="),
	Args: []types.Type{
		types.A,
		types.A,
	},
}

LessThanEq represents the "<=" comparison operator. 

var Lower = &Builtin{
	Name: String("lower"),
	Args: []types.Type{
		types.S,
		types.S,
	},
	TargetPos: []int{1},
}

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

var Max = &Builtin{
	Name: String("max"),
	Args: []types.Type{
		types.NewAny(
			types.NewSet(types.A),
			types.NewArray(nil, types.A),
		),
		types.A,
	},
	TargetPos: []int{1},
}

Max returns the maximum value in a collection. 

var Min = &Builtin{
	Name: String("min"),
	Args: []types.Type{
		types.NewAny(
			types.NewSet(types.A),
			types.NewArray(nil, types.A),
		),
		types.A,
	},
	TargetPos: []int{1},
}

Min returns the minimum value in a collection. 

var Minus = &Builtin{
	Name:  String("minus"),
	Infix: String("-"),
	Args: []types.Type{
		types.NewAny(types.N, types.NewSet(types.A)),
		types.NewAny(types.N, types.NewSet(types.A)),
		types.NewAny(types.N, types.NewSet(types.A)),
	},
	TargetPos: []int{2},
}

Minus subtracts the second number from the first number or computes the diff between two sets. 

var Multiply = &Builtin{
	Name:  String("mul"),
	Infix: String("*"),
	Args: []types.Type{
		types.N,
		types.N,
		types.N,
	},
	TargetPos: []int{2},
}

Multiply multiplies two numbers together. 

var NotEqual = &Builtin{
	Name:  String("neq"),
	Infix: String("!="),
	Args: []types.Type{
		types.A,
		types.A,
	},
}

NotEqual represents the "!=" comparison operator. 

var Or = &Builtin{
	Name:  String("or"),
	Infix: String("|"),
	Args: []types.Type{
		types.NewSet(types.A),
		types.NewSet(types.A),
		types.NewSet(types.A),
	},
	TargetPos: []int{2},
}

Or performs a union operation on sets. 

var Plus = &Builtin{
	Name:  String("plus"),
	Infix: String("+"),
	Args: []types.Type{
		types.N,
		types.N,
		types.N,
	},
	TargetPos: []int{2},
}

Plus adds two numbers together. 

var RegexMatch = &Builtin{
	Name: String("re_match"),
	Args: []types.Type{
		types.S,
		types.S,
	},
}

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

var Replace = &Builtin{
	Name: String("replace"),
	Args: []types.Type{
		types.S,
		types.S,
		types.S,
		types.S,
	},
	TargetPos: []int{3},
}

Replace returns the given string with all instances of the second argument replaced by the third. 

var ReservedVars = NewVarSet(
	DefaultRootDocument.Value.(Var),
	InputRootDocument.Value.(Var),
)

ReservedVars is the set of names that refer to implicitly ground vars. 

var RootDocumentNames = &Set{
	DefaultRootDocument,
	InputRootDocument,
}

RootDocumentNames contains the names of top-level documents that can be referred to in modules and queries. 

var RootDocumentRefs = &Set{
	NewTerm(DefaultRootRef),
	NewTerm(InputRootRef),
}

RootDocumentRefs contains the prefixes of top-level documents that all non-local references start with. 

var Round = &Builtin{
	Name: String("round"),
	Args: []types.Type{
		types.N,
		types.N,
	},
	TargetPos: []int{1},
}

Round rounds the number up to the nearest integer. 

var SetDiff = &Builtin{
	Name: String("set_diff"),
	Args: []types.Type{
		types.NewSet(types.A),
		types.NewSet(types.A),
		types.NewSet(types.A),
	},
	TargetPos: []int{2},
}

SetDiff has been replaced by the minus built-in. 

var Split = &Builtin{
	Name: String("split"),
	Args: []types.Type{
		types.S,
		types.S,
		types.NewArray(nil, types.S),
	},
	TargetPos: []int{2},
}

Split returns an array containing elements of the input string split on a delimiter. 

var Sprintf = &Builtin{
	Name: String("sprintf"),
	Args: []types.Type{
		types.S,
		types.NewArray(nil, types.A),
		types.S,
	},
	TargetPos: []int{2},
}

Sprintf returns the given string, formatted. 

var StartsWith = &Builtin{
	Name: String("startswith"),
	Args: []types.Type{
		types.S,
		types.S,
	},
}

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

var Substring = &Builtin{
	Name: String("substring"),
	Args: []types.Type{
		types.S,
		types.N,
		types.N,
		types.S,
	},
	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.

var Sum = &Builtin{
	Name: String("sum"),
	Args: []types.Type{
		types.NewAny(
			types.NewSet(types.N),
			types.NewArray(nil, types.N),
		),
		types.N,
	},
	TargetPos: []int{1},
}

Sum takes an array or set of numbers and sums them. 

var SystemDocumentKey = String("system")

SystemDocumentKey is the name of the top-level key that identifies the system document. 

var ToNumber = &Builtin{
	Name: String("to_number"),
	Args: []types.Type{
		types.NewAny(
			types.N,
			types.S,
			types.B,
			types.NewNull(),
		),
		types.N,
	},
	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. 

var Trim = &Builtin{
	Name: String("trim"),
	Args: []types.Type{
		types.S,
		types.S,
		types.S,
	},
	TargetPos: []int{2},
}

Trim returns the given string will all leading or trailing instances of the second argument removed. 

var Upper = &Builtin{
	Name: String("upper"),
	Args: []types.Type{
		types.S,
		types.S,
	},
	TargetPos: []int{1},
}

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

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

Wildcard represents the wildcard variable as defined in the language. 

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 

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 IsConstant 

func IsConstant(v Value) bool

IsConstant returns true if the AST value is constant.

func IsError 

func IsError(code string, err error) bool

IsError returns true if err is an AST error with code.

func IsKeyword 

func IsKeyword(s string) bool

IsKeyword returns true if s is a language keyword.

func IsScalar 

func IsScalar(v Value) bool

IsScalar returns true if the AST value is a scalar.

func IsValidImportPath 

func IsValidImportPath(v Value) (err error)

IsValidImportPath returns an error indicating if the import path is invalid. If the import path is invalid, err is nil.

func JSON 

func JSON(v Value) (interface{}, error)

JSON returns the JSON representation of v. The value must not contain any refs or terms that require evaluation (e.g., vars, comprehensions, etc.)

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 RegisterBuiltin 

func RegisterBuiltin(b *Builtin)

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

func Transform 

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 

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

TransformRefs calls the function f on all references under x.

func TypeName 

func TypeName(x interface{}) string

TypeName returns a human readable name for the AST element type.

func ValueToInterface 

func ValueToInterface(v Value, resolver Resolver) (interface{}, error)

ValueToInterface returns the Go representation of an AST value. The AST value should not contain any values that require evaluation (e.g., vars, comprehensions, etc.)

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 

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 WalkExprs 

func WalkExprs(x interface{}, f func(*Expr) bool)

WalkExprs calls the function f on all expressions 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 WalkRules 

func WalkRules(x interface{}, f func(*Rule) bool)

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

func WalkVars 

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.

func WalkWiths 

func WalkWiths(x interface{}, f func(*With) bool)

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

Types

type ArgErrDetail 

type ArgErrDetail struct {
	Have []types.Type `json:"have"`
	Want []types.Type `json:"want"`
}

ArgErrDetail represents a generic argument error.

func (*ArgErrDetail) Lines 

func (d *ArgErrDetail) Lines() []string

Lines returns the string representation of the detail.

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 

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) Find 

func (arr Array) Find(path Ref) (Value, error)

Find returns the value at the index or an out-of-range error.

func (Array) Get 

func (arr Array) Get(pos *Term) *Term

Get returns the element at pos or nil if not possible.

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) MarshalJSON 

func (arr Array) MarshalJSON() ([]byte, error)

MarshalJSON returns JSON encoded bytes representing arr.

func (Array) String 

func (arr Array) String() string

type ArrayComprehension 

type ArrayComprehension struct {
	Term *Term `json:"term"`
	Body Body  `json:"body"`
}

ArrayComprehension represents an array comprehension as defined in the language.

func (*ArrayComprehension) Copy 

func (ac *ArrayComprehension) Copy() *ArrayComprehension

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) Find 

func (ac *ArrayComprehension) Find(path Ref) (Value, error)

Find returns the current value or a not found error.

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 

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) Append 

func (body *Body) Append(expr *Expr)

Append adds the expr to the body and updates the expr's index accordingly.

func (Body) Compare 

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 

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(params VarVisitorParams) VarSet

Vars returns a VarSet containing variables in body. The params can be set to control which vars are included.

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) Find 

func (bol Boolean) Find(path Ref) (Value, error)

Find returns the current value or a not found error.

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      String       // Unique name of built-in function, e.g., name(term,term,...,term)
	Infix     String       // Unique name of infix operator. Default should be unset.
	Args      []types.Type // Built-in argument type declaration.
	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 Comment 

type Comment struct {
	Text     []byte
	Location *Location
}

Comment contains the raw text from the comment in the definition.

func NewComment 

func NewComment(text []byte) *Comment

NewComment returns a new Comment object.

func (*Comment) Loc 

func (c *Comment) Loc() *Location

Loc returns the location of the comment in the definition.

func (*Comment) String 

func (c *Comment) String() string

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 containing
	// 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 dependencies between rules. An edge (u,v) is
	// added to the graph if rule "u" depends on rule "v". A rule "u" depends on
	// rule "v" if rule "u" refers to the virtual document defined by rule "v".
	RuleGraph *RuleGraph

	// TypeEnv holds type information for values inferred by the compiler.
	TypeEnv *TypeEnv
	// 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

Code:play  

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 input.bar

p[x] { foo[x]; not bar[x]; x >= min_x }
min_x = 100 { true }`

	// 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 input.bar[x]
Expr 3: 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) GetRules 

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

GetRules returns a slice of rules that are referred to by ref.

E.g., given the following module: 

package a.b.c

p[x] = y { q[x] = y; ... } # rule1
q[x] = y { ... }           # rule2

The following calls yield the rules on the right. 

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

func (*Compiler) GetRulesExact 

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 

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 

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 

func (c *Compiler) QueryCompiler() QueryCompiler

QueryCompiler returns a new QueryCompiler object.

func (*Compiler) RuleIndex 

func (c *Compiler) RuleIndex(path Ref) RuleIndex

RuleIndex returns a RuleIndex built for the rule set referred to by path. The path must refer to the rule set exactly, i.e., given a rule set at path data.a.b.c.p, refs data.a.b.c.p.x and data.a.b.c would not return a RuleIndex built for the rule.

func (*Compiler) WithModuleLoader 

func (c *Compiler) WithModuleLoader(f ModuleLoader) *Compiler

WithModuleLoader sets f as the ModuleLoader on the compiler.

The compiler will invoke the ModuleLoader after resolving all references in the current set of input modules. The ModuleLoader can return a new collection of parsed modules that are to be included in the compilation process. This process will repeat until the ModuleLoader returns an empty collection or an error. If an error is returned, compilation will stop immediately.

type DocKind 

type DocKind int

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

type Error 

type Error struct {
	Code     string       `json:"code"`
	Message  string       `json:"message"`
	Location *Location    `json:"location,omitempty"`
	Details  ErrorDetails `json:"details,omitempty"`
}

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

func NewError 

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

NewError returns a new Error object.

func (*Error) Error 

func (e *Error) Error() string

type ErrorDetails 

type ErrorDetails interface {
	Lines() []string
}

ErrorDetails defines the interface for detailed error messages.

type Errors 

type Errors []*Error

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

func (Errors) Error 

func (e Errors) Error() string

type Expr 

type Expr struct {
	Location *Location   `json:"-"`
	Index    int         `json:"index"`
	Negated  bool        `json:"negated,omitempty"`
	Terms    interface{} `json:"terms"`
	With     []*With     `json:"with,omitempty"`
}

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

func MustParseExpr 

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 

func NewExpr(terms interface{}) *Expr

NewExpr returns a new Expr object.

func ParseExpr 

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

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

func (*Expr) Builtin 

func (expr *Expr) Builtin() *Builtin

Builtin returns the builtin object referred to by this expression. If the expression does not refer to a built-in or the built-in is unknown, this function returns nil.

func (*Expr) Compare 

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. Preceding expression (by Index) is always less than the other expression. 2. Non-negated expressions are always less than than negated expressions. 3. Single term expressions are always less than built-in expressions.

Otherwise, the expression terms are compared normally. If both expressions have the same terms, the modifiers are compared.

func (*Expr) Complement 

func (expr *Expr) Complement() *Expr

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

func (*Expr) Copy 

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) IncludeWith 

func (expr *Expr) IncludeWith(target *Term, value *Term) *Expr

IncludeWith returns a copy of expr with the with modifier appended.

func (*Expr) IsBuiltin 

func (expr *Expr) IsBuiltin() bool

IsBuiltin returns true if this expression refers to a built-in function.

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) NoWith 

func (expr *Expr) NoWith() *Expr

NoWith returns a copy of expr where the with modifier has been removed.

func (*Expr) Operand 

func (expr *Expr) Operand(pos int) *Term

Operand returns the term at the zero-based pos. If the expr does not include at least pos+1 terms, this function returns nil.

func (*Expr) Operands 

func (expr *Expr) Operands() []*Term

Operands returns the built-in function operands.

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(params VarVisitorParams) VarSet

Vars returns a VarSet containing variables in expr. The params can be set to control which vars are included.

type GenericTransformer 

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 

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 NewGenericVisitor 

func NewGenericVisitor(f func(x interface{}) bool) *GenericVisitor

NewGenericVisitor returns a new GenericVisitor that will invoke the function f on AST nodes.

func (*GenericVisitor) Visit 

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

Visit calls the function f on the GenericVisitor. 

type Head struct {
	Location *Location `json:"-"`
	Name     Var       `json:"name"`
	Key      *Term     `json:"key,omitempty"`
	Value    *Term     `json:"value,omitempty"`
}

Head represents the head of a rule.

func NewHead 

func NewHead(name Var, args ...*Term) *Head

NewHead returns a new Head object. If args are provided, the first will be used for the key and the second will be used for the value.

func (*Head) Compare 

func (head *Head) Compare(other *Head) int

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

func (*Head) Copy 

func (head *Head) Copy() *Head

Copy returns a deep copy of head.

func (*Head) DocKind 

func (head *Head) DocKind() DocKind

DocKind returns the type of document produced by this rule.

func (*Head) Equal 

func (head *Head) Equal(other *Head) bool

Equal returns true if this head equals other.

func (*Head) String 

func (head *Head) String() string

func (*Head) Vars 

func (head *Head) Vars() VarSet

Vars returns a set of vars found in the head.

type Import 

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

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

func MustParseImports 

func MustParseImports(input string) []*Import

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

func ParseImports 

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

ParseImports returns a slice of Import objects.

func (*Import) Compare 

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 

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 

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 IndexResult 

type IndexResult struct {
	Rules   []*Rule
	Else    map[*Rule][]*Rule
	Default *Rule
}

IndexResult contains the result of an index lookup.

func NewIndexResult 

func NewIndexResult() *IndexResult

NewIndexResult returns a new IndexResult object.

func (*IndexResult) Empty 

func (ir *IndexResult) Empty() bool

Empty returns true if there are no rules to evaluate.

func (*IndexResult) Kind 

func (ir *IndexResult) Kind() DocKind

Kind returns the DocKind generated by the rules in the result.

type Location 

type Location struct {
	Text []byte `json:"-"`    // The original text fragment from the source.
	File string `json:"file"` // The name of the source file (which may be empty).
	Row  int    `json:"row"`  // The line in the source.
	Col  int    `json:"col"`  // 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 

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

Format returns a formatted string prefixed with the location information.

func (*Location) String 

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  `json:"package"`
	Imports []*Import `json:"imports,omitempty"`
	Rules   []*Rule   `json:"rules,omitempty"`
}

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 

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 

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) RuleSet 

func (mod *Module) RuleSet(name Var) RuleSet

RuleSet returns a RuleSet containing named rules in the mod.

func (*Module) String 

func (mod *Module) String() string

type ModuleLoader 

type ModuleLoader func(resolved map[string]*Module) (parsed map[string]*Module, err error)

ModuleLoader defines the interface that callers can implement to enable lazy loading of modules during compilation.

type ModuleTreeNode 

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

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 

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) Find 

func (null Null) Find(path Ref) (Value, error)

Find returns the current value or a not found error.

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 json.Number

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) Find 

func (num Number) Find(path Ref) (Value, error)

Find returns the current value or a not found error.

func (Number) Hash 

func (num Number) Hash() int

Hash returns the hash code for the Value.

func (Number) Int 

func (num Number) Int() (int, bool)

Int returns the int representation of num if possible.

func (Number) IsGround 

func (num Number) IsGround() bool

IsGround always returns true.

func (Number) MarshalJSON 

func (num Number) MarshalJSON() ([]byte, error)

MarshalJSON returns JSON encoded bytes representing num.

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 

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) Find 

func (obj Object) Find(path Ref) (Value, error)

Find returns the value at the key or undefined.

func (Object) Get 

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 

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

Keys returns the keys of obj.

func (Object) MarshalJSON 

func (obj Object) MarshalJSON() ([]byte, error)

MarshalJSON returns JSON encoded bytes representing 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       `json:"path"`
}

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

func MustParsePackage 

func MustParsePackage(input string) *Package

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

func ParsePackage 

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

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

func (*Package) Compare 

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 

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 

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)

	// TypeEnv returns the type environment built after running type checking
	// on the query.
	TypeEnv() *TypeEnv

	// 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 

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

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 

func NewQueryContext() *QueryContext

NewQueryContext returns a new QueryContext object.

func (*QueryContext) Copy 

func (qc *QueryContext) Copy() *QueryContext

Copy returns a deep copy of qc.

func (*QueryContext) InputDefined 

func (qc *QueryContext) InputDefined() bool

InputDefined returns true if the input document is defined in qc.

func (*QueryContext) WithImports 

func (qc *QueryContext) WithImports(imports []*Import) *QueryContext

WithImports sets the imports on qc.

func (*QueryContext) WithInput 

func (qc *QueryContext) WithInput(input Value) *QueryContext

WithInput sets the input on qc.

func (*QueryContext) WithPackage 

func (qc *QueryContext) WithPackage(pkg *Package) *QueryContext

WithPackage sets the pkg on 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 

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

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

func (Ref) Copy 

func (ref Ref) Copy() Ref

Copy returns a deep copy of ref.

func (Ref) Dynamic 

func (ref Ref) Dynamic() int

Dynamic returns the offset of the first non-constant operand of ref.

func (Ref) Equal 

func (ref Ref) Equal(other Value) bool

Equal returns true if ref is equal to other.

func (Ref) Extend 

func (ref Ref) Extend(other Ref) Ref

Extend returns a copy of ref with the terms from other appended. The head of other will be converted to a string.

func (Ref) Find 

func (ref Ref) Find(path Ref) (Value, error)

Find returns the current value or a not found error.

func (Ref) GroundPrefix 

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 

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

type RefErrDetail 

type RefErrDetail struct {
	Ref      Ref        `json:"ref"`
	Index    int        `json:"index"`
	Refers   types.Type `json:"refers"`
	Referrer types.Type `json:"referrer"`
}

RefErrDetail represents an undefined ref.

func (*RefErrDetail) Lines 

func (r *RefErrDetail) Lines() []string

Lines returns the string representation of the detail.

type Resolver 

type Resolver interface {
	Resolve(ref Ref) (value interface{}, err error)
}

Resolver defines the interface for resolving references to native Go values.

type Rule 

type Rule struct {
	Default bool  `json:"default,omitempty"`
	Head    *Head `json:"head"`
	Body    Body  `json:"body"`
	Else    *Rule `json:"else,omitempty"`

	// Module is a pointer to the module containing this rule. If the rule
	// was NOT created while parsing/constructing a module, this should be
	// left unset. The pointer is not included in any standard operations
	// on the rule (e.g., printing, comparison, visiting, etc.)
	Module *Module `json:"-"`
}

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 ParseRule 

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

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

func ParseRuleFromBody 

func ParseRuleFromBody(module *Module, body Body) (*Rule, error)

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

func (*Rule) Compare 

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 

func (rule *Rule) Copy() *Rule

Copy returns a deep copy of rule.

func (*Rule) Equal 

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

Equal returns true if rule is equal to other.

func (*Rule) Loc 

func (rule *Rule) Loc() *Location

Loc returns the location of the Rule in the definition.

func (*Rule) Path 

func (rule *Rule) Path() Ref

Path returns a ref referring to the document produced by this rule. If rule is not contained in a module, this function panics.

func (*Rule) String 

func (rule *Rule) String() string

type RuleGraph 

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

RuleGraph represents the dependencies between rules.

func NewRuleGraph 

func NewRuleGraph(modules map[string]*Module, list func(Ref) []*Rule) *RuleGraph

NewRuleGraph returns a new RuleGraph based on modules. The list function must return the rules referred to directly by the ref.

func (*RuleGraph) Dependencies 

func (g *RuleGraph) Dependencies(rule *Rule) map[*Rule]struct{}

Dependencies returns the set of rules that rule depends on.

func (*RuleGraph) Sort 

func (g *RuleGraph) Sort() (sorted []*Rule, ok bool)

Sort returns a slice of rules sorted by dependencies. If a cycle is found, ok is set to false.

type RuleIndex 

type RuleIndex interface {

	// Build tries to construct an index for the given rules. If the index was
	// constructed, ok is true, otherwise false.
	Build(rules []*Rule) (ok bool)

	// Lookup searches the index for rules that will match the provided
	// resolver. If the resolver returns an error, it is returned via err.
	Lookup(resolver ValueResolver) (result *IndexResult, err error)
}

RuleIndex defines the interface for rule indices.

type RuleSet 

type RuleSet []*Rule

RuleSet represents a collection of rules that produce a virtual document.

func NewRuleSet 

func NewRuleSet(rules ...*Rule) RuleSet

NewRuleSet returns a new RuleSet containing the given rules.

func (*RuleSet) Add 

func (rs *RuleSet) Add(rule *Rule)

Add inserts the rule into rs.

func (RuleSet) Contains 

func (rs RuleSet) Contains(rule *Rule) bool

Contains returns true if rs contains rule.

func (RuleSet) Diff 

func (rs RuleSet) Diff(other RuleSet) RuleSet

Diff returns a new RuleSet containing rules in rs that are not in other.

func (RuleSet) Equal 

func (rs RuleSet) Equal(other RuleSet) bool

Equal returns true if rs equals other.

func (RuleSet) Merge 

func (rs RuleSet) Merge(other RuleSet) RuleSet

Merge returns a ruleset containing the union of rules from rs an other.

func (RuleSet) String 

func (rs RuleSet) String() string

type RuleTreeNode 

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

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

func NewRuleTree 

func NewRuleTree(mtree *ModuleTreeNode) *RuleTreeNode

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

func (*RuleTreeNode) Child 

func (n *RuleTreeNode) Child(k Value) *RuleTreeNode

Child returns n's child with key k.

func (*RuleTreeNode) DepthFirst 

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 

func (n *RuleTreeNode) Size() int

Size returns the number of rules in the tree.

type Set 

type Set []*Term

Set represents a set as defined by the language.

func (*Set) Add 

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

Add updates s to include t.

func (Set) Contains 

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

Contains returns true if t is in s.

func (*Set) Copy 

func (s *Set) Copy() *Set

Copy returns a deep copy of s.

func (*Set) Diff 

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

Diff returns elements in s that are not in other.

func (*Set) Equal 

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

Equal returns true if s is equal to v.

func (*Set) Find 

func (s *Set) Find(path Ref) (Value, error)

Find returns the current value or a not found error.

func (*Set) Hash 

func (s *Set) Hash() int

Hash returns a hash code for s.

func (*Set) Intersect 

func (s *Set) Intersect(other *Set) *Set

Intersect returns the set containing elements in both s and other.

func (*Set) IsGround 

func (s *Set) IsGround() bool

IsGround returns true if all terms in s are ground.

func (*Set) Iter 

func (s *Set) Iter(f func(*Term) bool) (stop bool)

Iter calls f on each element in s. If f returns true, iteration stops and the return value is true.

func (*Set) Map 

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) Reduce 

func (s *Set) Reduce(i *Term, f func(*Term, *Term) (*Term, error)) (*Term, error)

Reduce returns a Term produced by applying f to each value in s. The first argument to f is the reduced value (starting with i) and the second argument to f is the element in s.

func (*Set) String 

func (s *Set) String() string

func (*Set) Union 

func (s *Set) Union(other *Set) *Set

Union returns the set containing all elements of s and other.

type Statement 

type Statement interface {
	Loc() *Location
}

Statement represents a single statement in a policy module.

func MustParseStatement 

func MustParseStatement(input string) Statement

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

func MustParseStatements 

func MustParseStatements(input string) []Statement

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

func ParseStatement 

func ParseStatement(input string) (Statement, 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) ([]Statement, error)

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

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) Find 

func (str String) Find(path Ref) (Value, error)

Find returns the current value or a not found error.

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     `json:"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 FloatNumberTerm 

func FloatNumberTerm(f float64) *Term

FloatNumberTerm creates a new Term with a floating point Number value.

func IntNumberTerm 

func IntNumberTerm(i int) *Term

IntNumberTerm creates a new Term with an integer Number 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 

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 json.Number) *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 

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 

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 

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 TypeEnv 

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

TypeEnv contains type info for static analysis such as type checking.

func NewTypeEnv 

func NewTypeEnv() *TypeEnv

NewTypeEnv returns an empty TypeEnv.

func (*TypeEnv) Get 

func (env *TypeEnv) Get(x interface{}) types.Type

Get returns the type of x.

type UnificationErrDetail 

type UnificationErrDetail struct {
	Left  types.Type `json:"a"`
	Right types.Type `json:"b"`
}

UnificationErrDetail represents a type mismatch error when two **values** are unified (as in x = y).

func (*UnificationErrDetail) Lines 

func (a *UnificationErrDetail) Lines() []string

Lines returns the string representation of the detail.

type Value 

type Value interface {
	Equal(other Value) bool       // Equal returns true if this value equals the other value.
	Find(path Ref) (Value, error) // Find returns value referred to by path or an error if path is not found.
	Hash() int                    // Returns hash code of the value.
	IsGround() bool               // IsGround returns true if this value is not a variable or contains no variables.
	String() string               // String returns a human readable string representation of the value.
}

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, Set - Variables, References - Array Comprehensions

func InterfaceToValue 

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

InterfaceToValue converts a native Go value x to a Value.

func MustInterfaceToValue 

func MustInterfaceToValue(x interface{}) Value

MustInterfaceToValue converts a native Go value x to a Value. If the conversion fails, this function will panic. This function is mostly for test purposes.

type ValueMap 

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 

func NewValueMap() *ValueMap

NewValueMap returns a new ValueMap.

func (*ValueMap) Copy 

func (vs *ValueMap) Copy() *ValueMap

Copy returns a shallow copy of the ValueMap.

func (*ValueMap) Delete 

func (vs *ValueMap) Delete(k Value)

Delete removes a key k from the map.

func (*ValueMap) Equal 

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

Equal returns true if this ValueMap equals the other.

func (*ValueMap) Get 

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

Get returns the value in the map for k.

func (*ValueMap) Hash 

func (vs *ValueMap) Hash() int

Hash returns a hash code for this ValueMap.

func (*ValueMap) Iter 

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 

func (vs *ValueMap) Len() int

Len returns the number of elements in the map.

func (*ValueMap) Put 

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

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

func (*ValueMap) String 

func (vs *ValueMap) String() string

type ValueResolver 

type ValueResolver interface {
	Resolve(ref Ref) (value Value, err error)
}

ValueResolver defines the interface for resolving references to AST values.

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) Find 

func (v Var) Find(path Ref) (Value, error)

Find returns the current value or a not found error.

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 

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 

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 VarVisitor 

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

VarVisitor walks AST nodes under a given node and collects all encountered variables. The collected variables can be controlled by specifying VarVisitorParams when creating the visitor.

func NewVarVisitor 

func NewVarVisitor() *VarVisitor

NewVarVisitor returns a new VarVisitor object.

func (*VarVisitor) Vars 

func (vis *VarVisitor) Vars() VarSet

Vars returns a VarSet that contains collected vars.

func (*VarVisitor) Visit 

func (vis *VarVisitor) Visit(v interface{}) Visitor

Visit is called to walk the AST node v.

func (*VarVisitor) WithParams 

func (vis *VarVisitor) WithParams(params VarVisitorParams) *VarVisitor

WithParams sets the parameters in params on vis.

type VarVisitorParams 

type VarVisitorParams struct {
	SkipRefHead    bool
	SkipObjectKeys bool
	SkipClosures   bool
	SkipWithTarget bool
	SkipSets       bool
}

VarVisitorParams contains settings for a VarVisitor.

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.

type With 

type With struct {
	Location *Location `json:"-"`
	Target   *Term     `json:"target"`
	Value    *Term     `json:"value"`
}

With represents a modifier on an expression.

func (*With) Compare 

func (w *With) Compare(other *With) int

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

func (*With) Copy 

func (w *With) Copy() *With

Copy returns a deep copy of w.

func (*With) Equal 

func (w *With) Equal(other *With) bool

Equal returns true if this With is equals the other With.

func (With) Hash 

func (w With) Hash() int

Hash returns the hash code of the With.

func (*With) String 

func (w *With) String() string

Source Files

builtins.go check.go compare.go compile.go doc.go env.go errors.go index.go map.go parser.go parser_ext.go policy.go strings.go term.go transform.go unify.go varset.go visit.go

Version
v0.4.10
Published
May 31, 2017
Platform
js/wasm
Imports
22 packages
Last checked
2 minutes ago –

Tools for package owners.