New web interface

In addition to the console UIs, we also maintain a browser based (remote, via HTTP) interface to the tool, which provides an even more convenient way for code grokking. The main features of the web interface are:

• Running and exploring semantic queries (both normal and context-sensitive queries)
• Prev-next style browsing of query results
• Query construct assistant (auto-complete)
• Persistent queries
• Management of (possibly multiple) running queries
• Database operations
• Ability to mark files with error forms
• Dependency examinations

Note that JavaScript must be enabled in the browser to be able to use this interface.

Installation

The web based UI is built upon the ​Yaws web server. To be able to start this interface you need a Yaws web server installed. Installation help: ​http://yaws.hyber.org/yaws.pdf (see Chapter 2).

• Recommended version: 1.92
• Required version: 1.89 or higher.

If you prefer using the 1.89 version of yaws, please use the -yaws_189 option during compilation:

bin/referl -build tool -yaws_189 

If Erlang/OTP-R16B01 is used, then none of the Yaws versions will be compiled from source. The problem is that every Erlang source of Yaws is compiled with the -Werror flag which causes build error when used with Erlang/OTP-R16B01 to compile Yaws.

To fix this error, you should use this modified Makefile. Put this Makefile under the src directory of the downloaded sources of Yaws-1.96, then execute make clean. After the execution, the standard build procedure should be followed which is shown in LocalInstallLinux page.

If Windows is used, then other opportunity exists. Use the installer binaries of different Yaws versions (Yaws-1.92 - Yaws-1.96) instead of compiling them from source.

For a step-by-step installation tutorial, which is including the installation guide of Yaws, please see LocalInstallLinux.

Starting up

We can start the server either with the referl script using the -web2 option, or from a running RefactorErl shell. Both cases provide a default configuration: server name localhost, port 8001, and address 127.0.0.1., which can be overridden.

Possible options:

• yaws_path YPATH

The absolute location of your Yaws ebin directory.

• yaws_listen YLISTEN

Valid IP address, which Yaws will listen to.

• yaws_name YNAME

Valid domain name, which Yaws will be bound to.

• yaws_port YPORT

Valid port number, which Yaws will be bound to.

• browser_root BROOT

The web interface allows database operations. The root directory for those operations can be set with this parameter.

• images_dir IDIR

Path of the directory where the generated images (visualisation of dependency examinations) will be placed.

• restricted_mode RMODE

If set the interface starts in restricted mode, which means some features are blocked for non-admin users.

Startup: referl script

You can pass any of the above options via command-line arguments (note that -nitrogen is mandatory). Example:

bin/referl -nitrogen 
           -yaws_path /Users/V/yaws-1.89/ebin 
           -yaws_listen 127.0.0.1
           -yaws_port 8000
           -yaws_name localhost
           -browser_root /Users/V/erlang
           -images_dir /Users/V/graph_images
           -restricted_mode

Startup: RefactorErl shell

We have two functions for starting the interface : ri:start_web2/0 and ri:start_web2/1. Without passing any parameters the web server starts up with the default configuration. The 1-arity function allows the interface to be configured using an ​Erlang proplist. Example:

ri:start_web2([
    {yaws_path,"/Users/V/yaws-1.89/ebin"},
    {yaws_listen,"127.0.0.1"},
    {yaws_name, localhost},
    {yaws_port,"8000"},
    {browser_root,"/Users/V/erlang"},
    {images_dir,"/Users/V/graph_images"},
    {restricted_mode,true}]).

Shutting down

You are advised to always log out before shutting down the web server, because the log-out process deletes temporary, dynamically generated components of web pages. If the server has been started from the RefactorErl shell, then ri:stop_web2() should be called in order to shut down the service.

Logging in

In your favourite browser, navigate to the server address defined by the configuration (the default is http://localhost:8001) after the web server has been successfully started. Services are allowed only to authorized people, so first you have to log in with a username. The browser will be redirected to the queries page. If restricted_mode is on, you have to use the username 'admin' to access restricted features, this will require you to provide a password as well. You can set the password with the index:makeadminpassword/1 function, with a string as the parameter.

Global notifications

When someone starts/finishes a modification of the database (e.g. adding files), a notification will appear stating what process has been started/finished. During any modification process most functions on the web interface will not be available. This restriction is global for the whole system. Only things available are:

• Browsing an already completed query's results (if source files were generated previously).
• Browsing files on the server.

For further information, see: Configurable Jobserver

Database operations

This service is available under the "Database" tab. #!comment In restricted mode, this service is not available for non-admin users. It only works correctly if the server process has the appropriate access to files and directories. The file browser panel is located at the left side of the page. You can either browse files which are located on the server ("Browse server"), or which had been loaded into the database ("Browse loaded files"). You can switch between these two options by clicking the button in the top right corner of the file browser box.

Browsing files on the server

The root directory of the browser is an optional configuration parameter. Possible values are:

• If the browser_root parameter is set during start up, the given value is the root directory.
• If the browser_root parameter is not set during start up
• If the database had contained files before start up, the root elements are the directories of these files.
• If the database had not contained files before start up, then RefactorErl’s lib directory will be the root.

In this mode, directories can be listed, the contents of files can be shown, and a selected directory or file can be added to the database. The selected directory or file is highlighted by a blue background. Database operations are indicated by a progress bar.

Searching is possible in both file system files, and loaded files.

Browsing loaded files

In this mode, directories' and files' contents can be listed, a selected file or directory can be reloaded to the database, dropped from the database, or can be pre-generated for the source code viewer. Status messages are displayed during the reloading/dropping/generating process, and also after the process has finished. The file browser displays the last directory that contains all the loaded files.

Dropping a file from the database does not imply removing it from the file system.

Running semantic queries

See Running semantic queries.

Errors

This service is available under the "Errors" tab.

If the database contains file(s) with error form(s), the list of errors will be displayed in a table. Each row in the table shows an error. Clicking the file name shows the file and highlights the position of the error.

If the database does not contain any files with error forms, a "No error" message is displayed.

Dependency examination

See Dependency examinations.

Logging out

You can log out by clicking the "Log out username" button. During the logout process the interface clears the users' session, deletes the dynamically generated images belonging to the user, and redirects the browser to the login page. The interface does not delete the queries executed by the user, nor their results, and also keeps the state of the database.