Documentation
¶
Index ¶
- Constants
- Variables
- func MustParseStatement(input string) interface{}
- func MustParseStatements(input string) []interface{}
- func ParseStatement(input string) (interface{}, error)
- func ParseStatements(input string) ([]interface{}, error)
- func RegisterBuiltin(b *Builtin)
- func Walk(v Visitor, x interface{})
- type Array
- type Body
- type Boolean
- type Builtin
- type Compiler
- type DocKind
- type Expr
- type Import
- type Location
- type Module
- type ModuleTreeNode
- type Null
- type Number
- type Object
- type Package
- type QueryIterator
- type Ref
- type Rule
- type String
- type Term
- func ArrayTerm(a ...*Term) *Term
- func BooleanTerm(b bool) *Term
- func Item(key, value *Term) [2]*Term
- func MustParseTerm(input string) *Term
- func NullTerm() *Term
- func NumberTerm(n float64) *Term
- func ObjectTerm(o ...[2]*Term) *Term
- func ParseTerm(input string) (*Term, error)
- func RefTerm(r ...*Term) *Term
- func StringTerm(s string) *Term
- func VarTerm(v string) *Term
- type Value
- type Var
- type VarSet
- type Visitor
Constants ¶
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 ¶
var BuiltinMap map[Var]*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 DefaultBuiltins = [...]*Builtin{ Equality, GreaterThan, GreaterThanEq, LessThan, LessThanEq, NotEqual, }
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 Equality = &Builtin{ Name: Var("="), Alias: Var("eq"), NumArgs: 2, RecTargetPos: []int{0, 1}, }
Equality represents the "=" operator.
var GreaterThan = &Builtin{ Name: Var(">"), Alias: Var("gt"), NumArgs: 2, }
GreaterThan represents the ">" comparison operator.
var GreaterThanEq = &Builtin{ Name: Var(">="), Alias: Var("gte"), NumArgs: 2, }
GreaterThanEq represents the ">=" comparison operator.
var Keywords = [...]string{
"package", "import", "not",
}
Keywords is an array of reserved keywords in the language. These are reserved names that cannot be used for variables.
var LessThan = &Builtin{ Name: Var("<"), Alias: Var("lt"), NumArgs: 2, }
LessThan represents the "<" comparison operator.
var LessThanEq = &Builtin{ Name: Var("<="), Alias: Var("lte"), NumArgs: 2, }
LessThanEq represents the "<=" comparison operator.
var NotEqual = &Builtin{ Name: Var("!="), Alias: Var("neq"), NumArgs: 2, }
NotEqual represents the "!=" comparison operator.
var ReservedVars = NewVarSet(DefaultRootDocument.Value.(Var))
ReservedVars is the set of reserved variable names.
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 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 ParseStatement ¶
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 ¶
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.
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) Equal ¶
Equal returns true if the other Value is an Array and the elements of the other Array are equal to the elements of this Array. The elements are ordered.
type Body ¶
type Body []*Expr
Body represents one or more expressios contained inside a rule.
func MustParseBody ¶
MustParseBody returns a parsed body. If an error occurs during parsing, panic.
func ParseBody ¶
ParseBody returns exactly one body. If multiple bodies are parsed, an error is returned.
type Boolean ¶
type Boolean bool
Boolean represents a boolean value defined by JSON.
type Builtin ¶
Builtin represents a built-in function supported by OPA. Every built-in function is uniquely identified by a name.
func (*Builtin) GetPrintableName ¶
GetPrintableName returns a printable name for the builtin. Some built-ins have names that are used for infix operators but when printing we want to use something a bit more readable, e.g., "gte(a,b)" instead of ">=(a,b)".
func (*Builtin) Unifies ¶
Unifies returns true if a term in the given position will unify non-recursively or recursively.
func (*Builtin) UnifiesRecursively ¶
UnifiesRecursively returns true if a term in the given position will unify recursively, i.e., variables embedded inside a collection type will unify.
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 []error
// 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
// Exports contains a mapping of package paths to variables. The variables
// represent externally accessible symbols. For now the only type of
// externally visible symbol is a rule. For example:
//
// package a.b.c
//
// import data.e.f
//
// p = true :- q[x] = 1 # "p" is an export
// q[x] :- f.r[x], not f.m[x] # "q" is an export
//
// In this case, the mapping would be:
//
// {
// a.b.c: [p, q]
// }
Exports *util.HashMap
// Globals contains a mapping of modules to globally accessible variables
// within each module. Each variable is mapped to the value which represents
// the fully qualified name of the variable. For example:
//
// package a.b.c
//
// import data.e.f
// import y as z
//
// p = true :- q[x] = 1
// q[x] :- f.r[x], not f.m[x]
//
// In this case, the mapping would be
//
// {
// <modptr>: {q: data.a.b.c.q, f: data.e.f, p: data.a.b.c.p, z: y}
// }
Globals map[*Module]map[Var]Value
// 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
// 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 (*Compiler) Compile ¶
Compile runs the compilation process on the input modules. The output of the compilation process can be obtained from the Errors or Modules attributes of the Compiler.
func (*Compiler) FlattenErrors ¶
FlattenErrors returns a single message that contains a flattened version of the compiler error messages. This must only be called when the compilation process has failed.
type DocKind ¶
type DocKind int
DocKind represents the collection of document types that can be produced by rules.
type Expr ¶
type Expr struct {
Location *Location `json:"-"`
Negated bool `json:",omitempty"`
Terms interface{}
}
Expr represents a single expression contained inside the body of a rule.
func NewBuiltinExpr ¶
NewBuiltinExpr creates a new Expr object with the supplied terms. The builtin operator must be the first term.
func (*Expr) Complement ¶
Complement returns a copy of this expression with the negation flag flipped.
func (*Expr) Equal ¶
Equal returns true if this Expr equals the other Expr. Two expressions are considered equal if both expressions are negated (or not), are built-ins (or not), and have the same ordered terms.
func (*Expr) IsEquality ¶
IsEquality returns true if this is an equality expression.
func (*Expr) OutputVars ¶
OutputVars returns the set of variables that would be bound by evaluating this expression in isolation.
func (*Expr) UnmarshalJSON ¶
UnmarshalJSON parses the byte array and stores the result in expr.
type Import ¶
Import represents a dependency on a document outside of the policy namespace. Imports are optional.
type Location ¶
type Location struct {
Text []byte // 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
type Module ¶
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 ¶
MustParseModule returns a parsed module. If an error occurs during parsing, panic.
func ParseModule ¶
ParseModule returns a parsed Module object. For details on Module objects and their fields, see policy.go. Empty input will return nil, nil.
func ParseModuleFile ¶
ParseModuleFile returns a parsed Module object.
type ModuleTreeNode ¶
type ModuleTreeNode struct {
Key string
Modules []*Module
Children map[string]*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) 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.
type Number ¶
type Number float64
Number represents a numeric value as defined by JSON.
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) Equal ¶
Equal returns true if the other Value is an Object and the key/value pairs of the Other object are equal to the key/value pairs of this Object. The key/value pairs are ordered.
type Package ¶
Package represents the namespace of the documents produced by rules inside the module.
type QueryIterator ¶
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 MustParseRef ¶
MustParseRef returns a parsed reference. If an error occurs during parsing, panic.
func (Ref) Equal ¶
Equal returns true if the other Value is a Ref and the elements of the other Ref are equal to the this Ref.
func (Ref) Underlying ¶
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 ¶
MustParseRule returns a parsed rule. If an error occurs during parsing, panic.
func ParseRule ¶
ParseRule returns exactly one rule. If multiple rules are parsed, an error is returned.
func (*Rule) Equal ¶
Equal returns true if this Rule has the same name, arguments, and body as the other Rule.
type String ¶
type String string
String represents a string value as defined by JSON.
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 BooleanTerm ¶
BooleanTerm creates a new Term with a Boolean value.
func Item ¶
Item is a helper for constructing an tuple containing two Terms representing a key/value pair in an Object.
func MustParseTerm ¶
MustParseTerm returns a parsed term. If an error occurs during parsing, panic.
func NumberTerm ¶
NumberTerm creates a new Term with a Number value.
func ObjectTerm ¶
ObjectTerm creates a new Term with an Object value.
func ParseTerm ¶
ParseTerm returns exactly one term. If multiple terms are parsed, an error is returned.
func StringTerm ¶
StringTerm creates a new Term with a String value.
func (*Term) Equal ¶
Equal returns true if this term equals the other term. Equality is defined for each kind of term.
func (*Term) MarshalJSON ¶
MarshalJSON returns the JSON encoding of the term. Specialized marshalling logic is required to include a type hint for Value.
func (*Term) UnmarshalJSON ¶
UnmarshalJSON parses the byte array and stores the result in term. Specialized unmarshalling is required to handle Value.
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
type Var ¶
type Var string
Var represents a variable as defined by the language.
type VarSet ¶
type VarSet map[Var]struct{}
VarSet represents a set of variables.
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.
Source Files