This class forms the main interface to the Rego library. More...

#include <rego.hh>

Public Member Functions
	Interpreter ()
	Constructor.

Node	add_module_file (const std::filesystem::path &path)
	Adds a module (i.e. virtual document) file to the interpreter.

Node	add_module (const std::string &name, const std::string &contents)
	Adds a module (i.e. virtual document) to the interpreter.

Node	add_data_json_file (const std::filesystem::path &path)
	Adds a base document to the interpreter.

Node	add_data_json (const std::string &json)
	Adds a base document to the interpreter.

Node	add_data (const Node &node)
	Adds a base document to the interpreter.

Node	set_input_json_file (const std::filesystem::path &path)
	Sets the input document to the interpreter.

Node	set_input_json (const std::string &json)
	Sets the input document to the interpreter.

Node	set_input_term (const std::string &term)
	Sets the input term of the interpreter.

Node	set_input (const Node &node)
	Sets the input document to the interpreter.

Node	set_query (const std::string &query)
	Sets the query expression of the interpreter.

Interpreter &	entrypoints (const std::initializer_list< std::string > &entrypoints)
	Sets the entrypoints to include when building a bundle.

Interpreter &	entrypoints (const std::vector< std::string > &entrypoints)
	Sets the entrypoints to include when building a bundle.

const std::vector< std::string > &	entrypoints () const
	Gets the entrypoints to include when building a bundle.

std::vector< std::string > &	entrypoints ()
	Gets the entrypoints to include when building a bundle.

std::string	query ()
	Executes the documents against the interpreter.

std::string	query (const std::string &query_expr)
	Executes a query against the interpreter.

Node	query_node (const std::string &query_expr)
	Executes a query against the interpreter.

Node	query_node ()
	Executes a query against the interpreter.

Node	build ()
	Builds a bundle from the current state of the interpreter.

Node	save_bundle (const std::filesystem::path &dir, const Node &bundle)
	Saves a bundle to a directory in JSON format.

Node	load_bundle (const std::filesystem::path &dir)
	Loads a bundle in JSON format from a direction.

Node	query_bundle (const Bundle &bundle)
	Performs a query against a bundle.

Node	query_bundle (const Bundle &bundle, const std::string &endpoint)
	Performs a query against a bundle.

Interpreter &	debug_path (const std::filesystem::path &prefix)
	The path to the debug directory.

const std::filesystem::path &	debug_path () const
	Gets the debug path.

Interpreter &	debug_enabled (bool enabled)
	Sets whether debug mode is enabled.

bool	debug_enabled () const
	Checks if debug mode is enabled.

Interpreter &	wf_check_enabled (bool enabled)
	Sets whether well-formedness checks are enabled.

bool	wf_check_enabled () const
	Checks if well-formedness checks are enabled.

BuiltIns	builtins () const
	The built-ins used by the interpreter.

std::string	output_to_string (const Node &output) const
	Converts an output node into a human-readable string.

LogLevel	log_level () const
	Returns the current log level of this interpreter.

Interpreter &	log_level (LogLevel level)
	Sets the log level of the interpreter.

Interpreter &	log_level (const std::string &level)
	Sets the logging level for the interpreter from a string.

const std::string &	c_error () const
	Returns a string representing the most recent error message.

Interpreter &	c_error (const std::string &error)
	Sets the most recent error message.

Detailed Description

This class forms the main interface to the Rego library.

You can use it to assemble and then execute queries, for example:

Interpreter rego;
rego.add_module_file("objects.rego");
rego.add_data_json_file("data0.json");
rego.add_data_json_file("data1.json");
rego.set_input_json_file("input0.json");
std::cout << rego.query("[data.one, input.b, data.objects.sites[1]]") <<
std::endl;

Member Function Documentation

◆ add_data()

Node rego::Interpreter::add_data ( const Node & node )

Adds a base document to the interpreter.

Adds a JSON AST node to the interpreter's data sequence.

Parameters

node	The contents of the document.

Returns: either an error node or a nullptr if the node is valid.

◆ add_data_json()

Node rego::Interpreter::add_data_json ( const std::string & json )

Adds a base document to the interpreter.

The document must contain a single JSON-encoded object, and will be parsed and added to the interpreter's data sequence.

Parameters

json	The contents of the document.

Returns: either an error node or a nullptr if the JSON is valid.

◆ add_data_json_file()

Node rego::Interpreter::add_data_json_file ( const std::filesystem::path & path )

Adds a base document to the interpreter.

This is the same as calling Interpreter::add_data_json with the contents of the file.

Parameters

path	The path to the data JSON file.

Returns: either an error node or a nullptr if the JSON is valid.

◆ add_module()

Node rego::Interpreter::add_module	(	const std::string &	name,
		const std::string &	contents )

Adds a module (i.e. virtual document) to the interpreter.

The module will be parsed and added to the interpreter's module sequence.

Parameters

name	The name of the module.
contents	The contents of the module.

Returns: either an error node or a nullptr if the module is valid.

◆ add_module_file()

Node rego::Interpreter::add_module_file ( const std::filesystem::path & path )

Adds a module (i.e. virtual document) file to the interpreter.

This is the same as calling Interpreter::add_module with the contents of the file.

Parameters

path	The path to the module file.

Returns: either an error node or a nullptr if the module is valid.

◆ build()

Node rego::Interpreter::build ( )

Builds a bundle from the current state of the interpreter.

The bundle will include all base and virtual documents, and will include execution plans for a query (if set) and zero or more entrypoints (if set). If no query or entrypoints are set, or if there is an error during bundle creation, an error node will be returned. The resulting bundle node can be used as an input to Bundle::from_node.

rego.set_query("[data.one, input.b, data.objects.sites[1]] = x");
rego.entrypoints({"objects/sites", "objects/rect"});
rego::Node bundle_node = rego.build();
rego::Bundle bundle = rego::BundleDef::from_node(bundle_node);
// we can assemble the input term manually
rego::Node input = rego::object({
  rego::object_item(rego::scalar("a"), rego::scalar(rego::BigInt(10L))),
  rego::object_item(rego::scalar("b"), rego::scalar("20")),
  rego::object_item(rego::scalar("c"), rego::scalar(30.0)),
  rego::object_item(rego::scalar("d"), rego::scalar(true)),
});
rego.set_input(input);
std::cout << rego.output_to_string(rego.query_bundle(bundle)) << std::endl;
// we can also query bundle entrypoints directly
std::cout << rego.output_to_string(rego.query_bundle(bundle, "objects/sites"))
          << std::endl;

Returns: The bundle, or an error node.

◆ builtins()

BuiltIns rego::Interpreter::builtins ( ) const

The built-ins used by the interpreter.

This object can be used to register custom built-ins created using BuiltInDef::create.

Returns: the builtins used by the interpreter

◆ c_error() [1/2]

const std::string & rego::Interpreter::c_error ( ) const

Returns a string representing the most recent error message.

Note: This is intended for use by the C API.

Returns: An error string

◆ c_error() [2/2]

Interpreter & rego::Interpreter::c_error ( const std::string & error )

Sets the most recent error message.

Note: This is intended for use by the C API.

Parameters

error the error message

Returns: A reference to the interpreter.

◆ debug_enabled() [1/2]

bool rego::Interpreter::debug_enabled ( ) const

Checks if debug mode is enabled.

Returns: True if debug mode is enabled, false otherwise.

◆ debug_enabled() [2/2]

Interpreter & rego::Interpreter::debug_enabled ( bool enabled )

Sets whether debug mode is enabled.

If true, then the interpreter will output intermediary ASTs after each compiler pass to the debug directory set via Interpreter::debug_path.

Parameters

enabled whether debug is enabled

Returns: a reference to this Interpreter

◆ debug_path() [1/2]

const std::filesystem::path & rego::Interpreter::debug_path ( ) const

Gets the debug path.

Returns: The debug path.

◆ debug_path() [2/2]

Interpreter & rego::Interpreter::debug_path ( const std::filesystem::path & prefix )

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.

◆ entrypoints() [1/4]

std::vector< std::string > & rego::Interpreter::entrypoints ( )

Gets the entrypoints to include when building a bundle.

Returns: The entrypoints.

◆ entrypoints() [2/4]

const std::vector< std::string > & rego::Interpreter::entrypoints ( ) const

Gets the entrypoints to include when building a bundle.

Returns: The entrypoints.

◆ entrypoints() [3/4]

Interpreter & rego::Interpreter::entrypoints ( const std::initializer_list< std::string > & entrypoints )

Sets the entrypoints to include when building a bundle.

Parameters

entrypoints The entrypoints.

Returns: A reference to this interpreter.

◆ entrypoints() [4/4]

Interpreter & rego::Interpreter::entrypoints ( const std::vector< std::string > & entrypoints )

Sets the entrypoints to include when building a bundle.

Parameters

entrypoints The entrypoints.

Returns: A reference to this interpreter.

◆ load_bundle()

Node rego::Interpreter::load_bundle ( const std::filesystem::path & dir )

Loads a bundle in JSON format from a direction.

The directory is expected to contain a plan.json file, a data.json file, and zero or more .rego files. If there is an error when loading, an error node will be returned.

Parameters

dir	The direction to use when loading the bundle

Returns: Either an bundle node, or an error node if there was a problem during loading.

◆ log_level() [1/3]

LogLevel rego::Interpreter::log_level ( ) const

Returns the current log level of this interpreter.

Returns: The log level

◆ log_level() [2/3]

Interpreter & rego::Interpreter::log_level ( const std::string & level )

Sets the logging level for the interpreter from a string.

Parameters

level The logging level. One of "None", "Error", "Output", "Warn", "Info", "Debug", or "Trace".

Returns: A reference to the interpreter.

◆ log_level() [3/3]

Interpreter & rego::Interpreter::log_level ( LogLevel level )

Sets the log level of the interpreter.

Parameters

level the log level

Returns: A reference to the interpreter.

◆ output_to_string()

std::string rego::Interpreter::output_to_string ( const Node & output ) const

Converts an output node into a human-readable string.

Parameters

output An output node returned from Interpreter::query_node or Interpreter::query_bundle.

Returns: A human-readable string representing the output

◆ query() [1/2]

std::string rego::Interpreter::query ( )

Executes the documents against the interpreter.

This method calls Interpreter::query_node and then converts it into a human-readable string using Interpeter::output_to_string.

Returns: The result of the query.

◆ query() [2/2]

std::string rego::Interpreter::query ( const std::string & query_expr )

Executes a query against the interpreter.

This method calls Interpreter::query_node and then converts it into a human-readable string using Interpreter::output_to_string.

Parameters

query_expr The query expression.

Returns: The result of the query.

◆ query_bundle() [1/2]

Node rego::Interpreter::query_bundle ( const Bundle & bundle )

Performs a query against a bundle.

The interpreter will load this bundle into its virtual machine and then execute the stored query plan. If no query was compiled into the bundle, this will result in an error. Otherwise, the result will be an AST node representing the result, which will either be a list of bindings and terms, or an error sequence.

Parameters

bundle The bundle to query

Returns: The result of the query

◆ query_bundle() [2/2]

Node rego::Interpreter::query_bundle	(	const Bundle &	bundle,
		const std::string &	endpoint )

Performs a query against a bundle.

The interpreter will load this bundle into its virtual machine and then execute the stored entrypoint plan. If this entrypoint was not compiled into the bundle, this will result in an error. Otherwise, the result will be an AST node representing the result, which will either be a list of bindings and terms, or an error sequence.

Parameters

bundle	The bundle to query
endpoint	The entrypoint to execute

Returns: The result of the query

◆ query_node() [1/2]

Node rego::Interpreter::query_node ( )

Executes a query against the interpreter.

The query executed will be the one provided to Interpreter::set_query. The result will be an AST node representing the result, which will either be a list of bindings and terms, or an error sequence.

Returns: The result of the query.

◆ query_node() [2/2]

Node rego::Interpreter::query_node ( const std::string & query_expr )

Executes a query against the interpreter.

The query expression must be a valid Rego query expression. The result will be an AST node representing the result, which will either be a list of bindings and terms, or an error sequence.

Parameters

query_expr The query expression.

Returns: The result of the query.

◆ save_bundle()

Node rego::Interpreter::save_bundle	(	const std::filesystem::path &	dir,
		const Node &	bundle )

Saves a bundle to a directory in JSON format.

The bundle will be saved in a format compatible with OPA. The directory will be created if it does not exist. There will be a plan.json file, a data.json file, and zero or more .rego files (from the modules used during compilation). If there is an error during saving, an error node will be returned.

Parameters

dir	The directory to save the bundle to.
bundle	The bundle to save (as produced by Interpreter::build).

Returns: Either an error node, or a null node if the bundle was saved successfully.

◆ set_input()

Node rego::Interpreter::set_input ( const Node & node )

Sets the input document to the interpreter.

Sets an AST node directly as the interpreter's input. Use with caution. The node can either be a JSON AST (which will be converted) or a Rego AST.

Parameters

node	The contents of the document.

◆ set_input_json()

Node rego::Interpreter::set_input_json ( const std::string & json )

Sets the input document to the interpreter.

The document must contain a single JSON-encoded object, and will be parsed and set as the interpreter's input.

Parameters

json	The contents of the document.

Returns: either an error node or a nullptr if the input document is valid.

◆ set_input_json_file()

Node rego::Interpreter::set_input_json_file ( const std::filesystem::path & path )

Sets the input document to the interpreter.

This is the same as calling Interpreter::set_input_json with the contents of the file.

Parameters

path	The path to the input file.

Returns: either an error node or a nullptr if the input document is valid.

◆ set_input_term()

Node rego::Interpreter::set_input_term ( const std::string & term )

Sets the input term of the interpreter.

The string must contain a single valid Rego data term.

Parameters

term	The contents of the term.

Returns: either an error node or a nullptr if the input term is valid.

◆ set_query()

Node rego::Interpreter::set_query ( const std::string & query )

Sets the query expression of the interpreter.

This query will be included when building a bundle.

Parameters

query The query expression.

Returns: either an error node or a nullptr if the query expression is valid.

◆ wf_check_enabled() [1/2]

bool rego::Interpreter::wf_check_enabled ( ) const

Checks if well-formedness checks are enabled.

Returns: True if well-formedness checks are enabled, false otherwise.

◆ wf_check_enabled() [2/2]

Interpreter & rego::Interpreter::wf_check_enabled ( bool enabled )

Sets whether well-formedness checks are enabled.

If true, then the interpreter will perform well-formedness checks after each compiler pass using the well-formedness definitions.

Parameters

enabled Whether well-formedness checks are enabled

Returns: a reference to this Interpreter

The documentation for this class was generated from the following file:

include/rego/rego.hh

Public Member Functions

Detailed Description

Member Function Documentation

◆ add_data()

◆ add_data_json()

◆ add_data_json_file()

◆ add_module()

◆ add_module_file()

◆ build()

◆ builtins()

◆ c_error() [1/2]

◆ c_error() [2/2]

◆ debug_enabled() [1/2]

◆ debug_enabled() [2/2]

◆ debug_path() [1/2]

◆ debug_path() [2/2]

◆ entrypoints() [1/4]

◆ entrypoints() [2/4]

◆ entrypoints() [3/4]

◆ entrypoints() [4/4]

◆ load_bundle()

◆ log_level() [1/3]

◆ log_level() [2/3]

◆ log_level() [3/3]

◆ output_to_string()

◆ query() [1/2]

◆ query() [2/2]

◆ query_bundle() [1/2]

◆ query_bundle() [2/2]

◆ query_node() [1/2]

◆ query_node() [2/2]

◆ save_bundle()

◆ set_input()

◆ set_input_json()

◆ set_input_json_file()

◆ set_input_term()

◆ set_query()

◆ wf_check_enabled() [1/2]

◆ wf_check_enabled() [2/2]