Extending Clingo

Detailed Description

Functions to customize clingo's main function.

This module allows for customizing the clingo application. For example, this can be used to register custom propagators and command line options with clingo.

Warning: This part of the API is not yet finalized and might change in the future.

Classes
struct	clingo_application
	This struct contains a set of functions to customize the clingo application. More...
struct	clingo_script
	Custom scripting language to run functions during grounding. More...

Typedefs
typedef struct clingo_options	clingo_options_t
	Object to add command-line options.
typedef bool(*	clingo_main_function_t) (clingo_control_t *control, char const *const *files, size_t size, void *data)
	Callback to customize clingo main function. More...
typedef bool(*	clingo_default_model_printer_t) (void *data)
	Callback to print a model in default format. More...
typedef bool(*	clingo_model_printer_t) (clingo_model_t const *model, clingo_default_model_printer_t printer, void *printer_data, void *data)
	Callback to customize model printing. More...
typedef struct clingo_application	clingo_application_t
	This struct contains a set of functions to customize the clingo application.
typedef struct clingo_script	clingo_script_t
	Custom scripting language to run functions during grounding.

Functions
CLINGO_VISIBILITY_DEFAULT bool	clingo_options_add (clingo_options_t *options, char const *group, char const *option, char const *description, bool(*parse)(char const *value, void *data), void *data, bool multi, char const *argument)
	Add an option that is processed with a custom parser. More...
CLINGO_VISIBILITY_DEFAULT bool	clingo_options_add_flag (clingo_options_t *options, char const *group, char const *option, char const *description, bool *target)
	Add an option that is a simple flag. More...
CLINGO_VISIBILITY_DEFAULT int	clingo_main (clingo_application_t *application, char const *const *arguments, size_t size, void *data)
	Run clingo with a customized main function (similar to python and lua embedding). More...
CLINGO_VISIBILITY_DEFAULT bool	clingo_register_script (char const *name, clingo_script_t const *script, void *data)
	Add a custom scripting language to clingo. More...
CLINGO_VISIBILITY_DEFAULT const char *	clingo_script_version (char const *name)
	Get the version of the registered scripting language. More...

Typedef Documentation

clingo_default_model_printer_t

typedef bool(* clingo_default_model_printer_t) (void *data)

Callback to print a model in default format.

Parameters

[in]

data

user data for the callback

Returns

whether the call was successful

clingo_main_function_t

typedef bool(* clingo_main_function_t) (clingo_control_t *control, char const *const *files, size_t size, void *data)

Callback to customize clingo main function.

Parameters

[in]	control	corresponding control object
[in]	files	files passed via command line arguments
[in]	size	number of files
[in]	data	user data for the callback

Returns

whether the call was successful

clingo_model_printer_t

typedef bool(* clingo_model_printer_t) (clingo_model_t const *model, clingo_default_model_printer_t printer, void *printer_data, void *data)

Callback to customize model printing.

Parameters

[in]	model	the model
[in]	printer	the default model printer
[in]	printer_data	user data for the printer
[in]	data	user data for the callback

Returns

whether the call was successful

Function Documentation

clingo_main()

CLINGO_VISIBILITY_DEFAULT int clingo_main	(	clingo_application_t *	application,
		char const *const *	arguments,
		size_t	size,
		void *	data
	)

Run clingo with a customized main function (similar to python and lua embedding).

Parameters

[in]	application	struct with callbacks to override default clingo functionality
[in]	arguments	command line arguments
[in]	size	number of arguments
[in]	data	user data to pass to callbacks in application

Returns

exit code to return from main function

Examples

application.c.

clingo_options_add()

CLINGO_VISIBILITY_DEFAULT bool clingo_options_add	(	clingo_options_t *	options,
		char const *	group,
		char const *	option,
		char const *	description,
		bool(*)(char const *value, void *data)	parse,
		void *	data,
		bool	multi,
		char const *	argument
	)

Add an option that is processed with a custom parser.

Note that the parser also has to take care of storing the semantic value of the option somewhere.

Parameter option specifies the name(s) of the option. For example, "ping,p" adds the short option "-p" and its long form "--ping". It is also possible to associate an option with a help level by adding ",@l" to the option specification. Options with a level greater than zero are only shown if the argument to help is greater or equal to l.

Parameters

[in]	options	object to register the option with
[in]	group	options are grouped into sections as given by this string
[in]	option	specifies the command line option
[in]	description	the description of the option
[in]	parse	callback to parse the value of the option
[in]	data	user data for the callback
[in]	multi	whether the option can appear multiple times on the command-line
[in]	argument	optional string to change the value name in the generated help output

Returns

whether the call was successful

Examples

application.c.

clingo_options_add_flag()

CLINGO_VISIBILITY_DEFAULT bool clingo_options_add_flag	(	clingo_options_t *	options,
		char const *	group,
		char const *	option,
		char const *	description,
		bool *	target
	)

Add an option that is a simple flag.

This function is similar to clingo_options_add() but simpler because it only supports flags, which do not have values. If a flag is passed via the command-line the parameter target is set to true.

Parameters

[in]	options	object to register the option with
[in]	group	options are grouped into sections as given by this string
[in]	option	specifies the command line option
[in]	description	the description of the option
[in]	target	boolean set to true if the flag is given on the command-line

Returns

whether the call was successful

clingo_register_script()

CLINGO_VISIBILITY_DEFAULT bool clingo_register_script	(	char const *	name,
		clingo_script_t const *	script,
		void *	data
	)

Add a custom scripting language to clingo.

Parameters

[in]	name	the name of the scripting language
[in]	script	struct with functions implementing the language
[in]	data	user data to pass to callbacks in the script

Returns

whether the call was successful

clingo_script_version()

CLINGO_VISIBILITY_DEFAULT const char* clingo_script_version

(

char const *

name

)

Get the version of the registered scripting language.

Parameters

[in]

name

the name of the scripting language

Returns

the version