#!/usr/bin/env python  """ Fix name-related operations. The code in this module operates upon simplified program node trees.  Copyright (C) 2006 Paul Boddie <paul@boddie.org.uk>  This software is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.  This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.  You should have received a copy of the GNU General Public License along with this library; see the file LICENCE.txt If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA  --------  To use this module, the easiest approach is to use the fix function:  fix(module)  The more complicated approach involves instantiating a Fixer object:  fixer = Fixer()  Then, applying the fixer to an existing module:  fixer.process(module)  If a module containing built-in classes and functions exists, apply the fixer as follows:  fixer.process(module, builtins) """  from simplified import *  # Fixing of name-related operations.  class Fixer(Visitor):      """     The name fixer which traverses the program nodes in a module, typically     depth-first, and maintains a record of name usage in the different     namespaces. As a consequence of various observations, some parts of the     program node tree are modified with different operations employed to those     originally defined.      There are two kinds of subprograms in modules: functions/methods and     internal subprograms which support things like loops. The latter kind of     subprogram may acquire the locals from their callers and must therefore be     traversed with information from such callers. Thus, we choose the top-level     code and all functions/methods as roots for processing, following     invocations of internal subprograms in order to reach all subprograms that     are defined in each module.      top-level         ...         invoke function         ...         invoke loop -> subprogram (internal)                            ...      subprogram (function)         ...         invoke loop -> subprogram (internal)                            ...      ...      The above approach should guarantee that all subprograms are traversed and     that all name lookups are correctly categorised.     """      def __init__(self):          "Initialise the name fixer."          Visitor.__init__(self)          # Satisfy visitor issues.          self.visitor = self      def process(self, module, builtins=None):          """         Process the given 'module' optionally using some 'builtins' to reference         built-in objects.         """          # The fixer maintains a list of transformed subprograms (added for each         # of the processing "roots" and also for each invoked internal         # subprogram), along with a list of current subprograms (used to avoid         # recursion issues) and a list of current namespaces (used to recall         # namespaces upon invoking internal subprograms).          self.subprograms = []         self.current_subprograms = []         self.current_namespaces = []          # First, process the top-level code, finding out which names are         # defined at that level.          self.global_namespace = None         self.module = module         self.builtins = builtins or module          self.process_node(self.module)          # Then, process all functions and methods, providing a global namespace.         # By setting a global namespace, we influence the resolution of names:         # those which are global to the top-level module (processed above) are         # considered as built-in names, whereas those which are global to a         # function or method are searched for in the global namespace.          self.global_namespace = self.namespace          for subprogram in self.module.simplifier.subprograms:              # Internal subprograms are skipped here and processed specially via             # Invoke nodes.              if not getattr(subprogram, "internal", 0):                 self.subprograms.append(self.process_node(subprogram))          # Ultimately, we redefine the list of subprograms on the visitor.          self.module.simplifier.subprograms = self.subprograms         return self.module      def process_node(self, node, namespace=None):          """         Process a subprogram or module 'node', discovering from attributes on         'node' any initial locals. Return a modified subprogram or module.         """          # Do not process subprograms already being processed.          if node in self.current_subprograms:             return None          # Obtain a namespace either based on locals or on a structure.          structure = structure=getattr(node, "structure", None)         self.namespace = NameOrganiser(structure)          # Record the current subprogram and namespace.          self.current_subprograms.append(node)         self.current_namespaces.append(self.namespace)          # If passed some namespace, merge its contents into this namespace.          if namespace is not None:             self.namespace.merge_namespace(namespace)          # NOTE: Avoid PEP 227 (nested scopes) whilst permitting references to a         # NOTE: subprogram within itself. Do not define the name of the function         # NOTE: within a method definition.          if isinstance(node, Subprogram) and getattr(node, "name", None) is not None and not getattr(node, "is_method", 0):             self.namespace.store(node.name)          # Register the names of parameters in the namespace.          if hasattr(node, "params"):             new_params = []             for param, default in node.params:                 new_params.append((param, self.dispatch(default)))                 self.namespace.store(param)             node.params = new_params         if getattr(node, "star", None):             param, default = node.star             self.namespace.store(param)             node.star = param, self.dispatch(default)         if getattr(node, "dstar", None):             param, default = node.dstar             self.namespace.store(param)             node.dstar = param, self.dispatch(default)          # Add namespace details to any structure involved.          if hasattr(node, "structure") and node.structure is not None:              # Initialise bases where appropriate.              if hasattr(node.structure, "bases"):                 bases = []                 for base in node.structure.bases:                     bases.append(self.dispatch(base))                 node.structure.bases = bases          # Dispatch to the code itself.          result = self.dispatch(node)         result.organiser = self.namespace          # Restore the previous subprogram and namespace.          self.current_namespaces.pop()         if self.current_namespaces:             self.namespace = self.current_namespaces[-1]         self.current_subprograms.pop()          return result      # Visitor methods.      def default(self, node):          """         Process the given 'node', given that it does not have a specific         handler.         """          for attr in ("pos_args",):             value = getattr(node, attr, None)             if value is not None:                 setattr(node, attr, self.dispatches(value))         for attr in ("kw_args",):             value = getattr(node, attr, None)             if value is not None:                 setattr(node, attr, self.dispatch_dict(value))         for attr in ("expr", "lvalue", "test", "star", "dstar"):             value = getattr(node, attr, None)             if value is not None:                 setattr(node, attr, self.dispatch(value))         for attr in ("body", "else_", "handler", "finally_", "code", "choices"):             value = getattr(node, attr, None)             if value is not None:                 setattr(node, attr, self.dispatches(value))         return node      def dispatch(self, node, *args):         return Visitor.dispatch(self, node, *args)      def visitGlobal(self, global_):         for name in global_.names:             self.namespace.make_global(name)         return global_      def visitLoadName(self, loadname):          "Transform the 'loadname' node to a specific, scope-sensitive node."          scope = self.namespace.find_for_load(loadname.name)          # For structure namespaces, load an attribute.          if scope == "structure":             result = self.dispatch(                 LoadAttr(loadname.original, loadname.defining,                     expr=LoadRef(loadname.original,                         ref=self.namespace.structure),                     name=loadname.name,                     nstype="structure")                 )          # For global accesses (ie. those outside the local namespace)...          elif scope == "global":              # Where a distinct global namespace exists, examine it.              if self.global_namespace is not None:                 scope = self.global_namespace.find_for_load(loadname.name)                  # Where the name is outside the global namespace, it must be a                 # built-in.                  if scope == "global":                     result = self.dispatch(                         LoadAttr(loadname.original, loadname.defining,                             expr=LoadRef(loadname.original,                                 ref=self.builtins),                             name=loadname.name,                             nstype="module")                         )                  # Otherwise, it is within the global namespace and must be a                 # global.                  else:                     result = self.dispatch(                         LoadAttr(loadname.original, loadname.defining,                             expr=LoadRef(loadname.original,                                 ref=self.module),                             name=loadname.name,                             nstype="module")                         )              # Where no global namespace exists, we are at the module level and             # must be accessing a built-in.              else:                 result = self.dispatch(                     LoadAttr(loadname.original, loadname.defining,                         expr=LoadRef(loadname.original,                             ref=self.builtins),                         name=loadname.name,                         nstype="module")                     )          # For local accesses...          else:              # Where a distinct global namespace exists, it must be a local.              if self.global_namespace is not None:                 result = loadname              # Otherwise, we must be accessing a global (which is local at the             # module level).              else:                 result = self.dispatch(                     LoadAttr(loadname.original, loadname.defining,                         expr=LoadRef(loadname.original,                             ref=self.module),                         name=loadname.name,                         nstype="module")                     )          return result      def visitStoreName(self, storename):          "Transform the 'storename' node to a specific, scope-sensitive node."          scope = self.namespace.find_for_store(storename.name)          # For structure namespaces, store an attribute.          if scope == "structure":             self.namespace.store(storename.name)              return self.dispatch(                 StoreAttr(storename.original, storename.defining,                     lvalue=LoadRef(storename.original,                         ref=self.namespace.structure),                     name=storename.name,                     expr=storename.expr,                     nstype="structure")                 )          # Where the name is outside the local namespace, disallow any built-in         # assignment and store the name globally.          elif scope == "global":             return self.dispatch(                 StoreAttr(storename.original, storename.defining,                     lvalue=LoadRef(storename.original,                         ref=self.module),                     name=storename.name,                     expr=storename.expr,                     nstype="module")                 )          # For local namespace accesses...          else:             self.namespace.store(storename.name)              # If a distinct global namespace exists, it must be a local access.              if self.global_namespace is not None:                 return storename              # Otherwise, the name is being set at the module level and is             # considered global.              else:                 return self.dispatch(                     StoreAttr(storename.original, storename.defining,                         lvalue=LoadRef(storename.original,                             ref=self.module),                         name=storename.name,                         expr=storename.expr,                         nstype="module")                     )      def visitInvokeFunction(self, invoke):          "Transform the 'invoke' node, performing processing on subprograms."          return self.default(invoke)      def visitInvokeBlock(self, invoke):          "Transform the 'invoke' node, performing processing on subprograms."          # The special case of internal subprogram invocation is addressed by         # propagating namespace information to the subprogram and processing it.          subprogram = self.process_node(invoke.expr.ref, self.namespace)         if subprogram is not None:             self.subprograms.append(subprogram)         return invoke  class ScopeMismatch(Exception):     pass  class NameOrganiser:      """     A local namespace which may either relate to a genuine set of function     locals or the initialisation of a structure.     """      def __init__(self, structure=None):          "Initialise the namespace with an optional 'structure'."          self.structure = structure         if structure is not None:             self.local = "structure"         else:             self.local = "local"          # Names may be self.local or "global".          self.names = {}      def make_global(self, name):         if not self.names.has_key(name):             self.names[name] = "global"         elif self.names[name] == self.local:             raise ScopeMismatch, "Name '%s' already considered as %s." % (name, self.local)      def find_for_load(self, name):         return self.names.get(name, "global")      def find_for_store(self, name):         return self.names.get(name, self.local)      def store(self, name):         if self.names.get(name) != "global":             self.names[name] = self.local         else:             raise ScopeMismatch, "Name '%s' already considered as global." % name      def merge(self, name, scope):         if self.names.get(name) in (None, scope):             self.names[name] = scope         else:             raise ScopeMismatch, "Name '%s' already considered as %s." % (name, self.names[name])      def merge_namespace(self, namespace):         self.merge_items(namespace.names.items())      def merge_items(self, items):         for name, scope in items:             self.merge(name, scope)      def __repr__(self):         return repr(self.names)  # Convenience functions.  def fix(module, builtins=None):      """     Fix the names in the given 'module', also employing the optional 'builtins'     module, if specified.     """      fixer = Fixer()     if builtins is not None:         fixer.process(module, builtins)     else:         fixer.process(module)  # vim: tabstop=4 expandtab shiftwidth=4