FregIDE Tutorial

Note: this page is partly out of date, meanwhile. Please use the tutorial at github.

Introduction

The Eclipse plugin that supports Frege is called fregIDE. Don't ask how to pronounce that!

Currently, the following is supported:
  • Enabling a project to use the Frege Builder. 
  • Frege preferences 
  • Syntax coloring 
  • Outline view
  • Mouse-Over Documentation
  • Mouse-Over Left-Ctrl Navigation
  • Live error markers in the editor 
  • Project builder, i.e. compilation of Frege files 
  • Compilation populates the problem view with errors, warnings and hints and the editor with persistent markers.
  • Editor Actions for inserting non ASCII characters
  • A "Compile" button.
  • Content proposals 
Prerequisites

Currently, the following is required to use fregIDE
  • a Java Runtime Environment 1.7 
  • Eclipse 3.7 (Indigo) (more recent versions should be ok)
Eclipse should have the following VM settings:

-Xmx512m -Xss4m -XX:MaxPermSize=128M

For more information see the Eclipse FAQ 
Small tests will work without modifying the Eclipse settings, however, for source files with hundreds of lines it is better to be generous here.

Installation

  • Download the latest version of fregIDE3.xx.vvv.zip labelled Featured from the download page.
  • Start up Eclipse, open the preferences window and select the Install/Update category. In the page  Available Software Sites add the IMP Update Site http://download.eclipse.org/technology/imp/updates/
Adding the IMP Update Site
  • Open the installation page and add the fregIDE Zip as local archive.  Turn off the check box Group items by category. Select the Functional Programming with Frege feature and click Next>

Ready to start installation
  • Confirm the following dialogs. Eventually the following dialog appears:
  • Choose Restart Now to complete the installation.
Update
An update to a new version works like an installation, but there are a few more activities needed:

  • In existing projects, remove the old JAR from the build path (in the project explorer). You can add the new JAR by enabling the Frege Builder (see below) again.
  • It is recommended to perform a clean build because already compiled code could have library references that are no longer valid. This would manifest itself at runtime with ClassNotFound or MethodNotFound exceptions. The malicious JVM could even run your program  partly, because certain references will not be resolved until they are actually used.

Preferences
When Eclipse is back again, take a look at the Frege preferences page:

Editor font and syntax colors can be customized to your liking.

The syntax coloring will make use of information about identifiers gathered by name resolution. First, the identifiers are categorized as names of types, name spaces, data constructors and variables (functions and values). Type, constructor and variable names can origin in the current package or they can be foreign ones made available by an import from another module. Variables that are not imported are either globally visible (top level declarations), or they are local bindings.
You can decide to set namespace names visually apart by displaying them in bold face. Likewise, imported names can be shown in italics. Depending on the settings made here, imported variables can be shown in a different color than top level variables defined in the current source file and in a different color than local bindings. Local bindings are always shown in the standard black color.

Set up a Project for Frege
It is now time to start a project. Specifically, we need a Java Project where we can hook up Frege support. This is due to the Build and Run support that comes with Java Projects, but not with plain Projects.
The Wizard demands only entry of a project name. For the sake of this tutorial, we create a java project named Hello.
After clicking finish, the new project is visible in the package explorer. (If the package explorer is not visible, make sure to open the Java Perspective.) To add Frege Build support to the project, right click the project name and select Enable Frege Builder.


Write Source Code
Now we can open a Frege source file and edit it. Let's call the file World.fr
The correct file extension .fr is crucial for letting Eclipse recognize it automatically as Frege file.


After clicking finish, an editor window for World.fr will open. This is a good opportunity to do one last setting: by default, the Eclipse text editors will not replace tabulator characters with spaces. It is strongly recommended to change this to avoid mysterious indentation problems with layout. For this, right-click in the editor area, select Preferences ... from the context menu and check the "Insert spaces for tabs" option in the Text Editors preferences dialog. You may also customize the number of spaces inserted.

The next picture shows the state after having typed a bit of source code:



During typing, error markers appear and disappear in the left margin and items change colors. For example, after the block comment opening sequence has been typed, it turned all red to indicate a not yet finished lexical construct. The same will happen when one types quoted constructs like string constants while the ending delimiter is missing.
On every character typed and a short delay, a sequence of compiler passes will be run up to and including type checking - unless the process is cancelled through typing the next character or an error is found. In the latter case, subsequent passes will not run (as usual), but the errors will be indicated in the left margin and through underlining of the tokens that are most likely the cause of the error. In the screen shot above, the word prinltn is underlined and when moving the mouse over the squiggly line a tool tip with the message can't resolve ` prinltn` , do you mean ` println` instead? is displayed. Indeed! After correction and completion, the screen looks like this: 
    There are no error markers anymore and this means that the program passed the type check. 
    By the way: usually, you'll type faster than the process of parsing, name resolution, type checking and syntax coloring takes. In such cases, you'll notice that what you just typed appears in all grey or that the coloring disappears in the visible portion of the text following your insertion point. This is not a problem, the IDE will catch up as soon as you pause for 1 or 2 seconds.
    We can now compile the program by saving the file with CTRL-S.  A second later the compilation is done, but now a warning appears in the Problem view:
    This is the compiler's way to tell us that we have forgotten to consider the case that no arguments at all may be given to main. We will of course correct that later, but right now we can't wait to see how our program runs. For this, we need a Run Configuration in Eclipse parlance.  The procedure to follow is now the same like in a normal java project. After all, programming in Frege can be seen as  just another way to write Java programs. In fact, you can find the java file generated by the frege builder in the bin directory of the project (this is not visible in the project explorer, to see it one needs to open the Navigator view). This java file was then compiled by the eclipse compiler just like in any java project. The run configuration wizard is available from the Run menu.
    The icon to create a new configuration of the selected type is in the row over the selection list on the left, which is a bit counter-intuitive at first sight. (When I first visited this wizard, it took some time before I recognized that there is not a Next> button like in other wizards ...)
    The name will be used to identify the various run configurations. The project can be found via the Browse button, but it wont find our main class automatically for some reason. The name to type here is exactly the (case sensitive!) Frege module name which is  World in our case.
    Now, if we Apply and Run, the followoing will happen:
    frege.RT$NoMatch is the exception thrown when a pattern match fails and it happened at line 9. (The compiler did warn us, didn't he?)
    We better specify an argument so that main does not get an empty list. Back to run configurations and to the Arguments tab:
    Running this one should produce a console output like in the following screen shot. The picture also shows the corrected source code without any warnings anymore.

    Outline View
    From version 3.19.9 on, the outline view will be populated. You can choose to sort the items alphabetically, the default is to show them in the order they are defined within their category (classes, instances, type aliases, data types, functions & values). A click on an item takes you to the line in the source code where it is defined. For variables, functions and constructors, the type is shown.

    Mouse-Over Documentation
    Move the mouse to any identifier in your code.
    An instant later,  a window with information will appear that contains type and documentation, if any available for the item in question.

    Bold parts in function types indicate that the function is strict in that argument.

    This works also for let, lambda and case bound items. Note that let bound items that are used only once will often have been inlined, so no information may be available and the type is shown as t-1.

    Mouse-Over Navigation
    When the mouse is moved over an identifier, press the left Ctrl key. When the source code of the module this identifier is defined in is available in the workspace, the indentifier  will appear blue and  underlined. Now a left click of the mouse activates the editor (or opens a new editor) with the definition of the item, and the cursor is set to the definition.
    This works, of course, also with identifiers from the active editor, even with locals (i.e. with names bound in lets, lambdas or case alternatives).
    If a new editor must be opened, the source code will be parsed and type-checked. This make take a few seconds on larger source files.
    To be able to jump also to library code, there is a library source ZIP file in the download area. Download the one whose release number matches the one of the fregIDE. Create an empty frege project dedicated just for this purpose and unpack the ZIP file below the src directory of that project. Then refresh the src directory in fregIDE.

    Now you will be able to navigate to any library function from any project in the same workspace.
    (If you have automatic build on, the builder will probably build the library once. It doesn't matter.)

    If the versions of the source library and the fregIDE do not match, or if you change the sources, the navigation will be inexact. The correct sources can be re-installed anytime, though.

    Both Mouse-Over features work best when the source code did survive the type check at least once. An indication for this is when there are no error markers, the outline view is populated and the source code is correctly syntax-colored. When more code is added, and there are type errors or name resolution errors, the features may not work on certain parts of the code. It will resume to work as soon as the errors are corrected.

    Editor Actions
    There is a Frege sub-menu in the editor context menu that contains some actions: One acts like a key that inserts the function composition operator. The second encloses the selected text with grave accent marks to form a regular expression literal, or inserts just two grave accent marks. The third encloses the selected text with back-ticks, to form an operator. This is for convenience, as not all keyboards have the required keys, or the keys are not easily accessible, or are mapped differently.

    The "Compile" button tells the builder to compile the current file, irrespective of any build settings. Be sure to save the file before doing this.

    The buttons are also available from the toolbar when a frege editor is active and will help people to use those non-ASCII symbols. (Be sure to have set up your Eclipse workspace to use UTF-8 encoding for text files. This can be done in the Window -> Preferences -> Workspace preferences dialog.)

    Content Proposals

    Recently, we have added content proposals. Please read the tutorial dedicated to this feature.


    This conlcudes the short introduction to fregIDE. Further features and how to use them will be added as soon as they are implemented.





    No comments:

    Post a Comment

    Comments will be censored by me as I see fit, most likely if they contain insults or propaganda for ideologies I do not like. Comments that are on topic will not be censored. If I leave a comment uncensored this does not imply that I agree with the opinions expressed therein.