#!/usr/bin/env python
#
# $Id: utils.py,v 1.2 2006/12/05 13:10:46 doughellmann Exp $
#
# Copyright 2001 Doug Hellmann.
#
#
# All Rights Reserved
#
# Permission to use, copy, modify, and distribute this software and
# its documentation for any purpose and without fee is hereby
# granted, provided that the above copyright notice appear in all
# copies and that both that copyright notice and this permission
# notice appear in supporting documentation, and that the name of Doug
# Hellmann not be used in advertising or publicity pertaining to
# distribution of the software without specific, written prior
# permission.
#
# DOUG HELLMANN DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
# INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN
# NO EVENT SHALL DOUG HELLMANN BE LIABLE FOR ANY SPECIAL, INDIRECT OR
# CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
# NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
#
"""Utility functions for parseinfo package.
"""
__rcs_info__ = {
#
# Creation Information
#
'module_name' : '$RCSfile: utils.py,v $',
'rcs_id' : '$Id: utils.py,v 1.2 2006/12/05 13:10:46 doughellmann Exp $',
'creator' : 'Doug Hellmann',
'project' : 'HappyDoc',
'created' : 'Sun, 11-Nov-2001 10:47:39 EST',
#
# Current Information
#
'author' : '$Author: doughellmann $',
'version' : '$Revision: 1.2 $',
'date' : '$Date: 2006/12/05 13:10:46 $',
}
try:
__version__ = __rcs_info__['version'].split(' ')[1]
except:
__version__ = '0.0'
#
# Import system modules
#
import pprint
import symbol
import token
import types
#
# Import Local modules
#
#
# Module
#
# This pattern identifies compound statements, allowing them to be readily
# differentiated from simple statements.
#
COMPOUND_STMT_PATTERN = (
symbol.stmt,
(symbol.compound_stmt, ['compound'])
)
# This pattern matches the name of an item which appears in a
# testlist sequence. This can be used for finding the
# base classes of a class, or the parameters to a function or
# method.
#
# BASE_CLASS_NAME_PATTERN = (
# symbol.test,
# (symbol.and_test,
# (symbol.not_test,
# (symbol.comparison,
# (symbol.expr,
# (symbol.xor_expr,
# (symbol.and_expr,
# (symbol.shift_expr,
# (symbol.arith_expr,
# (symbol.term,
# (symbol.factor,
# (symbol.power,
# (symbol.atom,
# (token.NAME, ['name'])
# )))))))))))))
BASE_CLASS_NAME_PATTERN = (
symbol.test,
(symbol.and_test,
(symbol.not_test,
(symbol.comparison,
(symbol.expr,
(symbol.xor_expr,
(symbol.and_expr,
(symbol.shift_expr,
(symbol.arith_expr,
(symbol.term,
(symbol.factor, ['power'])
))))))))))
# This pattern will match a 'stmt' node which *might* represent a docstring;
# docstrings require that the statement which provides the docstring be the
# first statement in the class or function, which this pattern does not check.
#
DOCSTRING_STMT_PATTERN = (
symbol.stmt,
(symbol.simple_stmt,
(symbol.small_stmt,
(symbol.expr_stmt,
(symbol.testlist,
(symbol.test,
(symbol.and_test,
(symbol.not_test,
(symbol.comparison,
(symbol.expr,
(symbol.xor_expr,
(symbol.and_expr,
(symbol.shift_expr,
(symbol.arith_expr,
(symbol.term,
(symbol.factor,
(symbol.power,
(symbol.atom,
(token.STRING, ['docstring'])
)))))))))))))))),
(token.NEWLINE, '')
))
def joinCodeSnippets(first, second, separator):
"""Join two code snippets into one string.
Use some general code content rules to try to make the
resulting snippet look nice.
"""
if second.strip() in ('.',):
sep_to_be_used = ''
elif second and ( second[0] in ('.', ',', '(',) ):
if second[0] == '(' and first and first[-1] == ',':
sep_to_be_used = separator
else:
sep_to_be_used = ''
elif (not first) or (first and first[-1] in ('.',)) or (first in ('-',)):
sep_to_be_used = ''
elif ( (first and ( first[-1] in ('(', '[', '{') )) and
(second and ( second[-1] in (')', ']', '}') ))
):
sep_to_be_used = ''
elif first and ( first[-1] in ('(', '[', '{') ):
sep_to_be_used = separator
else:
sep_to_be_used = separator
text = '%s%s%s' % (first, sep_to_be_used, second)
return text
def parseTreeToString(tree, separator=' '):
"""Convert a parse tree to a string which would have parsed in that way.
Given a parse tree, walk it to determine the original string
which would have been parsed to produce that tree.
"""
#pprint 'STRINGING: ',
#pprint.pprint(tree)
text = ''
if tree and type(tree) in (types.TupleType, types.ListType):
if type(tree[0]) in (types.TupleType, types.ListType):
tree_parts = tree
else:
tree_parts = tree[1:]
sub_parts = map( lambda x, s=separator: parseTreeToString(x, s),
tree_parts)
for one_part in sub_parts:
text = joinCodeSnippets(text, one_part, separator)
else:
text = str(tree)
return text
def findNode(tree, node, response=None):
"Return a sequence of subtrees starting with node value of 'node'."
if response == None:
response = []
if type(tree) not in (types.ListType, types.TupleType):
return response
if tree[0] == node:
response.append(tree)
else:
for subtree in tree[1:]:
findNode(subtree, node, response)
return response
def drill(tree, depth):
"Return the section of the parse 'tree' that is 'depth' nodes deep."
for i in range(depth):
try:
tree = tree[1]
except IndexError:
return ()
return tree
def match(pattern, data, vars=None, dbg=0):
"""Match `data' to `pattern', with variable extraction.
pattern --
Pattern to match against, possibly containing variables.
data --
Data to be checked and against which variables are extracted.
vars --
Dictionary of variables which have already been found. If not
provided, an empty dictionary is created.
The `pattern' value may contain variables of the form ['varname'] which
are allowed to match anything. The value that is matched is returned as
part of a dictionary which maps 'varname' to the matched value. 'varname'
is not required to be a string object, but using strings makes patterns
and the code which uses them more readable.
This function returns two values: a boolean indicating whether a match
was found and a dictionary mapping variable names to their associated
values.
"""
pattern_type = type(pattern)
#if dbg:
# print 'PATTERN: ',
# pprint.pprint(pattern)
# print 'DATA:',
# pprint.pprint(data)
if vars is None:
vars = {}
if pattern_type is types.ListType: # 'variables' are ['varname']
#if dbg:
# print 'storing "%s" for variable "%s"' % (data, pattern[0])
vars[pattern[0]] = data
return 1, vars
if pattern_type is not types.TupleType:
#if dbg:
# print 'end recursion'
# print 'pattern=', pattern
# print 'data', data
#
# Ignore comments, since the pattern will include an empty
# string.
#
if (pattern_type == types.StringType) and (data and data[0] == '#'):
return 1, vars
return (pattern == data), vars
if len(data) != len(pattern):
#if dbg:
# print 'shortcut, length does not match'
return 0, vars
for pattern, data in map(None, pattern, data):
#if dbg:
# print 'recursing'
same, vars = match(pattern, data, vars, dbg=dbg)
if not same:
break
return same, vars
def lenientMatch(pattern, data, vars=None, dbg=0):
"""Match `data' to `pattern', with variable extraction.
pattern --
Pattern to match against, possibly containing variables.
data --
Data to be checked and against which variables are extracted.
vars --
Dictionary of variables which have already been found. If not
provided, an empty dictionary is created.
The `pattern' value may contain variables of the form ['varname'] which
are allowed to match anything. The value that is matched is returned as
part of a dictionary which maps 'varname' to the matched value. 'varname'
is not required to be a string object, but using strings makes patterns
and the code which uses them more readable.
This function is based on the match() function, but is more lenient.
The pattern does not have to completely describe the tree. Instead,
it can be the 'top' portion of the tree. Everything must match down
to the leaves of the pattern. At that point, the matching stops. If
a match was found at all, the return values indicate a match.
This function returns two values: a boolean indicating whether a match
was found and a dictionary mapping variable names to their associated
values.
"""
#if dbg:
# print 'PATTERN : ',
# pprint.pprint(pattern)
# print 'DATA :',
# #pprint.pprint(data)
# print data
if vars is None:
vars = {}
if type(pattern) is types.ListType: # 'variables' are ['varname']
#if dbg:
# print 'storing "%s" for variable "%s"' % (data, pattern[0])
vars[pattern[0]] = data
return 1, vars
if type(pattern) is not types.TupleType:
#if dbg:
# print 'end recursion'
return (pattern == data), vars
found_match = 0
if pattern and data:
for pattern, data in map(None, pattern, data):
#if dbg:
# print 'recursing'
same, vars = lenientMatch(pattern, data, vars, dbg=dbg)
if not same:
break
else:
found_match = same
return found_match, vars
|