TCL2ADA
(Documentation)

Files in this distribution
Copyright
Installation
Usage
4.1 Using a separate template file
4.2 Using a single file
4.3 Example
Why use tcl2ada ?
A final note...

tcl2ada is a small utility for those who develop Tash programs. It allows you to keep your tcl code separated from your Ada code.

Files in this distribution

tcl2ada.htm	This file
tcl2ada.adb	The program. It consists of a single procedure.
tkprog.tpl	An sample template, that allows you to turn any Tcl/TK file into a stand-alone executable
tkprog.tcl	A minimal Tcl/TK application, included by tkprog.tpl

This software is distributed under Adalog's "advertiseware" license. The goal of this license is to make this product widely available as an advertisement for Adalog activities and a demonstration of Adalog's know-how in Ada development, without imposing any constraint on the user, except that code not made by Adalog should not be confused with original code (we cannot accept responsability for your bugs). Therefore:

Rights to use, distribute or modify in any way this software and its documentation are hereby granted, provided:

You do not remove or change the initial comment in the source files that contains the copyright notice and the reference to Adalog's activities. Similarly, you do not remove this copyright notice and the reference to Adalog's activities from this documentation. Additionnal headers in source files, or changes to the documentation are otherwise allowed.
You distribute this documentation with any copy of the software (whether as source or compiled form).
If you make modifications to the software or this documentation, these modifications must be properly identified as additions or modifications not originating from Adalog. If you make a valuable addition, we would appreciate (but do not require) to be kept informed by sending a message to rosen@adalog.fr.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Although we do not require it, you are very welcome, if you find this software useful, to send us a note at rosen@adalog.fr. We also welcome critics, suggestions for improvement, etc.

Installation

Compile the file tcl2ada.adb with your favorite compiler. There is nothing that could create the slightest dependance on any particular compiler or environment.

As a first example (and assuming Tash is properly installed), you can run:

tcl2ada tkprog.tpl tkprog.adb

and then compile and run the resulting tkprog.adb program.

Usage

tcl2ada [<input-file> | - ] [<output-file> | - ]

If no argument is provided, tcl2ada reads from standard_input and writes to standard_output. If only one argument is given, it is taken both as the input file and the output file, i.e. the file is replaced by the output of tcl2ada (unless it is "-"). The conventional name "-" designates the standard_input as the first argument, and the standard_output as the second argument. Therefore, the following three lines are equivalent:

tcl2ada tcl2ada - tcl2ada - -

tcl2ada copies its input file (the template) to its output file (using a temporary file if only one file is given). If it encounters an input line of the form:

--tcl2ada tcl_file

it includes the file "tcl_file" as a properly formated Ada string. Leading blanks, empty lines, and tcl comments are removed from the tcl file, in order to save space in the Ada program. Ascii.LF characters are inserted in place of line breaks.

However, anything between a line of the form:

--tcl2ada off

and a line of the form:

--tcl2ada on

is not copied to the output.

Similarly, if the "tcl_file" contains a line that starts with the Tcl comment:

#tcl2ada other_tcl_file

the other_tcl_file is recursively included, and anything between a line of the form

#tcl2ada off

and a line of the form

#tcl2ada on

is not included. This allows you to include code in the Tcl file which is useful only for stand-alone testing of your Tcl code, and won't get included in your Ada program.

Of course, you must regenerate the Ada file from the template each time you modify the template or the Tcl file. Make (or equivalent) can be very helpful in making sure that tcl2ada is called whenever necessary.

Using a separate template file

In this case, you keep a file that acts as a template, and use tcl2ada to generate the actual Ada file. Typically, the template file would look like:

   Prog : constant String :=
      --tcl2ada prog.tcl
      --tcl2ada off
      ""
      --tcl2ada on
   ; -- do not forget the semi-colon!
begin
   Tcl_Eval (Interp, Prog);
   ...

or even:

begin
   Tcl_Eval (Interp, 
      --tcl2ada prog.tcl
      --tcl2ada off
      ""
      --tcl2ada on
      );
   ...

Note the empty string which is provided between the "tcl2ada off" and the "tcl2ada on": this allows you to have a template which is still a syntactically correct Ada program, but the processing by tcl2ada will replace the empty string by the content of the provided file. This is useful because some reformaters (notably Grasp) choke when given programs that are not syntactically correct.

The benefit of using this approach is that you never see the Tcl code from your Ada code. The drawback is that error messages from the compiler refer to the expanded file, and do not necessarilly correspond to the line numbers in the template. It is also very common to fix an error in the generated file rather than in the template, and to loose the fix as soon as the template is regenerated!

Using a single file

Alternatively, the same file can act both as the template and the generated file (if you give only one file name to tcl2ada). This works, because:

The "--tcl2ada tcl_file" line is left in the output file
The included Tcl code is preceded by a "--tcl2ada off" line, and followed by a "--tcl2ada on" line.

So, if you simply rerun tcl2ada on its own output file, the Tcl_file will be included again, and the previous inclusion will be discarded. The benefits of following this approach is that you don't need a separate template file, and that you can fix errors right in the file that has been compiled. The drawback is that you'll get a lot of unreadable (since all formatting has been stripped off) Tcl code in your file... and that you have to make sure that you reload the file in your editor each time you regenerate it!

Example

The tkprog.tpl file is an exemple template, that provides the necessary minimal initialisations for a Tcl/Tk application to run. If you have a Tcl/Tk application that you want to provide as an executable, just edit the "--tcl2ada" line in tkprog.tpl to refer to your tcl program, run tcl2ada, compile, et voilà !

Why use tcl2ada ?

When you develop a Tash application, there are two ways to include the Tcl parts:

Keep the Tcl in separate files, and "source" them.

This allows to keep the Tcl parts completely separated, but the application has to know where the Tcl files reside, therefore making the installation more complicated.

Keep the Tcl as strings in the program.

This allows to provide the program as a single executable, at the cost of having the whole Tcl program inside your Ada code.

tcl2ada helps in the second case. You can keep your Tcl code in a separate file, check it interactively with Wish (or Twash!), even have nice indentations and comments, and then have it included automatically into your Ada code, with all the extra baggage removed.

A final note...

If you found this program useful...
If you think that getting it from us saved you some time...
If it showed you some usages of Ada that you didn't think about...

Maybe you should consider using Adalog's consulting and training services !

TCL2ADA (Documentation)

TCL2ADA
(Documentation)