Webshort provides a few classes that allow to compile a version of the Smalleiffel short command line utility for use on the web as a CGI program.
This provides a rudimentary yet convenient class browser for SmallEiffel.
Contents
A CGI (Common Gateway Interface) program is an executable that is launched by a web server in reply to an URL request. The program's input contains information on the request and server in various environment variable and the standard output of the program is sent back to the user. The output is usually a web page.
SmallEiffel's short utility already has HTML output using one of the formats provided in the standard distribution. All is required to make that suitable as the output of a CGI program is to add a corresponding header, which this utility does. The other task required to make short a CGI program is to get the parameters for the request from CGI environment variables instead of the command line.
The Webshort utility is a variant of the SmallEiffel's short utility. The class WEBSHORT inherits from short's root class and redefines command line parsing and adds the relevant headers.
An auxiliary class, MINIMAL_CGI_QUERY provides parsing of the command line parameters. It is minimal in the sense that it is not a full blown CGI library so it does not bring in any dependency -- so it could make sense to integrate it in the mainstream SmallEiffel distribution for instance. It's also minimal in doing just what's required for that application, eg it does not deal with escaped characters, because they do not occur in this particular application.
In addition to these classes, a slightly modified version of the HTML output template is provided. The changes are: (1) provide a small form on top of each class short form so that any class name can be typed and the webshort utility called again, and (2) all links to other classes are made to use the Webshort utility instead of the default formats' static file links.
In order to install the program, the webshort program needs to be compiled. The lib_se directory needs to be in the SmallEiffel load path, but it normally is in a default compiler installation.
The htmlcgi format has then to be added to $SmallEiffel/short/. This is done by running the HOOKS.SH shell script in a new htmlcgi directory or simply using the ready made version provided in the distribution. The latter is recommended if there is no Unix shell environment available -- HOOKS.SH is a Unix shell script (slightly modified from the Smalleiffel distribution).
HOOKS.SH needs to be modified with the reference to your local machine's location and name for the webshort program. The hook files hook002 and Bcn may also be modified directly if HOOKS.SH cannot be run.
Finally, the webshort program has to be put into a web server's CGI directory or equivalent -- a web server is indeed required. The environment variables of the CGI programs must include Smalleiffel's system variable ($SmallEiffel). A loadpath.se file in the CGI directory can also be useful to define a set of browsable classes.
Then, from a web browser the URL http://localhost/cgi-bin/webshort?class=integer should show something. The URL may need to be adapted to local requirements: other machine, other path to CGI programs, .exe on Windows servers...
To summarise the installation process in a few commands:
Usage
The base format of a Webshort URL is:
http://<host>/<cgi-directory>/webshort[.exe]?class=<classname>
The options of the short utility can be enabled by adding "<option>=on". The options have the same name as in the original command line version of short (without leading dash). Both the W3C-recommended ';' and the traditional but sometimes problematic '&' are accepted as option separators. Using options an example URL is http://localhost/cgi-bin/webshort?class=real;short=yes
The current version does not return correct CGI output in erroneous cases, unless the error occurs in the middle of the short form (where it is still incorrect but can be displayed). The problem lies in the CGI header. In case of error the standard output contains the compiler's text error message and no HTML page. This is fine, as long as the header says so (either it says that the data is text or HTML). The problem is that whenever Smalleiffel knows something is wrong it displays something to the standard output. It is therefore not easy for the WEBSHORT class to know before the first output if it's text or HTML to write the correct (text or html) header.
This would be possible to fix this by touching the Smalleiffel code but this seems too inconvenient and unmaintainable a hack. The current behaviour is that if there is an incorrect command line parameter or more commonly an incorrect class name, the web browser will display an error message like "Empty page" or "No reply from CGI script" instead of a proper error message. In normal circumstances this is just a mistyped class name and can be easily remedied.
Future enhancements
Possible future enhancements include a web version of the pretty utility to look at the class text, with links between both forms. A version of finder could also be modified to display the raw Eiffel source texts.