Auto_Text_IO

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 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.

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.

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 : 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.

To have gprbuild run Auto_Text_IO, create a separate project file for
the Auto_Text_IO language. For example:

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.

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).

Extract to a directory of your choice; typically the root directory of the GNAT installation.

In directory asis-2008-src, run make install

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.

run make install to copy the executable and
auto_text_io.xml to the installation directory.

Include SAL in your project; it contains the run-time
packages that are "with"ed by the code generated by
auto_text_io.

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 :)