| 25 | | == Installation == |
| 26 | | To be able to use the web based interface we need to have an already working Yaws webserver. Required version is 1.89. Help for the installation: http://yaws.hyber.org/yaws.pdf (Chapter 2). |
| 27 | | |
| 28 | | == Start up == |
| 29 | | We can start the interface either with {{{referl}}} script with {{{-nitrogen}}} switch, or from !RefactorErl shell. In both cases we get a default configuration with server name {{{localhost}}}, port {{{8001}}}, and IP {{{127.0.0.1.}}} |
| 30 | | |
| 31 | | === Starting up with referl script === |
| 32 | | Parameters to be configured: |
| 33 | | |
| 34 | | * {{{-yaws path YPATH:}}} The absolute location of your Yaws ebin directory. |
| 35 | | * {{{-yaws listen YLISTEN:}}} Valid IP address, which Yaws will listen to. |
| 36 | | * {{{-yaws name YNAME:}}} Valid domain name, which Yaws will be bound to. |
| 37 | | * {{{-yaws port YPORT:}}} Valid port number, which Yaws will be bound to. |
| 38 | | * {{{-browser root BROOT:}}} The web based interface allows database operations. The root directory for those operations can be set, by giving the path of root directory in this parameter. |
| 39 | | * {{{-images dir IDIR:}}} Path of the directory where the generated images, which are the visualisation of the results of dependency examinations, will be written. |
| 40 | | |
| 41 | | Usage of switches is optional, except the {{{-nitrogen}}} switch. |
| 42 | | |
| 43 | | |
| 44 | | Example: |
| 45 | | {{{ |
| 46 | | bin/referl -nitrogen |
| 47 | | -yaws_path /Users/V/yaws-1.89/ebin |
| 48 | | -yaws_listen 127.0.0.1 |
| 49 | | -yaws_port 8000 |
| 50 | | -yaws_name localhost |
| 51 | | -browser_root /Users/V/erlang |
| 52 | | -images_dir /Users/V/graph_images |
| 53 | | }}} |
| 54 | | |
| 55 | | === Starting up from !RefactorErl shell === |
| 56 | | We have 2 functions for starting the interface : {{{ri:start nitrogen/0}}} and {{{ri:start nitrogen/1}}}. If the 0 arity function is used, the interface starts up with default configuration. If the 1 arity function is used the start up can be configured using a prop-list. Available properties are the same as described in the previous section. Usage of switches is optional. |
| 57 | | Example: |
| 58 | | {{{ |
| 59 | | ri:start_nitrogen([ |
| 60 | | {yaws_path,"/Users/V/yaws-1.89/ebin"}, |
| 61 | | {yaws_listen,"127.0.0.1"}, |
| 62 | | {yaws_name, localhost}, |
| 63 | | {yaws_port,"8000"}, |
| 64 | | {browser_root,"/Users/V/erlang"}, |
| 65 | | {images_dir,"/Users/V/graph_images"}]). |
| 66 | | }}} |
| 67 | | == Shutting down == |
| 68 | | It is important to log out, before shutting down the interface, because the log out process will delete the dynamic generated images, which belong to the user. If the interface have been started up from !RefactorErl shell, then {{{ri:stop nitrogen().}}} can be called to shut down the interface. |
| 69 | | == Logging in == |
| 70 | | To log in one must open a browser (recommended: Mozilla Firefox, Google Chrome) and enter the URL defined by the configuration (the default is {{{http://localhost:8001/}}}) after the web server had been started. Usage of services are allowed only to authorized people. First, you have to log in with a username (passwords are not supported yet). The browser will be redirected to {{{queries}}} page. |
| 71 | | == Semantic queries == |
| 72 | | This service is available under ”Queries” menu. |
| 73 | | === Constructing semantic queries === |
| 74 | | The query construct assistant is located at the top-left corner of the page. While typing into the text-box, the interface offers possible continuations for the actual, uncompleted sub-term. The offered option can be chosen from a drop-down list. This auto-complete mechanism helps new !RefactorErl users to use the language, and also all developers to speed up query construction and to avoid constructing wrong queries. |
| 75 | | |
| 76 | | Pressing the ”Run” button evaluates the query and displays the result. |
| 77 | | === Position based queries === |
| 78 | | A file browser is placed at the left side of ’Queries’ page at ’File browser’ tab. One of the previously loaded files can be opened in text view from the file browser panel, by clicking on the magnifying glass icon after selecting a file. By selecting a region or pointing at a position in the text- box, where the contents of the file are loaded in, one can specify the exact position as starting point. Also the result of the previous query can still be reused as a starting point. |
| 79 | | === Node based queries === |
| 80 | | Previously loaded files can also be opened in ''links view'' from the file browser panel, by clicking the link icon after selecting a file. In this view queries can be started from a specific node. You can select a node by clicking on it (only text in bold can be selected). The selected node will be marked with red color. |
| 81 | | [[BR]] |
| 82 | | After selecting a node you can either: |
| 83 | | * Run pre-defined queries for that node from the top-right corner of the screen. |
| 84 | | * Run previously made queries for that node type by selecting one from the ''Choose previous query'' dropdown box. |
| 85 | | * Run a query from the query construct assistant text-box, which will start from that node. |
| 86 | | The first result of the query will be shown (if there was any). Results can be browsed with the appearing ''Prev'' and ''Next'' buttons. The total number of results as well as the currently shown result's number are displayed under those buttons. |
| 87 | | |
| 88 | | ''NOTE: This feature is still under development, and does not support every query. Please use the Position based queries when you need more explicit results.'' |
| 89 | | === Global queries === |
| 90 | | If the ''Global queries'' checkbox is checked, all queries run from the query construct assistant text-box will work as in ''text view'' (and not starting from the selected node). This setting is only important when browsing a file in ''links view'', and a node is currently selected. |
| 91 | | === Alias-able queries === |
| 92 | | We made queries alias-able, cause of named queries can be identified easier, and are more readable for humans, too. |
| 93 | | |
| 94 | | After a query has been successfully run first, it appears at the left side of ’Queries’ page at ’Previous Queries’ tab. |
| 95 | | |
| 96 | | By clicking the corresponding ’E’ button, a text-field appears, which contains the query string. By replacing the query string with the name, what is wanted to assign to the query, and clicking the ’Save’ button the query will be named. After a name has been assigned to the query, the name appears at ’Previous Queries’ tab instead of the query string. If the name of the query should be changed, the same mechanism should be done as described above. |
| 97 | | |
| 98 | | The query string can be shown as an information element by clicking the ’?’ button. |
| 99 | | === Previous Queries === |
| 100 | | For your convenience, the interface stores previously exe- cuted queries and their results, which are listed at the left side of the page at ”Previous Queries” tab. One can choose to list only the queries which belong to the current user, or all the queries stored in the system. |
| 101 | | |
| 102 | | When one of the queries located in the list is clicked on, the interface first examines if the database has changed since that given query was last run. If there are no changes, the stored result is displayed. In the other case, the query is re-executed, the stored result is updated, and the new result is displayed. |
| 103 | | |
| 104 | | Users have possibility to delete their own queries from the list by clicking on the corresponding ”X” icon, or to run queries which belong to other users by clicking on the query string. |
| 105 | | |
| 106 | | By clicking on the corresponding ”?” icon, the query string and previously added comments are always shown. If query is one of the queries with @ the starting file and position are also shown. |
| 107 | | |
| 108 | | By clicking on the corresponding ”E” icon, one can assign or can reassign a name to the query. This mechanism helps users to identify queries much easier. Users can add comments, either on their own queries, either on the queries of the others, too. By clicking on the corresponding ”C” icon, one can modify the previously added comment. By default, the comment field is empty. |
| 109 | | === Running Queries === |
| 110 | | The list of currently running queries is displayed at the left side of the page at ”Running Queries” tab. The list is updated in every second. A running query,which has been started by the current user, can be aborted by pressing the corresponding X icon. The current user, who started the query, is notified about the success of the abort. |
| 111 | | === Displaying the result of queries === |
| 112 | | Results are displayed at the left side of the page at ”Last Result” tab in a table. The source of the entries of the result’s can be visualised by clicking on the given entry in the detail. If the source is loaded to the database, it will be shown in a text-box located to the right of the table. The part of the source code responsible for the entry will be highlighted in the text-box. |
| 113 | | === Skeleton of queries === |
| 114 | | Large amount of queries are similar to each-other. The difference usually originates from the actual value of their filter parameter or from the used sub-query. Examples are shown below. |
| 115 | | |
| 116 | | {{{ |
| 117 | | mods[name = a].funs[(name = f) and (arity = 2)].refs |
| 118 | | mods[name = b].funs[(name = g) and (arity = 3)].refs |
| 119 | | }}} |
| 120 | | |
| 121 | | or |
| 122 | | |
| 123 | | {{{ |
| 124 | | mods.funs[arity = 2] |
| 125 | | mods.funs[exported and is_tail_rec] |
| 126 | | }}} |
| 127 | | |
| 128 | | A new abstract level is introduced, where those queries are not only similar to each-other, but those queries do equal to each-other, we called it Skeleton. Examples are shown below. |
| 129 | | |
| 130 | | {{{ |
| 131 | | mods[name = $ModName$].funs[name = $FunName$ and arity = $Arity$].refs |
| 132 | | mods.funs[$FunSubQuery$] |
| 133 | | }}} |
| 134 | | === Usage of the skeleton === |
| 135 | | The service of the skeletons is available under ’Queries’ menu. A skeleton can be constructed by typing its body, which observes the rules of the valid skeleton, into the query construct assistant, than ’Save as skeleton’ button should be pressed. By pressing the ’Save as skeleton’ button, a dialogue box appears, where the wanted name of the constructed skeleton should be typed. By clicking the ’Save’ button, which is placed in the dialogue box, the skeleton will be saved. The constructed skeleton appears in the list of available skeletons, which is located at the ’Skeletons’ tab, whether the save was success. If any error occurs during the save, an error message will be shown. |
| 136 | | |
| 137 | | A previously saved skeleton can be evaluated by calling as a function with the actual values of the parameters. A valid actual parameter can contain nearly anything, only the {{{’}}} character is needed to avoid, because the {{{’}}} character is the delimiter of the value of an actual parameter. Auto-complete does not only offer the possible endings, but also does offer the joint skeletons. |
| 138 | | |
| 139 | | A valid skeleton call is shown below: |
| 140 | | |
| 141 | | {{{ |
| 142 | | Name = skeleton_name |
| 143 | | Body = mods.funs[$FunSubQuery$] |
| 144 | | skeleton_name(’ (arity>0) and (name like s) ’). |
| 145 | | }}} |
| 146 | | |
| 147 | | Previously saved skeletons are listed at ’Skeletons’ tab. |
| 148 | | |
| 149 | | By clicking the name of the skeleton, a valid ’skeleton call’ will be placed in the query construct assistant, where the actual parameters should be written by replacing character with the corresponding parameter value. |
| 150 | | |
| 151 | | By clicking the ? icon, the body of the skeleton and the owner of the skeleton will be shown. |
| 152 | | |
| 153 | | After a successful evaluation of a skeleton, the generated semantic query string and its result are saved in the ’Previous queries’ list, and the result of the semantic query will be shown in the right side of the page. |
| 154 | | |
| 155 | | Only the owner of the skeleton can edit its body, or can delete it. |
| 156 | | |
| 157 | | By clicking the corresponding ’E’ icon, the body of the skeleton will be placed into the query construct assistant. After the necessary changes had been made then the ’Update skeleton’ button has been pressed, the body of the skeleton will be updated. |
| 158 | | |
| 159 | | By clicking the corresponding ’X’ icon, the skeleton will be deleted. |
