Auto_Text_IO

Current version is 3.04

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, based on 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 95 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 95 types are supported. If you find one that isn't, it can probably be added.

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

Auto_Text_IO is copyright 2006 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 specifices 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 05 syntax in source file. Not fully supported yet.

-d

Output debug information

-f

Replace an existing Text_IO child (if any)

-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

-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

-?

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 declarations 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 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. The environment variables described there are used by the Auto_Text_IO makefile.
2. Download auto_text_io-3.04.tar.gz.
3. Extract to the directory of your choice; typicallly the same root directory as SAL.
4. Download asis-gpl-2006-src.tgz.
5. Extract to a directory of your choice; typically the root directory of the GNAT installation.
6. In fileasis-2006-src/Makefile.stub, change INSTALL_DIR to a directory of your choice; I use GNAT/local
7. In directory asis-2006-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_windows_release, run make. This will build the auto_text_io executable, and run all the tests.
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

• none!
• Well, except that there are Ada types that are not supported by Auto_Text_IO. But that's a missing feature, not a bug :)
• And GNAT ASIS for GPL-2006 does not support Ada 2005, so most Ada 2005 additions to the language are not supported.

History

Version 3.04 18 June 2006

• Add -05 switch
• Delete support for GNAT 3.15p.
• Compiles cleanly with GNAT GPL-2006, GNAT 5.04a, using project files.
• Some redundant 'use' and 'with' clauses are no longer generated.
• Generic formal package parameters no longer need to be renamed with "Parent_" prefix.

Version 3.03 4 August 2004

• Delete -w; we no longer support 'warnings'; only 'errors'.
• Text_IO child not generated if there are any errors.
• Add some documentation on how to add support for types in Standard.
• Support Duration, Character types.
• In generated Put, use Single_Line_Record rather than Single_Line_Component to control new lines in some places.
• Properly support private extensions.
• Support selected names in discriminants.
• Properly ignore procedure instantiations and renames.
• Allow Text_IO child to with Private_Text_IO child, and vice versa.

Version 3.02 5 April 2004

• Minor cleanups, bug fixes
• More complete test coverage
• Delete -v option, which was not properly implemented.
• Tested with GNAT 3.15p Windows 2k, 5.02a Windows 2k and Lynx 4.0

Version 3.01 17 Nov 2003

• Match SAL 1.51 changes.
• Add -s command line option and gps.menu file for integration with GPS.
• Add support for Lynx OS; split out build directories.
• Tested with GNAT 3.15p, 3.16a1, 5.01a

Version 3.00 2 Sept 2003

• Support generic parent packages, with formal package parameters.
• Support variant records.
• Support user override of basic Put, Get to allow special formats or input validation.
• Merge run-time packages into SAL.
• All Text_IO packages in SAL now generated by Auto_Text_IO.
• Cleaned up code structure; use more ASIS queries.
• Tested with GNAT 3.15p, 3.16a1, 5.01a

Version 2.02 1 May 2003

• Match changes in SAL 1.06
• Added support for fully private (invisible) types.
• Use GNAT 3.15p project in Makefile.
• Reduce dependencies on GNAT-specific stuff.
• Support more pre-defined types.

Version 2.01 26 September, 2002

• Restructure code; separate files for each Build element state. More consistent naming conventions.
• Support private types, tagged types, derived types, discriminants.
• Special handling of pre-defined Ada.* and Interfaces.* packages.
• Handle more array component types.

Version 1.01 18 November, 2001

First release.

my home page.

Author : Stephen Leake