3.5 Common Scheme Functions

This section describes a number of general purpose functions that make the kind of string processing that AutoGen does a little easier. Unlike the AutoGen specific functions (see section AutoGen Scheme Functions), these functions are available for direct use during definition load time. The equality test (see section ‘string-eqv?’ - caseless match) is “overloaded” to do string equivalence comparisons. If you are looking for inequality, the Scheme/Lisp way of spelling that is, “(not (= ...))”.

3.5.1 ‘agpl’ - GNU Affero General Public License

Usage: (agpl prog-name prefix)
Emit a string that contains the GNU Affero General Public License. This function is now deprecated. Please See section ‘license-description’ - Emit a license description.

Arguments:
prog-name - name of the program under the GPL
prefix - String for starting each output line

3.5.2 ‘bsd’ - BSD Public License

Usage: (bsd prog_name owner prefix)
Emit a string that contains the Free BSD Public License. This function is now deprecated. Please See section ‘license-description’ - Emit a license description.

Arguments:
prog_name - name of the program under the BSD
owner - Grantor of the BSD License
prefix - String for starting each output line

3.5.3 ‘c-string’ - emit string for ANSI C

Usage: (c-string string)
Reform a string so that, when printed, the C compiler will be able to compile the data and construct a string that contains exactly what the current string contains. Many non-printing characters are replaced with escape sequences. Newlines are replaced with a backslash, an n, a closing quote, a newline, seven spaces and another re-opening quote. The compiler will implicitly concatenate them. The reader will see line breaks.

A K&R compiler will choke. Use kr-string for that compiler.

Arguments:
string - string to reformat

3.5.4 ‘error-source-line’ - display of file & line

Usage: (error-source-line)
This function is only invoked just before Guile displays an error message. It displays the file name and line number that triggered the evaluation error. You should not need to invoke this routine directly. Guile will do it automatically.

This Scheme function takes no arguments.

3.5.5 ‘extract’ - extract text from another file

Usage: (extract file-name marker-fmt [ caveat ] [ default ])
This function is used to help construct output files that may contain text that is carried from one version of the output to the next.

The first two arguments are required, the second are optional:

• The file-name argument is used to name the file that contains the demarcated text.
• The marker-fmt is a formatting string that is used to construct the starting and ending demarcation strings. The sprintf function is given the marker-fmt with two arguments. The first is either "START" or "END". The second is either "DO NOT CHANGE THIS COMMENT" or the optional caveat argument.
• caveat is presumed to be absent if it is the empty string (""). If absent, “DO NOT CHANGE THIS COMMENT” is used as the second string argument to the marker-fmt.
• When a default argument is supplied and no pre-existing text is found, then this text will be inserted between the START and END markers.

The resulting strings are presumed to be unique within the subject file. As a simplified example:

[+ (extract "fname" "// %s - SOMETHING - %s" ""
"example default") +]

will result in the following text being inserted into the output:

// START - SOMETHING - DO NOT CHANGE THIS COMMENT
example default
// END   - SOMETHING - DO NOT CHANGE THIS COMMENT

The “example default” string can then be carried forward to the next generation of the output, provided the output is not named "fname" and the old output is renamed to "fname" before AutoGen-eration begins.

NB:

You can set aside previously generated source files inside the pseudo macro with a Guile/scheme function, extract the text you want to keep with this extract function. Just remember you should delete it at the end, too. Here is an example from my Finite State Machine generator:

[+ AutoGen5 Template -*- Mode: text -*- h=%s-fsm.h c=%s-fsm.c (shellf "test -f %1$s-fsm.h && mv -f %1$s-fsm.h .fsm.head test -f %1$s-fsm.c && mv -f %1$s-fsm.c .fsm.code" (base-name)) +]

This code will move the two previously produced output files to files named ".fsm.head" and ".fsm.code". At the end of the ’c’ output processing, I delete them.

also NB:

This function presumes that the output file ought to be editable so that the code between the START and END marks can be edited by the template user. Consequently, when the (extract ...) function is invoked, if the writable option has not been specified, then it will be set at that point. If this is not the desired behavior, the --not-writable command line option will override this. Also, you may use the guile function (chmod "file" mode-value) to override whatever AutoGen is using for the result mode.

Arguments:
file-name - name of file with text
marker-fmt - format for marker text
caveat - Optional - warn about changing marker
default - Optional - default initial text

3.5.6 ‘format-arg-count’ - count the args to a format

Usage: (format-arg-count format)
Sometimes, it is useful to simply be able to figure out how many arguments are required by a format string. For example, if you are extracting a format string for the purpose of generating a macro to invoke a printf-like function, you can run the formatting string through this function to determine how many arguments to provide for in the macro. e.g. for this extraction text:

 /*=fumble bumble
  * fmt: 'stumble %s: %d\n'
 =*/

You may wish to generate a macro:

 #define BUMBLE(a1,a2) printf_like(something,(a1),(a2))

You can do this by knowing that the format needs two arguments.

Arguments:
format - formatting string

3.5.7 ‘fprintf’ - format to a file

Usage: (fprintf port format [ format-arg ... ])
Format a string using arguments from the alist. Write to a specified port. The result will NOT appear in your output. Use this to print information messages to a template user.

Arguments:
port - Guile-scheme output port
format - formatting string
format-arg - Optional - list of arguments to formatting string

3.5.8 ‘gperf’ - perform a perfect hash function

Usage: (gperf name str)
Perform the perfect hash on the input string. This is only useful if you have previously created a gperf program with the make-gperf function See section ‘make-gperf’ - build a perfect hash function program. The name you supply here must match the name used to create the program and the string to hash must be one of the strings supplied in the make-gperf string list. The result will be a perfect hash index.

See the documentation for gperf(1GNU) for more details.

Arguments:
name - name of hash list
str - string to hash

3.5.9 ‘gperf-code’ - emit the source of the generated gperf program

Usage: (gperf-code st-name)
Returns the contents of the emitted code, suitable for inclusion in another program. The interface contains the following elements:

‘struct <st-name>_index’

containg the fields: {char const * name, int const id; };

‘<st-name>_hash()’

This is the hashing function with local only scope (static).

‘<st-name>_find()’

This is the searching and validation function. The first argument is the string to look up, the second is its length. It returns a pointer to the corresponding <st-name>_index entry.

Use this in your template as follows where "<st-name>" was set to be "lookup":

[+ (make-gperf "lookup" (join "\n" (stack "name_list")))
(gperf-code "lookup") +]
void my_fun(char * str) {
struct lookup_index * li = lookup_find(str, strlen(str));
if (li != NULL) printf("%s yields %d\n", str, li->idx);

Arguments:
st-name - the name of the gperf hash list

3.5.10 ‘gpl’ - GNU General Public License

Usage: (gpl prog-name prefix)
Emit a string that contains the GNU General Public License. This function is now deprecated. Please See section ‘license-description’ - Emit a license description.

Arguments:
prog-name - name of the program under the GPL
prefix - String for starting each output line

3.5.11 ‘hide-email’ - convert eaddr to javascript

Usage: (hide-email display eaddr)
Hides an email address as a java scriptlett. The ’mailto:’ tag and the email address are coded bytes rather than plain text. They are also broken up.

Arguments:
display - display text
eaddr - email address

3.5.12 ‘html-escape-encode’ - encode html special characters

Usage: (html-escape-encode str)
This function will replace replace the characters '&', '<' and '>' characters with the HTML/XML escape-encoded strings ("&", "<", and ">", respectively).

Arguments:
str - string to make substitutions in

3.5.13 ‘in?’ - test for string in list

Usage: (in? test-string string-list ...)
Return SCM_BOOL_T if the first argument string is found in one of the entries in the second (list-of-strings) argument.

Arguments:
test-string - string to look for
string-list - list of strings to check

3.5.14 ‘join’ - join string list with separator

Usage: (join separator list ...)
With the first argument as the separator string, joins together an a-list of strings into one long string. The list may contain nested lists, partly because you cannot always control that.

Arguments:
separator - string to insert between entries
list - list of strings to join

3.5.15 ‘kr-string’ - emit string for K&R C

Usage: (kr-string string)
Reform a string so that, when printed, a K&R C compiler will be able to compile the data and construct a string that contains exactly what the current string contains. Many non-printing characters are replaced with escape sequences. New-lines are replaced with a backslash-n-backslash and newline sequence,

Arguments:
string - string to reformat

3.5.16 ‘lgpl’ - GNU Library General Public License

Usage: (lgpl prog_name owner prefix)
Emit a string that contains the GNU Library General Public License. This function is now deprecated. Please See section ‘license-description’ - Emit a license description.

Arguments:
prog_name - name of the program under the LGPL
owner - Grantor of the LGPL
prefix - String for starting each output line

3.5.17 ‘license’ - an arbitrary license

Usage: (license lic_name prog_name owner prefix)
Emit a string that contains the named license. This function is now deprecated. Please See section ‘license-description’ - Emit a license description.

Arguments:
lic_name - file name of the license
prog_name - name of the licensed program or library
owner - Grantor of the License
prefix - String for starting each output line

3.5.18 ‘license-description’ - Emit a license description

Usage: (license-description license prog-name prefix [ owner ])
Emit a string that contains a detailed license description, with substitutions for program name, copyright holder and a per-line prefix. This is the text typically used as part of a source file header. For more details, See section the license-full command.

Arguments:
license - name of license type
prog-name - name of the program under the GPL
prefix - String for starting each output line
owner - Optional - owner of the program

3.5.19 ‘license-full’ - Emit the licensing information and description

Usage: (license-full license prog-name prefix [ owner ] [ years ])
Emit all the text that license-info and license-description would emit (see section license-info, and see section license-description), with all the same substitutions.

All of these depend upon the existence of a license file named after the license argument with a .lic suffix. That file should contain three blocks of text, each separated by two or more consecutive newline characters (at least one completely blank line).

The first section describes copyright attribution and the name of the usage licence. For GNU software, this should be the text that is to be displayed with the program version. Four text markers can be replaced: <PFX>, <program>, <years> and <owner>.

The second section is a short description of the terms of the license. This is typically the kind of text that gets displayed in the header of source files. Only the <PFX>, <owner> and <program> markers are substituted.

The third section is strictly the name of the license. No marker substitutions are performed.

<PFX>Copyright (C) <years> <owner>, all rights reserved.
<PFX>
<PFX>This is free software. It is licensed for use,
<PFX>modification and redistribution under the terms
<PFX>of the GNU General Public License, version 3 or later
<PFX>    <http://gnu.org/licenses/gpl.html>

<PFX><program> is free software: you can redistribute it
<PFX>and/or modify it under the terms of the GNU General
<PFX>Public License as published by the Free Software ...

the GNU General Public License, version 3 or later

Arguments:
license - name of license type
prog-name - name of the program under the GPL
prefix - String for starting each output line
owner - Optional - owner of the program
years - Optional - copyright years

3.5.20 ‘license-info’ - Emit the licensing information and copyright years

Usage: (license-info license prog-name prefix [ owner ] [ years ])
Emit a string that contains the licensing description, with some substitutions for program name, copyright holder, a list of years when the source was modified, and a per-line prefix. This text typically includes a brief license description and is often printed out when a program starts running or as part of the --version output. For more details, See section the license-full command.

Arguments:
license - name of license type
prog-name - name of the program under the GPL
prefix - String for starting each output line
owner - Optional - owner of the program
years - Optional - copyright years

3.5.21 ‘license-name’ - Emit the name of the license

Usage: (license-name license)
Emit a string that contains the full name of the license.

Arguments:
license - name of license type

3.5.22 ‘make-gperf’ - build a perfect hash function program

Usage: (make-gperf name strings ...)
Build a program to perform perfect hashes of a known list of input strings. This function produces no output, but prepares a program named, ‘gperf_<name>’ for use by the gperf function See section ‘gperf’ - perform a perfect hash function.

This program will be obliterated as AutoGen exits. However, you may incorporate the generated hashing function into your C program with commands something like the following:

[+ (shellf "sed '/^int main(/,$d;/^#line/d' ${gpdir}/%s.c"
name ) +]

where name matches the name provided to this make-perf function. gpdir is the variable used to store the name of the temporary directory used to stash all the files.

Arguments:
name - name of hash list
strings - list of strings to hash

3.5.23 ‘makefile-script’ - create makefile script

Usage: (makefile-script text)
This function will take ordinary shell script text and reformat it so that it will work properly inside of a makefile shell script. Not every shell construct can be supported; the intent is to have most ordinary scripts work without much, if any, alteration.

The following transformations are performed on the source text:

1. Trailing whitespace on each line is stripped.
2. Except for the last line, the string, " ; \\" is appended to the end of every line that does not end with certain special characters or keywords. Note that this will mutilate multi-line quoted strings, but make renders it impossible to use multi-line constructs anyway.
3. If the line ends with a backslash, it is left alone.
4. If the line ends with a semi-colon, conjunction operator, pipe (vertical bar) or one of the keywords "then", "else" or "in", then a space and a backslash is added, but no semi-colon.
5. The dollar sign character is doubled, unless it immediately precedes an opening parenthesis or the single character make macros ’*’, ’<’, ’@’, ’?’ or ’%’. Other single character make macros that do not have enclosing parentheses will fail. For shell usage of the "$@", "$?" and "$*" macros, you must enclose them with curly braces, e.g., "${?}". The ksh construct $(<command>) will not work. Though some makes accept ${var} constructs, this function will assume it is for shell interpretation and double the dollar character. You must use $(var) for all make substitutions.
6. Double dollar signs are replaced by four before the next character is examined.
7. Every line is prefixed with a tab, unless the first line already starts with a tab.
8. The newline character on the last line, if present, is suppressed.
9. Blank lines are stripped.
10. Lines starting with "@ifdef", "@ifndef", "@else" and "@endif" are presumed to be autoconf "sed" expression tags. These lines will be emitted as-is, with no tab prefix and no line splicing backslash. These lines can then be processed at configure time with AC_CONFIG_FILES sed expressions, similar to:

    sed "/^@ifdef foo/d;/^@endif foo/d;/^@ifndef foo/,/^@endif foo/d"

This function is intended to be used approximately as follows:

$(TARGET) : $(DEPENDENCIES)
<+ (out-push-new) +>
....mostly arbitrary shell script text....
<+ (makefile-script (out-pop #t)) +>

Arguments:
text - the text of the script

3.5.24 ‘max’ - maximum value in list

Usage: (max list ...)
Return the maximum value in the list

Arguments:
list - list of values. Strings are converted to numbers

3.5.25 ‘min’ - minimum value in list

Usage: (min list ...)
Return the minimum value in the list

Arguments:
list - list of values. Strings are converted to numbers

3.5.26 ‘prefix’ - prefix lines with a string

Usage: (prefix prefix text)
Prefix every line in the second string with the first string. This includes empty lines, though trailing white space will be removed if the line consists only of the "prefix". Also, if the last character is a newline, then *two* prefixes will be inserted into the result text.

For example, if the first string is "# " and the second contains:

"two\nlines\n"

The result string will contain:

# two
# lines
#

The last line will be incomplete: no newline and no space after the hash character, either.

Arguments:
prefix - string to insert at start of each line
text - multi-line block of text

3.5.27 ‘printf’ - format to stdout

Usage: (printf format [ format-arg ... ])
Format a string using arguments from the alist. Write to the standard out port. The result will NOT appear in your output. Use this to print information messages to a template user. Use “(sprintf ...)” to add text to your document.

Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string

3.5.28 ‘raw-shell-str’ - single quote shell string

Usage: (raw-shell-str string)
Convert the text of the string into a singly quoted string that a normal shell will process into the original string. (It will not do macro expansion later, either.) Contained single quotes become tripled, with the middle quote escaped with a backslash. Normal shells will reconstitute the original string.

Notice: some shells will not correctly handle unusual non-printing characters. This routine works for most reasonably conventional ASCII strings.

Arguments:
string - string to transform

3.5.29 ‘shell’ - invoke a shell script

Usage: (shell command ...)
Generate a string by writing the value to a server shell and reading the output back in. The template programmer is responsible for ensuring that it completes within 10 seconds. If it does not, the server will be killed, the output tossed and a new server started.

Please note: This is the same server process used by the ’#shell’ definitions directive and backquoted ` definitions. There may be left over state from previous shell expressions and the ` processing in the declarations. However, a cd to the original directory is always issued before the new command is issued.

Also note: When initializing, autogen will set the environment variable "AGexe" to the full path of the autogen executable.

Arguments:
command - shell command - the result is from stdout

3.5.30 ‘shell-str’ - double quote shell string

Usage: (shell-str string)
Convert the text of the string into a double quoted string that a normal shell will process into the original string, almost. It will add the escape character \\ before two special characters to accomplish this: the backslash \\ and double quote ".

Notice: some shells will not correctly handle unusual non-printing characters. This routine works for most reasonably conventional ASCII strings.

WARNING:
This function omits the extra backslash in front of a backslash, however, if it is followed by either a backquote or a dollar sign. It must do this because otherwise it would be impossible to protect the dollar sign or backquote from shell evaluation. Consequently, it is not possible to render the strings "\\$" or "\\‘". The lesser of two evils.

All others characters are copied directly into the output.

The sub-shell-str variation of this routine behaves identically, except that the extra backslash is omitted in front of " instead of `. You have to think about it. I’m open to suggestions.

Meanwhile, the best way to document is with a detailed output example. If the backslashes make it through the text processing correctly, below you will see what happens with three example strings. The first example string contains a list of quoted foos, the second is the same with a single backslash before the quote characters and the last is with two backslash escapes. Below each is the result of the raw-shell-str, shell-str and sub-shell-str functions.

foo[0]           ''foo'' 'foo' "foo" `foo` $foo
raw-shell-str -> \'\''foo'\'\'' '\''foo'\'' "foo" `foo` $foo'
shell-str     -> "''foo'' 'foo' \"foo\" `foo` $foo"
sub-shell-str -> `''foo'' 'foo' "foo" \`foo\` $foo`

foo[1]           \'bar\' \"bar\" \`bar\` \$bar
raw-shell-str -> '\'\''bar\'\'' \"bar\" \`bar\` \$bar'
shell-str     -> "\\'bar\\' \\\"bar\\\" \`bar\` \$bar"
sub-shell-str -> `\\'bar\\' \"bar\" \\\`bar\\\` \$bar`

foo[2]           \\'BAZ\\' \\"BAZ\\" \\`BAZ\\` \\$BAZ
raw-shell-str -> '\\'\''BAZ\\'\'' \\"BAZ\\" \\`BAZ\\` \\$BAZ'
shell-str     -> "\\\\'BAZ\\\\' \\\\\"BAZ\\\\\" \\\`BAZ\\\` \\\$BAZ"
sub-shell-str -> `\\\\'BAZ\\\\' \\\"BAZ\\\" \\\\\`BAZ\\\\\` \\\$BAZ`

There should be four, three, five and three backslashes for the four examples on the last line, respectively. The next to last line should have four, five, three and three backslashes. If this was not accurately reproduced, take a look at the agen5/test/shell.test test. Notice the backslashes in front of the dollar signs. It goes from zero to one to three for the "cooked" string examples.

Arguments:
string - string to transform

3.5.31 ‘shellf’ - format a string, run shell

Usage: (shellf format [ format-arg ... ])
Format a string using arguments from the alist, then send the result to the shell for interpretation.

Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string

3.5.32 ‘sprintf’ - format a string

Usage: (sprintf format [ format-arg ... ])
Format a string using arguments from the alist.

Arguments:
format - formatting string
format-arg - Optional - list of arguments to formatting string

3.5.33 ‘string-capitalize’ - capitalize a new string

Usage: (string-capitalize str)
Create a new SCM string containing the same text as the original, only all the first letter of each word is upper cased and all other letters are made lower case.

Arguments:
str - input string

3.5.34 ‘string-capitalize!’ - capitalize a string

Usage: (string-capitalize! str)
capitalize all the words in an SCM string.

Arguments:
str - input/output string

3.5.35 ‘string-contains-eqv?’ - caseless substring

Usage: (*=* text match)
string-contains-eqv?: Test to see if a string contains an equivalent string. ‘equivalent’ means the strings match, but without regard to character case and certain characters are considered ‘equivalent’. Viz., ’-’, ’_’ and ’^’ are equivalent.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.36 ‘string-contains?’ - substring match

Usage: (*==* text match)
string-contains?: Test to see if a string contains a substring. "strstr(3)" will find an address.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.37 ‘string-downcase’ - lower case a new string

Usage: (string-downcase str)
Create a new SCM string containing the same text as the original, only all the upper case letters are changed to lower case.

Arguments:
str - input string

3.5.38 ‘string-downcase!’ - make a string be lower case

Usage: (string-downcase! str)
Change to lower case all the characters in an SCM string.

Arguments:
str - input/output string

3.5.39 ‘string-end-eqv-match?’ - caseless regex ending

Usage: (*~ text match)
string-end-eqv-match?: Test to see if a string ends with a pattern. Case is not significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.40 ‘string-end-match?’ - regex match end

Usage: (*~~ text match)
string-end-match?: Test to see if a string ends with a pattern. Case is significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.41 ‘string-ends-eqv?’ - caseless string ending

Usage: (*= text match)
string-ends-eqv?: Test to see if a string ends with an equivalent string.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.42 ‘string-ends-with?’ - string ending

Usage: (*== text match)
string-ends-with?: Test to see if a string ends with a substring. strcmp(3) returns zero for comparing the string ends.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.43 ‘string-equals?’ - string matching

Usage: (== text match)
string-equals?: Test to see if two strings exactly match.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.44 ‘string-eqv-match?’ - caseless regex match

Usage: (~ text match)
string-eqv-match?: Test to see if a string fully matches a pattern. Case is not significant, but any character equivalences must be expressed in your regular expression.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.45 ‘string-eqv?’ - caseless match

Usage: (= text match)
string-eqv?: Test to see if two strings are equivalent. ‘equivalent’ means the strings match, but without regard to character case and certain characters are considered ‘equivalent’. Viz., ’-’, ’_’ and ’^’ are equivalent. If the arguments are not strings, then the result of the numeric comparison is returned.

This is an overloaded operation. If the arguments are both numbers, then the query is passed through to scm_num_eq_p(), otherwise the result depends on the SCMs being strictly equal.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.46 ‘string-has-eqv-match?’ - caseless regex contains

Usage: (*~* text match)
string-has-eqv-match?: Test to see if a string contains a pattern. Case is not significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.47 ‘string-has-match?’ - contained regex match

Usage: (*~~* text match)
string-has-match?: Test to see if a string contains a pattern. Case is significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.48 ‘string-match?’ - regex match

Usage: (~~ text match)
string-match?: Test to see if a string fully matches a pattern. Case is significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.49 ‘string-start-eqv-match?’ - caseless regex start

Usage: (~* text match)
string-start-eqv-match?: Test to see if a string starts with a pattern. Case is not significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.50 ‘string-start-match?’ - regex match start

Usage: (~~* text match)
string-start-match?: Test to see if a string starts with a pattern. Case is significant.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.51 ‘string-starts-eqv?’ - caseless string start

Usage: (=* text match)
string-starts-eqv?: Test to see if a string starts with an equivalent string.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.52 ‘string-starts-with?’ - string starting

Usage: (==* text match)
string-starts-with?: Test to see if a string starts with a substring.

Arguments:
text - text to test for pattern
match - pattern/substring to search for

3.5.53 ‘string-substitute’ - multiple global replacements

Usage: (string-substitute source match repl)
match and repl may be either a single string or a list of strings. Either way, they must have the same structure and number of elements. For example, to replace all amphersands, less than and greater than characters, do something like this:

(string-substitute source
(list "&"     "<"    ">")
(list "&amp;" "&lt;" "&gt;"))

Arguments:
source - string to transform
match - substring or substring list to be replaced
repl - replacement strings or substrings

3.5.54 ‘string-table-add’ - Add an entry to a string table

Usage: (string-table-add st-name str-val)
Check for a duplicate string and, if none, then insert a new string into the string table. In all cases, returns the character index of the beginning of the string in the table.

The returned index can be used in expressions like:

string_array + <returned-value>

that will yield the address of the first byte of the inserted string. See the ‘strtable.test’ AutoGen test for a usage example.

Arguments:
st-name - the name of the array of characters
str-val - the (possibly) new value to add

3.5.55 ‘string-table-add-ref’ - Add an entry to a string table, get reference

Usage: (string-table-add-ref st-name str-val)
Identical to string-table-add, except the value returned is the string "st-name" ’+’ and the index returned by string-table-add.

Arguments:
st-name - the name of the array of characters
str-val - the (possibly) new value to add

3.5.56 ‘string-table-new’ - create a string table

Usage: (string-table-new st-name)
This function will create an array of characters. The companion functions, (See section ‘string-table-add’ - Add an entry to a string table, See section ‘string-table-add-ref’ - Add an entry to a string table, get reference, and see section ‘emit-string-table’ - output a string table) will insert text and emit the populated table.

With these functions, it should be much easier to construct structures containing string offsets instead of string pointers. That can be very useful when transmitting, storing or sharing data with different address spaces.

Here is a brief example copied from the strtable.test test:

[+ (string-table-new "scribble")
   (out-push-new) ;; redirect output to temporary
   (define ct 1)  +][+

FOR str IN that was the week that was +][+
  (set! ct (+ ct 1))
+]
    [+ (string-table-add-ref "scribble" (get "str")) +],[+
ENDFOR  +]
[+ (out-suspend "main")
   (emit-string-table "scribble")
   (ag-fprintf 0 "\nchar const *ap[%d] = {" ct)
   (out-resume "main")
   (out-pop #t) ;; now dump out the redirected output +]
    NULL };

Some explanation:

I added the (out-push-new) because the string table text is diverted into an output stream named, “scribble” and I want to have the string table emitted before the string table references. The string table references are also emitted inside the FOR loop. So, when the loop is done, the current output is suspended under the name, “main” and the “scribble” table is then emitted into the primary output. (emit-string-table inserts its output directly into the current output stream. It does not need to be the last function in an AutoGen macro block.) Next I ag-fprintf the array-of-pointer declaration directly into the current output. Finally I restore the “main” output stream and (out-pop #t)-it into the main output stream.

Here is the result. Note that duplicate strings are not repeated in the string table:

static char const scribble[18] =
    "that\0" "was\0"  "the\0"  "week\0";

char const *ap[7] = {
    scribble+0,
    scribble+5,
    scribble+9,
    scribble+13,
    scribble+0,
    scribble+5,
    NULL };

These functions use the global name space stt-* in addition to the function names.

If you utilize this in your programming, it is recommended that you prevent printf format usage warnings with the GCC option -Wno-format-contains-nul

Arguments:
st-name - the name of the array of characters

3.5.57 ‘string-table-size’ - print the current size of a string table

Usage: (string-table-size st-name)
Returns the current byte count of the string table.

Arguments:
st-name - the name of the array of characters

3.5.58 ‘string->c-name!’ - map non-name chars to underscore

Usage: (string->c-name! str)
Change all the graphic characters that are invalid in a C name token into underscores. Whitespace characters are ignored. Any other character type (i.e. non-graphic and non-white) will cause a failure.

Arguments:
str - input/output string

3.5.59 ‘string->camelcase’ - make a string be CamelCase

Usage: (string->camelcase str)
Capitalize the first letter of each block of letters and numbers, and stripping out characters that are not alphanumerics. For example, "alpha-beta0gamma" becomes "AlphaBeta0gamma".

Arguments:
str - input/output string

3.5.60 ‘string-tr’ - convert characters with new result

Usage: (string-tr source match translation)
This is identical to string-tr!, except that it does not over-write the previous value.

Arguments:
source - string to transform
match - characters to be converted
translation - conversion list

3.5.61 ‘string-tr!’ - convert characters

Usage: (string-tr! source match translation)
This is the same as the tr(1) program, except the string to transform is the first argument. The second and third arguments are used to construct mapping arrays for the transformation of the first argument.

It is too bad this little program has so many different and incompatible implementations!

Arguments:
source - string to transform
match - characters to be converted
translation - conversion list

3.5.62 ‘string-upcase’ - upper case a new string

Usage: (string-upcase str)
Create a new SCM string containing the same text as the original, only all the lower case letters are changed to upper case.

Arguments:
str - input string

3.5.63 ‘string-upcase!’ - make a string be upper case

Usage: (string-upcase! str)
Change to upper case all the characters in an SCM string.

Arguments:
str - input/output string

3.5.64 ‘sub-shell-str’ - back quoted (sub-)shell string

Usage: (sub-shell-str string)
This function is substantially identical to shell-str, except that the quoting character is ` and the "leave the escape alone" character is ".

Arguments:
string - string to transform

3.5.65 ‘sum’ - sum of values in list

Usage: (sum list ...)
Compute the sum of the list of expressions.

Arguments:
list - list of values. Strings are converted to numbers

3.5.66 ‘time-string->number’ - duration string to seconds

Usage: (time-string->number time_spec)
Convert the argument string to a time period in seconds. The string may use multiple parts consisting of days, hours minutes and seconds. These are indicated with a suffix of d, h, m and s respectively. Hours, minutes and seconds may also be represented with HH:MM:SS or, without hours, as MM:SS.

Arguments:
time_spec - string to parse

3.5.67 ‘version-compare’ - compare two version numbers

Usage: (version-compare op v1 v2)
Converts v1 and v2 strings into 64 bit values and returns the result of running ’op’ on those values. It assumes that the version is a 1 to 4 part dot-separated series of numbers. Suffixes like, "5pre4" or "5-pre4" will be interpreted as two numbers. The first number ("5" in this case) will be decremented and the number after the "pre" will be added to 0xC000. (Unless your platform is unable to support 64 bit integer arithmetic. Then it will be added to 0xC0.) Consequently, these yield true:

(version-compare > "5.8.5"       "5.8.5-pre4")
(version-compare > "5.8.5-pre10" "5.8.5-pre4")

Arguments:
op - comparison operator
v1 - first version
v2 - compared-to version

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.