parsing

tuprolog.core.parsing ¶

Parsing terms and clauses from Prolog text.

Parsing turns text in Prolog syntax, e.g. "parent(X, bart)", into terms. In one text, equally named variables are the same variable (_ excepted), and operators (see tuprolog.core.operators) let expressions such as X is 1 + 2 be read: parsers use the default operator set, unless given another one.

This package offers:

functions parsing one term from a string with the default parser, possibly checking its type: parse_term, parse_struct, parse_atom, parse_var, parse_constant, parse_numeric, parse_integer, parse_real, parse_clause;
functions reading terms ending with . from streams: read_term and read_terms;
parsers and readers with custom operators (TermParser, TermReader, term_parser, term_reader), and the default ones (DEFAULT_TERM_PARSER, DEFAULT_TERM_READER);
the exceptions raised on errors: ParseException and InvalidTermTypeException.

Examples:

>>> from tuprolog.core.parsing import parse_clause, parse_term
>>> parse_term("parent(X, bart)")
parent(X_..., bart)
>>> clause = parse_clause("grandparent(X, Z) :- parent(X, Y), parent(Y, Z)")
>>> clause.head, clause.body_size
(grandparent(X_..., Z_...), 2)

TermParser `module-attribute` ¶

TermParser = _parsing.TermParser

A parser of terms from strings, holding a default operator set.

Each method parses one term (without the final .), checks that it has the requested type, and raises ParseException on syntax errors (InvalidTermTypeException on type mismatches). Variables with the same name in one string are the same variable; _ is anonymous.

Build parsers with tuprolog.core.parsing.term_parser, or use DEFAULT_TERM_PARSER. Members: default_operator_set, and the methods parse_term, parse_struct, parse_constant, parse_var, parse_atom, parse_numeric, parse_integer, parse_real, parse_clause (each taking a string and, optionally, an operator set), plus parse (an alias of parse_term).

Examples:

>>> from tuprolog.core.parsing import term_parser
>>> parser = term_parser()
>>> parser.parse_clause("ancestor(X, Y) :- parent(X, Y)")
ancestor(X_..., Y_...) :- parent(X_..., Y_...)

Note

2P-Kt's it.unibo.tuprolog.core.parsing.TermParser.

TermReader `module-attribute` ¶

TermReader = _parsing.TermReader

A reader of terms from streams, i.e. of Prolog text made of terms each ending with ., holding a default operator set.

Build readers with tuprolog.core.parsing.term_reader, or use DEFAULT_TERM_READER. Members: default_operator_set, read_term(input, operators=None) (the next term, or None at the end), read_terms(input, operators=None) (all terms, lazily), and their aliases read and read_all. The input is a JVM InputStream, a Python stream (binary or text), or a file path; it is closed once read.

Examples:

>>> import io
>>> from tuprolog.core.parsing import term_reader
>>> list(term_reader().read_terms(io.StringIO("parent(homer, bart). parent(abe, homer).")))
[parent(homer, bart), parent(abe, homer)]

Note

2P-Kt's it.unibo.tuprolog.core.parsing.TermReader.

ParseException `module-attribute` ¶

ParseException = _parsing.ParseException

Raised when parsing fails because the text is not valid Prolog syntax.

Members: input (the parsed text, or the name of the source), offending_symbol (the text where parsing failed, when known), line and column (where parsing failed, from 1).

Examples:

>>> from tuprolog.core.parsing import parse_term
>>> try:
...     parse_term("f(a")
... except ParseException as e:
...     print(e.line, e.column)
1 4

Note

2P-Kt's it.unibo.tuprolog.core.parsing.ParseException.

InvalidTermTypeException `module-attribute` ¶

InvalidTermTypeException = _parsing.InvalidTermTypeException

Raised when parsing succeeds, but gives a term of another type than the requested one (e.g. parse_atom("f(x)")). A ParseException.

Members: term (the parsed term), type (the requested type), and those of ParseException.

Note

2P-Kt's it.unibo.tuprolog.core.parsing.InvalidTermTypeException.

DEFAULT_TERM_PARSER `module-attribute` ¶

DEFAULT_TERM_PARSER = TermParser.withDefaultOperators()

The term parser with the default operators (see DEFAULT_OPERATORS), used by the parse_* functions.

DEFAULT_TERM_READER `module-attribute` ¶

DEFAULT_TERM_READER = TermReader.withDefaultOperators()

The term reader with the default operators (see DEFAULT_OPERATORS), used by read_term and read_terms.

parser_factory ¶

parser_factory(
    source: Any,
    with_default_operators: bool = True,
    operators: OperatorSet | None = None,
) -> Any

Builds a parser or a reader with a given operator set (used by term_parser and term_reader).

Parameters:

Name	Type	Description	Default
`source`	`Any`	the factory, i.e. `TermParser` or `TermReader` (anything with `withDefaultOperators`, `withNoOperator` and `withOperators` methods).	required
`with_default_operators`	`bool`	whether to include the default operators (`DEFAULT_OPERATORS`).	`True`
`operators`	`OperatorSet \| None`	other operators to include. If `None`, none.	`None`

Returns:

Type	Description
`Any`	The parser (or reader).

term_parser ¶

term_parser(
    with_default_operators: bool = True,
    operators: OperatorSet | None = None,
) -> TermParser

Creates a term parser with a given default operator set.

Parameters:

Name	Type	Description	Default
`with_default_operators`	`bool`	whether to include the default operators (`DEFAULT_OPERATORS`).	`True`
`operators`	`OperatorSet \| None`	other operators to include (e.g. declared by a program). If `None`, none.	`None`

Returns:

Type	Description
`TermParser`	The parser.

Examples:

>>> from tuprolog.core.operators import XFX, operator, operator_set
>>> parser = term_parser(operators=operator_set(operator("++", XFX, 700)))
>>> parser.parse_term("X ++ 1 + 2")
'++'(X_..., '+'(1, 2))

term_reader ¶

term_reader(
    with_default_operators: bool = True,
    operators: OperatorSet | None = None,
) -> TermReader

Creates a term reader with a given default operator set.

Parameters:

Name	Type	Description	Default
`with_default_operators`	`bool`	whether to include the default operators (`DEFAULT_OPERATORS`).	`True`
`operators`	`OperatorSet \| None`	other operators to include (e.g. declared by a program). If `None`, none.	`None`

Returns:

Type	Description
`TermReader`	The reader (a `TermReader`).

Examples:

>>> import io
>>> reader = term_reader()
>>> reader.read_term(io.StringIO("f(X). g(Y)."))
f(X_...)

parse_term ¶

parse_term(
    string: str, operators: OperatorSet | None = None
) -> Term

Parses a term from a string, with the default parser (DEFAULT_TERM_PARSER).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Term`	The term.

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.

Examples:

>>> parse_term("f(X, [1, 2 | T], 'Hello')")
f(X_..., [1, 2 | T_...], 'Hello')
>>> t = parse_term("f(X, X)")
>>> t[0] == t[1]
True
>>> from tuprolog.core.operators import DEFAULT_OPERATORS, XFX, operator
>>> parse_term("a ++ b", DEFAULT_OPERATORS + operator("++", XFX, 700))
'++'(a, b)

parse_struct ¶

parse_struct(
    string: str, operators: OperatorSet | None = None
) -> Struct

Parses a structure from a string, with the default parser (DEFAULT_TERM_PARSER).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Struct`	The structure.

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.
`InvalidTermTypeException`	if `string` is valid, but represents another kind of term.

Examples:

>>> parse_struct("parent(homer, bart)").arity
2

parse_constant ¶

parse_constant(
    string: str, operators: OperatorSet | None = None
) -> Constant

Parses a constant (an atom or a number) from a string, with the default parser (DEFAULT_TERM_PARSER).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Constant`	The constant.

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.
`InvalidTermTypeException`	if `string` is valid, but represents another kind of term.

Examples:

>>> parse_constant("bart"), parse_constant("42")
(bart, 42)

parse_var ¶

parse_var(
    string: str, operators: OperatorSet | None = None
) -> Var

Parses a variable from a string, with the default parser (DEFAULT_TERM_PARSER).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Var`	The variable.

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.
`InvalidTermTypeException`	if `string` is valid, but represents another kind of term.

Examples:

>>> parse_var("X").name
'X'

parse_atom ¶

parse_atom(
    string: str, operators: OperatorSet | None = None
) -> Atom

Parses an atom from a string, with the default parser (DEFAULT_TERM_PARSER).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Atom`	The atom.

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.
`InvalidTermTypeException`	if `string` is valid, but represents another kind of term.

Examples:

>>> parse_atom("'Hello World'").value
'Hello World'

parse_numeric ¶

parse_numeric(
    string: str, operators: OperatorSet | None = None
) -> Numeric

Parses a number from a string, with the default parser (DEFAULT_TERM_PARSER).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Numeric`	The number (an integer or a real).

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.
`InvalidTermTypeException`	if `string` is valid, but represents another kind of term.

Examples:

>>> parse_numeric("42"), parse_numeric("2.5"), parse_numeric("0x1F")
(42, 2.5, 31)

parse_integer ¶

parse_integer(
    string: str, operators: OperatorSet | None = None
) -> Integer

Parses an integer from a string, with the default parser (DEFAULT_TERM_PARSER).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Integer`	The integer.

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.
`InvalidTermTypeException`	if `string` is valid, but represents another kind of term.

Examples:

>>> parse_integer("123456789012345678901234567890").value
123456789012345678901234567890

parse_real ¶

parse_real(
    string: str, operators: OperatorSet | None = None
) -> Real

Parses a real number from a string, with the default parser (DEFAULT_TERM_PARSER).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Real`	The real.

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.
`InvalidTermTypeException`	if `string` is valid, but represents another kind of term.

Examples:

>>> parse_real("3.14").value
Decimal('3.14')

parse_clause ¶

parse_clause(
    string: str, operators: OperatorSet | None = None
) -> Clause

Parses a clause from a string, with the default parser (DEFAULT_TERM_PARSER).

The text must be a rule or a fact with an explicit :- (e.g. "p :- true"), or a directive (":- goal"): a bare head, e.g. "p", is not a clause here (wrap it with tuprolog.core.fact, or read whole programs with tuprolog.theory.parsing).

Parameters:

Name	Type	Description	Default
`string`	`str`	the text, in Prolog syntax, without the final `.`.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Clause`	The clause.

Raises:

Type	Description
`ParseException`	if `string` is not valid Prolog syntax.
`InvalidTermTypeException`	if `string` is valid, but represents another kind of term.

Examples:

>>> parse_clause("grandparent(X, Z) :- parent(X, Y), parent(Y, Z)")
grandparent(X_..., Z_...) :- (parent(X_..., Y_...), parent(Y_..., Z_...))
>>> parse_clause("parent(homer, bart) :- true"), parse_clause(":- dynamic(counter/1)")
(parent(homer, bart) :- true, :- dynamic(counter/1))

read_term ¶

read_term(
    input: InputStream | str,
    operators: OperatorSet | None = None,
) -> Term

Reads the first term from a stream, with the default reader (DEFAULT_TERM_READER).

Parameters:

Name	Type	Description	Default
`input`	`InputStream \| str`	a Python stream (binary or text), a JVM `InputStream`, or a file path: a string is a path, not Prolog text (use `parse_term` for that). It is closed once read.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Term`	The first term (each term ends with `.`), or `None` if there is none.

Raises:

Type	Description
`ParseException`	if the text is not valid Prolog syntax.

Examples:

>>> import io
>>> read_term(io.StringIO("parent(homer, bart). parent(abe, homer)."))
parent(homer, bart)

read_terms ¶

read_terms(
    input: InputStream | str,
    operators: OperatorSet | None = None,
) -> Iterable[Term]

Reads all the terms from a stream, lazily, with the default reader (DEFAULT_TERM_READER).

Parameters:

Name	Type	Description	Default
`input`	`InputStream \| str`	a Python stream (binary or text), a JVM `InputStream`, or a file path: a string is a path, not Prolog text. It is closed once read.	required
`operators`	`OperatorSet \| None`	the operators to parse with, replacing the parser's default ones (so pass e.g. `DEFAULT_OPERATORS + custom` to add operators). If `None`, the parser's default ones.	`None`

Returns:

Type	Description
`Iterable[Term]`	The terms (each ending with `.` in the text), as a lazy iterable, to consume once: syntax
`Iterable[Term]`	errors raise `ParseException` while iterating.

Examples:

>>> import io
>>> list(read_terms(io.StringIO("parent(homer, bart). ancestor(X, Y) :- parent(X, Y).")))
[parent(homer, bart), ancestor(X_..., Y_...) :- parent(X_..., Y_...)]

parsing

tuprolog.core.parsing ¶

TermParser module-attribute ¶

TermReader module-attribute ¶

ParseException module-attribute ¶

InvalidTermTypeException module-attribute ¶

DEFAULT_TERM_PARSER module-attribute ¶

DEFAULT_TERM_READER module-attribute ¶

parser_factory ¶

term_parser ¶

term_reader ¶

parse_term ¶

parse_struct ¶

parse_constant ¶

parse_var ¶

parse_atom ¶

parse_numeric ¶

parse_integer ¶

parse_real ¶

parse_clause ¶

read_term ¶

read_terms ¶

TermParser `module-attribute` ¶

TermReader `module-attribute` ¶

ParseException `module-attribute` ¶

InvalidTermTypeException `module-attribute` ¶

DEFAULT_TERM_PARSER `module-attribute` ¶

DEFAULT_TERM_READER `module-attribute` ¶