SDA SE Wiki

Software Engineering for Smart Data Analytics & Smart Data Analytics for Software Engineering

User Tools

Site Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
research:pdt:docs:editor [2015/01/13 14:36]
127.0.0.1 external edit
research:pdt:docs:editor [2018/05/09 01:59] (current)
Line 1: Line 1:
 +~~NOTOC~~
  
 +====== The Prolog Editor ======
 +
 +{{page>​editor_navigation&​nofooter}}
 +
 +==== Syntax Highlighting ​ ====
 +
 +Depending on their properties, predicates, quoted atoms and comments are highlighted ​
 +with a specific colours. These colours can be modified in the [[configuration|preferences]].
 +
 +^ Highlighting ​ ^ Indicated Property ^
 +| {{editor_predicate_dynamic.png|}} | Dynamic predicate |
 +| {{editor_predicate_builtin.png|}} | Built-in predicate |
 +| {{editor_predicate_metapredicate.png|}} | Meta predicate |
 +| {{editor_predicate_transparent.png|}} | [[http://​www.swi-prolog.org/​pldoc/​man?​section=ctxmodule|Module transparent predicate]] |
 +| {{editor_predicate_normal.png|}} | ++ Normal | (having none of the properties mentioned above) ++ predicate |
 +| {{editor_predicate_atom.png|}} | Quoted atom |
 +| {{editor_comment.png}}| Comment ​ |
 +
 +==== Name Highlighting ​ ====
 +Occurences of atom and variable names are highlighted in the ++current clause| (that is the clause in which the cursor is currently located)++.
 +The highlighting is updated instantly, upon typing. ​
 +
 +^ Highlighting in the editor ^ Description ^
 +| {{editor_highlight_occurences_vars.png|}} | All occurences of the ++variable touched by the cursor| (that means, the cursor is located just before, just after or
 +within the variable name)++ are highlighted with a grey background. |
 +| {{editor_highlight_occurences_atom.png|}} | All occurences of the ++atom touched by the cursor| (that means, the cursor is located just before, just after or
 +within the atom name)++ are highlighted with a grey background. |
 +| {{editor_highlight_singleton.png|}} | Singleton variables are highlighted with a red background. |
 +| {{editor_highlight_nonsingleton.png|}} | Variables that start with "​_"​ but occur multiply in the  ++current clause| (that is the clause in which the cursor is currently located)++ are highlighted with a light ivory background. |
 +
 +==== Warnings and Errors ====
 + 
 +All SWI-Prolog errors and warnings that occur while consulting a file are displayed in the Prolog Editor:
 +    * **Warnings** are highlighted by a yellow underline and {{warning.gif|warning}} markers in the sidebars of the editor.
 +    * **Syntax errors** are highlighted by a red underline and {{error.gif|error}} markers in the sidebars of the editor.
 +
 +These errors and warnings are also displayed in the Eclipse Package Explorer and Eclipse Problems View:
 +
 +^   ^ Prolog Editor ​ ^   ​Package Explorer ​  ​^ ​ Problems View  ^
 +^  Warnings|{{warning_editor.png|}}|{{warning_packageexplorer.png|}}|{{warning_problemsview.png|}}|
 +^  Errors |{{error_editor.png|}}|{{error_packageexplorer.png|}}|{{error_problemsview.png|}}|
 +
 +==== Saving and consulting files ====
 +The file which is opened in the editor can be consulted to the current process by pressing **F9**.
 +
 +Whenever you save a file in the editor it is automatically (re)consulted. If you don't want a file to be consulted after saving you can save the file by pressing **Ctrl+Alt+S** or by selecting the menu item "Save without consult"​. ((Note that the file icon in the [[navigator]] will become yellow to illustrate that an older version of the file is consulted))
 +
 +Furthermore you have the possibility to deactivate the reconsult on save in the [[configuration|Preferences]]. This means, that files will only be consulted manually.
 +
 +==== Outline ====
 +
 +{{ outline.png|}}
 +
 +The Outline view displays an outline of all predicates defined in the Prolog file opened in the editor.
 +The Outline supports **multi-file awareness**,​ that is, it shows //all// the clauses of a predicate, also 
 +for multifile predicates:
 +  * **First level**: Modules.
 +  * **Second level**: Predicate indicators of predicates defined in this file and  ​
 +    total number of clauses of each predicate (in this and in other files).
 +    Dynamic predicates are emphasized with blue text colour. ​
 +    The icon to the left of the predicate indicator represents the visibility of the predicate: ​
 +    A green icon indicates exported predicates and predicates in non-module files. ​
 +    A yellow icon indicates non-exported predicates of a module.
 +  * **Third level**: ​
 +    * Top: Clauses of the predicate defined in the local file (each clause with its first line number and 
 +      its first argument. If the argument is a function term it is presented as Functor/​Arity.
 +    * Rest: Other files that contain multifile contributions to the predicate.
 +  * **Fourth level**: Clauses in each file listed at the third level (= multifile contributions from other files).
 +     Each clause is displayed with its first line number and its first argument.
 +     If the argument is a function term it is presented as Functor/​Arity.
 +
 +
 +In the outline, multifile predicates are shown either as "​for"​ or "​from"​ contributions:​
 +
 +  * **For**: If the ++local file| (= the file for which the outline is displayed)++ ​
 +    contains predicates for ++remote modules| (= modules different from the one defined in the local file, i.e. modules defined explicitly in another file or a  modules defined just implicitly by mutlifile contributions in different files)++
 +    the remote modules are displayed in the outline with a black arrow overlay on the module icon. 
 +    Below each remote module icon, its ++local predicates| (= predicates for which the local file contains clauses)++
 +    are displayed with all their clauses: The ++local clauses| (= clauses in the local file)++ at the top, 
 +    followed by the other files that contribute clauses (at the third level) ​
 +    and the contributed contributed clauses (at the fourth level). ​
 +  * **From**: If local predicates from other files are listed below a 
 +    file icon. The local clauses are displayed immediately below the predicate ​
 +    icon, no matter whether they are for the local module or another module.
 +
 +A single click on the icon of a **local** predicate or clause selects the first line of that predicate / clause in the 
 +associated editor. ​
 +A single click on the icon of ++remote clause| (= a clause from another file)++ has no effect. ​
 +Double clicking a remote clause shows its first line **in another editor**. ​
 +Single click is equivalent to navigating via the arrow keys, double ​
 +click is equivalent to hitting <​Return>​.
 +
 +The order of modules in the outline is 
 +  - local module first
 +  - then ++remote modules| (= modules different from the one defined in the local file, i.e. modules defined explicitly in another file or a  modules defined just implicitly by mutlifile contributions in different files)++ ​ in alphabetic order
 +
 +Within each module'​s section, predicates are displayed by default according to the textual order in the local file.
 +However, the predicates can also be sorted alphabetically using the corresponding icon in the 
 +outline'​s tool bar. The order of modules cannot be changed. ​
 +
 +==== Quick Outline ====
 +
 +{{ quickoutline.png|}}
 +In the Prolog Editor a quick outline is available via **Ctrl+O** or via the context menu. 
 +
 +When nothing is typed into the input field, the quick outline shows the same content as the 
 +outline view. Typing retains only the predicates whose name contains the typed string. ​
 +Hitting **Return** when there is just one choice left jumps to that predicate. ​
 +  ​
 +
 +
 +
 +
 +==== Code Completion ====
 +
 +The Prolog Editor supports code completion dependent on the current file and the loaded code in the currently selected Prolog process. Code completion in the Prolog editor uses the default Eclipse key binding (**<​Ctrl><​Space>​**). The following elements are shown in the completion:
 +
 +  * **Predicates** ({{public_co.gif}},​ {{protected_co.gif}},​ {{private_co.gif}},​ {{variable.gif}}):​ All matching predicates that are visible in the module of the current file.
 +    * If the prefix is qualified with a module, all matching predicates visible in the qualifying module are listed.
 +    * If a documentation of a predicate is availabe, it is shown in the right window.
 +    * The icon shows the visibility of the predicate.
 +    * The text inserted as completion depends on the key mask when accepting a proposal:
 +      * **No key mask**: A predicate head is inserted. It is possible to navigate through the arguments with **<​TAB>​**. If a documentation is available, the argument names defined in the documentation will be used as variables for the inserted head.
 +      * **CTRL**: A predicate indicator (//​Functor//​ / //Arity//) is inserted.
 +  * **Modules** ({{:​package_obj.gif}}):​ all matching modules.
 +  * **atoms** ({{atom.png}}):​ all matching atoms currently known in the prolog system.
 +  * **logtalk templates** ({{template_obj.gif}}):​ all matching logtalk templates for entities, directives, etc. only available in logtalk files.
 +
 +the following table shows some examples for the completion (click on the images to enlarge).
 +^  predicates and atoms  ^  modules and atoms  ^   ​logtalk templates ​ ^|  {{autocompletion.png?​200|Code completion in the Prolog Editor}} ​ |  {{autocompletion2.png?​200|Code completion in the Prolog Editor}} ​ |  {{autocompletion3.png?​200|Code completion in the Prolog Editor}} ​ |
 +
 +
 +
 +
 +==== Open Primary Declaration ====
 +
 +|  {{primary.png|}} ​ |  {{:​research:​pdt:​docs:​primary_result.png|}} ​ |  {{:​research:​pdt:​docs:​primary_alternatives.png|}} ​ |\\
 +|  Select a predicate call and run **Open Primary Definition or Declaration** ​ |  The cursor goes to line 17  |  Suggested alternatives if a non-existing or locally invisible predicate is searched|\\
 +**Open Primary Definition or Declaration** offers the possibility to easily jump to the first 
 +clause of a selected predicate, similar to the "Open Declaration"​ command in the Java 
 +editor. ​
 +In the example above the declaration is contained in the same file and therefore the 
 +cursor will jump to line 17. If the declaration of the predicate is contained in 
 +another file, the other file will be opened in new editor.
 +  * In case of multifile predicates the first clause which is found 
 +    will be opened in the editor. Additionally the //[[#find definitions and declarations]]// ​
 +    search will be started to display all clauses.
 +  * If the selected predicate exists but there is no source for it, a message will be displayed.
 +  * If the selected predicate does not exist or is not visible locally, the editor will offer a 
 +    list of similar predicates or show a warning if there are no similar predicates.
 +
 +
 +==== Find Definitions and Declarations ====
 +
 +|{{finddeclarations.png|}} | {{finddeclarations_result.png|}}|\\
 +[[search|Search]] for all //​declarations and definitions//​ of the currently selected //​predicate//​ in the editor. This search is done using the currently selected prolog process in the [[console|Prolog Console]]. The resulting modules get a visibility depending on the context of the selected goal. Possible values for visibility are //local//, //super//, //sub// and //​invisible//​.
 +
 +==== Find References ====
 +
 +|{{findreferences.png|}} | {{findreferences_result.png|}}|\\
 +[[search|Search]] for all //​references//​ to the currently selected //​predicate//​ in the editor. This search is done using the currently selected prolog process in the [[console|Prolog Console]]. Each result represents one clause that contains a call to the selected predicate. ​
 +
 +==== Breakpoints ====
 +
 +SWI Prolog offers the possibility of setting breakpoints in the prolog code. These breakpoints are visible in the [[gui_tracer|SWI GUI Tracer]] and they can be set and removed within the GUI Tracer.\\
 +The PDT Prolog Editor also displays these breakpoints. These breakpoints are those from the currently selected prolog process in the [[console|Prolog Console]]. In the PDT Prolog Editor, one line in the editor can only have one breakpoint. It is possible to set and remove breakpoints directly from the editor. This can be done by double-clicking at the required location on the bar at the left edge of the editor or by using the context menu at the same location (see the screenshots below).\\
 +Setting a breakpoint in the editor means setting the breakpoint in the currently selected prolog process in the [[console|Prolog Console]]. Therefore the file in the editor must be consulted in this prolog process, otherwise setting of breakpoints is not possible. \\
 +| {{breakpoint_swi.png|}} | {{breakpoint_editor.png|}} | {{breakpoint_editor_contextmenu.png|}} |\\
 +| Breakpoint in the SWI GUI Tracer | The same breakpoint in the PDT Prolog Editor | Context menu of the bar at the left edge of the editor |\\
 +
 +==== External files ====
 +
 +Files which are not contained in any project in the workspace are called **external files**. For example the prolog code of SWI Prolog is usually not contained in any project in the workspace. To emphasize that a file in the Prolog Editor is an external file the editor uses a different icon in the editor title bar and the background colour of the editor is different (light gray).
 +
 +{{editor_external.png|}}
 +
 +==== Open a file with edit/1 ====
 +
 +{{ editor_open_via_edit.png|}}
 +The SWI-Prolog predicate [[http://​www.swi-prolog.org/​pldoc/​doc_for?​object=edit/​1|edit/​1]] ​
 +can be used in the [[console|Prolog Console]] to open a [[editor|Prolog editor]] for any
 +currently loaded predicate that has attached source code. This applies also
 +to predicates residing in [[:​research:​pdt:​docs:​navigator#​external files]]. ​
 + 
 +E. g. the query "?- edit(member)."​ will open the library file "​lists.pl"​ and 
 +position the cursor in the first clause of member/2 (see screenshots).
 +
 +<​note> ​
 +Even system files, that is, libraries that are part of the PDT or your Prolog system
 +can be edited this way. However, this is something for experts.
 +You should be very sure you know what you are doing. ​
 +
 +Even then, please be aware that the default behaviour of saving ​
 +an edited file includes reconsulting the file. So it is very easy 
 +to break a running system if you edit a system file and save it
 +before editing another file that would need a consistent change. ​
 +
 +If you want to perform a set of related changes in different ​
 +system files use <​Ctrl>​ <Alt> S for saving, disabling the 
 +auto-consult for that particular action. You can also change
 +the default behaviour of <​Ctrl>​ S in the PDT preferences. ​
 +</​note>​
research/pdt/docs/editor.txt · Last modified: 2018/05/09 01:59 (external edit)

SEWiki, © 2019