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).
- 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
- It is already loaded
- It is declared with prolog:quasi_quotation_syntax/2
- 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 syntax.
The options below are processed in addition to the options of read_term/3. Note that the
offsetoptions are mutually exclusive.
- 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 `source module'.
- 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 (
- 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.
- 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.
process_source(Src) :- prolog_open_source(Src, In), call_cleanup(process(Src), prolog_close_source(In)).
- 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
- 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 prolog_open_source/2.
- 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). /(/(a,b),c) 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
- valid_term_position(@Term, @TermPos) is semidet
- Check that a Term has an appropriate TermPos layout. An incorrect
TermPos results in either failure of this predicate or an error.
If a position in TermPos is a variable, the validation of the corresponding part of Term succeeds. This matches the term_expansion/4 treats "unknown" layout information. If part of a TermPos is given, then all its "from" and "to" information must be specified; for example,
string_position(X,Y)is an error but
string_position(0,5)succeeds. The position values are checked for being plausible -- e.g.,
This should always succeed:
read_term(Term, [subterm_positions(TermPos)]), valid_term_position(Term, TermPos)
- term_position_list_tail(@List, -HdPart, -Tail) is det[private]
- Similar to
append(HdPart, [Tail], List)for proper lists, but also works for inproper lists, in which case it unifies Tail with the tail of the partial list. HdPart is always a proper list:
?- prolog_source:term_position_list_tail([a,b,c], Hd, Tl). Hd = [a, b, c], Tl = . ?- prolog_source:term_position_list_tail([a,b|X], Hd, Tl). X = Tl, Hd = [a, b].