Home Contents Index Summary Previous Next

3.3 Listing and Editor Interface

SWI-Prolog offers an extensible interface which allows the user to edit objects of the program: predicates, modules, files, etc. The editor interface is implemented by edit/1 and consists of three parts: locating, selecting and starting the editor.

Any of these parts may be extended or redefined by adding clauses to various multi-file (see multifile/1) predicates defined in the module prolog_edit.

The built-in edit specifications for edit/1 (see prolog_edit:locate/3) are described below.

Fully specified objects
<Module>:<Name>/<Arity> Refers a predicate
module(<Module>)Refers to a module
file(<Path>)Refers to a file
source_file(<Path>)Refers to a loaded source-file
Ambiguous specifications
<Name>/<Arity> Refers this predicate in any module
<Name> Refers to (1) named predicate in any module with any arity, (2) a (source) file or (3) a module.

edit(+Specification)
First exploits prolog_edit:locate/3 to translate Specification into a list of Locations. If there is more than one `hit', the user is allows to select from the found locations. Finally, prolog_edit:edit_source/1 is used to invoke the user's preferred editor.

prolog_edit:locate(+Spec, -FullSpec, -Location)
Where Spec is the specification provided through edit/1. This multifile predicate is used to enumerate locations at with an object satisfying the given Spec can be found. FullSpec is unified with the complete specification for the object. This distinction is used to allow for ambiguous specifications. For example, if Spec is an atom, which appears as the base-name of a loaded file and as the name of a predicate, FullSpec will be bound to file(Path) or Name/Arity.

Location is a list of attributes of the location. Normally, this list will contain the term file(File) and ---if available--- the term line(Line).

prolog_edit:locate(+Spec, -Location)
Same as prolog_edit:locate/3, but only deals with fully-sepecified objects.

prolog_edit:edit_source(+Location)
Start editor on Location. See locate/3 for the format of a location term. This multi-file predicate is normally not defined. If it succeeds, edit/1 assumes the editor is started.

If it fails, edit/1 will invoke an external editor. The editor to be invoked is determined from the evironment variable EDITOR, which may be set from the operating system or from the Prolog initialisation file using setenv/2. If no editor is defined, vi is the default in Unix systems, and notepad on Windows.

The predicate prolog_edit:edit_command/2 defines how the editor will be invoked.

prolog_edit:edit_command(+Editor, -Command)
Determines how Editor is to be invoked using shell/1. Editor is the determined editor (see edit_source/1), without the full path specification, and without possible (exe) extension. Command is an atom describing the command. The pattern %f is replaced by the full file-name of the location, and %d by the line number. If the editor can deal with starting at a specified line, two clauses should be provided, one holding only the %f pattern, and one holding both patterns.

The default contains definitions for vi, emacs, emacsclient, vim and notepad (latter without line-number version).

Please contribute your specifications to jan@swi.psy.uva.nl.

prolog_edit:load
Normally not-defined multifile predicate. This predicate may be defined to provide loading hooks for user-extensions to the edit module. For example, XPCE provides the code below to load library(swi_edit), containing definitions to locate classes and methods as well as to bind this package to the PceEmacs built-in editor. 


:- multifile prolog_edit:load/0.

prolog_edit:load :-
        ensure_loaded(library(swi_edit)).

listing(+Pred)
List specified predicates (when an atom is given all predicates with this name will be listed). The listing is produced on the basis of the internal representation, thus loosing user's layout and variable name information. See also portray_clause/1.

listing
List all predicates of the database using listing/1.

portray_clause(+Clause)
Pretty print a clause as good as we can. A clause should be specified as a term `<Head> :- <Body>' (put brackets around it to avoid operator precedence problems). Facts are represented as `<Head> :- true'.