Commits

Anonymous committed ac141c2

updated some of the restructuring docs

Comments (0)

Files changed (3)

 
   >>> from rope.refactor import restructure
 
-  >>> pattern = '${?pow_func}(${?param1}, ${?param2})'
-  >>> goal = '${?param1} ** ${?param2}'
+  >>> pattern = '${pow_func}(${param1}, ${param2})'
+  >>> goal = '${param1} ** ${param2}'
+  >>> args = {'pow_func': 'name=mod1.pow'}
 
-  >>> restructuring = restructure.Restructure(project, pattern, goal)
-  >>> checks = restructuring.make_checks({'?pow_func': 'mod1.pow'})
+  >>> restructuring = restructure.Restructure(project, pattern, goal, args)
 
-  >>> project.do(restructuring.get_changes(checks))
+  >>> project.do(restructuring.get_changes())
   >>> mod2.read()
   u'import mod1\nprint(2 ** 3)\n'
   

docs/overview.txt

 Now that we know ``**`` exists we want to use it wherever `pow` is
 used (there might be hundreds of them!).  We can use a pattern like::
 
-  pattern: pow(${?param1}, ${?param2})
+  pattern: pow(${param1}, ${param2})
 
 Goal can be some thing like::
 
-  goal: ${?param1} ** ${?param2}
+  goal: ${param1} ** ${param2}
 
-Note that ``${...}`` is used to match something in the pattern.  If
-names that appear in ``${...}`` start with a leading ``?`` every
-expression at that point will match, otherwise only the specified name
-will match (for instance ``${name}`` matches ``name``, ``x.name`` but
-not ``var`` or ``(1 + 2)`` while a ``${?name}`` can match all of
-them).
+Note that ``${...}`` can be used to match expressions.  By default
+every expression at that point will match.
 
 You can use the matched names in goal and they will be replaced with
 the string that was matched in each occurrence.  So the outcome of our
 
 It seems to be working but what if `pow` is imported in some module or
 we have some other function defined in some other module that uses the
-same name and we don't want to change it.  Checks come to rescue.
-Checks are mappings; Its keys are pattern names that appear in the
-pattern (the names in ``${...}``).  They might have a ``.object`` or
-``.type`` postfix.
+same name and we don't want to change it.  Wildcard arguments come to
+rescue.  As already seen, arguments are mappings; Its keys are
+wildcard names that appear in the pattern (the names inside
+``${...}``).
 
-The values should be resolved into a python variable (or reference).
+The values are the parameters that are passed to wildcard matchers.
+The default wildcard takes ``name``, ``object`` and ``type`` arguments
+for checking the reference/object/type of a wildcard.
+
+For checking the type of a wildcard, we can pass ``type=value`` as an
+arg; ``value`` should be resolved to a python variable (or reference).
 For instance for showing `pow` in this example we can use `mod.pow`.
-As you see this string should start from module names.  For
-referencing python builtin types and functions you can use
-`__builtin__` module (for instance `__builtin__.int`).
+As you see this string should start from module name.  For referencing
+python builtin types and functions you can use `__builtin__` module
+(for instance `__builtin__.int`).
 
 For solving the mentioned problem we change our `pattern`.  But `goal`
 remains the same::
 
-  pattern: ${?pow_func}(${?param1}, ${?param2})
-  goal: ${?param1} ** ${?param2}
+  pattern: ${pow_func}(${param1}, ${param2})
+  goal: ${param1} ** ${param2}
 
 Consider the name of the module containing our `pow` function is
-`mod`.  ``checks`` can be::
+`mod`.  ``args`` can be::
 
-  ?pow_func == mod.pow
+  pow_func: name=mod.pow
 
-Note that we could have used ``${pow}`` instead of ``${?pow_func}`` in
-our patterns.  The difference is that ``pow`` cannot handle aliases
-like::
+If we need to pass more arguments to a wildcard matcher we can use
+``,`` to separate them.  Such as ``name: type=mod.MyClass,exact``.
+
+This restructuring handles aliases; like in::
 
   mypow = pow
-  mypow(2, 3)
+  result = mypow(2, 3)
+
+Transforms into::
+
+  mypow = pow
+  result = 2 ** 3
+
+If we want to ignore aliases we can pass ``exact`` as another wildcard
+argument::
+
+  pattern: ${pow}(${param1}, ${param2})
+  goal: ${param1} ** ${param2}
+  args: pow: name=mod.pow, exact
+
+``${name}``, by default, matches every expression at that point; if
+``exact`` argument is passed to a wildcard only the specified name
+will match (for instance, if ``exact`` is specified , ``${name}``
+matches ``name`` and ``x.name`` but not ``var`` nor ``(1 + 2)`` while
+a normal ``${name}`` can match all of them).
 
 For performing this refactoring using rope library see `library.txt`_.
 
 just an example; consider inline refactoring is not implemented yet!).
 Restructurings come to rescue::
 
-  pattern: ${?inst}.f(${?p1}, ${?p2})
-  goal: ${?inst}.f1(${?p1})
-        ${?inst}.f2(${?p2})
+  pattern: ${inst}.f(${p1}, ${p2})
+  goal: ${inst}.f1(${p1})
+        ${inst}.f2(${p2})
   
-  checks: ?inst.type == mod.A
+  checks: inst: type=mod.A
 
 After performing we will have::
 
 
 We can perform a restructuring with these information::
 
-  pattern: ${?x}.set(${?y})
-  goal: ${?x} = ${?y}
+  pattern: ${x}.set(${y})
+  goal: ${x} = ${y}
 
-  checks: ?x.type == mod.A
+  checks: x: type=mod.A
 
 The names in checks as you see should be the name of a wild card
-pattern like ``?x`` or ``?y`` in the above example.  They can have a
+pattern like ``x`` or ``y`` in the above example.  They can have a
 ``.type`` or ``.object`` prefix if you want to match the type of the
 object or the type a name holds instead of the reference itself.  The
 values in checks are the representation of python references.  They

rope/refactor/wildcards.py

     for token in tokens:
         if '=' in token:
             parts = token.split('=', 1)
-            result[parts[0]] = parts[1]
+            result[parts[0].strip()] = parts[1].strip()
         else:
-            result[token] = True
+            result[token.strip()] = True
     return result