#include "version.h"

Include dependency graph for rego_c.h:

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

Macros
#define	REGO_OK 0

#define	REGO_ERROR 1

#define	REGO_ERROR_BUFFER_TOO_SMALL 2

#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_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_WARN 2

#define	REGO_LOG_LEVEL_INFO 3

#define	REGO_LOG_LEVEL_DEBUG 4

#define	REGO_LOG_LEVEL_TRACE 5

Typedefs
typedef void	regoInterpreter

typedef void	regoNode

typedef void	regoOutput

typedef unsigned int	regoEnum

typedef unsigned char	regoBoolean

typedef unsigned int	regoSize

Functions
void	regoSetLogLevel (regoEnum level)

regoInterpreter *	regoNew ()

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)

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)

regoNode *	regoOutputNode (regoOutput *output)

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

Allocates and initializes a new Rego interpreter.

The caller is responsible for freeing the interpreter with regoFree.

Returns: A pointer to the new 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.

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)

◆ regoOutputNode()

regoNode * regoOutputNode ( regoOutput * output )

Returns the node containing the output of the query.

This will either be a node which contains sequence of terms and/or bindings, 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.

◆ 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.

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.

◆ regoSetLogLevel()

void 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_WARN, REGO_LOG_LEVEL_INFO, REGO_LOG_LEVEL_DEBUG, REGO_LOG_LEVEL_TRACE.

◆ 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.

◆ 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.

Macros

Typedefs

Functions

Function Documentation

◆ regoAddDataJSON()

◆ regoAddDataJSONFile()

◆ regoAddModule()

◆ regoAddModuleFile()

◆ regoFree()

◆ regoFreeOutput()

◆ regoGetDebugEnabled()

◆ regoGetError()

◆ regoGetStrictBuiltInErrors()

◆ regoGetWellFormedChecksEnabled()

◆ regoNew()

◆ regoNodeGet()

◆ regoNodeJSON()

◆ regoNodeJSONSize()

◆ regoNodeSize()

◆ regoNodeType()

◆ regoNodeTypeName()

◆ regoNodeValue()

◆ regoNodeValueSize()

◆ regoOutputBinding()

◆ regoOutputNode()

◆ regoOutputOk()

◆ regoOutputString()

◆ regoQuery()

◆ regoSetDebugEnabled()

◆ regoSetDebugPath()

◆ regoSetInputJSON()

◆ regoSetInputJSONFile()

◆ regoSetLogLevel()

◆ regoSetStrictBuiltInErrors()

◆ regoSetWellFormedChecksEnabled()