User Guide

User Guide

This document teaches you the basics of using iGROM for Answer Set Programming Development. As an example, we will use vanilla DLV, but we will also add notes on advanced features (such as additional configuration for DLV dialects).

Since this guide is both for the Eclipse plugin and iGROM stand-alone, we will just write „application” when referring to either. The screenshots are from iGROM stand-alone though.

Writing your programs

Workspace and Projects

The concept of workspaces and projects are central to developing programs in Eclipse and in Eclipse-based applications.

Some definitions first. Simply put, a project is a container for files and folders. A workspace is, in turn, a container for projects (and some additional configuration files). Workspaces are mostly useful if you have multiple Eclipse installations, or if you want to categorize your projects generally (such as work, study, private etc.). However, there are ways to do this within a single workspace, and in fact I recommend to use only one workspace for normal work.

Working Sets are an advanced concept and you don't immediately need them when you start developing your programs. However, you will find them useful as you end up with a lot projects. See the Appendix for details.

Your first project and program

Let's start with creating a project. Open up your application, right-click on the white area to the left (the Explorer), select „New” and „New DLV Project”. Input the project's name into the text field, and click „Finish”.

You should see the new project appear in the Explorer. Now, click on this project again, and select “New”->„New DLV Program” this time. Fill in the name of the program (don't forget the „.dlv” extension), and select Finish.

The new program will open in the main window and you can start editing!

Several things to note:

  1. iGROM will mark your syntax with colors denoting different components of the language: variables, operators, etc. You can customize these colors (currently only for DLV and dialects) by going to “Window”->”Preferences...” and the selecting “Answer Set Programming”->”DLV”->”Syntax Highlighting”.

  2. iGROM also notifies you of problems with your code, such as syntax errors. There are two reporting levels:

  • Errors, which show you problems with your syntax (missing point and the like) and basic semantics (redeclaration of a predicate with different arity etc.),

  • Warnings, which show problems that will not cause your code to fail, but may produce an unexpected result (redeclaration of a query, for example).

Once you're done writing your first program, it's now time to run it. This will be explained in the next section.

Running Programs – Basic

Once we've written the program, we can now run it. First, we need to configure the interpreter. To do that, go to “Window”->”Preferences”->”Answer Set Programming”->”DLV”->”Interpreters”.

On the page, click “Add...” and then “Browse...” to add the interpreter executable. Note that it must be in the form of “dlv(.[exe|bat|sh])?”.

Note: for Smodels, you need to refer to a shell script that pipes lparse's result through smodels, and should be named “smodelslaunch(.[exe|bat|sh])?”. A simple example for Linux is here:

#!/bin/sh
lparse $1 | smodels

Then press “OK” twice, and there you have it. Of course, you can add as many interpreters as you like.

Note: the currently supported DLV interpreter version is “build BEN/Oct 11 2007”, mileage may vary on newer versions.

You're all set to run your program. Right-click on the editor window, select “Run As..”->”DLV Program”. The result of your program should appear in the console window.

Now that you know how you run a program consisting of a single file, you might want to learn how to include multiple files, and tweak the interpreter. This will be explained in the next section.

Running Programs – Advanced

Running a program from multiple files

To do that, simply Ctrl+Click on the chosen files in the Explorer, select “Run As..”->”DLV Program”. That's it!

Note: the files don't need to be in the same project.

Note: this also works for the frontends. For example, for diagnosis, just select a .hyp file, an .obs file, and one or more .dl files. iGROM will run the diagnosis with those files.

Managing your programs and projects

Now, in the top menu, select “Run.”->”Run Configurations...”. Run configurations are just what the name says, a configuration of the interpreter that causes a specific program to be run. A configuration contains the references to all the files that compose the program, and stores additional interpreter arguments as well.

If you've done the previous steps, some run configurations should be already there. Feel free to explore the available tabs and options. Mostly, you'll only need to concern yourself with the Main tab (where you set the input files), the “Arguments” tab (where you can set additional interpreter arguments) and the “Common” tab (where you tweak the run further, like redirect the standard output to a file).

Keep in mind that the planning and diagnosis frontends also have their specific tabs, in which you can configure the front-end specific parameters.

As you can probably see, you can also duplicate run configurations, and create new ones from scratch.

One important thing to note – the “Run as...” right-click menu is context-sensitive! This means that, if you launch e.g. a program with 3 files x,y, and z that way, change the created run configuration with some interpreter arguments, and then later select those 3 files (and only those files) again, the program will run with the previously saved changes!

Now you know everything you have to write and launch your programs in iGROM!

Additional features

Keep in mind that iGROM is based on the Eclipse platform, and, as such, contains many capabilities directly derived from it. Here are a few examples:

  • To search your files, use the Search menu, or press Ctrl-H. This will take you to a customizable dialog. To search/replace within one file, use Ctrl-F instead. Both searches support regular expressions.

  • You can automatically pack your files into archives. To do this, right-click on the Explorer, select “Export”, and then in the “General” category choose “Archive File”.

  • You can also export/import launch configurations. The options is located in the same place as the archive export, but in the “Run/Debug” tab.

  • If you want to add additional functionality, such as SVN and Git support, you can use Eclipse's plugin system via the “Help”->”Install new Software” option. This works only if you use iGROM as a plugin, not as stand-alone.

Appendix – Additional organization

Projects can be grouped further into Working Sets. Working Sets are tags for your projects – you can have a project in multiple working sets, or a project in no working sets. As the number of your projects grows, it is recommended to place them in working sets (instead of creating multiple workspaces). To start using working sets, click on the bottom-pointing arrow in the upper-right corner of the Explorer window, choose “Top Level Elements”->”Working Sets”. A window should pop up that will allow you to create the working sets and assign projects to them.