ir

Documentation

Overview

Package ir defines an intermediate representation (IR) for Rego.

The IR specifies an imperative execution model for Rego policies similar to a query plan in traditional databases.

Index

• func Pretty(w io.Writer, x interface{}) error
• func Walk(vis Visitor, x interface{}) error
• type ArrayAppendStmt
• type AssignIntStmt
• type AssignVarOnceStmt
• type AssignVarStmt
• type Block
  • func (a *Block) String() string
• type BlockStmt
  • func (a *BlockStmt) String() string
• type Bool
  • func (b Bool) String() string
• type BooleanConst
• type BreakStmt
• type BuiltinFunc
• type CallDynamicStmt
• type CallStmt
• type Const
• type DotStmt
• type EqualStmt
• type FloatConst
• type Func
  • func (a *Func) String() string
• type Funcs
  • func (a *Funcs) String() string
• type IntConst
• type IsArrayStmt
• type IsDefinedStmt
• type IsObjectStmt
• type IsUndefinedStmt
• type LenStmt
• type Local
  • func (l Local) String() string
• type LocalOrConst
• type Location
  • func (l *Location) GetLocation() *Location
  • func (l *Location) SetLocation(index, row, col int, file, text string)
• type MakeArrayStmt
• type MakeNullStmt
• type MakeNumberFloatStmt
• type MakeNumberIntStmt
• type MakeNumberRefStmt
• type MakeObjectStmt
• type MakeSetStmt
• type NopStmt
• type NotEqualStmt
• type NotStmt
• type NullConst
• type ObjectInsertOnceStmt
• type ObjectInsertStmt
• type ObjectMergeStmt
• type Plan
  • func (a *Plan) String() string
• type Plans
• type Policy
  • func (a *Policy) String() string
• type ResetLocalStmt
• type ResultSetAdd
• type ReturnLocalStmt
• type ScanStmt
• type SetAddStmt
• type Static
  • func (a *Static) String() string
• type Stmt
• type StringConst
• type StringIndex
  • func (s StringIndex) String() string
• type Visitor
• type WithStmt

Functions

func Pretty

func Pretty(w io.Writer, x interface{}) error

Pretty writes a human-readable representation of an IR object to w.

func Walk

func Walk(vis Visitor, x interface{}) error

Walk invokes the visitor for nodes under x.

Types

type ArrayAppendStmt

type ArrayAppendStmt struct {
	Value LocalOrConst
	Array Local

	Location
}

ArrayAppendStmt represents a dynamic append operation of a value onto an array.

type AssignIntStmt

type AssignIntStmt struct {
	Value  int64
	Target Local

	Location
}

AssignIntStmt represents an assignment of an integer value to a local variable.

type AssignVarOnceStmt

type AssignVarOnceStmt struct {
	Target Local
	Source LocalOrConst

	Location
}

AssignVarOnceStmt represents an assignment of one local variable to another. If the target is defined, execution aborts with a conflict error.

TODO(tsandall): is there a better name for this?

type AssignVarStmt

type AssignVarStmt struct {
	Source LocalOrConst
	Target Local

	Location
}

AssignVarStmt represents an assignment of one local variable to another.

type Block

type Block struct {
	Stmts []Stmt
}

Block represents an ordered sequence of statements to execute. Blocks are executed until a return statement is encountered, a statement is undefined, or there are no more statements. If all statements are defined but no return statement is encountered, the block is undefined.

func (*Block) String

func (a *Block) String() string

type BlockStmt

type BlockStmt struct {
	Blocks []*Block

	Location
}

BlockStmt represents a nested block. Nested blocks and break statements can be used to short-circuit execution.

func (*BlockStmt) String

func (a *BlockStmt) String() string

type Bool

type Bool bool

Bool represents a constant boolean.

func (Bool) String

func (b Bool) String() string

type BooleanConst

type BooleanConst struct {
	Value bool
}

BooleanConst represents a boolean value.

type BreakStmt

type BreakStmt struct {
	Index uint32

	Location
}

BreakStmt represents a jump out of the current block. The index specifies how many blocks to jump starting from zero (the current block). Execution will continue from the end of the block that is jumped to.

type BuiltinFunc

type BuiltinFunc struct {
	Name string
}

BuiltinFunc represents a built-in function that may be required by the policy.

type CallDynamicStmt

type CallDynamicStmt struct {
	Args   []Local
	Result Local
	Path   []LocalOrConst

	Location
}

CallDynamicStmt represents an indirect (data) function call. The result should be stored in the result local.

type CallStmt

type CallStmt struct {
	Func   string
	Args   []LocalOrConst
	Result Local

	Location
}

CallStmt represents a named function call. The result should be stored in the result local.

type Const

type Const interface {
	// contains filtered or unexported methods
}

Const represents a constant value from the policy.

type DotStmt

type DotStmt struct {
	Source LocalOrConst
	Key    LocalOrConst
	Target Local

	Location
}

DotStmt represents a lookup operation on a value (e.g., array, object, etc.) The source of a DotStmt may be a scalar value in which case the statement will be undefined.

type EqualStmt

type EqualStmt struct {
	A LocalOrConst
	B LocalOrConst

	Location
}

EqualStmt represents an value-equality check of two local variables.

type FloatConst

type FloatConst struct {
	Value float64
}

FloatConst represents a floating-point constant.

type Func

type Func struct {
	Name   string
	Params []Local
	Return Local
	Blocks []*Block // TODO(tsandall): should this be a plan?
	Path   []string // optional: if non-nil, include in data function tree
}

Func represents a named plan (function) that can be invoked. Functions accept one or more parameters and return a value. By convention, the input document and data documents are always passed as the first and second arguments (respectively).

func (*Func) String

func (a *Func) String() string

type Funcs

type Funcs struct {
	Funcs []*Func
}

Funcs represents a collection of planned functions to include in the policy.

func (*Funcs) String

func (a *Funcs) String() string

type IntConst

type IntConst struct {
	Value int64
}

IntConst represents an integer constant.

type IsArrayStmt

type IsArrayStmt struct {
	Source LocalOrConst

	Location
}

IsArrayStmt represents a dynamic type check on a local variable.

type IsDefinedStmt

type IsDefinedStmt struct {
	Source Local

	Location
}

IsDefinedStmt represents a check of whether a local variable is defined.

type IsObjectStmt

type IsObjectStmt struct {
	Source LocalOrConst

	Location
}

IsObjectStmt represents a dynamic type check on a local variable.

type IsUndefinedStmt

type IsUndefinedStmt struct {
	Source Local

	Location
}

IsUndefinedStmt represents a check of whether local variable is undefined.

type LenStmt

type LenStmt struct {
	Source LocalOrConst
	Target Local

	Location
}

LenStmt represents a length() operation on a local variable. The result is stored in the target local variable.

type Local

type Local int

Local represents a plan-scoped variable.

TODO(tsandall): should this be int32 for safety?

const (
	// Input is the local variable that refers to the global input document.
	Input Local = iota

	// Data is the local variable that refers to the global data document.
	Data

	// Unused is the free local variable that can be allocated in a plan.
	Unused
)

func (Local) String

func (l Local) String() string

type LocalOrConst

type LocalOrConst interface {
	fmt.Stringer
	// contains filtered or unexported methods
}

LocalOrConst is a tagged union of the two types, Local and StringIndex.

type Location

type Location struct {
	Index    int // filename string constant index
	Col, Row int
	// contains filtered or unexported fields
}

Location records the filen index, and the row and column inside that file that a statement can be connected to.

func (*Location) GetLocation

func (l *Location) GetLocation() *Location

GetLocation returns a Stmt's Location.

func (*Location) SetLocation

func (l *Location) SetLocation(index, row, col int, file, text string)

SetLocation sets the Location for a given Stmt.

type MakeArrayStmt

type MakeArrayStmt struct {
	Capacity int32
	Target   Local

	Location
}

MakeArrayStmt constructs a local variable that refers to an array value.

type MakeNullStmt

type MakeNullStmt struct {
	Target Local

	Location
}

MakeNullStmt constructs a local variable that refers to a null value.

type MakeNumberFloatStmt

type MakeNumberFloatStmt struct {
	Value  float64
	Target Local

	Location
}

MakeNumberFloatStmt constructs a local variable that refers to a floating-point number value.

type MakeNumberIntStmt

type MakeNumberIntStmt struct {
	Value  int64
	Target Local

	Location
}

MakeNumberIntStmt constructs a local variable that refers to an integer value.

type MakeNumberRefStmt

type MakeNumberRefStmt struct {
	Index  int
	Target Local

	Location
}

MakeNumberRefStmt constructs a local variable that refers to a number stored as a string.

type MakeObjectStmt

type MakeObjectStmt struct {
	Target Local

	Location
}

MakeObjectStmt constructs a local variable that refers to an object value.

type MakeSetStmt

type MakeSetStmt struct {
	Target Local

	Location
}

MakeSetStmt constructs a local variable that refers to a set value.

type NopStmt

type NopStmt struct {
	Location
}

NopStmt adds a nop instruction. Useful during development and debugging only.

type NotEqualStmt

type NotEqualStmt struct {
	A LocalOrConst
	B LocalOrConst

	Location
}

NotEqualStmt represents a != check of two local variables.

type NotStmt

type NotStmt struct {
	Block *Block

	Location
}

NotStmt represents a negated statement.

type NullConst

type NullConst struct{}

NullConst represents a null value.

type ObjectInsertOnceStmt

type ObjectInsertOnceStmt struct {
	Key    LocalOrConst
	Value  LocalOrConst
	Object Local

	Location
}

ObjectInsertOnceStmt represents a dynamic insert operation of a key/value pair into an object. If the key already exists and the value differs, execution aborts with a conflict error.

type ObjectInsertStmt

type ObjectInsertStmt struct {
	Key    LocalOrConst
	Value  LocalOrConst
	Object Local

	Location
}

ObjectInsertStmt represents a dynamic insert operation of a key/value pair into an object.

type ObjectMergeStmt

type ObjectMergeStmt struct {
	A      Local
	B      Local
	Target Local

	Location
}

ObjectMergeStmt performs a recursive merge of two object values. If either of the locals refer to non-object values this operation will abort with a conflict error. Overlapping object keys are merged recursively.

type Plan

type Plan struct {
	Name   string
	Blocks []*Block
}

Plan represents an ordered series of blocks to execute. Plan execution stops when a return statement is reached. Blocks are executed in-order.

func (*Plan) String

func (a *Plan) String() string

type Plans

type Plans struct {
	Plans []*Plan
}

Plans represents a collection of named query plans to expose in the policy.

type Policy

type Policy struct {
	Static *Static
	Plans  *Plans
	Funcs  *Funcs
}

Policy represents a planned policy query.

func (*Policy) String

func (a *Policy) String() string

type ResetLocalStmt

type ResetLocalStmt struct {
	Target Local

	Location
}

ResetLocalStmt resets a local variable to 0.

type ResultSetAdd

type ResultSetAdd struct {
	Value Local

	Location
}

ResultSetAdd adds a value into the result set returned by the query plan.

type ReturnLocalStmt

type ReturnLocalStmt struct {
	Source Local

	Location
}

ReturnLocalStmt represents a return statement that yields a local value.

type ScanStmt

type ScanStmt struct {
	Source Local
	Key    Local
	Value  Local
	Block  *Block

	Location
}

ScanStmt represents a linear scan over a composite value. The source may be a scalar in which case the block will never execute.

type SetAddStmt

type SetAddStmt struct {
	Value LocalOrConst
	Set   Local

	Location
}

SetAddStmt represents a dynamic add operation of an element into a set.

type Static

type Static struct {
	Strings      []*StringConst
	BuiltinFuncs []*BuiltinFunc
	Files        []*StringConst
}

Static represents a static data segment that is indexed into by the policy.

func (*Static) String

func (a *Static) String() string

type Stmt

type Stmt interface {
	// contains filtered or unexported methods
}

Stmt represents an operation (e.g., comparison, loop, dot, etc.) to execute.

type StringConst

type StringConst struct {
	Value string
}

StringConst represents a string value.

type StringIndex

type StringIndex int

StringIndex represents the index into the plan's list of constant strings of a constant string.

func (StringIndex) String

func (s StringIndex) String() string

type Visitor

type Visitor interface {
	Before(x interface{})
	Visit(x interface{}) (Visitor, error)
	After(x interface{})
}

Visitor defines the interface for visiting IR nodes.

type WithStmt

type WithStmt struct {
	Local Local
	Path  []int
	Value LocalOrConst
	Block *Block

	Location
}

WithStmt replaces the Local or a portion of the document referred to by the Local with the Value and executes the contained block. If the Path is non-empty, the Value is upserted into the Local. If the intermediate nodes in the Local referred to by the Path do not exist, they will be created. When the WithStmt finishes the Local is reset to it's original value.