GNU AutoGen - The Automated Program Generator: 8.7 Invoking xml2ag

8.7 Invoking xml2ag

This program will convert any arbitrary XML file into equivalent AutoGen definitions, and invoke AutoGen. The template used will be derived from either:

The –override-tpl command line option
A top level XML attribute named, "template"

One or the other must be provided, or the program will exit with a failure message.

The base-name for the output will similarly be either:

The –base-name command line option.
The base name of the ‘.xml’ file.

The definitions derived from XML generally have an extra layer of definition. Specifically, this XML input:

<mumble attr="foo">
  mumble-1
  <grumble>
  grumble, grumble, grumble.
</grumble>mumble, mumble
</mumble>

Will get converted into this:

mumble = {
  grumble = {
    text = 'grumble, grumble, grumble';
  };
  text = 'mumble-1';
  text = 'mumble, mumble';
};

Please notice that some information is lost. AutoGen cannot tell that "grumble" used to lie between the mumble texts. Also please note that you cannot assign:

grumble = 'grumble, grumble, grumble.';

because if another "grumble" has an attribute or multiple texts, it becomes impossible to have the definitions be the same type (compound or text values).

This section was generated by AutoGen, using the agtexi-cmd template and the option descriptions for the xml2ag program. This software is released under the GNU General Public License, version 3 or later.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.7.1 xml2ag help/usage (‘`--help`’)

This is the automatically generated usage text for xml2ag.

The text printed is the same whether selected with the help option (‘--help’) or the more-help option (‘--more-help’). more-help will print the usage text by passing it through a pager program. more-help is disabled on platforms without a working fork(2) function. The PAGER environment variable is used to select the program, defaulting to ‘more’. Both will exit with a status code of 0.

xml2ag (GNU AutoGen) - XML to AutoGen Definiton Converter - Ver. 5.18.6pre15
Usage:  xml2ag [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ]

All other options are derived from autogen:

  Flg Arg Option-Name    Description
   -O Str output         Output file in lieu of AutoGen processing

All other options:

  Flg Arg Option-Name    Description
   -L Str templ-dirs     Search for templates in DIR
                                - may appear multiple times
   -T Str override-tpl   Use TPL-FILE for the template
      Str definitions    Read definitions from FILE
      Str shell          name or path name of shell to use
   -m no  no-fmemopen    Do not use in-mem streams
      Str equate         characters considered equivalent
   -b Str base-name      Specify NAME as the base name for output
      no  source-time    set mod times to latest source
      no  writable       Allow output files to be writable
                                - disabled as '--not-writable'
      Num loop-limit     Limit on increment loops
                                - is scalable with a suffix: k/K/m/M/g/G/t/T
                                - it must lie in one of the ranges:
                                  -1 exactly, or
                                  1 to 16777216
   -t Num timeout        Limit server shell operations to SECONDS
                                - it must be in the range:
                                  0 to 3600
      KWd trace          tracing level of detail
      Str trace-out      tracing output file or filter
      no  show-defs      Show the definition tree
      no  used-defines   Show the definitions used
   -C no  core           Leave a core dump on a failure exit
   -s Str skip-suffix    Skip the file with this SUFFIX
                                - prohibits the option 'select-suffix'
                                - may appear multiple times
   -o Str select-suffix  specify this output suffix
                                - may appear multiple times
   -D Str define         name to add to definition list
                                - may appear multiple times
   -U Str undefine       definition list removal pattern
                                - an alternate for 'define'
   -M opt make-dep       emit make dependency file
                                - may appear multiple times

Version, usage and configuration options:

  Flg Arg Option-Name    Description
   -v opt version        output version information and exit
   -? no  help           display extended usage information and exit
   -! no  more-help      extended usage information passed thru pager

Options are specified by doubled hyphens and their name or by a single
hyphen and the flag character.
This program will convert any arbitrary XML file into equivalent AutoGen
definitions, and invoke AutoGen.

The valid "trace" option keywords are:
  nothing       debug-message server-shell  templates     block-macros
  expressions   everything
  or an integer from 0 through 6
The template will be derived from either: * the ``--override-tpl'' command
line option * a top level XML attribute named, "template"

The ``base-name'' for the output will similarly be either: * the
``--base-name'' command line option * the base name of the .xml file
Packaged by Bruce (2015-08-21)
Report xml2ag bugs to bkorb@gnu.org

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.7.2 the-xml2ag-option options

All other options are derived from autogen.

output option (-O).

This is the “output file in lieu of autogen processing” option. This option takes a string argument ‘file’. By default, the output is handed to an AutoGen for processing. However, you may save the definitions to a file instead.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

8.7.3 autogen-options options

All other options. These options are mostly just passed throug to autogen. The one exception is --override-tpl which replaces the default template in the output definitions. It does not get passed through on the command line.

templ-dirs option (-L).

This is the “search for templates in ‘dir’” option. This option takes a string argument ‘DIR’.

This option has some usage constraints. It:

may appear an unlimited number of times.

Pass-through AutoGen argument

override-tpl option (-T).

This is the “use ‘tpl-file’ for the template” option. This option takes a string argument ‘TPL-FILE’. Pass-through AutoGen argument

lib-template option (-l).

This is the “load autogen macros from ‘tpl-file’” option. This option takes a string argument ‘TPL-FILE’.

This option has some usage constraints. It:

may appear an unlimited number of times.

Pass-through AutoGen argument

NOTE: THIS OPTION IS DEPRECATED

definitions option.

This is the “read definitions from ‘file’” option. This option takes a string argument ‘FILE’. Pass-through AutoGen argument

shell option.

This is the “name or path name of shell to use” option. This option takes a string argument ‘shell’. Pass-through AutoGen argument

no-fmemopen option (-m).

This is the “do not use in-mem streams” option. Pass-through AutoGen argument

equate option.

This is the “characters considered equivalent” option. This option takes a string argument ‘char-list’. Pass-through AutoGen argument

base-name option (-b).

This is the “specify name as the base name for output” option. This option takes a string argument ‘NAME’. Pass-through AutoGen argument

source-time option.

This is the “set mod times to latest source” option. Pass-through AutoGen argument

writable option.

This is the “allow output files to be writable” option.

This option has some usage constraints. It:

can be disabled with –not-writable.

Pass-through AutoGen argument

loop-limit option.

This is the “limit on increment loops” option. This option takes a number argument ‘lim’. Pass-through AutoGen argument

timeout option (-t).

This is the “limit server shell operations to seconds” option. This option takes a number argument ‘SECONDS’. Pass-through AutoGen argument

trace option.

This is the “tracing level of detail” option. This option takes a keyword argument ‘level’.

This option has some usage constraints. It:

This option takes a keyword as its argument. The argument sets an enumeration value that can be tested by comparing the option value macro (OPT_VALUE_TRACE). The available keywords are:
nothing debug-message server-shell templates block-macros expressions everything
or their numeric equivalent.

Pass-through AutoGen argument

trace-out option.

This is the “tracing output file or filter” option. This option takes a string argument ‘file’. Pass-through AutoGen argument

show-defs option.

This is the “show the definition tree” option. Pass-through AutoGen argument

used-defines option.

This is the “show the definitions used” option. Pass-through AutoGen argument

core option (-C).

This is the “leave a core dump on a failure exit” option.

This option has some usage constraints. It:

must be compiled in by defining HAVE_SYS_RESOURCE_H during the compilation.

Many systems default to a zero sized core limit. If the system has the sys/resource.h header and if this option is supplied, then in the failure exit path, autogen will attempt to set the soft core limit to whatever the hard core limit is. If that does not work, then an administrator must raise the hard core size limit.