The main control class for grounding and solving logic programs. More...

#include <control.hh>

Public Types
using	Context = std::function< SymbolVector(std::string_view, SymbolSpan)>
	Callbock for injecting symbols into the grounding process.

Public Member Functions
	Control (Library const &lib, StringList arguments)
	Constructs a control object with the given library and arguments.

	Control (Library const &lib, StringSpan arguments={})
	Constructs a control object with the given library and arguments.

	Control (clingo_control_t *rep, bool acquire)
	Constructs a control object from an existing C representation.

auto	mode () const -> ControlMode
	Get the control mode.

void	write_aspif (std::string_view path, WriteAspifFlags flags=WriteAspifFlags::none) const
	Write the current program to an ASPIF file.

void	parse_files (StringSpan files) const
	Parse files with the given paths.

void	parse_files (StringList files) const
	Parse files with the given paths.

void	parse_string (std::string_view program) const
	Parse a logic program from a string.

void	ground (std::optional< PartSpan > parts=std::nullopt, Context ctx=nullptr) const
	Ground the control object with the given parts.

void	ground (std::initializer_list< Part > parts, Context ctx=nullptr) const
	Ground the control object with the given parts.

auto	base () const -> Base
	Get the base of the program.

auto	stats () const -> ConstStats
	Get the statistics of the control object.

auto	solve (SolveEventHandler &handler, ProgramLiteralSpan const &assumptions={}, SolveFlags flags=SolveFlags::empty) const -> SolveHandle
	Solve the grounded program with the given assumptions and flags.

auto	solve (ProgramLiteralSpan const &assumptions={}, SolveFlags flags=SolveFlags::yield) const -> SolveHandle
	Solve the grounded program with the given assumptions and flags.

void	main () const
	Run the default ground and solve flow.

void	interrupt () const
	Interrupt the current solve operation.

void	discard (DiscardType type) const
	Discard the statements of the given types.

auto	buffer () const -> std::string_view
	Get the text buffer of the control object.

auto	parts () const -> std::optional< PartVector >
	Get the parts to ground.

void	parts (PartList parts) const
	Set the parts to ground.

void	parts (std::optional< PartSpan > parts) const
	Set the parts to ground.

auto	config () const -> Config
	Get the configuration of the control object.

auto	const_map () const -> ConstMap
	Get the constant map of the control object.

void	observe (Observer &obs, bool preprocess=true) const
	Inspect the current ground program held by the control object.

auto	backend () const -> ProgramBackend
	Get the backend of the control object.

template<std::derived_from< Propagator > T>
auto	register_propagator (std::unique_ptr< T > propagator) const -> T &
	Register a propagator with the control object.

void	join (AST::Program const &prg) const
	Join the given non-ground program to the current control object.

Friends
auto	c_cast (Control const &ctl) -> clingo_control_t *
	Cast to the C representation of the control object.

Detailed Description

The main control class for grounding and solving logic programs.

Control objects are reference counted. For example, care must be taken not to store objects by value in registered propagators to avoid reference cycles.

Member Typedef Documentation

◆ Context

using Clingo::Control::Context = std::function<SymbolVector(std::string_view, SymbolSpan)>

Callbock for injecting symbols into the grounding process.

The callback takes the name of the function and the parameters as a string view and a span of symbols as arguments and returns a vector of symbols to inject.

Constructor & Destructor Documentation

◆ Control() [1/3]

Clingo::Control::Control	(	Library const &	lib,
		StringList	arguments
	)

inlineexplicit

Constructs a control object with the given library and arguments.

Parameters

lib	the library to store symbols
arguments	the command-line arguments to pass to the control object

◆ Control() [2/3]

Clingo::Control::Control	(	Library const &	lib,
		StringSpan	arguments = `{}`
	)

inlineexplicit

Constructs a control object with the given library and arguments.

Parameters

lib	the library to store symbols
arguments	the command-line arguments to pass to the control object

◆ Control() [3/3]

Clingo::Control::Control	(	clingo_control_t *	rep,
		bool	acquire
	)

inlineexplicit

Constructs a control object from an existing C representation.

For internal use.

Parameters

rep	the C representation of the control object
acquire	whether to acquire the control object

Member Function Documentation

◆ backend()

auto Clingo::Control::backend ( ) const -> ProgramBackend

inline

Get the backend of the control object.

Returns: the backend of the control object

◆ base()

auto Clingo::Control::base ( ) const -> Base

inline

Get the base of the program.

Returns: the base of the program

◆ buffer()

auto Clingo::Control::buffer ( ) const -> std::string_view

inline

Get the text buffer of the control object.

Manually created control objects use this buffer to output statements to if the control mode has been set to parse, rewrite, or ground.

Returns: the contents of the text buffer

◆ config()

auto Clingo::Control::config ( ) const -> Config

inline

Get the configuration of the control object.

Returns: the configuration of the control object

◆ const_map()

auto Clingo::Control::const_map ( ) const -> ConstMap

inline

Get the constant map of the control object.

Returns: the constant map of the control object

◆ discard()

void Clingo::Control::discard ( DiscardType type ) const

inline

Discard the statements of the given types.

Parameters

type	the types of statements to discard

◆ ground() [1/2]

void Clingo::Control::ground	(	std::initializer_list< Part >	parts,
		Context	ctx = `nullptr`
	)		const

inline

Ground the control object with the given parts.

The given parts determine which program parts are grounded with which paramaters. If no parts are given, the parts given by the parts directive are grounded.

Parameters

parts	the parts to ground the control object with
ctx	the context to use for grounding

◆ ground() [2/2]

void Clingo::Control::ground	(	std::optional< PartSpan >	parts = `std::nullopt`,
		Context	ctx = `nullptr`
	)		const

inline

Ground the control object with the given parts.

The given parts determine which program parts are grounded with which paramaters. If no parts are given, the parts given by the parts directive are grounded.

Parameters

parts	the parts to ground the control object with
ctx	the context to use for grounding

◆ interrupt()

void Clingo::Control::interrupt ( ) const

inline

Interrupt the current solve operation.

This function is thread-safe and can be called from any thread.

◆ join()

void Clingo::Control::join ( AST::Program const & prg ) const

inline

Join the given non-ground program to the current control object.

Parameters

prg	the program to join

◆ main()

void Clingo::Control::main ( ) const

inline

Run the default ground and solve flow.

The flow can be configured by specifying a control mode and the parts to ground.

◆ mode()

auto Clingo::Control::mode ( ) const -> ControlMode

inline

Get the control mode.

Returns: the control mode

◆ observe()

void Clingo::Control::observe	(	Observer &	obs,
		bool	preprocess = `true`
	)		const

inline

Inspect the current ground program held by the control object.

Parameters

obs	the observer to use for inspecting the program
preprocess	whether to preprocess the program before observing

◆ parse_files() [1/2]

void Clingo::Control::parse_files ( StringList files ) const

inline

Parse files with the given paths.

It is also possible to read files in aspif format. However, aspif files must be read before grounding to avoid redefinition errors. Multiple aspif files can be given, for example, in the order they have been output by write_aspif.

Parameters

files the paths to the files to parse

◆ parse_files() [2/2]

void Clingo::Control::parse_files ( StringSpan files ) const

inline

Parse files with the given paths.

It is also possible to read files in aspif format. However, aspif files must be read before grounding to avoid redefinition errors. Multiple aspif files can be given, for example, in the order they have been output by write_aspif.

Parameters

files the paths to the files to parse

◆ parse_string()

void Clingo::Control::parse_string ( std::string_view program ) const

inline

Parse a logic program from a string.

Parameters

program the logic program to parse

◆ parts() [1/3]

auto Clingo::Control::parts ( ) const -> std::optional<PartVector>

inline

Get the parts to ground.

If no parts are set, the next call to ground would ground the base part.

Returns: the parts to ground, or an empty optional if no parts are set

◆ parts() [2/3]

void Clingo::Control::parts ( PartList parts ) const

inline

Set the parts to ground.

Parameters

parts the parts to set

◆ parts() [3/3]

void Clingo::Control::parts ( std::optional< PartSpan > parts ) const

inline

Set the parts to ground.

Use std::nullopt to ground the base part.

Parameters

parts the parts to set

◆ register_propagator()

template<std::derived_from< Propagator > T>

auto Clingo::Control::register_propagator ( std::unique_ptr< T > propagator ) const -> T &

inline

Register a propagator with the control object.

Can be used to register both propagators with and without heuristics.

Parameters

propagator the propagator to register

Returns: a reference to the registered propagator

◆ solve() [1/2]

auto Clingo::Control::solve	(	ProgramLiteralSpan const &	assumptions = `{}`,
		SolveFlags	flags = `SolveFlags::yield`
	)		const -> SolveHandle

inline

Solve the grounded program with the given assumptions and flags.

This function does not take a solve event handler. Instead, the returned solve handle is configured to yield models as they are found.

Parameters

assumptions	the assumptions to use for solving
flags	the flags to use for solving

Returns: a handle to the solve operation

◆ solve() [2/2]

auto Clingo::Control::solve	(	SolveEventHandler &	handler,
		ProgramLiteralSpan const &	assumptions = `{}`,
		SolveFlags	flags = `SolveFlags::empty`
	)		const -> SolveHandle

inline

Solve the grounded program with the given assumptions and flags.

Parameters

handler	the solve event handler to report events to
assumptions	the assumptions to use for solving
flags	the flags to use for solving

Returns: a handle to the solve operation

◆ stats()

auto Clingo::Control::stats ( ) const -> ConstStats

inline

Get the statistics of the control object.

Returns: the statistics of the control object

◆ write_aspif()

void Clingo::Control::write_aspif	(	std::string_view	path,
		WriteAspifFlags	flags = `WriteAspifFlags::none`
	)		const

inline

Write the current program to an ASPIF file.

Note that the control object discards previously grounded programs after calls to solve(). Only the part of the program grounded after the last call to solve() or at the beginning are written to the file.

Parameters

path	the path to the ASPIF file
flags	the flags to use when writing the ASPIF file

Friends And Related Symbol Documentation

◆ c_cast

auto c_cast ( Control const & ctl ) -> clingo_control_t *

friend

Cast to the C representation of the control object.

Parameters

ctl	the control object to cast

Returns: the C representation of the control object

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

clingo/control.hh

Public Types

Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

◆ Context

Constructor & Destructor Documentation

◆ Control() [1/3]

◆ Control() [2/3]

◆ Control() [3/3]

Member Function Documentation

◆ backend()

◆ base()

◆ buffer()

◆ config()

◆ const_map()

◆ discard()

◆ ground() [1/2]

◆ ground() [2/2]

◆ interrupt()

◆ join()

◆ main()

◆ mode()

◆ observe()

◆ parse_files() [1/2]

◆ parse_files() [2/2]

◆ parse_string()

◆ parts() [1/3]

◆ parts() [2/3]

◆ parts() [3/3]

◆ register_propagator()

◆ solve() [1/2]

◆ solve() [2/2]

◆ stats()

◆ write_aspif()

Friends And Related Symbol Documentation

◆ c_cast