Home/Compilers/WebAda

WebAda Macros

Overview | Scripts | Templates | Macros

<hr>
WebAda uses HTML to provide a Graphical User Interface (GUI). In general, HTML was designed to provide information that doesn't change often (static) and wasn't designed to handle information that changed quickly (dynamic).

To take advantage of HTML and introduce dynamic information, WebAda uses macros embedded in HTML templates. The macros look very similar to HTML tags:

<filename>Unknown</filename>

When a WebAda script is invoked, an appropriate template is expanded, substituting information for the macros it recognizes. The macros can appear anywhere in the file, but not within quotes. Here's an example you can play with:

File name

When you hit the Save button, the text in the window is saved to the file, example.html. To expand that file, type the following URL into your browser:

http://sw-eng.falls-church.va.us/cgi-bin/webada/file?template=example.html
or
http://sw-eng.falls-church.va.us/cgi-bin/webada/file?template=example.html&file=example.html

The URL breaks down this way:

  • http://sw-eng.falls-church.va.us/cgi-bin/webada/expand
    is the name of the CGI script.
  • ?
    is the CGI character which indicates there are parameters for the script
  • template=example.html
    is a CGI parameter which might mean something to the script (you don't get to change WebAda scripts!)
  • &
    is the CGI character which separates CGI parameters.

Of course, you have to know what parameters make sense to which scripts. Then you can begin to build your own templates, which call each other through the WebAda scripts to form your own Graphical User Interface (GUI) to an Ada Development Environment (ADE).

<hr>
There are several kinds of macros:

  • Simple substitution expands to some information provided by the script. However, if the information is not available, the alternate text between the tags is used. For example, <filename>Unknown</filename> in the example.html template expands to:

    ...file?template=example.html&file=hello.adb

    hello.adb

    ...file?template=example.html

    Unknown

  • List substitution expands lists. For example, the CGI parameters can be expanded using the macro pattern, <parameters><key></key><value></value></parameters>. The "parameters" macro is iterative, and each iteration uses the two simple substitutions for "key" and "value" macros. HTML can be interspersed and is illustrated in the overview. The example can be modified to list CGI parameters, because the file script recognizes the key macro. Then you can try adding additional parameters when you call the script (but keep the template=example.html parameter!)
  • Conditional substitution will expand the text between tags only if some condition is true. For example, the result of file?action=compile... can succeed or fail. So there are two macros: <success> and <failure> used in the gnat_compile.html template. The macros can appear multiple times and will be expanded or removed at each place. Study the occurrences of the <success> and <failure> macros in the gnat_compile.html template to get an idea of what is possible.

<hr>
Macros can be repeated any number of times and in any order with HTML interspersed between the macro tags. Closing macro tags are required! Here are the available macros:

<variables><variable></variable><value></value></variables>
variables is a list macro which iterates through the Environment Variables. variable and value are simple macros which expand during each iteration. (cgi-environment-expand.ads; cgi-environment-expand.adb)
<parameters><key></key><value></value></parameters>
parameters is a list macro which iterates through the CGI Parameter. key and value are simple macros which expand during each iteration. (cgi-parameters-expand.ads; cgi-parameters-expand.adb)
<library></library>
library is a simple macro which expands the current library name. (webada-library.ads, webada-library.adb)
<comp_unit><cu_path></cu_path><cu_URL></cu_URL><cu_name></cu_name></comp_unit>
comp_unit is a list macro which iterates through the compilation units in a library (<library>). The cu_path, cu_URL, and cu_name are simple macros which expand during each iteration. (webada-library.ads, webada-library.adb)
<code></code>
<filename></filename>
<filepath></filepath>
code, filename, and filepath are simple macros which expand information about a file (given in the CGI-parameter, file=URL). code expands the contents of the file, filename expands to the simple filename, and filepath expands to the full pathname. (webada-source_code.ads, webada-source_code.adb)
<na></na>
<
no_filename></no_filename>
<
no_code></no_code>
<
unable_to_save_file></unable_to_save_file>
<
unable_to_open_file><unable_to_open_file>
<
unable_to_create_file><unable_to_create_file>
<
file_created></file_created>
<
file_saved></file_saved>
Only one of these conditional macros will expand, corresponding to the results of attempting to save some source code. As the macros indicate, filename and code should be provided (as CGI-parameters filename=URL&code=text) when the save operations is invoked (with a CGI-parameter, action=save). If the save is not invoked, the na macro is expanded; otherwise, each of the conditions is checked (in the order listed) and when true, the save operation completes. (webada-source_code.ads, webada-source_code.adb)
<compile></compile>
compile is a simple macro which expands the output from the compiler when the compile operation is invoked (action=compile) and completes 1. The file script automatically performs a save (action=save) and therefore the associated conditional macros can indicate problems such as no_filename (no_code does not preempt the compile operation). (webada-source_code-gnat.ads, webada-source_code-gnat.adb)
<success></success>
<
failure></failure>
These conditional macros expand when a compile operation completes and the source either has errors (failure) or is compilable (success). If the compile operation has not been invoked or did not complete, neither of these macros expands. (webada-source_code-gnat.ads, webada-source_code-gnat.adb)
<GNAT_options><option_name></option_name><value></value><description></description></GNAT_options>
GNAT_options is a list macro which iterates through the options passed as parameters or set in a preferences file. The option_name, value, and description are simple macros which expand during each iteration. (webada-source_code-gnat.ads, webada-source_code-gnat.adb)
<GNAT_prefs><option_name></option_name><value></value><description></description></GNAT_prefs>
GNAT_prefs is a list macro which iterates through the options stored in a preferences file. The option_name, value, and description are simple macros which expand during each iteration. (webada-source_code-gnat.ads, webada-source_code-gnat.adb)
<Lovelace_options><option_name></option_name><value></value><description></description></Lovelace_options>
Lovelace _options is a list macro which iterates through the options passed as parameters or set in a preferences file. The option_name, value, and description are simple macros which expand during each iteration. (webada-lovelace.ads, webada-lovelace.adb)
<Lovelace_prefs><option_name></option_name><value></value><description></description></Lovelace_prefs>
Lovelace_prefs is a list macro which iterates through the options stored in a preferences file. The option_name, value, and description are simple macros which expand during each iteration. (webada-lovelace.ads, webada-lovelace.adb)
<surfada></surfada>
surfada is a simple macro which expands Ada source code into HTML. The surfada script automatically performs a save (action=save) and therefore the associated conditional macros can indicate problems such as no_filename (no_code does not preempt the compile operation). (webada-source_code-surfada.ads, webada-source_code-surfada.adb)
<webada_version></webada_version>
webada_version is a simple macro which expands the version number found in the script. (webada.ads)


  1. Compilation has four states: Not_Compiled, Failed, Has_Errors, Succeeded.
    Initial State : Not_Compiled;
    when action=compile and compilation does not complete => Failed;
    when action=compile and compilation completes with errors => Has_Errors;
    when action=compile and compilation completes without errors => Succeeded;