7.22.5.1 Overview ¶

Module ‘(texinfo string-utils)’ provides various string-related functions useful to Guile’s texinfo support.

7.22.5.2 Usage ¶

Function: escape-special-chars str special-chars escape-char ¶

Returns a copy of str with all given special characters preceded by the given escape-char.

special-chars can either be a single character, or a string consisting of all the special characters.

;; make a string regexp-safe...
 (escape-special-chars "***(Example String)***"  
                      "[]()/*." 
                      #\\)
=> "\\*\\*\\*\\(Example String\\)\\*\\*\\*"

;; also can escape a singe char...
 (escape-special-chars "richardt@vzavenue.net"
                      #\@
                      #\@)
=> "richardt@@vzavenue.net"

Function: transform-string str match? replace [start] [end] ¶

Uses match? against each character in str, and performs a replacement on each character for which matches are found.

match? may either be a function, a character, a string, or #t. If match? is a function, then it takes a single character as input, and should return ‘#t’ for matches. match? is a character, it is compared to each string character using char=?. If match? is a string, then any character in that string will be considered a match. #t will cause every character to be a match.

If replace is a function, it is called with the matched character as an argument, and the returned value is sent to the output string via ‘display’. If replace is anything else, it is sent through the output string via ‘display’.

Note that the replacement for the matched characters does not need to be a single character. That is what differentiates this function from ‘string-map’, and what makes it useful for applications such as converting ‘#\&’ to ‘"&"’ in web page text. Some other functions in this module are just wrappers around common uses of ‘transform-string’. Transformations not possible with this function should probably be done with regular expressions.

If start and end are given, they control which portion of the string undergoes transformation. The entire input string is still output, though. So, if start is ‘5’, then the first five characters of str will still appear in the returned string.

; these two are equivalent...
 (transform-string str #\space #\-) ; change all spaces to -'s
 (transform-string str (lambda (c) (char=? #\space c)) #\-)

Function: expand-tabs str [tab-size] ¶

Returns a copy of str with all tabs expanded to spaces. tab-size defaults to 8.

Assuming tab size of 8, this is equivalent to:

 (transform-string str #\tab "        ")

Function: center-string str [width] [chr] [rchr] ¶

Returns a copy of str centered in a field of width characters. Any needed padding is done by character chr, which defaults to ‘#\space’. If rchr is provided, then the padding to the right will use it instead. See the examples below. left and rchr on the right. The default width is 80. The default chr and rchr is ‘#\space’. The string is never truncated.

 (center-string "Richard Todd" 24)
=> "      Richard Todd      "

 (center-string " Richard Todd " 24 #\=)
=> "===== Richard Todd ====="

 (center-string " Richard Todd " 24 #\< #\>)
=> "<<<<< Richard Todd >>>>>"

Function: left-justify-string str [width] [chr] ¶

left-justify-string str [width chr]. Returns a copy of str padded with chr such that it is left justified in a field of width characters. The default width is 80. Unlike ‘string-pad’ from srfi-13, the string is never truncated.

Function: right-justify-string str [width] [chr] ¶

Returns a copy of str padded with chr such that it is right justified in a field of width characters. The default width is 80. The default chr is ‘#\space’. Unlike ‘string-pad’ from srfi-13, the string is never truncated.

Function: collapse-repeated-chars str [chr] [num] ¶

Returns a copy of str with all repeated instances of chr collapsed down to at most num instances. The default value for chr is ‘#\space’, and the default value for num is 1.

 (collapse-repeated-chars "H  e  l  l  o")
=> "H e l l o"
 (collapse-repeated-chars "H--e--l--l--o" #\-)
=> "H-e-l-l-o"
 (collapse-repeated-chars "H-e--l---l----o" #\- 2)
=> "H-e--l--l--o"

Function: make-text-wrapper [#:line-width] [#:expand-tabs?] [#:tab-width] [#:collapse-whitespace?] [#:subsequent-indent] [#:initial-indent] [#:break-long-words?] ¶

Returns a procedure that will split a string into lines according to the given parameters.

#:line-width

This is the target length used when deciding where to wrap lines. Default is 80.

#:expand-tabs?

Boolean describing whether tabs in the input should be expanded. Default is #t.

#:tab-width

If tabs are expanded, this will be the number of spaces to which they expand. Default is 8.

#:collapse-whitespace?

Boolean describing whether the whitespace inside the existing text should be removed or not. Default is #t.

If text is already well-formatted, and is just being wrapped to fit in a different width, then set this to ‘#f’. This way, many common text conventions (such as two spaces between sentences) can be preserved if in the original text. If the input text spacing cannot be trusted, then leave this setting at the default, and all repeated whitespace will be collapsed down to a single space.

#:initial-indent

Defines a string that will be put in front of the first line of wrapped text. Default is the empty string, “”.

#:subsequent-indent

Defines a string that will be put in front of all lines of wrapped text, except the first one. Default is the empty string, “”.

#:break-long-words?

If a single word is too big to fit on a line, this setting tells the wrapper what to do. Defaults to #t, which will break up long words. When set to #f, the line will be allowed, even though it is longer than the defined #:line-width.

The return value is a procedure of one argument, the input string, which returns a list of strings, where each element of the list is one line.

Function: fill-string str . kwargs ¶

Wraps the text given in string str according to the parameters provided in kwargs, or the default setting if they are not given. Returns a single string with the wrapped text. Valid keyword arguments are discussed in make-text-wrapper.

Function: string->wrapped-lines str . kwargs ¶

string->wrapped-lines str keywds .... Wraps the text given in string str according to the parameters provided in keywds, or the default setting if they are not given. Returns a list of strings representing the formatted lines. Valid keyword arguments are discussed in make-text-wrapper.