Remerciez-le!

Remerciez @Admin pour avoir partagé cet document gratuitement, de la manière la plus simple, en partageant sur les réseaux sociaux.

AutoGen - The Automated Program Generator For version 5.18, August 2015 Bruce K

AutoGen - The Automated Program Generator For version 5.18, August 2015 Bruce Korb bkorb@gnu.org AutoGen copyright c ⃝1992-2015 Bruce Korb This is the second edition of the GNU AutoGen documentation, Published by Bruce Korb, 910 Redwood Dr., Santa Cruz, CA 95060 AutoGen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. AutoGen is distributed in the hope that it will be useful, but WITHOUT ANY WAR- RANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>. This manual is for GNU AutoGen version 5.18, updated August 2015. Copyright c ⃝1992-2015 by Bruce Korb. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. The Automated Program Generator 1 The Automated Program Generator This file documents AutoGen version 5.18. It is a tool designed for generating program files that contain repetitive text with varied substitutions. This document is very long because it is intended as a reference document. For a quick start example, See Section 1.2 [Example Usage], page 3. The AutoGen distribution includes the basic generator engine and several add-on li- braries and programs. Of the most general interest would be Automated Option processing, See Chapter 7 [AutoOpts], page 83, which also includes stand-alone support for configura- tion file parsing, See Section 7.1 [Features], page 83. See Chapter 8 [Add-Ons], page 185, section for additional programs and libraries associated with AutoGen. This edition documents version 5.18, August 2015. Chapter 1: Introduction 2 1 Introduction AutoGen is a tool designed for generating program files that contain repetitive text with varied substitutions. Its goal is to simplify the maintenance of programs that contain large amounts of repetitious text. This is especially valuable if there are several blocks of such text that must be kept synchronized in parallel tables. An obvious example is the problem of maintaining the code required for processing program options and configuration settings. Processing options requires a minimum of four different constructs be kept in proper order in different places in your program. You need at least: 1. The flag character in the flag string, 2. code to process the flag when it is encountered, 3. a global state variable or two, and 4. a line in the usage text. You will need more things besides this if you choose to implement long option names, configuration (rc/ini) file processing, environment variable settings and keep all the docu- mentation for these up to date. This can be done mechanically; with the proper templates and this program. In fact, it has already been done and AutoGen itself uses it See Chapter 7 [AutoOpts], page 83. For a simple example of Automated Option processing, See Section 7.4 [Quick Start], page 88. For a full list of the Automated Option features, See Section 7.1 [Features], page 83. Be forewarned, though, the feature list is ridiculously extensive. 1.1 The Purpose of AutoGen The idea of this program is to have a text file, a template if you will, that contains the general text of the desired output file. That file includes substitution expressions and sections of text that are replicated under the control of separate definition files. AutoGen was designed with the following features: 1. The definitions are completely separate from the template. By completely isolating the definitions from the template it greatly increases the flexibility of the template implementation. A secondary goal is that a template user only needs to specify those data that are necessary to describe his application of a template. 2. Each datum in the definitions is named. Thus, the definitions can be rearranged, augmented and become obsolete without it being necessary to go back and clean up older definition files. Reduce incompatibilities! 3. Every definition name defines an array of values, even when there is only one entry. These arrays of values are used to control the replication of sections of the template. 4. There are named collections of definitions. They form a nested hierarchy. Associated values are collected and associated with a group name. These associated data are used collectively in sets of substitutions. 5. The template has special markers to indicate where substitutions are required, much like the ${VAR} construct in a shell here doc. These markers are not fixed strings. They are specified at the start of each template. Template designers know best what fits into their syntax and can avoid marker conflicts. Chapter 1: Introduction 3 We did this because it is burdensome and difficult to avoid conflicts using either M4 tokenization or C preprocessor substitution rules. It also makes it easier to specify expressions that transform the value. Of course, our expressions are less cryptic than the shell methods. 6. These same markers are used, in conjunction with enclosed keywords, to indicate sec- tions of text that are to be skipped and for sections of text that are to be repeated. This is a major improvement over using C preprocessing macros. With the C prepro- cessor, you have no way of selecting output text because it is an unvarying, mechanical substitution process. 7. Finally, we supply methods for carefully controlling the output. Sometimes, it is just simply easier and clearer to compute some text or a value in one context when its application needs to be later. So, functions are available for saving text or values for later use. 1.2 A Simple Example This is just one simple example that shows a few basic features. If you are interested, you also may run "make check" with the VERBOSE environment variable set and see a number of other examples in the agen5/test directory. Assume you have an enumeration of names and you wish to associate some string with each name. Assume also, for the sake of this example, that it is either too complex or too large to maintain easily by hand. We will start by writing an abbreviated version of what the result is supposed to be. We will use that to construct our output templates. In a header file, list.h, you define the enumeration and the global array containing the associated strings: typedef enum { IDX_ALPHA, IDX_BETA, IDX_OMEGA } list_enum; extern char const* az_name_list[ 3 ]; Then you also have list.c that defines the actual strings: #include "list.h" char const* az_name_list[] = { "some alpha stuff", "more beta stuff", "final omega stuff" }; First, we will define the information that is unique for each enumeration name/string pair. This would be placed in a file named, list.def, for example. autogen definitions list; list = { list_element = alpha; list_info = "some alpha stuff"; }; list = { list_info = "more beta stuff"; list_element = beta; }; list = { list_element = omega; Chapter 1: Introduction 4 list_info = "final omega stuff"; }; The autogen definitions list; entry defines the file as an AutoGen definition file that uses a template named list. That is followed by three list entries that define the associations between the enumeration names and the strings. The order of the differently named elements inside of list is unimportant. They are reversed inside of the beta entry and the output is unaffected. Now, to actually create the output, we need a template or two that can be expanded into the files you want. In this program, we use a single template that is capable of multiple output files. The definitions above refer to a list template, so it would normally be named, list.tpl. It looks something like this. (For a full description, See Chapter 3 [Template File], page 21.) [+ AutoGen5 template h c +] [+ CASE (suffix) +][+ == h +] typedef enum {[+ FOR list "," +] IDX_[+ (string-upcase! (get "list_element")) +][+ ENDFOR list +] } list_enum; extern char const* az_name_list[ [+ (count "list") +] ]; [+ == c +] #include "list.h" char const* az_name_list[] = {[+ FOR list "," +] "[+list_info+]"[+ ENDFOR list +] };[+ ESAC +] The [+ AutoGen5 template h c +] text tells AutoGen that this is an AutoGen version 5 template file; that it is to be processed twice; that the start macro marker is [+; and the end marker is +]. The template will be processed first with a suffix value of h and then with c. Normally, the suffix values are appended to the base-name to create the output file name. The [+ == h +] and [+ == c +] CASE selection clauses select different text for the two different passes. In this example, the output is nearly disjoint and could have been put in two separate uploads/Litterature/ autogen-guide.pdf