This module provides predicates to open, close and read terms from
Prolog source-files. This may seem easy, but there are a couple of
problems that must be taken care of.
- Source files may start with #!, supporting PrologScript
- Embedded operators declarations must be taken into account
- Style-check options must be taken into account
- Operators and style-check options may be implied by directives
- On behalf of the development environment we also wish to
parse PceEmacs buffers
This module concentrates these issues in a single library. Intended
users of the library are:
- The Prolog cross-referencer
- Get details about (compiled) clauses
- Colourise source-code
- Emacs syntax-colouring
- The documentation framework
- prolog_read_source_term(+In, -Term, -Expanded, +Options) is det
- Read a term from a Prolog source-file. Options is a option list
that is forwarded to read_clause/3.
This predicate is intended to read the file from the start. It
tracks directives to update its notion of the currently
effective syntax (e.g., declared operators).
|Term||- Term read|
|Expanded||- Result of term-expansion on the term|
- See also
- - read_source_term_at_location/3 for reading at an
- requires_library(+Term, -Library)[multifile]
- known expansion hooks. May be expanded as multifile predicate.
- update_state(+Term, +Expanded, +Module) is det[private]
- Update operators and style-check options from the expanded term.
- import_syntax(+Path, +Module, +Imports, +ExportStatement) is det[private]
- Import syntax affecting aspects of a declaration. Deals with
op/3 terms and Syntax/4 quasi quotation declarations.
- load_quasi_quotation_syntax(:Path, +Syntax) is semidet
- Import quasi quotation syntax Syntax from Path into the module
specified by the first argument. Quasi quotation syntax is
- To be done
- - We need a better way to know that an import affects the
syntax or compilation process. This is also needed for
better compatibility with systems that provide a
- module_decl(+FileSpec, -Path, -Decl) is semidet[private]
- If FileSpec refers to a Prolog module file, unify Path with the
canonical file path to the file and Decl with the second argument of
the module declaration.
- read_source_term_at_location(+Stream, -Term, +Options) is semidet
- Try to read a Prolog term form an arbitrary location inside a
file. Due to Prolog's dynamic syntax, e.g., due to operator
declarations that may change anywhere inside the file, this is
theoreticaly impossible. Therefore, this predicate is
fundamentally heuristic and may fail. This predicate is used
by e.g., clause_info/4 and by PceEmacs to colour the current
This predicate has two ways to find the right syntax. If the
file is loaded, it can be passed the module using the module
option. This deals with module files that define the used
operators globally for the file. Second, there is a hook
prolog:alternate_syntax/4 that can be used to temporary redefine
The options below are processed in addition to the options of
read_term/3. Note that the
offset options are
- If present, start reading at line Line.
- Use seek/4 to go to the indicated location. See seek/4
for limitations of seeking in text-files.
- Use syntax from the given module. Default is the current
- List of additional operator declarations to enforce while
reading the term.
- If no correct parse can be found, unify Error with a term
Offset:Message that indicates the (character) location of
the error and the related message. Adding this option
makes read_source_term_at_location/3 deterministic (
- See also
- - Use read_source_term/4 to read a file from the start.
- - prolog:alternate_syntax/4 for locally scoped operators.
- alternate_syntax(?Syntax, +Module, -Setup, -Restore) is nondet[private]
- Define an alternative syntax to try reading a term at an
arbitrary location in module Module.
Calls the hook prolog:alternate_syntax/4 with the same signature
to allow for user-defined extensions.
|Setup||- is a deterministic goal to enable this syntax in
|Restore||- is a deterministic goal to revert the actions of
- seek_to_start(+Stream, +Options) is det[private]
- Go to the location from where to start reading.
- seek_to_line(+Stream, +Line)[private]
- Seek to indicated line-number.
- qq_read_term(+Stream, -Term, +Options)[private]
- Same as read_term/3, but dynamically loads known quasi
quotations. Quasi quotations that can be autoloaded must be
defined using prolog:quasi_quotation_syntax/2.
- prolog:quasi_quotation_syntax(+Syntax, -Library) is semidet[multifile]
- True when the quasi quotation syntax Syntax can be loaded from
Library. Library must be a valid first argument for
This multifile hook is used by library(prolog_source) to load
quasi quotation handlers on demand.
- prolog_open_source(+CanonicalId:atomic, -Stream:stream) is det
- Open source with given canonical id (see
prolog_canonical_source/2) and remove the #! line if any.
Streams opened using this predicate must be closed using
prolog_close_source/1. Typically using the skeleton below. Using
this skeleton, operator and style-check options are
automatically restored to the values before opening the source.
- prolog:xref_open_source(+SourceID, -Stream)[multifile]
- Hook to open an xref SourceID. This is used for
cross-referencing non-files, such as XPCE buffers, files from
archives, git repositories, etc. When successful, the
corresponding prolog:xref_close_source/2 hook is called for
closing the source.
- prolog_close_source(+In:stream) is det
- Close a stream opened using prolog_open_source/2. Restores
operator and style options. If the stream has not been read to
the end, we call
expand_term(end_of_file, _) to allow expansion
modules to clean-up.
- prolog:xref_close_source(+SourceID, +Stream) is semidet[multifile]
- Called by prolog_close_source/1 to close a source previously
opened by the hook prolog:xref_open_source/2. If the hook fails
close/2 using the option
force(true) is used.
- prolog_canonical_source(+SourceSpec:ground, -Id:atomic) is semidet
- Given a user-specification of a source, generate a unique and
indexable identifier for it. For files we use the
prolog_canonical absolute filename. Id must be valid input for
- file_name_on_path(+File:atom, -OnPath) is det
- True if OnPath a description of File based on the file search
path. This performs the inverse of absolute_file_name/3.
- file_alias_path(-Alias, ?Dir) is nondet
- True if file Alias points to Dir. Multiple solutions are
generated with the longest directory first.
- path_segments_atom(+Segments, -Atom) is det
- path_segments_atom(-Segments, +Atom) is det
- Translate between a path represented as a/b/c and an atom
representing the same path. For example:
?- path_segments_atom(a/b/c, X).
X = 'a/b/c'.
?- path_segments_atom(S, 'a/b/c'), display(S).
S = a/b/c.
This predicate is part of the Prolog source library because
SWI-Prolog allows writing paths as /-nested terms and
source-code analysis programs often need this.
- directory_source_files(+Dir, -Files, +Options) is det
- True when Files is a sorted list of Prolog source files in Dir.
false), recurse into subdirectories
loaded), only report loaded files.
Other options are passed to absolute_file_name/3, unless
loaded(true) is passed.