String

TODO: Pretty printing
(Use in getopt)
John Hughes's and Simon Peyton Jones's Pretty Printer Combinators
Based on The Design of a Pretty-printing Library in Advanced
Functional Programming, Johan Jeuring and Erik Meijer (eds), LNCS 925
http://www.cs.chalmers.se/~rjmh/Papers/pretty.ps
Heavily modified by Simon Peyton Jones, Dec 96
Haskell types:
data Doc list of lines
quote :: Char -> Char -> Doc -> Doc Wrap document in ...
(<>) :: Doc -> Doc -> Doc Beside
(<+>) :: Doc -> Doc -> Doc Beside, separated by space
($$) :: Doc -> Doc -> Doc Above; if there is no overlap it "dovetails" the two
nest :: Int -> Doc -> Doc Nested
punctuate :: Doc -> [Doc] -> [Doc] punctuate p [d1, ... dn] = [d1 <> p, d2 <> p, ... dn-1 <> p, dn]
render :: Int Line length
-> Float Ribbons per line
-> (TextDetails -> a -> a) What to do with text
-> a What to do at the end
-> Doc The document
-> a Result

__index: Give strings a subscription operator
s: string
i: index
returns
s_: string.sub (s, i, i) if i is a number,
or falls back to any previous metamethod (by default, string
methods)

__append: Give strings an append metamethod
s: string
c: character (1-character string)
returns
s_: s .. c

caps: Capitalise each word in a string
s: string
returns
s_: capitalised string

chomp: Remove any final newline from a string
s: string to process
returns
s_: processed string

escapePattern: Escape a string to be used as a pattern
s: string to process
returns
s_: processed string

escapeShell: Escape a string to be used as a shell token
Quotes spaces, parentheses, brackets, quotes, apostrophes and \s
s: string to process
returns
s_: processed string

ordinalSuffix: Return the English suffix for an ordinal
n: number of the day
returns
s: suffix

format: Extend to work better with one argument
If only one argument is passed, no formatting is attempted
f: format
...: arguments to format
returns
s: formatted string

pad: Justify a string
When the string is longer than w, it is truncated (left or right
according to the sign of w)
s: string to justify
w: width to justify to (-ve means right-justify; +ve means
left-justify)
[p]: string to pad with [" "]
returns
s_: justified string

wrap: Wrap a string into a paragraph
s: string to wrap
w: width to wrap to [78]
ind: indent [0]
ind1: indent of first line [ind]
returns
s_: wrapped paragraph

numbertosi: Write a number using SI suffixes
The number is always written to 3 s.f.
n: number
returns
n_: string

findl: Do find, returning captures as a list
s: target string
p: pattern
[init]: start position [1]
[plain]: inhibit magic characters [nil]
returns
from, to: start and finish of match
capt: table of captures

finds: Do multiple find's on a string
s: target string
p: pattern
[init]: start position [1]
[plain]: inhibit magic characters [nil]
returns
l: list of {from, to; capt = {captures}}

gsubs: Perform multiple calls to gsub
s: string to call gsub on
sub: {pattern1=replacement1 ...}
[n]: upper limit on replacements [infinite]
returns
s_: result string
r: number of replacements made

FIXME: Consider Perl and Python versions.
split: Split a string at a given separator
s: string to split
sep: separator regex
returns
l: list of strings

ltrim: Remove leading matter from a string
s: string
[r]: leading regex ["%s+"]
returns
s_: string without leading r

rtrim: Remove trailing matter from a string
s: string
[r]: trailing regex ["%s+"]
returns
s_: string without trailing r

trim: Remove leading and trailing matter from a string
s: string
[r]: leading/trailing regex ["%s+"]
returns
s_: string without leading/trailing r