Returns the build information as a string.
@brief Adds a base document from the specified string.
@details
The string should contain a single JSON object. The object will be
parsed and merged with the interpreter’s base document.
@par If an error code is returned, more error information can be
obtained by calling ::regoError.
@param rego The interpreter.
@param contents The contents of the JSON object.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Adds a base document from the file at the specified path.
@details
The file should contain a single JSON object. The object will be
parsed and merged with the interpreter’s base document.
@par If an error code is returned, more error information can be
obtained by calling ::regoError.
@param rego The interpreter.
@param path The path to the JSON file.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Adds an entrypoint to the interpreter.
@details
By using this method, an entrypoint can be added to the list of those with
compiled execution plans in a bundle.
@param rego The interpreter
@param entrypoint A valid Rego entrypoint of the form path/to/rule
@return REGO_OK if successful, REGO_ERROR if there were any issues adding
the entrypoint.
@brief Adds a module (e.g. virtual document) from the specified string.
@details
If an error code is returned, more error information can be
obtained by calling ::regoError.
@param rego The interpreter.
@param name The name of the module.
@param contents The contents of the module.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Adds a module (e.g. virtual document) from the file at the
specified path.
@details
If an error code is returned, more error information can be
obtained by calling ::regoError.
@param rego The interpreter.
@param path The path to the policy file.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Builds a compiled Rego bundle.
@details
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.
@return a compiled Rego bundle
@brief Populate a buffer with a string of the form “VERSION (BUILD_NAME,
BUILD_DATE) BUILD_TOOLCHAIN on PLATFORM”
@details
The buffer must be large enough to hold the value. The size of the buffer
can be determined by calling ::regoBuildInfoSize.
@param buffer The buffer to populate.
@param size The size of the buffer.
@return REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.
@brief Returns the number of bytes needed to store a 0-terminated string
representing the build info.
@details
The value returned by this function can be used to allocate a buffer to
pass to ::regoBuildInfo.
@return The number of bytes needed to store the build info.
@brief Loads a compiled Rego bundle from the specified directory.
@details
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.
@param rego The interpreter
@param dir The path to the directory containing the bundle.
@return The loaded bundle, or NULL if there was an error.
@brief Loads a compiled Rego bundle from the specified binary file.
@details
The file must contain a valid Rego bundle in Rego Bundle Binary format.
For more information on the format, see
the
specification.
@param rego The interpreter
@param path The path to the binary file containing the bundle.
@return The loaded bundle, or NULL if there was an error.
@brief 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.
@param bundle The bundle.
@return A node containing the base document of the bundle.
@brief Returns whether the bundle is ok.
@details
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.
@param bundle The bundle.
@return Whether the bundle is ok.
@brief Performs a query against the specified bundle.
@details
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.
@param rego The interpreter.
@param bundle The bundle to query.
@return The output of the query.
@brief Performs a query against the specified bundle at the specified
entrypoint.
@details
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.
@param rego The interpreter.
@param bundle The bundle to query.
@param endpoint The entrypoint to query.
@return The output of the query.
@brief Saves a compiled Rego bundle to the specified directory.
@details
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.
@param rego The interpreter
@param dir The path to the directory where the bundle will be saved.
@param bundle The bundle to save.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Saves a compiled Rego bundle to the specified binary file.
@details
The bundle will be saved in Rego Bundle Binary format.
For more information on the format, see
the
specification.
@param rego The interpreter
@param path The path to the binary file where the bundle will be saved.
@param bundle The bundle to save.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Populate a buffer with the most recent error message.
@details
If an error code is returned from an interface function, more error
information can usually be obtained by calling this function.
@par The buffer must be large enough to hold the value. The size of the
buffer can be determined by calling ::regoErrorSize.
@param rego The interpreter.
@param buffer The buffer to populate.
@param size The size of the buffer.
@return REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.
@brief Returns the number of bytes needed to store a 0-terminated string
representing the most recent error message.
@details
The value returned by this function can be used to allocate a buffer to
pass to ::regoError.
@return The number of bytes needed to store the error message.
@brief Frees a Rego interpreter.
@note This pointer must have been allocated with ::regoNew.
@param rego The interpreter to free.
@brief Frees a Rego bundle.
@note This pointer must have been allocated with ::regoBuild,
::regoBundleLoad, or ::regoBundleLoadBinary.
@param bundle The bundle to free.
@brief Frees a Rego Input object.
@note This pointer must have been allocated with ::regoNewInput.
@param input The input object to free.
@brief Frees a Rego output.
@note This pointer must have been allocated with regoQuery.
@param output The output to free.
@brief Gets the level of logging on the interpreter.
@return 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.
@brief Gets whether strict built-in errors are enabled.
@param rego The interpreter.
@return Whether strict built-in errors are enabled.
@brief Gets whether well-formedness checks are enabled.
@param rego The interpreter.
@return Whether well-formedness checks are enabled.
@brief Uses the top ‘count’ values on the stack to create an array and
pushes it back onto the stack.
@param input The input object.
@param count The number of values to use.
@return REGO_OK if successful, REGO_ERROR or REGO_INPUT_MISSING_ARGUMENTS
otherwise.
@brief Adds a boolean value to the input object.
@param input The input object.
@param value The boolean value.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Adds a floating point value to the input object.
@param input The input object.
@param value The floating point value.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Adds an integer value to the input object.
@param input The input object.
@param value The integer value.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Returns the top of the Input stack.
@param input The input object.
@return The top of the input stack as a regoNode. If the input is invalid
or empty, this function will return NULL.
@brief Adds a null value to the input object.
@param input The input object.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief 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.
@param input The input object.
@param count The number of object items to use.
@return REGO_OK if successful, REGO_ERROR, REGO_INPUT_MISSING_ARGUMENTS,
or REGO_INPUT_OBJECT_ITEM otherwise.
@brief Uses the top two values on the stack to create an object item
and pushes it back onto the stack.
@details
The top value on the stack will be used as the value, and the second value
will be used as the key.
@param input The input object.
@return REGO_OK if successful, REGO_ERROR or REGO_INPUT_MISSING_ARGUMENTS
otherwise.
@brief 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.
@param input The input object.
@param count The number of values to use.
@return REGO_OK if successful, REGO_ERROR or REGO_INPUT_MISSING_ARGUMENTS
otherwise.
@brief Returns the number of items on the Input stack.
@param input The input object.
@return The number of items on the input stack.
@brief Adds a string value to the input object.
@param input The input object.
@param value The string value.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Validates the input object.
@details
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).
@param input The input object.
@return REGO_OK if the input is valid, REGO_ERROR_INPUT_* otherwise.
@brief Returns whether the specified name corresponds to an available
built-in in the interpreter.
@param rego The interpreter.
@param name The name of the built-in.
@return Whether the built-in exists.
@brief Gets a log level constant value from a string (case-invariant).
@details 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.
@param level The log level string.
@return 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
@brief Allocates and initializes a new Rego interpreter.
@note The caller is responsible for freeing the interpreter with
::regoFree.
@return A pointer to the new interpreter.
@brief Allocates and initializes a new Rego Input object.
@details
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.
@brief Returns the child node at the specified index.
@param node The node.
@param index The index of the child.
@return The child node.
@brief Populate a buffer with the JSON representation of the node.
@details
The buffer must be large enough to hold the value. The size of the buffer
can be determined by calling ::regoNodeJSONSize.
@param node The node.
@param buffer The buffer to populate.
@param size The size of the buffer.
@return REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.
@brief Returns the number of bytes needed to store a 0-terminated string
representing the JSON representation of the node.
@details
The value returned by this function can be used to allocate a buffer to
pass to ::regoNodeJSON.
@param node The node.
@return The number of bytes needed to store the JSON representation.
@brief Returns the number of children of the node.
@param node The node.
@return The number of children.
@brief Returns an enumeration value indicating the node’s type.
@details
This type will be one of the following values:
@brief Returns the name of the node type as a human-readable string.
@details
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.
@param node The node.
@param buffer The buffer to populate.
@param size The size of the buffer.
@return REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.
@brief Returns the number of bytes needed to store a 0-terminated string
representing the name of the node type.
@details
The value returned by this function can be used to allocate a buffer to
pass to ::regoNodeTypeName.
@param node The node.
@return The number of bytes needed to store the node type name.
@brief Populate a buffer with the node value.
@details
The buffer must be large enough to hold the value. The size of the buffer
can be determined by calling regoNodeValueSize.
@param node The node.
@param buffer The buffer to populate.
@param size The size of the buffer.
@return REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.
@brief Returns the number of bytes needed to store a 0-terminated string
representing the text value of the node.
@details
The value returned by this function can be used to allocate a buffer to
pass to ::regoNodeValue.
@param node The node.
@return The number of bytes needed to store the text value.
@brief Returns the bound value for a given variable name at the first
index.
@details
If the variable is not bound, then this function will return NULL.
@param output The output.
@param name The variable name.
@return The bound value (or NULL if the variable was not bound)
@brief Returns the bound value for a given variable name.
@details
If the variable is not bound, then this function will return NULL.
@param output The output.
@param index The result index.
@param name The variable name.
@return The bound value (or NULL if the variable was not bound)
@brief Returns a node containing a list of terms resulting from the query
at the default index.
@param output The output.
@return The output node.
@brief Returns a node containing a list of terms resulting from the query
at the specified index.
@param output The output.
@param index The result index.
@return The output node.
@brief Populate a buffer with the output represented as a human-readable
string.
@details
The buffer must be large enough to hold the value. The size of the buffer
can be determined by calling ::regoOutputJSONSize.
@param output The output.
@param buffer The buffer to populate.
@param size The size of the buffer.
@return REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.
@brief Returns the number of bytes needed to store a 0-terminated string
representing the output as a human-readable string.
@details
The value returned by this function can be used to allocate a buffer to
pass to ::regoOutputJSON.
@param output The output.
@return The number of bytes needed to store the output string.
@brief Returns the node containing the output of the query.
@details
This will either be a node which contains one or more results,
or an error sequence.
@param output The output.
@return The output node.
@brief Returns whether the output is ok.
@details
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.
@param output The output.
@return Whether the output is ok.
@brief Returns the number of results in the output.
@details
Each query can potentially generate multiple results.
@return The number of results in the output
@brief Performs a query against the current base and virtual documents.
@details
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.
@param rego The interpreter.
@param query_expr The query expression.
@return The output of the query.
@brief Sets the debug mode of the interpreter.
@details
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.
@param rego The interpreter.
@param enabled Whether debug mode should be enabled.
@brief Sets the path to the debug directory.
@details
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.
@par If an error code is returned, more error information can be
obtained by calling ::regoError.
@param rego The interpreter.
@param path The path to the debug directory.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Sets the default level of logging.
@details
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.
@param 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.
@return REGO_OK if successful, REGO_ERROR_INVALID_LOG_LEVEL otherwise.
@brief Sets the current input document from the specified Input object.
@details
If an error code is returned, more error information can be
obtained by calling ::regoError.
@param rego The interpreter.
@param input The input object.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Sets the current input document from the file at the specified
path.
@details
The file should contain a single JSON value. The value will be
parsed and set as the interpreter’s input document.
@par If an error code is returned, more error information can be
obtained by calling ::regoError.
@param rego The interpreter.
@param path The path to the JSON file.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Sets the current input document from the specified string.
@details
The string should contain a single Rego data term. The value will be
parsed and set as the interpreter’s input document.
@par If an error code is returned, more error information can be
obtained by calling ::regoError.
@param rego The interpreter.
@param contents The contents of the Rego data term.
@return REGO_OK if successful, REGO_ERROR otherwise.
@brief Sets the level of logging on the interpreter.
@details
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.
@param rego The interpreter whose log level is to be set.
@param 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.
@return REGO_OK if successful, REGO_ERROR_INVALID_LOG_LEVEL otherwise.
@brief Sets the query for the interpreter.
@details
By using this method, a query can be set such that it is included as a
default entrypoint in a bundle.
@param rego The interpreter
@param query_expr A Rego query expression
@return REGO_OK if successful, REGO_ERROR if there was a problem parsing
the query
@brief Sets whether the built-ins should throw errors.
@details
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.
@param rego The interpreter.
@param enabled Whether strict built-in errors should be enabled.
@brief Sets whether to perform well-formedness checks after each compiler
pass.
@details
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.
@param rego The interpreter.
@param enabled Whether well-formedness checks should be enabled.
@brief Populate a buffer with a string representing the semantic version
of the library.
@details
The buffer must be large enough to hold the value. The size of the buffer
can be determined by calling ::regoVersionSize.
@param buffer The buffer to populate.
@param size The size of the buffer.
@return REGO_OK if successful, REGO_ERROR_BUFFER_TOO_SMALL otherwise.
@brief Returns the number of bytes needed to store a 0-terminated string
representing version.
@details
The value returned by this function can be used to allocate a buffer to
pass to ::regoVersion.
@return The number of bytes needed to store the version string.