diff options
Diffstat (limited to 'doc/libopts.texi')
| -rw-r--r-- | doc/libopts.texi | 901 |
1 files changed, 901 insertions, 0 deletions
diff --git a/doc/libopts.texi b/doc/libopts.texi new file mode 100644 index 0000000..a09ac44 --- /dev/null +++ b/doc/libopts.texi @@ -0,0 +1,901 @@ +@node libopts procedures +@subsection 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 @file{options.h} header is +fairly clear about this, too. + +@menu +* libopts-ao_string_tokenize:: ao_string_tokenize +* libopts-configFileLoad:: configFileLoad +* libopts-optionFileLoad:: optionFileLoad +* libopts-optionFindNextValue:: optionFindNextValue +* libopts-optionFindValue:: optionFindValue +* libopts-optionFree:: optionFree +* libopts-optionGetValue:: optionGetValue +* libopts-optionLoadLine:: optionLoadLine +* libopts-optionNextValue:: optionNextValue +* libopts-optionOnlyUsage:: optionOnlyUsage +* libopts-optionProcess:: optionProcess +* libopts-optionRestore:: optionRestore +* libopts-optionSaveFile:: optionSaveFile +* libopts-optionSaveState:: optionSaveState +* libopts-optionUnloadNested:: optionUnloadNested +* libopts-optionVersion:: optionVersion +* libopts-pathfind:: pathfind +* libopts-strequate:: strequate +* libopts-streqvcmp:: streqvcmp +* libopts-streqvmap:: streqvmap +* libopts-strneqvcmp:: strneqvcmp +* libopts-strtransform:: strtransform +@end menu + +This subsection was automatically generated by AutoGen +using extracted information and the aginfo3.tpl template. + +@node libopts-ao_string_tokenize +@subsubsection ao_string_tokenize +@findex ao_string_tokenize + +tokenize an input string + +@noindent +Usage: +@example +token_list_t* res = ao_string_tokenize( string ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab string @tab @code{char const*} +@tab string to be tokenized +@item @tab returns @tab token_list_t* +@tab pointer to a structure that lists each token +@end multitable + +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 @code{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: +@table @samp +@item tkn_ct +The number of tokens found in the input string. +@item tok_list +An array of @code{tkn_ct + 1} pointers to substring tokens, with +the last pointer set to NULL. +@end table + +There are two types of quoted strings: single quoted (@code{'}) and +double quoted (@code{"}). Singly quoted strings are fairly raw in that +escape characters (@code{\\}) are simply another character, except when +preceding the following characters: +@example +@code{\\} double backslashes reduce to one +@code{'} incorporates the single quote into the string +@code{\n} suppresses both the backslash and newline character +@end example + +Double quote strings are formed according to the rules of string +constants in ANSI-C programs. + +NULL is returned and @code{errno} will be set to indicate the problem: +@itemize @bullet +@item +@code{EINVAL} - There was an unterminated quoted string. +@item +@code{ENOENT} - The input string was empty. +@item +@code{ENOMEM} - There is not enough memory. +@end itemize + + +@node libopts-configFileLoad +@subsubsection configFileLoad +@findex configFileLoad + +parse a configuration file + +@noindent +Usage: +@example +const tOptionValue* res = configFileLoad( pzFile ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pzFile @tab @code{char const*} +@tab the file to load +@item @tab returns @tab const tOptionValue* +@tab An allocated, compound value structure +@end multitable + +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 "@code{OPARG_TYPE_HIERARCHY}". It may be used in calls to +@code{optionGetValue()}, @code{optionNextValue()} and +@code{optionUnloadNested()}. + +If the file cannot be loaded or processed, @code{NULL} is returned and +@var{errno} is set. It may be set by a call to either @code{open(2)} +@code{mmap(2)} or other file system calls, or it may be: +@itemize @bullet +@item +@code{ENOENT} - the file was not found. +@item +@code{ENOMSG} - the file was empty. +@item +@code{EINVAL} - the file contents are invalid -- not properly formed. +@item +@code{ENOMEM} - not enough memory to allocate the needed structures. +@end itemize + + +@node libopts-optionFileLoad +@subsubsection optionFileLoad +@findex optionFileLoad + +Load the locatable config files, in order + +@noindent +Usage: +@example +int res = optionFileLoad( pOpts, pzProg ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor + +@item @tab pzProg @tab @code{char const*} +@tab program name +@item @tab returns @tab int +@tab 0 -> SUCCESS, -1 -> FAILURE +@end multitable + +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 @strong{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. + + +@node libopts-optionFindNextValue +@subsubsection optionFindNextValue +@findex optionFindNextValue + +find a hierarcicaly valued option instance + +@noindent +Usage: +@example +const tOptionValue* res = optionFindNextValue( pOptDesc, pPrevVal, name, value ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptDesc @tab @code{const tOptDesc*} +@tab an option with a nested arg type + +@item @tab pPrevVal @tab @code{const tOptionValue*} +@tab the last entry + +@item @tab name @tab @code{char const*} +@tab name of value to find + +@item @tab value @tab @code{char const*} +@tab the matching value +@item @tab returns @tab const tOptionValue* +@tab a compound value structure +@end multitable + +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: +@itemize @bullet +@item +@code{EINVAL} - the @code{pOptValue} does not point to a valid +hierarchical option value. +@item +@code{ENOENT} - no entry matched the given name. +@end itemize + + +@node libopts-optionFindValue +@subsubsection optionFindValue +@findex optionFindValue + +find a hierarcicaly valued option instance + +@noindent +Usage: +@example +const tOptionValue* res = optionFindValue( pOptDesc, name, value ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptDesc @tab @code{const tOptDesc*} +@tab an option with a nested arg type + +@item @tab name @tab @code{char const*} +@tab name of value to find + +@item @tab value @tab @code{char const*} +@tab the matching value +@item @tab returns @tab const tOptionValue* +@tab a compound value structure +@end multitable + +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: +@itemize @bullet +@item +@code{EINVAL} - the @code{pOptValue} does not point to a valid +hierarchical option value. +@item +@code{ENOENT} - no entry matched the given name. +@end itemize + + +@node libopts-optionFree +@subsubsection optionFree +@findex optionFree + +free allocated option processing memory + +@noindent +Usage: +@example +optionFree( pOpts ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor +@end multitable + +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. + + +@node libopts-optionGetValue +@subsubsection optionGetValue +@findex optionGetValue + +get a specific value from a hierarcical list + +@noindent +Usage: +@example +const tOptionValue* res = optionGetValue( pOptValue, valueName ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptValue @tab @code{const tOptionValue*} +@tab a hierarchcal value + +@item @tab valueName @tab @code{char const*} +@tab name of value to get +@item @tab returns @tab const tOptionValue* +@tab a compound value structure +@end multitable + +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: +@itemize @bullet +@item +@code{EINVAL} - the @code{pOptValue} does not point to a valid +hierarchical option value. +@item +@code{ENOENT} - no entry matched the given name. +@end itemize + + +@node libopts-optionLoadLine +@subsubsection optionLoadLine +@findex optionLoadLine + +process a string for an option name and value + +@noindent +Usage: +@example +optionLoadLine( opts, line ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab opts @tab @code{tOptions*} +@tab program options descriptor + +@item @tab line @tab @code{char const*} +@tab NUL-terminated text +@end multitable + +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 (@pxref{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. + + +@node libopts-optionNextValue +@subsubsection optionNextValue +@findex optionNextValue + +get the next value from a hierarchical list + +@noindent +Usage: +@example +const tOptionValue* res = optionNextValue( pOptValue, pOldValue ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptValue @tab @code{const tOptionValue*} +@tab a hierarchcal list value + +@item @tab pOldValue @tab @code{const tOptionValue*} +@tab a value from this list +@item @tab returns @tab const tOptionValue* +@tab a compound value structure +@end multitable + +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 "@var{errno}" will be set to EINVAL. +The "@var{pOldValue}" must have been gotten from a prior call to this +routine or to "@code{opitonGetValue()}". + +The returned result is NULL and errno is set: +@itemize @bullet +@item +@code{EINVAL} - the @code{pOptValue} does not point to a valid +hierarchical option value or @code{pOldValue} does not point to a +member of that option value. +@item +@code{ENOENT} - the supplied @code{pOldValue} pointed to the last entry. +@end itemize + + +@node libopts-optionOnlyUsage +@subsubsection optionOnlyUsage +@findex optionOnlyUsage + +Print usage text for just the options + +@noindent +Usage: +@example +optionOnlyUsage( pOpts, ex_code ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor + +@item @tab ex_code @tab @code{int} +@tab exit code for calling exit(3) +@end multitable + +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. + + +@node libopts-optionProcess +@subsubsection optionProcess +@findex optionProcess + +this is the main option processing routine + +@noindent +Usage: +@example +int res = optionProcess( pOpts, argc, argv ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor + +@item @tab argc @tab @code{int} +@tab program arg count + +@item @tab argv @tab @code{char**} +@tab program arg vector +@item @tab returns @tab int +@tab the count of the arguments processed +@end multitable + +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 +@emph{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. @code{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. + + +@node libopts-optionRestore +@subsubsection optionRestore +@findex optionRestore + +restore option state from memory copy + +@noindent +Usage: +@example +optionRestore( pOpts ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor +@end multitable + +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 @code{optionSaveState} before, a diagnostic is +printed to @code{stderr} and exit is called. + + +@node libopts-optionSaveFile +@subsubsection optionSaveFile +@findex optionSaveFile + +saves the option state to a file + +@noindent +Usage: +@example +optionSaveFile( pOpts ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor +@end multitable + +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 @code{--save-opts} +option, or by appending the @code{rcfile} attribute to the last +@code{homerc} attribute. If no @code{rcfile} attribute was specified, it +will default to @code{.@i{programname}rc}. If you wish to specify another +file, you should invoke the @code{SET_OPT_SAVE_OPTS(@i{filename})} macro. + +The recommend usage is as follows: +@example +optionProcess(&progOptions, argc, argv); +if (i_want_a_non_standard_place_for_this) +SET_OPT_SAVE_OPTS("myfilename"); +optionSaveFile(&progOptions); +@end example + +If no @code{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 @code{stderr} and the routine will return. + + +@node libopts-optionSaveState +@subsubsection optionSaveState +@findex optionSaveState + +saves the option state to memory + +@noindent +Usage: +@example +optionSaveState( pOpts ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor +@end multitable + +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. + + +@node libopts-optionUnloadNested +@subsubsection optionUnloadNested +@findex optionUnloadNested + +Deallocate the memory for a nested value + +@noindent +Usage: +@example +optionUnloadNested( pOptVal ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptVal @tab @code{tOptionValue const *} +@tab the hierarchical value +@end multitable + +A nested value needs to be deallocated. The pointer passed in should +have been gotten from a call to @code{configFileLoad()} (See +@pxref{libopts-configFileLoad}). + + +@node libopts-optionVersion +@subsubsection optionVersion +@findex optionVersion + +return the compiled AutoOpts version number + +@noindent +Usage: +@example +char const* res = optionVersion(); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab returns @tab char const* +@tab the version string in constant memory +@end multitable + +Returns the full version string compiled into the library. +The returned string cannot be modified. + + +@node libopts-pathfind +@subsubsection pathfind +@findex pathfind + +fild a file in a list of directories + +@noindent +Usage: +@example +char* res = pathfind( path, file, mode ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab path @tab @code{char const*} +@tab colon separated list of search directories + +@item @tab file @tab @code{char const*} +@tab the name of the file to look for + +@item @tab mode @tab @code{char const*} +@tab the mode bits that must be set to match +@item @tab returns @tab char* +@tab the path to the located file +@end multitable + +pathfind looks for a a file with name "FILE" and "MODE" access +along colon delimited "PATH", and returns the full pathname as a +string, or NULL if not found. If "FILE" contains a slash, then +it is treated as a relative or absolute path and "PATH" is ignored. + +@strong{NOTE}: this function is compiled into @file{libopts} only if +it is not natively supplied. + +The "MODE" argument is a string of option letters chosen from the +list below: +@example +Letter Meaning +r readable +w writable +x executable +f normal file (NOT IMPLEMENTED) +b block special (NOT IMPLEMENTED) +c character special (NOT IMPLEMENTED) +d directory (NOT IMPLEMENTED) +p FIFO (pipe) (NOT IMPLEMENTED) +u set user ID bit (NOT IMPLEMENTED) +g set group ID bit (NOT IMPLEMENTED) +k sticky bit (NOT IMPLEMENTED) +s size nonzero (NOT IMPLEMENTED) +@end example + +returns NULL if the file is not found. + + +@node libopts-strequate +@subsubsection strequate +@findex strequate + +map a list of characters to the same value + +@noindent +Usage: +@example +strequate( ch_list ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab ch_list @tab @code{char const*} +@tab characters to equivalence +@end multitable + +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. + + +@node libopts-streqvcmp +@subsubsection streqvcmp +@findex streqvcmp + +compare two strings with an equivalence mapping + +@noindent +Usage: +@example +int res = streqvcmp( str1, str2 ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab str1 @tab @code{char const*} +@tab first string + +@item @tab str2 @tab @code{char const*} +@tab second string +@item @tab returns @tab int +@tab the difference between two differing characters +@end multitable + +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. + + +@node libopts-streqvmap +@subsubsection streqvmap +@findex streqvmap + +Set the character mappings for the streqv functions + +@noindent +Usage: +@example +streqvmap( From, To, ct ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab From @tab @code{char} +@tab Input character + +@item @tab To @tab @code{char} +@tab Mapped-to character + +@item @tab ct @tab @code{int} +@tab compare length +@end multitable + +Set the character mapping. If the count (@code{ct}) is set to zero, then +the map is cleared by setting all entries in the map to their index +value. Otherwise, the "@code{From}" character is mapped to the "@code{To}" +character. If @code{ct} is greater than 1, then @code{From} and @code{To} +are incremented and the process repeated until @code{ct} entries have been +set. For example, +@example +streqvmap('a', 'A', 26); +@end example +@noindent +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. + + +@node libopts-strneqvcmp +@subsubsection strneqvcmp +@findex strneqvcmp + +compare two strings with an equivalence mapping + +@noindent +Usage: +@example +int res = strneqvcmp( str1, str2, ct ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab str1 @tab @code{char const*} +@tab first string + +@item @tab str2 @tab @code{char const*} +@tab second string + +@item @tab ct @tab @code{int} +@tab compare length +@item @tab returns @tab int +@tab the difference between two differing characters +@end multitable + +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 @code{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. + + +@node libopts-strtransform +@subsubsection strtransform +@findex strtransform + +convert a string into its mapped-to value + +@noindent +Usage: +@example +strtransform( dest, src ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab dest @tab @code{char*} +@tab output string + +@item @tab src @tab @code{char const*} +@tab input string +@end multitable + +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. + |