Current version is 3.06
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 can be run by gprbuild; see Using gprbuild.
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]
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.
project Text_IO is for Languages use ("Auto_Text_IO"); for Source_Dirs use ("."); for Object_Dir use "auto"; for Source_Files use ("a_package.ads"); end Text_IO;Each file that must be processed by Auto_Text_IO must be listed explicitly. When building a main program, gprbuild doesn't know that it should run auto_text_io first. So you will get errors about missing sources. For a clean build from scratch, invoke gprbuild with the text_io project first, then with the Ada main project. Auto_Text_IO invokes GNAT to generate the ASIS tree files. It uses a default set of options when doing that. If more specific options are needed, you must create yet another project file to specify them, and tell Auto_Text_IO to use it:
project Text_IO is for Languages use ("Auto_Text_IO"); for Source_Dirs use ("."); for Object_Dir use "auto"; for Source_Files use ("a_package.ads"); package Compiler is for Default_Switches ("Auto_Text_IO") use ("-P../gds_tree.gpr"); end Compiler; end Text_IO;gds_tree.gpr must specify the same object directory as text_io.gpr, which must be different from gds.gpr; the ASIS tree files are produced by GNAT in ASIS mode, and are different from the tree files produced in normal mode. The path to gds_tree.gpr includes ../, because auto_text_io is invoked with auto as the current directory. In this case, ADA_PROJECT_PATH should be all absolute paths.
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.
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).
my home page Author : Stephen Leake Last modified: Mon Apr 5 09:49:40 EDT 2010