Package lyntin :: Module utils
[show private | hide private]
[frames | no frames]

Module lyntin.utils

This has a series of utility functions that aren't related to classes in the application, but are useful in a variety of places. They're not dependent on application things, so it's easier to test them.
Classes
PriorityQueue This is a pretty basic priority queue.

Function Summary
  build_graph(numbers_dict)
Takes in a dict of keys to values and prints out a graph accordingly.
string chomp(text)
Removes all CR and LF from the end of the input string.
string columnize(textlist, screenwidth, indent)
Takes a list of data and converts it into a series of columns and rows that are evenly spaced and pretty and stuff.
Re compile_regexp(text, anchors, stars)
Takes in a string and compiles it into a regular expression.
int convert_boolean(text)
Returns 1 if true, 0 if false, or -1 if it's not a boolean.
string denest_vars(text, varmap)
Replaces all the nested variables with appropriate variables.
string escape(s)
Takes in a string and escapes all \ (single backslash) by one level (turning it into a double backslash) and all $ (single dollar sign) by one level (turning it into a single backslash and a single dollar sign).
string expand_placement_vars(input, expansion)
Takes an user input line and an alias expansion and hands it off to the appropriate function for evaluating the placement variable replacement.
list of strings expand_text(filter, fulllist)
Returns a subset of the list that matches the given string.
string expand_vars(text, varmap)
Note: If you have a text string and you want the variable manager to expand variables in that string according to session variables, use 'exported.expand_ses_vars' instead.
string filter_cm(text)
Filters out ^M.
string fixdir(d)
Takes in a directory (datadir, moduledir, ...) and fixes it (by adding an os.sep to the end) as well as verifies that it exists.
string http_get(url)
Retrieves the data at a given url and returns it as a big string.
list of tuples of (string, string) parse_args(args)
Takes in a list of args and parses it out into a hashmap of arg-name to value(s).
int parse_time(timearg)
Parses a time into the number of seconds since the epoch.
int parse_timespan(timespan)
Parses a timsspan into a number of seconds.
list of strings split_commands(text)
This method takens in text and parses it into separate commands on the ;.
string strip_braces(text)
Returns text after stripping the braces around the text.
string wrap_text(textlist, wraplength, indent, firstline)
It takes a block of text and wraps it nicely.

Variable Summary
SRE_Pattern CHOMP_EOL = [\r\n]+$
SRE_Pattern PVAR_REGEXP = %+(-?(\d+):?-?(\d*)|:-?(\d+))
SRE_Pattern REG_REGEXP = ^(r\[.*?)(\$?\][Ii]*)$
SRE_Pattern SEMI_REGEXP = (?!\\);
SRE_Pattern SUBVAR_REGEXP = %_?[0-9]+
SRE_Pattern TIME_REGEXP1 = ^([1-9]|1[0-2])([ap])$
SRE_Pattern TIME_REGEXP2 = ^([1-9]|1[0-2]):([0-5][0-9])(:([0-5]\d))?...
SRE_Pattern TIME_REGEXP3 = ^(0|1[3-9]|2[0-3]):([0-5][0-9])(:([0-5]\d...
SRE_Pattern TIMESPAN_REGEXP = ^(\d+d)?(\d+h)?(\d+m)?(\d+s?)?$

Function Details

build_graph(numbers_dict)

Takes in a dict of keys to values and prints out a graph accordingly.

chomp(text)

Removes all CR and LF from the end of the input string.
Parameters:
text - the text to chomp
           (type=string)
Returns:
the text without CR or LF at the end.
           (type=string)

columnize(textlist, screenwidth=72, indent=0)

Takes a list of data and converts it into a series of columns and rows that are evenly spaced and pretty and stuff.
Parameters:
textlist - the list of strings to columnize
           (type=list of strings)
screenwidth - the maximum width to wrap against
           (type=int)
indent - the amount of spaces to indent each line
           (type=int)
Returns:
the final formatted columnized string
           (type=string)

compile_regexp(text, anchors=0, stars=0)

Takes in a string and compiles it into a regular expression. This is for commands that take in strings that can be compiled either as a full-fledged regular expression (using Perl5 regexp syntax) or strings that are not regular expressions and use * as a wildcard character.
Parameters:
text - the string to convert
           (type=string)
anchors - whether (1) or not (0) to deal with anchors in the case of a string that's not a regular expression. anchors are ^ and $ at the beginning and end of a string.
           (type=boolean)
stars - whether (1) or not (0) to deal with * wildcards which can match whatever
           (type=boolean)
Returns:
the resulting regular expression
           (type=Re)

convert_boolean(text)

Returns 1 if true, 0 if false, or -1 if it's not a boolean.
Parameters:
text - the text to convert to a boolean value
           (type=string)
Returns:
1 if true, 0 if false, -1 if not a boolean
           (type=int)

denest_vars(text, varmap)

Replaces all the nested variables with appropriate variables.
Parameters:
text - the string to expand variables in
           (type=string)
varmap - the varname to expansion mapping (here only in case a mode needs it in the future, and for consistency with the other var expansion commands.)
           (type=dict)
Returns:
the text with all variables expanded
           (type=string)

escape(s)

Takes in a string and escapes all \ (single backslash) by one level (turning it into a double backslash) and all $ (single dollar sign) by one level (turning it into a single backslash and a single dollar sign).
Parameters:
s - the string to escape
           (type=string)
Returns:
the escaped string
           (type=string)

expand_placement_vars(input, expansion)

Takes an user input line and an alias expansion and hands it off to the appropriate function for evaluating the placement variable replacement.

Takes an input and an expansion and replaces expansion variables with the components from the input.

Returns the finalized string.
Parameters:
input - the user's input
           (type=string)
expansion - the expansion of the alias in the input
           (type=string)
Returns:
the expansion with all nested_vars replaced and placement vars replaced
           (type=string)

expand_text(filter, fulllist)

Returns a subset of the list that matches the given string.

Takes a list and a string and returns a list of items in the original list that match the given string. Handles * and anchors too.
Parameters:
filter - the string to match
           (type=string)
fulllist - the list of strings to match in
           (type=list of strings)
Returns:
the matching strings from the full list
           (type=list of strings)

expand_vars(text, varmap)

Note: If you have a text string and you want the variable manager to expand variables in that string according to session variables, use 'exported.expand_ses_vars' instead.

The following functions are used in the command processing pipeline at different points:
  1. expand_vars - This expands variables in a function arbitrarily according to the desired expansion policy. It should be safe to recusively evaluate this string and not have strings re-expanded.
  2. denest_vars - This finishes expansion of a string and should be called after all expansions are done.

Note that the variablemanager's "expand" function is used for general expansion of text when there won't be a recursion on the partially expanded (but not yet denested) text. It consists of chaining expand_vars and denest_vars together.

Looks at user input and expands any variables involved using the Lyntin variable expansion methodology.

Lyntin variable expansion works by replacing all instances of $blah with the appropriate variable. Then at a later point, variables preceded by multiple $ are denested one scope and lose a $.

It returns the (un)adjusted text.
Parameters:
text - the text to expand variables in
           (type=string)
varmap - the varname to expansion mapping
           (type=dict)
Returns:
the text with all variables expanded
           (type=string)

filter_cm(text)

Filters out ^M. Useful for logging.
Returns:
text without ^M stuff
           (type=string)

fixdir(d)

Takes in a directory (datadir, moduledir, ...) and fixes it (by adding an os.sep to the end) as well as verifies that it exists.

If it does not exist, then it returns a None. If it does exist, then it returns the adjusted directory name.
Parameters:
d - the directory in question
           (type=string)
Returns:
None or the fixed directory
           (type=string)

http_get(url)

Retrieves the data at a given url and returns it as a big string.
Parameters:
url - the url of the resource to retrieve
           (type=string)
Returns:
the resource at the given url
           (type=string)
Raises:
ValueError - if the url is not valid or if the resource doesn't exist

parse_args(args)

Takes in a list of args and parses it out into a hashmap of arg-name to value(s).
Parameters:
args - the list of command-line arguments
           (type=list of strings)
Returns:
list of tuples of (arg, value) pairings
           (type=list of tuples of (string, string))

parse_time(timearg)

Parses a time into the number of seconds since the epoch.

First attempts to parse as a time of day, and if that fails attempts to parse as a timespan. Timespans are interpretted as times from time.time() (now).
Parameters:
timearg - the time string to parse
           (type=string)
Returns:
the number of seconds
           (type=int)
Raises:
ValueError - if the time string was unparseable

parse_timespan(timespan)

Parses a timsspan into a number of seconds.
Parameters:
timespan - the timespan string to parse
           (type=string)
Returns:
the number of seconds in the timespan
           (type=int)
Raises:
ValueError - if the timespan is unparseable

split_commands(text)

This method takens in text and parses it into separate commands on the ;. It accounts for \; as well as ; in { } which indicate that we shouldn't be splitting there.
Parameters:
text - the text to split
           (type=string)
Returns:
the split text
           (type=list of strings)

strip_braces(text)

Returns text after stripping the braces around the text. If the incoming text has a { at the beginning and a } at the end, it removes the braces.
Parameters:
text - the string to remove braces from
           (type=string)
Returns:
the text with braces (if matched) removed
           (type=string)

wrap_text(textlist, wraplength=50, indent=0, firstline=0)

It takes a block of text and wraps it nicely. It accounts for indenting lines of text, wraplengths, and wrapping around ANSI colors.

We break on carriage returns (those are easy) and if no carriage returns are available we break on spaces.

If the actual line is longer than the wraplength, then we'll break in the line at the wraplength--this will cut words in two.

Note: we don't expand tabs or backspaces. Both count as one character.
Parameters:
textlist - either a string of text needing to be formatted and wrapped, or a textlist needing to be formatted and wrapped.
           (type=string or list of strings)
wraplength - the maximum length any line can be. we'll wrap at an index equal to or less than this length.
           (type=int)
indent - how many spaces to indent every line.
           (type=int)
firstline - 0 if we shouldn't indent the first line, 1 if we should
           (type=boolean)
Returns:
the wrapped text string
           (type=string)

Variable Details

CHOMP_EOL

Type:
SRE_Pattern
Value:
[\r\n]+$                                                               

PVAR_REGEXP

Type:
SRE_Pattern
Value:
%+(-?(\d+):?-?(\d*)|:-?(\d+))                                          

REG_REGEXP

Type:
SRE_Pattern
Value:
^(r\[.*?)(\$?\][Ii]*)$                                                 

SEMI_REGEXP

Type:
SRE_Pattern
Value:
(?!\\);                                                                

SUBVAR_REGEXP

Type:
SRE_Pattern
Value:
%_?[0-9]+                                                              

TIME_REGEXP1

Type:
SRE_Pattern
Value:
^([1-9]|1[0-2])([ap])$                                                 

TIME_REGEXP2

Type:
SRE_Pattern
Value:
^([1-9]|1[0-2]):([0-5][0-9])(:([0-5]\d))?([ap])?$                      

TIME_REGEXP3

Type:
SRE_Pattern
Value:
^(0|1[3-9]|2[0-3]):([0-5][0-9])(:([0-5]\d))?$                          

TIMESPAN_REGEXP

Type:
SRE_Pattern
Value:
^(\d+d)?(\d+h)?(\d+m)?(\d+s?)?$                                        

Generated by Epydoc 2.1 on Mon Aug 9 09:17:41 2004 http://epydoc.sf.net