Module clingo.script

This module contains functions to add custom scripts, which can be embedded into logic programs.

Examples

The following example shows how to add a script that works the same way as clingo's embedded Python script:

>>> from clingo.script import Script, register_script
>>> from clingo.control import Control
>>>
>>> import __main__
>>>
>>> class MyPythonScript(Script):
...     def execute(self, location, code):
...         exec(code, __main__.__dict__, __main__.__dict__)
...     def call(self, location, name, arguments):
...         return getattr(__main__, name)(*arguments)
...     def callable(self, name):
...         return name in __main__.__dict__ and callable(__main__.__dict__[name])
...
>>> register_script('mypython', MyPythonScript())
>>>
>>> ctl = Control()
>>> ctl.add('base', [], """
... #script(mypython)
... from clingo.symbol import Number
... def func(a):
...     return Number(a.number + 1)
... #end.
... a(@func(1)).
... """)
>>>
>>> ctl.ground([('base',[])])
>>> ctl.solve(on_model=print)
a(2)

Functions

def enable_python() ‑> None

Expand source code

def enable_python() -> None:
    """
    This function can be called to enable evaluation of Python scripts in logic
    programs.

    By default evaluation is only enabled in the clingo executable but not in
    the Python module.
    """
    c_version = _c_call(
        "char const*", _lib.clingo_add_string, python_version().encode()
    )
    c_script = _ffi.new("clingo_script_t*")
    c_script[0].execute = _ffi.cast("void*", _lib.pyclingo_execute)
    c_script[0].call = _ffi.cast("void*", _lib.pyclingo_call)
    c_script[0].callable = _ffi.cast("void*", _lib.pyclingo_callable)
    c_script[0].main = _ffi.cast("void*", _lib.pyclingo_main)
    c_script[0].free = _ffi.NULL
    c_script[0].version = c_version
    _handle_error(_lib.clingo_register_script("python".encode(), c_script, _ffi.NULL))

This function can be called to enable evaluation of Python scripts in logic programs.

By default evaluation is only enabled in the clingo executable but not in the Python module.

def register_script(name: str,
script: Script,
version: str = '1.0.0') ‑> None

Expand source code

def register_script(name: str, script: Script, version: str = "1.0.0") -> None:
    """
    Registers a script language which can then be embedded into a logic
    program.

    Parameters
    ----------
    name
        The name of the script. This name can then be used in the script
        statement in a logic program.
    script
        The class to register.
    version
        The version of the script.
    """
    c_version = _c_call("char const*", _lib.clingo_add_string, version.encode())
    c_script = _ffi.new("clingo_script_t*")
    c_script[0].execute = _ffi.cast("void*", _lib.pyclingo_script_execute)
    c_script[0].call = _ffi.cast("void*", _lib.pyclingo_script_call)
    c_script[0].callable = _ffi.cast("void*", _lib.pyclingo_script_callable)
    c_script[0].main = _ffi.cast("void*", _lib.pyclingo_script_main)
    c_script[0].free = _ffi.NULL
    c_script[0].version = c_version
    data = _ffi.new_handle(script)
    _GLOBAL_SCRIPTS.append((script, data))
    _handle_error(_lib.clingo_register_script(name.encode(), c_script, data))

Registers a script language which can then be embedded into a logic program.

Parameters

name

The name of the script. This name can then be used in the script statement in a logic program.

script

The class to register.

version

The version of the script.

Classes

class Script

Expand source code

class Script(metaclass=ABCMeta):
    """
    This interface can be implemented to embed custom scripting languages into
    logic programs.
    """

    @abstractmethod
    def execute(self, location: Location, code: str) -> None:
        """
        Execute the given source code.

        Parameters
        ----------
        location
            The location of the code.
        code
            The code to execute.
        """

    @abstractmethod
    def call(
        self, location: Location, name: str, arguments: Iterable[Symbol]
    ) -> Union[Iterable[Symbol], Symbol]:
        """
        Call the function with the given name and arguments.

        Parameters
        ----------
        location
            From where in the logic program the function was called.
        name
            The name of the function.
        arguments
            The arguments to the function.

        Returns
        -------
        The resulting pool of symbols.
        """

    @abstractmethod
    def callable(self, name: str) -> bool:
        """
        Check there is a function with the given name.

        Parameters
        ----------
        name
            The name of the function.

        Returns
        -------
        Whether the function is callable.
        """

    def main(self, control: Control) -> None:
        """
        Run the main function.

        This function exisits primarily for internal purposes and does not need
        to be implemented.

        Parameters
        ----------
        control
            Control object to pass to the main function.
        """

This interface can be implemented to embed custom scripting languages into logic programs.

Subclasses

• clingo.script._PythonScript

Methods

def call(self,
location: Location,
name: str,
arguments: Iterable[Symbol]) ‑> Iterable[Symbol] | Symbol

Expand source code

@abstractmethod
def call(
    self, location: Location, name: str, arguments: Iterable[Symbol]
) -> Union[Iterable[Symbol], Symbol]:
    """
    Call the function with the given name and arguments.

    Parameters
    ----------
    location
        From where in the logic program the function was called.
    name
        The name of the function.
    arguments
        The arguments to the function.

    Returns
    -------
    The resulting pool of symbols.
    """

Call the function with the given name and arguments.

Parameters

location

From where in the logic program the function was called.

name

The name of the function.

arguments

The arguments to the function.

Returns

The resulting pool of symbols.

def callable(self, name: str) ‑> bool

Expand source code

@abstractmethod
def callable(self, name: str) -> bool:
    """
    Check there is a function with the given name.

    Parameters
    ----------
    name
        The name of the function.

    Returns
    -------
    Whether the function is callable.
    """

Check there is a function with the given name.

Parameters

name

The name of the function.

Returns

Whether the function is callable.

def execute(self,
location: Location,
code: str) ‑> None

Expand source code

@abstractmethod
def execute(self, location: Location, code: str) -> None:
    """
    Execute the given source code.

    Parameters
    ----------
    location
        The location of the code.
    code
        The code to execute.
    """

Execute the given source code.

Parameters

location

The location of the code.

code

The code to execute.

def main(self,
control: Control) ‑> None

Expand source code

def main(self, control: Control) -> None:
    """
    Run the main function.

    This function exisits primarily for internal purposes and does not need
    to be implemented.

    Parameters
    ----------
    control
        Control object to pass to the main function.
    """

Run the main function.

This function exisits primarily for internal purposes and does not need to be implemented.

Parameters

control

Control object to pass to the main function.