channel

tuprolog.solve.channel ¶

Input and output channels: how solvers read and write, e.g. for write/1 or warnings.

A channel connects a solver to the outside world: solvers read strings from input channels (e.g. their standard input), and write strings on output channels (e.g. their standard output and error), plus warnings on a dedicated channel. Channels are created from Python callables or streams, so the output of write/1 can go to sys.stdout, an io.StringIO, or a list.

Solvers hold their channels in stores, by name (an alias): InputStore (with stdin) and OutputStore (with stdout and stderr), where predicates opening streams add theirs.

Main types and functions:

InputChannel and OutputChannel (both Channels), created by input_channel and output_channel; ensure_input_channel and ensure_output_channel convert Python streams and callables;
std_in, std_out, std_err and warn: channels on Python's sys.stdin, sys.stdout and sys.stderr, the default ones of solvers;
InputStore and OutputStore (both ChannelStores), created by input_store and output_store;
Listener, created by listener: a callback receiving everything transiting a channel.

Examples:

>>> from tuprolog.solve.prolog import prolog_solver
>>> written = []
>>> solver = prolog_solver(std_out=output_channel(written.append))
>>> solver.solve_once("write(hello), write(world)").is_yes
True
>>> written
['hello', 'world']

Channel `module-attribute` ¶

Channel = _channel.Channel

A channel of communication between a solver and the outside world (base of input and output).

Members: close(), is_closed, stream_term (the term denoting the channel in Prolog programs), and addListener(listener), removeListener(listener), clearListeners(), to register callbacks receiving every element transiting the channel (see listener).

ChannelStore `module-attribute` ¶

ChannelStore = _channel.ChannelStore

An immutable map of channels by alias (base of InputStore and OutputStore).

Besides the read-only JVM map members (e.g. keys(), get(alias)), stores have the current channel (aliased $current, where predicates like write/1 write by default), aliases_of(channel) and find_by_term(stream_term). Changes return new stores: plus(...) (alias-channel pairs), minus(...) (aliases), set_current(...), close(channel).

InputChannel `module-attribute` ¶

InputChannel = _channel.InputChannel

A channel solvers read strings from, e.g. their standard input.

Members: read() (the next string, None at the end), peek() (the next string, without consuming it), available, is_over, and those of Channel. Create input channels with input_channel.

Examples:

>>> from tuprolog.solve.channel import input_channel
>>> channel = input_channel("ab")
>>> channel.read(), channel.peek(), channel.read(), channel.read()
('a', 'b', 'b', None)

InputStore `module-attribute` ¶

InputStore = _channel.InputStore

The input channels of a solver, by alias (a ChannelStore).

Its standard input, std_in, is aliased stdin (InputStore.STDIN, also user_input). Create input stores with input_store.

OutputChannel `module-attribute` ¶

OutputChannel = _channel.OutputChannel

A channel solvers write on, e.g. their standard output, standard error, or warnings.

Members: write(value), flush(), and those of Channel. Create output channels with output_channel.

Examples:

>>> from tuprolog.solve.channel import output_channel
>>> received = []
>>> output_channel(received.append).write("hello")
>>> received
['hello']

OutputStore `module-attribute` ¶

OutputStore = _channel.OutputStore

The output channels of a solver, by alias (a ChannelStore), plus the channel of warnings.

Its standard output, std_out, is aliased stdout (OutputStore.STDOUT, also user_output), its standard error, std_err, stderr (OutputStore.STDERR); the channel of warnings, warnings, has no alias. Create output stores with output_store.

Listener `module-attribute` ¶

Listener = _kfunctions.Function1

A callback receiving every element transiting a channel: a Kotlin function of one argument.

Create listeners from Python callables with listener, and register them with channel.addListener(listener).

ReaderChannel `module-attribute` ¶

ReaderChannel = _channel.ReaderChannel

An input channel reading a JVM java.io.Reader (or InputStream), one character at a time.

input_channel creates one for JVM input streams (see tuprolog.jvmioutils).

WriterChannel `module-attribute` ¶

WriterChannel = _channel.WriterChannel

An output channel writing on a JVM java.io.Writer (or OutputStream).

std_in ¶

std_in() -> InputChannel

Creates an input channel reading Python's sys.stdin, one character at a time.

sys.stdin is looked up at each read, so it follows its replacements (e.g. by tests), and sys.stdout is flushed before each read, as input() does, to show pending prompts.

Returns:

Type	Description
`InputChannel`	The input channel; solvers use one by default.

input_channel ¶

input_channel(
    generator: Callable | str | IOBase,
    availability_checker: Callable | None = None,
) -> InputChannel

Creates an input channel from a Python callable, a string, or a Python stream.

Strings and streams are read one character at a time (see input_channel_from_string and input_channel_from_stream).

Parameters:

Name	Type	Description	Default
`generator`	`Callable \| str \| IOBase`	A callable taking no argument, and returning the next string at each call, or `None` at the end; or a string, or a Python stream.	required
`availability_checker`	`Callable \| None`	For callables, a callable taking no argument and returning whether more strings are available; by default, they are while `generator` returns strings.	`None`

Returns:

Type	Description
`InputChannel`	The input channel.

Examples:

>>> lines = iter(["first", "second"])
>>> channel = input_channel(lambda: next(lines, None))
>>> channel.read(), channel.read(), channel.read()
('first', 'second', None)

input_channel_from_string ¶

input_channel_from_string(string: str) -> InputChannel

Creates an input channel reading a string, one character at a time.

Parameters:

Name	Type	Description	Default
`string`	`str`	The text to read.	required

Returns:

Type	Description
`InputChannel`	The input channel, also returned by `input_channel(string)`.

Examples:

>>> channel = input_channel_from_string("hi")
>>> channel.read(), channel.read(), channel.read()
('h', 'i', None)

input_channel_from_stream ¶

input_channel_from_stream(stream: IOBase) -> InputChannel

Creates an input channel reading a Python stream, one character at a time.

Parameters:

Name	Type	Description	Default
`stream`	`IOBase`	A text stream, a binary stream (decoded as UTF-8), or a JVM input stream from `tuprolog.jvmioutils` (read through a `ReaderChannel`).	required

Returns:

Type	Description
`InputChannel`	The input channel, also returned by `input_channel(stream)`.

Examples:

>>> import io
>>> channel = input_channel_from_stream(io.BytesIO("né".encode()))
>>> channel.read(), channel.read(), channel.read()
('n', 'é', None)

ensure_input_channel ¶

ensure_input_channel(
    channel: InputChannel | IOBase | Callable | None,
    default: Callable[[], InputChannel] = std_in,
) -> InputChannel

Converts a Python stream or callable into an input channel, leaving input channels as they are.

Parameters:

Name	Type	Description	Default
`channel`	`InputChannel \| IOBase \| Callable \| None`	An input channel, a Python stream, a callable (see `input_channel`), or `None`.	required
`default`	`Callable[[], InputChannel]`	A function creating the input channel to return for `None`; by default, `std_in`.	`std_in`

Returns:

Type	Description
`InputChannel`	The input channel.

Raises:

Type	Description
`TypeError`	If `channel` is of none of the types above.

input_store ¶

input_store(
    stdin: InputChannel | IOBase | None = None,
    channels: Mapping[str, InputChannel | IOBase]
    | None = None,
) -> InputStore

Creates a store of input channels.

Parameters:

Name	Type	Description	Default
`stdin`	`InputChannel \| IOBase \| None`	The standard input, converted by `ensure_input_channel`; by default, `std_in()`.	`None`
`channels`	`Mapping[str, InputChannel \| IOBase] \| None`	More input channels (or Python streams), by alias.	`None`

Returns:

Type	Description
`InputStore`	The input store, also aliasing the standard input as the current input.

Examples:

>>> store = input_store(channels={"data": input_channel("x")})
>>> sorted(store.keys())
['$current', 'data', 'stdin']

std_out ¶

std_out() -> OutputChannel

Creates an output channel writing on Python's sys.stdout, as looked up at each write.

Returns:

Type	Description
`OutputChannel`	The output channel; solvers use one by default.

std_err ¶

std_err() -> OutputChannel

Creates an output channel writing on Python's sys.stderr, as looked up at each write.

Returns:

Type	Description
`OutputChannel`	The output channel; solvers use one as standard error by default.

warn ¶

warn() -> OutputChannel

Creates an output channel writing the messages of warnings on Python's sys.stderr.

Each warning's message is written on a line of its own; sys.stderr is looked up at each write.

Returns:

Type	Description
`OutputChannel`	The output channel; solvers use one for warnings by default.

output_channel ¶

output_channel(
    consumer: Callable | IOBase,
) -> OutputChannel

Creates an output channel feeding a Python callable, or writing on a Python stream.

Parameters:

Name	Type	Description	Default
`consumer`	`Callable \| IOBase`	A callable taking each value written (a Python string for strings, else the JVM object, e.g. a `tuprolog.solve.exception.Warning`); or a text stream, or a binary stream (written in UTF-8), on which values are written as strings (warnings as their message, on a line of their own).	required

Returns:

Type	Description
`OutputChannel`	The output channel.

Examples:

>>> import io
>>> buffer = io.StringIO()
>>> output_channel(buffer).write("hello")
>>> buffer.getvalue()
'hello'

ensure_output_channel ¶

ensure_output_channel(
    channel: OutputChannel | IOBase | Callable | None,
    default: Callable[[], OutputChannel] = std_out,
) -> OutputChannel

Converts a Python stream or callable into an output channel, leaving output channels as they are.

Parameters:

Name	Type	Description	Default
`channel`	`OutputChannel \| IOBase \| Callable \| None`	An output channel, a Python stream, a callable (see `output_channel`), or `None`.	required
`default`	`Callable[[], OutputChannel]`	A function creating the output channel to return for `None`; by default, `std_out`.	`std_out`

Returns:

Type	Description
`OutputChannel`	The output channel.

Raises:

Type	Description
`TypeError`	If `channel` is of none of the types above.

output_store ¶

output_store(
    stdout: OutputChannel | IOBase | None = None,
    stderr: OutputChannel | IOBase | None = None,
    warnings: OutputChannel | IOBase | None = None,
    channels: Mapping[str, OutputChannel | IOBase]
    | None = None,
) -> OutputStore

Creates a store of output channels.

Parameters:

Name	Type	Description	Default
`stdout`	`OutputChannel \| IOBase \| None`	The standard output, converted by `ensure_output_channel`; by default, `std_out()`.	`None`
`stderr`	`OutputChannel \| IOBase \| None`	The standard error; by default, `std_err()`.	`None`
`warnings`	`OutputChannel \| IOBase \| None`	The channel of warnings; by default, `warn()`.	`None`
`channels`	`Mapping[str, OutputChannel \| IOBase] \| None`	More output channels (or Python streams or callables), by alias.	`None`

Returns:

Type	Description
`OutputStore`	The output store, also aliasing the standard output as the current output.

Examples:

>>> sorted(output_store().keys())
['$current', 'stderr', 'stdout']

listener ¶

listener(consumer: Callable) -> Listener

Creates a listener of channels from a Python callable.

Parameters:

Name	Type	Description	Default
`consumer`	`Callable`	A callable taking each element transiting the channels it listens to.	required

Returns:

Type	Description
`Listener`	The listener, to register with `channel.addListener(listener)`.

Examples:

>>> seen = []
>>> channel = output_channel(lambda _: None)
>>> channel.addListener(listener(seen.append))
>>> channel.write("x")
>>> seen
['x']

channel

tuprolog.solve.channel ¶

Channel module-attribute ¶

ChannelStore module-attribute ¶

InputChannel module-attribute ¶

InputStore module-attribute ¶

OutputChannel module-attribute ¶

OutputStore module-attribute ¶

Listener module-attribute ¶

ReaderChannel module-attribute ¶

WriterChannel module-attribute ¶

std_in ¶

input_channel ¶

input_channel_from_string ¶

input_channel_from_stream ¶

ensure_input_channel ¶

input_store ¶

std_out ¶

std_err ¶

warn ¶

output_channel ¶

ensure_output_channel ¶

output_store ¶

listener ¶

Channel `module-attribute` ¶

ChannelStore `module-attribute` ¶

InputChannel `module-attribute` ¶

InputStore `module-attribute` ¶

OutputChannel `module-attribute` ¶

OutputStore `module-attribute` ¶

Listener `module-attribute` ¶

ReaderChannel `module-attribute` ¶

WriterChannel `module-attribute` ¶