#include "version.h"
#include <stdint.h>

Include dependency graph for rego_c.h:

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

Macros
#define	REGO_API(x)
	Macro for exporting functions from a shared library on other platforms.

Typedefs
typedef void	regoInterpreter
	Opaque interpreter type.

typedef void	regoNode
	Opaque node type.

typedef void	regoOutput
	Opaque output type.

typedef void	regoBundle
	Opaque bundle type.

typedef void	regoInput
	Opaque input type.

typedef uint_least8_t	regoBoolean
	Boolean type.

typedef uint_least32_t	regoEnum
	Enum type.

typedef uint_least32_t	regoSize
	Size type.

typedef int_least64_t	regoInt
	Integer type.

typedef uint_least32_t	regoType
	Node Type type.

Functions
regoSize	regoBuildInfoSize (void)
	Returns the number of bytes needed to store a 0-terminated string representing the build info.

regoEnum	regoBuildInfo (char *buffer, regoSize size)
	Populate a buffer with a string of the form "VERSION (BUILD_NAME, BUILD_DATE) BUILD_TOOLCHAIN on PLATFORM".

regoSize	regoVersionSize (void)
	Returns the number of bytes needed to store a 0-terminated string representing version.

regoEnum	regoVersion (char *buffer, regoSize size)
	Populate a buffer with a string representing the semantic version of the library.

regoEnum	regoLogLevelFromString (const char *level)
	Gets a log level constant value from a string (case-invariant).

regoEnum	regoSetLogLevel (regoInterpreter *rego, regoEnum level)
	Sets the level of logging on the interpreter.

regoEnum	regoSetDefaultLogLevel (regoEnum level)
	Sets the default level of logging.

regoEnum	regoGetLogLevel (regoInterpreter *rego)
	Gets the level of logging on the interpreter.

regoInterpreter *	regoNew (void)
	Allocates and initializes a new Rego interpreter.

void	regoFree (regoInterpreter *rego)
	Frees a Rego interpreter.

regoEnum	regoAddModuleFile (regoInterpreter rego, const char path)
	Adds a module (e.g. virtual document) from the file at the specified path.

regoEnum	regoAddModule (regoInterpreter rego, const char name, const char *contents)
	Adds a module (e.g. virtual document) from the specified string.

regoEnum	regoAddDataJSONFile (regoInterpreter rego, const char path)
	Adds a base document from the file at the specified path.

regoEnum	regoAddDataJSON (regoInterpreter rego, const char contents)
	Adds a base document from the specified string.

regoEnum	regoSetInputJSONFile (regoInterpreter rego, const char path)
	Sets the current input document from the file at the specified path.

regoEnum	regoSetInputTerm (regoInterpreter rego, const char contents)
	Sets the current input document from the specified string.

regoEnum	regoSetInput (regoInterpreter rego, regoInput input)
	Sets the current input document from the specified Input object.

void	regoSetDebugEnabled (regoInterpreter *rego, regoBoolean enabled)
	Sets the debug mode of the interpreter.

regoBoolean	regoGetDebugEnabled (regoInterpreter *rego)
	Gets the debug mode of the interpreter.

regoEnum	regoSetDebugPath (regoInterpreter rego, const char path)
	Sets the path to the debug directory.

void	regoSetWellFormedChecksEnabled (regoInterpreter *rego, regoBoolean enabled)
	Sets whether to perform well-formedness checks after each compiler pass.

regoBoolean	regoGetWellFormedChecksEnabled (regoInterpreter *rego)
	Gets whether well-formedness checks are enabled.

regoOutput *	regoQuery (regoInterpreter rego, const char query_expr)
	Performs a query against the current base and virtual documents.

void	regoSetStrictBuiltInErrors (regoInterpreter *rego, regoBoolean enabled)
	Sets whether the built-ins should throw errors.

regoBoolean	regoGetStrictBuiltInErrors (regoInterpreter *rego)
	Gets whether strict built-in errors are enabled.

regoBoolean	regoIsAvailableBuiltIn (regoInterpreter rego, const char name)
	Returns whether the specified name corresponds to an available built-in in the interpreter.

regoSize	regoErrorSize (regoInterpreter *rego)
	Returns the number of bytes needed to store a 0-terminated string representing the most recent error message.

regoEnum	regoError (regoInterpreter rego, char buffer, regoSize size)
	Populate a buffer with the most recent error message.

regoEnum	regoSetQuery (regoInterpreter rego, const char query_expr)
	Sets the query for the interpreter.

regoEnum	regoAddEntrypoint (regoInterpreter rego, const char entrypoint)
	Adds an entrypoint to the interpreter.

regoBundle *	regoBuild (regoInterpreter *rego)
	Builds a compiled Rego bundle.

regoBundle *	regoBundleLoad (regoInterpreter rego, const char dir)
	Loads a compiled Rego bundle from the specified directory.

regoBundle *	regoBundleLoadBinary (regoInterpreter rego, const char path)
	Loads a compiled Rego bundle from the specified binary file.

regoEnum	regoBundleSave (regoInterpreter rego, const char dir, regoBundle *bundle)
	Saves a compiled Rego bundle to the specified directory.

regoEnum	regoBundleSaveBinary (regoInterpreter rego, const char path, regoBundle *bundle)
	Saves a compiled Rego bundle to the specified binary file.

regoOutput *	regoBundleQuery (regoInterpreter rego, regoBundle bundle)
	Performs a query against the specified bundle.

regoOutput *	regoBundleQueryEntrypoint (regoInterpreter rego, regoBundle bundle, const char *endpoint)
	Performs a query against the specified bundle at the specified entrypoint.

regoBoolean	regoOutputOk (regoOutput *output)
	Returns whether the output is ok.

regoSize	regoOutputSize (regoOutput *output)
	Returns the number of results in the output.

regoNode *	regoOutputExpressionsAtIndex (regoOutput *output, regoSize index)
	Returns a node containing a list of terms resulting from the query at the specified index.

regoNode *	regoOutputExpressions (regoOutput *output)
	Returns a node containing a list of terms resulting from the query at the default index.

regoNode *	regoOutputNode (regoOutput *output)
	Returns the node containing the output of the query.

regoNode *	regoOutputBindingAtIndex (regoOutput output, regoSize index, const char name)
	Returns the bound value for a given variable name.

regoNode *	regoOutputBinding (regoOutput output, const char name)
	Returns the bound value for a given variable name at the first index.

regoSize	regoOutputJSONSize (regoOutput *output)
	Returns the number of bytes needed to store a 0-terminated string representing the output as a human-readable string.

regoEnum	regoOutputJSON (regoOutput output, char buffer, regoSize size)
	Populate a buffer with the output represented as a human-readable string.

void	regoFreeOutput (regoOutput *output)
	Frees a Rego output.

regoType	regoNodeType (regoNode *node)
	Returns an enumeration value indicating the node's type.

regoEnum	regoNodeTypeNameSize (regoNode *node)
	Returns the number of bytes needed to store a 0-terminated string representing the name of the node type.

regoEnum	regoNodeTypeName (regoNode node, char buffer, regoSize size)
	Returns the name of the node type as a human-readable string.

regoSize	regoNodeValueSize (regoNode *node)
	Returns the number of bytes needed to store a 0-terminated string representing the text value of the node.

regoEnum	regoNodeValue (regoNode node, char buffer, regoSize size)
	Populate a buffer with the node value.

regoSize	regoNodeSize (regoNode *node)
	Returns the number of children of the node.

regoNode *	regoNodeGet (regoNode *node, regoSize index)
	Returns the child node at the specified index.

regoSize	regoNodeJSONSize (regoNode *node)
	Returns the number of bytes needed to store a 0-terminated string representing the JSON representation of the node.

regoEnum	regoNodeJSON (regoNode node, char buffer, regoSize size)
	Populate a buffer with the JSON representation of the node.

regoInput *	regoNewInput ()
	Allocates and initializes a new Rego Input object.

regoEnum	regoInputInt (regoInput *input, regoInt value)
	Adds an integer value to the input object.

regoEnum	regoInputFloat (regoInput *input, double value)
	Adds a floating point value to the input object.

regoEnum	regoInputString (regoInput input, const char value)
	Adds a string value to the input object.

regoEnum	regoInputBoolean (regoInput *input, regoBoolean value)
	Adds a boolean value to the input object.

regoEnum	regoInputNull (regoInput *input)
	Adds a null value to the input object.

regoEnum	regoInputObjectItem (regoInput *input)
	Uses the top two values on the stack to create an object item and pushes it back onto the stack.

regoEnum	regoInputObject (regoInput *input, regoSize count)
	Uses the top 'count' values on the stack to create an object and pushes it back onto the stack.

regoEnum	regoInputArray (regoInput *input, regoSize count)
	Uses the top 'count' values on the stack to create an array and pushes it back onto the stack.

regoEnum	regoInputSet (regoInput *input, regoSize count)
	Uses the top 'count' values on the stack to create a set and pushes it back onto the stack.

regoEnum	regoInputValidate (regoInput *input)
	Validates the input object.

regoNode *	regoInputNode (regoInput *input)
	Returns the top of the Input stack.

regoSize	regoInputSize (regoInput *input)
	Returns the number of items on the Input stack.

void	regoFreeInput (regoInput *input)
	Frees a Rego Input object.

regoBoolean	regoBundleOk (regoBundle *bundle)
	Returns whether the bundle is ok.

regoNode *	regoBundleNode (regoBundle *bundle)
	Returns a node containing the base document of the bundle.

void	regoFreeBundle (regoBundle *bundle)
	Frees a Rego bundle.

Macro Definition Documentation

◆ REGO_API

#define REGO_API ( x )

Value:

x

Macro for exporting functions from a shared library on other platforms.

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

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

Parameters

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

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoAddEntrypoint()

regoEnum regoAddEntrypoint	(	regoInterpreter *	rego,
		const char *	entrypoint )

Adds an entrypoint to the interpreter.

By using this method, an entrypoint can be added to the list of those with compiled execution plans in a bundle.

Parameters

rego	The interpreter
entrypoint	A valid Rego entrypoint of the form `path/to/rule`

Returns: REGO_OK if successful, REGO_ERROR if there were any issues adding the entrypoint.

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

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

Parameters

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

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoBuild()

regoBundle * regoBuild ( regoInterpreter * rego )

Builds a compiled Rego bundle.

The bundle will include any base and virtual documents added to the interpreter, as well as a query set with regoSetQuery (if present) and any entrypoints added with regoAddEntrypoint (if any). There must be at least one entrypoint or a query specified for the build to be successful. The resulting handle can be used with regoBundleQuery and/or saved to the disk for later re-use.

Returns: a compiled Rego bundle

◆ regoBuildInfo()

regoEnum regoBuildInfo	(	char *	buffer,
		regoSize	size )

Populate a buffer with a string of the form "VERSION (BUILD_NAME, BUILD_DATE) BUILD_TOOLCHAIN on PLATFORM".

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

Parameters

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

Returns: REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.

◆ regoBuildInfoSize()

regoSize regoBuildInfoSize ( void )

Returns the number of bytes needed to store a 0-terminated string representing the build info.

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

Returns: The number of bytes needed to store the build info.

◆ regoBundleLoad()

regoBundle * regoBundleLoad	(	regoInterpreter *	rego,
		const char *	dir )

Loads a compiled Rego bundle from the specified directory.

The directory must contain a valid Rego bundle, which consists of a plan.json file, a data.json file, and zero or more .rego files which were used to create the bundle.

Parameters

rego	The interpreter
dir	The path to the directory containing the bundle.

Returns: The loaded bundle, or NULL if there was an error.

◆ regoBundleLoadBinary()

regoBundle * regoBundleLoadBinary	(	regoInterpreter *	rego,
		const char *	path )

Loads a compiled Rego bundle from the specified binary file.

The file must contain a valid Rego bundle in Rego Bundle Binary format. For more information on the format, see thespecification".

Parameters

rego	The interpreter
path	The path to the binary file containing the bundle.

Returns: The loaded bundle, or NULL if there was an error.

◆ regoBundleNode()

regoNode * regoBundleNode ( regoBundle * bundle )

Returns a node containing the base document of the bundle.

Warning: If the node was loaded from a binary file, this node will be missing. Future versions of the API may provide a way to reconstruct the bundle AST from the binary file.

Parameters

bundle The bundle.

Returns: A node containing the base document of the bundle.

◆ regoBundleOk()

regoBoolean regoBundleOk ( regoBundle * bundle )

Returns whether the bundle is ok.

If the bundle was built or loaded successfully, this function will return true. Otherwise, it will return false, indicating that there was an error during bundle creation. This error can be retrieved using regoError on the interpreter used to create or load the bundle.

Parameters

bundle The bundle.

Returns: Whether the bundle is ok.

◆ regoBundleQuery()

regoOutput * regoBundleQuery	(	regoInterpreter *	rego,
		regoBundle *	bundle )

Performs a query against the specified bundle.

The output of the query will be returned as a regoOutput object. The query executed will be the one set with regoSetQuery when the bundle was built. If no query was set, the output will be an error sequence.

Note: The caller is responsible for freeing the output object with regoFreeOutput.

Parameters

rego	The interpreter.
bundle	The bundle to query.

Returns: The output of the query.

◆ regoBundleQueryEntrypoint()

regoOutput * regoBundleQueryEntrypoint	(	regoInterpreter *	rego,
		regoBundle *	bundle,
		const char *	endpoint )

Performs a query against the specified bundle at the specified entrypoint.

The output of the query will be returned as a regoOutput object. The entrypoint must be one of those added with regoAddEntrypoint when the bundle was built. If the entrypoint does not exist, the output will be an error sequence.

Note: The caller is responsible for freeing the output object with regoFreeOutput.

Parameters

rego	The interpreter.
bundle	The bundle to query.
endpoint	The entrypoint to query.

Returns: The output of the query.

◆ regoBundleSave()

regoEnum regoBundleSave	(	regoInterpreter *	rego,
		const char *	dir,
		regoBundle *	bundle )

Saves a compiled Rego bundle to the specified directory.

The directory will be created if it does not exist. The bundle will be saved in the standard Rego bundle format, which consists of a plan.json file, a data.json file, and zero or more .rego files.

Parameters

rego	The interpreter
dir	The path to the directory where the bundle will be saved.
bundle	The bundle to save.

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoBundleSaveBinary()

regoEnum regoBundleSaveBinary	(	regoInterpreter *	rego,
		const char *	path,
		regoBundle *	bundle )

Saves a compiled Rego bundle to the specified binary file.

The bundle will be saved in Rego Bundle Binary format. For more information on the format, see thespecification".

Parameters

rego	The interpreter
path	The path to the binary file where the bundle will be saved.
bundle	The bundle to save.

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoError()

regoEnum regoError	(	regoInterpreter *	rego,
		char *	buffer,
		regoSize	size )

Populate a buffer with the most recent error message.

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

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

Parameters

rego	The interpreter.
buffer	The buffer to populate.
size	The size of the buffer.

Returns: REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.

◆ regoErrorSize()

regoSize regoErrorSize ( regoInterpreter * rego )

Returns the number of bytes needed to store a 0-terminated string representing the most recent error message.

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

Returns: The number of bytes needed to store the error message.

◆ regoFree()

void regoFree ( regoInterpreter * rego )

Frees a Rego interpreter.

Note: This pointer must have been allocated with regoNew.

Parameters

rego	The interpreter to free.

◆ regoFreeBundle()

void regoFreeBundle ( regoBundle * bundle )

Frees a Rego bundle.

Note: This pointer must have been allocated with regoBuild, regoBundleLoad, or regoBundleLoadBinary.

Parameters

bundle The bundle to free.

◆ regoFreeInput()

void regoFreeInput ( regoInput * input )

Frees a Rego Input object.

Note: This pointer must have been allocated with regoNewInput.

Parameters

input The input object to free.

◆ regoFreeOutput()

void regoFreeOutput ( regoOutput * output )

Frees a Rego output.

Note: 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.

◆ regoGetLogLevel()

regoEnum regoGetLogLevel ( regoInterpreter * rego )

Gets the level of logging on the interpreter.

Returns: 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.

◆ 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-formedness checks are enabled.

Parameters

rego	The interpreter.

Returns: Whether well-formedness checks are enabled.

◆ regoInputArray()

regoEnum regoInputArray	(	regoInput *	input,
		regoSize	count )

Uses the top 'count' values on the stack to create an array and pushes it back onto the stack.

Parameters

input	The input object.
count	The number of values to use.

Returns: REGO_OK if successful, REGO_ERROR or REGO_INPUT_MISSING_ARGUMENTS otherwise.

◆ regoInputBoolean()

regoEnum regoInputBoolean	(	regoInput *	input,
		regoBoolean	value )

Adds a boolean value to the input object.

Parameters

input	The input object.
value	The boolean value.

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoInputFloat()

regoEnum regoInputFloat	(	regoInput *	input,
		double	value )

Adds a floating point value to the input object.

Parameters

input	The input object.
value	The floating point value.

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoInputInt()

regoEnum regoInputInt	(	regoInput *	input,
		regoInt	value )

Adds an integer value to the input object.

Parameters

input	The input object.
value	The integer value.

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoInputNode()

regoNode * regoInputNode ( regoInput * input )

Returns the top of the Input stack.

Parameters

input The input object.

Returns: The top of the input stack as a regoNode. If the input is invalid or empty, this function will return NULL.

◆ regoInputNull()

regoEnum regoInputNull ( regoInput * input )

Adds a null value to the input object.

Parameters

input The input object.

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoInputObject()

regoEnum regoInputObject	(	regoInput *	input,
		regoSize	count )

Uses the top 'count' values on the stack to create an object and pushes it back onto the stack.

Note: The top 'count' values must be object items.

Parameters

input	The input object.
count	The number of object items to use.

Returns: REGO_OK if successful, REGO_ERROR, REGO_INPUT_MISSING_ARGUMENTS, or REGO_INPUT_OBJECT_ITEM otherwise.

◆ regoInputObjectItem()

regoEnum regoInputObjectItem ( regoInput * input )

Uses the top two values on the stack to create an object item and pushes it back onto the stack.

The top value on the stack will be used as the value, and the second value will be used as the key.

Parameters

input The input object.

Returns: REGO_OK if successful, REGO_ERROR or REGO_INPUT_MISSING_ARGUMENTS otherwise.

◆ regoInputSet()

regoEnum regoInputSet	(	regoInput *	input,
		regoSize	count )

Uses the top 'count' values on the stack to create a set and pushes it back onto the stack.

Note: As part of this operation, duplicate values will be removed and the values will be sorted.

Parameters

input	The input object.
count	The number of values to use.

Returns: REGO_OK if successful, REGO_ERROR or REGO_INPUT_MISSING_ARGUMENTS otherwise.

◆ regoInputSize()

regoSize regoInputSize ( regoInput * input )

Returns the number of items on the Input stack.

Parameters

input The input object.

Returns: The number of items on the input stack.

◆ regoInputString()

regoEnum regoInputString	(	regoInput *	input,
		const char *	value )

Adds a string value to the input object.

Parameters

input	The input object.
value	The string value.

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoInputValidate()

regoEnum regoInputValidate ( regoInput * input )

Validates the input object.

This function should be called after building the input object and before using it with regoSetInput. This function will ensure that the input object is valid (e.g. that there is exactly one value on the stack and there were no errors during construction).

Parameters

input The input object.

Returns: REGO_OK if the input is valid, REGO_ERROR_INPUT_* otherwise.

◆ regoIsAvailableBuiltIn()

regoBoolean regoIsAvailableBuiltIn	(	regoInterpreter *	rego,
		const char *	name )

Returns whether the specified name corresponds to an available built-in in the interpreter.

Parameters

rego	The interpreter.
name	The name of the built-in.

Returns: Whether the built-in exists.

◆ regoLogLevelFromString()

regoEnum regoLogLevelFromString ( const char * level )

Gets a log level constant value from a string (case-invariant).

String must be one of None, Error, Output, Warn, Info, Debug or Trace. An unrecognized string will result in a value of REGO_LOG_LEVEL_UNSUPPORTED.

Parameters

level The log level string.

Returns: 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, or REGO_LOG_LEVEL_UNSUPPORTED

◆ regoNew()

regoInterpreter * regoNew ( void )

Allocates and initializes a new Rego interpreter.

Note: The caller is responsible for freeing the interpreter with regoFree.

Returns: A pointer to the new interpreter.

◆ regoNewInput()

regoInput * regoNewInput ( )

Allocates and initializes a new Rego Input object.

Rego Input objects can be used to build input documents programmatically. An input is built up by making a series of calls to the API to add values to the stack. Some operations use the values on the stack to create composite values (e.g. objects, arrays, sets) which are then pushed back onto the stack. Once the input is built, it can be validated and then set on the interpreter with regoSetInput. While you can test the result of every operation, you can continue to use a broken Input object and the error will be returned when you call regoInputValidate.

// Example of building the following input document:
// {
//   "user": {
//     "name": "alice",
//     "age": 30,
//     "active": true
//   },
//   "roles": ["admin", "user"]
// }
regoInput* input = regoNewInput();
regoInputString(input, "user");     // Push "user"
regoInputString(input, "name");     // Push "name"
regoInputString(input, "alice");    // Push "alice"
regoInputObjectItem(input);         // Create {"name": "alice"}
regoInputString(input, "age");      // Push "age"
regoInputInt(input, 30);            // Push 30
regoInputObjectItem(input);         // Create {"age": 30}
regoInputString(input, "active");   // Push "active"
regoInputBoolean(input, true);      // Push true
regoInputObjectItem(input);         // Create {"active": true}
regoInputObject(input, 3);          // Create {"name": "alice", "age": 30, "active": true}
regoInputObjectItem(input);         // Create {"user": {...}}
regoInputString(input, "roles");    // Push "roles"
regoInputString(input, "admin");    // Push "admin"
regoInputString(input, "user");     // Push "user"
regoInputArray(input, 2);           // Create ["admin", "user"]
regoInputObjectItem(input);         // Create {"roles": [...]}
regoInputObject(input, 2);          // Create the final object
regoInputValidate(input);           // Validate the input
regoSetInput(rego, input);          // Set the input on the interpreter

Note: The caller is responsible for freeing the input object with regoFreeInput.

Returns: A pointer to the new input object.

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

regoType regoNodeType ( regoNode * node )

Returns an enumeration value indicating the node's 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 zero or more children of: REGO_NODE_TERM
REGO_NODE_SET	A set. Will have zero or more children of: REGO_NODE_TERM
REGO_NODE_OBJECT	An object. Will have zero 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_TERMS	Will have zero or more children of: REGO_NODE_TERM
REGO_NODE_BINDINGS	Will have zero or more children of: REGO_NODE_BINDING
REGO_NODE_RESULTS	Will have one or more children of: REGO_NODE_RESULT
REGO_NODE_RESULT	Will have two children, a REGO_NODE_BINDINGS and a REGO_NODE_TERMS.
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.

Parameters

node	the node to inspect

Returns: The node type.

◆ regoNodeTypeName()

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

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. The buffer must be large enough to hold the value. The size of the buffer can be determined by calling regoNodeTypeNameSize.

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.

◆ regoNodeTypeNameSize()

regoEnum regoNodeTypeNameSize ( regoNode * node )

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

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

Parameters

node The node.

Returns: The number of bytes needed to store 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.

◆ regoOutputJSON()

regoEnum regoOutputJSON	(	regoOutput *	output,
		char *	buffer,
		regoSize	size )

Populate a buffer with the output represented as a human-readable string.

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

Parameters

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

Returns: REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.

◆ regoOutputJSONSize()

regoSize regoOutputJSONSize ( regoOutput * output )

Returns the number of bytes needed to store a 0-terminated string representing the output as a human-readable string.

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

Parameters

output The output.

Returns: The number of bytes needed to store the output string.

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

Returns: The number of results in the output

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

Note: 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 regoError.

Parameters

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

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoSetDefaultLogLevel()

regoEnum regoSetDefaultLogLevel ( regoEnum level )

Sets the default level of logging.

This setting controls the amount of logging that will be output to stdout. The default level is REGO_LOG_LEVEL_OUTPUT. New interpreters will be set to this level of logging unless overridden by regoSetLogLevel.

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.

◆ regoSetInput()

regoEnum regoSetInput	(	regoInterpreter *	rego,
		regoInput *	input )

Sets the current input document from the specified Input object.

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

Parameters

rego	The interpreter.
input	The input object.

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

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

Parameters

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

Returns: REGO_OK if successful, REGO_ERROR otherwise.

◆ regoSetLogLevel()

regoEnum regoSetLogLevel	(	regoInterpreter *	rego,
		regoEnum	level )

Sets the level of logging on the interpreter.

This setting controls the amount of logging that will be output to stdout. The default level is REGO_LOG_LEVEL_OUTPUT, but can be changed using regoSetDefaultLogLevel.

Parameters

rego	The interpreter whose log level is to be set.
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.

◆ regoSetQuery()

regoEnum regoSetQuery	(	regoInterpreter *	rego,
		const char *	query_expr )

Sets the query for the interpreter.

By using this method, a query can be set such that it is included as a default entrypoint in a bundle.

Parameters

rego	The interpreter
query_expr	A Rego query expression

Returns: REGO_OK if successful, REGO_ERROR if there was a problem parsing the query

◆ 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-formedness checks after each compiler pass.

The interpreter has a set of well-formedness 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-formedness checks should be enabled.

◆ regoVersion()

regoEnum regoVersion	(	char *	buffer,
		regoSize	size )

Populate a buffer with a string representing the semantic version of the library.

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

Parameters

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

Returns: REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.

◆ regoVersionSize()

regoSize regoVersionSize ( void )

Returns the number of bytes needed to store a 0-terminated string representing version.

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

Returns: The number of bytes needed to store the version string.

Macros

Typedefs

Functions

Macro Definition Documentation

◆ REGO_API

Function Documentation

◆ regoAddDataJSON()

◆ regoAddDataJSONFile()

◆ regoAddEntrypoint()

◆ regoAddModule()

◆ regoAddModuleFile()

◆ regoBuild()

◆ regoBuildInfo()

◆ regoBuildInfoSize()

◆ regoBundleLoad()

◆ regoBundleLoadBinary()

◆ regoBundleNode()

◆ regoBundleOk()

◆ regoBundleQuery()

◆ regoBundleQueryEntrypoint()

◆ regoBundleSave()

◆ regoBundleSaveBinary()

◆ regoError()

◆ regoErrorSize()

◆ regoFree()

◆ regoFreeBundle()

◆ regoFreeInput()

◆ regoFreeOutput()

◆ regoGetDebugEnabled()

◆ regoGetLogLevel()

◆ regoGetStrictBuiltInErrors()

◆ regoGetWellFormedChecksEnabled()

◆ regoInputArray()

◆ regoInputBoolean()

◆ regoInputFloat()

◆ regoInputInt()

◆ regoInputNode()

◆ regoInputNull()

◆ regoInputObject()

◆ regoInputObjectItem()

◆ regoInputSet()

◆ regoInputSize()

◆ regoInputString()

◆ regoInputValidate()

◆ regoIsAvailableBuiltIn()

◆ regoLogLevelFromString()

◆ regoNew()

◆ regoNewInput()

◆ regoNodeGet()

◆ regoNodeJSON()

◆ regoNodeJSONSize()

◆ regoNodeSize()

◆ regoNodeType()

◆ regoNodeTypeName()

◆ regoNodeTypeNameSize()

◆ regoNodeValue()

◆ regoNodeValueSize()

◆ regoOutputBinding()

◆ regoOutputBindingAtIndex()

◆ regoOutputExpressions()

◆ regoOutputExpressionsAtIndex()

◆ regoOutputJSON()

◆ regoOutputJSONSize()

◆ regoOutputNode()

◆ regoOutputOk()

◆ regoOutputSize()

◆ regoQuery()

◆ regoSetDebugEnabled()

◆ regoSetDebugPath()

◆ regoSetDefaultLogLevel()

◆ regoSetInput()

◆ regoSetInputJSONFile()

◆ regoSetInputTerm()

◆ regoSetLogLevel()

◆ regoSetQuery()

◆ regoSetStrictBuiltInErrors()

◆ regoSetWellFormedChecksEnabled()

◆ regoVersion()

◆ regoVersionSize()