Hulles - NetBeans

Son Of GeeWhiz Prolog: Olio

nospam@example.com (Hulles) — Thu, 07 Aug 2008 21:10:57 +0200

This article describes an enhancement to GeeWhiz Prolog, a project to implement the Prolog language in the NetBeans IDE. See the GeeWhiz Prolog home page for more information.

What We'll Be Doing

In this installment of Son of GeeWhiz Prolog there really won't be much tutorial content. I'll do my best, but to be honest it's been long enough since I made the changes described here that I haven't been able to reassemble my notes properly, and I misplaced my screenshots. However I thought it would be better to post the new version of the source and NBM on the GeeWhiz Prolog home page rather than wait any longer. So here you go. I am not including separate source code in this article, so you'll need to download the source on the Home Page to find the changes. Dang, sorry.

Moving the Satellite Window to the Navigator

Probably the most obvious change is that the satellite view of the Prolog diagram has been transformed from a standalone JFrame window into a TopComponent that nestles into the Navigator window area. This is more convenient as it stays out of the way but remains accessible as you scroll around the larger diagram. It also makes us a "better NetBeans citizen": standalone JFrames bad, TopComponents good. We're leaving the popup code JFrame windows alone however, so I guess we're not that good a NetBeans citizen.

Another change is that we got rid of VPrologAction.java, which was the action living in the "Window" menu that opened up the demo/dummy diagram. Along with that, we eliminated the code in VPrologGraphScene to create the dummy diagram, and we added code to VPrologTopComponent to open and close the satellite navigator component. The final change regarding the satellite window is that we changed the "show / hide satellite" action in the right-click context menu in the main diagram. It is now just "show satellite", since you can close the satellite window like any other window whenever you want.

Minor Stuff

In the process of cleaning up GeeWhiz, it seemed to make more sense for the popup editor code to live in SceneUtils, so there it now resides. I also changed the phrase "1 instances" to read "1 instance" in the case where there is only 1 instance. Hey, it is too rocket science.

Problems, Setbacks and Failures

For Son 2 (this article) I wanted to experiment with FreeMarker, which is a scripting language that one can use to insert text into a template. This can automatically insert licensing information or whatever else you want into our trusty Prolog program template. Unfortunately I could not get it to work reliably. In the newest version of the source code I left the FreeMarker code in, but every time I tried to execute it outside of the top level of the source code I got a cryptic error:

WARNING [org.openide.WizardDescriptor] java.lang.StringIndexOutOfBoundsException: String index out of range: -1 at java.lang.String.substring(String.java:1938) at java.lang.String.substring(String.java:1905) ...

Ouch. As I mentioned this only happened when the template was not in the top level of the source, for some reason. I puzzled over it for a while then gave it up as a bad job. But I thought I'd pass it along anyway. I guess GeeWhiz Prolog was not destined to be the kind of application that has source code licenses....

Another experiment I thought I would try was to use the capability of the Visual Library to directly associate objects with scene nodes. This would allow us to eliminate the Prolog object lookup we need to do to translate from node to Prolog clause. Hmmm, I thought, simpler is better, it sounds good. However, I hammered away at associating any kind of object with the nodes in our diagram scene and kept getting assertion errors in the Visual Library that didn't tell me what the hell was wrong. I finally traced the VL source code and found out that in a GraphScene there is already an object associated with a node that lurks behind the scenes. At least I think that's what's happening; it looks like a String is hooked up to a node as an object, and you can only have one object per node. Consequently, we can't hook up our Prolog clauses to nodes that way unless we quit using GraphScene, which is a poor trade. So the list association we started with remains intact, bloody but unbowed. As a footnote, I've used the Visual Library a great deal since the experiment I described above, and every time I get an accursed assertion error from VL I know that it's a problem with trying to add multiple objects to a node. That would probably be a good thing to fix in the next release of the Visual Library. And it's a good thing to know if you're working with it.

Almost forgot - another problem I encountered has nothing directly to do with NetBeans: I have been trying to get some HTML windows to pop up from this blog platform that don't have the sidebars etc. so I can better display a few movies I made using Wink that demonstrate the use of GeeWhiz Prolog. I haven't been able accomplish that so I am posting the Flash videos just as links on the GeeWhiz Prolog home page. Check them out. I created the movies so that people who are interested in Prolog but who don't care to know anything about NetBeans can see what the program does without going through the process of downloading NetBeans and learning the IDE. I'm nice like that.

Going Further

Well, sort of a lame Son of GeeWhiz Prolog, I know, but I didn't want to post the updated source code and not provide an explanation to go with it. I don't have plans to post anything new here for a while as I am in the middle of a large project utilizing NetBeans, unless.... Well, we'll see.

Files From This Entry

(see the newly posted source code zip files and NBM on the GeeWhiz Prolog home page.)

Son Of GeeWhiz Prolog: Improving The Diagram

nospam@example.com (Hulles) — Tue, 27 May 2008 00:33:51 +0200

This article describes an enhancement to GeeWhiz Prolog, a project to implement the Prolog language in the NetBeans IDE. See the GeeWhiz Prolog home page for more information.

What We'll Be Doing

In this add-on to our GeeWhiz Prolog project, we're going to add some new features and Geewhizability to our predicate modeler. Big thanks go to David Kaspar who provided the Visual Library examples from which much of this material is ~~stolen~~ taken. The examples are located in the "main/contrib" section of the NetBeans Mercurial repository (although I haven't updated my own library yet to reflect this). You can find them at this link: http://hg.netbeans.org/main/contrib/file/ under "visual.examples".

Adding An Export Function

The first change we're going to make to our nifty Prolog predicate diagrammer is that we're going to add a means by which we can export our diagram to a Portable Network Graphics (PNG) file. Once we have a PNG file, we can print it, email it to Aunt Margaret in Philly, or (hypothetically) stick it on our GeeWhiz Prolog home page. So let's get started.

First, create a new Java class in your project called "SceneExport". Replace the empty class with this:

public class SceneExport { public void exportScene(VMDGraphScene scene) { JComponent view; Dimension dim; BufferedImage bufImage; Graphics2D graphics; File file; view = scene.getView(); dim = view.getSize(); bufImage = new BufferedImage (dim.width, dim.height, BufferedImage.TYPE_4BYTE_ABGR); graphics = bufImage.createGraphics (); scene.paint (graphics); graphics.dispose (); file = getPNGSaveFile(view); if (file != null) { diagramToPNG(file, bufImage); } } private File getPNGSaveFile (JComponent view) { JFileChooser chooser; File file; //TODO: save selected directory as default for next time chooser = new JFileChooser(); chooser.setDialogTitle("Export Scene As ..."); chooser.setDialogType(JFileChooser.SAVE_DIALOG); chooser.setMultiSelectionEnabled(false); chooser.setFileSelectionMode(JFileChooser.FILES_ONLY); chooser.setFileFilter(new FileFilter() { public boolean accept(File file) { if (file.isDirectory()) return true; return file.getName().toLowerCase().endsWith(".png"); } public String getDescription () { return "Portable Network Graphics (.png)"; } }); if (chooser.showSaveDialog (view) != JFileChooser.APPROVE_OPTION) { return null; } file = chooser.getSelectedFile (); if (! file.getName ().toLowerCase ().endsWith (".png")) file = new File (file.getParentFile (), file.getName () + ".png"); if (file.exists ()) { DialogDescriptor descriptor = new DialogDescriptor ( "File (" + file.getAbsolutePath () + ") already exists. Do you want to overwrite it?", "File Exists", true, DialogDescriptor.YES_NO_OPTION, DialogDescriptor.NO_OPTION, null); DialogDisplayer.getDefault().createDialog(descriptor).setVisible(true); if (descriptor.getValue() != DialogDescriptor.YES_OPTION) { return null; } } return file; } private void diagramToPNG(File file, BufferedImage bufImage) { try { ImageIO.write (bufImage, "png", file); // NOI18N } catch (IOException e) { ErrorManager.getDefault ().notify (e); } } }

What the above code does is copy the predicate diagram graphics to a BufferedImage then save the image to a PNG file. Pretty straightforward, and taken from Visual Library example code that I haven't been able to find again. So fix imports, save and close the SceneExport class then create a new Java class called "SceneUtils". Replace the empty class with this code:

public class SceneUtils { private static final String EXPORT_SCENE = "export"; private static final String ACTION_MOVE = "move"; private static final String REMOVE_LABEL = "remove"; private static final String REPLACE_LABEL = "replace"; private LabelWidget label; private Scene scene = null; private boolean isVMD; public SceneUtils(Scene scene) { this.scene = scene; isVMD = scene instanceof VMDGraphScene; } public void addContextMenu() { WidgetAction popup; if (scene == null) { return; } label = new LabelWidget (scene, "Right-click to open popup menu."); label.setPreferredLocation (new Point (100, 100)); scene.addChild (label); popup = ActionFactory.createPopupMenuAction (new MyPopupProvider ()); scene.getActions ().addAction (popup); // leave popup menu up (?) scene.createActions (ACTION_MOVE).addAction (popup); label.createActions (ACTION_MOVE).addAction (ActionFactory. createMoveAction ()); } private void exportScene() { SceneExport exporter; if (isVMD) { // TODO: thread exporter = new SceneExport(); exporter.exportScene((VMDGraphScene) scene); } } private void addMoveAction() { scene.setActiveTool(ACTION_MOVE); } private void removeLabel() { // removes it from the scene, doesn't delete it this.label.removeFromParent(); } private void replaceLabel() { if (label.getParentWidget() == null) { scene.addChild(label); scene.validate(); } } private final class MyPopupProvider implements PopupMenuProvider, ActionListener { private JPopupMenu menu; public MyPopupProvider () { menu = new JPopupMenu ("Popup menu"); JMenuItem item; if (isVMD) { item = new JMenuItem ("Export scene to PNG..."); item.setActionCommand (EXPORT_SCENE); item.addActionListener (this); menu.add (item); } item = new JMenuItem ("Move the label"); item.setActionCommand (ACTION_MOVE); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Delete the label"); item.setActionCommand (REMOVE_LABEL); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Replace the label"); item.setActionCommand (REPLACE_LABEL); item.addActionListener (this); menu.add (item); } public JPopupMenu getPopupMenu (Widget widget, Point localLocation) { return menu; } public void actionPerformed (ActionEvent e) { String cmd; cmd = e.getActionCommand (); if (cmd.equals(EXPORT_SCENE)) { exportScene(); } else if (cmd.equals(ACTION_MOVE)) { addMoveAction(); } else if (cmd.equals(REMOVE_LABEL)) { removeLabel(); } else if (cmd.equals(REPLACE_LABEL)) { replaceLabel(); } } } }

In SceneUtils we're creating a context menu that pops up when you right-click on our lovely model diagram. In this incarnation it was written to cope with any kind of Scene even though the export function only handles VMDGraphScene. The menu includes some choices that are of limited utility in practice but serve to demonstrate the capability of the right-click popup. We also introduce the LabelWidget, which we haven't seen before. So fix imports, save and close the SceneUtils file.

Finally, we're going to change the VPrologGraphScene class to use our SceneUtils class. At the beginning of each constructor, add the following code:

SceneUtils sceneUtils; sceneUtils = new SceneUtils(this); sceneUtils.addContextMenu();

At the very end of each constructor, add this line:

        layoutScene();

I found the "layoutScene" method by accident when I was working through some of David Kaspar's Visual Library examples. It automatically cleans up our diagram! Evidentally there is a more robust orthogonal link router in the works, but for our purposes this one works just fine and eliminates much of the haphazardness of the random way we were placing nodes before. Woohoo!

Save and close the file. Now we're ready to test the beast. Clean and build the project, then install it to the target IDE. (You missed doing that since completing the original GeeWhiz project, didn't you?) Open your Algorithms project and wait for the indexing to stop. Now we're ready to check out our new popup menu. Open the sieve.pro file (or any other Prolog file) and wait for the Navigator to fill in the statements and for the syntax to color. Then go to the menu and click "View" "Show Prolog Diagram" to bring up the predicate model of our program. ("Gee whiz!") Right-click on the diagram to get our popup menu.

First, try moving, deleting and re-adding the label. Then, when you're tired of playing with that, try exporting the diagram to a PNG file. Cool, eh? If you monkey around with it enough, however, you'll notice that if you zoom and pan the diagram prior to exporting the PNG the export doesn't work exactly right. For now my solution for this glitch is: don't zoom or pan the diagram prior to exporting the PNG. Someday I'll look into fixing this; I think that maybe I need to get the dimensions from something other than the view graphics. But we have other things to do now, so let's leave it alone.

And by the way, don't forget to gasp with delight at the way layoutScene() fixes up our diagram when it is first displayed! When you're done testing and fooling around you can close the target IDE.

Adding Editor Windows To Nodes

The next feature we're going to add is a window containing the text Prolog source code for the predicate that opens up when we double-click on a predicate node. You wondered why we built the text into our PrologClause class, didn't you? This is why. First, create a new JFrame Java class called "NodeContents" by right-clicking on the package and selecting "New" "JFrame Form..." This is going to be the window in which we display our source code. In the "Design" view, add a scroll pane that snaps to the preferred borders of the frame and then add a text area that fills the scroll pane. Rename the text area to "textArea", then in Properties give it a descriptive tool tip, unclick the "editable" property and change the tab size to 4. In the JFrame properties, change the defaultCloseOperation to "HIDE". Switch to "Source" and delete the Main method. Right below the constructor, insert the following code:

public void setText(String text) { textArea.setText(text); } public void changeTitle(String title) { this.setTitle(title); }

Save and close the file. Now open VPrologGraphScene and replace the whole VPrologGraphScene class with this:

public class VPrologGraphScene extends VMDGraphScene { private static final Image IMAGE_NODE = Utilities. loadImage ("org/hulles/geewhiz/node.png"); // NOI18N private static final Image IMAGE_EXTERNAL = Utilities. loadImage ("org/hulles/geewhiz/external.png"); // NOI18N private static final Image IMAGE_ITEM = Utilities. loadImage ("org/hulles/geewhiz/item.gif"); // NOI18N private static int pinID = 1; private static int edgeID = 1; private List<PrologClause> clauses; /** Creates a new instance of VPrologGraphScene */ public VPrologGraphScene() { // demo SceneUtils sceneUtils; sceneUtils = new SceneUtils(this); sceneUtils.addContextMenu(); createNode (this, 100, 100, IMAGE_NODE, "Clause1", "Internal", null); createPin (this, "Clause1", "start", IMAGE_ITEM, "Start", "Element"); createNode (this, 400, 100, IMAGE_NODE, "Clause2", "External", Arrays.asList (IMAGE_EXTERNAL)); createPin (this, "Clause2", "ok", IMAGE_ITEM, "okCommand1", "Command"); createEdge (this, "start", "Clause2"); createEdge (this, "ok", "Clause1"); layoutScene(); } public VPrologGraphScene(DataObject dObj) { PrologAST pTree; List<PrologClause> embedded; String nodeID; Integer instances; String newPinID; PrologClause existingClause; String eNodeID; List<String> eNodes; SceneUtils sceneUtils; VMDNodeWidget node; sceneUtils = new SceneUtils(this); sceneUtils.addContextMenu(); pTree = new PrologAST(dObj); clauses = pTree.getClauses(); // create all primary nodes first so they're available // to create edges to.... for (PrologClause clause : clauses) { instances = clause.getInstanceCount(); nodeID = makeNodeID(clause); node = createNode(this, randXPoint(), randYPoint(), IMAGE_NODE, nodeID, instances.toString() + " instances", null); addEditor(node, clause); } // now create pins and edges eNodes = new ArrayList<String>(); for (PrologClause clause : clauses) { nodeID = makeNodeID(clause); embedded = clause.getBody(); for (PrologClause e : embedded) { eNodeID = makeNodeID(e); newPinID = "pin" + VPrologGraphScene.pinID++; createPin(this, nodeID, newPinID, IMAGE_ITEM, eNodeID, "Embedded"); existingClause = PrologClause.findClause(clauses, e); if (existingClause == null) { if (!eNodes.contains(eNodeID)) { // externally defined (?) createNode(this, randXPoint(), randYPoint(), IMAGE_NODE, eNodeID, "External", Arrays.asList (IMAGE_EXTERNAL)); eNodes.add(eNodeID); } } createEdge(this, newPinID, eNodeID); } } layoutScene(); } private String makeNodeID(PrologClause clause) { String name; Integer arity; name = clause.getName(); arity = clause.getArity(); return name + "/" + arity.toString(); } private int randXPoint() { return (int) (Math.random() * 800); } private int randYPoint() { return (int) (Math.random() * 800); } private VMDNodeWidget createNode (VMDGraphScene scene, int x, int y, Image image, String name, String type, List<Image> glyphs) { VMDNodeWidget widget; widget = (VMDNodeWidget) scene.addNode (name); widget.setPreferredLocation (new Point (x, y)); widget.setNodeProperties (image, name, type, glyphs); scene.addPin (name, name + VMDGraphScene.PIN_ID_DEFAULT_SUFFIX); return widget; } private void createPin (VMDGraphScene scene, String nodeID, String pinID, Image image, String name, String type) { VMDPinWidget pinWidget; pinWidget = (VMDPinWidget) scene.addPin (nodeID, pinID); pinWidget.setProperties (name, null); } private void createEdge (VMDGraphScene scene, String sourcePinID, String targetNodeID) { String localEdgeId; localEdgeId = "edge" + VPrologGraphScene.edgeID ++; scene.addEdge (localEdgeId); scene.setEdgeSource (localEdgeId, sourcePinID); scene.setEdgeTarget (localEdgeId, targetNodeID + VMDGraphScene.PIN_ID_DEFAULT_SUFFIX); } private void addEditor(VMDNodeWidget node, PrologClause clause) { NodeEditor editor; WidgetAction nodeAction; editor = new NodeEditor(clause); nodeAction = ActionFactory.createEditAction(editor); node.getActions().addAction(nodeAction); } public void newLayout() { layoutScene(); } private class NodeEditor implements EditProvider { private final PrologClause clause; private final String popupTitle; private final String popupText; private NodeContents popup; public NodeEditor(PrologClause clause) { this.clause = clause; this.popup = null; popupTitle = makeNodeID(clause); popupText = clause.getText(); } public void edit(Widget node) { // assumes read-only text VMDNodeWidget myNode; myNode = (VMDNodeWidget) node; // lazy edit window construction if (popup == null) { java.awt.EventQueue.invokeLater(new Runnable() { public void run() { popup = new NodeContents(); popup.changeTitle(popupTitle); popup.setText(popupText); popup.setVisible(true); } }); } else { popup.setVisible(true); } } } }

What we're doing here is, for every defined node (as opposed to external node) that we create, we're adding an EditAction that creates a NodeContents window when the node is double-clicked. We hold off actually creating the NodeContents window until the node is double-clicked so we can be a good NetBeans neighbor. Also, notice that instead of disposing of the window when we close it we just hide it so we can set it visible again the next time it's clicked.

Adding A Satellite Window

Before we test the editor functionality we're going to go ahead and make another window that shows the entire diagram in miniature, called in Visual Library terms a satellite view. We're going to show it and hide it via our context menu. So create another new JFrame called NodeSatelliteView.

In "Design" mode add a panel to the frame that takes up the whole frame and make it "BorderLayout". Change the name from jPanel1 to satellitePanel and give it a tooltip "Prolog diagram satellite view". Change the JFrame defaultCloseOperation to "HIDE" and the title to "Prolog Satellite View". Switch to "Source" mode, remove the Main method, and add this method below the constructor.

public void addView(JComponent view) { satellitePanel.removeAll(); satellitePanel.add(view); }

Save and close the file. Now open "SceneUtils" and replace the entire class with this.

public class SceneUtils { private static final String EXPORT_SCENE = "export"; // NOI18N private static final String LAYOUT_SCENE = "layout"; // NOI18N private static final String PRINT_SCENE = "print"; // NOI18N private static final String SATELLITE_VIEW = "satellite"; // NOI18N private VPrologGraphScene scene = null; private NodeSatelliteView viewer; public SceneUtils(VPrologGraphScene scene) { this.scene = scene; } public void addContextMenu() { WidgetAction popup; if (scene == null) { return; } popup = ActionFactory.createPopupMenuAction (new MyPopupProvider ()); scene.getActions ().addAction (popup); // leave popup menu up (?) scene.createActions (LAYOUT_SCENE).addAction (popup); } private void exportScene() { SceneExport exporter; // TODO: thread exporter = new SceneExport(); exporter.exportScene((VMDGraphScene) scene); } private void reLayoutScene() { scene.newLayout(); } private void printScene() { // not yet implemented } private void makeSatelliteView() { if (viewer == null) { java.awt.EventQueue.invokeLater(new Runnable() { public void run() { JComponent view; viewer = new NodeSatelliteView(); view = scene.createSatelliteView(); viewer.addView(view); viewer.setVisible(true); } }); } else { if (viewer.isVisible()) { viewer.setVisible(false); } else { viewer.setVisible(true); } } } private final class MyPopupProvider implements PopupMenuProvider, ActionListener { private JPopupMenu menu; public MyPopupProvider () { menu = new JPopupMenu ("Popup menu"); JMenuItem item; item = new JMenuItem ("Print scene..."); item.setActionCommand (PRINT_SCENE); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Export scene to PNG..."); item.setActionCommand (EXPORT_SCENE); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Redo scene layout"); item.setActionCommand (LAYOUT_SCENE); item.addActionListener (this); menu.add (item); item = new JMenuItem ("Show / hide satellite view"); item.setActionCommand (SATELLITE_VIEW); item.addActionListener (this); menu.add (item); } public JPopupMenu getPopupMenu (Widget widget, Point localLocation) { return menu; } public void actionPerformed (ActionEvent e) { String cmd; cmd = e.getActionCommand (); if (cmd.equals(EXPORT_SCENE)) { exportScene(); } else if (cmd.equals(PRINT_SCENE)) { printScene(); } else if (cmd.equals(LAYOUT_SCENE)) { reLayoutScene(); } else if (cmd.equals(SATELLITE_VIEW)) { makeSatelliteView(); } } } }

Notice that we got rid of the label and label actions and tailored the class to be specific to our Prolog needs instead of generic. We added an empty printing function, a layout function, and a satellite view function to our context menu and implemented the satellite view within the class. Fix imports, save and close the file. Now we're ready to test the work we've done. You'll like this.

Testing The New Diagram

Clean and build the main project, then install to the target IDE. Open the "Algorithms" project and open "sieve.pro". When the Navigator comes up, start up the modeler ("View" "Show Prolog Diagram") and double-click on a node. If the node is defined and not external then a window should open with the text of all the clauses that make up the predicate.

Notice that you can open more than one predicate window at a time but only one window per node, which makes sense within the context of the diagram.

Now right-click on the diagram to bring up our context menu.

Move a node or two then try out the "Redo layout" function. Hold your breath, then try "Show / hide satellite view".

Move the cursor around on the satellite view and watch what happens to your underlying diagram. Gee whiz! Pretty awesome, right? To close the satellite view you can click "Show / hide..." again in the context menu or just close the window. As you might suspect, the satellite view is not very useful with small diagrams like the one sieve.pro generates, but with a larger diagram like that in the screen shot it can be very useful indeed. Plus, it's just plain fun to have it around.

Going Further

One of the funky things about what we accomplished in this entry is that the screens for the node text and the screen for the satellite window are all JFrames independent of the diagram TopComponent. If you close the diagram, the frames stick around anyway. While you could possibly make a case that the little text windows are useful independently of the diagram, at least the satellite window should be dependent on the TopComponent and go away when it goes away. It is not useful without the diagram. So a reasonable next step would be to make the "pop up" screens for node text and the satellite window JDialogs or close them when the TopComponent goes away.

Now that we have all these new features on our diagram, what else could we do? The first thing that comes to mind is to allow the user to edit the code in the popup node window and have the changes reflected in the editor window source code. This would take some careful design because of the way multiple clauses make up a predicate, but it could certainly be done using techniques we've already looked at. We could disembowel the PrologAST class and store line and column numbers in PrologClause, then use the same way we pop into the source code from the output window to go into the editor and change the text. But the usefulness of editing directly in the popup window is pretty questionable, at least for Prolog programming, so we won't go that route. I won't, anyway, but you certainly can...

An even more interesting (to me) idea is to use the stuff we learned in GeeWhiz to write a whole new language interface. It would be based on Java but instead of writing code you would just manipulate nodes and edges then compile the diagram! Theoretically a person would not even have to know Java to "program" with this new language. I know, I know, it sounds like UML but it would be way cooler. Actually, this is something I've always wanted to develop, so look for "Project PipeDreams" coming your way soon....

Files From This Entry

GeeWhiz Prolog - Part Eight - Creating An NBM

nospam@example.com (Hulles) — Fri, 23 May 2008 15:18:12 +0200

This is Part Eight, the ninth and final part of a series of entries describing an implementation of the Prolog language in the NetBeans IDE.

Part Zero, "About The Project," is here.
Part One, "Before We Start," is here.
Part Two, "Creating A File Type," is here.
Part Three, "Adding Language Support," is here.
Part Four, "A Visual Prolog Modeler" is here.
Part Five, "Adding The Compiler" is here.
Part Six, "Creating Prolog Projects" is here.
Part Seven, "Adding An Option Panel" is here.

What We'll Be Doing

Well, we've come a long way. Our NetBeans-embedded Prolog IDE has grown like Topsy (whoever Topsy is) and now threatens to take over NetBeans entirely and make everyone program in Prolog instead of Java. Okay, maybe not, but it has come a long way as I said. We will look at what we've accomplished in a post mortem in a little bit, but right now let's create a NetBeans plug-in module (NBM) from GeeWhiz Prolog and install the module into our development IDE at last.

Creating The NBM

As I'm sure you've noticed, one of the options on the GeeWhiz project context menu in NetBeans has always been "Create NBM". Go ahead and clean and build GeeWhiz, right-click on the project and select "Create NBM" now.

After some whirring and clanking (note to self: backup Aspen files!) the IDE settles down again and you've created the NBM file. Unless you have the output window open you might not even notice that anything happened as there is no user interaction for this process.

What we've done is generate a nifty little zip file called (in my case) "org-hulles-geewhiz.nbm" in the build folder of our project.

At this point, you should save the NBM file to another directory. I realized to my chagrin while writing this that the "clean" process in cleaning and building your project wipes out the build directory, including the NBM file. It's easy enough to regenerate, as we just saw, but still.... One wants to be sure the NBM file one thinks one has matches the file one thought one had, doesn't one? Yes one does, by golly.

I'm not sure you noticed in the above screenshot, but I had the properties for the NBM file open so you could see what I saw the first time I went through this process. "Hmm," says I to myself. "The size is a little larger than I thought it would be. And I guess the NetBeans folks forgot to put the 'kB' on the size property. It's still too large to host as a download, though." Then I went and looked at the file in the folder just to make sure and it's 47kB! Dang, that's like buying a case of beer for a dollar, it just doesn't happen that often these days. So it's a little file, is my point, and I can stick it on my blog site as a download without a further thought. Hell, I can even email it as an attachment to my Aunt Margaret in Philly who still has dial-up. (Not sure she has NetBeans, though....)

So now what do we do with our brand new (and shrimpy little) NBM file? For one thing, if we wanted to we could make it available to the whole world via the NetBeans Plug-In Download Center (or whatever it's called) but that's a bit outside the scope of this project and besides, it's not ready for implementation yet. But we can use it to finally install GeeWhiz Prolog in our development IDE if we want to. So let's do that.

Installing The NBM In Your IDE

There is probably a more dignified way to install a local NBM into your IDE, but the way I found works pretty well so we'll use that. In the main menu of your development IDE click "Tools", then "Plugins". Once the Plugins manager has started, select the Downloads tab. Click the "Add Plugins..." button and navigate to your NBM file and select it.

Now your new module looks all shiny and ready to go, doesn't it? You can change the information that shows up on the right by right-clicking the GeeWhiz project and selecting "Properties" and filling out the "Display" and "Packaging" tabs in the Properties window. Then of course you have to recreate your NBM file. Once you're ready to bite the bullet, select "GeeWhiz Prolog" then click the "Install" button.

On the first screen there isn't much to do but sit and admire the professional look of your work. When you're ready, click the "Next" button.

On the next screen, unless you created a GeeWhiz license when I wasn't looking, you can just go ahead and click "Install". Ignore the "not digitally signed" messages you will generate unless you also signed it when you created the license, you rascal.

Eventually the IDE will come back and tell you the module is installed. To check it, select "Tools" "Module Manager" from the main menu and there GeeWhiz Prolog is, under "Language Support".

Gee whiz! Ain't it great? Check it out in your IDE; all the functions we tested in the target IDE should be there. You might consider copying or moving the Algorithms project from the target project directory to your real project directory, just to have test fodder available.

Guess What - We're Done!

That wraps up our adventures with GeeWhiz Prolog, at least for now. I am in the process of creating a home page for GeeWhiz Prolog on my blog that you can check occasionally if you want. I will post the NBM there, plus a complete set of source files, plus a PDF of all the GeeWhiz blog entries for your convenience in downloading and reading offline. Any addenda and errata (as if) will be posted there as well. I already thought of one thing I forgot to mention, and that's that you can zoom in and out (ctrl + mouse button) and pan (hold middle mouse button) on the modeling diagrams we created earlier.

As a special bonus for acting now, you will also receive an additional Java class in the complete source file archive called SceneExport.java that may or may not create a .PNG file from the modeling diagram. I'm still working on it and haven't incorporated it into the diagram yet, but I'm sure I'll write about it when I do. It's based on a slightly cryptic code segment in the Visual Library API and... Oh, just wait and read the article when I write it.

It's hard to end this series. I feel like we just scratched the surface with GeeWhiz Prolog, but hey, the surface itched. So... ciao, it's been fun. I hope you found this series useful, informative and occasionally entertaining. -- Hulles

GeeWhiz Prolog Feature Summary

Incorporated as an integral part of the NetBeans IDE
Has a WYSIWYG source code editor
Provides Prolog syntax checking and highlighting
Works with the sidebar statement navigator
Generates a visual and interactive Prolog predicate model that personally rocks my world
Supports in-line Prolog source code compilation with error lines linked back to source
Is O/S- and compiler-independent
Is installable as a plug-in module to the NetBeans IDE
Is free
The source code is easily modifiable since you build the damn thing yourself
Did I mention it's free?

Going Further - My GeeWhiz Notes

Fixes And Improvements To Current Features

Use public API for Generic Languages Framework: Change PrologAST to not user ParserManagerImpl to get the AST root node so we can go back to the public API and not use an implementation version of GLF.
Change Names To Be More Descriptive: Change the name of the PrologClause class to PrologPredicate, e.g. In other words, refactor refactor refactor.
Improve the Prolog grammar definition: Improve the grammar defined in language.nbs for Prolog. I think it can be simplified and improved.
Improve threading in GeeWhiz: Analyze GeeWhiz and introduce threading, concurrency, Runnables and all of that kind of shit so it looks like I know what I'm doing in Java but that makes the code five times more complicated and harder to understand.
Take care of compiler warnings: Analyze the warnings produced by the IDE when it starts up the target IDE and see what I can fix and what I should leave alone.
Experiment with other SWI Prolog compiler options: Try the -s option instead of the -c option and actually read the SWI documentation a little more closely.
Fix remaining TODOs in code comments: Probably I'll need to look at the good old Task List (ctrl+6) sometime. Jeez, it's like being married....
Fix the *&$%!* coffee cup icon on my new Prolog projects: Enough said. Although while I'm at it I can see if there's anything else I can get rid of (or add) for new Prolog projects.
Add license and digital certificate to GeeWhiz: I should maybe make this an entry since a first glance at the docs available seemed less than promising.
Find out how to create a target platform that is leaner for performance reasons: Either that or buy a faster machine.

Additional Features That Could Be Added To GeeWhiz

Localize messages, strings, etc.: Be a good world citizen and stick all messages etc. in Bundle
Add help: Add JavaHelp to the project. This might be another entry as well. It's pretty cool how it works, though....
Make the static predicate visual model dynamic and refer back to source: This is complicated by the fact that the predicate / clause relationship is not 1:1, but maybe light up all source clauses when a widget is selected....
Add freemarker support: Oops, I was going to do that as part of the original project. Hopefully no one noticed.
Interact with SWI Prolog via IOProvider Reader: Just for fun we should try out the Reader in the output window.
Create a satellite view for the modeler: Make a satellite view of the diagram a la Geertjan's example but preferably in a different window (popup?) as opposed to a sidebar.
Add XPCE support: Add support for SWI Prolog's buddy XPCE somehow. That would be a challenge, I bet... Wonder if it's Windows-compatible.

Either They're IDE Bugs Or I'm Doing Something Wrong Dept.

On-again / off-again DataObject-dependent icons and menu items: Find out once and for all if the above is me or the IDE. Then yell at the IDE people regardless.
Wizards should be able to deal with icons already in the project directory: For creating actions e.g. the wizard shouldn't give an error if the icon is already in the directory.
Better reload support in "Install / reload to target": I shouldn't have to clean the project every damn time I retest. Look into security errors etc.

Areas For Further Research

NetBeans platforms and their creation
Visual Library, especially the VMD part
JavaHelp
DataObjects, cookies, and their ilk

GeeWhiz Prolog - Part Seven - Adding An Option Panel

nospam@example.com (Hulles) — Thu, 22 May 2008 17:05:13 +0200

This is Part Seven, the eighth part of a series of entries describing an implementation of the Prolog language in the NetBeans IDE.

Part Zero, "About The Project," is here.
Part One, "Before We Start," is here.
Part Two, "Creating A File Type," is here.
Part Three, "Adding Language Support," is here.
Part Four, "A Visual Prolog Modeler" is here.
Part Five, "Adding The Compiler" is here.
Part Six, "Creating Prolog Projects" is here.

What We'll Be Doing

Our Prolog IDE is quickly maturing into a comfortable, fun and feature-rich programming environment. But if you're like me -- and I hope for your sake you are not -- you've been laying awake at night, sweating, thinking to yourself,

"Gee whiz! I created this great Prolog IDE but I totally ruined it when I hard-coded the compiler command stuff into the project (see Part Five, "Adding The Compiler"). Now I can't make it into an NBM and distribute it and have everybody in the world use it and love it and have somebody write an article for NetBeans.org called 'Meet A NetBeans Module Writer: Hulles' with my picture in it and everything."

Well, we all need our sleep, so lay awake no longer. This time we're going to add an IDE-level Prolog options screen where we can set the compiler command and arguments outside of our code and have it retained between sessions. We're also going to clean up some code while we're at it so our project is a little more compatible with the NetBeans IDE -- a "better NetBeans citizen," as they say.

This entry is partially based on a Geertjan article in NetBeans called "NetBeans Options Window Module Tutorial". I recommend checking it out prior to doing this entry if you feel so inclined; he gives you more background than I give you here. And thanks to the author for that tutorial and all the other fine NetBeans articles he has done.

Adding An Options Panel

First off we're going to start up the New Options Wizard. Right-click on your GeeWhiz project and select "New" "Other".

Select the "Module Development" category and choose "Options Panel", then click "Next". On the next screen of the wizard we're going to create a tab for Prolog in the "Miscellaneous" section of the "Tools/Options" menu.

Select "Create Miscellaneous Panel" then enter "Prolog" for the title. Type "Prolog project options" for the tooltip text and hit "Next".

The next screen should come up already filled in for you, but check and make sure the project is "GeeWhiz Prolog", the class name prefix is "Geewhiz", and the package name is filled in correctly ("org.myorg.geewhiz"). Then click "Finish" and let the wizard generate the files.

Now we're going to take the panel that the wizard created and modify it for our own nefarious purposes. Open "GeewhizPanel.java" in design mode and from the Swing palette add a panel that fills the frame, then add two labels and two text fields to the panel, as in the screenshot.

Rename the top text field by right-clicking it and selecting "Change Variable Name...". Call it "compilerName". Add a tooltip to it in Properties that says "Enter the command to invoke the compiler, e.g. "swipl"". Rename the bottom text field to "compilerArgs" in the same way and add a tooltip that says "Enter arguments to the compiler command, e.g. "-c -r"". When you're satisfied, switch to source view and change the load and store methods to:

    void load() {
        compilerName.setText(NbPreferences.forModule(GeewhizPanel.class).
                get("compilerName", "swipl"));        
        compilerArgs.setText(NbPreferences.forModule(GeewhizPanel.class).
                get("compilerArgs", "-c"));        
    }

    void store() {
        NbPreferences.forModule(GeewhizPanel.class).put("compilerName", 
                compilerName.getText());
        NbPreferences.forModule(GeewhizPanel.class).put("compilerArgs", 
               compilerArgs.getText());
    }

What we're doing here is loading and storing the two data we need for our compiler, the compiler command and arguments string, in NetBeans Preferences. It may be necessary at some point to add environment and working directory information here, but for now we'll just leave it at the command and arguments.

Save and close the GeewhizPanel class.

Modifying The Compiler Class

Now we need to change our PrologCompiler class to use the NbPreferences we created in the Options panel. I went through several iterations of changes and testing with this class, and here is the final version (as if any programming code was ever final). Note: if you've made any changes to the class yourself from the version we created earlier, you should save your old version of PrologCompiler.java prior to making these changes. Whenever you're ready, change the class definition to the one listed below:

public class PrologCompiler {
    private DataObject dataObject;
    private String fileName;
    private String compilerName;
    private String compilerArgs;
    
    public PrologCompiler() {
        Preferences pref;
        
        this.dataObject = null;
        pref = NbPreferences.forModule(GeewhizPanel.class);
        this.compilerName = pref.get("compilerName", "");
        this.compilerArgs = pref.get("compilerArgs", "");
        
        pref.addPreferenceChangeListener(new PreferenceChangeListener() {
            public void preferenceChange(PreferenceChangeEvent evt) {
                if (evt.getKey().equals("compilerName")) {
                    compilerName = (evt.getNewValue());
                } else if (evt.getKey().equals("compilerArgs")) {
                    compilerArgs = (evt.getNewValue());
                }
            }
        });
    }
    
    public void compileDataObject(DataObject dObj) {
        ProcessBuilder procBuilder;
        Process process;
        List<String> cmd;
        Map<String, String> env;
        String line;
        InputOutput io;
        OutputWriter outputWriter;
        SaveCookie sCookie;

        
        // set DataObject and file name
        this.dataObject = dObj;
        File file = FileUtil.toFile(dObj.getPrimaryFile());
        this.fileName = file.getAbsolutePath();
        
        // save file first if it's been modified
        sCookie = dObj.getCookie (SaveCookie.class);
        if (sCookie != null) {
            try {
                sCookie.save();
                StatusDisplayer.getDefault().setStatusText("Save finished");
            } catch (IOException ex) {
                Exceptions.printStackTrace(ex);
            }
        }
        
        // get an output window tab
        io = IOProvider.getDefault().getIO("Prolog", false);
        io.select();
        outputWriter = io.getOut();

        // first see if we have a compiler available
        if (this.compilerName.isEmpty()) {
            outputWriter.println("You need to set up the compiler first.");
            outputWriter.print("In the main menu go to 'Tools / Options");
            outputWriter.println("/ Miscellaneous / Prolog'.");
            whiteLines(outputWriter);
            outputWriter.close();
            return;
        }

        // construct the SWI Prolog process command
        cmd = new ArrayList<String>();
        cmd.add(this.compilerName);
        cmd.add(this.compilerArgs);
        cmd.add(fileName);
        
        procBuilder = new ProcessBuilder(cmd);
        procBuilder.redirectErrorStream(true);
        try {
            process = procBuilder.start();
            InputStream is = process.getInputStream();
            InputStreamReader isr = new InputStreamReader(is);
            BufferedReader br = new BufferedReader(isr);
            // TODO: might want to clear the output window first...
            outputWriter.printf("Output of running %s is:\n\n",
                        commandString(cmd));
            while ((line = br.readLine()) != null) {
                if (lineIsNotable(line)) {
                    outputWriter.println(line, listener);
                } else {
                    outputWriter.println(line);
                }
            }
        } catch (IOException ex) {
            outputWriter.print("Error occurred running Prolog compiler. ");
            outputWriter.println("Check options.");
            outputWriter.print("In the main menu go to 'Tools / Options");
            outputWriter.println("/ Miscellaneous / Prolog'.");
            outputWriter.printf("Command string is %s.\n", commandString(cmd));
     //       Exceptions.printStackTrace(ex);
        } finally {
            whiteLines(outputWriter);
            outputWriter.close();
        }
    }

    private OutputListener listener = new OutputListener() {
        public void outputLineAction(OutputEvent ev) {
            String outputLine;
            Line editorLine;
            LineCookie lCookie;
            int lineNumber;
            int columnNumber;
            
            outputLine = ev.getLine();
            lineNumber = parseLineNumber(outputLine);
            columnNumber = parseColumnNumber(outputLine);
            lCookie = dataObject.getCookie (LineCookie.class);
            editorLine = lCookie.getLineSet ().getOriginal (lineNumber-1);
            editorLine.show (Line.SHOW_GOTO, columnNumber);

            StatusDisplayer.getDefault().setStatusText("Fix me!");
        }
        public void outputLineSelected(OutputEvent ev) {
            // Let's not do anything special.
        }
        public void outputLineCleared(OutputEvent ev) {
            // Leave it blank, no state to remove.
        }

    };

    
    private boolean lineIsNotable(String line) {
        boolean result = false;
        
        if (line.startsWith("Warning:") || line.startsWith("ERROR:")) {
            result = true;
        }
        return result;
    }
    
/*
 * SAMPLE SWI PROLOG LINES:
ERROR: /home/.../sieve.pro:16:0: Syntax error: Operator expected
Warning: (/home/.../sieve.pro:18): Singleton variables: [P]
*/
    
    private int parseLineNumber(String line) {
        int fpos;
        int startpos;
        int lineNumber;
        Character ch;
        StringBuffer numBuf;
        
        fpos = line.indexOf(this.fileName);
        // assuming there are no colons in file name!
        startpos = line.indexOf(":", fpos);
        if (startpos == -1) {
            // lineNumber is converted to lineNumber - 1
            //     this causes an exception in caller if this is 0
            //     so return 1 instead
            return 1;
        }
        numBuf = new StringBuffer();
        for (int i = startpos+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                numBuf.append(ch);
            } else {
                break;
            }
        }
        lineNumber = Integer.parseInt(numBuf.toString());
        return lineNumber;
    }
    
    private int parseColumnNumber(String line) {
        int fpos;
        int startpos;
        int colNumber;
        Character ch;
        StringBuffer numBuf;
        int colstart = -1;
        
        fpos = line.indexOf(this.fileName);
        // assuming there are no colons in file name!
        startpos = line.indexOf(":", fpos);
        if (startpos == -1) {
            return 0;
        }
        for (int i = startpos+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                // skip line number
            } else {
                colstart = i;
                break;
            }
        }
        if ((colstart == -1) || (line.charAt(colstart) != ':')) {
            return 0;
        }
        numBuf = new StringBuffer();
        for (int i = colstart+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                numBuf.append(ch);
            } else {
                break;
            }
        }
        colNumber = Integer.parseInt(numBuf.toString());
        return colNumber;
    }
    
    private void whiteLines(OutputWriter ow) {
        final int limit = 3;
        
        for(int i = 0; i < limit; i++) {
            ow.println();
        }
    }
    
    private String commandString(List<String> cmds) {
        StringBuffer sBuf;
        
        sBuf = new StringBuffer();
        for (String cmd : cmds) {
            sBuf.append(cmd);
            sBuf.append(' ');
        }
        // leave extra space on the end
        return sBuf.toString();
    }
}

Actually, rather a lot has changed. Notice in the constructor that we are now getting the compiler command and arguments from NbPreferences and starting a listener to see if they change. Actually, the listener may be overkill for this application but as I mentioned above we're trying to be better NetBeans citizens so let's leave it in just in case we have a very quick typist on our hands.

Also notice that now we are checking for a SaveCookie before we start the compilation. If one exists, and it will if our source file has been modified since the last save, we grab it and use it to save the file prior to compiling it. I love how easy that is in NetBeans. We follow the NetBeans Java example of not asking prior to doing the save; we just go ahead and do it.

Note that we also are adding a couple helper methods to clean up our code (and the output) a little bit. White space rocks. And we're adding more cleanup -- we are finally closing the OutputWriter in our class.

Since we opened up the compiler command and arguments to user input, now we have to do some reality checks on the data prior to using it. First we check to make sure the NbPreference is there for the compiler command and issue an error if it is not. (The command arguments should be optional.) The compiler command will not be there if the user has not set up the compiler in our new options panel so we firmly order her/him to go to the options panel and set it up right the hell now. Hmph. The nerve.

We also changed the try/catch for the compiler invocation, since now we're executing whatever the user typed in for a command and arguments. Instead of doing a stack trace we're issuing an error message in the catch, since

is not considered good user feedback in most circles. Never mind how I got the screenshot, why do you think I changed it? Of course I left the stack trace in place but commented out, since no good Java programmer feels completely comfortable about a catch statement without a stack trace laying around somewhere.

I think that about covers the changes. Let's try it out. But before we do that, you might want to grab a new PrologAST from the archive to this article. I modified it to not print all the debugging information unless a constant is set, and if printing is requested to not keep the OutputWriter tied up quite so long. Good citizenship again, but not worth including the source code in this article.

Testing The Option Panel And The Compiler

You know the drill -- clean and build the GeeWhiz project then install it to the target IDE. Don't go into the options menu yet. Open up the "Algorithms" project (!) and open sieve.pro. Try to compile it with the menu bar button. You should get an error.

Next, from the main menu, select "Tools" "Options", then click the "Miscellaneous" tab then the "Prolog" tab.

Our options panel should appear with the default values from our load statements in GeewhizPanel. Click "OK". Now try compiling sieve.pro again. You should get a normal compilation.

Now go back into our option panel and change the values to something invalid for your compiler and platform, like :

Click "OK" to save them, then try compiling again. You should get an error.

You don't need to change the options back since they'll go away once the target IDE is destroyed in our clean and build. However, before you quit testing you should make sure you can still create a diagram with the modified PrologAST class without printing any text in the Prolog output tab if you installed the class from this article's archives. Then you can quit.

So now GeeWhiz is back to being platform- and compiler-independent and it's a little easier on the NetBeans enviroment. Now maybe we can all go get some sleep. Next time we'll create a NetBeans module (NBM) file for sharing with others, a fairly trivial task, and sum up what we've accomplished so far. Zzzzzz....

Files From This Entry

GeeWhiz Prolog - Part Six - Creating Prolog Projects

nospam@example.com (Hulles) — Thu, 22 May 2008 13:45:23 +0200

This is Part Six, the seventh part of a series of entries describing an implementation of the Prolog language in the NetBeans IDE.
Part Zero, "About The Project," is here.
Part One, "Before We Start," is here.
Part Two, "Creating A File Type," is here.
Part Three, "Adding Language Support," is here.
Part Four, "A Visual Prolog Modeler" is here.
Part Five, "Adding The Compiler" is here.

What We'll Be Doing

So far we've cobbled together a pretty decent Prolog IDE within the NetBeans environment. As far as features, it has... well, you can review the previous articles in the series yourself but it has a lot of Cool Stuff. Now we're going to create a new project template so when you want to start working on a new Prolog project you don't have to call it a Java class library or a web application just to be able to create new Prolog source files.

Create A New Project Template

First we need to create a sample project to use in the new project template wizard. This project should have what just what we need when we start a new Prolog project and no more. Since we're only working with text source files, that's pretty much all the project needs. We'll just copy one source file into the project since both Nature and Hulles abhor a vacuum. In the main menu, select "File" "New Project" and create yourself a new Java class library project called, appropriately enough, "NewProject".

Find a copy of sieve.pro in your target IDE directory and copy it into the src folder of NewProject. If you would prefer, you can extract a copy from the archive files at the end of this article.

Now we're going to pare down the project as much as we can, which isn't much at this point. Right-click on NewProject and select "Properties". In "Categories" select "Libraries", then click the "Compile Tests" tab. Delete the test libraries that are there.

Click "OK" to close the properties window. Now we have a simple project we can use as a base for creating new Prolog projects. Time to create our new project template. Right-click the GeeWhiz project and select "New" "Project Template...". In the first screen of the wizard select "NewProject".

Click "Next". On the next screen of the wizard, enter "NewProject" for the template name, "Prolog Application" for the display name, select "Other" for the category, and make sure the package is correctly filled in.

Once everything is correct, click "Finish".

Now we're going to customize our new project template a little bit. Edit "NewProjectDescription.html" and change the description to simply "Prolog project".

Save and close the file. Open the layer.xml file and traverse "this layer" down to "Templates" "Project" "Other".

Right-click on "Prolog Application" and select "Pick Icon...". Navigate to your package source folder and select "prolog-star.png", the dreaded Black Star of Prolog.

Click "OK" and you're done. You can now delete the "NewProject" project because we won't need it anymore. The necessary stuff from "NewProject" was zipped into our "GeeWhiz" project by the new project template wizard.

Testing The New Template

Our new Prolog project template should now be ready to test. Clean and build your main project and install it to the Target IDE. Once your "personal domain" is created, in the main menu select "File" "New Project" and you should see our new Prolog project option, complete with BSofP icon.

Select "Prolog Application" and fill in the necessary fields, calling your new project "Algorithms" in honor of our two hard-working sample Prolog programs, fib1.pro and sieve.pro.

Check out "Algorithms" and note that "sieve.pro" is include in the default package of our new project. If you want to be really loyal, copy fib1.pro into our new project and delete the "BraveNewWorld" project since we won't need it anymore.

While we're here, note also that there is a disturbing Java coffee cup icon on our new Prolog project. There is a way to change that, but that procedure is beyond the scope of this how-to series. This is because I have no idea what the procedure is. If you do, please let me know.

There, wasn't that easy? Now we have a way to create a Prolog project as a home for our precious Prolog source code. Next we'll do some housework in GeeWhiz and make it a "good NetBeans IDE citizen" (or at least a better one). In the process we'll make GeeWhiz Prolog platform- and compiler-independent once again. (It was until the last entry when we added the compiler.) Until next time.

Files From This Entry

GeeWhiz Prolog - Part Five - Adding The Compiler

nospam@example.com (Hulles) — Wed, 21 May 2008 20:46:21 +0200

This is Part Five, the sixth part of a series of entries describing an implementation of the Prolog language in the NetBeans IDE.
Part Zero, "About The Project," is here.
Part One, "Before We Start," is here.
Part Two, "Creating A File Type," is here.
Part Three, "Adding Language Support," is here.
Part Four, "A Visual Prolog Modeler" is here.

What We'll Be Doing

Up to this point we've created a Prolog editor within the NetBeans IDE with built-in syntax highlighting, navigation, a visual modeler, and some other stuff that I forget but that's probably pretty cool. Now we're going to add in-place compilation so we don't need to switch between NetBeans and whatever Prolog compiler we're using just to fix syntax errors and such.

In this entry I'll be using SWI Prolog as my Prolog compiler. It's a free, robust open-source compiler that runs on multiple platforms including, probably, yours. One thing it does not have, however, is a feature-rich IDE -- hence this project. When we're done with this segment, we'll be able to compile our Prolog source code directly from the NetBeans IDE and hotlink (whatever that means) the error lines back to our source code. In other words, it will function much like the Java compilation process within NetBeans that we all know and love.

By the way, if you currently use a different Prolog compiler, don't worry. Once we're done here it should be pretty obvious how to adapt this project to incorporate your favorite compiler as long as you can run it from a terminal command line. In fact part of the reason I'm writing this how-to is to allow you to adapt ANY language to the NetBeans IDE. I'm trying to assemble the knowledge that's scattered around the NetBeans universe in one place so that this series of articles gives you the ability to quickly and dirtily add your favorite language to the NetBeans IDE. We'll work on the "dirtily" part later; for now our goal is results, baby.

Adding Compiler Support

Adding compiler support to GeeWhiz turns out to be surprisingly easy. It's easy if you know where to look for info, that is. It took me for-effing-ever to find the information I needed to do this, but once I did, implementing support for an external compiler turned out to be almost trivial. But I digress. The first thing we need to do is create an action in our project to invoke the compiler. Right-click on our GeeWhiz project and select "New" "Action".

In the first screen of the New Action Wizard, once again select "Conditionally Enabled" and "User Selects One Node". Set the cookie class to "DataObject" since we want to only compile Prolog source files with our compiler. Hit the "Next" button.

On this wizard screen select "File" for a category (just for something different; we chose "Other" for our "ShowDiagram" action). (I've always wondered why it takes so long for this window to come up on my machine. I suspect that this is the place where NetBeans is sending encrypted information about my unspeakable habits to our shadowy overlords.) Uncheck "Global Menu Item" and check "Global Toolbar Button" (again, for something different). We're going to stick our toolbar button at the very end of the Build toolbar so select "Build" for the toolbar and "Profile Main Project... - HERE" as the position. Click "Next".

On this screen, enter "CompileProlog" for a class name and "Compile Prolog Program" for a display name. For icons, you'll need both a 16x16 and 24x24 icon in the same directory, called (in our case) compile16.png and compile24.png, otherwise the wizard will grumpily issue error messages until you do. You can use these if you'd like, another modified Black Star of Prolog. Right-click on them in your browser and save them to a directory that is not your project directory and let the wizard copy them. Fill in the path and file name of the 16x16 icon in the icon field in the wizard. Make sure your package node ("org.myorg.geewhiz") is filled in in the package field and click "Finish".

Note: in the last screenshot ignore the GeeWhiz2 reference. I didn't make screenshots of this process the first time around, probably because I didn't expect it to work the first time! I thought I'd have to do 8 or 9 trials to get it right like I did for the other stuff in this project. Gee whiz, I must be learning something....

Once the wizard creates our new action, you can close the icon files in the editor and add the following lines to the CompileProlog class, where it says "TODO: use DataObject":

        PrologCompiler compiler = new PrologCompiler();
        compiler.compileDataObject(dataObject);

Save and close the file. Great. We have a toolbar action, now all we need to do is write a PrologCompiler class. So let's do that.

Create a new Java class called "PrologCompiler" and replace the empty class with:

public class PrologCompiler {
    DataObject dataObject;
    String fileName;
    
    public PrologCompiler() {
        this.dataObject = null;
    }
    
    public void compileDataObject(DataObject dObj) {
        ProcessBuilder procBuilder;
        Process process;
        Map<String, String> env;
//        File currDir;
        List<String> cmd;
        String line;
        InputOutput io;
        OutputWriter outputWriter;

        // TODO: should save file first if it's been modified
        
        // set DataObject and file name
        this.dataObject = dObj;
        File file = FileUtil.toFile(dObj.getPrimaryFile());
        fileName = file.getAbsolutePath();
        
        // get an output window tab
        io = IOProvider.getDefault().getIO("Prolog", false);
        io.select();
        outputWriter = io.getOut();

        // construct the SWI Prolog process command
        cmd = new ArrayList<String>();
        cmd.add("swipl");
        cmd.add("-c");
        cmd.add(fileName);
        
        procBuilder = new ProcessBuilder(cmd);
        procBuilder.redirectErrorStream(true);
        // also s/b able to merge it into OutputWriter
//        env = procBuilder.environment();
//        env.put("VAR1", "myValue");
//        env.remove("OTHERVAR");
//        env.put("VAR2", env.get("VAR1") + "suffix");
//        currDir = procBuilder.directory();
//        if (currDir != null) {
//            System.out.printf("Current directory is %s.", currDir.toString());
//        }
//        procBuilder.directory(new File("myDir"));
        try {
            process = procBuilder.start();
            InputStream is = process.getInputStream();
            InputStreamReader isr = new InputStreamReader(is);
            BufferedReader br = new BufferedReader(isr);
            // TODO: might want to clear the output window first...
            outputWriter.printf("Output of running %s is:\n\n", cmd.toString());
            while ((line = br.readLine()) != null) {
                outputWriter.println(line);
            }
            // TODO: close outputwriter
        } catch (IOException ex) {
            Exceptions.printStackTrace(ex);
        }
    }
}

What we want this to do is invoke the SWI Prolog compiler with our source file, the name of which we retrieved from our trusty Prolog DataObject. We're using the IOProvider/OutputWriter we saw last time to write the output to the Output tab, just like a real adult language module does. We're also using ProcessBuilder to build a Process so we can execute an external command.

Just a couple of other things worth mentioning about the above class: one is that I left in some comments showing how to access the environment and change the working directory, just in case you need the info to make your compiler work. Also, note that the command line I used is for the Linux version of SWI Prolog. If you run on another platform, you'll probably need to change this. For example, I believe Windows uses "plwin". See the SWI Prolog site for more information.

Testing The First Version

So let's try it: clean and build your main project and install to the target IDE. Open up the BraveNewWorld project. Wait until the excitement dies down. Open up sieve.pro. Add a line somewhere in the program that says:

	gruesome(ugly error).

This introduces an error in our otherwise nearly pristine Prolog program. Save sieve.pro. Find our new compiler button on the toolbar and click it.

At this point my original notes say "holy shit it worked!" As indeed it did, the first time. Nothing works the first time, ever. Imagine my elation. If you look at the "Prolog" output tab (!), you'll see the gruesome ugly error we introduced does indeed give us an error in the compiler output. Also note in passing that our syntax parser did flag our gruesome ugly error statement as an error. Heh heh.

The compiler also gives us a warning that there is a singleton variable in one of the clauses. This means that the variable "P" in the statement "remove(P,[],[])." isn't used. In Prolog, instead of using a named variable here you should use an anonymous variable, the underscore. If you want you can change the statement to read "remove(_,[],[])." and recompile it to see that the warning goes away. When you're done muttering "Gee whiz!" you can close the target IDE.

Add Hotlinks (Whatever They Are)

Now we're going to add hyperlinks to our compiler output so when you click an error line in the output you are magically transported to the source code at the point of the error. I know, you're saying "Gee whiz!" to yourself again. Just wait....

In trying to add this feature, I knew exactly what I wanted to do but I really wasn't sure how to accomplish it. Until, that is, I found an article called "Meet A NetBeans Module Writer: Jens Trapp". In the article is a code snippet that does exactly what I wanted to do in about three lines of code! Thank you Mr. Trapp; may the rest of your days be happy ones. Who knew there was a LineCookie that plunked you right down in the middle of the source code editor? Probably the people who RTFD, that's who.... But for the rest of us there's Hulles.

So now we're going to change our PrologCompiler class to "hotlink" our compiler code to our source code. Open the class file and replace the class with this:

public class PrologCompiler {
    DataObject dataObject;
    String fileName;
    
    public PrologCompiler() {
        this.dataObject = null;
    }
    
    public void compileDataObject(DataObject dObj) {
        ProcessBuilder procBuilder;
        Process process;
        Map<String, String> env;
        List<String> cmd;
        String line;
        InputOutput io;
        OutputWriter outputWriter;

        // TODO: should save file first if it's been modified
        
        // set DataObject and file name
        this.dataObject = dObj;
        File file = FileUtil.toFile(dObj.getPrimaryFile());
        fileName = file.getAbsolutePath();
        
        // get an output window tab
        io = IOProvider.getDefault().getIO("Prolog", false);
        io.select();
        outputWriter = io.getOut();

        // construct the SWI Prolog process command
        cmd = new ArrayList<String>();
        cmd.add("swipl");
        cmd.add("-c");
        cmd.add(fileName);
        
        procBuilder = new ProcessBuilder(cmd);
        procBuilder.redirectErrorStream(true);
        // also s/b able to merge it into OutputWriter
        try {
            process = procBuilder.start();
            InputStream is = process.getInputStream();
            InputStreamReader isr = new InputStreamReader(is);
            BufferedReader br = new BufferedReader(isr);
            // TODO: might want to clear the output window first...
            outputWriter.printf("Output of running %s is:\n\n", cmd.toString());
            while ((line = br.readLine()) != null) {
                if (lineIsNotable(line)) {
                    outputWriter.println(line, listener);
                } else {
                    outputWriter.println(line);
                }
            }
            // TODO: close outputwriter
        } catch (IOException ex) {
            Exceptions.printStackTrace(ex);
        }
    }

    private OutputListener listener = new OutputListener() {
        public void outputLineAction(OutputEvent ev) {
            String outputLine;
            Line editorLine;
            LineCookie lCookie;
            int lineNumber;
            int columnNumber;
            
            outputLine = ev.getLine();
            lineNumber = parseLineNumber(outputLine);
            columnNumber = parseColumnNumber(outputLine);
//          System.out.printf("Showing line %d column %d.\n", 
//                      lineNumber, columnNumber);
            lCookie = (LineCookie) dataObject.getCookie (LineCookie.class);
            editorLine = lCookie.getLineSet ().getOriginal (lineNumber-1);
            editorLine.show (Line.SHOW_GOTO, columnNumber);

            StatusDisplayer.getDefault().setStatusText("Fix me!");
        }
        public void outputLineSelected(OutputEvent ev) {
            // Let's not do anything special.
        }
        public void outputLineCleared(OutputEvent ev) {
            // Leave it blank, no state to remove.
        }

    };
    
    private boolean lineIsNotable(String line) {
        boolean result = false;
        
        if (line.startsWith("Warning:") || line.startsWith("ERROR:")) {
            result = true;
        }
        return result;
    }
    
/*
SAMPLE SWI PROLOG ERROR AND WARNING LINES:
ERROR: /home/.../bravenewworld/sieve.pro:16:0: Syntax error: Operator expected
Warning: (/home/.../bravenewworld/sieve.pro:18): Singleton variables: [P]
*/
    
    private int parseLineNumber(String line) {
        int fpos;
        int startpos;
        int lineNumber;
        Character ch;
        StringBuffer numBuf;
        
        fpos = line.indexOf(this.fileName);
		// assumes there are no colons in file name!
        startpos = line.indexOf(":", fpos);
        if (startpos == -1) {
            return 1;
	// in caller, lineNumber is converted to lineNumber - 1,
	//    this causes an exception if this is 0
        }
        numBuf = new StringBuffer();
        for (int i = startpos+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                numBuf.append(ch);
            } else {
                break;
            }
        }
        lineNumber = Integer.parseInt(numBuf.toString());
        return lineNumber;
    }
    
    private int parseColumnNumber(String line) {
        int fpos;
        int startpos;
        int colNumber;
        Character ch;
        StringBuffer numBuf;
        int colstart = -1;
        
        fpos = line.indexOf(this.fileName);
		// assumes there are no colons in file name!
        startpos = line.indexOf(":", fpos); 
        if (startpos == -1) {
            return 0;
        }
        for (int i = startpos+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                // skip line number
            } else {
                colstart = i;
                break;
            }
        }
        if ((colstart == -1) || (line.charAt(colstart) != ':')) {
            return 0;
        }
        numBuf = new StringBuffer();
        for (int i = colstart+1; i < line.length(); i++) {
            ch = line.charAt(i);
            if (Character.isDigit(ch)) {
                numBuf.append(ch);
            } else {
                break;
            }
        }
        colNumber = Integer.parseInt(numBuf.toString());
        return colNumber;
    }
}

As you can see, we added an OutputListener that does the work of popping us into the editor at exactly the right place where the error is located. The parsing of the error / warning lines to get the line number and column number is ugly, but that's because A) I didn't want to have to relearn regular expression syntax for the umpteenth time, and B) I didn't have 244 Swiss Francs for the ISO Prolog error message standard so I was winging it from the SWI Prolog output. Actually, there are two ISO Prolog standards documents, so it would have been 488CHF. As if.

I suppose I should also mention the StatusDisplayer line. This is one of those things that I couldn't resist putting in but that gets obnoxious very quickly. When you go to an error line, it displays "Fix me!" on the status line at the bottom of the IDE. Hah hah. So take it out, you don't like it.

Testing The Final Version

Okay, let's give 'er a spin. Clean and build your project then install it to the target IDE as before. Open up the BraveNewWorld project. Wait. Open up sieve.pro. Unfix the error and the warning if you fixed them last time so we have something to work with. Click our "Compile Prolog" button on the toolbar.

We have hyperlinks! Click on an unlinked (white) line in the Prolog output tab to make that window current. Click on one hyperlink, then the other. Notice how the cursor is moved to the editor window to the line and column where the error occurred. Now leave sieve.pro open and open up fib1.pro. Introduce an error into the code, save it, and compile it with our shiny new button. The error hyperlink from that compile should take you to the error in fib1.pro. Now scroll up the Prolog output window to our first compile and click one of the original hyperlinks. Notice that sieve.pro is reselected and the error position is displayed again. Go ahead, say it, you know you want to: "Gee whiz!"

So now we can compile our little Prolog hearts out in the NetBeans IDE. We still need to open SWI Prolog to run the stuff, but that's not so bad. It should be possible to connect up a Reader in the same way we did with the OutputWriter to allow the interaction, however. Hmmm.... You're welcome to do that if you want. I haven't yet, but I'm sure it's only a matter of time before I have to try it. If you do, let me know how it comes out.

We now have a pretty decent Prolog IDE embedded within the NetBeans architecture. What's next? We're going to create a Prolog project template so we don't have to stick our lovely, elegant and erudite nonprocedural Prolog source code into an icky stinky Java class library, that's what's next. Stay tuned.