Recent Changes - Search:




Modes.AidaScripting History

Hide minor edits - Show changes to markup

January 23, 2006, at 10:24 AM by -
Added lines 1-188:

This purpose of this page is to discuss the Scripting capacities of Aida Mode. It contains the following sections:

  1. The :Source: header parameter

  2. The :TclCmd: header parameter

  3. The s substitution tag

  4. The if tag

  5. Custom header parameters

  6. Target format

Back to the Features.AidaProject main page.

Aida has some scripting capacities due to the fact that it is able to source a Tcl file or to evaluate Tcl commands. This evaluation is made using either a substitution tag or a conditional tag.

In all the examples below we suppose that our Aida file is documenting some hypothetical software.

The :Source: header parameter

This header parameter lets you specify the name of a Tcl script file to source. This file can be specified either by a full path name or by a relative file name (in which case, the file name is relative to the Aida file being currently processed). This allows you to define procs which will be invoked later during the conversion process. This can be a proc seeking a particular information on the system, or a proc which writes some external file on the fly, or whatever...

There can be as many :Source: header parameters as necessary.

Example Suppose we have a Tcl proc called listMySourceFiles which is able to build a list of all the source files included in some package and that it is stored in a Tcl file called MyAidaUtils.tcl located in the same folder as the Aida file itself. You would declare, in the header of the Aida file:

     :Source:    MyAidaUtils.tcl

We'll explain below how the proc can then be invoked.

The :TclCmd: header parameter

There can be as many :TclCmd: header parameters as necessary. They are used to execute a Tcl command before an Aida file is converted to another format. This parameter can be followed by any Tcl instruction which will be evaluated when the header is parsed, i-e at the very beginning of the converting process. You can for instance declare global variables which can be used anywhere in the text or invoke more complex commands and procs which have been defined in the Tcl interpreter (for instance by sourcing a particular file as explained in the previous section).

Example Let us define a global variable called thevers defining the current version number of the software documented by the Aida file:

     :TclCmd:	set thevers 1.2.1

We could also use the result value of some proc defined in the file sourced with the :Source: parameter. Suppose we have a proc called GetPackageSize which returns the size in bytes of our packaged software. We could define a global variable like this:

     :TclCmd:	set thesize [GetPackageSize]

The s substitution tag

The ((s s)) pair of tags is called substitution tags. These tags are used inside the body of the Aida file to provoke the evaluation by the Tcl interpreter of the text it encloses.

Example For instance, using the procs and variables defined above with the :TclCmd: and :Source: header parameters, we could now write something like:

 This file documents version  ((s $thevers s)). The size 
 of the download is ((s $thesize s)) K. It contains the 
 following files: ((s [listMySourceFiles] s)).

Everything enclosed inside the ((s s)) pair of tags must be a valid Tcl instruction. One can of course use Tcl commands directly (i-e a value does not always have to be stored in a variable). For instance:

 Last modification ((s [clock format [clock seconds]] s))

will yield Last modification Wed Jan 21 00:40:01 CET 2004.

The if tag

The ((if if)) pair of tags lets you define conditional blocks. Both the opening and the closing tags must be at the beginning of the line. The opening ((if tag must be followed by a Tcl instruction returning a boolean value (1 or 0 for true or false). If the instruction evaluates to false all the text included between the opening and the closing tags will be discarded. Otherwise it is normally included.

Example Here is an example of some text which will be included only in version 2.1 of our software:

     ((if $thevers eq "1.2"
     Here is some text specific to version 1.2...

Custom header parameters

There is another way of defining particular values to be inserted in the Aida file using custom header parameters. One can in fact define any header parameter: a header parameter is just a word enclosed between colons. When the header of the file is parsed, the value of all the header parameters (other than the

and :Source: parameters explained above) is stored in an array variable

called aida_keywd. The key of the array is the name of the parameter without its colons and the value is the value of the parameter.

This array is reinitialized at the beginning of every conversion.

Example Let us define a header parameter called :HomePage: and designating the address of a Web page for our software, like this:


This Web address can be invoked in the Aida file as the value of the aida_keywd(HomePage) variable. For instance:

Visit our home page at ((s $aida_keywd(HomePage) s))

This method has two advantages over the simple definition of a global variable using the :TclCmd: header parameter:

  • it avoids defining variables which pollute the global scope because there is no simple way to unset them in the Aida file once the conversion is completed.

  • the aida_keywd can encapsulate lots of informations if necessary and it can also be used and manipulated from procs defined in a file sourced with the :Source: header parameter. Such a proc just has to include a
 global aida_keywd


Target format

The target format of a conversion operation is stored in the aida_params array with the key target (the aida_params array is different from the aida_keywd array: it is an array used by Aida Mode for keeping its internal values). This can be useful in if blocks to conditionalize them on the target format.

Example In the following example an image is inserted only if we are making a conversion to Html:

     ((if $aida_params(target) eq "Html"
     ((im ../Images/tclpowered.gif 
     Tcl Powered Logo im))

It might be unclear from the examples showed on this page, but note that all the header parameters have to be written at the beginning of a line.

Page last modified on January 23, 2006, at 10:24 AM
Hosted on Logo