rego_c.h File Reference

#include "version.h"

Include dependency graph for rego_c.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	REGO_OK   0
#define	REGO_ERROR   1
#define	REGO_ERROR_BUFFER_TOO_SMALL   2
#define	REGO_ERROR_INVALID_LOG_LEVEL   3
#define	REGO_ERROR_MANUAL_TZDATA_NOT_SUPPORTED   4
#define	REGO_NODE_BINDING   1000
#define	REGO_NODE_VAR   1001
#define	REGO_NODE_TERM   1002
#define	REGO_NODE_SCALAR   1003
#define	REGO_NODE_ARRAY   1004
#define	REGO_NODE_SET   1005
#define	REGO_NODE_OBJECT   1006
#define	REGO_NODE_OBJECT_ITEM   1007
#define	REGO_NODE_INT   1008
#define	REGO_NODE_FLOAT   1009
#define	REGO_NODE_STRING   1010
#define	REGO_NODE_TRUE   1011
#define	REGO_NODE_FALSE   1012
#define	REGO_NODE_NULL   1013
#define	REGO_NODE_UNDEFINED   1014
#define	REGO_NODE_TERMS   1015
#define	REGO_NODE_BINDINGS   1016
#define	REGO_NODE_RESULTS   1017
#define	REGO_NODE_RESULT   1018
#define	REGO_NODE_ERROR   1800
#define	REGO_NODE_ERROR_MESSAGE   1801
#define	REGO_NODE_ERROR_AST   1802
#define	REGO_NODE_ERROR_CODE   1803
#define	REGO_NODE_ERROR_SEQ   1804
#define	REGO_NODE_INTERNAL   1999
#define	REGO_LOG_LEVEL_NONE   0
#define	REGO_LOG_LEVEL_ERROR   1
#define	REGO_LOG_LEVEL_OUTPUT   2
#define	REGO_LOG_LEVEL_WARN   3
#define	REGO_LOG_LEVEL_INFO   4
#define	REGO_LOG_LEVEL_DEBUG   5
#define	REGO_LOG_LEVEL_TRACE   6

Typedefs
typedef void	regoInterpreter
typedef void	regoNode
typedef void	regoOutput
typedef unsigned int	regoEnum
typedef unsigned char	regoBoolean
typedef unsigned int	regoSize

Functions
regoEnum	regoSetLogLevel (regoEnum level)
regoEnum	regoSetLogLevelFromString (const char *level)
regoEnum	regoSetTZDataPath (const char *path)
regoInterpreter *	regoNew (void)
regoInterpreter *	regoNewV1 (void)
void	regoFree (regoInterpreter *rego)
regoEnum	regoAddModuleFile (regoInterpreter *rego, const char *path)
regoEnum	regoAddModule (regoInterpreter *rego, const char *name, const char *contents)
regoEnum	regoAddDataJSONFile (regoInterpreter *rego, const char *path)
regoEnum	regoAddDataJSON (regoInterpreter *rego, const char *contents)
regoEnum	regoSetInputJSONFile (regoInterpreter *rego, const char *path)
regoEnum	regoSetInputJSON (regoInterpreter *rego, const char *contents)
regoEnum	regoSetInputTerm (regoInterpreter *rego, const char *contents)
void	regoSetDebugEnabled (regoInterpreter *rego, regoBoolean enabled)
regoBoolean	regoGetDebugEnabled (regoInterpreter *rego)
regoEnum	regoSetDebugPath (regoInterpreter *rego, const char *path)
void	regoSetWellFormedChecksEnabled (regoInterpreter *rego, regoBoolean enabled)
regoBoolean	regoGetWellFormedChecksEnabled (regoInterpreter *rego)
regoOutput *	regoQuery (regoInterpreter *rego, const char *query_expr)
void	regoSetStrictBuiltInErrors (regoInterpreter *rego, regoBoolean enabled)
regoBoolean	regoGetStrictBuiltInErrors (regoInterpreter *rego)
const char *	regoGetError (regoInterpreter *rego)
regoBoolean	regoOutputOk (regoOutput *output)
regoSize	regoOutputSize (regoOutput *output)
regoNode *	regoOutputExpressionsAtIndex (regoOutput *output, regoSize index)
regoNode *	regoOutputExpressions (regoOutput *output)
regoNode *	regoOutputNode (regoOutput *output)
regoNode *	regoOutputBindingAtIndex (regoOutput *output, regoSize index, const char *name)
regoNode *	regoOutputBinding (regoOutput *output, const char *name)
const char *	regoOutputString (regoOutput *output)
void	regoFreeOutput (regoOutput *output)
regoEnum	regoNodeType (regoNode *node)
const char *	regoNodeTypeName (regoNode *node)
regoSize	regoNodeValueSize (regoNode *node)
regoEnum	regoNodeValue (regoNode *node, char *buffer, regoSize size)
regoSize	regoNodeSize (regoNode *node)
regoNode *	regoNodeGet (regoNode *node, regoSize index)
regoSize	regoNodeJSONSize (regoNode *node)
regoEnum	regoNodeJSON (regoNode *node, char *buffer, regoSize size)

Function Documentation

regoAddDataJSON()

regoEnum regoAddDataJSON	(	regoInterpreter *	rego,
		const char *	contents )

Adds a base document from the specified string.

The string should contain a single JSON object. The object will be parsed and merged with the interpreter's base document.

If an error code is returned, more error information can be obtained by calling regoGetError.

Parameters

rego	The interpreter.
contents	The contents of the JSON object.

Returns

REGO_OK if successful, REGO_ERROR otherwise.

regoAddDataJSONFile()

regoEnum regoAddDataJSONFile	(	regoInterpreter *	rego,
		const char *	path )

Adds a base document from the file at the specified path.

The file should contain a single JSON object. The object will be parsed and merged with the interpreter's base document.

If an error code is returned, more error information can be obtained by calling regoGetError.

Parameters

rego	The interpreter.
path	The path to the JSON file.

Returns

REGO_OK if successful, REGO_ERROR otherwise.

regoAddModule()

regoEnum regoAddModule	(	regoInterpreter *	rego,
		const char *	name,
		const char *	contents )

Adds a module (e.g. virtual document) from the specified string.

If an error code is returned, more error information can be obtained by calling regoGetError.

Parameters

rego	The interpreter.
name	The name of the module.
contents	The contents of the module.

Returns

REGO_OK if successful, REGO_ERROR otherwise.

regoAddModuleFile()

regoEnum regoAddModuleFile	(	regoInterpreter *	rego,
		const char *	path )

Adds a module (e.g. virtual document) from the file at the specified path.

If an error code is returned, more error information can be obtained by calling regoGetError.

Parameters

rego	The interpreter.
path	The path to the policy file.

Returns

REGO_OK if successful, REGO_ERROR otherwise.

regoFree()

void regoFree

(

regoInterpreter *

rego

)

Frees a Rego interpreter.

This pointer must have been allocated with regoNew.

Parameters

rego	The interpreter to free.

regoFreeOutput()

void regoFreeOutput

(

regoOutput *

output

)

Frees a Rego output.

This pointer must have been allocated with regoQuery.

Parameters

output

The output to free.

regoGetDebugEnabled()

regoBoolean regoGetDebugEnabled

(

regoInterpreter *

rego

)

Gets the debug mode of the interpreter.

Parameters

rego	The interpreter.

Returns

Whether debug mode is enabled.

regoGetError()

const char * regoGetError

(

regoInterpreter *

rego

)

Returns the most recently thrown error.

If an error code is returned from an interface function, more error information can be obtained by calling this function.

Parameters

rego	The interpreter.

Returns

The error message.

regoGetStrictBuiltInErrors()

regoBoolean regoGetStrictBuiltInErrors

(

regoInterpreter *

rego

)

Gets whether strict built-in errors are enabled.

Parameters

rego	The interpreter.

Returns

Whether strict built-in errors are enabled.

regoGetWellFormedChecksEnabled()

regoBoolean regoGetWellFormedChecksEnabled

(

regoInterpreter *

rego

)

Gets whether well-formed checks are enabled.

Parameters

rego	The interpreter.

Returns

Whether well-formed checks are enabled.

regoNew()

regoInterpreter * regoNew

(

void

)

Allocates and initializes a new Rego interpreter.

The caller is responsible for freeing the interpreter with regoFree.

Returns

A pointer to the new interpreter.

regoNewV1()

regoInterpreter * regoNewV1

(

void

)

Allocates and initializes a new V1 Rego interpreter.

The caller is responsible for freeing the interpreter with regoFree.

Returns

A pointer to the new V1 interpreter.

regoNodeGet()

regoNode * regoNodeGet	(	regoNode *	node,
		regoSize	index )

Returns the child node at the specified index.

Parameters

node	The node.
index	The index of the child.

Returns

The child node.

regoNodeJSON()

regoEnum regoNodeJSON	(	regoNode *	node,
		char *	buffer,
		regoSize	size )

Populate a buffer with the JSON representation of the node.

The buffer must be large enough to hold the value. The size of the buffer can be determined by calling regoNodeJSONSize.

Parameters

node	The node.
buffer	The buffer to populate.
size	The size of the buffer.

Returns

REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.

regoNodeJSONSize()

regoSize regoNodeJSONSize

(

regoNode *

node

)

Returns the number of bytes needed to store a 0-terminated string representing the JSON representation of the node.

The value returned by this function can be used to allocate a buffer to pass to regoNodeJSON.

Parameters

node

The node.

Returns

The number of bytes needed to store the JSON representation.

regoNodeSize()

regoSize regoNodeSize

(

regoNode *

node

)

Returns the number of children of the node.

Parameters

node

The node.

Returns

The number of children.

regoNodeType()

regoEnum regoNodeType

(

regoNode *

node

)

Returns an enumeration value indicating the nodes type.

This type will be one of the following values:

Name	Description
REGO_NODE_BINDING	A binding. Will have two children, a REGO_NODE_VAR and a REGO_NODE_TERM
REGO_NODE_VAR	A variable name.
REGO_NODE_TERM	A term. Will have one child of: REGO_NODE_SCALAR, REGO_NODE_ARRAY, REGO_NODE_SET, REGO_NODE_OBJECT
REGO_NODE_SCALAR	A scalar value. Will have one child of: REGO_NODE_INT, REGO_NODE_FLOAT, REGO_NODE_STRING, REGO_NODE_TRUE, REGO_NODE_FALSE, REGO_NODE_NULL, REGO_NODE_UNDEFINED
REGO_NODE_ARRAY	An array. Will have one or more children of: REGO_NODE_TERM
REGO_NODE_SET	A set. Will have one or more children of: REGO_NODE_TERM
REGO_NODE_OBJECT	An object. Will have one or more children of: REGO_NODE_OBJECT_ITEM
REGO_NODE_OBJECT_ITEM	An object item. Will have two children, a REGO_NODE_TERM (the key) and a REGO_NODE_TERM (the value)
REGO_NODE_INT	An integer value.
REGO_NODE_FLOAT	A floating point value.
REGO_NODE_STRING	A string value.
REGO_NODE_TRUE	A true value.
REGO_NODE_FALSE	A false value.
REGO_NODE_NULL	A null value.
REGO_NODE_UNDEFINED	An undefined value.
REGO_NODE_ERROR	An error. Will have three children: REGO_NODE_ERROR_MESSAGE, REGO_NODE_ERROR_AST, and REGO_NODE_ERROR_CODE
REGO_NODE_ERROR_MESSAGE	An error message.
REGO_NODE_ERROR_AST	An error AST.
REGO_NODE_ERROR_CODE	An error code.
REGO_NODE_ERROR_SEQ	An error sequence. Will have one or more children of: REGO_NODE_ERROR
REGO_NODE_INTERNAL	An internal node. Use regoNodeTypeName to get the full value.

Returns

The node type.

regoNodeTypeName()

const char * regoNodeTypeName

(

regoNode *

node

)

Returns the name of the node type as a human-readable string.

This function supports arbitrary nodes (i.e. it will always produce a value) including internal nodes which appear in error messages.

Parameters

node

The node.

Returns

The node type name.

regoNodeValue()

regoEnum regoNodeValue	(	regoNode *	node,
		char *	buffer,
		regoSize	size )

Populate a buffer with the node value.

The buffer must be large enough to hold the value. The size of the buffer can be determined by calling regoNodeValueSize.

Parameters

node	The node.
buffer	The buffer to populate.
size	The size of the buffer.

Returns

REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.

regoNodeValueSize()

regoSize regoNodeValueSize

(

regoNode *

node

)

Returns the number of bytes needed to store a 0-terminated string representing the text value of the node.

The value returned by this function can be used to allocate a buffer to pass to regoNodeValue.

Parameters

node

The node.

Returns

The number of bytes needed to store the text value.

regoOutputBinding()

regoNode * regoOutputBinding	(	regoOutput *	output,
		const char *	name )

Returns the bound value for a given variable name at the first index.

If the variable is not bound, then this function will return NULL.

Parameters

output	The output.
name	The variable name.

Returns

The bound value (or NULL if the variable was not bound)

regoOutputBindingAtIndex()

regoNode * regoOutputBindingAtIndex	(	regoOutput *	output,
		regoSize	index,
		const char *	name )

Returns the bound value for a given variable name.

If the variable is not bound, then this function will return NULL.

Parameters

output	The output.
index	The result index.
name	The variable name.

Returns

The bound value (or NULL if the variable was not bound)

regoOutputExpressions()

regoNode * regoOutputExpressions

(

regoOutput *

output

)

Returns a node containing a list of terms resulting from the query at the default index.

Parameters

output

The output.

Returns

The output node.

regoOutputExpressionsAtIndex()

regoNode * regoOutputExpressionsAtIndex	(	regoOutput *	output,
		regoSize	index )

Returns a node containing a list of terms resulting from the query at the specified index.

Parameters

output	The output.
index	The result index.

Returns

The output node.

regoOutputNode()

regoNode * regoOutputNode

(

regoOutput *

output

)

Returns the node containing the output of the query.

This will either be a node which contains one or more results, or an error sequence.

Parameters

output

The output.

Returns

The output node.

regoOutputOk()

regoBoolean regoOutputOk

(

regoOutput *

output

)

Returns whether the output is ok.

If the output resulted in a valid query result, then this function will return true. Otherwise, it will return false, indicating that the output contains an error sequence.

Parameters

output

The output.

Returns

Whether the output is ok.

regoOutputSize()

regoSize regoOutputSize

(

regoOutput *

output

)

Returns the number of results in the output.

Each query can potentially generate multiple results. This function returns the number of results in the output.

regoOutputString()

const char * regoOutputString

(

regoOutput *

output

)

Returns the output represented as a human-readable string.

Parameters

output

The output.

Returns

The output string.

regoQuery()

regoOutput * regoQuery	(	regoInterpreter *	rego,
		const char *	query_expr )

Performs a query against the current base and virtual documents.

The query expression should be a Rego query. The output of the query will be returned as a regoOutput object. The caller is responsible for freeing the output object with regoFreeOutput.

Parameters

rego	The interpreter.
query_expr	The query expression.

Returns

The output of the query.

regoSetDebugEnabled()

void regoSetDebugEnabled	(	regoInterpreter *	rego,
		regoBoolean	enabled )

Sets the debug mode of the interpreter.

When debug mode is enabled, the interpreter will output intermediary ASTs after each compiler pass to the debug directory and output pass information to stdout. This is mostly useful for creating reports for compiler issues, but can also be of use in understanding why a policy is invalid or is behaving unexpectedly.

Parameters

rego	The interpreter.
enabled	Whether debug mode should be enabled.

regoSetDebugPath()

regoEnum regoSetDebugPath	(	regoInterpreter *	rego,
		const char *	path )

Sets the path to the debug directory.

If set, then (when in debug mode) the interpreter will output intermediary ASTs after each compiler pass to the debug directory. If the directory does not exist, it will be created.

If an error code is returned, more error information can be obtained by calling regoGetError.

Parameters

rego	The interpreter.
path	The path to the debug directory.

Returns

REGO_OK if successful, REGO_ERROR otherwise.

regoSetInputJSON()

regoEnum regoSetInputJSON	(	regoInterpreter *	rego,
		const char *	contents )

Sets the current input document from the specified string.

The string should contain a single JSON value. The value will be parsed and set as the interpreter's input document.

If an error code is returned, more error information can be obtained by calling regoGetError.

Deprecated

This method's name is misleading, as the input term can be any valid Rego (i.e. not just JSON). Please use the updated version regoSetInputTerm.

Parameters

rego	The interpreter.
contents	The contents of the JSON value.

Returns

REGO_OK if successful, REGO_ERROR otherwise.

regoSetInputJSONFile()

regoEnum regoSetInputJSONFile	(	regoInterpreter *	rego,
		const char *	path )

Sets the current input document from the file at the specified path.

The file should contain a single JSON value. The value will be parsed and set as the interpreter's input document.

If an error code is returned, more error information can be obtained by calling regoGetError.

Parameters

rego	The interpreter.
path	The path to the JSON file.

Returns

REGO_OK if successful, REGO_ERROR otherwise.

regoSetInputTerm()

regoEnum regoSetInputTerm	(	regoInterpreter *	rego,
		const char *	contents )

Sets the current input document from the specified string.

The string should contain a single Rego data term. The value will be parsed and set as the interpreter's input document.

If an error code is returned, more error information can be obtained by calling regoGetError.

Parameters

rego	The interpreter.
contents	The contents of the Rego data term.

Returns

REGO_OK if successful, REGO_ERROR otherwise.

regoSetLogLevel()

regoEnum regoSetLogLevel

(

regoEnum

level

)

Sets the level of logging.

This setting controls the amount of logging that will be output to stdout. The default level is REGO_LOG_LEVEL_NONE.

Parameters

level

One of the following values: REGO_LOG_LEVEL_NONE, REGO_LOG_LEVEL_ERROR, REGO_LOG_LEVEL_OUTPUT, REGO_LOG_LEVEL_WARN, REGO_LOG_LEVEL_INFO, REGO_LOG_LEVEL_DEBUG, REGO_LOG_LEVEL_TRACE.

Returns

REGO_OK if successful, REGO_ERROR_INVALID_LOG_LEVEL otherwise.

regoSetLogLevelFromString()

regoEnum regoSetLogLevelFromString

(

const char *

level

)

Sets the level of logging.

This setting controls the amount of logging that will be output to stdout. The default level is REGO_LOG_LEVEL_NONE.

Parameters

level

One of the following strings: "None", "Error", "Output", "Warn", "Info", "Debug", "Trace".

Returns

REGO_OK if successful, REGO_ERROR_INVALID_LOG_LEVEL otherwise.

regoSetStrictBuiltInErrors()

void regoSetStrictBuiltInErrors	(	regoInterpreter *	rego,
		regoBoolean	enabled )

Sets whether the built-ins should throw errors.

When strict built-in errors are enabled, built-in functions will throw errors when they encounter invalid input. When disabled, built-in functions will return undefined when they encounter invalid input.

Parameters

rego	The interpreter.
enabled	Whether strict built-in errors should be enabled.

regoSetTZDataPath()

regoEnum regoSetTZDataPath

(

const char *

path

)

Sets the location where rego-cpp will look for timezone database information.

The timezone database will be interpreted as one obtained from the IANA (https://www.iana.org/time-zones) which has been downloaded and unpacked into at the path provided. If the library was built without manual tzdata support, this function will return an error code.

Parameters

path	The path to the timezone database.

Returns

REGO_OK if successful, REGO_ERROR_MANUAL_TZDATA_NOT_SUPPORTED otherwise.

regoSetWellFormedChecksEnabled()

void regoSetWellFormedChecksEnabled	(	regoInterpreter *	rego,
		regoBoolean	enabled )

Sets whether to perform well-formed checks after each compiler pass.

The interpreter has a set of well-formness definitions which indicate the expected form of the AST before and after each compiler pass. This setting determines whether the interpreter will perform these intermediary checks.

Parameters

rego	The interpreter.
enabled	Whether well-formed checks should be enabled.