1This is autogen.info, produced by makeinfo version 6.5 from 2autogen.texi. 3 4This manual is for GNU AutoGen version 5.18, updated August 2018. 5 6 Copyright (C) 1992-2018 by Bruce Korb. 7 8 Permission is granted to copy, distribute and/or modify this 9 document under the terms of the GNU Free Documentation License, 10 Version 1.2 or any later version published by the Free Software 11 Foundation; with no Invariant Sections, no Front-Cover Texts, and 12 no Back-Cover Texts. 13INFO-DIR-SECTION GNU programming tools 14START-INFO-DIR-ENTRY 15* AutoGen: (autogen). The Automated Program Generator 16END-INFO-DIR-ENTRY 17 18 This file documents GNU AutoGen Version 5.18. 19 20 AutoGen copyright (C) 1992-2018 Bruce Korb AutoOpts copyright (C) 211992-2018 Bruce Korb snprintfv copyright (C) 1999-2000 Gary V. Vaughan 22 23 AutoGen is free software: you can redistribute it and/or modify it 24under the terms of the GNU General Public License as published by the 25Free Software Foundation, either version 3 of the License, or (at your 26option) any later version. 27 28 AutoGen is distributed in the hope that it will be useful, but 29WITHOUT ANY WARRANTY; without even the implied warranty of 30MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General 31Public License for more details. 32 33 You should have received a copy of the GNU General Public License 34along with this program. If not, see <http://www.gnu.org/licenses/>. 35 36 37File: autogen.info, Node: Common Attributes, Next: Immediate Action, Prev: Required Attributes, Up: option attributes 38 397.5.5.2 Common Option Attributes 40................................ 41 42These option attributes are optional. Any that do appear in the 43definition of a flag, may appear only once. 44 45'value' 46 The flag character to specify for traditional option flags, e.g., 47 '-L'. 48 49'max' 50 Maximum occurrence count (invalid if DISABLE present). The default 51 maximum is 1. 'NOLIMIT' can be used for the value, otherwise it 52 must be a number or a '#define' that evaluates to a number. 53 54'min' 55 Minimum occurrence count. If present, then the option *must* 56 appear on the command line. Do not define it with the value zero 57 (0). 58 59'must-set' 60 If an option must be specified, but it need not be specified on the 61 command line, then specify this attribute for the option. 62 63'deprecated' 64 There are two effects to this attribute: the usage text will not 65 show the option, and the generated documentation will mark it with: 66 _NOTE: THIS OPTION IS DEPRECATED_. 67 68'disable' 69 Prefix for disabling (inverting sense of) the option. Only useful 70 if long option names are being processed. When an option has this 71 attribute, the test 'ENABLED_OPT(OPTNAME)' is false when either of 72 the following is true: 73 * The option has not been specified and the 'enable' attribute 74 has not been specified. 75 * The option has been specified with this disabling prefix. 76 To detect that the option has been specified with the disabling 77 prefix, you must use: 78 HAVE_OPT(OPTNAME) && ! ENABLED_OPT(OPTNAME) 79 80'enable' 81 Long-name prefix for enabling the option (invalid if DISABLE *not* 82 present). Only useful if long option names are being processed. 83 84'enabled' 85 If default is for option being enabled. (Otherwise, the 86 OPTST_DISABLED bit is set at compile time.) Only useful if the 87 option can be disabled. 88 89'ifdef' 90'ifndef' 91'omitted-usage' 92 If an option is relevant on certain platforms or when certain 93 features are enabled or disabled, you can specify the compile time 94 flag used to indicate when the option should be compiled in or out. 95 For example, if you have a configurable feature, 'mumble' that is 96 indicated with the compile time define, 'WITH_MUMBLING', then add: 97 98 ifdef = WITH_MUMBLING; 99 100 Take care when using these. There are several caveats: 101 102 * The case and spelling must match whatever is specified. 103 * Do not confuse these attributes with the AutoGen directives of 104 the same names, *Note Directives::. These cause C 105 preprocessing directives to be inserted into the generated C 106 text. 107 * Only one of 'ifdef' and 'ifndef' may apply to any one option. 108 * The 'VALUE_OPT_' values are '#define'-d. If 'WITH_MUMBLING' 109 is not defined, then the associated 'VALUE_OPT_' value will 110 not be '#define'-d either. So, if you have an option named, 111 'MUMBLING' that is active only if 'WITH_MUMBLING' is 112 '#define'-d, then 'VALUE_OPT_MUMBLING' will be '#define'-d iff 113 'WITH_MUMBLING' is '#define'-d. Watch those switch 114 statements. 115 * If you specify 'omitted-usage', then the option will be 116 recognized as disabled when it is configured out of the build, 117 but will yield the message, "This option has been disabled." 118 You may specify an alternate message by giving 'omitted-usage' 119 a string value. e.g.: 120 omitted-usage = 'you cannot do this'; 121 122'no-command' 123 This option specifies that the option is not allowed on the command 124 line. Such an option may not take a 'value' (flag character) 125 attribute. The program must have the 'homerc' (*note program 126 attributes::) option set. 127 128 129File: autogen.info, Node: Immediate Action, Next: Option Conflict Attributes, Prev: Common Attributes, Up: option attributes 130 1317.5.5.3 Immediate Action Attributes 132................................... 133 134Certain options may need to be processed early. For example, in order 135to suppress the processing of configuration files, it is necessary to 136process the command line option '--no-load-opts' *before* the config 137files are processed. To accommodate this, certain options may have 138their enabled or disabled forms marked for immediate processing. The 139consequence of this is that they are processed ahead of all other 140options in the reverse of normal order. 141 142 Normally, the first options processed are the options specified in 143the first 'homerc' file, followed by then next 'homerc' file through to 144the end of config file processing. Next, environment variables are 145processed and finally, the command line options. The later options 146override settings processed earlier. That actually gives them higher 147priority. Command line immediate action options actually have the 148lowest priority of all. They would be used only if they are to have an 149effect on the processing of subsequent options. 150 151'immediate' 152 Use this option attribute to specify that the enabled form of the 153 option is to be processed immediately. The 'help' and 'more-help' 154 options are so specified. They will also call 'exit()' upon 155 completion, so they *do* have an effect on the processing of the 156 remaining options :-). 157 158'immed-disable' 159 Use this option attribute to specify that the disabled form of the 160 option is to be processed immediately. The 'load-opts' option is 161 so specified. The '--no-load-opts' command line option will 162 suppress the processing of config files and environment variables. 163 Contrariwise, the '--load-opts' command line option is processed 164 normally. That means that the options specified in that file will 165 be processed after all the 'homerc' files and, in fact, after 166 options that precede it on the command line. 167 168'also' 169 If either the 'immediate' or the 'immed-disable' attributes are set 170 to the string, 'also', then the option will actually be processed 171 twice: first at the immediate processing phase and again at the 172 normal time. 173 174 175File: autogen.info, Node: Option Conflict Attributes, Next: opt-attr settable, Prev: Immediate Action, Up: option attributes 176 1777.5.5.4 Option Conflict Attributes 178.................................. 179 180These attributes may be used as many times as you need. They are used 181at the end of the option processing to verify that the context within 182which each option is found does not conflict with the presence or 183absence of other options. 184 185 This is not a complete cover of all possible conflicts and 186requirements, but it simple to implement and covers the more common 187situations. 188 189'flags-must' 190 one entry for every option that *must* be present when this option 191 is present 192 193'flags-cant' 194 one entry for every option that *cannot* be present when this 195 option is present 196 197 198File: autogen.info, Node: opt-attr settable, Next: opt-attr no-preset, Prev: Option Conflict Attributes, Up: option attributes 199 2007.5.5.5 Program may set option 201.............................. 202 203If the option can be set outside of option processing, specify 204'settable'. If this attribute is defined, special macros for setting 205this particular option will be inserted into the interface file. For 206example, 'TEMPL_DIRS' is a settable option for AutoGen, so a macro named 207'SET_OPT_TEMPL_DIRS(a)' appears in the interface file. This attribute 208interacts with the DOCUMENTATION attribute. 209 210 211File: autogen.info, Node: opt-attr no-preset, Next: opt-attr equivalence, Prev: opt-attr settable, Up: option attributes 212 2137.5.5.6 Option cannot be pre-configured 214....................................... 215 216If presetting this option is not allowed, specify 'no-preset'. (Thus, 217environment variables and values set in configuration files will be 218ignored.) 219 220 221File: autogen.info, Node: opt-attr equivalence, Next: opt-attr aliases, Prev: opt-attr no-preset, Up: option attributes 222 2237.5.5.7 Option Equivalence Class 224................................ 225 226Generally, when several options are mutually exclusive and basically 227serve the purpose of selecting one of several processing modes, specify 228the 'equivalence' attribute. These options will be considered an 229equivalence class. Sometimes, it is just easier to deal with them as 230such. All members of the equivalence class must contain the same 231equivalenced-to option, including the equivalenced-to option itself. 232Thus, it must be a class member. 233 234 For an option equivalence class, there is a single occurrence counter 235for the class. It can be referenced with the interface macro, 236'COUNT_OPT(BASE_OPTION)', where BASE_OPTION is the equivalenced-to 237option name. 238 239 Also, please take careful note: since the options are mapped to the 240equivalenced-to option descriptor, any option argument values are mapped 241to that descriptor also. Be sure you know which "equivalent option" was 242selected before getting an option argument value! 243 244 During the presetting phase of option processing (*note Presetting 245Options::), equivalenced options may be specified. However, if 246different equivalenced members are specified, only the last instance 247will be recognized and the others will be discarded. A conflict error 248is indicated only when multiple different members appear on the command 249line itself. 250 251 As an example of where equivalenced options might be useful, 252'cpio(1)' has three options '-o', '-i', and '-p' that define the 253operational mode of the program ('create', 'extract' and 'pass-through', 254respectively). They form an equivalence class from which one and only 255one member must appear on the command line. If 'cpio' were an 256AutoOpt-ed program, then each of these option definitions would contain: 257 258 equivalence = create; 259 260 and the program would be able to determine the operating mode with 261code that worked something like this: 262 263 switch (WHICH_IDX_CREATE) { 264 case INDEX_OPT_CREATE: ... 265 case INDEX_OPT_EXTRACT: ... 266 case INDEX_OPT_PASS_THROUGH: ... 267 default: /* cannot happen */ 268 } 269 270 271File: autogen.info, Node: opt-attr aliases, Next: opt-attr default option, Prev: opt-attr equivalence, Up: option attributes 272 2737.5.5.8 Option Aliasing 274....................... 275 276Sometimes, for backwards compatibility or tradition or just plain 277convenience, it works better to define one option as a pure alias for 278another option. For such situations, provide the following pieces of 279information: 280 flag = { 281 name = aliasing-option-name; 282 value = aliasing-flag-char; // optional ! 283 aliases = aliased-to-option; 284 }; 285 Do not provide anything else. The usage text for such an option will 286be: 287 This is an alias for aliased-to-option 288 289 290File: autogen.info, Node: opt-attr default option, Next: opt-attr documentation, Prev: opt-attr aliases, Up: option attributes 291 2927.5.5.9 Default Option 293...................... 294 295If your program processes its arguments in named option mode (See 296'long-opts' in *note program attributes::), then you may select *one* of 297your options to be the default option. Do so by using attribute 298'default' with one of the options. The option so specified must have an 299'arg-type' (*note Option Arguments::) specified, but not the 300'arg-optional' (*note arg-optional::) attribute. That is to say, the 301option argument must be required. 302 303 If you have done this, then any arguments that do not match an option 304name and do not contain an equal sign ('=') will be interpreted as an 305option argument to the default option. 306 307 308File: autogen.info, Node: opt-attr documentation, Next: opt-attr translators, Prev: opt-attr default option, Up: option attributes 309 3107.5.5.10 Option Sectioning Comment 311.................................. 312 313This attribute means the option exists for the purpose of separating 314option description text in the usage output and texi documentation. 315Without this attribute, every option is a separate node in the texi 316docs. With this attribute, the documentation options become texi doc 317nodes and the options are collected under them. Choose the name 318attribute carefully because it will appear in the texi documentation. 319 320 Libraries may also choose to make it settable so that the library can 321determine which command line option is the first one that pertains to 322the library. 323 324 If the 'documentation' attribute is present, then all other 325attributes are disabled except 'settable', 'call-proc' and 'flag-code'. 326'settable' must be and is only specified if 'call-proc', 'extract-code' 327or 'flag-code' has been specified. When present, the 'descrip' 328attribute will be displayed only when the '--help' option has been 329specified. It will be displayed flush to the left hand margin and may 330consist of one or more lines of text, filled to 72 columns. 331 332 The name of the option will not be printed in the help text. It 333will, however, be printed as section headers in the texi documentation. 334If the attribute is given a non-empty value, this text will be 335reproduced in the man page and texi doc immediately after the 'descrip' 336text. 337 338 339File: autogen.info, Node: opt-attr translators, Prev: opt-attr documentation, Up: option attributes 340 3417.5.5.11 Translator Notes 342......................... 343 344If you need to give the translators a special note about a particular 345option, please use the 'translators' attribute. The attribute text will 346be emitted into the generated '.c' text where the option related strings 347get defined. To make a general comment about all of the option code, 348add comments to an 'include' attribute (*note program attributes::). Do 349*not* use this attribute globally, or it will get emitted into every 350option definition block. 351 352 353File: autogen.info, Node: Option Arguments, Next: Option Argument Handling, Prev: option attributes, Up: Option Definitions 354 3557.5.6 Option Argument Specification 356----------------------------------- 357 358Command line options come in three flavors: options that do not take 359arguments, those that do and those that may. Without an "arg-type" 360attribute, AutoOpts will not process an argument to an option. If 361"arg-type" is specified and "arg-optional" is also specified, then the 362next command line token will be taken to be an argument, unless it looks 363like the name of another option. 364 365 If the argument type is specified to be anything other than 366"str[ing]", then AutoOpts will specify a callback procedure to handle 367the argument. Some of these procedures will be created and inserted 368into the generated '.c' file, and others are already built into the 369'libopts' library. Therefore, if you write your own callback procedure 370(*note Option Argument Handling::), then you must either not specify an 371"arg-type" attribute, or else specify it to be of type "str[ing]". Your 372callback function will be able to place its own restrictions on what 373that string may contain or represent. 374 375 Option argument handling attributes depend upon the value set for the 376'arg-type' attribute. It specifies the type of argument the option will 377take. If not present, the option cannot take an argument. If present, 378it must be an entry in the following table. The first three letters is 379sufficient. 380 381* Menu: 382 383* arg-type string:: Arg Type String 384* arg-type number:: Arg Type Number 385* arg-type boolean:: Arg Type Boolean 386* arg-type keyword:: Arg Type Keyword 387* arg-type set membership:: Arg Type Set Membership 388* arg-type hierarchy:: Arg Type Hierarchical 389* arg-type file name:: Arg Type File Name 390* arg-type time-duration:: Arg Type Time Duration 391* arg-type time-date:: Arg Type Time and Date 392 393Supporting attributes for particular argument types: 394 395* arg-keyword:: Keyword list 396* arg-optional:: Option Argument Optional 397* arg-default:: Default Option Argument Value 398 399 400File: autogen.info, Node: arg-type string, Next: arg-type number, Up: Option Arguments 401 4027.5.6.1 Arg Type String 403....................... 404 405'arg-type = string;' 406 407 The argument may be any arbitrary string, though your program or 408option callback procedure may place additional constraints upon it. 409 410 411File: autogen.info, Node: arg-type number, Next: arg-type boolean, Prev: arg-type string, Up: Option Arguments 412 4137.5.6.2 Arg Type Number 414....................... 415 416'arg-type = number;' 417 418 The argument must be a correctly formed integer, without any trailing 419U's or L's. AutoOpts contains a library procedure to convert the string 420to a number. If you specify range checking with 'arg-range' (see 421below), then AutoOpts produces a special purpose procedure for this 422option. 423 424'scaled' 425 'scaled' marks the option so that suffixes of 'k', 'K', 'm', 'M', 426 'g', 'G', 't', and 'T' will multiply the given number by a power of 427 1000 or 1024. Lower case letters scale by a power of 1000 and 428 upper case scale by a power of 1024. 429 430'arg-range' 431 'arg-range' is used to create a callback procedure for validating 432 the range of the option argument. It must match one of the range 433 entries. Each 'arg-range' should consist of either an integer by 434 itself or an integer range. The integer range is specified by one 435 or two integers separated by the two character sequence, '->'. Be 436 sure to quote the entire range string. The definitions parser will 437 not accept the range syntax as a single string token. 438 439 The generated procedure imposes the range constraints as follows: 440 * A number by itself will match that one value. 441 * The high end of the range may not be 'INT_MIN', both for 442 obvious reasons and because that value is used to indicate a 443 single-valued match. 444 * An omitted lower value implies a lower bound of INT_MIN. 445 * An omitted upper value implies a upper bound of INT_MAX. 446 * The argument value is required. It may not be optional. 447 * The value must match one of the entries. If it can match more 448 than one, then you have redundancies, but no harm will come of 449 it. 450 451 452File: autogen.info, Node: arg-type boolean, Next: arg-type keyword, Prev: arg-type number, Up: Option Arguments 453 4547.5.6.3 Arg Type Boolean 455........................ 456 457'arg-type = boolean;' 458 459 The argument will be interpreted and always yield either AG_TRUE or 460AG_FALSE. False values are the empty string, the number zero, or a 461string that starts with 'f', 'F', 'n' or 'N' (representing False or No). 462Anything else will be interpreted as True. 463 464 465File: autogen.info, Node: arg-type keyword, Next: arg-type set membership, Prev: arg-type boolean, Up: Option Arguments 466 4677.5.6.4 Arg Type Keyword 468........................ 469 470'arg-type = keyword;' 471 472 The argument must match a specified list of strings (*note 473arg-keyword::). Assuming you have named the option, 'optn-name', the 474strings will be converted into an enumeration of type 'te_Optn_Name' 475with the values 'OPTN_NAME_KEYWORD'.* If you have *not* specified a 476default value, the value 'OPTN_NAME_UNDEFINED' will be inserted with the 477value zero. The option will be initialized to that value. You may now 478use this in your code as follows: 479 480 te_Optn_Name opt = OPT_VALUE_OPTN_NAME; 481 switch (opt) { 482 case OPTN_NAME_UNDEFINED: /* undefined things */ break; 483 case OPTN_NAME_KEYWORD: /* `keyword' things */ break; 484 default: /* utterly impossible */ ; 485 } 486 487 AutoOpts produces a special purpose procedure for this option. You 488may not specify an alternate handling procedure. 489 490 If you have need for the string name of the selected keyword, you may 491obtain this with the macro, 'OPT_OPTN_NAME_VAL2STR(val)'. The value you 492pass would normally be 'OPT_VALUE_OPTN_NAME', but anything with numeric 493value that is legal for 'te_Optn_Name' may be passed. Anything out of 494range will result in the string, '"*INVALID*"' being returned. The 495strings are read only. It may be used as in: 496 497 te_Optn_Name opt = OPT_VALUE_OPTN_NAME; 498 printf( "you selected the %s keyword\n", 499 OPT_OPTN_NAME_VAL2STR(opt) ); 500 501 * Note: you may replace the 'OPTN_NAME' enumeration prefix with 502another prefix by specifying a 'prefix-enum' attribute. 503 504 Finally, users may specify the argument either by name or by number. 505Since the numeric equivalents change by having new entries inserted into 506the keyword list, this would not be a recommended practice. However, 507either '-1' or '~0' will always be equivalent to specifying the last 508keyword. 509 510 511File: autogen.info, Node: arg-type set membership, Next: arg-type hierarchy, Prev: arg-type keyword, Up: Option Arguments 512 5137.5.6.5 Arg Type Set Membership 514............................... 515 516'arg-type = set;' 517 518 The argument must be a list of names each of which must match the 519strings "'all'", "'none'" or one of the keywords (*note arg-keyword::) 520specified for this option. 'all' will turn on all membership bits and 521'none' will turn them all off. Specifying one of the keywords will set 522the corresponding set membership bit on (or off, if negated) . Literal 523numbers may also be used and may, thereby, set or clear more than one 524bit. 525 526 The membership result starts with the previous (or initialized) 527result. To clear previous results, either start the membership string 528with 'none +' or with the equals character ('='). To invert (bit flip) 529the final result (regardless of whether the previous result is carried 530over or not), start the string with a carat character ('^'). If you 531wish to invert the result and start without a carried over value, use 532one of the following: '=^' or '^none+'. These are equivalent. 533 534 The list of names or numbers must be separated by one of the 535following characters: '+-|!,' or whitespace. The comma is equivalent to 536whitespace, except that only one may appear between two entries and it 537may not appear in conjunction with the OR bar ('|'). The '+|' leading 538characters or unadorned name signify adding the next named bit to the 539mask, and the '-!' leading characters indicate removing it. 540 541 The number of keywords allowed is constrained by the number of bits 542in a pointer, as the bit set is kept in a 'void *' pointer. 543 544 If, for example, you specified 'first' in your list of keywords, then 545you can use the following code to test to see if either 'first' or 'all' 546was specified: 547 548 uintptr_t opt = OPT_VALUE_OPTN_NAME; 549 if (opt & OPTN_NAME_FIRST) 550 /* OPTN_NAME_FIRST bit was set */ ; 551 552 AutoOpts produces a special purpose procedure for this option. To 553set multiple bits as the default (initial) value, you must specify an 554initial numeric value (which might become inaccurate over time), or else 555specify 'arg-default' multiple times. Do not specify a series of names 556conjoined with '+' symbols as the value for any of the 'arg-default' 557attributes. That works for option parsing, but not for the option code 558generation. 559 560 561File: autogen.info, Node: arg-type hierarchy, Next: arg-type file name, Prev: arg-type set membership, Up: Option Arguments 562 5637.5.6.6 Arg Type Hierarchical 564............................. 565 566'arg-type = hierarchy;' 567'arg-type = nested;' 568 569 This denotes an option with a structure-valued argument, a.k.a. 570'subopts' in 'getopts' terminology. The argument is parsed and the 571values made available to the program via the find and find next calls 572(*Note libopts-optionFindValue::, *Note libopts-optionGetValue::, and 573*note libopts-optionFindNextValue::). 574 575 tOptionValue * val = optionGetValue(VALUE_OPT_OPTN_NAME, "name"); 576 while (val != NULL) { 577 process(val); 578 val = optionNextValue(VALUE_OPT_OPTN_NAME, val); 579 if (wrong_name(val, "name")) 580 break; 581 } 582 583 584File: autogen.info, Node: arg-type file name, Next: arg-type time-duration, Prev: arg-type hierarchy, Up: Option Arguments 585 5867.5.6.7 Arg Type File Name 587.......................... 588 589'arg-type = file;' 590 591 This argument type will have some validations on the argument and, 592optionally, actually open the file. You must specify several additonal 593attributes for the option: 594 595'file-exists' 596 If not specified or empty, then the directory portion of the name 597 is checked. The directory must exist or the argument is rejected 598 and the usage procedure is invoked. 599 600 Otherwise, both the directory as above and the full name is tested 601 for existence. If the value begins with the two letters 'no', then 602 the file must not pre-exist. Otherwise, the file is expected to 603 exist. 604 605'open-file' 606 If not specified or empty, the file is left alone. If the value 607 begins with the four letters 'desc'[riptor], then 'open(2)' is used 608 and 'optArg.argFd' is set. Otherwise, the file is opened with 609 'fopen' and 'optArg.argFp' is set. 610 611'file-mode' 612 If 'open-file' is set and not empty, then you must specify the open 613 mode. Set the value to the flag bits or mode string as appropriate 614 for the open type. 615 616 617File: autogen.info, Node: arg-type time-duration, Next: arg-type time-date, Prev: arg-type file name, Up: Option Arguments 618 6197.5.6.8 Arg Type Time Duration 620.............................. 621 622'arg-type = time-duration;' 623 624 The argument will be converted into a number of seconds. It may be a 625multi-part number with different parts being multiplied into a seconds 626value and added into the final result. Valid forms are in the table 627below. Upper cased letters represent numbers that must be used in the 628expressions. 629 630'[[HH:]MM:]SS' 631 'HH' is multiplied by '3600' and 'MM' multiplied by '60' before 632 they are added to 'SS'. This time specification may not be 633 followed by any other time specs. 'HH' and 'MM' are both optional, 634 though 'HH' cannot be specified without 'MM'. 635 636'DAYS d' 637 'DAYS' is multiplied by the number of seconds in a day. This value 638 may be followed by (and added to) values specified by 'HH:MM:SS' or 639 the suffixed values below. If present, it must always be first. 640 641'HRS h' 642 'HRS' is multiplied by the number of seconds in an hour. This 643 value may be followed by (and added to) values specified by 'MM:SS' 644 or the suffixed values below. 645 646'MINS m' 647 'MINS' is multiplied by the number of seconds in a minute. This 648 value may be followed by (and added to) a count of seconds. 649 650'SECS s' 651 This value can only be the last value in a time specification. The 652 's' suffix is optional. 653 654 5 d 1:10:05 ==> 5 days + 1 hour 10 minutes and 5 seconds 655 5 d 1 h 10 m 5 ==> yields: 436205 seconds 656 5d1h10m5s ==> same result -- spaces are optional. 657 658 When saved into a config file, the value will be stored as a simple 659count of seconds. There are actually more (many) accepted time duration 660strings. The full documentation can be found with ISO-8601 661documentation and the more extedded documentation when 662'parse_duration()' becomes more widely available. 663 664 665File: autogen.info, Node: arg-type time-date, Next: arg-keyword, Prev: arg-type time-duration, Up: Option Arguments 666 6677.5.6.9 Arg Type Time and Date 668.............................. 669 670'arg-type = time-date;' 671 672 The argument will be converted into the number of seconds since the 673epoch. The conversion rules are very complicated, please see the 674'getdate_r(3GNU)' man page. There are some additional restrictions: 675 676 1. Your project must be compiled with 'PKGDATADIR' defined and naming 677 a valid directory. 678 2. The 'DATEMSK' environment variable will be set to the 'datemsk' 679 file within that directory. 680 681 If that file is not accessible for any reason, the string will be 682parsed as a time duration (*note arg-type time-duration::) instead of a 683specific date and time. 684 685 686File: autogen.info, Node: arg-keyword, Next: arg-optional, Prev: arg-type time-date, Up: Option Arguments 687 6887.5.6.10 Keyword list 689..................... 690 691If the 'arg-type' is 'keyword' (*note arg-type keyword::) or 692'set-membership' (*note arg-type set membership::), then you must 693specify the list of keywords by a series of 'keyword' entries. The 694interface file will contain values for '<OPTN_NAME>_<KEYWORD>' for each 695keyword entry. 'keyword' option types will have an enumeration and 696'set-membership' option types will have a set of unsigned bits 697'#define'-d. 698 699 If the 'arg-type' is specifically 'keyword', you may also add special 700handling code with a 'extra-code' attribute. After 701'optionEnumerationVal' has converted the input string into an 702enumeration, you may insert code to process this enumeration value 703('pOptDesc->optArg.argEnum'). 704 705 706File: autogen.info, Node: arg-optional, Next: arg-default, Prev: arg-keyword, Up: Option Arguments 707 7087.5.6.11 Option Argument Optional 709................................. 710 711The 'arg-optional' attribute indicates that the argument to the option 712is optional (need not be specified on the command line). This is only 713valid if the ARG-TYPE is 'string' (*note arg-type string::) or 'keyword' 714(*note arg-type keyword::). If it is 'keyword', then this attribute may 715also specify the default keyword to assume when the argument is not 716supplied. If left empty, ARG-DEFAULT (*note arg-default::) or the 717zero-valued keyword will be used. 718 719 The syntax rules for identifying the option argument are: 720 * If the option is specified with a flag character and there is a 721 character following the flag character, then string following that 722 flag character is the option argument. 723 * If the flag character is the last character in an argument, then 724 the first character of the next argument is examined. If it is a 725 hyphen, then the option is presumed to not have an argument. 726 Otherwise, the entire next argument is the argument for the option. 727 * If the option is specified with a long option name and that name is 728 ended with an equal sign character ('='), then everything after 729 that character is the option argument. 730 * If the long name is ended by the end of the argument, then the 731 first character of the next argument is examined, just as with the 732 flag character ending an argument string. 733 734 This is overridden and the options are required if the libopts 735library gets configured with '--disable-optional-args'. 736 737 738File: autogen.info, Node: arg-default, Prev: arg-optional, Up: Option Arguments 739 7407.5.6.12 Default Option Argument Value 741...................................... 742 743This specifies the default option argument value to be used when the 744option is not specified or preset. You may specify multiple 745'arg-default' values if the argument type is 'set membership'. 746 747 748File: autogen.info, Node: Option Argument Handling, Next: Internationalizing Options, Prev: Option Arguments, Up: Option Definitions 749 7507.5.7 Option Argument Handling 751------------------------------ 752 753AutoOpts will either specify or automatically generate callback 754procedures for options that take specialized arguments. The only option 755argument types that are not specialized are plain string arguments and 756no argument at all. For options that fall into one of those two 757categories, you may specify your own callback function, as specified 758below. If you do this and if you specify that options are resettable 759(*note automatic options::), then your option handling code *must* look 760for the 'OPTST_RESET' bit in the 'fOptState' field of the option 761descriptor. 762 763 If the option takes a string argument, then the 'stack-arg' attribute 764can be used to specify that the option is to be handled by the 'libopts' 765'stackOptArg()' and 'unstackOptArg()' library procedures (see below). 766In this case, you may not provide option handling code. 767 768 Finally, 'documentation' options (*note opt-attr documentation::) may 769also be marked as 'settable' (*note opt-attr settable::) and have 770special callback functions (either 'flag-code', 'extract-code', or 771'call-proc'). 772 773'flag-code' 774 statements to execute when the option is encountered. This may be 775 used in conjunction with option argument types that cause AutoOpts 776 to emit handler code. If you do this, the 'flag-code' with index 777 zero (0) is emitted into the handler code _before_ the argument is 778 handled, and the entry with index one (1) is handled afterward. 779 780 The generated procedure will be laid out something like this: 781 782 static void 783 doOpt<name>(tOptions* pOptions, tOptDesc* pOptDesc) 784 { 785 <flag-code[0]> 786 <AutoOpts defined handler code> 787 <flag-code[1]> 788 } 789 790 Only certain fields within the 'tOptions' and 'tOptDesc' structures 791 may be accessed. *Note Option Processing Data::. When writing 792 this code, you must be very careful with the 'pOptions' pointer. 793 The handler code is called with this pointer set to special values 794 for handling special situations. Your code must handle them. As 795 an example, look at 'optionEnumerationVal' in 'enum.c'. 796 797'extract-code' 798 This is effectively identical to 'flag-code', except that the 799 source is kept in the output file instead of the definitions file 800 and you cannot use this in conjunction with options with arguments, 801 other than string arguments. 802 803 A long comment is used to demarcate the code. You must not modify 804 that marker. Before regenerating the option code file, the old 805 file is renamed from MUMBLE.c to MUMBLE.c.save. The template will 806 be looking there for the text to copy into the new output file. 807 808'call-proc' 809 external procedure to call when option is encountered. The calling 810 sequence must conform to the sequence defined above for the 811 generated procedure, 'doOpt<name>'. It has the same restrictions 812 regarding the fields within the structures passed in as arguments. 813 *Note Option Processing Data::. 814 815'flag-proc' 816 Name of another option whose 'flag-code' can be executed when this 817 option is encountered. 818 819'stack-arg' 820 Call a special library routine to stack the option's arguments. 821 Special macros in the interface file are provided for determining 822 how many of the options were found ('STACKCT_OPT(NAME)') and to 823 obtain a pointer to a list of pointers to the argument values 824 ('STACKLST_OPT(NAME)'). Obviously, for a stackable argument, the 825 'max' attribute (*note Common Attributes::) needs to be set higher 826 than '1'. 827 828 If this stacked argument option has a disablement prefix, then the 829 entire stack of arguments will be cleared by specifying the option 830 with that disablement prefix. 831 832'unstack-arg' 833 Call a special library routine to remove ('unstack') strings from a 834 'stack-arg' option stack. This attribute must name the option that 835 is to be 'unstacked'. Neither this option nor the stacked argument 836 option it references may be equivalenced to another option. 837 838 839File: autogen.info, Node: Internationalizing Options, Next: documentation attributes, Prev: Option Argument Handling, Up: Option Definitions 840 8417.5.8 Internationalizing Options 842-------------------------------- 843 844Normally, AutoOpts produces usage text that is difficult to translate. 845It is pieced together on the fly using words and phrases scattered 846around here and there, piecing together toe document. This does not 847translate well. 848 849 Incorporated into this package are some ways around the problem. 850First, you should specify the 'full-usage' and 'short-usage' program 851attributes (*note program attributes::). This will enable your 852translators to translate the usage text as a whole. 853 854 Your translators will also be able to translate long option names. 855The option name translations will then become the names searched for 856both on the command line and in configuration files. However, it will 857not affect the names of environment variable names used to configure 858your program. 859 860 If it is considered desireable to keep configuration files in the 'C' 861locale, then several macros are available to suppress or delay the 862translations of option names at run time. These are all disabled if 863'ENABLE_NLS' is not defined at compile time or if 'no-xlate' has been 864set to the value _anything_. These macros *must* be invoked before the 865first invocation of 'optionProcess'. 866 867'OPT_NO_XLAT_CFG_NAMES;' 868'OPT_XLAT_CFG_NAMES;' 869 Disable (or enable) the translations of option names for 870 configuration files. If you enable translation for config files, 871 then they will be translated for command line options. 872 873'OPT_NO_XLAT_OPT_NAMES;' 874'OPT_XLAT_OPT_NAMES;' 875 Disable (or enable) the translations of option names for command 876 line processing. If you disable the translation for command line 877 processing, you will also disable it for configuration file 878 processing. Once translated, the option names will remain 879 translated. 880 881 882File: autogen.info, Node: documentation attributes, Next: automatic options, Prev: Internationalizing Options, Up: Option Definitions 883 8847.5.9 Man and Info doc Attributes 885--------------------------------- 886 887AutoOpts includes AutoGen templates for producing abbreviated man pages 888and for producing the invoking section of an info document. To take 889advantage of these templates, you must add several attributes to your 890option definitions. 891 892* Menu: 893 894* per option attributes:: Per option documentation attributes 895* global option attributes:: Global documentation attributes 896 897 898File: autogen.info, Node: per option attributes, Next: global option attributes, Up: documentation attributes 899 9007.5.9.1 Per option documentation attributes 901........................................... 902 903These attributes are sub-attributes (sub-stanzas) of the 'flag' stanzas. 904 905'arg-name' 906 If an option has an argument, the argument should have a name for 907 documentation purposes. It will default to 'arg-type', but it will 908 likely be clearer with something else like, 'file-name' instead of 909 'string' (the type). 910 911'doc' 912 First, every 'flag' definition _other than_ 'documentation' 913 definitions, must have a 'doc' attribute defined. If the option 914 takes an argument, then it will need an 'arg-name' attribute as 915 well. The 'doc' text should be in plain sentences with minimal 916 formatting. The Texinfo commands '@code', and '@var' will have its 917 enclosed text made into *\fB* entries in the man page, and the 918 '@file' text will be made into *\fI* entries. The 'arg-name' 919 attribute is used to display the option's argument in the man page. 920 921 Options marked with the 'documentation' attribute are for 922 documenting the usage text. All other options should have the 923 'doc' attribute in order to document the usage of the option in the 924 generated man pages. 925 926 Since these blocks of text are inserted into all output forms, any 927 markup text included in these blocks must be massaged for each 928 output format. By default, it is presumed to be 'texi' format. 929 930 931File: autogen.info, Node: global option attributes, Prev: per option attributes, Up: documentation attributes 932 9337.5.9.2 Global documentation attributes 934....................................... 935 936'cmd-section' 937 If your command is a game or a system management command, specify 938 this attribute with the value '5' or '8', respectively. The 939 default is a user command (section 1). 940 941'detail' 942 This attribute is used to add a very short explanation about what a 943 program is used for when the 'title' attribute is insufficient. If 944 there is no 'doc-section' stanza of type 'DESCRIPTION', then this 945 text is used for the man page DESCRIPTION section, too. 946 947'addtogroup' 948 This attribute tells the template that the generated code should be 949 surrounded with the following doxygen comments: 950 /** @file <header-or-code-file-name> 951 * @addtogroup <value-of-addtogroup> 952 * @{ 953 */ 954 and 955 /** @} */ 956 957'option-format' 958 Specify the default markup style for the 'doc' stanzas. By 959 default, it is 'texi', but 'man' and 'mdoc' may also be selected. 960 There are nine converter programs that do a partial job of 961 converting one form of markup into another. 'texi2texi', 'man2man' 962 and 'mdoc2mdoc' work pretty well. 963 964 You may also post process the document by using 'doc-sub' stanzas, 965 see below. 966 967'option-info' 968 This text will be inserted as a lead-in paragraph in the 'OPTIONS' 969 section of the generated man page. 970 971'doc-section' 972 This is a compound attribute that requires three subattributes: 973 974 ds-format 975 This describes the format of the associated 'ds-text' section. 976 'man', 'mdoc' and 'texi' formats are supported. Regardless of 977 the chosen format, the formatting tags in the output text will 978 be converted to 'man' macros for 'man' pages, 'mdoc' macros 979 for 'mdoc' pages, and 'texi' macros for 'texinfo' pages. 980 981 ds-text 982 This is the descriptive text, written according to the rules 983 for 'ds-format' documents. 984 985 ds-type 986 This describes the section type. Basically, the title of the 987 section that will be added to all output documentation. There 988 may be only one 'doc-section' for any given 'ds-type'. If 989 there are duplicates, the results are undefined (it might 990 work, it might not). 991 992 There are five categories of 'ds-type' sections. They are 993 those that the documentation templates would otherwise: 994 1. always create itself, ignoring any 'ds-type's by this 995 name. These are marked, below, as 'ao-only'. 996 2. create, if none was provided. These are marked, 997 'alternate'. 998 3. create, but augment if the 'doc-section' was provided. 999 These are marked, 'augments'. 1000 4. do nothing, but inserts them into the output in a 1001 prescribed order. These are marked, 'known' 1002 5. knows nothing about them. They will be alphabetized and 1003 inserted after the list of leading sections and before 1004 the list of trailing sections. These are not marked 1005 because I don't know their names. 1006 1007 Some of these are emitted by the documentation templates only 1008 if certain conditions are met. If there are conditions, they 1009 are explained below. If there are no conditions, then you 1010 will always see the named section in the output. 1011 1012 The output sections will appear in this order: 1013 'NAME' 1014 'ao-only'. 1015 'SYNOPSIS' 1016 'alternate'. 1017 'DESCRIPTION' 1018 'augments'. 1019 'OPTIONS' 1020 'ao-only'. 1021 'OPTION PRESETS' 1022 'ao-only', if environment presets or configuration file 1023 processing has been specified. 1024 'unknown' 1025 At this point, the unknown, alphabetized sections are 1026 inserted. 1027 'IMPLEMENTATION NOTES' 1028 'known' 1029 'ENVIRONMENT' 1030 'augments', if environment presets have been specified. 1031 'FILES' 1032 'augments', if configuration file processing has been 1033 specified. 1034 'EXAMPLES' 1035 'known' 1036 'EXIT STATUS' 1037 'augments'. 1038 'ERRORS' 1039 'known' 1040 'COMPATIBILITY' 1041 'known' 1042 'SEE ALSO' 1043 'known' 1044 'CONFORMING TO' 1045 'known' 1046 'HISTORY' 1047 'known' 1048 'AUTHORS' 1049 'alternate', if the 'copyright' stanza has either an 1050 'author' or an 'owner' attribute. 1051 'COPYRIGHT' 1052 'alternate', if there is a 'copyright' stanza. 1053 'BUGS' 1054 'augments', if the 'copyright' stanza has an 'eaddr' 1055 attribute. 1056 'NOTES' 1057 'augments'. 1058 1059 Here is an example of a 'doc-section' for a 'SEE ALSO' type. 1060 1061 doc-section = { 1062 ds-type = 'SEE ALSO'; // or anything else 1063 ds-format = 'man'; // or texi or mdoc format 1064 ds-text = <<-_EOText_ 1065 text relevant to this section type, 1066 in the chosen format 1067 _EOText_; 1068 }; 1069 1070'doc-sub' 1071 This attribute will cause the resulting documentation to be 1072 post-processed. This is normally with 'sed', see 'doc-sub-cmd' 1073 below. This attribute has several sub-attributes: 1074 1075 'sub-name' 1076 This is the name of an autogen text definition value, like 1077 'prog-name' or 'version'. In the 'sub-text' field, 1078 occurrences of this name preceded by two less than characters 1079 and followed by two greater than characters will be replaced 1080 by the text value of the definition, e.g. '<<prog-name>>'. 1081 1082 'sub-text' 1083 The text that gets added to the command file for the post 1084 processing program. 1085 1086 'sub-type' 1087 If this command only applies to certain types of output, 1088 specify this with a regular expression that will match one of 1089 the valid output format types, e.g. 'man|mdoc' will match 1090 those two kinds, but not 'texi' output. If omitted, it will 1091 always apply. 1092 1093 For example, if you want to reference the program name in the 'doc' 1094 text for an option common to two programs, put '#PROG#' into the 1095 text. The following will replace all occrrences of '#PROG#' with 1096 the current value for 'prog': 1097 doc-sub = { 1098 sub-name = prog-name; 1099 sub-text = 's/#PROG#/<<prog-name>>/g'; 1100 }; 1101 1102'doc-sub-cmd' 1103 A formatting string for constructing the post-processing command. 1104 The first parameter is the name of the file with editing commands 1105 in it, and the second is the file containing the unprocessed 1106 document. The default value is: 1107 sed -f %s %s 1108 1109 1110File: autogen.info, Node: automatic options, Next: standard options, Prev: documentation attributes, Up: Option Definitions 1111 11127.5.10 Automatically Supported Options 1113-------------------------------------- 1114 1115AutoOpts provides automated support for several options. 'help' and 1116'more-help' are always provided. The others are conditional upon 1117various global program attributes being defined *Note program 1118attributes::. 1119 1120 Below are the option names and default flag values. The flags are 1121activated if and only if at least one user-defined option also uses a 1122flag value. The long names are supported as option names if 'long-opts' 1123has been specified. These option flags may be deleted or changed to 1124characters of your choosing by specifying 'xxx-value = "y";', where 1125'xxx' is one of the option names below and 'y' is either empty or the 1126character of your choice. For example, to change the help flag from '?' 1127to 'h', specify 'help-value = "h";'; and to require that 'save-opts' be 1128specified only with its long option name, specify 'save-opts-value = 1129"";'. 1130 1131 Additionally, the procedure that prints out the program version may 1132be replaced by specifying 'version-proc'. This procedure must be 1133defined to be of external scope (non-static). By default, the AutoOpts 1134library provides 'optionPrintVersion' and it will be the specified 1135callback function in the option definition structure. 1136 1137 With the exception of the 'load-opts' option, none of these 1138automatically supported options will be recognized in configuration 1139files or environment variables. 1140 1141'help -?' 1142 This option will immediately invoke the 'USAGE()' procedure and 1143 display the usage line, a description of each option with its 1144 description and option usage information. This is followed by the 1145 contents of the definition of the 'detail' text macro. 1146 1147'more-help -!' 1148 This option is identical to the 'help' option, except that the 1149 output is passed through a pager program. ('more' by default, or 1150 the program identified by the 'PAGER' environment variable.) 1151 1152'usage -u' 1153 This option must be requested by specifying, 'usage-opt' in the 1154 option definition file. It will produce abbreviated help text to 1155 'stdout' and exit with zero status ('EXIT_SUCCESS'). 1156 1157'version -v' 1158 1159 This will print the program name, title and version. If it is not 1160 followed by anything or is followed by the letter 'v', just the 1161 program name and version will be printed. If followed by the 1162 letter 'c' and a value for 'copyright' and 'owner' have been 1163 provided, then the copyright will be printed, too. If it is 1164 followed by the letter 'n', then the full copyright notice (if 1165 available) will be printed. The 'version' attribute must be 1166 specified in the option definition file. 1167 1168 Because some target platforms discourage optional arguments to 1169 options, the autoopts library can be compiled with 1170 'NO_OPTIONAL_OPT_ARGS' defined. Alternatively, the 'version-type' 1171 attribute can be added to the option definitions and it can specify 1172 which flavor is preferred. In either case, an argument to the 1173 '--version' option will then be disallowed. 1174 1175'load-opts -<' 1176 This option will load options from the named file. They will be 1177 treated exactly as if they were loaded from the normally found 1178 configuration files, but will not be loaded until the option is 1179 actually processed. This can also be used within another 1180 configuration file, causing them to nest. This is the *only* 1181 automatically supported option that can be activated inside of 1182 config files or with environment variables. 1183 1184 Specifying the negated form of the option ('--no-load-opts') will 1185 suppress the processing of configuration files and environment 1186 variables. 1187 1188 This option is activated by specifying one or more 'homerc' 1189 attributes. 1190 1191'save-opts ->' 1192 This option will cause the option state to be printed in the 1193 configuration file format when option processing is done but not 1194 yet verified for consistency. The program will terminate 1195 successfully without running when this has completed. Note that 1196 for most shells you will have to quote or escape the flag character 1197 to restrict special meanings to the shell. 1198 1199 The output file will be the configuration file name (default or 1200 provided by 'rcfile') in the last directory named in a 'homerc' 1201 definition. 1202 1203 This option may be set from within your program by invoking the 1204 "'SET_OPT_SAVE_OPTS(filename)'" macro (*note SET_OPT_name::). 1205 Invoking this macro will set the file name for saving the option 1206 processing state, but the state will *not* actually be saved. You 1207 must call 'optionSaveFile' to do that (*note 1208 libopts-optionSaveFile::). *CAVEAT:* if, after invoking this 1209 macro, you call 'optionProcess', the option processing state will 1210 be saved to this file and 'optionProcess' will not return. You may 1211 wish to invoke 'CLEAR_OPT( SAVE_OPTS )' (*note CLEAR_OPT::) 1212 beforehand if you do need to reinvoke 'optionProcess'. 1213 1214 This option is activated by specifying one or more 'homerc' 1215 attributes. 1216 1217 The method of saving the state may be altered by specifying flags 1218 before the output file name. "Flags" are specified by placing a 1219 list of them before the file name and separating them from the name 1220 with one or two greater-than characters (">"). There are three 1221 flags currently supported: 1222 1223 'default' 1224 If an option has a default value (has not been set), then the 1225 default value is inserted as a comment. 1226 1227 'usage' 1228 Every option that can be processed from the configuration file 1229 will have a comment that contains the usage string that gets 1230 printed with the '--help' text 1231 1232 'update' 1233 Instead of removing the old file and writing a new one, the 1234 output file is kept, but any pre-existing segment labeled with 1235 '<?program prog-name>' is removed. The new program segment is 1236 placed at the end of the file. This flag is implied if the 1237 flags are separated from the file name with doubled 1238 greater-than characters. In other words, 'update,usage > 1239 file-name' and 'usage >> file-name' are identical. 1240 1241'reset-option -R' 1242 This option takes the name of an option for the current program and 1243 resets its state such that it is set back to its original, 1244 compile-time initialized value. If the option state is 1245 subsequently stored (via '--save-opts'), the named option will not 1246 appear in that file. 1247 1248 This option is activated by specifying the 'resettable' attribute. 1249 1250 *BEWARE*: If the 'resettable' attribute is specified, all option 1251 callbacks *must* look for the 'OPTST_RESET' bit in the 'fOptState' 1252 field of the option descriptor. If set, the 'optCookie' and 1253 'optArg' fields will be unchanged from their last setting. When 1254 the callback returns, these fields will be set to their original 1255 values. If you use this feature and you have allocated data 1256 hanging off of the cookie, you need to deallocate it. 1257 1258 1259File: autogen.info, Node: standard options, Prev: automatic options, Up: Option Definitions 1260 12617.5.11 Library of Standard Options 1262---------------------------------- 1263 1264AutoOpts has developed a set of standardized options. You may 1265incorporate these options in your program simply by _first_ adding a 1266'#define' for the options you want, and then the line, 1267 1268 #include stdoptions.def 1269 1270in your option definitions. The supported options are specified thus: 1271 1272 #define DEBUG 1273 #define DIRECTORY 1274 #define DRY_RUN 1275 #define INPUT 1276 #define INTERACTIVE 1277 #define OUTPUT 1278 #define WARN 1279 1280 #define SILENT 1281 #define QUIET 1282 #define BRIEF 1283 #define VERBOSE 1284 1285 By default, only the long form of the option will be available. To 1286specify the short (flag) form, suffix these names with '_FLAG'. e.g., 1287 1288 #define DEBUG_FLAG 1289 1290 '--silent', '--quiet', '--brief' and '--verbose' are related in that 1291they all indicate some level of diagnostic output. These options are 1292all designed to conflict with each other. Instead of four different 1293options, however, several levels can be incorporated by '#define'-ing 1294'VERBOSE_ENUM'. In conjunction with 'VERBOSE', it incorporates the 1295notion of 5 levels in an enumeration: 'silent', 'quiet', 'brief', 1296'informative' and 'verbose'; with the default being 'brief'. 1297 1298 Here is an example program that uses the following set of 1299definitions: 1300 1301 AutoGen Definitions options; 1302 1303 prog-name = default-test; 1304 prog-title = 'Default Option Example'; 1305 homerc = '$$/../share/default-test', '$HOME', '.'; 1306 environrc; 1307 long-opts; 1308 gnu-usage; 1309 usage-opt; 1310 version = '1.0'; 1311 main = { 1312 main-type = shell-process; 1313 }; 1314 #define DEBUG_FLAG 1315 #define WARN_FLAG 1316 #define WARN_LEVEL 1317 #define VERBOSE_FLAG 1318 #define VERBOSE_ENUM 1319 #define DRY_RUN_FLAG 1320 #define OUTPUT_FLAG 1321 #define INPUT_FLAG 1322 #define DIRECTORY_FLAG 1323 #define INTERACTIVE_FLAG 1324 #include stdoptions.def 1325 1326Running a few simple commands on that definition file: 1327 1328 autogen default-test.def 1329 copts="-DTEST_DEFAULT_TEST_OPTS `autoopts-config cflags`" 1330 lopts="`autoopts-config ldflags`" 1331 cc -o default-test ${copts} default-test.c ${lopts} 1332 1333Yields a program which, when run with '--help', prints out: 1334 1335 1336 exit 0 1337 1338 1339File: autogen.info, Node: AutoOpts API, Next: Multi-Threading, Prev: Option Definitions, Up: AutoOpts 1340 13417.6 Programmatic Interface 1342========================== 1343 1344The user interface for access to the argument information is completely 1345defined in the generated header file and in the portions of the 1346distributed file "options.h" that are marked "public". 1347 1348 In the following macros, text marked <NAME> or NAME is the name of 1349the option *in upper case* and *segmented with underscores '_'*. The 1350macros and enumerations defined in the options header (interface) file 1351are used as follows: 1352 1353 To see how these '#define' macros are used in a program, the reader 1354is referred to the several 'opts.h' files included with the AutoGen 1355sources. 1356 1357* Menu: 1358 1359* Option Processing Data:: Data for Option Processing 1360* CLEAR_OPT:: CLEAR_OPT( <NAME> ) - Clear Option Markings 1361* COUNT_OPT:: COUNT_OPT( <NAME> ) - Definition Count 1362* DESC:: DESC( <NAME> ) - Option Descriptor 1363* DISABLE_OPT_name:: DISABLE_OPT_name - Disable an option 1364* ENABLED_OPT:: ENABLED_OPT( <NAME> ) - Is Option Enabled? 1365* ERRSKIP_OPTERR:: ERRSKIP_OPTERR - Ignore Option Errors 1366* ERRSTOP_OPTERR:: ERRSTOP_OPTERR - Stop on Errors 1367* HAVE_OPT:: HAVE_OPT( <NAME> ) - Have this option? 1368* ISSEL_OPT:: ISSEL_OPT( <NAME> ) - Is Option Selected? 1369* ISUNUSED_OPT:: ISUNUSED_OPT( <NAME> ) - Never Specified? 1370* OPTION_CT:: OPTION_CT - Full Count of Options 1371* OPT_ARG:: OPT_ARG( <NAME> ) - Option Argument String 1372* OPT_NO_XLAT_CFG_NAMES:: OPT_NO_XLAT_CFG_NAMES - option name xlation 1373* OPT_NO_XLAT_OPT_NAMES:: OPT_NO_XLAT_OPT_NAMES - option name xlation 1374* OPT_VALUE_name:: OPT_VALUE_name - Option Argument Value 1375* OPT_XLAT_CFG_NAMES:: OPT_XLAT_CFG_NAMES - option name xlation 1376* OPT_XLAT_OPT_NAMES:: OPT_XLAT_OPT_NAMES - option name xlation 1377* RESTART_OPT:: RESTART_OPT( n ) - Resume Option Processing 1378* SET_OPT_name:: SET_OPT_name - Force an option to be set 1379* STACKCT_OPT:: STACKCT_OPT( <NAME> ) - Stacked Arg Count 1380* STACKLST_OPT:: STACKLST_OPT( <NAME> ) - Argument Stack 1381* START_OPT:: START_OPT - Restart Option Processing 1382* STATE_OPT:: STATE_OPT( <NAME> ) - Option State 1383* USAGE:: USAGE( exit-code ) - Usage invocation macro 1384* VALUE_OPT_name:: VALUE_OPT_name - Option Flag Value 1385* VERSION:: VERSION - Version and Full Version 1386* WHICH_IDX_name:: WHICH_IDX_name - Which Equivalenced Index 1387* WHICH_OPT_name:: WHICH_OPT_name - Which Equivalenced Option 1388* teOptIndex:: teOptIndex - Option Index and Enumeration 1389* OPTIONS_STRUCT_VERSION:: OPTIONS_STRUCT_VERSION - active version 1390* libopts procedures:: libopts External Procedures 1391 1392 1393File: autogen.info, Node: Option Processing Data, Next: CLEAR_OPT, Up: AutoOpts API 1394 13957.6.1 Data for Option Processing 1396-------------------------------- 1397 1398This section describes the data that may be accessed from within the 1399option processing callback routines. The following fields may be used 1400in the following ways and may be used for read only. The first set is 1401addressed from the 'tOptDesc*' pointer: 1402 1403'optIndex' 1404'optValue' 1405 These may be used by option procedures to determine which option 1406 they are working on (in case they handle several options). 1407 1408'optActualIndex' 1409'optActualValue' 1410 These may be used by option procedures to determine which option 1411 was used to set the current option. This may be different from the 1412 above if the options are members of an equivalence class. 1413 1414'optOccCt' 1415 If AutoOpts is processing command line arguments, then this value 1416 will contain the current occurrence count. During the option 1417 preset phase (reading configuration files and examining environment 1418 variables), the value is zero. 1419 1420'fOptState' 1421 The field may be tested for the following bit values (prefix each 1422 name with 'OPTST_', e.g. 'OPTST_INIT'): 1423 1424 'INIT' 1425 Initial compiled value. As a bit test, it will always yield 1426 FALSE. 1427 1428 'SET' 1429 The option was set via the 'SET_OPT()' macro. 1430 1431 'PRESET' 1432 The option was set via a configuration file. 1433 1434 'DEFINED' 1435 The option was set via a command line option. 1436 1437 'SET_MASK' 1438 This is a mask of flags that show the set state, one of the 1439 above four values. 1440 1441 'EQUIVALENCE' 1442 This bit is set when the option was selected by an 1443 equivalenced option. 1444 1445 'DISABLED' 1446 This bit is set if the option is to be disabled. (Meaning it 1447 was a long option prefixed by the disablement prefix, or the 1448 option has not been specified yet and initializes as 1449 'disabled'.) 1450 1451 As an example of how this might be used, in AutoGen I want to allow 1452 template writers to specify that the template output can be left in 1453 a writable or read-only state. To support this, there is a Guile 1454 function named 'set-writable' (*note SCM set-writable::). Also, I 1455 provide for command options '--writable' and '--not-writable'. I 1456 give precedence to command line and RC file options, thus: 1457 1458 switch (STATE_OPT( WRITABLE )) { 1459 case OPTST_DEFINED: 1460 case OPTST_PRESET: 1461 fprintf(stderr, zOverrideWarn, pCurTemplate->pzFileName, 1462 pCurMacro->lineNo); 1463 break; 1464 1465 default: 1466 if (gh_boolean_p( set ) && (set == SCM_BOOL_F)) 1467 CLEAR_OPT( WRITABLE ); 1468 else 1469 SET_OPT_WRITABLE; 1470 } 1471 1472'pzLastArg' 1473 Pointer to the latest argument string. BEWARE If the argument type 1474 is numeric, an enumeration or a bit mask, then this will be the 1475 argument *value* and not a pointer to a string. 1476 1477 The following two fields are addressed from the 'tOptions*' pointer: 1478 1479'pzProgName' 1480 Points to a NUL-terminated string containing the current program 1481 name, as retrieved from the argument vector. 1482 1483'pzProgPath' 1484 Points to a NUL-terminated string containing the full path of the 1485 current program, as retrieved from the argument vector. (If 1486 available on your system.) 1487 1488 Note these fields get filled in during the first call to 1489'optionProcess()'. All other fields are private, for the exclusive use 1490of AutoOpts code and are subject to change. 1491 1492 1493File: autogen.info, Node: CLEAR_OPT, Next: COUNT_OPT, Prev: Option Processing Data, Up: AutoOpts API 1494 14957.6.2 CLEAR_OPT( <NAME> ) - Clear Option Markings 1496------------------------------------------------- 1497 1498Make as if the option had never been specified. 'HAVE_OPT(<NAME>)' will 1499yield 'FALSE' after invoking this macro. 1500 1501 1502File: autogen.info, Node: COUNT_OPT, Next: DESC, Prev: CLEAR_OPT, Up: AutoOpts API 1503 15047.6.3 COUNT_OPT( <NAME> ) - Definition Count 1505-------------------------------------------- 1506 1507This macro will tell you how many times the option was specified on the 1508command line. It does not include counts of preset options. 1509 1510 if (COUNT_OPT( NAME ) != desired-count) { 1511 make-an-undesirable-message. 1512 } 1513 1514 1515File: autogen.info, Node: DESC, Next: DISABLE_OPT_name, Prev: COUNT_OPT, Up: AutoOpts API 1516 15177.6.4 DESC( <NAME> ) - Option Descriptor 1518---------------------------------------- 1519 1520This macro is used internally by other AutoOpt macros. It is not for 1521general use. It is used to obtain the option description corresponding 1522to its *UPPER CASED* option name argument. This is primarily used in 1523other macro definitions. 1524 1525 1526File: autogen.info, Node: DISABLE_OPT_name, Next: ENABLED_OPT, Prev: DESC, Up: AutoOpts API 1527 15287.6.5 DISABLE_OPT_name - Disable an option 1529------------------------------------------ 1530 1531This macro is emitted if it is both settable and it can be disabled. If 1532it cannot be disabled, it may always be CLEAR-ed (see above). 1533 1534 The form of the macro will actually depend on whether the option is 1535equivalenced to another, and/or has an assigned handler procedure. 1536Unlike the 'SET_OPT' macro, this macro does not allow an option 1537argument. 1538 1539 DISABLE_OPT_NAME; 1540 1541 1542File: autogen.info, Node: ENABLED_OPT, Next: ERRSKIP_OPTERR, Prev: DISABLE_OPT_name, Up: AutoOpts API 1543 15447.6.6 ENABLED_OPT( <NAME> ) - Is Option Enabled? 1545------------------------------------------------ 1546 1547Yields true if the option defaults to disabled and 'ISUNUSED_OPT()' 1548would yield true. It also yields true if the option has been specified 1549with a disablement prefix, disablement value or the 'DISABLE_OPT_NAME' 1550macro was invoked. 1551 1552 1553File: autogen.info, Node: ERRSKIP_OPTERR, Next: ERRSTOP_OPTERR, Prev: ENABLED_OPT, Up: AutoOpts API 1554 15557.6.7 ERRSKIP_OPTERR - Ignore Option Errors 1556------------------------------------------- 1557 1558When it is necessary to continue (return to caller) on option errors, 1559invoke this option. It is reversible. *Note ERRSTOP_OPTERR::. 1560 1561 1562File: autogen.info, Node: ERRSTOP_OPTERR, Next: HAVE_OPT, Prev: ERRSKIP_OPTERR, Up: AutoOpts API 1563 15647.6.8 ERRSTOP_OPTERR - Stop on Errors 1565------------------------------------- 1566 1567After invoking this macro, if 'optionProcess()' encounters an error, it 1568will call 'exit(1)' rather than return. This is the default processing 1569mode. It can be overridden by specifying 'allow-errors' in the 1570definitions file, or invoking the macro *Note ERRSKIP_OPTERR::. 1571 1572 1573File: autogen.info, Node: HAVE_OPT, Next: ISSEL_OPT, Prev: ERRSTOP_OPTERR, Up: AutoOpts API 1574 15757.6.9 HAVE_OPT( <NAME> ) - Have this option? 1576-------------------------------------------- 1577 1578This macro yields true if the option has been specified in any fashion 1579at all. It is used thus: 1580 1581 if (HAVE_OPT( NAME )) { 1582 <do-things-associated-with-opt-name>; 1583 } 1584 1585 1586File: autogen.info, Node: ISSEL_OPT, Next: ISUNUSED_OPT, Prev: HAVE_OPT, Up: AutoOpts API 1587 15887.6.10 ISSEL_OPT( <NAME> ) - Is Option Selected? 1589------------------------------------------------ 1590 1591This macro yields true if the option has been specified either on the 1592command line or via a SET/DISABLE macro. 1593 1594 1595File: autogen.info, Node: ISUNUSED_OPT, Next: OPTION_CT, Prev: ISSEL_OPT, Up: AutoOpts API 1596 15977.6.11 ISUNUSED_OPT( <NAME> ) - Never Specified? 1598------------------------------------------------ 1599 1600This macro yields true if the option has never been specified, or has 1601been cleared via the 'CLEAR_OPT()' macro. 1602 1603 1604File: autogen.info, Node: OPTION_CT, Next: OPT_ARG, Prev: ISUNUSED_OPT, Up: AutoOpts API 1605 16067.6.12 OPTION_CT - Full Count of Options 1607---------------------------------------- 1608 1609The full count of all options, both those defined and those generated 1610automatically by AutoOpts. This is primarily used to initialize the 1611program option descriptor structure. 1612 1613 1614File: autogen.info, Node: OPT_ARG, Next: OPT_NO_XLAT_CFG_NAMES, Prev: OPTION_CT, Up: AutoOpts API 1615 16167.6.13 OPT_ARG( <NAME> ) - Option Argument String 1617------------------------------------------------- 1618 1619The option argument value as a pointer to string. Note that argument 1620values that have been specified as numbers are stored as numbers or 1621keywords. For such options, use instead the 'OPT_VALUE_name' define. 1622It is used thus: 1623 1624 if (HAVE_OPT( NAME )) { 1625 char* p = OPT_ARG( NAME ); 1626 <do-things-with-opt-name-argument-string>; 1627 } 1628 1629 1630File: autogen.info, Node: OPT_NO_XLAT_CFG_NAMES, Next: OPT_NO_XLAT_OPT_NAMES, Prev: OPT_ARG, Up: AutoOpts API 1631 16327.6.14 OPT_NO_XLAT_CFG_NAMES - option name xlation 1633-------------------------------------------------- 1634 1635Invoking this macro will disable the translation of option names only 1636while processing configuration files and environment variables. This 1637must be invoked before the first call to 'optionProcess'.. You need not 1638invoke this if your option definition file contains the attribute 1639assignment, 'no-xlate = opt-cfg;'. 1640 1641 1642File: autogen.info, Node: OPT_NO_XLAT_OPT_NAMES, Next: OPT_VALUE_name, Prev: OPT_NO_XLAT_CFG_NAMES, Up: AutoOpts API 1643 16447.6.15 OPT_NO_XLAT_OPT_NAMES - option name xlation 1645-------------------------------------------------- 1646 1647Invoking this macro will completely disable the translation of option 1648names. This must be invoked before the first call to 'optionProcess'. 1649You need not invoke this if your option definition file contains the 1650attribute assignment, 'no-xlate = opt;'. 1651 1652 1653File: autogen.info, Node: OPT_VALUE_name, Next: OPT_XLAT_CFG_NAMES, Prev: OPT_NO_XLAT_OPT_NAMES, Up: AutoOpts API 1654 16557.6.16 OPT_VALUE_name - Option Argument Value 1656--------------------------------------------- 1657 1658This macro gets emitted only for options that take numeric, keyword or 1659set membership arguments. The macro yields a word-sized integer 1660containing the enumeration, bit set or numeric value for the option 1661argument. 1662 1663 int opt_val = OPT_VALUE_name; 1664 1665 1666File: autogen.info, Node: OPT_XLAT_CFG_NAMES, Next: OPT_XLAT_OPT_NAMES, Prev: OPT_VALUE_name, Up: AutoOpts API 1667 16687.6.17 OPT_XLAT_CFG_NAMES - option name xlation 1669----------------------------------------------- 1670 1671If 'ENABLE_NLS' is defined and 'no-xlate' has been not set to the value 1672_anything_, this macro will cause the translation of option names to 1673happen before starting the processing of configuration files and 1674environment variables. This will change the recognition of options 1675within the '$PROGRAMNAME' environment variable, but will not alter the 1676names used for setting options via '$PROGRAMNAME_name' environment 1677variables. 1678 1679 This must be invoked before the first call to 'optionProcess'. You 1680might need to use this macro if your option definition file contains the 1681attribute assignment, 'no-xlate = opt;' or 'no-xlate = opt-cfg;', and 1682you have determined in some way that you wish to override that. 1683 1684 1685File: autogen.info, Node: OPT_XLAT_OPT_NAMES, Next: RESTART_OPT, Prev: OPT_XLAT_CFG_NAMES, Up: AutoOpts API 1686 16877.6.18 OPT_XLAT_OPT_NAMES - option name xlation 1688----------------------------------------------- 1689 1690If 'ENABLE_NLS' is defined and 'no-xlate' has been not set to the value 1691_anything_, translate the option names before processing the command 1692line options. Long option names may thus be localized. (If the names 1693were translated before configuration processing, they will not be 1694re-translated.) 1695 1696 This must be invoked before the first call to 'optionProcess'. You 1697might need to use this macro if your option definition file contains the 1698attribute assignment, 'no-xlate = opt;' and you have determined in some 1699way that you wish to override that. 1700 1701 1702File: autogen.info, Node: RESTART_OPT, Next: SET_OPT_name, Prev: OPT_XLAT_OPT_NAMES, Up: AutoOpts API 1703 17047.6.19 RESTART_OPT( n ) - Resume Option Processing 1705-------------------------------------------------- 1706 1707If option processing has stopped (either because of an error or 1708something was encountered that looked like a program argument), it can 1709be resumed by providing this macro with the index 'n' of the next option 1710to process and calling 'optionProcess()' again. 1711 1712 int main(int argc, char ** argv) { 1713 for (int ai = 0; ai < argc ;) { 1714 restart: 1715 ai = optionProcess(&progOptions, argc, argv); 1716 for (; ai < argc; ai++) { 1717 char * arg = arg[ai]; 1718 if (*arg == '-') { 1719 RESTART_OPT(ai); 1720 goto restart; 1721 } 1722 process(arg); 1723 } 1724 } 1725 } 1726 1727 If you want a program to operate this way, you might consider 1728specifying a 'for-each' main function (*note for-each main procedure: 1729main for-each.) with the 'interleaved' attribute. It will allow you to 1730process interleaved operands and options from either the command line or 1731when reading them from standard input. 1732 1733 1734File: autogen.info, Node: SET_OPT_name, Next: STACKCT_OPT, Prev: RESTART_OPT, Up: AutoOpts API 1735 17367.6.20 SET_OPT_name - Force an option to be set 1737----------------------------------------------- 1738 1739This macro gets emitted only when the given option has the 'settable' 1740attribute specified. 1741 1742 The form of the macro will actually depend on whether the option is 1743equivalenced to another, has an option argument and/or has an assigned 1744handler procedure. If the option has an argument, then this macro will 1745too. Beware that the argument is not reallocated, so the value must not 1746be on the stack or deallocated in any other way for as long as the value 1747might get referenced. 1748 1749 If you have supplied at least one 'homerc' file (*note program 1750attributes::), this macro will be emitted for the '--save-opts' option. 1751 1752 SET_OPT_SAVE_OPTS( "filename" ); 1753 1754*Note automatic options::, for a discussion of the implications of using 1755this particular example. 1756 1757 1758File: autogen.info, Node: STACKCT_OPT, Next: STACKLST_OPT, Prev: SET_OPT_name, Up: AutoOpts API 1759 17607.6.21 STACKCT_OPT( <NAME> ) - Stacked Arg Count 1761------------------------------------------------ 1762 1763When the option handling attribute is specified as 'stack_arg', this 1764macro may be used to determine how many of them actually got stacked. 1765 1766 Do not use this on options that have not been stacked or has not been 1767specified (the 'stack_arg' attribute must have been specified, and 1768'HAVE_OPT(<NAME>)' must yield TRUE). Otherwise, you will likely seg 1769fault. 1770 1771 if (HAVE_OPT( NAME )) { 1772 int ct = STACKCT_OPT( NAME ); 1773 char** pp = STACKLST_OPT( NAME ); 1774 1775 do { 1776 char* p = *pp++; 1777 do-things-with-p; 1778 } while (--ct > 0); 1779 } 1780 1781 1782File: autogen.info, Node: STACKLST_OPT, Next: START_OPT, Prev: STACKCT_OPT, Up: AutoOpts API 1783 17847.6.22 STACKLST_OPT( <NAME> ) - Argument Stack 1785---------------------------------------------- 1786 1787The address of the list of pointers to the option arguments. The 1788pointers are ordered by the order in which they were encountered in the 1789option presets and command line processing. 1790 1791 Do not use this on options that have not been stacked or has not been 1792specified (the 'stack_arg' attribute must have been specified, and 1793'HAVE_OPT(<OPTION>)' must yield TRUE). Otherwise, you will likely seg 1794fault. 1795 1796 if (HAVE_OPT( NAME )) { 1797 int ct = STACKCT_OPT( NAME ); 1798 char** pp = STACKLST_OPT( NAME ); 1799 1800 do { 1801 char* p = *pp++; 1802 do-things-with-p; 1803 } while (--ct > 0); 1804 } 1805 1806 1807File: autogen.info, Node: START_OPT, Next: STATE_OPT, Prev: STACKLST_OPT, Up: AutoOpts API 1808 18097.6.23 START_OPT - Restart Option Processing 1810-------------------------------------------- 1811 1812This is just a shortcut for RESTART_OPT(1) (*Note RESTART_OPT::.) 1813 1814 1815File: autogen.info, Node: STATE_OPT, Next: USAGE, Prev: START_OPT, Up: AutoOpts API 1816 18177.6.24 STATE_OPT( <NAME> ) - Option State 1818----------------------------------------- 1819 1820If you need to know if an option was set because of presetting actions 1821(configuration file processing or environment variables), versus a 1822command line entry versus one of the SET/DISABLE macros, then use this 1823macro. It will yield one of four values: 'OPTST_INIT', 'OPTST_SET', 1824'OPTST_PRESET' or 'OPTST_DEFINED'. It is used thus: 1825 1826 switch (STATE_OPT( NAME )) { 1827 case OPTST_INIT: 1828 not-preset, set or on the command line. (unless CLEAR-ed) 1829 1830 case OPTST_SET: 1831 option set via the SET_OPT_NAME() macro. 1832 1833 case OPTST_PRESET: 1834 option set via an configuration file or environment variable 1835 1836 case OPTST_DEFINED: 1837 option set via a command line option. 1838 1839 default: 1840 cannot happen :) 1841 } 1842 1843 1844File: autogen.info, Node: USAGE, Next: VALUE_OPT_name, Prev: STATE_OPT, Up: AutoOpts API 1845 18467.6.25 USAGE( exit-code ) - Usage invocation macro 1847-------------------------------------------------- 1848 1849This macro invokes the procedure registered to display the usage text. 1850Normally, this will be 'optionUsage' from the AutoOpts library, but you 1851may select another procedure by specifying 'usage = "proc_name"' program 1852attribute. This procedure must take two arguments first, a pointer to 1853the option descriptor, and second the exit code. The macro supplies the 1854option descriptor automatically. This routine is expected to call 1855'exit(3)' with the provided exit code. 1856 1857 The 'optionUsage' routine also behaves differently depending on the 1858exit code: 1859 1860'EXIT_SUCCESS (the value zero)' 1861 It is assumed that full usage help has been requested. 1862 Consequently, more information is provided than when displaying 1863 usage and exiting with a non-zero exit code. Output will be sent 1864 to 'stdout' and the program will exit with a zero status code. 1865 1866'EX_USAGE (64)' 1867 The abbreviated usage will be printed to 'stdout' and the program 1868 will exit with a zero status code. 'EX_USAGE' may or may not be 1869 64. If your system provides '/usr/include/sysexits.h' that has a 1870 different value, then that value will be used. 1871 1872'any other value' 1873 The abbreviated usage will be printed to stderr and the program 1874 will exit with the provided status code. 1875 1876 1877File: autogen.info, Node: VALUE_OPT_name, Next: VERSION, Prev: USAGE, Up: AutoOpts API 1878 18797.6.26 VALUE_OPT_name - Option Flag Value 1880----------------------------------------- 1881 1882This is a #define for the flag character used to specify an option on 1883the command line. If 'value' was not specified for the option, then it 1884is a unique number associated with the option. 'option value' refers to 1885this value, 'option argument' refers to the (optional) argument to the 1886option. 1887 1888 switch (WHICH_OPT_OTHER_OPT) { 1889 case VALUE_OPT_NAME: 1890 this-option-was-really-opt-name; 1891 case VALUE_OPT_OTHER_OPT: 1892 this-option-was-really-other-opt; 1893 } 1894 1895 1896File: autogen.info, Node: VERSION, Next: WHICH_IDX_name, Prev: VALUE_OPT_name, Up: AutoOpts API 1897 18987.6.27 VERSION - Version and Full Version 1899----------------------------------------- 1900 1901If the 'version' attribute is defined for the program, then a 1902stringified version will be #defined as PROGRAM_VERSION and 1903PROGRAM_FULL_VERSION. PROGRAM_FULL_VERSION is used for printing the 1904program version in response to the version option. The version option 1905is automatically supplied in response to this attribute, too. 1906 1907 You may access PROGRAM_VERSION via 'programOptions.pzFullVersion'. 1908 1909 1910File: autogen.info, Node: WHICH_IDX_name, Next: WHICH_OPT_name, Prev: VERSION, Up: AutoOpts API 1911 19127.6.28 WHICH_IDX_name - Which Equivalenced Index 1913------------------------------------------------ 1914 1915This macro gets emitted only for equivalenced-to options. It is used to 1916obtain the index for the one of the several equivalence class members 1917set the equivalenced-to option. 1918 1919 switch (WHICH_IDX_OTHER_OPT) { 1920 case INDEX_OPT_NAME: 1921 this-option-was-really-opt-name; 1922 case INDEX_OPT_OTHER_OPT: 1923 this-option-was-really-other-opt; 1924 } 1925 1926 1927File: autogen.info, Node: WHICH_OPT_name, Next: teOptIndex, Prev: WHICH_IDX_name, Up: AutoOpts API 1928 19297.6.29 WHICH_OPT_name - Which Equivalenced Option 1930------------------------------------------------- 1931 1932This macro gets emitted only for equivalenced-to options. It is used to 1933obtain the value code for the one of the several equivalence class 1934members set the equivalenced-to option. 1935 1936 switch (WHICH_OPT_OTHER_OPT) { 1937 case VALUE_OPT_NAME: 1938 this-option-was-really-opt-name; 1939 case VALUE_OPT_OTHER_OPT: 1940 this-option-was-really-other-opt; 1941 } 1942 1943 1944File: autogen.info, Node: teOptIndex, Next: OPTIONS_STRUCT_VERSION, Prev: WHICH_OPT_name, Up: AutoOpts API 1945 19467.6.30 teOptIndex - Option Index and Enumeration 1947------------------------------------------------ 1948 1949This enum defines the complete set of options, both user specified and 1950automatically provided. This can be used, for example, to distinguish 1951which of the equivalenced options was actually used. 1952 1953 switch (pOptDesc->optActualIndex) { 1954 case INDEX_OPT_FIRST: 1955 stuff; 1956 case INDEX_OPT_DIFFERENT: 1957 different-stuff; 1958 default: 1959 unknown-things; 1960 } 1961 1962 1963File: autogen.info, Node: OPTIONS_STRUCT_VERSION, Next: libopts procedures, Prev: teOptIndex, Up: AutoOpts API 1964 19657.6.31 OPTIONS_STRUCT_VERSION - active version 1966---------------------------------------------- 1967 1968You will not actually need to reference this value, but you need to be 1969aware that it is there. It is the first value in the option descriptor 1970that you pass to 'optionProcess'. It contains a magic number and 1971version information. Normally, you should be able to work with a more 1972recent option library than the one you compiled with. However, if the 1973library is changed incompatibly, then the library will detect the out of 1974date magic marker, explain the difficulty and exit. You will then need 1975to rebuild and recompile your option definitions. This has rarely been 1976necessary. 1977 1978 1979File: autogen.info, Node: libopts procedures, Prev: OPTIONS_STRUCT_VERSION, Up: AutoOpts API 1980 19817.6.32 libopts External Procedures 1982---------------------------------- 1983 1984These are the routines that libopts users may call directly from their 1985code. There are several other routines that can be called by code 1986generated by the libopts option templates, but they are not to be called 1987from any other user code. The 'options.h' header is fairly clear about 1988this, too. 1989 1990* Menu: 1991 1992* libopts-ao_string_tokenize:: ao_string_tokenize 1993* libopts-configFileLoad:: configFileLoad 1994* libopts-optionFileLoad:: optionFileLoad 1995* libopts-optionFindNextValue:: optionFindNextValue 1996* libopts-optionFindValue:: optionFindValue 1997* libopts-optionFree:: optionFree 1998* libopts-optionGetValue:: optionGetValue 1999* libopts-optionLoadLine:: optionLoadLine 2000* libopts-optionMemberList:: optionMemberList 2001* libopts-optionNextValue:: optionNextValue 2002* libopts-optionOnlyUsage:: optionOnlyUsage 2003* libopts-optionPrintVersion:: optionPrintVersion 2004* libopts-optionPrintVersionAndReturn:: optionPrintVersionAndReturn 2005* libopts-optionProcess:: optionProcess 2006* libopts-optionRestore:: optionRestore 2007* libopts-optionSaveFile:: optionSaveFile 2008* libopts-optionSaveState:: optionSaveState 2009* libopts-optionUnloadNested:: optionUnloadNested 2010* libopts-optionVersion:: optionVersion 2011* libopts-strequate:: strequate 2012* libopts-streqvcmp:: streqvcmp 2013* libopts-streqvmap:: streqvmap 2014* libopts-strneqvcmp:: strneqvcmp 2015* libopts-strtransform:: strtransform 2016 2017 This subsection was automatically generated by AutoGen using 2018extracted information and the aginfo3.tpl template. 2019 2020 2021File: autogen.info, Node: libopts-ao_string_tokenize, Next: libopts-configFileLoad, Up: libopts procedures 2022 20237.6.32.1 ao_string_tokenize 2024........................... 2025 2026tokenize an input string 2027 2028Usage: 2029 token_list_t * res = ao_string_tokenize( string ); 2030Where the arguments are: 2031 Name Type Description 2032 --- --- --------- 2033 string 'char const string to be tokenized 2034 *' 2035 returns token_list_t pointer to a structure that lists each 2036 * token 2037 2038 This function will convert one input string into a list of strings. 2039The list of strings is derived by separating the input based on white 2040space separation. However, if the input contains either single or 2041double quote characters, then the text after that character up to a 2042matching quote will become the string in the list. 2043 2044 The returned pointer should be deallocated with 'free(3C)' when are 2045done using the data. The data are placed in a single block of allocated 2046memory. Do not deallocate individual token/strings. 2047 2048 The structure pointed to will contain at least these two fields: 2049'tkn_ct' 2050 The number of tokens found in the input string. 2051'tok_list' 2052 An array of 'tkn_ct + 1' pointers to substring tokens, with the 2053 last pointer set to NULL. 2054 2055 There are two types of quoted strings: single quoted (''') and double 2056quoted ('"'). Singly quoted strings are fairly raw in that escape 2057characters ('\\') are simply another character, except when preceding 2058the following characters: 2059 \\ double backslashes reduce to one 2060 ' incorporates the single quote into the string 2061 \n suppresses both the backslash and newline character 2062 2063 Double quote strings are formed according to the rules of string 2064constants in ANSI-C programs. 2065 2066 NULL is returned and 'errno' will be set to indicate the problem: 2067 * 'EINVAL' - There was an unterminated quoted string. 2068 * 'ENOENT' - The input string was empty. 2069 * 'ENOMEM' - There is not enough memory. 2070 2071 2072File: autogen.info, Node: libopts-configFileLoad, Next: libopts-optionFileLoad, Prev: libopts-ao_string_tokenize, Up: libopts procedures 2073 20747.6.32.2 configFileLoad 2075....................... 2076 2077parse a configuration file 2078 2079Usage: 2080 const tOptionValue * res = configFileLoad( fname ); 2081Where the arguments are: 2082 Name Type Description 2083 --- --- --------- 2084 fname 'char const the file to load 2085 *' 2086 returns const An allocated, compound value structure 2087 tOptionValue 2088 * 2089 2090 This routine will load a named configuration file and parse the text 2091as a hierarchically valued option. The option descriptor created from 2092an option definition file is not used via this interface. The returned 2093value is "named" with the input file name and is of type 2094"'OPARG_TYPE_HIERARCHY'". It may be used in calls to 2095'optionGetValue()', 'optionNextValue()' and 'optionUnloadNested()'. 2096 2097 If the file cannot be loaded or processed, 'NULL' is returned and 2098ERRNO is set. It may be set by a call to either 'open(2)' 'mmap(2)' or 2099other file system calls, or it may be: 2100 * 'ENOENT' - the file was not found. 2101 * 'ENOMSG' - the file was empty. 2102 * 'EINVAL' - the file contents are invalid - not properly formed. 2103 * 'ENOMEM' - not enough memory to allocate the needed structures. 2104 2105 2106File: autogen.info, Node: libopts-optionFileLoad, Next: libopts-optionFindNextValue, Prev: libopts-configFileLoad, Up: libopts procedures 2107 21087.6.32.3 optionFileLoad 2109....................... 2110 2111Load the locatable config files, in order 2112 2113Usage: 2114 int res = optionFileLoad( opts, prog ); 2115Where the arguments are: 2116 Name Type Description 2117 --- --- --------- 2118 opts 'tOptions *' program options descriptor 2119 2120 prog 'char const program name 2121 *' 2122 returns int 0 -> SUCCESS, -1 -> FAILURE 2123 2124 This function looks in all the specified directories for a 2125configuration file ("rc" file or "ini" file) and processes any found 2126twice. The first time through, they are processed in reverse order 2127(last file first). At that time, only "immediate action" configurables 2128are processed. For example, if the last named file specifies not 2129processing any more configuration files, then no more configuration 2130files will be processed. Such an option in the *first* named directory 2131will have no effect. 2132 2133 Once the immediate action configurables have been handled, then the 2134directories are handled in normal, forward order. In that way, later 2135config files can override the settings of earlier config files. 2136 2137 See the AutoOpts documentation for a thorough discussion of the 2138config file format. 2139 2140 Configuration files not found or not decipherable are simply ignored. 2141 2142 Returns the value, "-1" if the program options descriptor is out of 2143date or indecipherable. Otherwise, the value "0" will always be 2144returned. 2145 2146 2147File: autogen.info, Node: libopts-optionFindNextValue, Next: libopts-optionFindValue, Prev: libopts-optionFileLoad, Up: libopts procedures 2148 21497.6.32.4 optionFindNextValue 2150............................ 2151 2152find a hierarcicaly valued option instance 2153 2154Usage: 2155 const tOptionValue * res = optionFindNextValue( odesc, pPrevVal, name, value ); 2156Where the arguments are: 2157 Name Type Description 2158 --- --- --------- 2159 odesc 'const an option with a nested arg type 2160 tOptDesc *' 2161 pPrevVal 'const the last entry 2162 tOptionValue 2163 *' 2164 name 'char const name of value to find 2165 *' 2166 value 'char const the matching value 2167 *' 2168 returns const a compound value structure 2169 tOptionValue 2170 * 2171 2172 This routine will find the next entry in a nested value option or 2173configurable. It will search through the list and return the next entry 2174that matches the criteria. 2175 2176 The returned result is NULL and errno is set: 2177 * 'EINVAL' - the 'pOptValue' does not point to a valid hierarchical 2178 option value. 2179 * 'ENOENT' - no entry matched the given name. 2180 2181 2182File: autogen.info, Node: libopts-optionFindValue, Next: libopts-optionFree, Prev: libopts-optionFindNextValue, Up: libopts procedures 2183 21847.6.32.5 optionFindValue 2185........................ 2186 2187find a hierarcicaly valued option instance 2188 2189Usage: 2190 const tOptionValue * res = optionFindValue( odesc, name, val ); 2191Where the arguments are: 2192 Name Type Description 2193 --- --- --------- 2194 odesc 'const an option with a nested arg type 2195 tOptDesc *' 2196 name 'char const name of value to find 2197 *' 2198 val 'char const the matching value 2199 *' 2200 returns const a compound value structure 2201 tOptionValue 2202 * 2203 2204 This routine will find an entry in a nested value option or 2205configurable. It will search through the list and return a matching 2206entry. 2207 2208 The returned result is NULL and errno is set: 2209 * 'EINVAL' - the 'pOptValue' does not point to a valid hierarchical 2210 option value. 2211 * 'ENOENT' - no entry matched the given name. 2212 2213 2214File: autogen.info, Node: libopts-optionFree, Next: libopts-optionGetValue, Prev: libopts-optionFindValue, Up: libopts procedures 2215 22167.6.32.6 optionFree 2217................... 2218 2219free allocated option processing memory 2220 2221Usage: 2222 optionFree( pOpts ); 2223Where the arguments are: 2224 Name Type Description 2225 --- --- --------- 2226 pOpts 'tOptions *' program options descriptor 2227 2228 AutoOpts sometimes allocates memory and puts pointers to it in the 2229option state structures. This routine deallocates all such memory. 2230 2231 As long as memory has not been corrupted, this routine is always 2232successful. 2233 2234 2235File: autogen.info, Node: libopts-optionGetValue, Next: libopts-optionLoadLine, Prev: libopts-optionFree, Up: libopts procedures 2236 22377.6.32.7 optionGetValue 2238....................... 2239 2240get a specific value from a hierarcical list 2241 2242Usage: 2243 const tOptionValue * res = optionGetValue( pOptValue, valueName ); 2244Where the arguments are: 2245 Name Type Description 2246 --- --- --------- 2247 pOptValue 'const a hierarchcal value 2248 tOptionValue 2249 *' 2250 valueName 'char const name of value to get 2251 *' 2252 returns const a compound value structure 2253 tOptionValue 2254 * 2255 2256 This routine will find an entry in a nested value option or 2257configurable. If "valueName" is NULL, then the first entry is returned. 2258Otherwise, the first entry with a name that exactly matches the argument 2259will be returned. If there is no matching value, NULL is returned and 2260errno is set to ENOENT. If the provided option value is not a 2261hierarchical value, NULL is also returned and errno is set to EINVAL. 2262 2263 The returned result is NULL and errno is set: 2264 * 'EINVAL' - the 'pOptValue' does not point to a valid hierarchical 2265 option value. 2266 * 'ENOENT' - no entry matched the given name. 2267 2268 2269File: autogen.info, Node: libopts-optionLoadLine, Next: libopts-optionMemberList, Prev: libopts-optionGetValue, Up: libopts procedures 2270 22717.6.32.8 optionLoadLine 2272....................... 2273 2274process a string for an option name and value 2275 2276Usage: 2277 optionLoadLine( opts, line ); 2278Where the arguments are: 2279 Name Type Description 2280 --- --- --------- 2281 opts 'tOptions *' program options descriptor 2282 2283 line 'char const NUL-terminated text 2284 *' 2285 2286 This is a client program callable routine for setting options from, 2287for example, the contents of a file that they read in. Only one option 2288may appear in the text. It will be treated as a normal (non-preset) 2289option. 2290 2291 When passed a pointer to the option struct and a string, it will find 2292the option named by the first token on the string and set the option 2293argument to the remainder of the string. The caller must NUL terminate 2294the string. The caller need not skip over any introductory hyphens. 2295Any embedded new lines will be included in the option argument. If the 2296input looks like one or more quoted strings, then the input will be 2297"cooked". The "cooking" is identical to the string formation used in 2298AutoGen definition files (*note basic expression::), except that you may 2299not use backquotes. 2300 2301 Invalid options are silently ignored. Invalid option arguments will 2302cause a warning to print, but the function should return. 2303 2304 2305File: autogen.info, Node: libopts-optionMemberList, Next: libopts-optionNextValue, Prev: libopts-optionLoadLine, Up: libopts procedures 2306 23077.6.32.9 optionMemberList 2308......................... 2309 2310Get the list of members of a bit mask set 2311 2312Usage: 2313 char * res = optionMemberList( od ); 2314Where the arguments are: 2315 Name Type Description 2316 --- --- --------- 2317 od 'tOptDesc *' the set membership option description 2318 returns char * the names of the set bits 2319 2320 This converts the OPT_VALUE_name mask value to a allocated string. 2321It is the caller's responsibility to free the string. 2322 2323 2324File: autogen.info, Node: libopts-optionNextValue, Next: libopts-optionOnlyUsage, Prev: libopts-optionMemberList, Up: libopts procedures 2325 23267.6.32.10 optionNextValue 2327......................... 2328 2329get the next value from a hierarchical list 2330 2331Usage: 2332 const tOptionValue * res = optionNextValue( pOptValue, pOldValue ); 2333Where the arguments are: 2334 Name Type Description 2335 --- --- --------- 2336 pOptValue 'const a hierarchcal list value 2337 tOptionValue 2338 *' 2339 pOldValue 'const a value from this list 2340 tOptionValue 2341 *' 2342 returns const a compound value structure 2343 tOptionValue 2344 * 2345 2346 This routine will return the next entry after the entry passed in. 2347At the end of the list, NULL will be returned. If the entry is not 2348found on the list, NULL will be returned and "ERRNO" will be set to 2349EINVAL. The "POLDVALUE" must have been gotten from a prior call to this 2350routine or to "'opitonGetValue()'". 2351 2352 The returned result is NULL and errno is set: 2353 * 'EINVAL' - the 'pOptValue' does not point to a valid hierarchical 2354 option value or 'pOldValue' does not point to a member of that 2355 option value. 2356 * 'ENOENT' - the supplied 'pOldValue' pointed to the last entry. 2357 2358 2359File: autogen.info, Node: libopts-optionOnlyUsage, Next: libopts-optionPrintVersion, Prev: libopts-optionNextValue, Up: libopts procedures 2360 23617.6.32.11 optionOnlyUsage 2362......................... 2363 2364Print usage text for just the options 2365 2366Usage: 2367 optionOnlyUsage( pOpts, ex_code ); 2368Where the arguments are: 2369 Name Type Description 2370 --- --- --------- 2371 pOpts 'tOptions *' program options descriptor 2372 2373 ex_code 'int' exit code for calling exit(3) 2374 2375 This routine will print only the usage for each option. This 2376function may be used when the emitted usage must incorporate information 2377not available to AutoOpts. 2378 2379 2380File: autogen.info, Node: libopts-optionPrintVersion, Next: libopts-optionPrintVersionAndReturn, Prev: libopts-optionOnlyUsage, Up: libopts procedures 2381 23827.6.32.12 optionPrintVersion 2383............................ 2384 2385Print the program version 2386 2387Usage: 2388 optionPrintVersion( opts, od ); 2389Where the arguments are: 2390 Name Type Description 2391 --- --- --------- 2392 opts 'tOptions *' program options descriptor 2393 2394 od 'tOptDesc *' the descriptor for this arg 2395 2396 This routine will print the version to stdout. 2397 2398 2399File: autogen.info, Node: libopts-optionPrintVersionAndReturn, Next: libopts-optionProcess, Prev: libopts-optionPrintVersion, Up: libopts procedures 2400 24017.6.32.13 optionPrintVersionAndReturn 2402..................................... 2403 2404Print the program version 2405 2406Usage: 2407 optionPrintVersionAndReturn( opts, od ); 2408Where the arguments are: 2409 Name Type Description 2410 --- --- --------- 2411 opts 'tOptions *' program options descriptor 2412 2413 od 'tOptDesc *' the descriptor for this arg 2414 2415 This routine will print the version to stdout and return instead of 2416exiting. Please see the source for the 'print_ver' funtion for details 2417on selecting how verbose to be after this function returns. 2418 2419 2420File: autogen.info, Node: libopts-optionProcess, Next: libopts-optionRestore, Prev: libopts-optionPrintVersionAndReturn, Up: libopts procedures 2421 24227.6.32.14 optionProcess 2423....................... 2424 2425this is the main option processing routine 2426 2427Usage: 2428 int res = optionProcess( opts, a_ct, a_v ); 2429Where the arguments are: 2430 Name Type Description 2431 --- --- --------- 2432 opts 'tOptions *' program options descriptor 2433 2434 a_ct 'int' program arg count 2435 2436 a_v 'char **' program arg vector 2437 returns int the count of the arguments processed 2438 2439 This is the main entry point for processing options. It is intended 2440that this procedure be called once at the beginning of the execution of 2441a program. Depending on options selected earlier, it is sometimes 2442necessary to stop and restart option processing, or to select completely 2443different sets of options. This can be done easily, but you generally 2444do not want to do this. 2445 2446 The number of arguments processed always includes the program name. 2447If one of the arguments is "-", then it is counted and the processing 2448stops. If an error was encountered and errors are to be tolerated, then 2449the returned value is the index of the argument causing the error. A 2450hyphen by itself ("-") will also cause processing to stop and will _not_ 2451be counted among the processed arguments. A hyphen by itself is treated 2452as an operand. Encountering an operand stops option processing. 2453 2454 Errors will cause diagnostics to be printed. 'exit(3)' may or may 2455not be called. It depends upon whether or not the options were 2456generated with the "allow-errors" attribute, or if the ERRSKIP_OPTERR or 2457ERRSTOP_OPTERR macros were invoked. 2458 2459 2460File: autogen.info, Node: libopts-optionRestore, Next: libopts-optionSaveFile, Prev: libopts-optionProcess, Up: libopts procedures 2461 24627.6.32.15 optionRestore 2463....................... 2464 2465restore option state from memory copy 2466 2467Usage: 2468 optionRestore( pOpts ); 2469Where the arguments are: 2470 Name Type Description 2471 --- --- --------- 2472 pOpts 'tOptions *' program options descriptor 2473 2474 Copy back the option state from saved memory. The allocated memory 2475is left intact, so this routine can be called repeatedly without having 2476to call optionSaveState again. If you are restoring a state that was 2477saved before the first call to optionProcess(3AO), then you may change 2478the contents of the argc/argv parameters to optionProcess. 2479 2480 If you have not called 'optionSaveState' before, a diagnostic is 2481printed to 'stderr' and exit is called. 2482 2483 2484File: autogen.info, Node: libopts-optionSaveFile, Next: libopts-optionSaveState, Prev: libopts-optionRestore, Up: libopts procedures 2485 24867.6.32.16 optionSaveFile 2487........................ 2488 2489saves the option state to a file 2490 2491Usage: 2492 optionSaveFile( opts ); 2493Where the arguments are: 2494 Name Type Description 2495 --- --- --------- 2496 opts 'tOptions *' program options descriptor 2497 2498 This routine will save the state of option processing to a file. The 2499name of that file can be specified with the argument to the 2500'--save-opts' option, or by appending the 'rcfile' attribute to the last 2501'homerc' attribute. If no 'rcfile' attribute was specified, it will 2502default to '.programnamerc'. If you wish to specify another file, you 2503should invoke the 'SET_OPT_SAVE_OPTS(filename)' macro. 2504 2505 The recommend usage is as follows: 2506 optionProcess(&progOptions, argc, argv); 2507 if (i_want_a_non_standard_place_for_this) 2508 SET_OPT_SAVE_OPTS("myfilename"); 2509 optionSaveFile(&progOptions); 2510 2511 If no 'homerc' file was specified, this routine will silently return 2512and do nothing. If the output file cannot be created or updated, a 2513message will be printed to 'stderr' and the routine will return. 2514 2515 2516File: autogen.info, Node: libopts-optionSaveState, Next: libopts-optionUnloadNested, Prev: libopts-optionSaveFile, Up: libopts procedures 2517 25187.6.32.17 optionSaveState 2519......................... 2520 2521saves the option state to memory 2522 2523Usage: 2524 optionSaveState( pOpts ); 2525Where the arguments are: 2526 Name Type Description 2527 --- --- --------- 2528 pOpts 'tOptions *' program options descriptor 2529 2530 This routine will allocate enough memory to save the current option 2531processing state. If this routine has been called before, that memory 2532will be reused. You may only save one copy of the option state. This 2533routine may be called before optionProcess(3AO). If you do call it 2534before the first call to optionProcess, then you may also change the 2535contents of argc/argv after you call optionRestore(3AO) 2536 2537 In fact, more strongly put: it is safest to only use this function 2538before having processed any options. In particular, the saving and 2539restoring of stacked string arguments and hierarchical values is 2540disabled. The values are not saved. 2541 2542 If it fails to allocate the memory, it will print a message to stderr 2543and exit. Otherwise, it will always succeed. 2544 2545 2546File: autogen.info, Node: libopts-optionUnloadNested, Next: libopts-optionVersion, Prev: libopts-optionSaveState, Up: libopts procedures 2547 25487.6.32.18 optionUnloadNested 2549............................ 2550 2551Deallocate the memory for a nested value 2552 2553Usage: 2554 optionUnloadNested( pOptVal ); 2555Where the arguments are: 2556 Name Type Description 2557 --- --- --------- 2558 pOptVal 'tOptionValue the hierarchical value 2559 const *' 2560 2561 A nested value needs to be deallocated. The pointer passed in should 2562have been gotten from a call to 'configFileLoad()' (See *note 2563libopts-configFileLoad::). 2564 2565 2566File: autogen.info, Node: libopts-optionVersion, Next: libopts-strequate, Prev: libopts-optionUnloadNested, Up: libopts procedures 2567 25687.6.32.19 optionVersion 2569....................... 2570 2571return the compiled AutoOpts version number 2572 2573Usage: 2574 char const * res = optionVersion(); 2575Where the arguments are: 2576 Name Type Description 2577 --- --- --------- 2578 returns char const * the version string in constant memory 2579 2580 Returns the full version string compiled into the library. The 2581returned string cannot be modified. 2582 2583 2584File: autogen.info, Node: libopts-strequate, Next: libopts-streqvcmp, Prev: libopts-optionVersion, Up: libopts procedures 2585 25867.6.32.20 strequate 2587................... 2588 2589map a list of characters to the same value 2590 2591Usage: 2592 strequate( ch_list ); 2593Where the arguments are: 2594 Name Type Description 2595 --- --- --------- 2596 ch_list 'char const characters to equivalence 2597 *' 2598 2599 Each character in the input string get mapped to the first character 2600in the string. This function name is mapped to option_strequate so as 2601to not conflict with the POSIX name space. 2602 2603 none. 2604 2605 2606File: autogen.info, Node: libopts-streqvcmp, Next: libopts-streqvmap, Prev: libopts-strequate, Up: libopts procedures 2607 26087.6.32.21 streqvcmp 2609................... 2610 2611compare two strings with an equivalence mapping 2612 2613Usage: 2614 int res = streqvcmp( str1, str2 ); 2615Where the arguments are: 2616 Name Type Description 2617 --- --- --------- 2618 str1 'char const first string 2619 *' 2620 str2 'char const second string 2621 *' 2622 returns int the difference between two differing 2623 characters 2624 2625 Using a character mapping, two strings are compared for 2626"equivalence". Each input character is mapped to a comparison character 2627and the mapped-to characters are compared for the two NUL terminated 2628input strings. This function name is mapped to option_streqvcmp so as 2629to not conflict with the POSIX name space. 2630 2631 none checked. Caller responsible for seg faults. 2632 2633 2634File: autogen.info, Node: libopts-streqvmap, Next: libopts-strneqvcmp, Prev: libopts-streqvcmp, Up: libopts procedures 2635 26367.6.32.22 streqvmap 2637................... 2638 2639Set the character mappings for the streqv functions 2640 2641Usage: 2642 streqvmap( from, to, ct ); 2643Where the arguments are: 2644 Name Type Description 2645 --- --- --------- 2646 from 'char' Input character 2647 2648 to 'char' Mapped-to character 2649 2650 ct 'int' compare length 2651 2652 Set the character mapping. If the count ('ct') is set to zero, then 2653the map is cleared by setting all entries in the map to their index 2654value. Otherwise, the "'From'" character is mapped to the "'To'" 2655character. If 'ct' is greater than 1, then 'From' and 'To' are 2656incremented and the process repeated until 'ct' entries have been set. 2657For example, 2658 streqvmap('a', 'A', 26); 2659will alter the mapping so that all English lower case letters will map 2660to upper case. 2661 2662 This function name is mapped to option_streqvmap so as to not 2663conflict with the POSIX name space. 2664 2665 none. 2666 2667 2668File: autogen.info, Node: libopts-strneqvcmp, Next: libopts-strtransform, Prev: libopts-streqvmap, Up: libopts procedures 2669 26707.6.32.23 strneqvcmp 2671.................... 2672 2673compare two strings with an equivalence mapping 2674 2675Usage: 2676 int res = strneqvcmp( str1, str2, ct ); 2677Where the arguments are: 2678 Name Type Description 2679 --- --- --------- 2680 str1 'char const first string 2681 *' 2682 str2 'char const second string 2683 *' 2684 ct 'int' compare length 2685 returns int the difference between two differing 2686 characters 2687 2688 Using a character mapping, two strings are compared for 2689"equivalence". Each input character is mapped to a comparison character 2690and the mapped-to characters are compared for the two NUL terminated 2691input strings. The comparison is limited to 'ct' bytes. This function 2692name is mapped to option_strneqvcmp so as to not conflict with the POSIX 2693name space. 2694 2695 none checked. Caller responsible for seg faults. 2696 2697 2698File: autogen.info, Node: libopts-strtransform, Prev: libopts-strneqvcmp, Up: libopts procedures 2699 27007.6.32.24 strtransform 2701...................... 2702 2703convert a string into its mapped-to value 2704 2705Usage: 2706 strtransform( dest, src ); 2707Where the arguments are: 2708 Name Type Description 2709 --- --- --------- 2710 dest 'char *' output string 2711 2712 src 'char const input string 2713 *' 2714 2715 Each character in the input string is mapped and the mapped-to 2716character is put into the output. This function name is mapped to 2717option_strtransform so as to not conflict with the POSIX name space. 2718 2719 The source and destination may be the same. 2720 2721 none. 2722 2723 2724File: autogen.info, Node: Multi-Threading, Next: option descriptor, Prev: AutoOpts API, Up: AutoOpts 2725 27267.7 Multi-Threading 2727=================== 2728 2729AutoOpts was designed to configure a program for running. This 2730generally happens before much real work has been started. Consequently, 2731it is expected to be run before multi-threaded applications have started 2732multiple threads. However, this is not always the case. Some 2733applications may need to reset and reload their running configuration, 2734and some may use 'SET_OPT_xxx()' macros during processing. If you need 2735to dynamically change your option configuration in your multi-threaded 2736application, it is your responsibility to prevent all threads from 2737accessing the option configuration state, except the one altering the 2738configuration. 2739 2740 The various accessor macros ('HAVE_OPT()', etc.) do not modify state 2741and are safe to use in a multi-threaded application. It is safe as long 2742as no other thread is concurrently modifying state, of course. 2743 2744 2745File: autogen.info, Node: option descriptor, Next: Using AutoOpts, Prev: Multi-Threading, Up: AutoOpts 2746 27477.8 Option Descriptor File 2748========================== 2749 2750This is the module that is to be compiled and linked with your program. 2751It contains internal data and procedures subject to change. Basically, 2752it contains a single global data structure containing all the 2753information provided in the option definitions, plus a number of static 2754strings and any callout procedures that are specified or required. You 2755should never have need for looking at this, except, perhaps, to examine 2756the code generated for implementing the 'flag-code' construct. 2757 2758 2759File: autogen.info, Node: Using AutoOpts, Next: Presetting Options, Prev: option descriptor, Up: AutoOpts 2760 27617.9 Using AutoOpts 2762================== 2763 2764There are actually several levels of 'using' autoopts. Which you choose 2765depends upon how you plan to distribute (or not) your application. 2766 2767* Menu: 2768 2769* local use:: local-only use 2770* binary not installed:: binary distro, AutoOpts not installed 2771* binary pre-installed:: binary distro, AutoOpts pre-installed 2772* source pre-installed:: source distro, AutoOpts pre-installed 2773* source not installed:: source distro, AutoOpts not installed 2774 2775 2776File: autogen.info, Node: local use, Next: binary not installed, Up: Using AutoOpts 2777 27787.9.1 local-only use 2779-------------------- 2780 2781To use AutoOpts in your application where you do not have to worry about 2782distribution issues, your issues are simple and few. 2783 2784 * Create a file 'myopts.def', according to the documentation above. 2785 It is probably easiest to start with the example in *note Quick 2786 Start:: and edit it into the form you need. 2787 2788 * Run AutoGen to create the option interface file ('myopts.h') and 2789 the option descriptor code ('myopts.c'): 2790 2791 autogen myopts.def 2792 2793 * In all your source files where you need to refer to option state, 2794 '#include "myopts.h"'. 2795 * In your main routine, code something along the lines of: 2796 2797 #define ARGC_MIN some-lower-limit 2798 #define ARGC_MAX some-upper-limit 2799 main( int argc, char** argv ) 2800 { 2801 { 2802 int arg_ct = optionProcess( &myprogOptions, argc, argv ); 2803 argc -= arg_ct; 2804 if ((argc < ARGC_MIN) || (argc > ARGC_MAX)) { 2805 fprintf( stderr, "%s ERROR: remaining args (%d) " 2806 "out of range\n", myprogOptions.pzProgName, 2807 argc ); 2808 2809 USAGE( EXIT_FAILURE ); 2810 } 2811 argv += arg_ct; 2812 } 2813 if (HAVE_OPT(OPTN_NAME)) 2814 respond_to_optn_name(); 2815 ... 2816 } 2817 2818 * Compile 'myopts.c' and link your program with the following 2819 additional arguments: 2820 2821 `autoopts-config cflags ldflags` myopts.c 2822 2823 2824File: autogen.info, Node: binary not installed, Next: binary pre-installed, Prev: local use, Up: Using AutoOpts 2825 28267.9.2 binary distro, AutoOpts not installed 2827------------------------------------------- 2828 2829If you will be distributing (or copying) your project to a system that 2830does not have AutoOpts installed, you will need to statically link the 2831AutoOpts library, 'libopts' into your program. Get the link information 2832with 'static-libs' instead of 'ldflags': 2833 2834 `autoopts-config static-libs` 2835 2836 2837File: autogen.info, Node: binary pre-installed, Next: source pre-installed, Prev: binary not installed, Up: Using AutoOpts 2838 28397.9.3 binary distro, AutoOpts pre-installed 2840------------------------------------------- 2841 2842If you will be distributing (or copying) your project to a system that 2843does have AutoOpts (or only 'libopts') installed, you will still need to 2844ensure that the library is findable at program load time, or you will 2845still have to statically link. The former can be accomplished by 2846linking your project with '--rpath' or by setting the 'LD_LIBRARY_PATH' 2847appropriately. Otherwise, *Note binary not installed::. 2848 2849 2850File: autogen.info, Node: source pre-installed, Next: source not installed, Prev: binary pre-installed, Up: Using AutoOpts 2851 28527.9.4 source distro, AutoOpts pre-installed 2853------------------------------------------- 2854 2855If you will be distributing your project to a system that will build 2856your product but it may not be pre-installed with AutoOpts, you will 2857need to do some configuration checking before you start the build. 2858Assuming you are willing to fail the build if AutoOpts has not been 2859installed, you will still need to do a little work. 2860 2861 AutoOpts is distributed with a configuration check M4 script, 2862'autoopts.m4'. It will add an 'autoconf' macro named, 2863'AG_PATH_AUTOOPTS'. Add this to your 'configure.ac' script and use the 2864following substitution values: 2865 2866'AUTOGEN' 2867 the name of the autogen executable 2868'AUTOGEN_TPLIB' 2869 the directory where AutoGen template library is stored 2870'AUTOOPTS_CFLAGS' 2871 the compile time options needed to find the AutoOpts headers 2872'AUTOOPTS_LIBS' 2873 the link options required to access the 'libopts' library 2874 2875 2876File: autogen.info, Node: source not installed, Prev: source pre-installed, Up: Using AutoOpts 2877 28787.9.5 source distro, AutoOpts not installed 2879------------------------------------------- 2880 2881If you will be distributing your project to a system that will build 2882your product but it may not be pre-installed with AutoOpts, you may wish 2883to incorporate the sources for 'libopts' in your project. To do this, I 2884recommend reading the tear-off libopts library 'README' that you can 2885find in the 'pkg/libopts' directory. You can also examine an example 2886package (blocksort) that incorporates this tear off library in the 2887autogen distribution directory. There is also a web page that describes 2888what you need to do: 2889 <http://autogen.sourceforge.net/blocksort.html> 2890 2891 Alternatively, you can pull the 'libopts' library sources into a 2892build directory and build it for installation along with your package. 2893This can be done approximately as follows: 2894 tar -xzvf `autoopts-config libsrc` 2895 cd libopts-* 2896 ./bootstrap 2897 configure 2898 make 2899 make install 2900 That will install the library, but not the headers or anything else. 2901 2902 2903File: autogen.info, Node: Presetting Options, Next: Config File Format, Prev: Using AutoOpts, Up: AutoOpts 2904 29057.10 Configuring your program 2906============================= 2907 2908AutoOpts supports the notion of 'presetting' the value or state of an 2909option. The values may be obtained either from environment variables or 2910from configuration files ('rc' or 'ini' files). In order to take 2911advantage of this, the AutoOpts client program must specify these 2912features in the option descriptor file (*note program attributes::) with 2913the 'rcfile' or 'environrc' attributes. 2914 2915* Menu: 2916 2917* loading rcfile:: configuration file presets 2918* saving rcfile:: Saving the presets into a configuration file 2919* sample rcfile:: Creating a sample configuration file 2920* environrc:: environment variable presets 2921* config example:: Config file only example 2922 2923 It is also possible to configure your program without using the 2924command line option parsing code. This is done by using only the 2925following four functions from the 'libopts' library: 2926 2927'configFileLoad' 2928 (*note libopts-configFileLoad::) will parse the contents of a 2929 config file and return a pointer to a structure representing the 2930 hierarchical value. The values are sorted alphabetically by the 2931 value name and all entries with the same name will retain their 2932 original order. Insertion sort is used. 2933 2934'optionGetValue' 2935 (*note libopts-optionGetValue::) will find the first value within 2936 the hierarchy with a name that matches the name passed in. 2937 2938'optionNextValue' 2939 (*note libopts-optionNextValue::) will return the next value that 2940 follows the value passed in as an argument. If you wish to get all 2941 the values for a particular name, you must take note when the name 2942 changes. 2943 2944'optionUnloadNested' 2945 (*note libopts-optionUnloadNested::). The pointer passed in must 2946 be of type, 'OPARG_TYPE_HIERARCHY' (see the autoopts/options.h 2947 header file). 'configFileLoad' will return a 'tOptionValue' 2948 pointer of that type. This function will release all the 2949 associated memory. 'AutoOpts' generated code uses this function 2950 for its own needs. Client code should only call this function with 2951 pointers gotten from 'configFileLoad'. 2952 2953 2954File: autogen.info, Node: loading rcfile, Next: saving rcfile, Up: Presetting Options 2955 29567.10.1 configuration file presets 2957--------------------------------- 2958 2959Configuration files are enabled by specifying the program attribute 2960'homerc' (*note program attributes::). Any option not marked with the 2961'no-preset' attribute may appear in a configuration file. The files 2962loaded are selected both by the 'homerc' entries and, optionally, via a 2963command line option. The first component of the 'homerc' entry may be 2964an environment variable such as '$HOME', or it may also be '$$' (*two* 2965dollar sign characters) to specify the directory of the executable. For 2966example: 2967 2968 homerc = "$$/../share/autogen"; 2969 2970will cause the AutoOpts library to look in the normal autogen datadir 2971relative to the current installation directory for autogen. 2972 2973 The configuration files are processed in the order they are specified 2974by the 'homerc' attribute, so that each new file will normally override 2975the settings of the previous files. This may be overridden by marking 2976some options for 'immediate action' (*note Immediate Action::). Any 2977such options are acted upon in *reverse* order. The disabled 2978'load-opts' ('--no-load-opts') option, for example, is an immediate 2979action option. Its presence in the last 'homerc' file will prevent the 2980processing of any prior 'homerc' files because its effect is immediate. 2981 2982 Configuration file processing can be completely suppressed by 2983specifying '--no-load-opts' on the command line, or 2984'PROGRAM_LOAD_OPTS=no' in the environment (if 'environrc' has been 2985specified). 2986 2987 See the 'Configuration File Format' section (*note Config File 2988Format::) for details on the format of the file. 2989 2990 2991File: autogen.info, Node: saving rcfile, Next: sample rcfile, Prev: loading rcfile, Up: Presetting Options 2992 29937.10.2 Saving the presets into a configuration file 2994--------------------------------------------------- 2995 2996When configuration files are enabled for an application, the user is 2997also provided with an automatically supplied '--save-opts' option. All 2998of the known option state will be written to either the specified output 2999file or, if it is not specified, then to the last specified 'homerc' 3000file. 3001 3002 3003File: autogen.info, Node: sample rcfile, Next: environrc, Prev: saving rcfile, Up: Presetting Options 3004 30057.10.3 Creating a sample configuration file 3006------------------------------------------- 3007 3008AutoOpts is shipped with a template named, 'rc-sample.tpl'. If your 3009option definition file specifies the 'homerc' attribute, then you may 3010invoke 'autogen' thus: 3011 3012 autogen -Trc-sample <your-option-def-file> 3013 3014 This will, by default, produce a sample file named, 3015'sample-<prog-name>rc'. It will be named differently if you specify 3016your configuration (rc) file name with the 'rcfile' attribute. In that 3017case, the output file will be named, 'sample-<rcfile-name>'. It will 3018contain all of the program options not marked as 'no-preset'. It will 3019also include the text from the 'doc' attribute. 3020 3021Doing so with getdefs' option definitions yields this sample-getdefsrc 3022file. I tend to be wordy in my 'doc' attributes: 3023 3024 # getdefs sample configuration file 3025 ## This source file is copyrighted and licensed under the following terms: 3026 # 3027 # Copyright (C) 1999-2018 Bruce Korb, all rights reserved. 3028 # This is free software. It is licensed for use, modification and 3029 # redistribution under the terms of the GNU General Public License, 3030 # version 3 or later <http://gnu.org/licenses/gpl.html> 3031 # 3032 # getdefs is free software: you can redistribute it and/or modify it 3033 # under the terms of the GNU General Public License as published by the 3034 # Free Software Foundation, either version 3 of the License, or 3035 # (at your option) any later version. 3036 # 3037 # getdefs is distributed in the hope that it will be useful, but 3038 # WITHOUT ANY WARRANTY; without even the implied warranty of 3039 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 3040 # See the GNU General Public License for more details. 3041 # 3042 # You should have received a copy of the GNU General Public License along 3043 # with this program. If not, see <http://www.gnu.org/licenses/>. 3044 3045 # defs_to_get -- Regexp to look for after the "/*=" 3046 # 3047 # 3048 # 3049 # 3050 # If you want definitions only from a particular category, or even 3051 # with names matching particular patterns, then specify this regular 3052 # expression for the text that must follow the @code{/*=}. 3053 # Example: 3054 # 3055 #defs_to_get reg-ex 3056 3057 # subblock -- subblock definition names 3058 # 3059 # 3060 # 3061 # 3062 # This option is used to create shorthand entries for nested definitions. 3063 # For example, with: 3064 # @table @r 3065 # @item using subblock thus 3066 # @code{--subblock=arg=argname,type,null} 3067 # @item and defining an @code{arg} thus 3068 # @code{arg: this, char *} 3069 # @item will then expand to: 3070 # @code{arg = @{ argname = this; type = "char *"; @};} 3071 # @end table 3072 # The "this, char *" string is separated at the commas, with the 3073 # white space removed. You may use characters other than commas by 3074 # starting the value string with a punctuation character other than 3075 # a single or double quote character. You may also omit intermediate 3076 # values by placing the commas next to each other with no intervening 3077 # white space. For example, "+mumble++yes+" will expand to: 3078 # @* 3079 # @code{arg = @{ argname = mumble; null = "yes"; @};}. 3080 # Example: 3081 # 3082 #subblock sub-def 3083 3084 # listattr -- attribute with list of values 3085 # 3086 # 3087 # 3088 # 3089 # This option is used to create shorthand entries for definitions 3090 # that generally appear several times. That is, they tend to be 3091 # a list of values. For example, with: 3092 # @* 3093 # @code{listattr=foo} defined, the text: 3094 # @* 3095 # @code{foo: this, is, a, multi-list} will then expand to: 3096 # @* 3097 # @code{foo = 'this', 'is', 'a', 'multi-list';} 3098 # @* 3099 # The texts are separated by the commas, with the 3100 # white space removed. You may use characters other than commas by 3101 # starting the value string with a punctuation character other than 3102 # a single or double quote character. 3103 # Example: 3104 # 3105 #listattr def 3106 3107 # ordering -- Alphabetize or use named file 3108 # 3109 # 3110 # 3111 # 3112 # By default, ordering is alphabetical by the entry name. Use, 3113 # @code{no-ordering} if order is unimportant. Use @code{ordering} 3114 # with no argument to order without case sensitivity. Use 3115 # @code{ordering=<file-name>} if chronological order is important. 3116 # getdefs will maintain the text content of @code{file-name}. 3117 # @code{file-name} need not exist. 3118 # Example: 3119 # 3120 #ordering file-name 3121 3122 # first_index -- The first index to apply to groups 3123 # 3124 # This configuration value takes an integer number as its argument. 3125 # 3126 # 3127 # By default, the first occurrence of a named definition will have an 3128 # index of zero. Sometimes, that needs to be a reserved value. Provide 3129 # this option to specify a different starting point. 3130 # Example: 3131 # 3132 #first_index 0 3133 3134 # filelist -- Insert source file names into defs 3135 # 3136 # 3137 # 3138 # 3139 # Inserts the name of each input file into the output definitions. 3140 # If no argument is supplied, the format will be: 3141 # @example 3142 # infile = '%s'; 3143 # @end example 3144 # If an argument is supplied, that string will be used for the entry 3145 # name instead of @var{infile}. 3146 # Example: 3147 # 3148 #filelist file 3149 3150 # assign -- Global assignments 3151 # 3152 # 3153 # 3154 # 3155 # The argument to each copy of this option will be inserted into 3156 # the output definitions, with only a semicolon attached. 3157 # Example: 3158 # 3159 #assign ag-def 3160 3161 # common_assign -- Assignments common to all blocks 3162 # 3163 # 3164 # 3165 # 3166 # The argument to each copy of this option will be inserted into 3167 # each output definition, with only a semicolon attached. 3168 # Example: 3169 # 3170 #common_assign ag-def 3171 3172 # copy -- File(s) to copy into definitions 3173 # 3174 # 3175 # 3176 # 3177 # The content of each file named by these options will be inserted into 3178 # the output definitions. 3179 # Example: 3180 # 3181 #copy file 3182 3183 # srcfile -- Insert source file name into each def 3184 # 3185 # 3186 # 3187 # 3188 # Inserts the name of the input file where a definition was found 3189 # into the output definition. 3190 # If no argument is supplied, the format will be: 3191 # @example 3192 # srcfile = '%s'; 3193 # @end example 3194 # If an argument is supplied, that string will be used for the entry 3195 # name instead of @var{srcfile}. 3196 # Example: 3197 # 3198 #srcfile file 3199 3200 # linenum -- Insert source line number into each def 3201 # 3202 # 3203 # 3204 # 3205 # Inserts the line number in the input file where a definition 3206 # was found into the output definition. 3207 # If no argument is supplied, the format will be: 3208 # @example 3209 # linenum = '%s'; 3210 # @end example 3211 # If an argument is supplied, that string will be used for the entry 3212 # name instead of @var{linenum}. 3213 # Example: 3214 # 3215 #linenum def-name 3216 3217 # input -- Input file to search for defs 3218 # 3219 # 3220 # 3221 # 3222 # All files that are to be searched for definitions must be named on 3223 # the command line or read from @code{stdin}. If there is only one 3224 # @code{input} option and it is the string, "-", then the input file 3225 # list is read from @code{stdin}. If a command line argument is not 3226 # an option name and does not contain an assignment operator 3227 # (@code{=}), then it defaults to being an input file name. 3228 # At least one input file must be specified. 3229 # Example: 3230 # 3231 #input src-file 3232 3233 # output -- Output file to open 3234 # 3235 # 3236 # 3237 # 3238 # If you are not sending the output to an AutoGen process, 3239 # you may name an output file instead. 3240 # Example: 3241 # 3242 #output file 3243 3244 # autogen -- Invoke AutoGen with defs 3245 # 3246 # 3247 # 3248 # 3249 # This is the default output mode. Specifying @code{no-autogen} is 3250 # equivalent to @code{output=-}. If you supply an argument to this 3251 # option, that program will be started as if it were AutoGen and 3252 # its standard in will be set to the output definitions of this program. 3253 # Example: 3254 # 3255 #autogen ag-cmd 3256 3257 # template -- Template Name 3258 # 3259 # 3260 # 3261 # 3262 # Specifies the template name to be used for generating the final output. 3263 # Example: 3264 # 3265 #template file 3266 3267 # agarg -- AutoGen Argument 3268 # 3269 # 3270 # 3271 # 3272 # This is a pass-through argument. It allows you to specify any 3273 # arbitrary argument to be passed to AutoGen. 3274 # Example: 3275 # 3276 #agarg ag-opt 3277 3278 # base_name -- Base name for output file(s) 3279 # 3280 # 3281 # 3282 # 3283 # When output is going to AutoGen, a base name must either be supplied 3284 # or derived. If this option is not supplied, then it is taken from 3285 # the @code{template} option. If that is not provided either, then 3286 # it is set to the base name of the current directory. 3287 # Example: 3288 # 3289 #base_name name 3290 3291 3292File: autogen.info, Node: environrc, Next: config example, Prev: sample rcfile, Up: Presetting Options 3293 32947.10.4 environment variable presets 3295----------------------------------- 3296 3297If the AutoOpts client program specifies 'environrc' in its option 3298descriptor file, then environment variables will be used for presetting 3299option state. Variables will be looked for that are named, 3300'PROGRAM_OPTNAME' and 'PROGRAM'. 'PROGRAM' is the upper cased 'C-name' 3301of the program, and OPTNAME is the upper cased 'C-name' of a specific 3302option. (The 'C-name's are the regular names with all special 3303characters converted to underscores ('_').) 3304 3305 Option specific environment variables are processed after (and thus 3306take precedence over) the contents of the 'PROGRAM' environment 3307variable. The option argument string for these options takes on the 3308string value gotten from the environment. Consequently, you can only 3309have one instance of the OPTNAME. 3310 3311 If a particular option may be disabled, then its disabled state is 3312indicated by setting the 'PROGRAM_OPTNAME' value to the disablement 3313prefix. So, for example, if the disablement prefix were 'dont', then 3314you can disable the 'optname' option by setting the 'PROGRAM_OPTNAME'' 3315environment variable to 'dont'. *Note Common Attributes::. 3316 3317 The 'PROGRAM' environment string is tokenized and parsed much like a 3318command line. Doubly quoted strings have backslash escapes processed 3319the same way they are processed in C program constant strings. Singly 3320quoted strings are pretty raw in that backslashes are honored before 3321other backslashes, apostrophes, newlines and cr/newline pairs. The 3322options must be introduced with hyphens in the same way as the command 3323line. 3324 3325 Note that not all options may be preset. Options that are specified 3326with the 'no-preset' attribute and the '--help', '--more-help', and 3327'--save-opts' auto-supported options may not be preset. 3328 3329 3330File: autogen.info, Node: config example, Prev: environrc, Up: Presetting Options 3331 33327.10.5 Config file only example 3333------------------------------- 3334 3335If for some reason it is difficult or unworkable to integrate 3336configuration file processing with command line option parsing, the 3337'libopts' (*note libopts procedures::) library can still be used to 3338process configuration files. Below is a Hello, World! greeting program 3339that tries to load a configuration file 'hello.conf' to see if it should 3340use an alternate greeting or to personalize the salutation. 3341 #include <config.h> 3342 #include <sys/types.h> 3343 #include <stdio.h> 3344 #include <pwd.h> 3345 #include <string.h> 3346 #ifdef HAVE_UNISTD_H 3347 #include <unistd.h> 3348 #endif 3349 #include <autoopts/options.h> 3350 int main(int argc, char ** argv) { 3351 char const * greeting = "Hello"; 3352 char const * greeted = "World"; 3353 tOptionValue const * pOV = configFileLoad("hello.conf"); 3354 3355 if (pOV != NULL) { 3356 const tOptionValue* pGetV = optionGetValue(pOV, "greeting"); 3357 3358 if ( (pGetV != NULL) 3359 && (pGetV->valType == OPARG_TYPE_STRING)) 3360 greeting = strdup(pGetV->v.strVal); 3361 3362 pGetV = optionGetValue(pOV, "personalize"); 3363 if (pGetV != NULL) { 3364 struct passwd * pwe = getpwuid(getuid()); 3365 if (pwe != NULL) 3366 greeted = strdup(pwe->pw_gecos); 3367 } 3368 3369 optionUnloadNested(pOV); /* deallocate config data */ 3370 } 3371 printf("%s, %s!\n", greeting, greeted); 3372 return 0; 3373 } 3374 3375With that text in a file named "hello.c", this short script: 3376 3377 cc -o hello hello.c `autoopts-config cflags ldflags` 3378 ./hello 3379 echo 'greeting Buzz off' > hello.conf 3380 ./hello 3381 echo personalize > hello.conf 3382 ./hello 3383 3384will produce the following output: 3385 3386 Hello, World! 3387 Buzz off, World! 3388 Hello, Bruce Korb,,,! 3389 3390 3391File: autogen.info, Node: Config File Format, Next: shell options, Prev: Presetting Options, Up: AutoOpts 3392 33937.11 Configuration File Format 3394============================== 3395 3396The configuration file is designed to associate names and values, much 3397like an AutoGen Definition File (*note Definitions File::). 3398Unfortunately, the file formats are different. Specifically, AutoGen 3399Definitions provide for simpler methods for the precise control of a 3400value string and provides for dynamically computed content. 3401Configuration files have some established traditions in their layout. 3402So, they are different, even though they do both allow for a single name 3403to be associated with multiple values and they both allow for 3404hierarchical values. 3405 3406* Menu: 3407 3408* config name/string-value:: assigning a string value to a configurable 3409* config integer-values:: integer values 3410* config nested-values:: hierarchical values 3411* config directives:: configuration file directives 3412* config comments:: comments in the configuration file 3413 3414 3415File: autogen.info, Node: config name/string-value, Next: config integer-values, Up: Config File Format 3416 34177.11.1 assigning a string value to a configurable 3418------------------------------------------------- 3419 3420The basic syntax is a name followed by a value on a single line. They 3421are separated from each other by either white space, a colon (':') or an 3422equal sign ('='). The colon or equal sign may optionally be surrounded 3423by additional white space. If more than one value line is needed, a 3424backslash ('\') may be used to continue the value. The backslash (but 3425not the newline) will be erased. Leading and trailing white space is 3426always stripped from the value. 3427 3428 Fundamentally, it looks like this: 3429 3430 name value for that name 3431 name = another \ 3432 multi-line value \ 3433 for that name. 3434 name: a *third* value for name 3435 3436 If you need more control over the content of the value, you may 3437enclose the value in XML style brackets: 3438 <name>value </name> 3439Within these brackets you need not (must not) continue the value data 3440with backslashes. You may also select the string formation rules to 3441use, just add the attribute after the name, thus: '<name keep>'. 3442 3443'keep' 3444 This mode will keep all text between the brackets and not strip any 3445 white space. 3446'uncooked' 3447 This mode strips leading and trailing white space, but not do any 3448 quote processing. This is the default and need not be specified. 3449'cooked' 3450 The text is trimmed of leading and trailing white space and XML 3451 encodings are processed. These encodings are slightly expanded 3452 over the XML specification. They are specified with an ampersand 3453 followed by a value name or numeric value and then a semicolon: 3454 3455 'amp' 3456 'lt' 3457 'gt' 3458 'quot' 3459 'apos' 3460 '#dd' 3461 '#xHH' 3462 3463 These are all per fairly standad HTML and/or XML encodings. 3464 Additionally: 3465 3466 'bs' 3467 The ASCII back space character. 3468 'ff' 3469 The ASCII form feed character. 3470 'ht' 3471 The ASCII horizontal (normal) tab character. 3472 'cr' 3473 The ASCII carriage return character. 3474 'vt' 3475 The ASCII vertical tab character. 3476 'bel' 3477 The ASCII alarm bell character. 3478 'nl' 3479 The ASCII new line character. 3480 'space' 3481 The ASCII space character. Normally not necessary, but if you 3482 want to preserve leading or trailing space characters, then 3483 use this. 3484 3485 And here is an example of an XML-styled value: 3486 3487 <name cooked> 3488 This is&nl;&ht;another multi-line 3489 &ht;string example. 3490 </name> 3491 3492 The string value associated with 'name' will be exactly the text 3493enclosed in quotes with the encoded characters 'cooked' as you would 3494expect (three text lines with the last line not ending with a newline, 3495but ending with a period). 3496 3497 3498File: autogen.info, Node: config integer-values, Next: config nested-values, Prev: config name/string-value, Up: Config File Format 3499 35007.11.2 integer values 3501--------------------- 3502 3503A name can be specified as having an integer value. To do this, you 3504must use the XML-ish format and specify a 'type' attribute for the name: 3505 3506 <name type=integer> 1234 </name> 3507 3508 Boolean, enumeration and set membership types will be added as time 3509allows. 'type=string' is also supported, but also is the default. 3510 3511 3512File: autogen.info, Node: config nested-values, Next: config directives, Prev: config integer-values, Up: Config File Format 3513 35147.11.3 hierarchical values 3515-------------------------- 3516 3517In order to specify a hierarchical value, you *must* use XML-styled 3518formatting, specifying a type that is shorter and easier to spell: 3519 3520 <structured-name type=nested> 3521 [[....]] 3522 </structured-name> 3523 3524The ellipsis may be filled with any legal configuration file name/value 3525assignments. 3526 3527 3528File: autogen.info, Node: config directives, Next: config comments, Prev: config nested-values, Up: Config File Format 3529 35307.11.4 configuration file directives 3531------------------------------------ 3532 3533The '<?' marker indicates an XML directive. There is only one directive 3534supported: program sectioning, though two syntaxes are supported. 3535 3536 If, for example, you have a collection of programs that work closely 3537together and, likely, have a common set of options, these programs may 3538use a single, sectioned, configuration file. The file may be sectioned 3539in either of two ways. The two ways may not be intermixed in a single 3540configuration file. All text before the first segmentation line is 3541processed, then only the segment that applies: 3542 3543'<?auto-options ...>' 3544 The '...' ellipsis may contain AutoOpts option processing options. 3545 Currently, that consists of one or both of: 3546 3547 'gnu' 3548 'autoopts' 3549 to indicate GNU-standard or AutoOpts-standard layout of usage 3550 and version information, and/or 3551 3552 'misuse-usage' 3553 'no-misuse-usage' 3554 to indicate whether the available options should be listed 3555 when an invalid option appears on the command line. 3556 Anything else will be silently ignored. 3557 3558'<?program prog-name>' 3559 The '<?' marker indicates an XML directive. The file is 3560 partitioned by these lines and the options are processed for the 3561 'prog-name' program only before the first '<?program' directive and 3562 the program section with a matching program name. 3563 3564'[PROG_NAME]' 3565 This is basically an alias for '<?program prog-name>', except that 3566 the program name must be upper cased and segmented only with 3567 underscores and it is *not* recognized as a program segment when 3568 updating configuration files with the '--save-opts' option. In 3569 other words, use this only for Windows compatibility. 3570 3571Segmentation does not apply if the config file is being parsed with the 3572'configFileLoad(3AutoOpts)' function. 3573 3574 3575File: autogen.info, Node: config comments, Prev: config directives, Up: Config File Format 3576 35777.11.5 comments in the configuration file 3578----------------------------------------- 3579 3580Comments are lines beginning with a hash mark ('#'), XML-style comments 3581('<!-- arbitrary text -->'), and unrecognized XML directives. 3582 3583 # this is a comment 3584 <!-- this is also 3585 a comment --> 3586 <?this is 3587 a bad comment ;-> 3588 3589 3590File: autogen.info, Node: shell options, Next: AutoInfo, Prev: Config File Format, Up: AutoOpts 3591 35927.12 AutoOpts for Shell Scripts 3593=============================== 3594 3595AutoOpts may be used with shell scripts either by automatically creating 3596a complete program that will process command line options and pass back 3597the results to the invoking shell by issuing shell variable assignment 3598commands, or it may be used to generate portable shell code that can be 3599inserted into your script. 3600 3601 The functionality of these features, of course, is somewhat 3602constrained compared with the normal program facilities. Specifically, 3603you cannot invoke callout procedures with either of these methods. 3604Additionally, if you generate a shell script to do the parsing: 3605 3606 1. You cannot obtain options from configuration files. 3607 2. You cannot obtain options from environment variables. 3608 3. You cannot save the option state to an option file. 3609 4. Option conflict/requirement verification is disabled. 3610 3611 Both of these methods are enabled by running AutoGen on the 3612definitions file with the additional main procedure attribute: 3613 3614 main = { main-type = shell-process; }; 3615or: 3616 main = { main-type = shell-parser; }; 3617 3618 If you do not supply a 'proc-to-call', it will default to 3619'optionPutShell'. That will produce a program that will process the 3620options and generate shell text for the invoking shell to interpret 3621(*note binary-parser::). If you supply the name, 'optionParseShell', 3622then you will have a program that will generate a shell script that can 3623parse the options (*note script-parser::). If you supply a different 3624procedure name, you will have to provide that routine and it may do 3625whatever you like. 3626 3627* Menu: 3628 3629* binary-parser:: Parsing with an Executable 3630* script-parser:: Parsing with a Portable Script 3631 3632 3633File: autogen.info, Node: binary-parser, Next: script-parser, Up: shell options 3634 36357.12.1 Parsing with an Executable 3636--------------------------------- 3637 3638The following commands are approximately all that is needed to build a 3639shell script command line option parser from an option definition file: 3640 3641 autogen -L <opt-template-dir> test-errors.def 3642 cc -o test-errors -L <opt-lib-dir> -I <opt-include-dir> \ 3643 -DTEST_PROGRAM_OPTS test-errors.c -lopts 3644 3645 The resulting program can then be used within your shell script as 3646follows: 3647 3648 eval `./test-errors "$@"` 3649 if [ -z "${OPTION_CT}" ] ; then exit 1 ; fi 3650 test ${OPTION_CT} -gt 0 && shift ${OPTION_CT} 3651 3652 Here is the usage output example from AutoOpts error handling tests. 3653The option definition has argument reordering enabled: 3654 3655 test_errors - Test AutoOpts for errors 3656 Usage: errors [ -<flag> [<val>] | --<name>[{=| }<val>] ]... arg ... 3657 Flg Arg Option-Name Description 3658 -o no option The option option descrip 3659 -s Str second The second option descrip 3660 - may appear up to 10 times 3661 -i --- ignored we have dumped this 3662 -X no another Another option descrip 3663 - may appear up to 5 times 3664 -? no help display extended usage information and exit 3665 -! no more-help extended usage information passed thru pager 3666 -> opt save-opts save the option state to a config file 3667 -< Str load-opts load options from a config file 3668 - disabled as '--no-load-opts' 3669 - may appear multiple times 3670 3671 Options are specified by doubled hyphens and their name or by a single 3672 hyphen and the flag character. 3673 Operands and options may be intermixed. They will be reordered. 3674 3675 The following option preset mechanisms are supported: 3676 - reading file errorsRC 3677 3678 Using the invocation, 3679 test-errors operand1 -s first operand2 -X -- -s operand3 3680 you get the following output for your shell script to evaluate: 3681 3682 OPTION_CT=4 3683 export OPTION_CT 3684 TEST_ERRORS_SECOND='first' 3685 export TEST_ERRORS_SECOND 3686 TEST_ERRORS_ANOTHER=1 # 0x1 3687 export TEST_ERRORS_ANOTHER 3688 set -- 'operand1' 'operand2' '-s' 'operand3' 3689 OPTION_CT=0 3690 3691 3692File: autogen.info, Node: script-parser, Prev: binary-parser, Up: shell options 3693 36947.12.2 Parsing with a Portable Script 3695------------------------------------- 3696 3697If you had used 'test-main = optionParseShell' instead, then you can, at 3698this point, merely run the program and it will write the parsing script 3699to standard out. You may also provide this program with command line 3700options to specify the shell script file to create or edit, and you may 3701specify the shell program to use on the first shell script line. That 3702program's usage text would look something like the following and the 3703script parser itself would be very verbose: 3704 3705 genshellopt - Generate Shell Option Processing Script - Ver. 1 3706 Usage: genshellopt [ -<flag> [<val>] | --<name>[{=| }<val>] ]... 3707 Flg Arg Option-Name Description 3708 -o Str script Output Script File 3709 -s Str shell Shell name (follows "#!" magic) 3710 - disabled as '--no-shell' 3711 - enabled by default 3712 -v opt version output version information and exit 3713 -? no help display extended usage information and exit 3714 -! no more-help extended usage information passed thru pager 3715 3716 Options are specified by doubled hyphens and their name or by a single 3717 hyphen and the flag character. 3718 Note that 'shell' is only useful if the output file does not already exist. 3719 If it does, then the shell name and optional first argument will be 3720 extracted from the script file. 3721 If the script file already exists and contains Automated Option Processing 3722 text, the second line of the file through the ending tag will be replaced 3723 by the newly generated text. The first '#!' line will be regenerated. 3724 3725 Please send bug reports to: <autogen-users@lists.sourceforge.net> 3726 3727 = = = = = = = = 3728 3729 This incarnation of genshell will produce 3730 a shell script to parse the options for getdefs: 3731 3732 getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5 3733 Usage: getdefs [ <option-name>[{=| }<val>] ]... 3734 Arg Option-Name Description 3735 Str defs-to-get Regexp to look for after the "/*=" 3736 Str subblock subblock definition names 3737 Str listattr attribute with list of values 3738 opt ordering Alphabetize or use named file 3739 Num first-index The first index to apply to groups 3740 opt filelist Insert source file names into defs 3741 Str assign Global assignments 3742 Str common-assign Assignments common to all blocks 3743 Str copy File(s) to copy into definitions 3744 opt srcfile Insert source file name into each def 3745 opt linenum Insert source line number into each def 3746 Str input Input file to search for defs 3747 Str output Output file to open 3748 opt autogen Invoke AutoGen with defs 3749 Str template Template Name 3750 Str agarg AutoGen Argument 3751 Str base-name Base name for output file(s) 3752 3753Resulting in the following script: 3754 #! /bin/sh 3755 # # # # # # # # # # -- do not modify this marker -- 3756 # 3757 # DO NOT EDIT THIS SECTION 3758 OF /u/bkorb/tools/ag/autogen-bld/doc/ag-texi-32340.d/.ag-5GQlKL/genshellopt.sh 3759 # 3760 # From here to the next `-- do not modify this marker --', 3761 # the text has been generated Sunday August 26, 2018 at 10:46:02 AM PDT 3762 # From the GETDEFS option definitions 3763 # 3764 GETDEFS_LONGUSAGE_TEXT='getdefs error: invalid option descriptor for version 3765 getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5 3766 Usage: getdefs [ <option-name>[{=| }<val>] ]... 3767 3768 Specify which definitions are of interest and what to say about them: 3769 3770 Arg Option-Name Description 3771 Str defs-to-get Regexp to look for after the "/*=" 3772 Str subblock subblock definition names 3773 - may appear multiple times 3774 Str listattr attribute with list of values 3775 - may appear multiple times 3776 3777 specify how to number the definitions: 3778 3779 Arg Option-Name Description 3780 opt ordering Alphabetize or use named file 3781 - disabled as '\''--no-ordering'\'' 3782 - enabled by default 3783 Num first-index The first index to apply to groups 3784 3785 Definition insertion options: 3786 3787 Arg Option-Name Description 3788 opt filelist Insert source file names into defs 3789 Str assign Global assignments 3790 - may appear multiple times 3791 Str common-assign Assignments common to all blocks 3792 - may appear multiple times 3793 Str copy File(s) to copy into definitions 3794 - may appear multiple times 3795 opt srcfile Insert source file name into each def 3796 opt linenum Insert source line number into each def 3797 3798 specify which files to search for markers: 3799 3800 Arg Option-Name Description 3801 Str input Input file to search for defs 3802 - may appear multiple times 3803 - default option for unnamed options 3804 3805 Definition output disposition options:: 3806 3807 Arg Option-Name Description 3808 Str output Output file to open 3809 - an alternate for '\''autogen'\'' 3810 opt autogen Invoke AutoGen with defs 3811 - disabled as '\''--no-autogen'\'' 3812 - enabled by default 3813 Str template Template Name 3814 Str agarg AutoGen Argument 3815 - prohibits the option '\''output'\'' 3816 - may appear multiple times 3817 Str base-name Base name for output file(s) 3818 - prohibits the option '\''output'\'' 3819 3820 Version, usage and configuration options: 3821 3822 Arg Option-Name Description 3823 ' 3824 3825 GETDEFS_USAGE_TEXT='getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5 3826 Usage: getdefs [ <option-name>[{=| }<val>] ]... 3827 Arg Option-Name Description 3828 Str defs-to-get Regexp to look for after the "/*=" 3829 Str subblock subblock definition names 3830 Str listattr attribute with list of values 3831 opt ordering Alphabetize or use named file 3832 Num first-index The first index to apply to groups 3833 opt filelist Insert source file names into defs 3834 Str assign Global assignments 3835 Str common-assign Assignments common to all blocks 3836 Str copy File(s) to copy into definitions 3837 opt srcfile Insert source file name into each def 3838 opt linenum Insert source line number into each def 3839 Str input Input file to search for defs 3840 Str output Output file to open 3841 opt autogen Invoke AutoGen with defs 3842 Str template Template Name 3843 Str agarg AutoGen Argument 3844 Str base-name Base name for output file(s) 3845 getdefs error: invalid option descriptor for version' 3846 3847 3848 GETDEFS_DEFS_TO_GET=${GETDEFS_DEFS_TO_GET} 3849 GETDEFS_DEFS_TO_GET_set=false 3850 export GETDEFS_DEFS_TO_GET 3851 3852 if test -z "${GETDEFS_SUBBLOCK}" 3853 then 3854 GETDEFS_SUBBLOCK_CT=0 3855 export GETDEFS_SUBBLOCK_CT 3856 else 3857 GETDEFS_SUBBLOCK_CT=1 3858 GETDEFS_SUBBLOCK_1=${GETDEFS_SUBBLOCK} 3859 export GETDEFS_SUBBLOCK_CT GETDEFS_SUBBLOCK_1 3860 fi 3861 3862 if test -z "${GETDEFS_LISTATTR}" 3863 then 3864 GETDEFS_LISTATTR_CT=0 3865 export GETDEFS_LISTATTR_CT 3866 else 3867 GETDEFS_LISTATTR_CT=1 3868 GETDEFS_LISTATTR_1=${GETDEFS_LISTATTR} 3869 export GETDEFS_LISTATTR_CT GETDEFS_LISTATTR_1 3870 fi 3871 3872 GETDEFS_ORDERING=${GETDEFS_ORDERING} 3873 GETDEFS_ORDERING_set=false 3874 export GETDEFS_ORDERING 3875 3876 GETDEFS_FIRST_INDEX=${GETDEFS_FIRST_INDEX-'0'} 3877 GETDEFS_FIRST_INDEX_set=false 3878 export GETDEFS_FIRST_INDEX 3879 3880 GETDEFS_FILELIST=${GETDEFS_FILELIST} 3881 GETDEFS_FILELIST_set=false 3882 export GETDEFS_FILELIST 3883 3884 if test -z "${GETDEFS_ASSIGN}" 3885 then 3886 GETDEFS_ASSIGN_CT=0 3887 export GETDEFS_ASSIGN_CT 3888 else 3889 GETDEFS_ASSIGN_CT=1 3890 GETDEFS_ASSIGN_1=${GETDEFS_ASSIGN} 3891 export GETDEFS_ASSIGN_CT GETDEFS_ASSIGN_1 3892 fi 3893 3894 if test -z "${GETDEFS_COMMON_ASSIGN}" 3895 then 3896 GETDEFS_COMMON_ASSIGN_CT=0 3897 export GETDEFS_COMMON_ASSIGN_CT 3898 else 3899 GETDEFS_COMMON_ASSIGN_CT=1 3900 GETDEFS_COMMON_ASSIGN_1=${GETDEFS_COMMON_ASSIGN} 3901 export GETDEFS_COMMON_ASSIGN_CT GETDEFS_COMMON_ASSIGN_1 3902 fi 3903 3904 if test -z "${GETDEFS_COPY}" 3905 then 3906 GETDEFS_COPY_CT=0 3907 export GETDEFS_COPY_CT 3908 else 3909 GETDEFS_COPY_CT=1 3910 GETDEFS_COPY_1=${GETDEFS_COPY} 3911 export GETDEFS_COPY_CT GETDEFS_COPY_1 3912 fi 3913 3914 GETDEFS_SRCFILE=${GETDEFS_SRCFILE} 3915 GETDEFS_SRCFILE_set=false 3916 export GETDEFS_SRCFILE 3917 3918 GETDEFS_LINENUM=${GETDEFS_LINENUM} 3919 GETDEFS_LINENUM_set=false 3920 export GETDEFS_LINENUM 3921 3922 if test -z "${GETDEFS_INPUT}" 3923 then 3924 GETDEFS_INPUT_CT=0 3925 export GETDEFS_INPUT_CT 3926 else 3927 GETDEFS_INPUT_CT=1 3928 GETDEFS_INPUT_1=${GETDEFS_INPUT} 3929 export GETDEFS_INPUT_CT GETDEFS_INPUT_1 3930 fi 3931 3932 GETDEFS_OUTPUT=${GETDEFS_OUTPUT} 3933 GETDEFS_OUTPUT_set=false 3934 export GETDEFS_OUTPUT 3935 3936 GETDEFS_AUTOGEN=${GETDEFS_AUTOGEN} 3937 GETDEFS_AUTOGEN_set=false 3938 export GETDEFS_AUTOGEN 3939 3940 GETDEFS_TEMPLATE=${GETDEFS_TEMPLATE} 3941 GETDEFS_TEMPLATE_set=false 3942 export GETDEFS_TEMPLATE 3943 3944 if test -z "${GETDEFS_AGARG}" 3945 then 3946 GETDEFS_AGARG_CT=0 3947 export GETDEFS_AGARG_CT 3948 else 3949 GETDEFS_AGARG_CT=1 3950 GETDEFS_AGARG_1=${GETDEFS_AGARG} 3951 export GETDEFS_AGARG_CT GETDEFS_AGARG_1 3952 fi 3953 3954 GETDEFS_BASE_NAME=${GETDEFS_BASE_NAME} 3955 GETDEFS_BASE_NAME_set=false 3956 export GETDEFS_BASE_NAME 3957 3958 ARG_COUNT=$# 3959 OPT_ARG=$1 3960 while [ $# -gt 0 ] 3961 do 3962 OPT_ELEMENT='' 3963 OPT_ARG_VAL='' 3964 OPT_ARG=${1} 3965 OPT_CODE=`echo "X${OPT_ARG}"|sed 's/^X-*//'` 3966 shift 3967 OPT_ARG=$1 3968 case "${OPT_CODE}" in *=* ) 3969 OPT_ARG_VAL=`echo "${OPT_CODE}"|sed 's/^[^=]*=//'` 3970 OPT_CODE=`echo "${OPT_CODE}"|sed 's/=.*$//'` ;; esac 3971 case "${OPT_CODE}" in 3972 'de' | \ 3973 'def' | \ 3974 'defs' | \ 3975 'defs-' | \ 3976 'defs-t' | \ 3977 'defs-to' | \ 3978 'defs-to-' | \ 3979 'defs-to-g' | \ 3980 'defs-to-ge' | \ 3981 'defs-to-get' ) 3982 if [ -n "${GETDEFS_DEFS_TO_GET}" ] && ${GETDEFS_DEFS_TO_GET_set} ; then 3983 echo 'Error: duplicate DEFS_TO_GET option' 3984 echo "$GETDEFS_USAGE_TEXT" 3985 exit 1 3986 fi >&2 3987 GETDEFS_DEFS_TO_GET_set=true 3988 OPT_NAME='DEFS_TO_GET' 3989 OPT_ARG_NEEDED=YES 3990 ;; 3991 3992 'su' | \ 3993 'sub' | \ 3994 'subb' | \ 3995 'subbl' | \ 3996 'subblo' | \ 3997 'subbloc' | \ 3998 'subblock' ) 3999 GETDEFS_SUBBLOCK_CT=`expr ${GETDEFS_SUBBLOCK_CT} + 1` 4000 OPT_ELEMENT="_${GETDEFS_SUBBLOCK_CT}" 4001 OPT_NAME='SUBBLOCK' 4002 OPT_ARG_NEEDED=YES 4003 ;; 4004 4005 'li' | \ 4006 'lis' | \ 4007 'list' | \ 4008 'lista' | \ 4009 'listat' | \ 4010 'listatt' | \ 4011 'listattr' ) 4012 GETDEFS_LISTATTR_CT=`expr ${GETDEFS_LISTATTR_CT} + 1` 4013 OPT_ELEMENT="_${GETDEFS_LISTATTR_CT}" 4014 OPT_NAME='LISTATTR' 4015 OPT_ARG_NEEDED=YES 4016 ;; 4017 4018 'or' | \ 4019 'ord' | \ 4020 'orde' | \ 4021 'order' | \ 4022 'orderi' | \ 4023 'orderin' | \ 4024 'ordering' ) 4025 if [ -n "${GETDEFS_ORDERING}" ] && ${GETDEFS_ORDERING_set} ; then 4026 echo 'Error: duplicate ORDERING option' 4027 echo "$GETDEFS_USAGE_TEXT" 4028 exit 1 4029 fi >&2 4030 GETDEFS_ORDERING_set=true 4031 OPT_NAME='ORDERING' 4032 eval GETDEFS_ORDERING${OPT_ELEMENT}=true 4033 export GETDEFS_ORDERING${OPT_ELEMENT} 4034 OPT_ARG_NEEDED=OK 4035 ;; 4036 4037 'no-' | \ 4038 'no-o' | \ 4039 'no-or' | \ 4040 'no-ord' | \ 4041 'no-orde' | \ 4042 'no-order' | \ 4043 'no-orderi' | \ 4044 'no-orderin' | \ 4045 'no-ordering' ) 4046 if [ -n "${GETDEFS_ORDERING}" ] && ${GETDEFS_ORDERING_set} ; then 4047 echo 'Error: duplicate ORDERING option' 4048 echo "$GETDEFS_USAGE_TEXT" 4049 exit 1 4050 fi >&2 4051 GETDEFS_ORDERING_set=true 4052 GETDEFS_ORDERING='no' 4053 export GETDEFS_ORDERING 4054 OPT_NAME='ORDERING' 4055 OPT_ARG_NEEDED=NO 4056 ;; 4057 4058 'fi' | \ 4059 'fir' | \ 4060 'firs' | \ 4061 'first' | \ 4062 'first-' | \ 4063 'first-i' | \ 4064 'first-in' | \ 4065 'first-ind' | \ 4066 'first-inde' | \ 4067 'first-index' ) 4068 if [ -n "${GETDEFS_FIRST_INDEX}" ] && ${GETDEFS_FIRST_INDEX_set} ; then 4069 echo 'Error: duplicate FIRST_INDEX option' 4070 echo "$GETDEFS_USAGE_TEXT" 4071 exit 1 4072 fi >&2 4073 GETDEFS_FIRST_INDEX_set=true 4074 OPT_NAME='FIRST_INDEX' 4075 OPT_ARG_NEEDED=YES 4076 ;; 4077 4078 'fi' | \ 4079 'fil' | \ 4080 'file' | \ 4081 'filel' | \ 4082 'fileli' | \ 4083 'filelis' | \ 4084 'filelist' ) 4085 if [ -n "${GETDEFS_FILELIST}" ] && ${GETDEFS_FILELIST_set} ; then 4086 echo 'Error: duplicate FILELIST option' 4087 echo "$GETDEFS_USAGE_TEXT" 4088 exit 1 4089 fi >&2 4090 GETDEFS_FILELIST_set=true 4091 OPT_NAME='FILELIST' 4092 eval GETDEFS_FILELIST${OPT_ELEMENT}=true 4093 export GETDEFS_FILELIST${OPT_ELEMENT} 4094 OPT_ARG_NEEDED=OK 4095 ;; 4096 4097 'as' | \ 4098 'ass' | \ 4099 'assi' | \ 4100 'assig' | \ 4101 'assign' ) 4102 GETDEFS_ASSIGN_CT=`expr ${GETDEFS_ASSIGN_CT} + 1` 4103 OPT_ELEMENT="_${GETDEFS_ASSIGN_CT}" 4104 OPT_NAME='ASSIGN' 4105 OPT_ARG_NEEDED=YES 4106 ;; 4107 4108 'co' | \ 4109 'com' | \ 4110 'comm' | \ 4111 'commo' | \ 4112 'common' | \ 4113 'common-' | \ 4114 'common-a' | \ 4115 'common-as' | \ 4116 'common-ass' | \ 4117 'common-assi' | \ 4118 'common-assig' | \ 4119 'common-assign' ) 4120 GETDEFS_COMMON_ASSIGN_CT=`expr ${GETDEFS_COMMON_ASSIGN_CT} + 1` 4121 OPT_ELEMENT="_${GETDEFS_COMMON_ASSIGN_CT}" 4122 OPT_NAME='COMMON_ASSIGN' 4123 OPT_ARG_NEEDED=YES 4124 ;; 4125 4126 'co' | \ 4127 'cop' | \ 4128 'copy' ) 4129 GETDEFS_COPY_CT=`expr ${GETDEFS_COPY_CT} + 1` 4130 OPT_ELEMENT="_${GETDEFS_COPY_CT}" 4131 OPT_NAME='COPY' 4132 OPT_ARG_NEEDED=YES 4133 ;; 4134 4135 'sr' | \ 4136 'src' | \ 4137 'srcf' | \ 4138 'srcfi' | \ 4139 'srcfil' | \ 4140 'srcfile' ) 4141 if [ -n "${GETDEFS_SRCFILE}" ] && ${GETDEFS_SRCFILE_set} ; then 4142 echo 'Error: duplicate SRCFILE option' 4143 echo "$GETDEFS_USAGE_TEXT" 4144 exit 1 4145 fi >&2 4146 GETDEFS_SRCFILE_set=true 4147 OPT_NAME='SRCFILE' 4148 eval GETDEFS_SRCFILE${OPT_ELEMENT}=true 4149 export GETDEFS_SRCFILE${OPT_ELEMENT} 4150 OPT_ARG_NEEDED=OK 4151 ;; 4152 4153 'li' | \ 4154 'lin' | \ 4155 'line' | \ 4156 'linen' | \ 4157 'linenu' | \ 4158 'linenum' ) 4159 if [ -n "${GETDEFS_LINENUM}" ] && ${GETDEFS_LINENUM_set} ; then 4160 echo 'Error: duplicate LINENUM option' 4161 echo "$GETDEFS_USAGE_TEXT" 4162 exit 1 4163 fi >&2 4164 GETDEFS_LINENUM_set=true 4165 OPT_NAME='LINENUM' 4166 eval GETDEFS_LINENUM${OPT_ELEMENT}=true 4167 export GETDEFS_LINENUM${OPT_ELEMENT} 4168 OPT_ARG_NEEDED=OK 4169 ;; 4170 4171 'in' | \ 4172 'inp' | \ 4173 'inpu' | \ 4174 'input' ) 4175 GETDEFS_INPUT_CT=`expr ${GETDEFS_INPUT_CT} + 1` 4176 OPT_ELEMENT="_${GETDEFS_INPUT_CT}" 4177 OPT_NAME='INPUT' 4178 OPT_ARG_NEEDED=YES 4179 ;; 4180 4181 'ou' | \ 4182 'out' | \ 4183 'outp' | \ 4184 'outpu' | \ 4185 'output' ) 4186 if [ -n "${GETDEFS_OUTPUT}" ] && ${GETDEFS_OUTPUT_set} ; then 4187 echo 'Error: duplicate OUTPUT option' 4188 echo "$GETDEFS_USAGE_TEXT" 4189 exit 1 4190 fi >&2 4191 GETDEFS_OUTPUT_set=true 4192 OPT_NAME='OUTPUT' 4193 OPT_ARG_NEEDED=YES 4194 ;; 4195 4196 'au' | \ 4197 'aut' | \ 4198 'auto' | \ 4199 'autog' | \ 4200 'autoge' | \ 4201 'autogen' ) 4202 if [ -n "${GETDEFS_AUTOGEN}" ] && ${GETDEFS_AUTOGEN_set} ; then 4203 echo 'Error: duplicate AUTOGEN option' 4204 echo "$GETDEFS_USAGE_TEXT" 4205 exit 1 4206 fi >&2 4207 GETDEFS_AUTOGEN_set=true 4208 OPT_NAME='AUTOGEN' 4209 eval GETDEFS_AUTOGEN${OPT_ELEMENT}=true 4210 export GETDEFS_AUTOGEN${OPT_ELEMENT} 4211 OPT_ARG_NEEDED=OK 4212 ;; 4213 4214 'no-' | \ 4215 'no-a' | \ 4216 'no-au' | \ 4217 'no-aut' | \ 4218 'no-auto' | \ 4219 'no-autog' | \ 4220 'no-autoge' | \ 4221 'no-autogen' ) 4222 if [ -n "${GETDEFS_AUTOGEN}" ] && ${GETDEFS_AUTOGEN_set} ; then 4223 echo 'Error: duplicate AUTOGEN option' 4224 echo "$GETDEFS_USAGE_TEXT" 4225 exit 1 4226 fi >&2 4227 GETDEFS_AUTOGEN_set=true 4228 GETDEFS_AUTOGEN='no' 4229 export GETDEFS_AUTOGEN 4230 OPT_NAME='AUTOGEN' 4231 OPT_ARG_NEEDED=NO 4232 ;; 4233 4234 'te' | \ 4235 'tem' | \ 4236 'temp' | \ 4237 'templ' | \ 4238 'templa' | \ 4239 'templat' | \ 4240 'template' ) 4241 if [ -n "${GETDEFS_TEMPLATE}" ] && ${GETDEFS_TEMPLATE_set} ; then 4242 echo 'Error: duplicate TEMPLATE option' 4243 echo "$GETDEFS_USAGE_TEXT" 4244 exit 1 4245 fi >&2 4246 GETDEFS_TEMPLATE_set=true 4247 OPT_NAME='TEMPLATE' 4248 OPT_ARG_NEEDED=YES 4249 ;; 4250 4251 'ag' | \ 4252 'aga' | \ 4253 'agar' | \ 4254 'agarg' ) 4255 GETDEFS_AGARG_CT=`expr ${GETDEFS_AGARG_CT} + 1` 4256 OPT_ELEMENT="_${GETDEFS_AGARG_CT}" 4257 OPT_NAME='AGARG' 4258 OPT_ARG_NEEDED=YES 4259 ;; 4260 4261 'ba' | \ 4262 'bas' | \ 4263 'base' | \ 4264 'base-' | \ 4265 'base-n' | \ 4266 'base-na' | \ 4267 'base-nam' | \ 4268 'base-name' ) 4269 if [ -n "${GETDEFS_BASE_NAME}" ] && ${GETDEFS_BASE_NAME_set} ; then 4270 echo 'Error: duplicate BASE_NAME option' 4271 echo "$GETDEFS_USAGE_TEXT" 4272 exit 1 4273 fi >&2 4274 GETDEFS_BASE_NAME_set=true 4275 OPT_NAME='BASE_NAME' 4276 OPT_ARG_NEEDED=YES 4277 ;; 4278 4279 've' | \ 4280 'ver' | \ 4281 'vers' | \ 4282 'versi' | \ 4283 'versio' | \ 4284 'version' ) 4285 echo "$GETDEFS_LONGUSAGE_TEXT" 4286 exit 0 4287 ;; 4288 4289 'he' | \ 4290 'hel' | \ 4291 'help' ) 4292 echo "$GETDEFS_LONGUSAGE_TEXT" 4293 exit 0 4294 ;; 4295 4296 'mo' | \ 4297 'mor' | \ 4298 'more' | \ 4299 'more-' | \ 4300 'more-h' | \ 4301 'more-he' | \ 4302 'more-hel' | \ 4303 'more-help' ) 4304 echo "$GETDEFS_LONGUSAGE_TEXT" | ${PAGER-more} 4305 exit 0 4306 ;; 4307 4308 'sa' | \ 4309 'sav' | \ 4310 'save' | \ 4311 'save-' | \ 4312 'save-o' | \ 4313 'save-op' | \ 4314 'save-opt' | \ 4315 'save-opts' ) 4316 echo 'Warning: Cannot save options files' >&2 4317 OPT_ARG_NEEDED=OK 4318 ;; 4319 4320 'lo' | \ 4321 'loa' | \ 4322 'load' | \ 4323 'load-' | \ 4324 'load-o' | \ 4325 'load-op' | \ 4326 'load-opt' | \ 4327 'load-opts' ) 4328 echo 'Warning: Cannot load options files' >&2 4329 OPT_ARG_NEEDED=YES 4330 ;; 4331 4332 'no-' | \ 4333 'no-l' | \ 4334 'no-lo' | \ 4335 'no-loa' | \ 4336 'no-load' | \ 4337 'no-load-' | \ 4338 'no-load-o' | \ 4339 'no-load-op' | \ 4340 'no-load-opt' | \ 4341 'no-load-opts' ) 4342 echo 'Warning: Cannot suppress the loading of options files' >&2 4343 OPT_ARG_NEEDED=NO 4344 ;; 4345 4346 * ) 4347 echo Unknown option: "${OPT_CODE}" >&2 4348 echo "$GETDEFS_USAGE_TEXT" >&2 4349 exit 1 4350 ;; 4351 esac 4352 case "${OPT_ARG_NEEDED}" in 4353 NO ) 4354 OPT_ARG_VAL='' 4355 ;; 4356 YES ) 4357 if [ -z "${OPT_ARG_VAL}" ] 4358 then 4359 if [ $# -eq 0 ] 4360 then 4361 echo No argument provided for ${OPT_NAME} option 4362 echo "$GETDEFS_USAGE_TEXT" 4363 exit 1 4364 fi >&2 4365 OPT_ARG_VAL=${OPT_ARG} 4366 shift 4367 OPT_ARG=$1 4368 fi 4369 ;; 4370 OK ) 4371 if [ -z "${OPT_ARG_VAL}" ] && [ $# -gt 0 ] 4372 then 4373 case "${OPT_ARG}" in -* ) ;; * ) 4374 OPT_ARG_VAL=${OPT_ARG} 4375 shift 4376 OPT_ARG=$1 ;; esac 4377 fi 4378 ;; 4379 esac 4380 if [ -n "${OPT_ARG_VAL}" ] 4381 then 4382 eval GETDEFS_${OPT_NAME}${OPT_ELEMENT}="'${OPT_ARG_VAL}'" 4383 export GETDEFS_${OPT_NAME}${OPT_ELEMENT} 4384 fi 4385 done 4386 OPTION_COUNT=`expr $ARG_COUNT - $#` 4387 OPERAND_COUNT=$# 4388 unset OPT_PROCESS || : 4389 unset OPT_ELEMENT || : 4390 unset OPT_ARG || : 4391 unset OPT_ARG_NEEDED || : 4392 unset OPT_NAME || : 4393 unset OPT_CODE || : 4394 unset OPT_ARG_VAL || : 4395 4396 # # # # # # # # # # 4397 # 4398 # END OF AUTOMATED OPTION PROCESSING 4399 # 4400 # # # # # # # # # # -- do not modify this marker -- 4401 4402 env | grep '^GETDEFS_' 4403 4404 4405File: autogen.info, Node: AutoInfo, Next: AutoMan pages, Prev: shell options, Up: AutoOpts 4406 44077.13 Automated Info Docs 4408======================== 4409 4410AutoOpts provides two templates for producing '.texi' documentation. 4411'agtexi-cmd.tpl' for the invoking section, and 'aginfo3.tpl' for 4412describing exported library functions and macros. 4413 4414 For both types of documents, the documentation level is selected by 4415passing a '-DLEVEL=<level-name>' argument to AutoGen when you build the 4416document. (See the example invocation below.) 4417 4418 Two files will be produced, a '.texi' file and a '.menu' file. You 4419should include the text in the '.menu' file in a '@menu' list, either 4420with '@include'-ing it or just copying text. The '.texi' file should be 4421'@include'-ed where the invoking section belongs in your document. 4422 4423 The '.texi' file will contain an introductory paragraph, a menu and a 4424subordinate section for the invocation usage and for each documented 4425option. The introductory paragraph is normally the boiler plate text, 4426along the lines of: 4427 4428 This chapter documents the @file{AutoOpts} generated usage text 4429 and option meanings for the @file{your-program} program. 4430 4431or: 4432 4433 These are the publicly exported procedures from the libname library. 4434 Any other functions mentioned in the header file are for the private use 4435 of the library. 4436 4437* Menu: 4438 4439* command-info:: 'invoking' info docs 4440* library-info:: library info docs 4441 4442 4443File: autogen.info, Node: command-info, Next: library-info, Up: AutoInfo 4444 44457.13.1 'invoking' info docs 4446--------------------------- 4447 4448Using the option definitions for an AutoOpt client program, the 4449'agtexi-cmd.tpl' template will produce texinfo text that documents the 4450invocation of your program. The text emitted is designed to be included 4451in the full texinfo document for your product. It is not a stand-alone 4452document. The usage text for the *note autogen usage::, *note getdefs 4453usage:: and *note columns usage:: programs, are included in this 4454document and are all generated using this template. 4455 4456 If your program's option definitions include a 'prog-info-descrip' 4457section, then that text will replace the boilerplate introductory 4458paragraph. 4459 4460These files are produced by invoking the following command: 4461 4462 autogen -L ${prefix}/share/autogen -Tagtexi-cmd.tpl \ 4463 -DLEVEL=section your-opts.def 4464 4465Where '${prefix}' is the AutoGen installation prefix and 'your-opts.def' 4466is the name of your product's option definition file. 4467 4468 4469File: autogen.info, Node: library-info, Prev: command-info, Up: AutoInfo 4470 44717.13.2 library info docs 4472------------------------ 4473 4474The 'texinfo' doc for libraries is derived from mostly the same 4475information as is used for producing man pages *Note man3::. The main 4476difference is that there is only one output file and the individual 4477functions are referenced from a 'texi' menu. There is also a small 4478difference in the global attributes used: 4479 4480 lib_description A description of the library. This text 4481 appears before the menu. If not provided, 4482 the standard boilerplate version will be 4483 inserted. 4484 see_also The 'SEE ALSO' functionality is not supported 4485 for the 'texinfo' documentation, so any 4486 'see_also' attribute will be ignored. 4487 4488These files are produced by invoking the following commands: 4489 4490 getdefs linenum srcfile template=aginfo3.tpl output=libexport.def \ 4491 <source-file-list> 4492 4493 autogen -L ${prefix}/share/autogen -DLEVEL=section libexport.def 4494 4495Where '${prefix}' is the AutoGen installation prefix and 'libexport.def' 4496is some name that suits you. 4497 4498 An example of this can be seen in this document, *Note libopts 4499procedures::. 4500 4501 4502File: autogen.info, Node: AutoMan pages, Next: getopt_long, Prev: AutoInfo, Up: AutoOpts 4503 45047.14 Automated Man Pages 4505======================== 4506 4507AutoOpts provides two templates for producing man pages. The command 4508('man1') pages are derived from the options definition file, and the 4509library ('man3') pages are derived from stylized comments (*note getdefs 4510Invocation::). 4511 4512 Man pages include a date in the footer. By default, this is derived 4513from the current date. However, this may be overridden with the 4514'MAN_PAGE_DATE' environment variable. If set and not empty, its 4515contents will be copied into where the output of 'date '+%d %b %Y'' 4516would otherwise go. 4517 4518 Man pages may be formatted as either traditional man pages or using 4519'mdoc' formatting. The format is selected by selecting the appropriate 4520template. 4521 4522* Menu: 4523 4524* man1:: command line man pages 4525* man3:: library man pages 4526 4527 4528File: autogen.info, Node: man1, Next: man3, Up: AutoMan pages 4529 45307.14.1 command line man pages 4531----------------------------- 4532 4533Man pages for commands are documented using the 'agman-cmd.tpl' and 4534'agmdoc-cmd.tpl' templates. If the options specify pulling information 4535from 'RC'/'ini'/'cfg' files, then you may use the 'rc-sample.tpl' 4536template to produce an example config file for your program. 4537 4538 Using the option definitions for an AutoOpts client program, the 4539'agman-cmd.tpl' template will produce an nroff document suitable for use 4540as a 'man(1)' page document for a command line command. The description 4541section of the document is either the 'prog-man-descrip' text, if 4542present, or the 'detail' text. 4543 4544 Each option in the option definitions file is fully documented in its 4545usage. This includes all the information documented above for each 4546option (*note option attributes::), plus the 'doc' attribute is 4547appended. Since the 'doc' text is presumed to be designed for 'texinfo' 4548documentation, 'sed' is used to convert some constructs from 'texi' to 4549'nroff'-for-'man'-pages. Specifically, 4550 4551 convert @code, @var and @samp into \fB...\fP phrases 4552 convert @file into \fI...\fP phrases 4553 Remove the '@' prefix from curly braces 4554 Indent example regions 4555 Delete the example commands 4556 Replace 'end example' command with ".br" 4557 Replace the '@*' command with ".br" 4558 4559This document is produced by invoking the following command: 4560 4561 autogen -L ${prefix}/share/autogen -Tagman-cmd.tpl options.def 4562 4563Where '${prefix}' is the AutoGen installation prefix and 'options.def' 4564is the name of your product's option definition file. I do not use this 4565very much, so any feedback or improvements would be greatly appreciated. 4566 4567 4568File: autogen.info, Node: man3, Prev: man1, Up: AutoMan pages 4569 45707.14.2 library man pages 4571------------------------ 4572 4573Man pages for libraries are documented using the 'agman3.tpl' template. 4574 4575 Two global definitions are required, and then one library man page is 4576produced for each 'export_func' definition that is found. It is 4577generally convenient to place these definitions as 'getdefs' comments 4578(*note getdefs Invocation::) near the procedure definition, but they may 4579also be a separate AutoGen definitions file (*note Definitions File::). 4580Each function will be cross referenced with their sister functions in a 4581'SEE ALSO' section. A global 'see_also' definition will be appended to 4582this cross referencing text. 4583 4584The two global definitions required are: 4585 4586 library This is the name of your library, without the 'lib' 4587 prefix. The AutoOpts library is named 4588 'libopts.so...', so the 'library' attribute would 4589 have the value 'opts'. 4590 header Generally, using a library with a compiled program 4591 entails '#include'-ing a header file. Name that 4592 header with this attribute. In the case of AutoOpts, 4593 it is generated and will vary based on the name of 4594 the option definition file. Consequently, 4595 'your-opts.h' is specified. 4596 4597The 'export_func' definition should contain the following attributes: 4598 4599 name The name of the procedure the library user may call. 4600 what A brief sentence describing what the procedure does. 4601 doc A detailed description of what the procedure does. 4602 It may ramble on for as long as necessary to properly 4603 describe it. 4604 err A short description of how errors are handled. 4605 ret_type The data type returned by the procedure. Omit this 4606 for 'void' procedures. 4607 ret_desc Describe what the returned value is, if needed. 4608 private If specified, the function will *not* be documented. 4609 This is used, for example, to produce external 4610 declarations for functions that are not available for 4611 public use, but are used in the generated text. 4612 arg This is a compound attribute that contains: 4613 arg_type The data type of the argument. 4614 arg_name A short name for it. 4615 arg_desc A brief description. 4616 4617As a 'getdefs' comment, this would appear something like this: 4618 4619 /*=--subblock=arg=arg_type,arg_name,arg_desc =*/ 4620 /*=* 4621 * library: opts 4622 * header: your-opts.h 4623 =*/ 4624 /*=export_func optionProcess 4625 * 4626 * what: this is the main option processing routine 4627 * arg: + tOptions* + pOpts + program options descriptor + 4628 * arg: + int + argc + program arg count + 4629 * arg: + char** + argv + program arg vector + 4630 * ret_type: int 4631 * ret_desc: the count of the arguments processed 4632 * 4633 * doc: This is what it does. 4634 * err: When it can't, it does this. 4635 =*/ 4636 4637Note the 'subblock' and 'library' comments. 'subblock' is an embedded 4638'getdefs' option (*note getdefs subblock::) that tells it how to parse 4639the 'arg' attribute. The 'library' and 'header' entries are global 4640definitions that apply to all the documented functions. 4641 4642 4643File: autogen.info, Node: getopt_long, Next: i18n, Prev: AutoMan pages, Up: AutoOpts 4644 46457.15 Using getopt(3C) 4646===================== 4647 4648There is a template named, 'getopt.tpl' that is distributed with 4649AutoOpts. Using that template instead of 'options.tpl' will produce 4650completely independent source code that will parse command line options. 4651It will utilize either the standard 'getopt(3C)' or the GNU 4652'getopt_long(3GNU)' function to drive the parsing. Which is used is 4653selected by the presence or absence of the 'long-opts' program 4654attribute. It will save you from being dependent upon the 'libopts' 4655library and it produces code ready for internationalization. However, 4656it also carries with it some limitations on the use of AutoOpts features 4657and some requirements on the build environment. 4658 4659 *PLEASE NOTE*: in processing the option definitions to produce the 4660usage text, it is necessary to compile some generated code in a 4661temporary directory. That means that all the include directories needed 4662to compile the code must be full path names and not relative directory 4663names. "." is a relative directory name. To specify "-I." in the 4664'CFLAGS' environment variable, you must expand it. For example, use: 4665 CFLAGS=-I`pwd` 4666 4667* Menu: 4668 4669* getopt limitations:: getopt feature limitations 4670* getopt building:: getopt build requirements 4671 4672 4673File: autogen.info, Node: getopt limitations, Next: getopt building, Up: getopt_long 4674 46757.15.1 getopt feature limitations 4676--------------------------------- 4677 4678This list of limitations is relative to the full list of AutoOpts 4679supported features, *Note Features::. 4680 4681 1. You cannot automatically take advantage of environment variable 4682 options or automated parsing of configuration files ('rc' or 'ini' 4683 files). Consequently, the resulting code does not support 4684 '--load-opts' or '--save-opts' options automatically. 4685 4686 2. You cannot use set membership, enumerated, range checked or stacked 4687 argument type options. In fact, you cannot use anything that 4688 depends upon the 'libopts' library. You are constrained to options 4689 that take 'string' arguments, though you may handle the option 4690 argument with a callback procedure. 4691 4692 3. Special disablement and/or enablement prefixes are not recognized. 4693 4694 4. Option coordination with external libraries will not work. 4695 4696 5. Every option must be 'settable' because the emitted code depends 4697 upon the 'SET_OPT_XXX' macros having been defined. Specify this as 4698 a global (program) attribute. 4699 4700 6. You must specify a main procedure attribute (*note Generated 4701 main::). The 'getopt.tpl' template depends upon being able to 4702 compile the traditional .c file into a program and get it to emit 4703 the usage text. 4704 4705 7. For the same reason, the traditional option parsing table code must 4706 be emitted before the 'getopt.tpl' template gets expanded. 4707 4708 8. The usage text is, therefore, statically defined. 4709 4710 4711File: autogen.info, Node: getopt building, Prev: getopt limitations, Up: getopt_long 4712 47137.15.2 getopt build requirements 4714-------------------------------- 4715 4716You must supply some compile and link options via environment variables. 4717 4718'srcdir' 4719 In case the option definition file lives in a different directory. 4720'CFLAGS' 4721 Any special flags required to compile. The flags from 4722 'autoopts-config cflags' will be included automatically. Since the 4723 creation of the option parsing code includes creating a program 4724 that prints out help text, if it is necessary to include files from 4725 various directories to compile that program, you will need to 4726 specify those directories with '-Idirpath' text in the 'CFLAGS'. 4727 Some experimentation may be necessary in that case. 4728 4729 *NOTE*: the '-Idirpath' text is only needed if your option callback 4730 functions include code that require additional '#include' 4731 directives. 4732'LDFLAGS' 4733 Any special flags required to link. The flags from 4734 'autoopts-config ldflags' will be included automatically. This is 4735 required only if additional link flags for the help text emission 4736 program might be needed. 4737'CC' 4738 This is needed only if 'cc' cannot be found in '$PATH' (or it is 4739 not the one you want). 4740 4741 To use this, set the exported environment variables and specify 4742'getopt' as the default template in your option definitions file (*note 4743Identification::). You will have four new files. Assuming your 4744definitions were in a file named 'myprog-opts.def' and your program name 4745was specified as 'progname', the resulting files would be created: 4746'myprog-opts.h', 'myprog-opts.c', 'getopt-progname.h' and 4747'getopt-progname.c'. You must compile and link both '.c' files into 4748your program. If there are link failures, then you are using AutoOpts 4749features that require the 'libopts' library. You must remove these 4750features, *Note getopt limitations::. 4751 4752 These generated files depend upon configure defines to work 4753correctly. Therefore, you must specify a 'config-header' attribute 4754(*note programming attributes::) and ensure it has '#defines' for either 4755'HAVE_STDINT_H' or 'HAVE_INTTYPES_H'; either 'HAVE_SYS_LIMITS_H' or 4756'HAVE_LIMITS_H'; and 'HAVE_SYSEXITS_H', if the 'sysexits.h' header is 4757available. The required header files for these defines are, 4758respectively, the '/usr/include' files named: 4759 * stdint.h 4760 * inttypes.h 4761 * sys/limits.h 4762 * limits.h 4763 * sysexits.h 4764 4765The following header files must also exist on the build platform: 4766 * sys/types.h 4767 * stdio.h 4768 * string.h 4769 * unistd.h - or, for getopt_long: 4770 * getopt.h 4771 4772 4773File: autogen.info, Node: i18n, Next: Naming Conflicts, Prev: getopt_long, Up: AutoOpts 4774 47757.16 Internationalizing AutoOpts 4776================================ 4777 4778The generated code for AutoOpts will enable and disable the translation 4779of AutoOpts run time messages. If 'ENABLE_NLS' is defined at compile 4780time and 'no-xlate' has been not set to the value _anything_, then the 4781'_()' macro may be used to specify a translation function. If 4782undefined, it will default to 'gettext(3GNU)'. This define will also 4783enable a callback function that 'optionProcess' invokes at the beginning 4784of option processing. The AutoOpts 'libopts' library will always check 4785for this _compiled with NLS_ flag, so 'libopts' does not need to be 4786specially compiled. The strings returned by the translation function 4787will be 'strdup(3)-ed' and kept. They will not be re-translated, even 4788if the locale changes, but they will also not be dependent upon reused 4789or unmappable memory. 4790 4791 You should also ensure that the 'ATTRIBUTE_FORMAT_ARG()' gets 4792'#define'-ed to something useful. There is an autoconf macro named 4793'AG_COMPILE_FORMAT_ARG' in 'ag_macros.m4' that will set it appropriately 4794for you. If you do not do this, then translated formatting strings may 4795trigger GCC compiler warnings. 4796 4797 To internationalize option processing, you should first 4798internationalize your program. Then, the option processing strings can 4799be added to your translation text by processing the AutoOpts-generated 4800'my-opts.c' file and adding the distributed 'po/usage-txt.pot' file. 4801(Also by extracting the strings yourself from the 'usage-txt.h' file.) 4802When you call 'optionProcess', all of the user visible AutoOpts strings 4803will be passed through the localization procedure established with the 4804'_()' preprocessing macro. 4805 4806 All of this is _dis_-abled if you specify the global attribute 4807'no-xlate' to _anything_. 4808 4809 4810File: autogen.info, Node: Naming Conflicts, Next: All Attribute Names, Prev: i18n, Up: AutoOpts 4811 48127.17 Naming Conflicts 4813===================== 4814 4815AutoOpts generates a header file that contains many C preprocessing 4816macros and several external names. For the most part, they begin with 4817either 'opt_' or 'option', or else they end with '_opt'. If this 4818happens to conflict with other macros you are using, or if you are 4819compiling multiple option sets in the same compilation unit, the 4820conflicts can be avoided. You may specify an external name 'prefix' 4821(*note program attributes::) for all of the names generated for each set 4822of option definitions. 4823 4824 Among these macros, several take an option name as a macro argument. 4825Sometimes, this will inconveniently conflict. For example, if you 4826specify an option named, 'debug', the emitted code will presume that 4827'DEBUG' is not a preprocessing name. Or also, if you are building on a 4828Windows platform, you may find that MicroSoft has usurped a number of 4829user space names in its header files. Consequently, you will get a 4830preprocessing error if you use, for example, 'HAVE_OPT(DEBUG)' or 4831'HAVE_OPT(INTERNAL)' (*note HAVE_OPT::) in your code. You may trigger 4832an obvious warning for such conflicts by specifying the 4833'guard-option-names' attribute (*note program attributes::). That 4834emitted code will also '#undef'-ine the conflicting name. 4835 4836 4837File: autogen.info, Node: All Attribute Names, Next: Option Define Names, Prev: Naming Conflicts, Up: AutoOpts 4838 48397.18 All Attribute Names 4840======================== 4841 4842This is the list of all the option attributes used in the various option 4843processing templates. There are several flavors of attributes, and 4844these are not distinguished here. 4845 4846 * Valid, current attributes that you are encouraged to use. 4847 * Internally generated attributes that you cannot use at all. I need 4848 to prefix these with a distinguished prefix. e.g. 'ao-' 4849 * Valid attributes, but are deprecated. Alternates should be 4850 documented. 4851 4852 This list is derived by running many example option definitions 4853through the option generation and man page templates and noting which 4854attributes are actually used. There may be a few that are used but not 4855exercised in my testing. If so, I need to ferret those out and test 4856them, too. 4857 4858 addtogroup aliases allow_errors arg_default 4859 arg_name arg_optional arg_range arg_type 4860 argument author call_proc cmd_section 4861 comment_char concept config_header copyright 4862 date default deprecated descrip 4863 detail die_code disable disable_load 4864 disable_save doc doc_section doc_sub 4865 doc_sub_cmd documentation ds_format ds_text 4866 ds_type eaddr enable enabled 4867 environrc equivalence exit_desc exit_name 4868 explain export extract_code field 4869 file_fail_code flag flag_code flag_proc 4870 flags_cant flags_must full_usage gnu_usage 4871 guard_option_names handler_proc handler_type help_type 4872 help_value home_rc homerc ifdef 4873 ifndef immed_disable immediate include 4874 interleaved keyword lib_name library 4875 load_opts_value long_opts main_fini main_init 4876 main_type max min more_help_value 4877 must_set name no_command no_libopts 4878 no_misuse_usage no_preset no_xlate omit_texi 4879 omitted_usage open_file opt_state option_format 4880 option_info owner package prefix 4881 prefix_enum preserve_case prog_descrip prog_info_descrip 4882 prog_man_descrip prog_name prog_title rcfile 4883 reorder_args reset_value resettable save_opts_value 4884 scaled set_desc set_index settable 4885 short_usage stack_arg stdin_input sub_name 4886 sub_text sub_type test_main translators 4887 type unshar_file_code unstack_arg usage 4888 usage_message usage_opt usage_value value 4889 vendor_opt version version_proc version_value 4890 4891 4892File: autogen.info, Node: Option Define Names, Prev: All Attribute Names, Up: AutoOpts 4893 48947.19 Option Definition Name Index 4895================================= 4896 4897�[index�] 4898* Menu: 4899 4900* addtogroup: global option attributes. 4901 (line 18) 4902* allow-errors: presentation attributes. 4903 (line 9) 4904* arg-default: arg-default. (line 6) 4905* arg-name: per option attributes. 4906 (line 9) 4907* arg-optional: arg-optional. (line 6) 4908* arg-range: arg-type number. (line 21) 4909* arg-type: Option Arguments. (line 24) 4910* argument: program attributes. (line 22) 4911* author: information attributes. 4912 (line 25) 4913* before-guile-boot: main guile. (line 9) 4914* call-proc: Option Argument Handling. 4915 (line 62) 4916* cmd-section: global option attributes. 4917 (line 7) 4918* comment-char: main-for-each-opts. (line 25) 4919* config-header: program attributes. (line 33) 4920* config-header <1>: programming attributes. 4921 (line 10) 4922* copyright: information attributes. 4923 (line 10) 4924* date: information attributes. 4925 (line 13) 4926* default: opt-attr default option. 4927 (line 6) 4928* deprecated: Common Attributes. (line 28) 4929* descrip: Required Attributes. (line 34) 4930* detail: information attributes. 4931 (line 39) 4932* detail <1>: global option attributes. 4933 (line 12) 4934* die-code: programming attributes. 4935 (line 51) 4936* disable: Common Attributes. (line 33) 4937* disable-load: config attributes. (line 13) 4938* disable-save: config attributes. (line 13) 4939* doc: per option attributes. 4940 (line 15) 4941* doc-section: global option attributes. 4942 (line 42) 4943* doc-sub: global option attributes. 4944 (line 141) 4945* doc-sub-cmd: global option attributes. 4946 (line 173) 4947* documentation: lib and program. (line 16) 4948* documentation <1>: opt-attr documentation. 4949 (line 17) 4950* eaddr: information attributes. 4951 (line 27) 4952* enable: Common Attributes. (line 45) 4953* enabled: Common Attributes. (line 49) 4954* environrc: config attributes. (line 17) 4955* equivalence: opt-attr equivalence. 4956 (line 6) 4957* exit-desc: programming attributes. 4958 (line 16) 4959* exit-name: programming attributes. 4960 (line 16) 4961* explain: information attributes. 4962 (line 43) 4963* export: programming attributes. 4964 (line 66) 4965* extra-code: arg-keyword. (line 15) 4966* extract-code: Option Argument Handling. 4967 (line 51) 4968* file-exists: arg-type file name. (line 13) 4969* file-mode: arg-type file name. (line 29) 4970* flag-code: Option Argument Handling. 4971 (line 27) 4972* flag-proc: Option Argument Handling. 4973 (line 69) 4974* full-usage: usage attributes. (line 10) 4975* gnu-usage: usage attributes. (line 43) 4976* gnu-usage <1>: information attributes. 4977 (line 82) 4978* guard-option-names: programming attributes. 4979 (line 73) 4980* guile-main: main guile. (line 14) 4981* handler-frees: main-for-each-type. (line 66) 4982* handler-proc: main-for-each-proc. (line 6) 4983* handler-type: main-for-each-type. (line 6) 4984* help-value: automatic options. (line 18) 4985* homerc: config attributes. (line 26) 4986* ifdef: Common Attributes. (line 56) 4987* ifndef: Common Attributes. (line 56) 4988* immed-disable: Immediate Action. (line 31) 4989* immediate: Immediate Action. (line 24) 4990* include: programming attributes. 4991 (line 104) 4992* interleaved: main-for-each-opts. (line 10) 4993* keyword: arg-keyword. (line 6) 4994* lib-name: lib and program. (line 24) 4995* library: lib and program. (line 7) 4996* load-opts-value: automatic options. (line 15) 4997* long-opts: presentation attributes. 4998 (line 15) 4999* main: Generated main. (line 8) 5000* main-fini: main-for-each-opts. (line 21) 5001* main-init: main-for-each-opts. (line 17) 5002* main-type: Generated main. (line 12) 5003* max: Common Attributes. (line 14) 5004* min: Common Attributes. (line 19) 5005* more-help-value: automatic options. (line 15) 5006* must-set: Common Attributes. (line 24) 5007* MYHANDLER-code: main-for-each-code. (line 6) 5008* name: Required Attributes. (line 9) 5009* no-command: Common Attributes. (line 87) 5010* no-libopts: programming attributes. 5011 (line 108) 5012* no-misuse-usage: usage attributes. (line 57) 5013* no-preset: opt-attr no-preset. (line 6) 5014* no-xlate: presentation attributes. 5015 (line 35) 5016* omitted-usage: Common Attributes. (line 56) 5017* open-file: arg-type file name. (line 23) 5018* option-code: main main. (line 7) 5019* option-format: global option attributes. 5020 (line 28) 5021* option-info: global option attributes. 5022 (line 38) 5023* opts-ptr: information attributes. 5024 (line 61) 5025* owner: information attributes. 5026 (line 14) 5027* package: information attributes. 5028 (line 46) 5029* prefix: programming attributes. 5030 (line 115) 5031* prefix-enum: arg-type keyword. (line 38) 5032* preserve-case: information attributes. 5033 (line 52) 5034* prog-desc: information attributes. 5035 (line 61) 5036* prog-group: usage attributes. (line 65) 5037* prog-name: program attributes. (line 15) 5038* prog-title: program attributes. (line 19) 5039* rcfile: config attributes. (line 56) 5040* reorder-args: presentation attributes. 5041 (line 51) 5042* reorder-args <1>: information attributes. 5043 (line 91) 5044* reset-value: automatic options. (line 15) 5045* resettable: presentation attributes. 5046 (line 68) 5047* save-opts-value: automatic options. (line 19) 5048* scaled: arg-type number. (line 15) 5049* settable: opt-attr settable. (line 6) 5050* short-usage: usage attributes. (line 38) 5051* stack-arg: Option Argument Handling. 5052 (line 73) 5053* text: information attributes. 5054 (line 23) 5055* translators: opt-attr translators. 5056 (line 6) 5057* type: information attributes. 5058 (line 15) 5059* unstack-arg: Option Argument Handling. 5060 (line 86) 5061* usage: usage attributes. (line 73) 5062* usage <1>: information attributes. 5063 (line 74) 5064* usage-message: programming attributes. 5065 (line 41) 5066* usage-opt: Features. (line 56) 5067* usage-opt <1>: usage attributes. (line 51) 5068* usage-value: automatic options. (line 15) 5069* value: Common Attributes. (line 10) 5070* vendor-opt: config attributes. (line 61) 5071* version: usage attributes. (line 90) 5072* version-proc: automatic options. (line 23) 5073* version-value: automatic options. (line 15) 5074 5075 5076File: autogen.info, Node: Add-Ons, Next: Future, Prev: AutoOpts, Up: Top 5077 50788 Add-on packages for AutoGen 5079***************************** 5080 5081This chapter includes several programs that either work closely with 5082AutoGen (extracting definitions or providing special formatting 5083functions), or leverage off of AutoGen technology. There is also a 5084formatting library that helps make AutoGen possible. 5085 5086 AutoOpts ought to appear in this list as well, but since it is the 5087primary reason why many people would even look into AutoGen at all, I 5088decided to leave it in the list of chapters. 5089 5090* Menu: 5091 5092* AutoFSM:: Automated Finite State Machine. 5093* AutoXDR:: Combined RPC Marshalling. 5094* AutoEvents:: Automated Event Management. 5095* Bit Maps:: Bit Maps and Enumerations. 5096* columns Invocation:: Invoking columns. 5097* getdefs Invocation:: Invoking getdefs. 5098* xml2ag Invocation:: Invoking xml2ag. 5099* snprintfv:: The extensible format printing library. 5100 5101 5102File: autogen.info, Node: AutoFSM, Next: AutoXDR, Up: Add-Ons 5103 51048.1 Automated Finite State Machine 5105================================== 5106 5107The templates to generate a finite state machine in C or C++ is included 5108with AutoGen. The documentation is not. The documentation is in HTML 5109format for viewing (http://www.gnu.org/software/autogen/autofsm.html), 5110or you can download FSM (http://download.sourceforge.net/autogen/). 5111 5112 5113File: autogen.info, Node: AutoXDR, Next: AutoEvents, Prev: AutoFSM, Up: Add-Ons 5114 51158.2 Combined RPC Marshalling 5116============================ 5117 5118The templates and NFSv4 definitions are not included with AutoGen in any 5119way. The folks that designed NFSv4 noticed that much time and bandwidth 5120was wasted sending queries and responses when many of them could be 5121bundled. The protocol bundles the data, but there is no support for it 5122in rpcgen. That means you have to write your own code to do that. 5123Until now. Download this and you will have a large, complex example of 5124how to use 'AutoXDR' for generating the marshaling and unmarshaling of 5125combined RPC calls. There is a brief example on the web 5126(http://www.gnu.org/software/autogen/xdr/index.html), but you should 5127download AutoXDR (http://download.sourceforge.net/autogen/). 5128 5129 5130File: autogen.info, Node: AutoEvents, Next: Bit Maps, Prev: AutoXDR, Up: Add-Ons 5131 51328.3 Automated Event Management 5133============================== 5134 5135Large software development projects invariably have a need to manage the 5136distribution and display of state information and state changes. In 5137other words, they need to manage their software events. Generally, each 5138such project invents its own way of accomplishing this and then 5139struggles to get all of its components to play the same way. It is a 5140difficult process and not always completely successful. This project 5141helps with that. 5142 5143 AutoEvents completely separates the tasks of supplying the data 5144needed for a particular event from the methods used to manage the 5145distribution and display of that event. Consequently, the programmer 5146writing the code no longer has to worry about that part of the problem. 5147Likewise the persons responsible for designing the event management and 5148distribution no longer have to worry about getting programmers to write 5149conforming code. 5150 5151 This is a work in progress. See my web page 5152(http://www.gnu.org/software/autogen/autoevents.html) on the subject, if 5153you are interested. I have some useful things put together, but it is 5154not ready to call a product. 5155 5156 5157File: autogen.info, Node: Bit Maps, Next: columns Invocation, Prev: AutoEvents, Up: Add-Ons 5158 51598.4 Bit Maps and Enumerations 5160============================= 5161 5162AutoGen provides two templates for managing enumerations and bit maps 5163(flag words). They produce an enumeration of the enum or '#define's for 5164the bit maps, plus conversion functions for converting a string into one 5165of these values or converting one of these values into a human readable 5166string. Finally, for enumerations, you may specify one or more sets of 5167dispatching functions that will be selected by identifying a keyword 5168prefix of a string (*note the dispatch attribute in Strings to Enums and 5169Back: enum-code.). 5170 5171 There is a separate project that produces a GDB add-on that will add 5172these capabilities into GDB for bit masks. (GDB does just fine with 5173enumerations.) 5174 5175* Menu: 5176 5177* enums:: Enumerations 5178* enum-code:: Strings to Enums and Back 5179* masks:: Bit Maps and Masks 5180 5181 5182File: autogen.info, Node: enums, Next: enum-code, Up: Bit Maps 5183 51848.4.1 Enumerations 5185------------------ 5186 5187'str2enum.tpl' 5188 5189 Produce an enumeration for a list of input "cmd"s (names). 5190Optionally, produce functions to: 5191 5192 * convert a string to an enumeration 5193 * convert an enumeration value into a string 5194 * invoke a function based on the first token name found in a string 5195 5196 The header file produced will contain the enumeration and 5197declarations for the optional procedures. The code ('.c') file will 5198contain these optional procedures, but can be omitted if the 'no-code' 5199attribute is specified. 5200 5201 The following attributes are recognized with the 'str2enum' template: 5202 5203'cmd' 5204 You must provide a series of these attributes: they specify the 5205 list of names used in the enumeration. Specific values for the 5206 names may be specified by specifying a numeric index for these 5207 attributes. e.g. 'cmd[5] = mumble;' will cause 5208 FOO_CMD_MUMBLE = 5 5209 to be inserted into the enumeration. Do not specify a value of 5210 "invalid", unless you specify the 'invalid-name' attribute. (In 5211 that case, do not specify a 'cmd' value that matches the 5212 'invalid-name' value.) 5213 5214'prefix' 5215 This specifies the first segment of each enumeration name. If not 5216 specified, the first segment of the enumeration definition file 5217 name will be used. e.g. 'foo-bar.def' will default to a 'FOO' 5218 prefix. 5219 5220'type' 5221 Normally, there is a second constant segment following the prefix. 5222 If not specified, it will be 'CMD', so if both 'prefix' and 'type' 5223 were to default from 'foo-bar.def', you will have enumeration 5224 values prefixed with 'FOO_CMD_'. If specified as the empty string, 5225 there will be no "type" component to the name and the default 5226 constant prefix will thus be 'FOO_'. 5227 5228'base-name' 5229 This specifies the base name of the output files, enumeration type 5230 and the translation functions. The default is to use the 5231 'basename(3)' of the definition file. e.g. 'foo-bar.def' results 5232 in a 'base-name' of 'foo-bar'. 5233 5234'invalid-val' 5235 The default invalid value is zero. Sometimes, it is useful for 5236 zero to be valid. If so, you can specify ~0 or the empty string to 5237 be invalid. The empty string will cause the enumeration count 5238 (maximum value plus 1) to be the invalid value. 5239 5240'invalid-name' 5241 By default, the invalid value is emitted into the enumeration as 5242 'FOO_INVALID_CMD'. Specifying this attribute will replace 5243 'INVALID' with whatever you place in this attribute. 5244 5245'add-on-text' 5246 Additional text to insert into the code or header file. 5247 5248 'ao-file' 5249 Which file to insert the text into. There are four choices, 5250 only two of which are relevant for the 'str2enum' template: 5251 "enum-header", "enum-code", "mask-header" or "mask-code". 5252 5253 'ao-text' 5254 The text to insert. 5255 5256 5257File: autogen.info, Node: enum-code, Next: masks, Prev: enums, Up: Bit Maps 5258 52598.4.2 Strings to Enums and Back 5260------------------------------- 5261 5262A continuation of the attributes for the 'str2enum.tpl' template. 5263 5264'no-code' 5265 Do not emit any string to enumeration or enumeration to string code 5266 at all. If this is specified, the remainder of the attributes have 5267 no effect. 5268 5269'no-name' 5270 Do not emit the enumeration to name function. 5271 5272'no-case' 5273 When looking up a string, the case of the input string is ignored. 5274 5275'alias' 5276 A single punctuation character can be interpreted as a command. 5277 The first character of this attribute is the aliased character and 5278 the remainder the aliased-to command. e.g. "#comment" makes '#' 5279 an alias for the 'comment' command. "#comment" must still be 5280 listed in the 'cmd' attributes. 5281 5282'length' 5283 Specify how lengths are to be handled. Under the covers, 5284 'gperf(1)' is used to map a string to an enumeration value. The 5285 code it produces requires the string length to be passed in. You 5286 may pass in the length yourself, or the generated code may figure 5287 it out, or you may ask for that length to be returned back after 5288 being figured out. 5289 5290 You have four choices with the 'length' attribute: 5291 5292 * Do not specify it. You will need to provide the length. 5293 * Specify "provided". You will need to provide the length. 5294 * Specify "returned". You must pass a pointer to a size_t 5295 object. If the name is found, the length will be put there. 5296 * Specify an empty string. The generated code will compute the 5297 length and that computed length will not be returned. The 5298 length parameter may be omitted. If the input strings contain 5299 only enumeration names, then this would be sufficient. 5300 * Specifying anything else is undefined. 5301 5302'partial' 5303 Normally, a name must fully match to be found successfully. This 5304 attribute causes the generated code to look for partial matches if 5305 the full match 'gperf' function fails. Partial matches must be at 5306 least two characters long. 5307 5308'undef-str' 5309 by default, the display string for an undefined value is "* 5310 UNDEFINED *". Use this to change that. 5311 5312'equate' 5313 A series of punctuation characters considered equivalent. 5314 Typically, "-_" but sometimes (Tandem) "-_^". Do not use '#' in 5315 the list of characters. 5316 5317'dispatch' 5318 A lookup procedure will call a dispatch function for the procedure 5319 named after the keyword identified at the start of a string. Other 5320 than as specially noted below, for every named "cmd", must have a 5321 handling function, plus another function to handle errors, with 5322 "invalid" (or the 'invalid-name' value) as the 'cmd' name. 5323 Multiple 'dispatch' definitions will produce multiple dispatching 5324 functions, each with (potentially) unique argument lists and return 5325 types. 5326 5327 You may also use 'add-on-text' to "#define" one function to 5328 another, thus allowing one function to handle multiple keywords or 5329 commands. The 'd-nam' and 'd-ret' attributes are required. The 5330 'd-arg', 'd-omit' and 'd-only' attributes are optional: 5331 5332 'd-nam' 5333 This must be a printf format string with one formatting 5334 element: '%s'. The '%s' will be replaced by each 'cmd' name. 5335 The '%s' will be stripped and the result will be combined with 5336 the base name to construct the dispatch procedure name. 5337 5338 'd-ret' 5339 The return type of the dispatched function, even if "void". 5340 5341 'd-arg' 5342 If there are additional arguments that are to be passed 5343 through to the dispatched function, specify this as though it 5344 were part of the procedure header. (It will be glued into the 5345 dispatching function as is and sedded into what is needed for 5346 the dispatched function.) 5347 5348 'd-omit' 5349 Instead of providing handling functions for all of the 'cmd' 5350 names, the invalid function will be called for omitted command 5351 codes. 5352 5353 'd-only' 5354 You need only provide functions for the names listed by 5355 'd-only', plus the "invalid" name. All other command values 5356 will trigger calls to the invalid handling function. Note 5357 that the invalid call can distinguish from a command that 5358 could not be found by examining the value of its first ('id') 5359 argument. 5360 5361 The handler functions will have the command enumeration as its 5362 first first argument, a pointer to a constant string that will be 5363 the character after the parsed command (keyword) name, plus any 5364 'd-arg' arguments that follow that. 5365 5366 As an example, a file 'samp-chk.def' containing this: 5367 AutoGen Definitions str2enum; 5368 cmd = one, two; invalid-name = oops; 5369 dispatch = { d-nam = 'hdl_%s_cmd'; d-ret = void; }; 5370 will produce a header containing: 5371 typedef enum { 5372 SAMP_OOPS_CMD = 0, 5373 SAMP_CMD_ONE = 1, 5374 SAMP_CMD_TWO = 2, 5375 SAMP_COUNT_CMD 5376 } samp_chk_enum_t; 5377 5378 extern samp_chk_enum_t 5379 find_samp_chk_cmd(char const * str, size_t len); 5380 5381 typedef void(samp_chk_handler_t)( 5382 samp_chk_enum_t id, char const * str); 5383 5384 samp_chk_handler_t 5385 hdl_oops_cmd, hdl_one_cmd, hdl_two_cmd; 5386 5387 extern void 5388 disp_samp_chk(char * str, size_t len); 5389 5390 extern char const * 5391 samp_chk_name(samp_chk_enum_t id); 5392 5393 * 'find_samp_chk_cmd' will look up a 'len' byte 'str' and return 5394 the corresponding 'samp_chk_enum_t' value. That value is 5395 'SAMP_OOPS_CMD' if the string is not "one" or "two". 5396 * 'samp_chk_handler_t' is the type of the callback procedures. 5397 Three must be provided for the dispatching function to call: 5398 'hdl_oops_cmd', 'hdl_one_cmd' and 'hdl_two_cmd'. 5399 'hdl_oops_cmd' will receive calls when the string does not 5400 match. 5401 * 'disp_samp_chk' this function will call the handler function 5402 and return whatever the handler returns. In this case, it is 5403 void. 5404 * 'samp_chk_name' will return a string corresponding to the 5405 enumeration value argument. If the value is not valid, "* 5406 UNDEFINED *" (or the value of 'undef-str') is used. 5407 5408 5409File: autogen.info, Node: masks, Prev: enum-code, Up: Bit Maps 5410 54118.4.3 Bit Maps and Masks 5412------------------------ 5413 5414'str2mask.tpl' 5415 5416 This template leverages highly off of enumerations (*note enums::). 5417It will produce a header file with bit masks defined for each bit 5418specified with a 'cmd' attribute. 63 is the highest legal bit number 5419because this template has not been extended to cope with multiple word 5420masks. (Patches would be welcome.) 5421 5422 There are a few constraints on the names allowed: 5423 5424 * names are constrained to alphanumerics and the underscore 5425 * aliases are not allowed 5426 * dispatch procedures are not allowed 5427 5428 'no-code' and 'no-name' are honored. 'dispatch' is not. The lookup 5429function will examine each token in an input string, determine which bit 5430is specified and add it into a result. The names may be prefixed with a 5431hyphen (-) or tilde (~) to remove the bit(s) from the cumulative result. 5432If the string begins with a plus (+), hyphen or tilde, a "base value" 5433parameter is used for the starting mask, otherwise the conversion starts 5434with zero. 5435 5436 Beyond the enumeration attributes that are used (or ignored), the 5437'str2mask' template accepts a 'mask' attribute. It takes a few 5438"subattributes": 5439 5440'm-name' 5441 a special name for a sub-collection of the mask bits 5442 5443'm-bit' 5444 The name of each previously defined bit(s). If the desired 5445 previously defined value is a mask, that 'm-name' must be suffixed 5446 with "-mask". 5447 5448'm-invert' 5449 When all done collecting the bits, x-or the value with the mask of 5450 all the bits in the collection. 5451 5452A mask of all bits in the collection is always generated. 5453 5454 5455File: autogen.info, Node: columns Invocation, Next: getdefs Invocation, Prev: Bit Maps, Up: Add-Ons 5456 54578.5 Invoking columns 5458==================== 5459 5460This program was designed for the purpose of generating compact, 5461columnized tables. It will read a list of text items from standard in 5462or a specified input file and produce a columnized listing of all the 5463non-blank lines. Leading white space on each line is preserved, but 5464trailing white space is stripped. Methods of applying per-entry and 5465per-line embellishments are provided. See the formatting and separation 5466arguments below. 5467 5468 This program is used by AutoGen to help clean up and organize its 5469output. 5470 5471 See 'autogen/agen5/fsm.tpl' and the generated output 'pseudo-fsm.h'. 5472 5473 This function was not implemented as an expression function because 5474either it would have to be many expression functions, or a provision 5475would have to be added to provide options to expression functions. 5476Maybe not a bad idea, but it is not being implemented at the moment. 5477 5478 A side benefit is that you can use it outside of 'autogen' to 5479columnize input, a la the 'ls' command. 5480 5481 This section was generated by *AutoGen*, using the 'agtexi-cmd' 5482template and the option descriptions for the 'columns' program. This 5483software is released under the GNU General Public License, version 3 or 5484later. 5485 5486* Menu: 5487 5488* columns usage:: columns help/usage ('--help') 5489* columns dimensions:: dimensions options 5490* columns treatment:: treatment options 5491* columns ordering:: ordering options 5492* columns input-text:: input-text options 5493* columns config:: presetting/configuring columns 5494* columns exit status:: exit status 5495* columns See Also:: See Also 5496 5497 5498File: autogen.info, Node: columns usage, Next: columns dimensions, Up: columns Invocation 5499 55008.5.1 columns help/usage ('--help') 5501----------------------------------- 5502 5503This is the automatically generated usage text for columns. 5504 5505 The text printed is the same whether selected with the 'help' option 5506('--help') or the 'more-help' option ('--more-help'). 'more-help' will 5507print the usage text by passing it through a pager program. 'more-help' 5508is disabled on platforms without a working 'fork(2)' function. The 5509'PAGER' environment variable is used to select the program, defaulting 5510to 'more'. Both will exit with a status code of 0. 5511 5512 columns (GNU AutoGen) - Columnize Input Text - Ver. 1.2 5513 Usage: columns [ -<flag> [<val>] | --<name>[{=| }<val>] ]... 5514 5515 Specify the output dimensions: 5516 5517 Flg Arg Option-Name Description 5518 -W Num width Maximum Line Width 5519 - it must be in the range: 5520 16 to 4095 5521 -c Num columns Desired number of columns 5522 - it must be in the range: 5523 1 to 2048 5524 -w Num col-width Set width of each column 5525 - it must be in the range: 5526 1 to 2048 5527 Num tab-width tab width 5528 5529 Specify how to lay out the text: 5530 5531 Flg Arg Option-Name Description 5532 Num spread maximum spread added to column width 5533 - it must be in the range: 5534 1 to 1024 5535 no fill Fill lines with input 5536 - prohibits these options: 5537 spread 5538 col-width 5539 by-columns 5540 -I Str indent Line prefix or indentation 5541 Str first-indent First line prefix 5542 - requires the option 'indent' 5543 -f Str format Formatting string for each input 5544 -S Str separation Separation string - follows all but last 5545 Str line-separation string at end of all lines but last 5546 Str ending string at end of last line 5547 5548 Specify the ordering of the entries: 5549 5550 Flg Arg Option-Name Description 5551 no by-columns Print entries in column order 5552 -s opt sort Sort input text 5553 5554 Redirecting stdin to an alternate file: 5555 5556 Flg Arg Option-Name Description 5557 -i Str input Input file (if not stdin) 5558 5559 Version, usage and configuration options: 5560 5561 Flg Arg Option-Name Description 5562 -v opt version output version information and exit 5563 -? no help display extended usage information and exit 5564 -! no more-help extended usage information passed thru pager 5565 -> opt save-opts save the option state to a config file 5566 -< Str load-opts load options from a config file 5567 - disabled as '--no-load-opts' 5568 - may appear multiple times 5569 5570 Options are specified by doubled hyphens and their name or by a single 5571 hyphen and the flag character. 5572 5573 The following option preset mechanisms are supported: 5574 - reading file ./.columnsrc 5575 - reading file $HOME/.columnsrc 5576 - examining environment variables named COLUMNS_* 5577 5578 Please send bug reports to: <autogen-users@lists.sourceforge.net> 5579 5580 5581File: autogen.info, Node: columns dimensions, Next: columns treatment, Prev: columns usage, Up: columns Invocation 5582 55838.5.2 dimensions options 5584------------------------ 5585 5586Specify the output dimensions. 5587 5588width option (-W). 5589.................. 5590 5591This is the "maximum line width" option. This option takes a number 5592argument 'num'. This option specifies the full width of the output 5593line, including any start-of-line indentation. The output will fill 5594each line as completely as possible, unless the column width has been 5595explicitly specified. If the maximum width is less than the length of 5596the widest input, you will get a single column of output. 5597 5598columns option (-c). 5599.................... 5600 5601This is the "desired number of columns" option. This option takes a 5602number argument 'count'. Use this option to specify exactly how many 5603columns to produce. If that many columns will not fit within 5604LINE_WIDTH, then the count will be reduced to the number that fit. 5605 5606col-width option (-w). 5607...................... 5608 5609This is the "set width of each column" option. This option takes a 5610number argument 'num'. Use this option to specify exactly how many 5611characters are to be allocated for each column. If it is narrower than 5612the widest entry, it will be over-ridden with the required width. 5613 5614tab-width option. 5615................. 5616 5617This is the "tab width" option. This option takes a number argument 5618'num'. If an indentation string contains tabs, then this value is used 5619to compute the ending column of the prefix string. 5620 5621 5622File: autogen.info, Node: columns treatment, Next: columns ordering, Prev: columns dimensions, Up: columns Invocation 5623 56248.5.3 treatment options 5625----------------------- 5626 5627Specify how to lay out the text. 5628 5629spread option. 5630.............. 5631 5632This is the "maximum spread added to column width" option. This option 5633takes a number argument 'num'. Use this option to specify exactly how 5634many characters may be added to each column. It allows you to prevent 5635columns from becoming too far apart. Without this option, 'columns' 5636will attempt to widen columns to fill the full width. 5637 5638fill option. 5639............ 5640 5641This is the "fill lines with input" option. 5642 5643This option has some usage constraints. It: 5644 * must not appear in combination with any of the following options: 5645 spread, col_width, by_columns. 5646 5647 Instead of columnizing the input text, fill the output lines with the 5648input lines. Blank lines on input will cause a blank line in the 5649output, unless the output is sorted. With sorted output, blank lines 5650are ignored. 5651 5652indent option (-I). 5653................... 5654 5655This is the "line prefix or indentation" option. This option takes a 5656string argument 'l-pfx'. If a number, then this many spaces will be 5657inserted at the start of every line. Otherwise, it is a line prefix 5658that will be inserted at the start of every line. 5659 5660first-indent option. 5661.................... 5662 5663This is the "first line prefix" option. This option takes a string 5664argument 'l-pfx'. 5665 5666This option has some usage constraints. It: 5667 * must appear in combination with the following options: indent. 5668 5669 If a number, then this many spaces will be inserted at the start of 5670the first line. Otherwise, it is a line prefix that will be inserted at 5671the start of that line. If its length exceeds "indent", then it will be 5672emitted on a line by itself, suffixed by any line separation string. 5673For example: 5674 5675 $ columns --first='#define TABLE' -c 2 -I4 --line=' \' <<_EOF_ 5676 one 5677 two 5678 three 5679 four 5680 _EOF_ 5681 #define TABLE \ 5682 one two \ 5683 three four 5684 5685format option (-f). 5686................... 5687 5688This is the "formatting string for each input" option. This option 5689takes a string argument 'fmt-str'. If you need to reformat each input 5690text, the argument to this option is interpreted as an 'sprintf(3)' 5691format that is used to produce each output entry. 5692 5693separation option (-S). 5694....................... 5695 5696This is the "separation string - follows all but last" option. This 5697option takes a string argument 'sep-str'. Use this option if, for 5698example, you wish a comma to appear after each entry except the last. 5699 5700line-separation option. 5701....................... 5702 5703This is the "string at end of all lines but last" option. This option 5704takes a string argument 'sep-str'. Use this option if, for example, you 5705wish a backslash to appear at the end of every line, except the last. 5706 5707ending option. 5708.............. 5709 5710This is the "string at end of last line" option. This option takes a 5711string argument 'end-str'. This option puts the specified string at the 5712end of the output. 5713 5714 5715File: autogen.info, Node: columns ordering, Next: columns input-text, Prev: columns treatment, Up: columns Invocation 5716 57178.5.4 ordering options 5718---------------------- 5719 5720Specify the ordering of the entries. 5721 5722by-columns option. 5723.................. 5724 5725This is the "print entries in column order" option. Normally, the 5726entries are printed out in order by rows and then columns. This option 5727will cause the entries to be ordered within columns. The final column, 5728instead of the final row, may be shorter than the others. 5729 5730sort option (-s). 5731................. 5732 5733This is the "sort input text" option. This option takes an optional 5734string argument 'key-pat'. Causes the input text to be sorted. If an 5735argument is supplied, it is presumed to be a pattern and the sort is 5736based upon the matched text. If the pattern starts with or consists of 5737an asterisk ('*'), then the sort is case insensitive. 5738 5739 5740File: autogen.info, Node: columns input-text, Next: columns config, Prev: columns ordering, Up: columns Invocation 5741 57428.5.5 input-text options 5743------------------------ 5744 5745Redirecting stdin to an alternate file. 5746 5747input option (-i). 5748.................. 5749 5750This is the "input file (if not stdin)" option. This option takes a 5751string argument 'file'. This program normally runs as a 'filter', 5752reading from standard input, columnizing and writing to standard out. 5753This option redirects input to a file. 5754 5755 5756File: autogen.info, Node: columns config, Next: columns exit status, Prev: columns input-text, Up: columns Invocation 5757 57588.5.6 presetting/configuring columns 5759------------------------------------ 5760 5761Any option that is not marked as not presettable may be preset by 5762loading values from configuration ("rc" or "ini") files, and values from 5763environment variables named 'COLUMNS' and 'COLUMNS_<OPTION_NAME>'. 5764'<OPTION_NAME>' must be one of the options listed above in upper case 5765and segmented with underscores. The 'COLUMNS' variable will be 5766tokenized and parsed like the command line. The remaining variables are 5767tested for existence and their values are treated like option arguments. 5768 5769'libopts' will search in 2 places for configuration files: 5770 * $PWD 5771 * $HOME 5772 The environment variables 'PWD', and 'HOME' are expanded and replaced 5773when 'columns' runs. For any of these that are plain files, they are 5774simply processed. For any that are directories, then a file named 5775'.columnsrc' is searched for within that directory and processed. 5776 5777 Configuration files may be in a wide variety of formats. The basic 5778format is an option name followed by a value (argument) on the same 5779line. Values may be separated from the option name with a colon, equal 5780sign or simply white space. Values may be continued across multiple 5781lines by escaping the newline with a backslash. 5782 5783 Multiple programs may also share the same initialization file. 5784Common options are collected at the top, followed by program specific 5785segments. The segments are separated by lines like: 5786 [COLUMNS] 5787or by 5788 <?program columns> 5789Do not mix these styles within one configuration file. 5790 5791 Compound values and carefully constructed string values may also be 5792specified using XML syntax: 5793 <option-name> 5794 <sub-opt>...<...>...</sub-opt> 5795 </option-name> 5796yielding an 'option-name.sub-opt' string value of 5797 "...<...>..." 5798 'AutoOpts' does not track suboptions. You simply note that it is a 5799hierarchicly valued option. 'AutoOpts' does provide a means for 5800searching the associated name/value pair list (see: optionFindValue). 5801 5802 The command line options relating to configuration and/or usage help 5803are: 5804 5805version (-v) 5806............ 5807 5808Print the program version to standard out, optionally with licensing 5809information, then exit 0. The optional argument specifies how much 5810licensing detail to provide. The default is to print just the version. 5811The licensing information may be selected with an option argument. Only 5812the first letter of the argument is examined: 5813 5814'version' 5815 Only print the version. This is the default. 5816'copyright' 5817 Name the copyright usage licensing terms. 5818'verbose' 5819 Print the full copyright usage licensing terms. 5820 5821 5822File: autogen.info, Node: columns exit status, Next: columns See Also, Prev: columns config, Up: columns Invocation 5823 58248.5.7 columns exit status 5825------------------------- 5826 5827One of the following exit values will be returned: 5828'0 (EXIT_SUCCESS)' 5829 Successful program execution. 5830'1 (EXIT_FAILURE)' 5831 The operation failed or the command syntax was not valid. 5832'66 (EX_NOINPUT)' 5833 A specified configuration file could not be loaded. 5834'70 (EX_SOFTWARE)' 5835 libopts had an internal operational error. Please report it to 5836 autogen-users@lists.sourceforge.net. Thank you. 5837 5838 5839File: autogen.info, Node: columns See Also, Prev: columns exit status, Up: columns Invocation 5840 58418.5.8 columns See Also 5842---------------------- 5843 5844This program is documented more fully in the Columns section of the 5845Add-On chapter in the 'AutoGen' Info system documentation. 5846 5847 5848File: autogen.info, Node: getdefs Invocation, Next: xml2ag Invocation, Prev: columns Invocation, Up: Add-Ons 5849 58508.6 Invoking getdefs 5851==================== 5852 5853If no 'input' argument is provided or is set to simply "-", and if 5854'stdin' is not a 'tty', then the list of input files will be read from 5855'stdin'. This program extracts AutoGen definitions from a list of 5856source files. Definitions are delimited by '/*=<entry-type> 5857<entry-name>\n' and '=*/\n'. From that, this program creates a 5858definition of the following form: 5859 5860 #line nnn "source-file-name" 5861 entry_type = { 5862 name = entry_name; 5863 ... 5864 }; 5865 5866 1. The ellipsis '...' is filled in by text found between the two 5867 delimiters. Each line of text is stripped of anything before the 5868 first asterisk, then leading asterisks, then any leading or 5869 trailing white space. 5870 5871 2. If what is left starts with what looks like a name followed by a 5872 colon, then it is interpreted as a name followed by a value. 5873 5874 3. If the first character of the value is either a single or double 5875 quote, then you are responsible for quoting the text as it gets 5876 inserted into the output definitions. So, if you want whitespace 5877 at the beginnings of the lines of text, you must do something like 5878 this: 5879 5880 * mumble: 5881 * " this is some\n" 5882 * " indented text." 5883 5884 4. If the '<entry-name>' is followed by a comma, the word 'ifdef' (or 5885 'ifndef') and a name 'if_name', then the above entry will be under 5886 'ifdef' control. 5887 5888 /*=group entry_name, ifdef FOO 5889 * attr: attribute value 5890 =*/ 5891 5892 Will produce the following: 5893 5894 #ifdef FOO 5895 #line nnn "source-file-name" 5896 group = { 5897 name = entry_name; 5898 attr = 'attribute value'; 5899 }; 5900 #endif 5901 5902 5. If you use of the 'subblock' option, you can specify a nested 5903 value, *Note getdefs subblock::. That is, this text: 5904 5905 * arg: int, this, what-it-is 5906 5907 with the '--subblock=arg=type,name,doc' option would yield: 5908 5909 arg = { type = int; name = this; doc = what-it-is; }; 5910 5911 This section was generated by *AutoGen*, using the 'agtexi-cmd' 5912template and the option descriptions for the 'getdefs' program. This 5913software is released under the GNU General Public License, version 3 or 5914later. 5915 5916* Menu: 5917 5918* getdefs usage:: getdefs help/usage ('help') 5919* getdefs def-selection:: def-selection options 5920* getdefs enumerating:: enumerating options 5921* getdefs doc-insert:: doc-insert options 5922* getdefs input-files:: input-files options 5923* getdefs doc-output:: doc-output options 5924* getdefs config:: presetting/configuring getdefs 5925* getdefs exit status:: exit status 5926* getdefs See Also:: See Also 5927 5928 5929File: autogen.info, Node: getdefs usage, Next: getdefs def-selection, Up: getdefs Invocation 5930 59318.6.1 getdefs help/usage ('help') 5932--------------------------------- 5933 5934This is the automatically generated usage text for getdefs. 5935 5936 The text printed is the same whether selected with the 'help' option 5937('help') or the 'more-help' option ('more-help'). 'more-help' will 5938print the usage text by passing it through a pager program. 'more-help' 5939is disabled on platforms without a working 'fork(2)' function. The 5940'PAGER' environment variable is used to select the program, defaulting 5941to 'more'. Both will exit with a status code of 0. 5942 5943 getdefs error: invalid option descriptor for version 5944 getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5 5945 Usage: getdefs [ <option-name>[{=| }<val>] ]... 5946 5947 Specify which definitions are of interest and what to say about them: 5948 5949 Arg Option-Name Description 5950 Str defs-to-get Regexp to look for after the "/*=" 5951 Str subblock subblock definition names 5952 - may appear multiple times 5953 Str listattr attribute with list of values 5954 - may appear multiple times 5955 5956 specify how to number the definitions: 5957 5958 Arg Option-Name Description 5959 opt ordering Alphabetize or use named file 5960 - disabled as '--no-ordering' 5961 - enabled by default 5962 Num first-index The first index to apply to groups 5963 5964 Definition insertion options: 5965 5966 Arg Option-Name Description 5967 opt filelist Insert source file names into defs 5968 Str assign Global assignments 5969 - may appear multiple times 5970 Str common-assign Assignments common to all blocks 5971 - may appear multiple times 5972 Str copy File(s) to copy into definitions 5973 - may appear multiple times 5974 opt srcfile Insert source file name into each def 5975 opt linenum Insert source line number into each def 5976 5977 specify which files to search for markers: 5978 5979 Arg Option-Name Description 5980 Str input Input file to search for defs 5981 - may appear multiple times 5982 - default option for unnamed options 5983 5984 Definition output disposition options:: 5985 5986 Arg Option-Name Description 5987 Str output Output file to open 5988 - an alternate for 'autogen' 5989 opt autogen Invoke AutoGen with defs 5990 - disabled as '--no-autogen' 5991 - enabled by default 5992 Str template Template Name 5993 Str agarg AutoGen Argument 5994 - prohibits the option 'output' 5995 - may appear multiple times 5996 Str base-name Base name for output file(s) 5997 - prohibits the option 'output' 5998 5999 Version, usage and configuration options: 6000 6001 Arg Option-Name Description 6002 6003 6004File: autogen.info, Node: getdefs def-selection, Next: getdefs enumerating, Prev: getdefs usage, Up: getdefs Invocation 6005 60068.6.2 def-selection options 6007--------------------------- 6008 6009Specify which definitions are of interest and what to say about them. 6010 6011defs-to-get option. 6012................... 6013 6014This is the "regexp to look for after the "/*="" option. This option 6015takes a string argument 'reg-ex'. If you want definitions only from a 6016particular category, or even with names matching particular patterns, 6017then specify this regular expression for the text that must follow the 6018'/*='. 6019 6020subblock option. 6021................ 6022 6023This is the "subblock definition names" option. This option takes a 6024string argument 'sub-def'. 6025 6026This option has some usage constraints. It: 6027 * may appear an unlimited number of times. 6028 6029 This option is used to create shorthand entries for nested 6030definitions. For example, with: 6031using subblock thus 6032 '--subblock=arg=argname,type,null' 6033and defining an 'arg' thus 6034 'arg: this, char *' 6035will then expand to: 6036 'arg = { argname = this; type = "char *"; };' 6037 The "this, char *" string is separated at the commas, with the white 6038space removed. You may use characters other than commas by starting the 6039value string with a punctuation character other than a single or double 6040quote character. You may also omit intermediate values by placing the 6041commas next to each other with no intervening white space. For example, 6042"+mumble++yes+" will expand to: 6043'arg = { argname = mumble; null = "yes"; };'. 6044 6045listattr option. 6046................ 6047 6048This is the "attribute with list of values" option. This option takes a 6049string argument 'def'. 6050 6051This option has some usage constraints. It: 6052 * may appear an unlimited number of times. 6053 6054 This option is used to create shorthand entries for definitions that 6055generally appear several times. That is, they tend to be a list of 6056values. For example, with: 6057'listattr=foo' defined, the text: 6058'foo: this, is, a, multi-list' will then expand to: 6059'foo = 'this', 'is', 'a', 'multi-list';' 6060The texts are separated by the commas, with the white space removed. 6061You may use characters other than commas by starting the value string 6062with a punctuation character other than a single or double quote 6063character. 6064 6065 6066File: autogen.info, Node: getdefs enumerating, Next: getdefs doc-insert, Prev: getdefs def-selection, Up: getdefs Invocation 6067 60688.6.3 enumerating options 6069------------------------- 6070 6071specify how to number the definitions. 6072 6073ordering option. 6074................ 6075 6076This is the "alphabetize or use named file" option. This option takes 6077an optional string argument 'file-name'. 6078 6079This option has some usage constraints. It: 6080 * can be disabled with -no-ordering. 6081 * It is enabled by default. 6082 6083 By default, ordering is alphabetical by the entry name. Use, 6084'no-ordering' if order is unimportant. Use 'ordering' with no argument 6085to order without case sensitivity. Use 'ordering=<file-name>' if 6086chronological order is important. getdefs will maintain the text 6087content of 'file-name'. 'file-name' need not exist. 6088 6089first-index option. 6090................... 6091 6092This is the "the first index to apply to groups" option. This option 6093takes a number argument 'first-index'. By default, the first occurrence 6094of a named definition will have an index of zero. Sometimes, that needs 6095to be a reserved value. Provide this option to specify a different 6096starting point. 6097 6098 6099File: autogen.info, Node: getdefs doc-insert, Next: getdefs input-files, Prev: getdefs enumerating, Up: getdefs Invocation 6100 61018.6.4 doc-insert options 6102------------------------ 6103 6104Definition insertion options. 6105 6106filelist option. 6107................ 6108 6109This is the "insert source file names into defs" option. This option 6110takes an optional string argument 'file'. Inserts the name of each 6111input file into the output definitions. If no argument is supplied, the 6112format will be: 6113 infile = '%s'; 6114 If an argument is supplied, that string will be used for the entry 6115name instead of INFILE. 6116 6117assign option. 6118.............. 6119 6120This is the "global assignments" option. This option takes a string 6121argument 'ag-def'. 6122 6123This option has some usage constraints. It: 6124 * may appear an unlimited number of times. 6125 6126 The argument to each copy of this option will be inserted into the 6127output definitions, with only a semicolon attached. 6128 6129common-assign option. 6130..................... 6131 6132This is the "assignments common to all blocks" option. This option 6133takes a string argument 'ag-def'. 6134 6135This option has some usage constraints. It: 6136 * may appear an unlimited number of times. 6137 6138 The argument to each copy of this option will be inserted into each 6139output definition, with only a semicolon attached. 6140 6141copy option. 6142............ 6143 6144This is the "file(s) to copy into definitions" option. This option 6145takes a string argument 'file'. 6146 6147This option has some usage constraints. It: 6148 * may appear an unlimited number of times. 6149 6150 The content of each file named by these options will be inserted into 6151the output definitions. 6152 6153srcfile option. 6154............... 6155 6156This is the "insert source file name into each def" option. This option 6157takes an optional string argument 'file'. Inserts the name of the input 6158file where a definition was found into the output definition. If no 6159argument is supplied, the format will be: 6160 srcfile = '%s'; 6161 If an argument is supplied, that string will be used for the entry 6162name instead of SRCFILE. 6163 6164linenum option. 6165............... 6166 6167This is the "insert source line number into each def" option. This 6168option takes an optional string argument 'def-name'. Inserts the line 6169number in the input file where a definition was found into the output 6170definition. If no argument is supplied, the format will be: 6171 linenum = '%s'; 6172 If an argument is supplied, that string will be used for the entry 6173name instead of LINENUM. 6174 6175 6176File: autogen.info, Node: getdefs input-files, Next: getdefs doc-output, Prev: getdefs doc-insert, Up: getdefs Invocation 6177 61788.6.5 input-files options 6179------------------------- 6180 6181specify which files to search for markers. 6182 6183input option. 6184............. 6185 6186This is the "input file to search for defs" option. This option takes a 6187string argument 'src-file'. 6188 6189This option has some usage constraints. It: 6190 * may appear an unlimited number of times. 6191 6192 All files that are to be searched for definitions must be named on 6193the command line or read from 'stdin'. If there is only one 'input' 6194option and it is the string, "-", then the input file list is read from 6195'stdin'. If a command line argument is not an option name and does not 6196contain an assignment operator ('='), then it defaults to being an input 6197file name. At least one input file must be specified. 6198 6199 6200File: autogen.info, Node: getdefs doc-output, Next: getdefs config, Prev: getdefs input-files, Up: getdefs Invocation 6201 62028.6.6 doc-output options 6203------------------------ 6204 6205Definition output disposition options:. 6206 6207output option. 6208.............. 6209 6210This is the "output file to open" option. This option takes a string 6211argument 'file'. 6212 6213This option has some usage constraints. It: 6214 * is a member of the autogen class of options. 6215 6216 If you are not sending the output to an AutoGen process, you may name 6217an output file instead. 6218 6219autogen option. 6220............... 6221 6222This is the "invoke autogen with defs" option. This option takes an 6223optional string argument 'ag-cmd'. 6224 6225This option has some usage constraints. It: 6226 * can be disabled with -no-autogen. 6227 * It is enabled by default. 6228 * is a member of the autogen class of options. 6229 6230 This is the default output mode. Specifying 'no-autogen' is 6231equivalent to 'output=-'. If you supply an argument to this option, 6232that program will be started as if it were AutoGen and its standard in 6233will be set to the output definitions of this program. 6234 6235template option. 6236................ 6237 6238This is the "template name" option. This option takes a string argument 6239'file'. Specifies the template name to be used for generating the final 6240output. 6241 6242agarg option. 6243............. 6244 6245This is the "autogen argument" option. This option takes a string 6246argument 'ag-opt'. 6247 6248This option has some usage constraints. It: 6249 * may appear an unlimited number of times. 6250 * must not appear in combination with any of the following options: 6251 output. 6252 6253 This is a pass-through argument. It allows you to specify any 6254arbitrary argument to be passed to AutoGen. 6255 6256base-name option. 6257................. 6258 6259This is the "base name for output file(s)" option. This option takes a 6260string argument 'name'. 6261 6262This option has some usage constraints. It: 6263 * must not appear in combination with any of the following options: 6264 output. 6265 6266 When output is going to AutoGen, a base name must either be supplied 6267or derived. If this option is not supplied, then it is taken from the 6268'template' option. If that is not provided either, then it is set to 6269the base name of the current directory. 6270 6271 6272File: autogen.info, Node: getdefs config, Next: getdefs exit status, Prev: getdefs doc-output, Up: getdefs Invocation 6273 62748.6.7 presetting/configuring getdefs 6275------------------------------------ 6276 6277Any option that is not marked as not presettable may be preset by 6278loading values from configuration ("rc" or "ini") files. 6279 6280'libopts' will search in '/dev/null' for configuration (option) data. 6281If this is a plain file, it is simply processed. If it is a directory, 6282then a file named '.getdefsrc' is searched for within that directory. 6283 6284 Configuration files may be in a wide variety of formats. The basic 6285format is an option name followed by a value (argument) on the same 6286line. Values may be separated from the option name with a colon, equal 6287sign or simply white space. Values may be continued across multiple 6288lines by escaping the newline with a backslash. 6289 6290 Multiple programs may also share the same initialization file. 6291Common options are collected at the top, followed by program specific 6292segments. The segments are separated by lines like: 6293 [GETDEFS] 6294or by 6295 <?program getdefs> 6296Do not mix these styles within one configuration file. 6297 6298 Compound values and carefully constructed string values may also be 6299specified using XML syntax: 6300 <option-name> 6301 <sub-opt>...<...>...</sub-opt> 6302 </option-name> 6303yielding an 'option-name.sub-opt' string value of 6304 "...<...>..." 6305 'AutoOpts' does not track suboptions. You simply note that it is a 6306hierarchicly valued option. 'AutoOpts' does provide a means for 6307searching the associated name/value pair list (see: optionFindValue). 6308 6309 The command line options relating to configuration and/or usage help 6310are: 6311 6312version 6313....... 6314 6315Print the program version to standard out, optionally with licensing 6316information, then exit 0. The optional argument specifies how much 6317licensing detail to provide. The default is to print just the version. 6318The licensing information may be selected with an option argument. Only 6319the first letter of the argument is examined: 6320 6321'version' 6322 Only print the version. This is the default. 6323'copyright' 6324 Name the copyright usage licensing terms. 6325'verbose' 6326 Print the full copyright usage licensing terms. 6327 6328 6329File: autogen.info, Node: getdefs exit status, Next: getdefs See Also, Prev: getdefs config, Up: getdefs Invocation 6330 63318.6.8 getdefs exit status 6332------------------------- 6333 6334One of the following exit values will be returned: 6335'0 (EXIT_SUCCESS)' 6336 Successful program execution. 6337'1 (EXIT_FAILURE)' 6338 The operation failed or the command syntax was not valid. 6339'2 (EXIT_INVALID_INPUT)' 6340 An input file was specified that is not a file 6341'3 (EXIT_NO_MEM)' 6342 Insufficient memory for operation 6343'66 (EX_NOINPUT)' 6344 A specified configuration file could not be loaded. 6345'70 (EX_SOFTWARE)' 6346 libopts had an internal operational error. Please report it to 6347 autogen-users@lists.sourceforge.net. Thank you. 6348 6349 6350File: autogen.info, Node: getdefs See Also, Prev: getdefs exit status, Up: getdefs Invocation 6351 63528.6.9 getdefs See Also 6353---------------------- 6354 6355This program is documented more fully in the Getdefs section of the 6356Add-On chapter in the 'AutoGen' Info system documentation. 6357 6358 6359File: autogen.info, Node: xml2ag Invocation, Next: snprintfv, Prev: getdefs Invocation, Up: Add-Ons 6360 63618.7 Invoking xml2ag 6362=================== 6363 6364This program will convert any arbitrary XML file into equivalent AutoGen 6365definitions, and invoke AutoGen. The template used will be derived from 6366either: 6367 * The *-override-tpl* command line option 6368 * A top level XML attribute named, "'template'" 6369One or the other *must* be provided, or the program will exit with a 6370failure message. 6371 6372 The _base-name_ for the output will similarly be either: 6373 * The *-base-name* command line option. 6374 * The base name of the '.xml' file. 6375 6376 The definitions derived from XML generally have an extra layer of 6377definition. Specifically, this XML input: 6378 <mumble attr="foo"> 6379 mumble-1 6380 <grumble> 6381 grumble, grumble, grumble. 6382 </grumble>mumble, mumble 6383 </mumble> 6384 Will get converted into this: 6385 mumble = { 6386 grumble = { 6387 text = 'grumble, grumble, grumble'; 6388 }; 6389 text = 'mumble-1'; 6390 text = 'mumble, mumble'; 6391 }; 6392 Please notice that some information is lost. AutoGen cannot tell 6393that "grumble" used to lie between the mumble texts. Also please note 6394that you cannot assign: 6395 grumble = 'grumble, grumble, grumble.'; 6396 because if another "grumble" has an attribute or multiple texts, it 6397becomes impossible to have the definitions be the same type (compound or 6398text values). 6399 6400 This section was generated by *AutoGen*, using the 'agtexi-cmd' 6401template and the option descriptions for the 'xml2ag' program. This 6402software is released under the GNU General Public License, version 3 or 6403later. 6404 6405* Menu: 6406 6407* xml2ag usage:: xml2ag help/usage ('--help') 6408* xml2ag the-xml2ag-option:: the-xml2ag-option options 6409* xml2ag autogen-options:: autogen-options options 6410* xml2ag exit status:: exit status 6411 6412 6413File: autogen.info, Node: xml2ag usage, Next: xml2ag the-xml2ag-option, Up: xml2ag Invocation 6414 64158.7.1 xml2ag help/usage ('--help') 6416---------------------------------- 6417 6418This is the automatically generated usage text for xml2ag. 6419 6420 The text printed is the same whether selected with the 'help' option 6421('--help') or the 'more-help' option ('--more-help'). 'more-help' will 6422print the usage text by passing it through a pager program. 'more-help' 6423is disabled on platforms without a working 'fork(2)' function. The 6424'PAGER' environment variable is used to select the program, defaulting 6425to 'more'. Both will exit with a status code of 0. 6426 6427 xml2ag (GNU AutoGen) - XML to AutoGen Definiton Converter - Ver. 5.18.16 6428 Usage: xml2ag [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ] 6429 6430 All other options are derived from autogen: 6431 6432 Flg Arg Option-Name Description 6433 -O Str output Output file in lieu of AutoGen processing 6434 6435 All other options: 6436 6437 Flg Arg Option-Name Description 6438 -L Str templ-dirs Search for templates in DIR 6439 - may appear multiple times 6440 -T Str override-tpl Use TPL-FILE for the template 6441 Str definitions Read definitions from FILE 6442 Str shell name or path name of shell to use 6443 -m no no-fmemopen Do not use in-mem streams 6444 Str equate characters considered equivalent 6445 -b Str base-name Specify NAME as the base name for output 6446 no source-time set mod times to latest source 6447 no writable Allow output files to be writable 6448 - disabled as '--not-writable' 6449 Num loop-limit Limit on increment loops 6450 - is scalable with a suffix: k/K/m/M/g/G/t/T 6451 - it must lie in one of the ranges: 6452 -1 exactly, or 6453 1 to 16777216 6454 -t Num timeout Limit server shell operations to SECONDS 6455 - it must be in the range: 6456 0 to 3600 6457 KWd trace tracing level of detail 6458 Str trace-out tracing output file or filter 6459 no show-defs Show the definition tree 6460 no used-defines Show the definitions used 6461 -C no core Leave a core dump on a failure exit 6462 -s Str skip-suffix Skip the file with this SUFFIX 6463 - prohibits the option 'select-suffix' 6464 - may appear multiple times 6465 -o Str select-suffix specify this output suffix 6466 - may appear multiple times 6467 -D Str define name to add to definition list 6468 - may appear multiple times 6469 -U Str undefine definition list removal pattern 6470 - an alternate for 'define' 6471 -M opt make-dep emit make dependency file 6472 - may appear multiple times 6473 6474 Version, usage and configuration options: 6475 6476 Flg Arg Option-Name Description 6477 -v opt version output version information and exit 6478 -? no help display extended usage information and exit 6479 -! no more-help extended usage information passed thru pager 6480 6481 Options are specified by doubled hyphens and their name or by a single 6482 hyphen and the flag character. 6483 This program will convert any arbitrary XML file into equivalent AutoGen 6484 definitions, and invoke AutoGen. 6485 6486 The valid "trace" option keywords are: 6487 nothing debug-message server-shell templates block-macros 6488 expressions everything 6489 or an integer from 0 through 6 6490 The template will be derived from either: * the ``--override-tpl'' command 6491 line option * a top level XML attribute named, "template" 6492 6493 The ``base-name'' for the output will similarly be either: * the 6494 ``--base-name'' command line option * the base name of the .xml file 6495 6496 Please send bug reports to: <autogen-users@lists.sourceforge.net> 6497 6498 6499File: autogen.info, Node: xml2ag the-xml2ag-option, Next: xml2ag autogen-options, Prev: xml2ag usage, Up: xml2ag Invocation 6500 65018.7.2 the-xml2ag-option options 6502------------------------------- 6503 6504All other options are derived from autogen. 6505 6506output option (-O). 6507................... 6508 6509This is the "output file in lieu of autogen processing" option. This 6510option takes a string argument 'file'. By default, the output is handed 6511to an AutoGen for processing. However, you may save the definitions to 6512a file instead. 6513 6514 6515File: autogen.info, Node: xml2ag autogen-options, Next: xml2ag exit status, Prev: xml2ag the-xml2ag-option, Up: xml2ag Invocation 6516 65178.7.3 autogen-options options 6518----------------------------- 6519 6520All other options. These options are mostly just passed throug to 6521'autogen'. The one exception is '--override-tpl' which replaces the 6522default template in the output definitions. It does not get passed 6523through on the command line. 6524 6525templ-dirs option (-L). 6526....................... 6527 6528This is the "search for templates in 'dir'" option. This option takes a 6529string argument 'DIR'. 6530 6531This option has some usage constraints. It: 6532 * may appear an unlimited number of times. 6533 6534 Pass-through AutoGen argument 6535 6536override-tpl option (-T). 6537......................... 6538 6539This is the "use 'tpl-file' for the template" option. This option takes 6540a string argument 'TPL-FILE'. Pass-through AutoGen argument 6541 6542definitions option. 6543................... 6544 6545This is the "read definitions from 'file'" option. This option takes a 6546string argument 'FILE'. Pass-through AutoGen argument 6547 6548shell option. 6549............. 6550 6551This is the "name or path name of shell to use" option. This option 6552takes a string argument 'shell'. Pass-through AutoGen argument 6553 6554no-fmemopen option (-m). 6555........................ 6556 6557This is the "do not use in-mem streams" option. Pass-through AutoGen 6558argument 6559 6560equate option. 6561.............. 6562 6563This is the "characters considered equivalent" option. This option 6564takes a string argument 'char-list'. Pass-through AutoGen argument 6565 6566base-name option (-b). 6567...................... 6568 6569This is the "specify 'name' as the base name for output" option. This 6570option takes a string argument 'NAME'. Pass-through AutoGen argument 6571 6572source-time option. 6573................... 6574 6575This is the "set mod times to latest source" option. Pass-through 6576AutoGen argument 6577 6578writable option. 6579................ 6580 6581This is the "allow output files to be writable" option. 6582 6583This option has some usage constraints. It: 6584 * can be disabled with -not-writable. 6585 6586 Pass-through AutoGen argument 6587 6588loop-limit option. 6589.................. 6590 6591This is the "limit on increment loops" option. This option takes a 6592number argument 'lim'. Pass-through AutoGen argument 6593 6594timeout option (-t). 6595.................... 6596 6597This is the "limit server shell operations to 'seconds'" option. This 6598option takes a number argument 'SECONDS'. Pass-through AutoGen argument 6599 6600trace option. 6601............. 6602 6603This is the "tracing level of detail" option. This option takes a 6604keyword argument 'level'. 6605 6606This option has some usage constraints. It: 6607 * This option takes a keyword as its argument. The argument sets an 6608 enumeration value that can be tested by comparing the option value 6609 macro (OPT_VALUE_TRACE). The available keywords are: 6610 nothing debug-message server-shell 6611 templates block-macros expressions 6612 everything 6613 6614 or their numeric equivalent. 6615 6616 Pass-through AutoGen argument 6617 6618trace-out option. 6619................. 6620 6621This is the "tracing output file or filter" option. This option takes a 6622string argument 'file'. Pass-through AutoGen argument 6623 6624show-defs option. 6625................. 6626 6627This is the "show the definition tree" option. Pass-through AutoGen 6628argument 6629 6630used-defines option. 6631.................... 6632 6633This is the "show the definitions used" option. Pass-through AutoGen 6634argument 6635 6636core option (-C). 6637................. 6638 6639This is the "leave a core dump on a failure exit" option. 6640 6641This option has some usage constraints. It: 6642 * must be compiled in by defining 'HAVE_SYS_RESOURCE_H' during the 6643 compilation. 6644 6645 Many systems default to a zero sized core limit. If the system has 6646the sys/resource.h header and if this option is supplied, then in the 6647failure exit path, autogen will attempt to set the soft core limit to 6648whatever the hard core limit is. If that does not work, then an 6649administrator must raise the hard core size limit. 6650 6651skip-suffix option (-s). 6652........................ 6653 6654This is the "skip the file with this 'suffix'" option. This option 6655takes a string argument 'SUFFIX'. 6656 6657This option has some usage constraints. It: 6658 * may appear an unlimited number of times. 6659 * must not appear in combination with any of the following options: 6660 select-suffix. 6661 6662 Pass-through AutoGen argument 6663 6664select-suffix option (-o). 6665.......................... 6666 6667This is the "specify this output suffix" option. This option takes a 6668string argument 'SUFFIX'. 6669 6670This option has some usage constraints. It: 6671 * may appear an unlimited number of times. 6672 6673 Pass-through AutoGen argument 6674 6675define option (-D). 6676................... 6677 6678This is the "name to add to definition list" option. This option takes 6679a string argument 'value'. 6680 6681This option has some usage constraints. It: 6682 * may appear an unlimited number of times. 6683 6684 Pass-through AutoGen argument 6685 6686undefine option (-U). 6687..................... 6688 6689This is the "definition list removal pattern" option. This option takes 6690a string argument 'name-pat'. 6691 6692This option has some usage constraints. It: 6693 * may appear an unlimited number of times. 6694 6695 Pass-through AutoGen argument 6696 6697make-dep option (-M). 6698..................... 6699 6700This is the "emit make dependency file" option. This option takes an 6701optional string argument 'type'. 6702 6703This option has some usage constraints. It: 6704 * may appear an unlimited number of times. 6705 6706 Pass-through AutoGen argument 6707 6708 6709File: autogen.info, Node: xml2ag exit status, Prev: xml2ag autogen-options, Up: xml2ag Invocation 6710 67118.7.4 xml2ag exit status 6712------------------------ 6713 6714One of the following exit values will be returned: 6715'0 (EXIT_SUCCESS)' 6716 Successful program execution. 6717'1 (EXIT_FAILURE)' 6718 The operation failed or the command syntax was not valid. 6719 6720 6721File: autogen.info, Node: snprintfv, Prev: xml2ag Invocation, Up: Add-Ons 6722 67238.8 Replacement for Stdio Formatting Library 6724============================================ 6725 6726Using the 'printf' formatting routines in a portable fashion has always 6727been a pain, and this package has been way more pain than anyone ever 6728imagined. Hopefully, with this release of snprintfv, the pain is now 6729over for all time. 6730 6731 The issues with portable usage are these: 6732 6733 1. Argument number specifiers are often either not implemented or are 6734 buggy. Even GNU libc, version 1 got it wrong. 6735 6736 2. ANSI/ISO "forgot" to provide a mechanism for computing argument 6737 lists for vararg procedures. 6738 6739 3. The argument array version of printf ('printfv()') is not generally 6740 available, does not work with the native printf, and does not have 6741 a working argument number specifier in the format specification. 6742 (Last I knew, anyway.) 6743 6744 4. You cannot fake varargs by calling 'vprintf()' with an array of 6745 arguments, because ANSI does not require such an implementation and 6746 some vendors play funny tricks because they are allowed to. 6747 6748 These four issues made it impossible for AutoGen to ship without its 6749own implementation of the 'printf' formatting routines. Since we were 6750forced to do this, we decided to make the formatting routines both 6751better and more complete :-). We addressed these issues and added the 6752following features to the common printf API: 6753 6754 5. The formatted output can be written to 6755 6756 * a string allocated by the formatting function ('asprintf()'). 6757 * a file descriptor instead of a file stream ('dprintf()'). 6758 * a user specified stream ('stream_printf()'). 6759 6760 6. The formatting functions can be augmented with your own functions. 6761 These functions are allowed to consume more than one character from 6762 the format, but must commence with a unique character. For 6763 example, 6764 6765 "%{struct stat}\n" 6766 6767 might be used with '{' registered to a procedure that would look up 6768 "struct stat" in a symbol table and do appropriate things, 6769 consuming the format string through the '}' character. 6770 6771 Gary V. Vaughan was generous enough to supply this implementation. 6772Many thanks!! 6773 6774 For further details, the reader is referred to the snprintfv 6775documentation. These functions are also available in the template 6776processing as 'sprintf' (*note SCM sprintf::), 'printf' (*note SCM 6777printf::), 'fprintf' (*note SCM fprintf::), and 'shellf' (*note SCM 6778shellf::). 6779 6780 6781File: autogen.info, Node: Future, Next: Copying This Manual, Prev: Add-Ons, Up: Top 6782 67839 Some ideas for the future. 6784**************************** 6785 6786Here are some things that might happen in the distant future. 6787 6788 * Fix up current tools that contain miserably complex perl, shell, 6789 sed, awk and m4 scripts to instead use this tool. 6790 6791 6792File: autogen.info, Node: Copying This Manual, Next: Concept Index, Prev: Future, Up: Top 6793 6794Appendix A Copying This Manual 6795****************************** 6796 6797You may copy this manual under the terms of the FDL (the GNU Free 6798Documentation License (http://gnu.org/licenses/fdl.texi)). 6799 6800 6801File: autogen.info, Node: Concept Index, Next: Function Index, Prev: Copying This Manual, Up: Top 6802 6803Concept Index 6804************* 6805 6806�[index�] 6807* Menu: 6808 6809* .: naming values. (line 23) 6810* .def file: Definitions File. (line 6) 6811* .tpl file: Template File. (line 6) 6812* Alternate Definition: Alternate Definition. 6813 (line 6) 6814* assert: Directives. (line 26) 6815* assert directive: Directives. (line 26) 6816* Augmenting AutoGen: Augmenting AutoGen. (line 6) 6817* AutoEvents: AutoEvents. (line 6) 6818* AutoFSM: AutoFSM. (line 6) 6819* autogen: autogen Invocation. (line 6) 6820* AutoGen Definition Extraction Tool: getdefs Invocation. (line 6) 6821* autogen help: autogen usage. (line 6) 6822* autogen-base-name: autogen out-handling. 6823 (line 11) 6824* autogen-core: autogen debug-tpl. (line 138) 6825* autogen-define: autogen processing. (line 46) 6826* autogen-definitions: autogen input-select. 6827 (line 40) 6828* autogen-equate: autogen input-select. 6829 (line 90) 6830* autogen-loop-limit: autogen debug-tpl. (line 13) 6831* autogen-make-dep: autogen dep-track. (line 11) 6832* autogen-no-abort: autogen autoopts-opts. 6833 (line 11) 6834* autogen-no-fmemopen: autogen input-select. 6835 (line 74) 6836* autogen-override-tpl: autogen input-select. 6837 (line 26) 6838* autogen-select-suffix: autogen processing. (line 31) 6839* autogen-shell: autogen input-select. 6840 (line 58) 6841* autogen-show-defs: autogen debug-tpl. (line 106) 6842* autogen-skip-suffix: autogen processing. (line 13) 6843* autogen-source-time: autogen out-handling. 6844 (line 33) 6845* autogen-templ-dirs: autogen input-select. 6846 (line 12) 6847* autogen-timeout: autogen debug-tpl. (line 23) 6848* autogen-trace: autogen debug-tpl. (line 40) 6849* autogen-trace-out: autogen debug-tpl. (line 95) 6850* autogen-undefine: autogen processing. (line 76) 6851* autogen-used-defines: autogen debug-tpl. (line 120) 6852* autogen-writable: autogen out-handling. 6853 (line 47) 6854* AutoInfo: AutoInfo. (line 6) 6855* AutoMan pages: AutoMan pages. (line 6) 6856* automatic options: automatic options. (line 6) 6857* autoopts: AutoOpts. (line 6) 6858* autoopts <1>: Caveats. (line 34) 6859* AutoOpts API: AutoOpts API. (line 6) 6860* autoopts directives: config directives. (line 6) 6861* AutoXDR: AutoXDR. (line 6) 6862* backtrack: naming values. (line 24) 6863* Columnize Input Text: columns Invocation. (line 6) 6864* columns: columns Invocation. (line 6) 6865* columns help: columns usage. (line 6) 6866* columns-by-columns: columns ordering. (line 11) 6867* columns-col-width: columns dimensions. (line 29) 6868* columns-columns: columns dimensions. (line 21) 6869* columns-ending: columns treatment. (line 89) 6870* columns-fill: columns treatment. (line 20) 6871* columns-first-indent: columns treatment. (line 42) 6872* columns-format: columns treatment. (line 67) 6873* columns-indent: columns treatment. (line 34) 6874* columns-input: columns input-text. (line 11) 6875* columns-line-separation: columns treatment. (line 82) 6876* columns-separation: columns treatment. (line 75) 6877* columns-sort: columns ordering. (line 19) 6878* columns-spread: columns treatment. (line 11) 6879* columns-tab-width: columns dimensions. (line 37) 6880* columns-width: columns dimensions. (line 11) 6881* comments: Comments. (line 6) 6882* Common Option Attributes: Common Attributes. (line 6) 6883* compound definitions: Definitions. (line 43) 6884* concat-string: concat-string. (line 6) 6885* conditional emit: IF. (line 6) 6886* conditional emit <1>: WHILE. (line 6) 6887* configuration file: opt-attr no-preset. (line 6) 6888* configuration file <1>: automatic options. (line 67) 6889* configuration file <2>: automatic options. (line 83) 6890* configuration file <3>: Option Processing Data. 6891 (line 40) 6892* Configuration File: config example. (line 6) 6893* Configuration File <1>: Config File Format. (line 6) 6894* configuration file <4>: shell options. (line 6) 6895* Configuration File example: config example. (line 6) 6896* configuring: configuring. (line 6) 6897* define: Directives. (line 41) 6898* define directive: Directives. (line 41) 6899* define macro: DEFINE. (line 6) 6900* Definition Index: Index Assignments. (line 6) 6901* definitions: Definitions. (line 6) 6902* definitions file: Definitions File. (line 6) 6903* design goals: Generalities. (line 11) 6904* directives: Directives. (line 6) 6905* diversion: output controls. (line 6) 6906* documentation attributes: documentation attributes. 6907 (line 6) 6908* Dynamic Definition Text: Dynamic Text. (line 6) 6909* elif: Directives. (line 49) 6910* elif directive: Directives. (line 49) 6911* else: Directives. (line 53) 6912* else directive: Directives. (line 53) 6913* endif: Directives. (line 58) 6914* endif directive: Directives. (line 58) 6915* endmac: Directives. (line 62) 6916* endmac directive: Directives. (line 62) 6917* endshell: Directives. (line 65) 6918* endshell directive: Directives. (line 65) 6919* environrc: environrc. (line 6) 6920* error: Directives. (line 68) 6921* error directive: Directives. (line 68) 6922* example, simple AutoGen: Example Usage. (line 6) 6923* example, simple AutoOpts: Quick Start. (line 6) 6924* expression syntax: expression syntax. (line 6) 6925* features: Features. (line 6) 6926* finite state machine: AutoFSM. (line 6) 6927* flags-cant: Option Conflict Attributes. 6928 (line 19) 6929* flags-must: Option Conflict Attributes. 6930 (line 15) 6931* fOptState: Option Processing Data. 6932 (line 28) 6933* for loop: FOR. (line 6) 6934* futures: Future. (line 6) 6935* getdefs: getdefs Invocation. (line 6) 6936* getdefs help: getdefs usage. (line 6) 6937* getdefs-agarg: getdefs doc-output. (line 46) 6938* getdefs-assign: getdefs doc-insert. (line 22) 6939* getdefs-autogen: getdefs doc-output. (line 23) 6940* getdefs-base-name: getdefs doc-output. (line 60) 6941* getdefs-common-assign: getdefs doc-insert. (line 34) 6942* getdefs-copy: getdefs doc-insert. (line 46) 6943* getdefs-defs-to-get: getdefs def-selection. 6944 (line 11) 6945* getdefs-filelist: getdefs doc-insert. (line 11) 6946* getdefs-first-index: getdefs enumerating. (line 27) 6947* getdefs-input: getdefs input-files. (line 11) 6948* getdefs-linenum: getdefs doc-insert. (line 69) 6949* getdefs-listattr: getdefs def-selection. 6950 (line 45) 6951* getdefs-ordering: getdefs enumerating. (line 11) 6952* getdefs-output: getdefs doc-output. (line 11) 6953* getdefs-srcfile: getdefs doc-insert. (line 58) 6954* getdefs-subblock: getdefs def-selection. 6955 (line 20) 6956* getdefs-template: getdefs doc-output. (line 39) 6957* getopt_long: getopt_long. (line 6) 6958* gnu: Caveats. (line 29) 6959* here-string: here-string. (line 6) 6960* ident: Directives. (line 72) 6961* ident directive: Directives. (line 72) 6962* identification: Identification. (line 6) 6963* if: Directives. (line 75) 6964* if directive: Directives. (line 75) 6965* if test: IF. (line 6) 6966* ifdef: Directives. (line 79) 6967* ifdef directive: Directives. (line 79) 6968* ifndef: Directives. (line 85) 6969* ifndef directive: Directives. (line 85) 6970* immediate action: Immediate Action. (line 6) 6971* include: Directives. (line 89) 6972* include directive: Directives. (line 89) 6973* information attributes: information attributes. 6974 (line 6) 6975* Installing: installing. (line 6) 6976* Internationalizing AutoOpts: i18n. (line 6) 6977* Internationalizing Options: Internationalizing Options. 6978 (line 6) 6979* Introduction: Introduction. (line 6) 6980* let: Directives. (line 94) 6981* let directive: Directives. (line 94) 6982* library attributes: library attributes. (line 6) 6983* Licensing: Licensing. (line 6) 6984* line: Directives. (line 97) 6985* line directive: Directives. (line 97) 6986* looping, for: FOR. (line 6) 6987* m4: Testimonial. (line 41) 6988* macdef: Directives. (line 104) 6989* macdef directive: Directives. (line 104) 6990* macro syntax: AGMacro syntax. (line 6) 6991* macro, pseudo: Template File. (line 10) 6992* main procedure: Generated main. (line 6) 6993* misuse-usage: Caveats. (line 45) 6994* named option mode: presentation attributes. 6995 (line 15) 6996* Naming Conflicts: Naming Conflicts. (line 6) 6997* naming values: naming values. (line 6) 6998* native macros: native macros. (line 6) 6999* no-misuse-usage: Caveats. (line 40) 7000* optActualIndex: Option Processing Data. 7001 (line 16) 7002* optActualValue: Option Processing Data. 7003 (line 17) 7004* optIndex: Option Processing Data. 7005 (line 11) 7006* option: Directives. (line 110) 7007* Option Argument Handling: Option Argument Handling. 7008 (line 6) 7009* Option Arguments: Option Arguments. (line 6) 7010* option attributes: option attributes. (line 6) 7011* Option Conflict Attributes: Option Conflict Attributes. 7012 (line 6) 7013* Option Definitions: Option Definitions. (line 6) 7014* option descriptor: option descriptor. (line 6) 7015* option directive: Directives. (line 110) 7016* Option Processing Data: Option Processing Data. 7017 (line 6) 7018* optOccCt: Option Processing Data. 7019 (line 22) 7020* optValue: Option Processing Data. 7021 (line 12) 7022* pragma: Directives. (line 125) 7023* pragma directive: Directives. (line 125) 7024* predefines: Predefines. (line 6) 7025* program attributes: program attributes. (line 6) 7026* pseudo macro: Template File. (line 10) 7027* pseudo macro <1>: pseudo macro. (line 6) 7028* pzLastArg: Option Processing Data. 7029 (line 80) 7030* pzProgName: Option Processing Data. 7031 (line 87) 7032* pzProgPath: Option Processing Data. 7033 (line 91) 7034* rcfile: loading rcfile. (line 6) 7035* rcfile <1>: config example. (line 6) 7036* Redirecting Output: output controls. (line 6) 7037* remote procedure call: AutoXDR. (line 6) 7038* Required Attributes: Required Attributes. (line 6) 7039* RPC: AutoXDR. (line 6) 7040* rpcgen: AutoXDR. (line 6) 7041* sample rcfile: sample rcfile. (line 6) 7042* shell: Directives. (line 128) 7043* shell directive: Directives. (line 128) 7044* shell options: Presetting Options. (line 6) 7045* shell options <1>: shell options. (line 6) 7046* shell-generated string: shell-generated. (line 6) 7047* Signal Names: signal names. (line 6) 7048* simple definitions: Definitions. (line 44) 7049* standard options: standard options. (line 6) 7050* string, double quote: double-quote-string. (line 6) 7051* string, shell output: shell-generated. (line 6) 7052* string, single quote: single-quote-string. (line 6) 7053* template file: Identification. (line 21) 7054* template file <1>: Template File. (line 6) 7055* The Automated Program Generator: autogen Invocation. (line 6) 7056* undef: Directives. (line 136) 7057* undef directive: Directives. (line 136) 7058* using AutoOpts: Using AutoOpts. (line 6) 7059* while test: WHILE. (line 6) 7060* XDR: AutoXDR. (line 6) 7061* XML to AutoGen Definiton Converter: xml2ag Invocation. (line 6) 7062* xml2ag: xml2ag Invocation. (line 6) 7063* xml2ag help: xml2ag usage. (line 6) 7064* xml2ag-base-name: xml2ag autogen-options. 7065 (line 55) 7066* xml2ag-core: xml2ag autogen-options. 7067 (line 125) 7068* xml2ag-define: xml2ag autogen-options. 7069 (line 164) 7070* xml2ag-definitions: xml2ag autogen-options. 7071 (line 31) 7072* xml2ag-equate: xml2ag autogen-options. 7073 (line 49) 7074* xml2ag-loop-limit: xml2ag autogen-options. 7075 (line 77) 7076* xml2ag-make-dep: xml2ag autogen-options. 7077 (line 186) 7078* xml2ag-no-fmemopen: xml2ag autogen-options. 7079 (line 43) 7080* xml2ag-output: xml2ag the-xml2ag-option. 7081 (line 11) 7082* xml2ag-override-tpl: xml2ag autogen-options. 7083 (line 25) 7084* xml2ag-select-suffix: xml2ag autogen-options. 7085 (line 153) 7086* xml2ag-shell: xml2ag autogen-options. 7087 (line 37) 7088* xml2ag-show-defs: xml2ag autogen-options. 7089 (line 113) 7090* xml2ag-skip-suffix: xml2ag autogen-options. 7091 (line 140) 7092* xml2ag-source-time: xml2ag autogen-options. 7093 (line 61) 7094* xml2ag-templ-dirs: xml2ag autogen-options. 7095 (line 14) 7096* xml2ag-timeout: xml2ag autogen-options. 7097 (line 83) 7098* xml2ag-trace: xml2ag autogen-options. 7099 (line 89) 7100* xml2ag-trace-out: xml2ag autogen-options. 7101 (line 107) 7102* xml2ag-undefine: xml2ag autogen-options. 7103 (line 175) 7104* xml2ag-used-defines: xml2ag autogen-options. 7105 (line 119) 7106* xml2ag-writable: xml2ag autogen-options. 7107 (line 67) 7108 7109 7110File: autogen.info, Node: Function Index, Prev: Concept Index, Up: Top 7111 7112Function Index 7113************** 7114 7115�[index�] 7116* Menu: 7117 7118* *=: SCM *=. (line 6) 7119* *=*: SCM *=*. (line 6) 7120* *==: SCM *==. (line 6) 7121* *==*: SCM *==*. (line 6) 7122* *~: SCM *~. (line 6) 7123* *~*: SCM *~*. (line 6) 7124* *~~: SCM *~~. (line 6) 7125* *~~*: SCM *~~*. (line 6) 7126* =: SCM =. (line 6) 7127* =*: SCM =*. (line 6) 7128* ==: SCM ==. (line 6) 7129* ==*: SCM ==*. (line 6) 7130* ~: SCM ~. (line 6) 7131* ~*: SCM ~*. (line 6) 7132* ~~: SCM ~~. (line 6) 7133* ~~*: SCM ~~*. (line 6) 7134* ag-fprintf: SCM ag-fprintf. (line 6) 7135* ag-function?: SCM ag-function?. (line 6) 7136* agpl: SCM agpl. (line 6) 7137* ao_string_tokenize: libopts-ao_string_tokenize. 7138 (line 6) 7139* autogen-version: SCM autogen-version. (line 6) 7140* base-name: SCM base-name. (line 6) 7141* BREAK: BREAK. (line 6) 7142* bsd: SCM bsd. (line 6) 7143* c-file-line-fmt: SCM c-file-line-fmt. (line 6) 7144* c-string: SCM c-string. (line 6) 7145* CASE: CASE. (line 6) 7146* chdir: SCM chdir. (line 6) 7147* CLEAR_OPT: CLEAR_OPT. (line 6) 7148* COMMENT: COMMENT. (line 6) 7149* configFileLoad: libopts-configFileLoad. 7150 (line 6) 7151* CONTINUE: CONTINUE. (line 6) 7152* count: SCM count. (line 6) 7153* COUNT_OPT: COUNT_OPT. (line 6) 7154* DEBUG: DEBUG. (line 6) 7155* def-file: SCM def-file. (line 6) 7156* def-file-line: SCM def-file-line. (line 6) 7157* DEFINE: DEFINE. (line 6) 7158* DESC: DESC. (line 6) 7159* DISABLE_OPT_name: DISABLE_OPT_name. (line 6) 7160* dne: SCM dne. (line 6) 7161* ELIF: ELIF. (line 6) 7162* ELSE: ELSE. (line 6) 7163* emit: SCM emit. (line 6) 7164* emit-string-table: SCM emit-string-table. (line 6) 7165* ENABLED_OPT: ENABLED_OPT. (line 6) 7166* ENDDEF: ENDDEF. (line 6) 7167* ENDFOR: ENDFOR. (line 6) 7168* ENDIF: ENDIF. (line 6) 7169* ENDWHILE: ENDWHILE. (line 6) 7170* error: SCM error. (line 6) 7171* error-source-line: SCM error-source-line. (line 6) 7172* ERRSKIP_OPTERR: ERRSKIP_OPTERR. (line 6) 7173* ERRSTOP_OPTERR: ERRSTOP_OPTERR. (line 6) 7174* ESAC: ESAC. (line 6) 7175* exist?: SCM exist?. (line 6) 7176* EXPR: EXPR. (line 6) 7177* extract: SCM extract. (line 6) 7178* find-file: SCM find-file. (line 6) 7179* first-for?: SCM first-for?. (line 6) 7180* FOR: FOR. (line 6) 7181* for-by: SCM for-by. (line 6) 7182* for-from: SCM for-from. (line 6) 7183* for-index: SCM for-index. (line 6) 7184* for-sep: SCM for-sep. (line 6) 7185* for-to: SCM for-to. (line 6) 7186* format-arg-count: SCM format-arg-count. (line 6) 7187* found-for?: SCM found-for?. (line 6) 7188* fprintf: SCM fprintf. (line 6) 7189* get: SCM get. (line 6) 7190* get-c-name: SCM get-c-name. (line 6) 7191* get-down-name: SCM get-down-name. (line 6) 7192* get-up-name: SCM get-up-name. (line 6) 7193* gperf: SCM gperf. (line 6) 7194* gperf-code: SCM gperf-code. (line 6) 7195* gpl: SCM gpl. (line 6) 7196* HAVE_OPT: HAVE_OPT. (line 6) 7197* hide-email: SCM hide-email. (line 6) 7198* high-lim: SCM high-lim. (line 6) 7199* html-escape-encode: SCM html-escape-encode. 7200 (line 6) 7201* IF: IF. (line 6) 7202* in?: SCM in?. (line 6) 7203* INCLUDE: INCLUDE. (line 6) 7204* insert-file: SCM insert-file. (line 6) 7205* insert-suspended: SCM insert-suspended. (line 6) 7206* INVOKE: INVOKE. (line 6) 7207* ISSEL_OPT: ISSEL_OPT. (line 6) 7208* ISUNUSED_OPT: ISUNUSED_OPT. (line 6) 7209* join: SCM join. (line 6) 7210* kr-string: SCM kr-string. (line 6) 7211* last-for?: SCM last-for?. (line 6) 7212* len: SCM len. (line 6) 7213* lgpl: SCM lgpl. (line 6) 7214* license: SCM license. (line 6) 7215* license-description: SCM license-description. 7216 (line 6) 7217* license-full: SCM license-full. (line 6) 7218* license-info: SCM license-info. (line 6) 7219* license-name: SCM license-name. (line 6) 7220* low-lim: SCM low-lim. (line 6) 7221* make-gperf: SCM make-gperf. (line 6) 7222* make-header-guard: SCM make-header-guard. (line 6) 7223* make-tmp-dir: SCM make-tmp-dir. (line 6) 7224* makefile-script: SCM makefile-script. (line 6) 7225* match-value?: SCM match-value?. (line 6) 7226* max: SCM max. (line 6) 7227* max-file-time: SCM max-file-time. (line 6) 7228* min: SCM min. (line 6) 7229* mk-gettextable: SCM mk-gettextable. (line 6) 7230* optionFileLoad: libopts-optionFileLoad. 7231 (line 6) 7232* optionFindNextValue: libopts-optionFindNextValue. 7233 (line 6) 7234* optionFindValue: libopts-optionFindValue. 7235 (line 6) 7236* optionFree: libopts-optionFree. (line 6) 7237* optionGetValue: libopts-optionGetValue. 7238 (line 6) 7239* optionLoadLine: libopts-optionLoadLine. 7240 (line 6) 7241* optionMemberList: libopts-optionMemberList. 7242 (line 6) 7243* optionNextValue: libopts-optionNextValue. 7244 (line 6) 7245* optionOnlyUsage: libopts-optionOnlyUsage. 7246 (line 6) 7247* optionPrintVersion: libopts-optionPrintVersion. 7248 (line 6) 7249* optionPrintVersionAndReturn: libopts-optionPrintVersionAndReturn. 7250 (line 6) 7251* optionProcess: libopts-optionProcess. (line 6) 7252* optionRestore: libopts-optionRestore. (line 6) 7253* optionSaveFile: libopts-optionSaveFile. 7254 (line 6) 7255* optionSaveState: libopts-optionSaveState. 7256 (line 6) 7257* optionUnloadNested: libopts-optionUnloadNested. 7258 (line 6) 7259* optionVersion: libopts-optionVersion. (line 6) 7260* OPTION_CT: OPTION_CT. (line 6) 7261* OPT_ARG: OPT_ARG. (line 6) 7262* OPT_NO_XLAT_CFG_NAMES: OPT_NO_XLAT_CFG_NAMES. (line 6) 7263* OPT_NO_XLAT_OPT_NAMES: OPT_NO_XLAT_OPT_NAMES. (line 6) 7264* OPT_VALUE_name: OPT_VALUE_name. (line 6) 7265* OPT_XLAT_CFG_NAMES: OPT_XLAT_CFG_NAMES. (line 6) 7266* OPT_XLAT_OPT_NAMES: OPT_XLAT_OPT_NAMES. (line 6) 7267* out-delete: SCM out-delete. (line 6) 7268* out-depth: SCM out-depth. (line 6) 7269* out-emit-suspended: SCM out-emit-suspended. 7270 (line 6) 7271* out-line: SCM out-line. (line 6) 7272* out-move: SCM out-move. (line 6) 7273* out-name: SCM out-name. (line 6) 7274* out-pop: SCM out-pop. (line 6) 7275* out-push-add: SCM out-push-add. (line 6) 7276* out-push-new: SCM out-push-new. (line 6) 7277* out-resume: SCM out-resume. (line 6) 7278* out-suspend: SCM out-suspend. (line 6) 7279* out-switch: SCM out-switch. (line 6) 7280* output-file-next-line: SCM output-file-next-line. 7281 (line 6) 7282* prefix: SCM prefix. (line 6) 7283* printf: SCM printf. (line 6) 7284* raw-shell-str: SCM raw-shell-str. (line 6) 7285* RESTART_OPT: RESTART_OPT. (line 6) 7286* RETURN: RETURN. (line 6) 7287* SELECT: SELECT. (line 6) 7288* set-option: SCM set-option. (line 6) 7289* set-writable: SCM set-writable. (line 6) 7290* SET_OPT_name: SET_OPT_name. (line 6) 7291* shell: SCM shell. (line 6) 7292* shell-str: SCM shell-str. (line 6) 7293* shellf: SCM shellf. (line 6) 7294* sprintf: SCM sprintf. (line 6) 7295* stack: SCM stack. (line 6) 7296* stack-join: SCM stack-join. (line 6) 7297* STACKCT_OPT: STACKCT_OPT. (line 6) 7298* STACKLST_OPT: STACKLST_OPT. (line 6) 7299* START_OPT: START_OPT. (line 6) 7300* STATE_OPT: STATE_OPT. (line 6) 7301* strequate: libopts-strequate. (line 6) 7302* streqvcmp: libopts-streqvcmp. (line 6) 7303* streqvmap: libopts-streqvmap. (line 6) 7304* string->c-name!: SCM string->c-name!. (line 6) 7305* string->camelcase: SCM string->camelcase. (line 6) 7306* string-capitalize: SCM string-capitalize. (line 6) 7307* string-capitalize!: SCM string-capitalize!. 7308 (line 6) 7309* string-contains-eqv?: SCM *=*. (line 6) 7310* string-contains?: SCM *==*. (line 6) 7311* string-downcase: SCM string-downcase. (line 6) 7312* string-downcase!: SCM string-downcase!. (line 6) 7313* string-end-eqv-match?: SCM *~. (line 6) 7314* string-end-match?: SCM *~~. (line 6) 7315* string-ends-eqv?: SCM *=. (line 6) 7316* string-ends-with?: SCM *==. (line 6) 7317* string-equals?: SCM ==. (line 6) 7318* string-eqv-match?: SCM ~. (line 6) 7319* string-eqv?: SCM =. (line 6) 7320* string-has-eqv-match?: SCM *~*. (line 6) 7321* string-has-match?: SCM *~~*. (line 6) 7322* string-match?: SCM ~~. (line 6) 7323* string-start-eqv-match?: SCM ~*. (line 6) 7324* string-start-match?: SCM ~~*. (line 6) 7325* string-starts-eqv?: SCM =*. (line 6) 7326* string-starts-with?: SCM ==*. (line 6) 7327* string-substitute: SCM string-substitute. (line 6) 7328* string-table-add: SCM string-table-add. (line 6) 7329* string-table-add-ref: SCM string-table-add-ref. 7330 (line 6) 7331* string-table-new: SCM string-table-new. (line 6) 7332* string-table-size: SCM string-table-size. (line 6) 7333* string-tr: SCM string-tr. (line 6) 7334* string-tr!: SCM string-tr!. (line 6) 7335* string-upcase: SCM string-upcase. (line 6) 7336* string-upcase!: SCM string-upcase!. (line 6) 7337* strneqvcmp: libopts-strneqvcmp. (line 6) 7338* strtransform: libopts-strtransform. (line 6) 7339* sub-shell-str: SCM sub-shell-str. (line 6) 7340* suffix: SCM suffix. (line 6) 7341* sum: SCM sum. (line 6) 7342* teOptIndex: teOptIndex. (line 6) 7343* time-string->number: SCM time-string->number. 7344 (line 6) 7345* tpl-file: SCM tpl-file. (line 6) 7346* tpl-file-line: SCM tpl-file-line. (line 6) 7347* tpl-file-next-line: SCM tpl-file-next-line. 7348 (line 6) 7349* UNKNOWN: UNKNOWN. (line 6) 7350* USAGE: USAGE. (line 6) 7351* VALUE_OPT_name: VALUE_OPT_name. (line 6) 7352* VERSION: VERSION. (line 6) 7353* version-compare: SCM version-compare. (line 6) 7354* warn: SCM warn. (line 6) 7355* WHICH_IDX_name: WHICH_IDX_name. (line 6) 7356* WHICH_OPT_name: WHICH_OPT_name. (line 6) 7357* WHILE: WHILE. (line 6) 7358 7359