11.  String Functions

      Most of the string handling primitives described in this section could as well have been implemented in Scheme based on the standard Scheme string primitives. They are provided as built-in primitives by unroff mainly as optimizations or because writing them as Scheme procedures would have been significantly more cumbersome. All the string functions return new strings, that is, they do not modify their arguments.

(concat . args)

      concat can be called with any number of Scheme strings, symbols, and characters. The primitive concatenates its arguments and returns the result as a string.

(spread)

      This primitive is identical to concat, except that it delimits its arguments by a space character. For example, the event procedure for a macro that just returns a line consisting of its arguments could be define like this:

(defmacro 'X
  (lambda (X . words)
    (parse (apply spread words) #\newline)))

(repeat-string num string)

      Returns a string consisting of the string argument string repeated num times.

(string-prune-left string prefix fail)

      This primitive checks whether string starts with the given string prefix, and if so, returns the rest of string beginning at the first character position after the initial prefix. If the strings do not match, fail is returned (which may an arbitrary object). Example:

(string-prune-left "+foo" "+" #f)     =>  "foo"
(string-prune-left "gulp" "+" #f)     =>  #f

(string-prune-right string suffix fail)

      This primitive is identical to string-prune-left, except that it checks for a suffix rather than a prefix, that is, whether string ends with suffix.

(string-compose string1 string2)

      If the argument string2 begins with a plus sign, string-compose returns the concatenation of string1 and string2 with the initial plus sign stripped. If string2 begins with a minus sign, it returns a string consisting of string1 with all characters occurring in string2 removed. Otherwise, string-compose just returns string2. This primitive is used for the implementation of the option type dynstring.

(parse-pair string)

      If string consists of two parts separated and enclosed by an arbitrary delimiter character, parse-pair returns a cons cell holding the two substrings. Otherwise, it returns #f. Example:

(parse-pair "'foo'bar'")    =>  ("foo" . "bar")
(parse-pair "hello")        =>  #f

(parse-triple string)

      This primitive is identical to parse-pair, except that it breaks up a three-part string rather than a two-part string and returns an improper list whose car, cadr, and cddr consist of the three substrings[note 5] . parse-pair and parse-triple are useful mainly for parsing the arguments to troff requests such as ``.if'' and ``.tl''.

(substitute string . args)

      This primitive returns a copy of string in which each sequence of a percent sign, a substitution specifier, and another percent sign is replaced by another string according to the specifier. Two adjacent percent signs are replaced by a single percent sign. The following list describes all substitution specifiers together with their respective replacements.

macros

The name of the troff macro package whose macros are recognized, that is, the argument to the option -m (or the empty string if none was specified).

format

The output format, that is, the argument to the option -f (or the default output format if the option was omitted).

directory

The name of the library directory from which unroff loads its Scheme files.

progname

The name of the running program (this is used as a prefix in error messages and warning messages).

filepos

A space character followed by the target of the current input stream, a colon, the number of the last input line read from the stream, and another colon. If the current input stream is bound to #f, the empty string is substituted. This specifier is useful for displaying error messages or warning messages.

tmpname

A file name that can be used for a temporary file. Each use of this specifier creates a new, unique file name.

version

The program's major and minor version numbers separated by a period.

weekday

The abbreviated weekday name.

weekday+

The full weekday name.

weekdaynum

The weekday (0-6, Sunday is 0).

monthname

The abbreviated month name.

monthname+

The full monthname.

day

The day of the month (01-31).

month

The month (01-12).

year

The year.

date

The date (in the local environment's representation).

time

The time (in the local environment's representation).

a positive number n

The nth additional argument in the call to the substitute primitive, which must be a string.

a string

string is interpreted as the name of an environment variable, and the value of this variable is substituted (or the empty string if the environment variable is undefined).

Examples:

(substitute "%date% %HOME%")     =>  "04/09/95 /home/kbs/net"

(substitute "%progname%:%filepos% %1%" "hello")
				 => "unroff: manual.ms:21: hello"

(load (substitute "%directory%/scm/%format%/m%macros%.scm"))