1.13 web.util -- Useful utility functions that don't fit elsewhere

#
1.13 `web.util` -- Useful utility functions that don't fit elsewhere

This module provides a number of functions which come in handy when programming web applications but that don't fit in elsewhere. It is a catch all module for useful leftovers.

`wrap`( | text, width)

  A word-wrap function that preserves existing line breaks and most spaces in the text. Expects that existing line breaks are posix newlines. (ie backslash n)
  text
    The text to wrap
  width
    The maximum number of characters in a line

`strip`( | html, [validTags=[]])

  Strip illegal HTML tags from string
  html
    The HTML which needs some tags stripping
  validTags
    A list or tuple of tags to leave in place

`runWebServer`( | [root='../', cgi='/cgi-bin', ])

  Run a simple webserver on port 8080 on localhost. The root of the website corresponds to the directory root. cgi is URL of the the cgi-bin where files can be executed. Once this command is run code execution stops as the webserver listens for requests so there is no point in writing code after this command as it will not be run.

  Warning: NOT SUITABLE FOR COMMERCIAL USE.

  dir
    The only directory where scripts are allowed to run. Directory names should be the full URL path from the root of the webserver and therefore should begin with `/`

`table`( | columns, values, [width=80], [mode])

  Pretty print a table of data for display in a terminal of width width

  Warning: This function has changed radically from version 0.4.0

  columns
    The names of the columns in the order they are displayed in each row of values.

  values
    The data to be displayed in the format:

        (
            ('column1value1', 'column2value1', 'column3value1', 'column4value1'),
            ('column1value2', 'column2value2', 'column3value2', 'column4value2'),
            ('column1value3', 'column2value3', 'column3value3', 'column4value3'),
        )

    The values and column headings can be any object which can be converted to a string using `str()`.

  width
    The wrap width of the string produced. The default is `80` which means the table will we wrapped to the width of a standard terminla or command line prompt. If width is set to `0` no wrapping is produced.

  display
    If display is set to `'terminal'` the line ending at the wrap width (specified by width) will not be added since the line will wrap around to the next line anyway. Adding the linebreak would result in blank lines appearing.

  mode
    If mode is set to `'sql'` the values are encoded in a way to represent `None` as `NULL` and use `repr()` when `str()` would be ambiguous.

For example:

    #!/usr/bin/env python

    import sys; sys.path.append('../../../') # show python where the web modules are

    import web.util
    columns = [
        'column1Heading',
        'column2Heading',
        'column3Heading',
        'column4Heading'
    ]
    values = [
        ['column1value1', 'column2value1', 'column3value1', 'column4value1'],
        ['column1value2', 'column2value2', 'column3value2', 'column4value2'],
        ['column1value3', 'column2value3', 'column3value3', 'column4value3'],
    ]
    print "Printing the table with wrap width=0...\n"
    print web.util.table(columns, values, width=0)
    print "Printing the table with wrap width=60...\n"
    print web.util.table(columns, values, width=60)

    The output produced is:

    Printing the table with wrap width=0...

    +----------------+----------------+----------------+----------------+
    | column4Heading | column3Heading | column2Heading | column1Heading |
    +----------------+----------------+----------------+----------------+
    | column4value1  | column3value1  | column2value1  | column1value1  |
    | column4value2  | column3value2  | column2value2  | column1value2  |
    | column4value3  | column3value3  | column2value3  | column1value3  |
    +----------------+----------------+----------------+----------------+

    Printing the table with wrap width=60...

    +----------------+----------------+----------------+--------
    | column4Heading | column3Heading | column2Heading | column1
    +----------------+----------------+----------------+--------
    | column4value1  | column3value1  | column2value1  | column1
    | column4value2  | column3value2  | column2value2  | column1
    | column4value3  | column3value3  | column2value3  | column1
    +----------------+----------------+----------------+--------

    --------+
    Heading |
    --------+
    value1  |
    value2  |
    value3  |
    --------+

Warning: If you don't set the wrap width and your table is wider than the terminal then the terminal will wrap the table output itself. If this happens it will wrap each induvidual line of text rather than the whole table producing output that looks more like this:

    +----------------+----------------+--------------
    --+----------------+
    | column4Heading | column3Heading | column2Headin
    g | column1Heading |
    +----------------+----------------+--------------
    --+----------------+
    | column4value1  | column3value1  | column2value1
    | column1value1  |
    | column4value2  | column3value2  | column2value2
    | column1value2  |
    | column4value3  | column3value3  | column2value3
    | column1value3  |
    +----------------+----------------+--------------
    --+----------------+