Original Amzi! Windows IDE

The original Amzi! Windows IDE (WIDE) is a relatively simple IDE ideal for introductory and student use in learning Prolog. It is included in the Amzi! distribution as an alternative to the full-featured Eclipse IDE which, while being much more powerful, takes a bit longer to learn.


Quick Tutorial

This section is a tutorial introduction to the Amzi! Prolog development tools. It is not intended to be an introduction to Prolog. If you need an introduction to the Prolog language we recommend Adventure in Prolog.

The tutorial makes use of a simple adventure game, Duck World, to illustrate how to use the Amzi! tools to build complex applications. Accordingly, it is composed of a number of files.

(Why Duck World? Because Amzi! inc. is located in an old farm house backed up on conservation land. We bought ducks out of whimsy one day, which were later discovered by the fox in the woods. The ducks have proved to be an adventure.)

The tutorial demonstrates both the command-line (alis) and Windows-IDE interfaces to Amzi! Prolog.

This tutorial starts by testing some of the basic predicates of Duck World in the listener. It then goes through the full example, showing how the program is modularized, how it is compiled and run using the listener, and how it is linked into a distributable application.

The source code for Duck World can be found in the samples/prolog/ducks sub-directory.

Duck World

An adventure game is a simulation of an environment, real or imagined, that the user explores, usually with some goal in mind. Duck World is a simple adventure game, where the objective is to go from the house, through the yard, to the duck pen to get an egg, and back to the house again, without losing any ducks to the fox.

The commands for manipulating the environment are all entered as legal Prolog goals (ending in periods).

They are:

  • goto(X) - moves you to place X, where X can be either house, yard or pen.
  • take(X) - takes something if it's where you are; the egg is the only thing you're supposed to take.
  • chase(ducks) - how to get the ducks back in their pen.
  • quit - this, or any illegal command, will quit the game for you.
  • When you have brought the egg into the house the game ends.

    Starting the Listener

    Amzi! Prolog can be run using one of two different methods:

    To start the listener from the operating system command-line, type the input shown in the left box. To do this within the IDE, select the menu items shown in the right box. General instructions are given in italics.

    Command-Line alis Windows-IDE
    c>  alis
    Double-Click on Icon for the
    Amzi! Prolog IDE
    Listener / Start

    The copyright message will be displayed followed by the prompt, ?-

    Amzi! Prolog <version information>
    Amzi! Prolog Listener
    Copyright (c)1987-97 Amzi! inc. All Rights Reserved.
    Type  'quit.'  to exit
    ?-

    You are now in a Prolog listener, which is awaiting your command. Try out this classic, being careful to remember the single quotes and the ending period.

    ?- write('Hello World').
    Hello World

    Note: The listener does NOT have a full line editor at the ?- prompt, although it appears to behave that way in the IDE. You can type in characters and backspace to fix mistakes. You cannot use the mouse or cursor keys to edit a query. You can cut and paste from one line to the prompt, but you can only edit that line using the backspace key.

    (To exit, you would type "quit." or select Listener / End from the IDE menu.)

    Creating a Source File

    Before looking at the Duck World source code, create a small experimental file called DW.PRO.

    Command-Line alis Windows-IDE
    Use an editor to type in your code
    Save your file as dw.pro 
    File / New
    Type your code into the window
    File / Save As dw.pro 

    Type the following lines of Prolog code into DW.PRO:

    % Experiments
    nextto(house, yard).
    nextto(yard, pen).
    
    loc(you, house).
    
    move(Place) :-
      retract( loc(you, _) ),
      assert( loc(you, Place) ).

    Note, it is important to keep the clauses defining a predicate together, as the clauses of the predicate nextto/2 are. If the definitions are scattered, the program will seem to work properly when interpreted, but behave in an unexpected manner when compiled.

    Consulting a Source File

    To play with DW.PRO, consult it into the listener as shown:

    Command-Line alis Windows-IDE
    ?- consult(dw).
    yes
    Listener / Consult
    dw.pro

    You are now in the listener with DW.PRO consulted.

    Using the Listener

    Now that you've reached the listener, make sure your file was consulted by using listing.

    ?- listing.

    This will show you the predicates of dw.pro, although they will look a little different because the variables are renamed with an _ and a number, e.g. _0.

    You can try various queries from the listener.

    ?- loc(you, X).
    X = house

    You can test move.

    ?- move(yard), loc(you, X).
    X = yard
    ?- move(foobar), loc(you, X).
    X = foobar

    Because move doesn't check to see if the move makes sense, you might decide to add a goto predicate with more intelligence. You can enter it directly in the listener using add.

    ?- add.
    |  goto(P) :-
    loc(you, X),
    nextto(X, P),
    move(P).
    |  quit.
    ?-

    This is a useful technique for quick experiments, but the code typed in the listener is not entered into your source file. Because we want goto to be part of the game it is best to type it directly into the source file and then reconsult it.

    This can be done by moving from the listener to the editor. You can use the built-in IDE editor, or, under DOS, invoke the editor of your choice. In the IDE, simply selecting Listener/Reconsult will reconsult the last file (or project) consulted. The last file consulted is also remembered between sessions, so you begin a new IDE session by simply selecting Reconsult.

    (You need to reconsult, rather than consult, because consulting would will simply add a second copy of your program to the Prolog workspace. Listing would show two of every predicate.)

    Command-Line alis Windows-IDE
    Edit dw.pro in an editor
    then in the listener:
    ?- reconsult(dw).
    yes
    Edit dw.pro in its window
    File / Save
    Listener / Reconsult

    You can then test it.

    ?- goto(yard).
    yes
    ?- goto(pen).
    yes
    ?- goto(yard).
    no

    It didn't work right, which leads to the next section.

    Debugging

    goto lets you get into the pen, but doesn't let you get back out. First, you can use the listener to make sure the game is in the state required for testing. To do this enter the goals to place you in the pen.

    ?- retract(loc(you, _)), assert(loc(you, pen)).
    yes

    The listener gives you the ability to dynamically adjust the state of your application, effectively putting you in the middle of it. This, by itself, is a powerful tool for debugging.

    You can now trace the execution of goto(yard) to see why it is failing. To do this you need to start the debugger. Type:

    Command-Line alis Windows-IDE
    ?- debug.
    Listener / Debug On

    The debugger in alis is line-oriented, and is controlled from the keyboard. In the IDE, a separate debugger window is opened, which is controlled with the mouse. You enter your normal interaction with the program in the listener window.

    Next, type in the goal to be traced at the listener prompt, which is ??- for alis and ?- for the IDE:

    ?- goto(yard).

    To step through the Prolog code type:

    Command-Line alis Windows-IDE
    ? c
    Alternatively
    ? [Enter]
    Click on the "Creep" button

    Note the IDE does not display the ? prompt. (See the Debugger section for other options.)

    Calling: goto(yard)
    CALL:(1) goto(yard)    ? c
       Calling: loc(you,H64)
       CALL: loc(you,pen)    ? c
       EXIT: loc(you,pen)    ? c
       Calling: nextto(pen,yard)
       FAIL: nextto(pen,yard)    ? c
       FAIL: loc(you,pen)    ? c
       FAIL: loc(you,H64)    ? c
    FAIL: goto(yard)    ? c
    FAIL: goto(yard)    ? c
    no

    To leave the debugger

    Command-Line alis Windows-IDE
    ??- quit.
    Listener / Debug Off
    Or, Click on the "Stop"
    button

    The trace reveals that nextto(pen, yard) is different from nextto(yard, pen), so, to get goto/1 to work, a predicate that equates the two is needed. The solution chosen for Duck World is the predicate connect/2, which is used instead of nextto/2 in the goto/1 definition.

    connect(X, Y) :- nextto(X, Y).
    connect(X, Y) :- nextto(Y, X).

    This code can be added to the source file and the development process continues. This is the normal way to develop a Prolog application. Predicates are gradually added to the source file as the application grows. The application can be tested at any point during the development process and individual predicates can be tested and their execution traced to understand why the application is working the way it does.

    Modules

    As an application grows, it is natural to want to break it up into modules. At the simplest this means splitting the predicate definitions among various source files. These files can be consulted together and the application run from the listener.

    However, it is often preferred to keep some of the predicates hidden within a file and to allow only certain predicates to be called from other source files. This is done through two compiler directives (specified by :- in the source code), import and export. These directives specify which predicates will be visible outside of the source file (export), and which predicates the file is calling that it expects to find elsewhere (import).

    Included in the samples are two source files that illustrate this idea. They are:

    Even for compiled applications, there are usually at least a few predicates which remain in the dynamic database. It is often convenient to separate their definition to a separate file that also initializes them by asserting them into the dynamic database when the program starts up.

    In the case of Duck World, the loc/2 predicate is constantly being changed by the application and therefore is kept in the dynamic database. The file DUCKENV.PRO contains the code to initialize the database. Notice that it is consulted when main/0 is called.

    If you want to keep a dynamic predicate's definition in with compiled code, you can use the dynamic directive. It tells the compiler to keep the specified predicate in the dynamic database, rather than comiling it.

    For example, in this code loc/2 will be in the dynamic database while main and goto are compiled. dynamic is ignored for interpreted code.

    Running a Modular Application

    You can run the modularized Duck World from a listener by consulting it and calling main/0, the predicate that starts it running. (You can also call any of the other predicates of Duck World to see if they're working and trace them if they're not.)

    ?- consult([duck1, duck2]).                               
    ?- main.
    Welcome to Duck World
    Go get an egg
    >> goto(yard).
    You are in the yard
    >> .....

    Using alis and BAT Files

    main/0 is a special predicate for Amzi! Prolog because it is the main entry point into your program. When you include files to be consulted on the alis command line, alis first tries to call main/0 before establishing the listener environment. This means that alis can be used to launch your application without the need for compiled or linked code. Further, when alis finds a main/0 to call, it exits back to the operating system when it's finished, rather than staying in the listener.

    c>  alis duck1 duck2
    Welcome to Duck World
    Go get an egg
    >> quit.
    Quitter
    c>

    By creating a batch file, ducks.bat with the line "alis duck1 duck2", you can run Duck World by simply typing "ducks" at the operating system prompt.

    If you have a large number of files in your application, you can create a file like DUCKS.PRO that consults each of the files. Then only this one file need be specified on the alis command line.

    Using Projects

    You can create a project file (.ppj) by selecting Build / Project New from the IDE menu. Enter the name of your project, e.g. ducks.ppj. Next you will be presented with a dialog box which you can use to add files to your project. Double-click on duck1.pro and duck2.pro. Their names will appear in the window on the bottom. Click on "OK."

    Now instead of using Listener / Consult to individually consult each file, you can simply consult the project, which, in turn, consults each file in the project.

    Compiling

    Compiling Duck World is easily done:

    Command-Line alis Windows-IDE
    c>  acmp duck1
    c>  acmp duck2
    Build / Compile
    ducks.ppj

    Note, under the IDE we simply compile the project. This causes all the modified source files in the project to be recompiled.

    acmp can also be invoked with no arguments, in which case it will prompt you for the names of the files. See the Compiler section for more details.

    The result of compiling is a Prolog object file, in this case, duck1.plm and duck2.plm.

    Running

    The .plm files can be run from either alis or the IDE just as the .pro Files were. The only difference is they go faster and the debugger cannot trace them. If you wanted, you could run Duck World consulting the .pro file for one and loading the .plm file for the other. This way you could use trace on the predicates in the .pro file (duck2 in this example).

    ?- load(duck1), consult(duck2), main.

    This can also be accomplished in the IDE by setting up your project to include duck1.plm and DUCK2.PRO. When consulting projects (using Listener / Consult), .plm files are loaded and .pro files are consulted.

    With alis, the .plm files can be loaded from the command line, just as the .pro files were. This can be either directly

    c>  alis duck1.plm duck2.plm

    or by using an intermediate file to load the component files.

    c>  alis ducks

    Linking and Running

    To build a stand-alone application first create a Prolog load module (.xpl file) with the Amzi! Prolog linker, alnk.

    Command-Line alis Windows-IDE
    c>  alnk ducks duck1 duck2
    Build / Link
    ducks.ppj

    Note, under the IDE we just link the project to create an .xpl file with the same name as the project.

    Using alnk, the first argument is the name of the .xpl file. The next two files are the .plm files that are linked together.

    The .plm files (in this case duck1.plm and duck2.plm) are linked with alib.plm, the Prolog portion of the Amzi! engine, to form an application. (Hence, alib.plm must be somewhere in the PATH or AMZI_DIR.)

    Alnk can also be invoked with no arguments, in which case it will prompt you for inputs. See the Linker section for more details.

    To run Duck World, just type:

    Command-Line alis Windows-IDE
    c> arun ducks
    Build / Run
    ducks.xpl                    

    Distributing an Application

    If you decided to distribute Duck World, then to do so, you need these files for command-line environments:

    For Windowing environments, arun.exe would be replaced by your own C/C++, Visual Basic or other language program.

    Interfacing with Other Tools

    You can enhance the Prolog engine with your own built-in predicates written in C/C++, Delphi or Java.

    For example, you might want to use a graphical interface for Duck World with quacking ducks and the like. In this case the Logic Server API allows you to either extend the Prolog language with graphics predicates written in C/C++ that are called directly by the Prolog code, or to write the user interface to the code in C/C++ (or Visual Basic under Windows) and call embedded Prolog for the logic. You can combine the techniques, both extending and embedding Prolog in the same application.

    The section on the Logic Server API tells how integrate Prolog with other languages.


    Windows IDE Interface

    The IDE is a Windows application which provides a friendly GUI interface to the Prolog system. From within the IDE you can:

    Interface

    The Windows IDE has two version, one uses just ASCII for source code and the other 32-bit Unicode or ASCII. These are: amzi/apls/bin/wideA.exe or wideW.exe. After the IDE has been invoked you are presented with a screen divided into four main areas:

    Each open Prolog source file is displayed in its own window. Windows can be moved, resized and reduced to an icon. If there is a project currently open, then it also appears in a window.

    The listener is also in its own window. The current release allows only one listener window to be active at one time. The debugger runs in a separate window, but it can only be turned on when the listener is active.

    The listener/debugger sessions can be logged to a file, saved or printed for later review.

    Using menu commands, source files can be compiled into object (.plm) files. Both source and object files can be consulted into the listener. Also using menu commands, you can link multiple .plm files into a load module, which can also be run in a window.

    Unicode and ASCII

    The wideW editor in the IDE will accept either Unicode or ASCII files, and save a file in the same format it was originally read in. New files can be saved as either ASCII or Unicode.

    To view Unicode characters it is necessary to set the IDE font to a Unicode font. Lucida Console has a large number of Unicode characters.

    File Menu

    New File
    Opens a new, blank edit window.
    New Project
    Creates a new project and displays the project dialog box.
    Open File
    Opens an existing Prolog source file (.pro).
    Open Project
    Opens an existing project.
    Close
    Closes the current edit window.
    Close All
    Closes all open edit windows.
    Save
    Saves the source file or project associated with the current window.
    Save As
    Saves the source file or project associated with the current window in a new file.
    Save All
    Saves all open source files and the current project (if one is open).
    Unlock
    Prompts for information required to activate the software.
    Print
    Prints the contents of the current edit, listener or debugger window.
    Print Preview
    Displays how the contents of the current window will appear when printed.
    Print Setup
    Select a printer and set parameters for printing.
    Recent File List
    A list of the Prolog source files most recently opened.
    Recent Project List
    A list of the projects most recently opened.
    Exit
    Exits the IDE.

    Edit Menu

    Undo
    Reverses the last editing change made.
    Cut
    Deletes the currently highlighted text and saves it on the clipboard.
    Copy
    Makes a copy of the currently highlighted text on the clipboard.
    Paste
    Inserts the contents of the clipboard at the cursor.
    Delete
    Deletes the currently highlighted text.
    Select All
    Selects (highlights) all the text.
    Find
    Finds the first occurance of a string in the current window.
    Find Next
    Finds the next occurance of a string in the current window.
    Replace
    Finds and replaces text in the current window.

    View Menu

    Tool Bar
    Toggles the display of the tool bar at the top of the main IDE window.
    Status Bar
    Toggles the display of the status bar at the bottom of the main IDE window.
    Set Font
    Sets the font name and size to be used for edit, listener and debugger window text.

    Listener Menu

    Start
    Opens the listener into a window and emits the ?- prompt.
    End
    Closes the listener.
    Consult
    Consults a Prolog source file (.pro) or loads a Prolog object file (.plm) into the listener.
    Reconsult
    Consults a Prolog source file into the listener, replacing any current definitions for the predicates.
    Debug On
    Opens the debugger into a window.
    Debug Off
    Closes the debugger.

    Build Menu

    Compile
    Compiles a Prolog source file (.pro).
    Link
    Links one or more Prolog object files (.plm) into a Prolog load module (.xpl).
    Build
    Compiles all modified files and links all files and libraries in a project into a Prolog load module.
    Run
    Loads a Prolog load module and calls the main/0 predicate in a new window.

    Window Menu

    Cascade
    Rearrange all open windows (including the listener, debugger and current project, if any) in a cascading fashion from the upper left to the lower right.
    Tile Horizontally
    Arranges the windows in a horizontal fashion.
    Tile Vertically
    Arranges the windows in a vertical fashion.
    Close All
    Closes all windows.
    Open Window List
    A list of all currently open windows.

    Help

    Index
    Displays the top-level index to all the Amzi! help files in a web browser.
    About Amzi!
    Displays version information for the installed software.
    Change Browser
    Changes the web browser program to use for displaying help.

    Projects

    Projects provide a useful way to organize and manage the creation of applications or components that consist of multiple files and/or libraries.

    Projects are created using the Windows-IDE. When a project is open a dialog box appears in the IDE with list boxes containing the files and libraries in the project. This dialog box stays open for the current project. Closing the dialog box closes the project.

    Creating a Project

    To create a project select File / New Project. This displays the project dialog box. To save your project, select File / Save or close the dialog box. Project files are saved with a .ppj suffix.

    Dialog Box

    Projects are edited via the project dialog box and saved using the normal File/Save or File/SaveAs menu items when the project dialog is the active window in the IDE. Projects are automatically saved when the project is closed. The project dialog box contains the following items:

    xpl File
    Enter the name of the .xpl file to be created when linking. This can be a full pathname.
    Project Directory
    The pathname for the directory to make current for all operations on the project.
    Operator Definitions
    The name of a Prolog file containing the operator definitions used by the source files in the project. This entry is optional, but if it is included it will be compiled or consulted first, so the operator definitions are known to all files in the project. (Note that operators defined in libraries are automatically applied first, so those operators do not have to be defined in either the project source files or the operator definition file.
    Project Files
    The list of .pro or .plm files included in the project. The extension is used when consulting the project into the listener. .pro Files are consulted as text files and .plm files are loaded as object files. The 'Add File' button adds one or more files. 'Remove File' removes a file from the project. The 'pro->plm' button changes a file extension.
    Library Files
    The list of .plm files included in the project (usually from the amzi/abin directory).

    Consulting/Loading

    In the Windows-IDE, you can consult and/or load all the files in your project into the listener by pressing the 'Re' button or by selecting Listener / Consult or Listener / Reconsult.

    All the .pro files are consulted, and the .plm files and libraries are loaded.

    Building

    Using the Windows-IDE, you can compile all the modified files, and link all the project files and libraries into an .xpl file by pressing the BLD button or by selecting Build / Build.

    Using the command-line, you can do the same by invoking abld on the project as follows:

    c> abld ducky.ppj

    Debugger

    Amzi! Prolog includes a debugger, based on the Clocksin & Mellish box-model of Prolog execution, that allows you to trace and interact with interpreted clauses as they are running. It is run from the Windows IDE using menu commands and dialog boxes, and from alis using built-in predicates.

    Box Model

    The box model of Prolog execution is a conceptual tool that gives a procedural interpretation of flow-of-control through a Prolog program. As such it is useful for understanding the execution of a program. To use the box model envision each Prolog goal surrounded by a box:

    Each box has four ports through which Prolog may enter (call and redo ports) or leave (exit or fail ports) the goal.

  • call - when Prolog is initially asked to prove the goal it enters through the call port.
  • exit - having entered through call, Prolog leaves through exit if it can prove the goal.
  • fail - if Prolog cannot prove the goal it leaves the box via the fail port.
  • redo - if at some further point in the program (i.e., after having entered through call and left via exit) Prolog backtracking occurs then eventually (if backtracking reaches this stage back in the proof) Prolog reenters the goal via the redo port.
  • There is one box per goal in a program, and the boxes are linked from port to port. Ports that we stop at in the debugger are known as "debug ports."

    You can creep through your program from port to port, stopping at each one. You might think of this as "single stepping" your program. The debugger can stop at every CALL, REDO, FAIL and EXIT and ask what to do next.

    Using leash (described later in this section) you can limit which of the ports are stopped at. Then, when you creep, all the ports will be displayed, but the debugger will only stop at the ones which are leashed. For example, you might want to stop only at CALLs and REDOs. By default, all ports are leashed when the debugger is started.

    Alternatively, you can "leap" to only the ports of predicates specified as spypoints. You might think of this as running until a "breakpoint" is reached. In this case, the intervening ports are not displayed.

    By combining your use of creeping and leaping, you can cause the debugger to stop at certain ports and interact with them before continuing. Thus you can rapidly trace through code which is of no interest (because it has already been debugged) and concentrate on a predicate or two at will.

    Starting and Exiting

    To start the debugger in the listener type:

    Command-Line alis Windows-IDE
    ?- debug. 
    Listener / Debug On

    To exit the debugger:

    Command-Line alis Windows-IDE
    ??- quit. 
    Listener / Debug Off

    Note, in command-line alis, the debug listener is identified by an extra "?" in the prompt. When you exit the debug listener you are returned to the original listener.

    Display

    In command-line alis, the debugger output is intermixed with other output in the normal scrolling dialog of the listener. The debugger is controlled by keyboard commands.

    Under the Windows-IDE, the debugger output is displayed in a separate window. The debugger is controlled by command buttons along the right side of the debugger window.

    The debugger works by displaying the names of the ports that execution passes through in the course of a computation.

    The message output by the debugger at a port is of the following form:

    For example:

    Notice that variables are represented using the Hn notation.

    DEPTH is a number of leading spaces indicating how many ancestors the goal involved in this port has, i.e., how deeply nested in the proof it is. So top-level goals (typed in response to ?-) are indented 0 spaces (for a depth of 0). Goals in the body of the clause proving this goal are indented 1 space (for a depth of 1). Goals in the bodies of clauses proving these goals are indented 2 spaces and so on. Depths greater than 10 are indicated by both a number and spaces.

    PORT: is one of CALL: REDO: FAIL: EXIT: corresponding to the ports of the box model discussed above.

    CLAUSE# is the number of the clause being executed. It is not displayed for built-in predicates because that is not useful.

    TERM is the goal (with any variable bindings) that caused entry to the call or redo port of the box.

    PROMPT if this port is a debugging port and we are running under a command-line environment, then ? is printed and user input is awaited, otherwise mouse or keyboard input is awaited.

    In the IDE the debugger display can be toggled to have formatting on or off. If formatting is on, then each argument of a goal appears on a separate line. With formatting off, each goal is written on a single line.

    portray(GOAL)

    portray/1 is a user-defined predicate that is called by the debugger when it displays a goal. You can create portray/1 clauses to generate formatted output of complex goals that are difficult to follow in the normal debugger listing.

    Debug Port Options

    At each debugging port you have a number of options for controlling the execution of the debugger. Under command-line environments, the usual response is one character (with no need to press [Enter]). Under the Windows-IDE, the usual response is to click on a button. The options are:

    Command
    -Line
    Windows
    -IDE
    Option
    Description
    [Enter]
    c
    Creep Creep to the very next port. If the next port is leashed (or is a spypoint) then prompt for further input else automatically creep to the next port after that. Consequently, if leashing is set to "none", creeping at one port will produce a tracing of all the ports between it and the next spypoint.
    f Fail Force the debugger to go to the fail port for this predicate invocation.
    l Leap Leap to the next spypoint. The next port to be displayed will be the next encountered spypoint.
    s Skip Skip. Only used at a call or redo port. This useful option turns off display from the debugger until it reaches the corresponding exit or fail port for this call. Thus it can be used to turn off the debugger during the course of a complex subproof. No messages will be issued by the debugger during this subproofeven if a spypoint is encountered.
    a Stop Aborts the debugger and returns to the debug listener.

    Other options are available for looking at and changing the Prolog environment under command-line alis. They are:

    Command- Line Windows- IDE Option Description
    n n/a Notrace. Turns off the debugger and then continues with the proof in progress. That is, runs the rest of your program.
    b n/a Break to a new listener. Temporarily turns off the debugger and invokes a new listener (with a ???- prompt). This allows you to work with the program however you please without leaving the trace. (You might want to separately test some predicates, change some, or whatever.) When the new listener is exited (by typing 'quit.'), the debugger is turned back on and the interrupted proof continues.
    d n/a Display the current goal with all of the current variable bindingsthen prompt again.
    h n/a Halts Prolog and exits.
    @ n/a Prompts for you to enter a Prolog goal. Temporarily turns off the debugger, like n, but instead lets you enter a single Prolog goal. It tries to prove it and then turns the debugger back on and continues the suspended proof. This is useful for quick checks of other parts of the program and for changing leashing or spypoints while debugging.
    ? n/a Displays a listing of debug port options.
    [^Break] n/a If your program is stuck in a loop, you can press [Ctrl-Break] and the debugger will stop at the next port and prompt for an option.

    Spypoints

    Spypoints are used to stop the debugger at particular predicates. Execution always pauses at a spypoint regardless of what ports are leashed and whether you are leaping or creeping.

    Under the Windows-IDE, you can click on the 'Spy...' button to get a dialog box containing a list of all predicates in your program. You can move those predicates back and forth between that list and the list of current spypoints.

    Under command-line alis, a spypoint is set on a predicate by using spy/1. It is removed by using nospy/1. To remove all spypoints, use nospyall/0. The current spypoints are listed by using spy/0.

    The argument to spy and nospy is one of:

  • name
  • name/arity
  • [list of name and/or name/arity]
  • In command-line alis, typically you will use the "@" debug port option to control your spypoints by entering the spy, nospy and nospyall commands as goals.

    Note that entering and exiting the debugger does not remove or otherwise alter the setting of spypoints. The only way to remove spypoints is to use one of the above.

    Leashing Debug Ports

    As mentioned above we can either creep or leap to a port. When we leap to a port, it is a port for a predicate that has a spypoint set on it, and the debugger pauses to allow interaction.

    Creeping takes us to the ports of predicates in between the spypoints. The debugger might pause at a port, or it may simply display it without giving you the opportunity to interact, as execution continues. The different behavior at ports is controlled by leashing.

    Leashing is not related to particular predicates, as spypoints are, but is instead a characteristic of each of the four types of ports, CALL, REDO, FAIL and EXIT. By default, all ports have leashing turned on, so all ports of predicates that are crept to are paused at. But leashing can be turned off for the ports of these intermediate predicates so they display but don't require step-by-step interaction from you.

    Under the Windows-IDE, you can select which ports are leashed by clicking on and off the button in front of the port name on the debugger window.

    Under command-line alis, you use the leash/1 predicate to specify the ports to make debugging ports as follows:

    Note that unmentioned ports are automatically unleashed. To find out what ports are currently being leashed use leash/0.

    In command-line alis, typically you will use the "@" debug port option to control your leashing by entering the leash command as a goal.

    Note that entering and exiting the debugger does not remove or otherwise alter the ports currently being leashed. The only way to change leashing is to use one of the above.

    Logging

    The log-file capability allows you to record a transcript of a Prolog session. This is especially useful in recording long traces during debugging.

    Logging can be controlled from a listener, or within a Prolog program or using the "@" debug port option through the use of built-in predicates.

  • openlog(Fname) - This opens the file Fname and sets a flag letting Prolog know it is logging. The file overwrites any previous file of the same name. Fname must be an atom, such as 'temp.log' or simply log.
  • closelog - This closes the log file and stops the logging process.
  • writelog(X) - Writes X just to the log file.
  • nllog - Writes a newline to the log file.
  • Logging can also be turned on for an application by specifying a log file in the application's .cfg file.

    Example

    Let's look at an example of creeping, leaping and leashing using Duck World presented in A Quick Tutorial. First we consult our source code and enter the debugger.

    Command-Line alis Windows-IDE
    ?- [duck1,duck2].
    yes
    ?- debug. 
    Listener / Consult duck1.pro
    Listener / Consult duck2.pro
    Listener / Debug On 

    Next, we set connect as a spypoint and leash only the call port. Then we call main.

    Command-Line alis Windows-IDE
    ??- spy(connect).
    yes
    ??- leash(call).
    yes
    ??- main. 
    Click Spy...
    Click connect / 2
    Click Add
    Click OK
    Uncheck REDO, FAIL and EXIT
    ?- main. 

    We start to creep through the program by typing "c" in command-line alis, and by clicking on "Creep" in Windows-IDE. Note, we pause only on CALL ports. Under alis, the program output is interspersed with the debugging information. Under the IDE, they are kept in separate windows. Here we show the command-line I/O with the program I/O shown in italics:

    Now we click on "Leap" (IDE) or type "l" (alis) to leap to our spypoint. No more debugging ports will be displayed until we get to the spypoint. But we will get a warning if there are no clauses matching a call.

    Our leap was interrupted for some user input, so we type "goto(yard)." We creep onwards watching the variable bindings and backtracking.

    We continue to creep forwards. Every time we reach a predicate that is a spypoint, we pause. Note that although we are only leashing CALLs, we pause at the other ports for connect, as shown below.

    We reach a predicate which we are not interested in seeing, so we click on "Skip" (IDE) or type "s" (alis) to skip to the EXIT or FAIL port for this call.

    Finally, we turn off trace and finish running the program:

    Command-Line alis Windows-IDE
    CALL: ! ? n
    >> quit.
    Quitter 
    Click Spy...
    Click Clear All
    Click OK
    CALL: !
    Click Leap
    >> quit.
    Quitter 

    Copyright ©1987-2011 Amzi! inc. All Rights Reserved. Amzi! is a registered trademark and Logic Server is a trademark of Amzi! inc.