prolog_source.pl -- Examine Prolog source-files

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:

prolog_xref.pl: The Prolog cross-referencer
prolog_clause.pl: Get details about (compiled) clauses
prolog_colour.pl: Colourise source-code
PceEmacs: Emacs syntax-colouring
PlDoc: 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).

Arguments:

`Term`	- `Term` read
`Expanded`	- Result of term-expansion on the term

See also

- read_source_term_at_location/3 for reading at an arbitrary location.

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 imported iff:

It is already loaded
It is declared with prolog:quasi_quotation_syntax/2

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 separate compiler.

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 clause.

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 line and offset options are mutually exclusive.

line(+Line): If present, start reading at line Line.
offset(+Characters): Use seek/4 to go to the indicated location. See seek/4 for limitations of seeking in text-files.
module(+Module): Use syntax from the given module. Default is the current `source module'.
operators(+List): List of additional operator declarations to enforce while reading the term.
error(-Error): 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 (det).

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.

Arguments:

`Setup`	- is a deterministic goal to enable this syntax in module.
`Restore`	- is a deterministic goal to revert the actions of `Setup`.

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 use_module/2.

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 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 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. Options:

recursive(boolean): If true (default false), recurse into subdirectories
if(Condition): If true (default loaded), only report loaded files.

Other options are passed to absolute_file_name/3, unless loaded(true) is passed.

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., string_position(5,0) will fail.

This should always succeed:

read_term(Term, [subterm_positions(TermPos)]),
valid_term_position(Term, TermPos)

Arguments:

`Term`	- Any Prolog term including a variable).
`TermPos`	- The detailed layout of the term, for example from using `read_term(Term, subterm_positions(TermPos)`.

Errors

- existence_error(matching_rule, Subterm) if a subterm of Term is inconsistent with the corresponding part of TermPos.

- expand_term/4, term_expansion/4, expand_goal/4, expand_term/4

- clause_info/4, clause_info/5

- unify_clause_hook/5

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].