Re: Column widths in <table>

[Gavin Smith]

On Thu, Dec 30, 2021 at 10:23:04AM +0000, Gavin Smith wrote:
> However, you can imagine that you might have two similarly formatted,
> semantically linked tables with intervening text when aligning
> the columns of the two tables would be felicitous.

Here's another couple.  From agdoc.texi, part of manual for
GNU AutoGen version 5.18, updated August 2015.

(Generated using --html --no-split --force options.)

One problem is that the default formatting is to make the columns
very close to each other, with little padding.

(This was previously discussed here -

https://lists.gnu.org/archive/html/bug-texinfo/2014-11/msg00058.html)

- including an image of the lack of padding.)

So if we did stop outputting width attributes I think we should
supply some padding.  Otherwise the output could look a lot worse.

In the agdoc-widths.html output file, you can see that the table
in section 1.2 "configFileLoad" is much more widely spaced than
that in 1.3 "optionFileLoad".  I don't know why this is but would
guess that the percentage values in the width attributes are not
always relative to the same base - perhaps relative to the width
of the table, which can change depending on the contents.

One thought is that since Texinfo requires one of the two types of
column width specification (either prototypes or @columnfractions), with
automatically generated output the @columnfractions is the easiest to
provide.  The author didn't necessarily want the column widths to be
exactly the same in all of the tables.

Some experiments follow.

I checked the inconsistent columns with the following:

<table>
    <tr><td width="20%">aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa 
aaa aaa aaa aaa aaa aaa aaa </td><td width="20%">bbb bbb bbb bbb bbb bbb bbb 
bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb </td><td width="60%">ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc </td></tr>
</table>


<table>
    <tr><td width="20%">aaa</td><td width="20%">bbb</td><td 
width="60%">ccc</td></tr>
</table>

where the two columns won't be aligned.  So it aligning columns
of different tables may not be a good argument for obeying
@columnfractions in HTML.

(I actually find it hard to find proper documentation of what exactly
the width attribute in a <td> is supposed to do.)

I tried with <colgroup> but it made no difference:

<table>
    <colgroup><col width="20%"><col width="20%"><col width="60%"></colgroup>
        <tr><td>aaa</td><td>bbb</td><td>ccc</td>
        </tr>
</table>

<table>
    <colgroup><col width="20%"><col width="20%"><col width="60%"></colgroup>
        <tr><td>aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa 
aaa aaa aaa aaa aaa aaa </td><td>bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb 
bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb </td><td>ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc </td>
        </tr>
</table>

However, it does line up if you give width="100%" to the table:

<table width="100%">
    <colgroup><col width="20%"><col width="20%"><col width="60%"></colgroup>
        <tr><td>aaa</td><td>bbb</td><td>ccc</td>
        </tr>
</table>

<table width="100%">
    <colgroup><col width="20%"><col width="20%"><col width="60%"></colgroup>
        <tr><td>aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa aaa 
aaa aaa aaa aaa aaa aaa </td><td>bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb 
bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb bbb </td><td>ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc ccc 
ccc ccc ccc </td>
        </tr>
</table>

<colgroup> did not exist in HTML 3.2, though.

width="100%" also made a difference without <colgroup>:

<table width="100%">
        <tr><td width="20%">aaa</td><td width="20%">bbb</td><td 
width="60%">ccc</td>
        </tr>
</table>

I haven't checked this in terminal browsers like lynx.

tmp.texi
Description: TeXInfo document

 

1 libopts External Procedures

These are the routines that libopts users may call directly from their code. There are several other routines that can be called by code generated by the libopts option templates, but they are not to be called from any other user code. The options.h header is fairly clear about this, too.

This subsection was automatically generated by AutoGen using extracted information and the aginfo3.tpl template.

• ao_string_tokenize
• configFileLoad
• optionFileLoad
• optionFindNextValue
• optionFindValue
• optionFree
• optionGetValue
• optionLoadLine
• optionMemberList
• optionNextValue
• optionOnlyUsage
• optionPrintVersion
• optionPrintVersionAndReturn
• optionProcess
• optionRestore
• optionSaveFile
• optionSaveState
• optionUnloadNested
• optionVersion
• strequate
• streqvcmp
• streqvmap
• strneqvcmp
• strtransform

---

Next: configFileLoad, Up: libopts External Procedures  

1.1 ao_string_tokenize

tokenize an input string

Usage:

token_list_t * res = ao_string_tokenize( string );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	string	char const *	string to be tokenized
	returns	token_list_t *	pointer to a structure that lists each token

This function will convert one input string into a list of strings. The list of strings is derived by separating the input based on white space separation. However, if the input contains either single or double quote characters, then the text after that character up to a matching quote will become the string in the list.

The returned pointer should be deallocated with free(3C) when are done using the data. The data are placed in a single block of allocated memory. Do not deallocate individual token/strings.

The structure pointed to will contain at least these two fields:

‘tkn_ct’

The number of tokens found in the input string.

‘tok_list’

An array of tkn_ct + 1 pointers to substring tokens, with the last pointer set to NULL.

There are two types of quoted strings: single quoted (') and double quoted ("). Singly quoted strings are fairly raw in that escape characters (\\) are simply another character, except when preceding the following characters:

\\  double backslashes reduce to one
'   incorporates the single quote into the string
\n  suppresses both the backslash and newline character

Double quote strings are formed according to the rules of string constants in ANSI-C programs.

NULL is returned and errno will be set to indicate the problem:

• EINVAL - There was an unterminated quoted string.
• ENOENT - The input string was empty.
• ENOMEM - There is not enough memory.

---

Next: optionFileLoad, Previous: ao_string_tokenize, Up: libopts External Procedures  

1.2 configFileLoad

parse a configuration file

Usage:

const tOptionValue * res = configFileLoad( fname );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	fname	char const *	the file to load
	returns	const tOptionValue *	An allocated, compound value structure

This routine will load a named configuration file and parse the text as a hierarchically valued option. The option descriptor created from an option definition file is not used via this interface. The returned value is "named" with the input file name and is of type "OPARG_TYPE_HIERARCHY". It may be used in calls to optionGetValue(), optionNextValue() and optionUnloadNested().

If the file cannot be loaded or processed, NULL is returned and errno is set. It may be set by a call to either open(2) mmap(2) or other file system calls, or it may be:

• ENOENT - the file was not found.
• ENOMSG - the file was empty.
• EINVAL - the file contents are invalid – not properly formed.
• ENOMEM - not enough memory to allocate the needed structures.

---

Next: optionFindNextValue, Previous: configFileLoad, Up: libopts External Procedures  

1.3 optionFileLoad

Load the locatable config files, in order

Usage:

int res = optionFileLoad( opts, prog );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	prog	char const *	program name
	returns	int	0 -> SUCCESS, -1 -> FAILURE

This function looks in all the specified directories for a configuration file ("rc" file or "ini" file) and processes any found twice. The first time through, they are processed in reverse order (last file first). At that time, only "immediate action" configurables are processed. For example, if the last named file specifies not processing any more configuration files, then no more configuration files will be processed. Such an option in the first named directory will have no effect.

Once the immediate action configurables have been handled, then the directories are handled in normal, forward order. In that way, later config files can override the settings of earlier config files.

See the AutoOpts documentation for a thorough discussion of the config file format.

Configuration files not found or not decipherable are simply ignored.

Returns the value, "-1" if the program options descriptor is out of date or indecipherable. Otherwise, the value "0" will always be returned.

---

Next: optionFindValue, Previous: optionFileLoad, Up: libopts External Procedures  

1.4 optionFindNextValue

find a hierarcicaly valued option instance

Usage:

const tOptionValue * res = optionFindNextValue( odesc, pPrevVal, name, value );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	odesc	const tOptDesc *	an option with a nested arg type
	pPrevVal	const tOptionValue *	the last entry
	name	char const *	name of value to find
	value	char const *	the matching value
	returns	const tOptionValue *	a compound value structure

This routine will find the next entry in a nested value option or configurable. It will search through the list and return the next entry that matches the criteria.

The returned result is NULL and errno is set:

• EINVAL - the pOptValue does not point to a valid hierarchical option value.
• ENOENT - no entry matched the given name.

---

Next: optionFree, Previous: optionFindNextValue, Up: libopts External Procedures  

1.5 optionFindValue

find a hierarcicaly valued option instance

Usage:

const tOptionValue * res = optionFindValue( odesc, name, val );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	odesc	const tOptDesc *	an option with a nested arg type
	name	char const *	name of value to find
	val	char const *	the matching value
	returns	const tOptionValue *	a compound value structure

This routine will find an entry in a nested value option or configurable. It will search through the list and return a matching entry.

The returned result is NULL and errno is set:

• EINVAL - the pOptValue does not point to a valid hierarchical option value.
• ENOENT - no entry matched the given name.

---

Next: optionGetValue, Previous: optionFindValue, Up: libopts External Procedures  

1.6 optionFree

free allocated option processing memory

Usage:

optionFree( pOpts );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOpts	tOptions *	program options descriptor

AutoOpts sometimes allocates memory and puts pointers to it in the option state structures. This routine deallocates all such memory.

As long as memory has not been corrupted, this routine is always successful.

---

Next: optionLoadLine, Previous: optionFree, Up: libopts External Procedures  

1.7 optionGetValue

get a specific value from a hierarcical list

Usage:

const tOptionValue * res = optionGetValue( pOptValue, valueName );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOptValue	const tOptionValue *	a hierarchcal value
	valueName	char const *	name of value to get
	returns	const tOptionValue *	a compound value structure

This routine will find an entry in a nested value option or configurable. If "valueName" is NULL, then the first entry is returned. Otherwise, the first entry with a name that exactly matches the argument will be returned. If there is no matching value, NULL is returned and errno is set to ENOENT. If the provided option value is not a hierarchical value, NULL is also returned and errno is set to EINVAL.

The returned result is NULL and errno is set:

• EINVAL - the pOptValue does not point to a valid hierarchical option value.
• ENOENT - no entry matched the given name.

---

Next: optionMemberList, Previous: optionGetValue, Up: libopts External Procedures  

1.8 optionLoadLine

process a string for an option name and value

Usage:

optionLoadLine( opts, line );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	line	char const *	NUL-terminated text

This is a client program callable routine for setting options from, for example, the contents of a file that they read in. Only one option may appear in the text. It will be treated as a normal (non-preset) option.

When passed a pointer to the option struct and a string, it will find the option named by the first token on the string and set the option argument to the remainder of the string. The caller must NUL terminate the string. The caller need not skip over any introductory hyphens. Any embedded new lines will be included in the option argument. If the input looks like one or more quoted strings, then the input will be "cooked". The "cooking" is identical to the string formation used in AutoGen definition files (see ‘basic _expression_’), except that you may not use backquotes.

Invalid options are silently ignored. Invalid option arguments will cause a warning to print, but the function should return.

---

Next: optionNextValue, Previous: optionLoadLine, Up: libopts External Procedures  

1.9 optionMemberList

Get the list of members of a bit mask set

Usage:

char * res = optionMemberList( od );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	od	tOptDesc *	the set membership option description
	returns	char *	the names of the set bits

This converts the OPT_VALUE_name mask value to a allocated string. It is the caller’s responsibility to free the string.

---

Next: optionOnlyUsage, Previous: optionMemberList, Up: libopts External Procedures  

1.10 optionNextValue

get the next value from a hierarchical list

Usage:

const tOptionValue * res = optionNextValue( pOptValue, pOldValue );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOptValue	const tOptionValue *	a hierarchcal list value
	pOldValue	const tOptionValue *	a value from this list
	returns	const tOptionValue *	a compound value structure

This routine will return the next entry after the entry passed in. At the end of the list, NULL will be returned. If the entry is not found on the list, NULL will be returned and "errno" will be set to EINVAL. The "pOldValue" must have been gotten from a prior call to this routine or to "opitonGetValue()".

The returned result is NULL and errno is set:

• EINVAL - the pOptValue does not point to a valid hierarchical option value or pOldValue does not point to a member of that option value.
• ENOENT - the supplied pOldValue pointed to the last entry.

---

Next: optionPrintVersion, Previous: optionNextValue, Up: libopts External Procedures  

1.11 optionOnlyUsage

Print usage text for just the options

Usage:

optionOnlyUsage( pOpts, ex_code );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOpts	tOptions *	program options descriptor
	ex_code	int	exit code for calling exit(3)

This routine will print only the usage for each option. This function may be used when the emitted usage must incorporate information not available to AutoOpts.

---

Next: optionPrintVersionAndReturn, Previous: optionOnlyUsage, Up: libopts External Procedures  

1.12 optionPrintVersion

Print the program version

Usage:

optionPrintVersion( opts, od );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	od	tOptDesc *	the descriptor for this arg

This routine will print the version to stdout.

---

Next: optionProcess, Previous: optionPrintVersion, Up: libopts External Procedures  

1.13 optionPrintVersionAndReturn

Print the program version

Usage:

optionPrintVersionAndReturn( opts, od );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	od	tOptDesc *	the descriptor for this arg

This routine will print the version to stdout and return instead of exiting. Please see the source for the print_ver funtion for details on selecting how verbose to be after this function returns.

---

Next: optionRestore, Previous: optionPrintVersionAndReturn, Up: libopts External Procedures  

1.14 optionProcess

this is the main option processing routine

Usage:

int res = optionProcess( opts, a_ct, a_v );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	a_ct	int	program arg count
	a_v	char **	program arg vector
	returns	int	the count of the arguments processed

This is the main entry point for processing options. It is intended that this procedure be called once at the beginning of the execution of a program. Depending on options selected earlier, it is sometimes necessary to stop and restart option processing, or to select completely different sets of options. This can be done easily, but you generally do not want to do this.

The number of arguments processed always includes the program name. If one of the arguments is "–", then it is counted and the processing stops. If an error was encountered and errors are to be tolerated, then the returned value is the index of the argument causing the error. A hyphen by itself ("-") will also cause processing to stop and will not be counted among the processed arguments. A hyphen by itself is treated as an operand. Encountering an operand stops option processing.

Errors will cause diagnostics to be printed. exit(3) may or may not be called. It depends upon whether or not the options were generated with the "allow-errors" attribute, or if the ERRSKIP_OPTERR or ERRSTOP_OPTERR macros were invoked.

---

Next: optionSaveFile, Previous: optionProcess, Up: libopts External Procedures  

1.15 optionRestore

restore option state from memory copy

Usage:

optionRestore( pOpts );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOpts	tOptions *	program options descriptor

Copy back the option state from saved memory. The allocated memory is left intact, so this routine can be called repeatedly without having to call optionSaveState again. If you are restoring a state that was saved before the first call to optionProcess(3AO), then you may change the contents of the argc/argv parameters to optionProcess.

If you have not called optionSaveState before, a diagnostic is printed to stderr and exit is called.

---

Next: optionSaveState, Previous: optionRestore, Up: libopts External Procedures  

1.16 optionSaveFile

saves the option state to a file

Usage:

optionSaveFile( opts );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor

This routine will save the state of option processing to a file. The name of that file can be specified with the argument to the --save-opts option, or by appending the rcfile attribute to the last homerc attribute. If no rcfile attribute was specified, it will default to .programnamerc. If you wish to specify another file, you should invoke the SET_OPT_SAVE_OPTS(filename) macro.

The recommend usage is as follows:

optionProcess(&progOptions, argc, argv);
if (i_want_a_non_standard_place_for_this)
SET_OPT_SAVE_OPTS("myfilename");
optionSaveFile(&progOptions);

If no homerc file was specified, this routine will silently return and do nothing. If the output file cannot be created or updated, a message will be printed to stderr and the routine will return.

---

Next: optionUnloadNested, Previous: optionSaveFile, Up: libopts External Procedures  

1.17 optionSaveState

saves the option state to memory

Usage:

optionSaveState( pOpts );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOpts	tOptions *	program options descriptor

This routine will allocate enough memory to save the current option processing state. If this routine has been called before, that memory will be reused. You may only save one copy of the option state. This routine may be called before optionProcess(3AO). If you do call it before the first call to optionProcess, then you may also change the contents of argc/argv after you call optionRestore(3AO)

In fact, more strongly put: it is safest to only use this function before having processed any options. In particular, the saving and restoring of stacked string arguments and hierarchical values is disabled. The values are not saved.

If it fails to allocate the memory, it will print a message to stderr and exit. Otherwise, it will always succeed.

---

Next: optionVersion, Previous: optionSaveState, Up: libopts External Procedures  

1.18 optionUnloadNested

Deallocate the memory for a nested value

Usage:

optionUnloadNested( pOptVal );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOptVal	tOptionValue const *	the hierarchical value

A nested value needs to be deallocated. The pointer passed in should have been gotten from a call to configFileLoad() (See see configFileLoad).

---

Next: strequate, Previous: optionUnloadNested, Up: libopts External Procedures  

1.19 optionVersion

return the compiled AutoOpts version number

Usage:

char const * res = optionVersion();

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	returns	char const *	the version string in constant memory

Returns the full version string compiled into the library. The returned string cannot be modified.

---

Next: streqvcmp, Previous: optionVersion, Up: libopts External Procedures  

1.20 strequate

map a list of characters to the same value

Usage:

strequate( ch_list );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	ch_list	char const *	characters to equivalence

Each character in the input string get mapped to the first character in the string. This function name is mapped to option_strequate so as to not conflict with the POSIX name space.

none.

---

Next: streqvmap, Previous: strequate, Up: libopts External Procedures  

1.21 streqvcmp

compare two strings with an equivalence mapping

Usage:

int res = streqvcmp( str1, str2 );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	str1	char const *	first string
	str2	char const *	second string
	returns	int	the difference between two differing characters

Using a character mapping, two strings are compared for "equivalence". Each input character is mapped to a comparison character and the mapped-to characters are compared for the two NUL terminated input strings. This function name is mapped to option_streqvcmp so as to not conflict with the POSIX name space.

none checked. Caller responsible for seg faults.

---

Next: strneqvcmp, Previous: streqvcmp, Up: libopts External Procedures  

1.22 streqvmap

Set the character mappings for the streqv functions

Usage:

streqvmap( from, to, ct );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	from	char	Input character
	to	char	Mapped-to character
	ct	int	compare length

Set the character mapping. If the count (ct) is set to zero, then the map is cleared by setting all entries in the map to their index value. Otherwise, the "From" character is mapped to the "To" character. If ct is greater than 1, then From and To are incremented and the process repeated until ct entries have been set. For example,

streqvmap('a', 'A', 26);

will alter the mapping so that all English lower case letters will map to upper case.

This function name is mapped to option_streqvmap so as to not conflict with the POSIX name space.

none.

---

Next: strtransform, Previous: streqvmap, Up: libopts External Procedures  

1.23 strneqvcmp

compare two strings with an equivalence mapping

Usage:

int res = strneqvcmp( str1, str2, ct );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	str1	char const *	first string
	str2	char const *	second string
	ct	int	compare length
	returns	int	the difference between two differing characters

Using a character mapping, two strings are compared for "equivalence". Each input character is mapped to a comparison character and the mapped-to characters are compared for the two NUL terminated input strings. The comparison is limited to ct bytes. This function name is mapped to option_strneqvcmp so as to not conflict with the POSIX name space.

none checked. Caller responsible for seg faults.

---

Previous: strneqvcmp, Up: libopts External Procedures  

1.24 strtransform

convert a string into its mapped-to value

Usage:

strtransform( dest, src );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	dest	char *	output string
	src	char const *	input string

Each character in the input string is mapped and the mapped-to character is put into the output. This function name is mapped to option_strtransform so as to not conflict with the POSIX name space.

The source and destination may be the same.

none.

bye

 

1 libopts External Procedures

These are the routines that libopts users may call directly from their code. There are several other routines that can be called by code generated by the libopts option templates, but they are not to be called from any other user code. The options.h header is fairly clear about this, too.

This subsection was automatically generated by AutoGen using extracted information and the aginfo3.tpl template.

• ao_string_tokenize
• configFileLoad
• optionFileLoad
• optionFindNextValue
• optionFindValue
• optionFree
• optionGetValue
• optionLoadLine
• optionMemberList
• optionNextValue
• optionOnlyUsage
• optionPrintVersion
• optionPrintVersionAndReturn
• optionProcess
• optionRestore
• optionSaveFile
• optionSaveState
• optionUnloadNested
• optionVersion
• strequate
• streqvcmp
• streqvmap
• strneqvcmp
• strtransform

---

Next: configFileLoad, Up: libopts External Procedures  

1.1 ao_string_tokenize

tokenize an input string

Usage:

token_list_t * res = ao_string_tokenize( string );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	string	char const *	string to be tokenized
	returns	token_list_t *	pointer to a structure that lists each token

This function will convert one input string into a list of strings. The list of strings is derived by separating the input based on white space separation. However, if the input contains either single or double quote characters, then the text after that character up to a matching quote will become the string in the list.

The returned pointer should be deallocated with free(3C) when are done using the data. The data are placed in a single block of allocated memory. Do not deallocate individual token/strings.

The structure pointed to will contain at least these two fields:

‘tkn_ct’

The number of tokens found in the input string.

‘tok_list’

An array of tkn_ct + 1 pointers to substring tokens, with the last pointer set to NULL.

There are two types of quoted strings: single quoted (') and double quoted ("). Singly quoted strings are fairly raw in that escape characters (\\) are simply another character, except when preceding the following characters:

\\  double backslashes reduce to one
'   incorporates the single quote into the string
\n  suppresses both the backslash and newline character

Double quote strings are formed according to the rules of string constants in ANSI-C programs.

NULL is returned and errno will be set to indicate the problem:

• EINVAL - There was an unterminated quoted string.
• ENOENT - The input string was empty.
• ENOMEM - There is not enough memory.

---

Next: optionFileLoad, Previous: ao_string_tokenize, Up: libopts External Procedures  

1.2 configFileLoad

parse a configuration file

Usage:

const tOptionValue * res = configFileLoad( fname );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	fname	char const *	the file to load
	returns	const tOptionValue *	An allocated, compound value structure

This routine will load a named configuration file and parse the text as a hierarchically valued option. The option descriptor created from an option definition file is not used via this interface. The returned value is "named" with the input file name and is of type "OPARG_TYPE_HIERARCHY". It may be used in calls to optionGetValue(), optionNextValue() and optionUnloadNested().

If the file cannot be loaded or processed, NULL is returned and errno is set. It may be set by a call to either open(2) mmap(2) or other file system calls, or it may be:

• ENOENT - the file was not found.
• ENOMSG - the file was empty.
• EINVAL - the file contents are invalid – not properly formed.
• ENOMEM - not enough memory to allocate the needed structures.

---

Next: optionFindNextValue, Previous: configFileLoad, Up: libopts External Procedures  

1.3 optionFileLoad

Load the locatable config files, in order

Usage:

int res = optionFileLoad( opts, prog );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	prog	char const *	program name
	returns	int	0 -> SUCCESS, -1 -> FAILURE

This function looks in all the specified directories for a configuration file ("rc" file or "ini" file) and processes any found twice. The first time through, they are processed in reverse order (last file first). At that time, only "immediate action" configurables are processed. For example, if the last named file specifies not processing any more configuration files, then no more configuration files will be processed. Such an option in the first named directory will have no effect.

Once the immediate action configurables have been handled, then the directories are handled in normal, forward order. In that way, later config files can override the settings of earlier config files.

See the AutoOpts documentation for a thorough discussion of the config file format.

Configuration files not found or not decipherable are simply ignored.

Returns the value, "-1" if the program options descriptor is out of date or indecipherable. Otherwise, the value "0" will always be returned.

---

Next: optionFindValue, Previous: optionFileLoad, Up: libopts External Procedures  

1.4 optionFindNextValue

find a hierarcicaly valued option instance

Usage:

const tOptionValue * res = optionFindNextValue( odesc, pPrevVal, name, value );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	odesc	const tOptDesc *	an option with a nested arg type
	pPrevVal	const tOptionValue *	the last entry
	name	char const *	name of value to find
	value	char const *	the matching value
	returns	const tOptionValue *	a compound value structure

This routine will find the next entry in a nested value option or configurable. It will search through the list and return the next entry that matches the criteria.

The returned result is NULL and errno is set:

• EINVAL - the pOptValue does not point to a valid hierarchical option value.
• ENOENT - no entry matched the given name.

---

Next: optionFree, Previous: optionFindNextValue, Up: libopts External Procedures  

1.5 optionFindValue

find a hierarcicaly valued option instance

Usage:

const tOptionValue * res = optionFindValue( odesc, name, val );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	odesc	const tOptDesc *	an option with a nested arg type
	name	char const *	name of value to find
	val	char const *	the matching value
	returns	const tOptionValue *	a compound value structure

This routine will find an entry in a nested value option or configurable. It will search through the list and return a matching entry.

The returned result is NULL and errno is set:

• EINVAL - the pOptValue does not point to a valid hierarchical option value.
• ENOENT - no entry matched the given name.

---

Next: optionGetValue, Previous: optionFindValue, Up: libopts External Procedures  

1.6 optionFree

free allocated option processing memory

Usage:

optionFree( pOpts );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOpts	tOptions *	program options descriptor

AutoOpts sometimes allocates memory and puts pointers to it in the option state structures. This routine deallocates all such memory.

As long as memory has not been corrupted, this routine is always successful.

---

Next: optionLoadLine, Previous: optionFree, Up: libopts External Procedures  

1.7 optionGetValue

get a specific value from a hierarcical list

Usage:

const tOptionValue * res = optionGetValue( pOptValue, valueName );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOptValue	const tOptionValue *	a hierarchcal value
	valueName	char const *	name of value to get
	returns	const tOptionValue *	a compound value structure

This routine will find an entry in a nested value option or configurable. If "valueName" is NULL, then the first entry is returned. Otherwise, the first entry with a name that exactly matches the argument will be returned. If there is no matching value, NULL is returned and errno is set to ENOENT. If the provided option value is not a hierarchical value, NULL is also returned and errno is set to EINVAL.

The returned result is NULL and errno is set:

• EINVAL - the pOptValue does not point to a valid hierarchical option value.
• ENOENT - no entry matched the given name.

---

Next: optionMemberList, Previous: optionGetValue, Up: libopts External Procedures  

1.8 optionLoadLine

process a string for an option name and value

Usage:

optionLoadLine( opts, line );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	line	char const *	NUL-terminated text

This is a client program callable routine for setting options from, for example, the contents of a file that they read in. Only one option may appear in the text. It will be treated as a normal (non-preset) option.

When passed a pointer to the option struct and a string, it will find the option named by the first token on the string and set the option argument to the remainder of the string. The caller must NUL terminate the string. The caller need not skip over any introductory hyphens. Any embedded new lines will be included in the option argument. If the input looks like one or more quoted strings, then the input will be "cooked". The "cooking" is identical to the string formation used in AutoGen definition files (see ‘basic _expression_’), except that you may not use backquotes.

Invalid options are silently ignored. Invalid option arguments will cause a warning to print, but the function should return.

---

Next: optionNextValue, Previous: optionLoadLine, Up: libopts External Procedures  

1.9 optionMemberList

Get the list of members of a bit mask set

Usage:

char * res = optionMemberList( od );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	od	tOptDesc *	the set membership option description
	returns	char *	the names of the set bits

This converts the OPT_VALUE_name mask value to a allocated string. It is the caller’s responsibility to free the string.

---

Next: optionOnlyUsage, Previous: optionMemberList, Up: libopts External Procedures  

1.10 optionNextValue

get the next value from a hierarchical list

Usage:

const tOptionValue * res = optionNextValue( pOptValue, pOldValue );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOptValue	const tOptionValue *	a hierarchcal list value
	pOldValue	const tOptionValue *	a value from this list
	returns	const tOptionValue *	a compound value structure

This routine will return the next entry after the entry passed in. At the end of the list, NULL will be returned. If the entry is not found on the list, NULL will be returned and "errno" will be set to EINVAL. The "pOldValue" must have been gotten from a prior call to this routine or to "opitonGetValue()".

The returned result is NULL and errno is set:

• EINVAL - the pOptValue does not point to a valid hierarchical option value or pOldValue does not point to a member of that option value.
• ENOENT - the supplied pOldValue pointed to the last entry.

---

Next: optionPrintVersion, Previous: optionNextValue, Up: libopts External Procedures  

1.11 optionOnlyUsage

Print usage text for just the options

Usage:

optionOnlyUsage( pOpts, ex_code );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOpts	tOptions *	program options descriptor
	ex_code	int	exit code for calling exit(3)

This routine will print only the usage for each option. This function may be used when the emitted usage must incorporate information not available to AutoOpts.

---

Next: optionPrintVersionAndReturn, Previous: optionOnlyUsage, Up: libopts External Procedures  

1.12 optionPrintVersion

Print the program version

Usage:

optionPrintVersion( opts, od );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	od	tOptDesc *	the descriptor for this arg

This routine will print the version to stdout.

---

Next: optionProcess, Previous: optionPrintVersion, Up: libopts External Procedures  

1.13 optionPrintVersionAndReturn

Print the program version

Usage:

optionPrintVersionAndReturn( opts, od );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	od	tOptDesc *	the descriptor for this arg

This routine will print the version to stdout and return instead of exiting. Please see the source for the print_ver funtion for details on selecting how verbose to be after this function returns.

---

Next: optionRestore, Previous: optionPrintVersionAndReturn, Up: libopts External Procedures  

1.14 optionProcess

this is the main option processing routine

Usage:

int res = optionProcess( opts, a_ct, a_v );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor
	a_ct	int	program arg count
	a_v	char **	program arg vector
	returns	int	the count of the arguments processed

This is the main entry point for processing options. It is intended that this procedure be called once at the beginning of the execution of a program. Depending on options selected earlier, it is sometimes necessary to stop and restart option processing, or to select completely different sets of options. This can be done easily, but you generally do not want to do this.

The number of arguments processed always includes the program name. If one of the arguments is "–", then it is counted and the processing stops. If an error was encountered and errors are to be tolerated, then the returned value is the index of the argument causing the error. A hyphen by itself ("-") will also cause processing to stop and will not be counted among the processed arguments. A hyphen by itself is treated as an operand. Encountering an operand stops option processing.

Errors will cause diagnostics to be printed. exit(3) may or may not be called. It depends upon whether or not the options were generated with the "allow-errors" attribute, or if the ERRSKIP_OPTERR or ERRSTOP_OPTERR macros were invoked.

---

Next: optionSaveFile, Previous: optionProcess, Up: libopts External Procedures  

1.15 optionRestore

restore option state from memory copy

Usage:

optionRestore( pOpts );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOpts	tOptions *	program options descriptor

Copy back the option state from saved memory. The allocated memory is left intact, so this routine can be called repeatedly without having to call optionSaveState again. If you are restoring a state that was saved before the first call to optionProcess(3AO), then you may change the contents of the argc/argv parameters to optionProcess.

If you have not called optionSaveState before, a diagnostic is printed to stderr and exit is called.

---

Next: optionSaveState, Previous: optionRestore, Up: libopts External Procedures  

1.16 optionSaveFile

saves the option state to a file

Usage:

optionSaveFile( opts );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	opts	tOptions *	program options descriptor

This routine will save the state of option processing to a file. The name of that file can be specified with the argument to the --save-opts option, or by appending the rcfile attribute to the last homerc attribute. If no rcfile attribute was specified, it will default to .programnamerc. If you wish to specify another file, you should invoke the SET_OPT_SAVE_OPTS(filename) macro.

The recommend usage is as follows:

optionProcess(&progOptions, argc, argv);
if (i_want_a_non_standard_place_for_this)
SET_OPT_SAVE_OPTS("myfilename");
optionSaveFile(&progOptions);

If no homerc file was specified, this routine will silently return and do nothing. If the output file cannot be created or updated, a message will be printed to stderr and the routine will return.

---

Next: optionUnloadNested, Previous: optionSaveFile, Up: libopts External Procedures  

1.17 optionSaveState

saves the option state to memory

Usage:

optionSaveState( pOpts );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOpts	tOptions *	program options descriptor

This routine will allocate enough memory to save the current option processing state. If this routine has been called before, that memory will be reused. You may only save one copy of the option state. This routine may be called before optionProcess(3AO). If you do call it before the first call to optionProcess, then you may also change the contents of argc/argv after you call optionRestore(3AO)

In fact, more strongly put: it is safest to only use this function before having processed any options. In particular, the saving and restoring of stacked string arguments and hierarchical values is disabled. The values are not saved.

If it fails to allocate the memory, it will print a message to stderr and exit. Otherwise, it will always succeed.

---

Next: optionVersion, Previous: optionSaveState, Up: libopts External Procedures  

1.18 optionUnloadNested

Deallocate the memory for a nested value

Usage:

optionUnloadNested( pOptVal );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	pOptVal	tOptionValue const *	the hierarchical value

A nested value needs to be deallocated. The pointer passed in should have been gotten from a call to configFileLoad() (See see configFileLoad).

---

Next: strequate, Previous: optionUnloadNested, Up: libopts External Procedures  

1.19 optionVersion

return the compiled AutoOpts version number

Usage:

char const * res = optionVersion();

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	returns	char const *	the version string in constant memory

Returns the full version string compiled into the library. The returned string cannot be modified.

---

Next: streqvcmp, Previous: optionVersion, Up: libopts External Procedures  

1.20 strequate

map a list of characters to the same value

Usage:

strequate( ch_list );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	ch_list	char const *	characters to equivalence

Each character in the input string get mapped to the first character in the string. This function name is mapped to option_strequate so as to not conflict with the POSIX name space.

none.

---

Next: streqvmap, Previous: strequate, Up: libopts External Procedures  

1.21 streqvcmp

compare two strings with an equivalence mapping

Usage:

int res = streqvcmp( str1, str2 );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	str1	char const *	first string
	str2	char const *	second string
	returns	int	the difference between two differing characters

Using a character mapping, two strings are compared for "equivalence". Each input character is mapped to a comparison character and the mapped-to characters are compared for the two NUL terminated input strings. This function name is mapped to option_streqvcmp so as to not conflict with the POSIX name space.

none checked. Caller responsible for seg faults.

---

Next: strneqvcmp, Previous: streqvcmp, Up: libopts External Procedures  

1.22 streqvmap

Set the character mappings for the streqv functions

Usage:

streqvmap( from, to, ct );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	from	char	Input character
	to	char	Mapped-to character
	ct	int	compare length

Set the character mapping. If the count (ct) is set to zero, then the map is cleared by setting all entries in the map to their index value. Otherwise, the "From" character is mapped to the "To" character. If ct is greater than 1, then From and To are incremented and the process repeated until ct entries have been set. For example,

streqvmap('a', 'A', 26);

will alter the mapping so that all English lower case letters will map to upper case.

This function name is mapped to option_streqvmap so as to not conflict with the POSIX name space.

none.

---

Next: strtransform, Previous: streqvmap, Up: libopts External Procedures  

1.23 strneqvcmp

compare two strings with an equivalence mapping

Usage:

int res = strneqvcmp( str1, str2, ct );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	str1	char const *	first string
	str2	char const *	second string
	ct	int	compare length
	returns	int	the difference between two differing characters

Using a character mapping, two strings are compared for "equivalence". Each input character is mapped to a comparison character and the mapped-to characters are compared for the two NUL terminated input strings. The comparison is limited to ct bytes. This function name is mapped to option_strneqvcmp so as to not conflict with the POSIX name space.

none checked. Caller responsible for seg faults.

---

Previous: strneqvcmp, Up: libopts External Procedures  

1.24 strtransform

convert a string into its mapped-to value

Usage:

strtransform( dest, src );

Where the arguments are:

	Name	Type	Description
	—–	—–	————-
	dest	char *	output string
	src	char const *	input string

Each character in the input string is mapped and the mapped-to character is put into the output. This function name is mapped to option_strtransform so as to not conflict with the POSIX name space.

The source and destination may be the same.

none.

bye