Auto_Text_IO

Current version is 3.05

Auto_Text_IO is a tool for automatically generating a Text_IO package for an Ada package. The generated package contains Put and Get subprograms for all the types in the Ada package, implemented via Ada.Text_IO. The Put and Get subprograms can use named notation aggregates (although Get does not support the full flexibility of Ada source code; in particular, the components of aggregates must be in declaration order). This makes it extremely easy to generate well-formatted output for Ada packages, and is one way to provide persistent storage in a readable form (see SAL.Config_Files for another way).

Auto_Text_IO is an ASIS application. It also uses some SAL data structures, and uses other SAL packages at run-time. It currently uses the GNAT implementation of ASIS, including some ASIS extensions. I'd be interested to help in porting it to other ASIS implementations.

Auto_Text_IO uses ASIS to iterate thru all the types declared in a package (called the "parent"). It creates a one or two child packages, containing Get and Put routines for each type. For scalar types, Auto_Text_IO generates an instantiation of the appropriate Ada.Text_IO package. For array types, it instantiates a package from SAL.Gen_Array_IO, a run-time package provided with SAL. For record types, it generates code to Put and Get an aggregate, optionally using named notation. For fully private types (that are not visible in the public part of the parent spec), it generates a separate private child package. The Get routine can read what Put outputs.

By default, Auto_Text_IO generates Ada 2005 code. There is an optional Ada 83 mode; the generated Text_IO package can be used with an Ada 83 compiler. In Ada 83 mode, no Get routines are generated. This is because Ada 83 Standard.Text_IO does not provide the Look_Ahead function, which is essential in a Get routine.

Most Ada types are supported. If you find one that isn't, it can probably be added. A notable exception is access types; it's not at all clear what to output in that case.

Download the source in tar.gz format. Then follow the simple installation instructions.

Auto_Text_IO is copyright 2009 by Stephen Leake, released under the Gnu General Public License. The run-time portions (in SAL) are released under the GNAT Modified Gnu General Public License (the same one that covers the supported GNAT run time libraries).

Auto_Text_IO is a command-line application. Here is a description of the command line:
auto_text_io [options] filename [directory]

filename
Parent package source file
directory
Optional directory in which to place generated Text_IO child package (default is '.'). This specifies a path relative to the parent package source directory, or it may be an absolute path.
-83
Use Ada 83 syntax (_Text_IO instead of .Text_IO, etc). Don't generate Get routines.
-05
Allow Ada 2005 syntax in source file.
-d
Output debug information
-f
Replace an existing Text_IO child (if any)
-g arg
Specify additional argument for running gnatmake.
-Idir
Source search dir, has the same meaning as for gnatmake
-I-
same as gnatmake
-iN
(N in 1 .. 9) Number of spaces used for identation in generated code
-k
Do not remove the GNAT tree file
-Pfile
Specify a GNAT project file for the source code.
-q
Quiet mode - do not output some messages
-r
Reuse the GNAT tree file instead of re-creating it. -r also implies -k
-sfile
Read the list of source search directories from a file. For use with GPS.
-t
Overwrite the existing GNAT tree file
-v
Specify verbose mode; less than debug, more than normal.
-?
Output this help information

If errors are encountered, no Text_IO child is produced. Errors are reported to standard error in standard Gnu format. If the gnatprep preprocessor is used, with option '-r', the auto_text_io error messages refer to the user source file, not the gnatprep output intermediate file.

A previous version of auto_text_io would output a Text_IO child in the presence of some warnings (such as a type not being supported). However, this turned out to be difficult to support cleanly, so now all unsupported types are reported as errors; the user must add "-- auto_text_io: ignore" comments.

There are special comments you can use to annotate your code, to influence what Auto_Text_IO does.

 --  Auto_Text_IO : ignore
--  Auto_Text_IO : separate

-- Auto_Text_IO : ignore preceding a type declaration excludes the type from Auto_Text_IO processing. This is useful if the type is not yet supported by Auto_Text_IO; it suppresses the warning message.

-- Auto_Text_IO : ignore preceding a generic formal package excludes it; see the Auto_Text_IO Manual for more information.

-- Auto_Text_IO : separate preceding a type declaration tells Auto_Text_IO that the user will provide the core Put and Get routines for the type, to provide special processing such as output format or input validation. See the Auto_Text_IO Manual for more information.

The file Source/gps.menu contains XML code to add Auto_Text_IO to the GPS menu. Copy it to ~/.gps.

Test code

There is complete test code for the Auto_Text_IO package. A set of example Ada packages is provided, with at least one of each type supported by Auto_Text_IO. In addition, all of the Text_IO child packages in SAL are generated by Auto_Text_IO; that serves as a test of the support for generic packages. The test driver calls Put for each type, then reads the result file with Get, verifying the correctness of Auto_Text_IO. There is a smaller test for Ada 83 mode, and another test that verifies some of the error messages generated by Auto_Text_IO. The makefile runs all the tests.

If you find a bug in Auto_Text_IO, or have a patch that provides an improvement, let me know.

Installation

Auto_Text_IO is distributed in source form only. There are two parts; the source for the Auto_Text_IO tool, and the source for the run-time components, which is in SAL.

If you'd like to compile Auto_Text_IO the way I do, see my SAL page for the list of tools I use. I give instructions here for using these tools (GNAT and Gnu make).

  1. Install SAL as described in SAL.
  2. Download auto_text_io-3.05.tar.gz.
  3. Extract to the same root directory as SAL.
  4. Download asis-gpl-2008-src.tgz.
  5. Extract to a directory of your choice; typically the root directory of the GNAT installation.
  6. In fileasis-2008-src/Makefile.stub, change INSTALL_DIR to a directory of your choice; I use GNAT/local
  7. In directory asis-2008-src, run make install
  8. Define GNAT_ASIS as an environment variable; its value must be the absolute path to the directory containing the file asis.gpr. In my case, that's GNAT/local/lib/gnat.
  9. Define INSTALL_BIN as an environment variable; its value must be the absolute path to the directory where you want to install the auto_text_io executable.
  10. From directory Auto_Text_IO/Build/x86_gnu_*_release, run make. Windows, Linux and Lynx build directories are provided. This will build the auto_text_io executable, and run all the tests. Note that even on Linux and Lynx, the executable file name ends in ".exe"; that simplifies the makefile.
  11. run make install to copy the executable to the installation directory.
  12. Include SAL in your project; it contains the run-time packages that are "with"ed by the code generated by auto_text_io.
  13. Makerules/auto_text_io_rules.make has an example make rule you can use for Auto_Text_IO. It places all automatically generated output in the sub-directory $AUTO_TEXT_IO_DIR, where it can be easily ignored by configuration management tools, and easily deleted by make clean.

Known Bugs

History

Version 3.05 11 April 2009
Version 3.04 18 June 2006
Version 3.03 4 August 2004
Version 3.02 5 April 2004
Version 3.01 17 Nov 2003
Version 3.00 2 Sept 2003
Version 2.02 1 May 2003
Version 2.01 26 September, 2002
Version 1.01 18 November, 2001
First release.

my home page Author : Stephen Leake Valid HTML 4.01! Created with Emacs powered by Ada Last modified: Tue Jul 21 03:29:17 EDT 2009