Penlight Documentation

# Module `pl.text`

Text processing utilities.

This provides a Template class (modeled after the same from the Python libraries, see string.Template). It also provides similar functions to those found in the textwrap module.

See the Guide.

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.

    > require 'pl.text'.format_operator()
    > = '%s = %5.3f' % {'PI',math.pi}
    PI = 3.142
    > = '$name = $value' % {name='dog',value='Pluto'}
    dog = Pluto

Dependencies: pl.utils, pl.types

## Functions

indent (s, n, ch) | indent a multiline string.
dedent (s) | dedent a multiline string by removing any initial indent.
wrap (s, width) | format a paragraph into lines so that they fit into a line width.
fill (s, width) | format a paragraph so that it fits into a line width.
Template:substitute (tbl) | substitute values into a template, throwing an error.
Template:safe_substitute (tbl) | substitute values into a template.
Template:indent_substitute (tbl) | substitute values into a template, preserving indentation.

## Functions

indent (s, n, ch)
  indent a multiline string.

  ### Parameters:

  - s the string
  - n the size of the indent
  - ch 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.

  ### Parameters:

  - s the string

  ### Returns:

  a string with initial indent zero.
wrap (s, width)
  format a paragraph into lines so that they fit into a line width. It will not break long words, so lines can be over the length to that extent.

  ### Parameters:

  - s the string
  - width the margin width, default 70

  ### Returns:

  a list of lines (List object)

  ### See also:

  pl.List
fill (s, width)
  format a paragraph so that it fits into a line width.

  ### Parameters:

  - s the string
  - width the margin width, default 70

  ### Returns:

  a string

  ### See also:

  wrap
Template:substitute (tbl)
  substitute values into a template, throwing an error. This will throw an error if no name is found.

  ### Parameters:

  - tbl a table of name-value pairs.
Template:safe_substitute (tbl)
  substitute values into a template. This version just passes unknown names through.

  ### Parameters:

  - tbl a table of name-value pairs.
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 subsituted using the same table.

  ### Parameters:

  - tbl a table of name-value pairs.

generated by LDoc 1.4.6