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
  n: index
returns
  s_: string.sub (s, n, n)


__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


split: Split a string at a given separator
  sep: separator regex
  s: string to split
returns
  l: list of strings


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


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


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