Term input
Author(s): Daniel Cabeza (modifications and documentation, adapted from SICStus 0.6 code), Manuel Carro (modifications and documentation), Jose F. Morales (modifications for curly blocks, postfix blocks, and doccomments).
This module provides falicities to read terms in Prolog syntax. This is very convenient in many cases (and not only if you are writing a Prolog compiler), because Prolog terms are easy to write and can convey a lot of information in a human-readable fashion.
Usage and interface
- Library usage:
:- use_module(library(read)). - Exports:
- Predicates:
read/1, read/2, read_term/2, read_term/3, read_top_level/3, second_prompt/2. - Regular Types:
read_option/1. - Multifiles:
define_flag/3.
- Predicates:
- Imports:
- System library modules:
tokenize, operators, lists. - Packages:
prelude, nonpure, assertions, nortchecks, isomodes, define_flag.
- System library modules:
Documentation on exports
Like read(Stream,Term) with Stream associated to the current input stream.
Usage:ISO
- Call and exit should be compatible with:
(basic_props:term/1)Term is any term. - The following properties should hold upon exit:
(basic_props:term/1)Term is any term.
Usage:ISOread(Stream,Term)
The next term, delimited by a full-stop (i.e., a . followed by either a space or a control character), is read from Stream and is unified with Term. The syntax of the term must agree with current operator declarations. If the end of Stream has been reached, Term is unified with the term end_of_file. Further calls to read/2 for the same stream will then cause an error, unless the stream is connected to the terminal (in which case a prompt is opened on the terminal).
- The following properties should hold at call time:
(term_typing:nonvar/1)Stream is currently a term which is not a free variable.
(streams_basic:stream/1)Stream is an open stream.
(basic_props:term/1)Term is any term.
Usage:ISOread_term(Term,Options)
Like read_term/3, but reading from the current input
- The following properties should hold at call time:
(term_typing:nonvar/1)Options is currently a term which is not a free variable.
(basic_props:term/1)Term is any term.
(basic_props:list/2)Options is a list of read_options.
Usage:ISOread_term(Stream,Term,Options)
Reads a Term from Stream with the ISO-Prolog Options. These options can control the behavior of read term (see read_option/1).
- The following properties should hold at call time:
(term_typing:nonvar/1)Stream is currently a term which is not a free variable.
(term_typing:nonvar/1)Options is currently a term which is not a free variable.
(streams_basic:stream/1)Stream is an open stream.
(basic_props:term/1)Term is any term.
(basic_props:list/2)Options is a list of read_options.
Predicate used to read in the Top Level.
Usage:second_prompt(Old,New)
Changes the prompt (the second prompt, as opposed to the first one, used by the toplevel) used by read/2 and friends to New, and returns the current one in Old.
- The following properties should hold upon exit:
(term_typing:atom/1)Old is currently instantiated to an atom.
(term_typing:atom/1)New is currently instantiated to an atom.
Usage:read_option(Option)
Option is an allowed read_term/[2,3] option. These options are:
read_option(variables(_V)). read_option(variable_names(_N)). read_option(singletons(_S)). read_option(lines(_StartLine,_EndLine)). read_option(dictionary(_Dict)).They can be used to return the singleton variables in the term, a list of variables, etc.
- The following properties should hold upon exit:
(term_typing:atom/1)Option is currently instantiated to an atom.
Documentation on multifiles
define_flag(read_hiord,[on,off],off). define_flag(read_curly_blocks,[on,off],off). define_flag(read_postfix_blocks,[on,off],off).(See Changing system behaviour and various flags).
If flag is on (it is off by default), a variable followed by a parenthesized lists of arguments is read as a call/N term, except if the variable is anonymous, in which case it is read as an anonymous predicate abstraction head. For example, P(X) is read as call(P,X) and _(X,Y) as ”(X,Y).
(Trust) Usage:define_flag(Flag,FlagValues,Default)
- The following properties hold upon exit:
(basic_props:atm/1)Flag is an atom.
(basic_props:flag_values/1)Define the valid flag values
Known bugs and planned improvements
- Run-time checks have been reported not to work with this code. That means that either the assertions here, or the code that implements the run-time checks are erroneous.
- The comma cannot be redefined as an operator, it is defined in any case as op(1000, xfy,[',']).
