Module pl.stringx
Python-style extended string library.
 see 3.6.1 of the Python reference.
 If you want to make these available as string methods, then say
 stringx.import() to bring them into the standard string table.
 See the Guide
 Dependencies: pl.utils, pl.types
	
	| lfind (s, sub[, first[, last]]) | find index of first instance of sub in s from the left. | 
	
	| rfind (s, sub[, first[, last]]) | find index of first instance of sub in s from the right. | 
	
	| replace (s, old, new[, n]) | replace up to n instances of old by new in the string s. | 
	
	| count (s, sub[, allow_overlap]) | count all instances of substring in string. | 
	
	| lines (s) | return an iterator over all lines in a string | 
	
	| title (s) | inital word letters uppercase ('title case'). | 
	
	| shorten (s, w, tail) | Return a shortened version of a string. | 
	
	| quote_string (s) | Quote the given string and preserve any control or escape characters, such that reloading the string in Lua returns the same result. | 
	
	| format_operator () | Python-style formatting operator. | 
	
	| import () | import the stringx functions into the global string (meta)table | 
    
    
    - 
    
    isalpha (s)
    
- 
    does s only contain alphabetic characters?
    Parameters:
- 
    
    isdigit (s)
    
- 
    does s only contain digits?
    Parameters:
- 
    
    isalnum (s)
    
- 
    does s only contain alphanumeric characters?
    Parameters:
- 
    
    isspace (s)
    
- 
    does s only contain whitespace?
 Matches on pattern '%s' so matches space, newline, tabs, etc.
    Parameters:
- 
    
    islower (s)
    
- 
    does s only contain lower case characters?
    Parameters:
- 
    
    isupper (s)
    
- 
    does s only contain upper case characters?
    Parameters:
- 
    
    startswith (s, prefix)
    
- 
    does s start with prefix or one of prefixes?
    Parameters:
        - s
            string
         a string
        
- prefix
         a string or an array of strings
        
 
- 
    
    endswith (s, suffix)
    
- 
    does s end with suffix or one of suffixes?
    Parameters:
        - s
            string
         a string
        
- suffix
         a string or an array of strings
        
 
    - 
    
    join (s, seq)
    
- 
    concatenate the strings using this string as a delimiter.
 Note that the arguments are reversed from string.concat.Parameters:
        - s
            string
         the string
        
- seq
         a table of strings or numbers
        
 Usage:stringx.join(' ', {1,2,3}) == '1 2 3'
- 
    
    splitlines (s[, keep_ends])
    
- 
    Split a string into a list of lines.
 "\r","\n", and"\r\n"are considered line ends.
 They are not included in the lines unlesskeependsis passed.
 Terminal line end does not produce an extra line.
 Splitting an empty string results in an empty list.Parameters:
        - s
            string
         the string.
        
- keep_ends
            bool
         include line ends.
         (optional)
        
 Returns:
        List of lines
     
- 
    
    split (s[, re[, n]])
    
- 
    split a string into a list of strings using a delimiter.
    Parameters:
        - s
            string
         the string
        
- re
            string
         a delimiter (defaults to whitespace)
         (optional)
        
- n
            int
         maximum number of results
         (optional)
        
 Returns:
        List
     Usage:
        - #(stringx.split('one two')) == 2
- stringx.split('one,two,three', ',') == List{'one','two','three'}
- stringx.split('one,two,three', ',', 2) == List{'one','two,three'}
 
- 
    
    expandtabs (s, tabsize)
    
- 
    replace all tabs in s with tabsize spaces.  If not specified, tabsize defaults to 8.
 Tab stops will be honored.
    Parameters:
        - s
            string
         the string
        
- tabsize
            int
        [opt=8] number of spaces to expand each tab
        
 Returns:
        expanded string
     Usage:
        - stringx.expandtabs('\tone,two,three', 4)   == '    one,two,three'
- stringx.expandtabs('  \tone,two,three', 4) == '    one,two,three'
 
    - 
    
    lfind (s, sub[, first[, last]])
    
- 
    find index of first instance of sub in s from the left.
    Parameters:
        - s
            string
         the string
        
- sub
            string
         substring
        
- first
            int
         first index
         (optional)
        
- last
            int
         last index
         (optional)
        
 Returns:
        start index, or nil if not found
     
- 
    
    rfind (s, sub[, first[, last]])
    
- 
    find index of first instance of sub in s from the right.
    Parameters:
        - s
            string
         the string
        
- sub
            string
         substring
        
- first
            int
         first index
         (optional)
        
- last
            int
         last index
         (optional)
        
 Returns:
        start index, or nil if not found
     
- 
    
    replace (s, old, new[, n])
    
- 
    replace up to n instances of old by new in the string s.
 If n is not present, replace all instances.
    Parameters:
        - s
            string
         the string
        
- old
            string
         the target substring
        
- new
            string
         the substitution
        
- n
            int
         optional maximum number of substitutions
         (optional)
        
 Returns:
        result string
     
- 
    
    count (s, sub[, allow_overlap])
    
- 
    count all instances of substring in string.
    Parameters:
        - s
            string
         the string
        
- sub
            string
         substring
        
- allow_overlap
            bool
         allow matches to overlap
         (optional)
        
 Usage:assert(stringx.count('banana', 'ana') == 1)
assert(stringx.count('banana', 'ana', true) == 2)
    - 
    
    ljust (s, w[, ch=' '])
    
- 
    left-justify s with width w.
    Parameters:
        - s
            string
         the string
        
- w
            int
         width of justification
        
- ch
            string
         padding character
         (default ' ')
        
 Usage:stringx.ljust('hello', 10, '*') == '*****hello'
- 
    
    rjust (s, w[, ch=' '])
    
- 
    right-justify s with width w.
    Parameters:
        - s
            string
         the string
        
- w
            int
         width of justification
        
- ch
            string
         padding character
         (default ' ')
        
 Usage:stringx.rjust('hello', 10, '*') == 'hello*****'
- 
    
    center (s, w[, ch=' '])
    
- 
    center-justify s with width w.
    Parameters:
        - s
            string
         the string
        
- w
            int
         width of justification
        
- ch
            string
         padding character
         (default ' ')
        
 Usage:stringx.center('hello', 10, '*') == '**hello***'
- 
    
    lstrip (s[, chrs='%s'])
    
- 
    trim any characters on the left of s.
    Parameters:
        - s
            string
         the string
        
- chrs
            string
         default any whitespace character,
 but can be a string of characters to be trimmed
         (default '%s')
        
 
- 
    
    rstrip (s[, chrs='%s'])
    
- 
    trim any characters on the right of s.
    Parameters:
        - s
            string
         the string
        
- chrs
            string
         default any whitespace character,
 but can be a string of characters to be trimmed
         (default '%s')
        
 
- 
    
    strip (s[, chrs='%s'])
    
- 
    trim any characters on both left and right of s.
    Parameters:
        - s
            string
         the string
        
- chrs
            string
         default any whitespace character,
 but can be a string of characters to be trimmed
         (default '%s')
        
 Usage:stringx.strip('  --== Hello ==--  ', "- =")  
    - 
    
    splitv (s[, re='%s'])
    
- 
    split a string using a pattern.  Note that at least one value will be returned!
    Parameters:
        - s
            string
         the string
        
- re
            string
         a Lua string pattern (defaults to whitespace)
         (default '%s')
        
 Returns:
        the parts of the string
     See also:Usage:a,b = line:splitv('=')
- 
    
    partition (s, ch)
    
- 
    partition the string using first occurance of a delimiter
    Parameters:
        - s
            string
         the string
        
- ch
            string
         delimiter (match as plain string, no patterns)
        
 Returns:
        - 
        part before ch
- 
        ch
- 
        part after ch
 Usage:
        - {stringx.partition('a,b,c', ','))} == {'a', ',', 'b,c'}
- {stringx.partition('abc', 'x'))} == {'abc', '', ''}
 
- 
    
    rpartition (s, ch)
    
- 
    partition the string p using last occurance of a delimiter
    Parameters:
        - s
            string
         the string
        
- ch
            string
         delimiter (match as plain string, no patterns)
        
 Returns:
        - 
        part before ch
- 
        ch
- 
        part after ch
 Usage:
        - {stringx.rpartition('a,b,c', ','))} == {'a,b', ',', 'c'}
- {stringx.rpartition('abc', 'x'))} == {'', '', 'abc'}
 
- 
    
    at (s, idx)
    
- 
    return the 'character' at the index.
    Parameters:
        - s
            string
         the string
        
- idx
            int
         an index (can be negative)
        
 Returns:
        a substring of length 1 if successful, empty string otherwise.
     
    - 
    
    indent (s, n[, ch=' '])
    
- 
    indent a multiline string.
    Parameters:
        - s
            string
         the (multiline) string
        
- n
            integer
         the size of the indent
        
- ch
            string
         the character to use when indenting
         (default ' ')
        
 Returns:
        indented string
     
- 
    
    dedent (s)
    
- 
    dedent a multiline string by removing any initial indent.
 useful when working with [[..]] strings.
 Empty lines are ignored.
    Parameters:
        - s
            string
         the (multiline) string
        
 Returns:
        a string with initial indent zero.
     Usage:local s = dedent [[
         One
       Two
     Three
]]
assert(s == [[
    One
  Two
Three
]])
- 
    
    wrap (s[, width=70[, breaklong=false]])
    
- 
    format a paragraph into lines so that they fit into a line width.
 It will not break long words by default, so lines can be over the length
 to that extent.
    Parameters:
        - s
            string
         the string to format
        
- width
            integer
         the margin width
         (default 70)
        
- breaklong
            boolean
         if truthy, words longer than the width given will be forced split.
         (default false)
        
 Returns:
        a list of lines (List object), use fill to return a string instead of a List.
     See also:
- 
    
    fill (s[, width=70[, breaklong=false]])
    
- 
    format a paragraph so that it fits into a line width.
    Parameters:
        - s
            string
         the string to format
        
- width
            integer
         the margin width
         (default 70)
        
- breaklong
            boolean
         if truthy, words longer than the width given will be forced split.
         (default false)
        
 Returns:
        a string, use wrap to return a list of lines instead of a string.
     See also:
    - 
    
    Template (tmpl)
    
- 
    Creates a new Template class.
 This is a shortcut to Template.new(tmpl).Parameters:
        - tmpl
            string
         the template string
        
 Returns:
           Template
     
- 
    
    Template:substitute (tbl)
    
- 
    substitute values into a template, throwing an error.
 This will throw an error if no name is found.
    Parameters:
        - tbl
            table
         a table of name-value pairs.
        
 Returns:
        string with place holders substituted
     
- 
    
    Template:safe_substitute (tbl)
    
- 
    substitute values into a template.
 This version just passes unknown names through.
    Parameters:
        - tbl
            table
         a table of name-value pairs.
        
 Returns:
        string with place holders substituted
     
- 
    
    Template:indent_substitute (tbl)
    
- 
    substitute values into a template, preserving indentation.  
 If the value is a multiline string or a template, it will insert
 the lines at the correct indentation.
 Furthermore, if a template, then that template will be substituted
 using the same table.Parameters:
        - tbl
            table
         a table of name-value pairs.
        
 Returns:
        string with place holders substituted
     
    - 
    
    lines (s)
    
- 
    return an iterator over all lines in a string
    Parameters:Returns:
        an iterator
     Usage:local line_no = 1
for line in stringx.lines(some_text) do
  print(line_no, line)
  line_no = line_no + 1
end 
- 
    
    title (s)
    
- 
    inital word letters uppercase ('title case').
 Here 'words' mean chunks of non-space characters.
    Parameters:Returns:
        a string with each word's first letter uppercase
     Usage:stringx.title("hello world") == "Hello World")
- 
    
    shorten (s, w, tail)
    
- 
    Return a shortened version of a string.
 Fits string within w characters. Removed characters are marked with ellipsis.
    Parameters:
        - s
            string
         the string
        
- w
            int
         the maxinum size allowed
        
- tail
            bool
         true if we want to show the end of the string (head otherwise)
        
 Usage:
        - ('1234567890'):shorten(8) == '12345...'
- ('1234567890'):shorten(8, true) == '...67890'
- ('1234567890'):shorten(20) == '1234567890'
 
- 
    
    quote_string (s)
    
- 
    Quote the given string and preserve any control or escape characters, such that reloading the string in Lua returns the same result.
    Parameters:
        - s
         The string to be quoted.
        
 Returns:
        The quoted string.
     
- 
    
    format_operator ()
    
- 
    Python-style formatting operator.
 Calling text.format_operator()overloads the % operator for strings to give
 Python/Ruby style formated output.
 This is extended to also do template-like substitution for map-like data. Note this goes further than the original, and will allow these cases: 
    - a single value
- a list of values
- a map of var=value pairs
- a function, as in gsub
  For the second two cases, it uses $-variable substituion.  When called, this function will monkey-patch the global string metatable by
 adding a __modmethod.
  See the lua-users wiki
     Usage:require 'pl.text'.format_operator()
local out1 = '%s = %5.3f' % {'PI',math.pi}                   local out2 = '$name = $value' % {name='dog',value='Pluto'}   
- 
    
    import ()
    
- 
    import the stringx functions into the global string (meta)table