[Pydev-cvs] org.python.pydev/PySrc/ThirdParty/brm README,NONE,1.1 DESIGN.html,NONE,1.1 ChangeLog,NON
Brought to you by:
fabioz
Menu
▾
▴
[Pydev-cvs] org.python.pydev/PySrc/ThirdParty/brm README,NONE,1.1 DESIGN.html,NONE,1.1 ChangeLog,NONE,1.1 AUTHORS,NONE,1.1 COPYING,NONE,1.1 __init__.py,NONE,1.1 NEWS,NONE,1.1
|
From: Fabio Z. <fa...@us...> - 2004-09-14 17:42:27
|
Update of /cvsroot/pydev/org.python.pydev/PySrc/ThirdParty/brm In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv9579/PySrc/ThirdParty/brm Added Files: README DESIGN.html ChangeLog AUTHORS COPYING __init__.py NEWS Log Message: Code completion improvements. Starting refactoring integration with bicycle repair man. --- NEW FILE: DESIGN.html --- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Bicyclerepairman Design</title> </head> <body> <h1>Bicyclerepairman Design</h1> This information is correct at 27th Jan 2004. <h2> Bike Component Interface </h2> <pre> import bike ctx = bike.init() ctx.renameByCoordinates("/home/joe/src/foo/bah.py",52,8,"bah") ctx.save() ctx.undo() </pre> <h2>File System Dependency:</h2> Bicyclerepair man operates off of the file system. Modules are loaded from the file system, and saved back after a refactoring. Integration with IDEs currently relies on the IDE ensuring that the files on disk are up-to-date before performing a query or refactoring, and is responsible for reloading the modified files after the operation. <!-- <h2>Example: - findDefinition</h2> Client code calls findDefinition via the context object in bikefacade.py. The client passes in a filename and coordinates of a reference she wants to find the definition of. The bikefacade module sets a search path (based on PYTHONPATH and the position of the file in a package hierarchy) and then calls the findDefinition module in the query package. The findDefinition module loads the file into a Module object via the getModule() call in the parsing package. --> <h2>Parsing and Fastparsing - the <em>parser</em> package</h2> <p> BRM originally did all its parsing using the Python compiler package (see python docs). This parser generates very accurate AST. Unfortunately this proved to be far too slow for interactive use, and so I built a seperate parser which does a basic job of parsing, but very fast. BRM uses this basic parser to locate and navigate round the code, and then applies the compiler package to small bits of code where necessary. </p> <p> The fastparser module in the parsing package operates on a single module at a time. It generates a simple tree containing Class and Function nodes, with a Module node at the root. This tree is called the 'fastparserast', and it's nodes (Module,Class,Function) are defined in the fastparserast module. Each fastparserast node contains a pointer to the start and end lines of the node in the source text, and basic information (e.g. name). It also contains methods for navigating between nodes (e.g. getChildNodes(), getParent() </p> <h3>BRM Tricks - masking the code</h3> <p> The fastparser is very fast because it leverages the power of the regex package, and has been carefully profiled and optimised. Before parsing a file it applies a number of regexes over the source to mask out all the comments and strings. This then allows it to scan the source very quickly for functions and classes using python keywords ('class', 'def') without fear of getting confused by occurences of keywords in strings. It builds up a tree of functions and classes in a module, storing their start and end positions (lines) in the source text. </p> <h3> BRM Tricks2 - logical lines and doctored lines</h3> <p> As mentioned above, the compiler module is very accurate but very slow. Because of this, BRM uses it sparingly, choosing only to parse lines of code when it is reasonably confident that the line contains something important. </p> <p> In order to parse a single line of source code, the line must sometimes be doctored to make it parsable. Take for example the following: <pre> def foo(a, b, c): </pre> This line cannot be parsed on its own, but may contain some interesting code. BRM overcomes this constraint via the makeLineParseable() function in the parserutils module. This function decorates the line with noops that make it parsable. For the above example it generates the following code: <pre> def foo(a, b, c): pass </pre> Which parses fine. </p> <p> The other problem with parsing single lines of code is that python statements often span multiple lines. e.g. <pre> myref = foo(arg1, arg2, arg3, arg4) </pre> To combat this problem, BRM has a neat function called generateLogicalLines() (also on the parserutils module). This function takes a list of (masked) physical lines as input, and generates complete 'logical' lines as output. <h2>Querying the code - The <em>query</em> Package</h2> <p> As mentioned above, the relative slow speed of the compiler module prohibits BRM from building up an AST of the entire file and then navigating it. Instead the query package uses text searches to narrow down the search and then parses single 'logical lines' using the compiler. </p> <h3>logical lines and doctored lines</h3> <p> In order to parse a single line of source code, the line must sometimes be doctored to make it parsable. Take for example the following: <pre> a = myfunc(arg1, arg2, arg3, arg4) </pre> <pre> def foo(a, b, c): </pre> The first problem is multiline lines. </p> <h3>Example - findDefinition</h3> <p> For example, when searching for the definition of a reference (see findDefinition.py), BRM first takes the input coordinates and locates the fastparserast node denoting the class/function scope containing the reference (by checking the coords against the start/end coords of the fastparserast nodes). This provides the initial search scope for the query. </p> <p> BRM then obtains the sourcecode of the scope with strings/comments masked out. It searches </p> <p> </p> <p> </p> <p> </p> <hr> <address><a href="mailto:pd...@us...">Phil Dawes</a></address> <!-- Created: Mon Jan 26 17:43:32 GMT 2004 --> <!-- hhmts start --> Last modified: Mon Jan 26 18:40:51 GMT 2004 <!-- hhmts end --> </body> </html> --- NEW FILE: COPYING --- COPYRIGHT AND PERMISSION NOTICE Copyright (c) 2000 by Shae Erisson <sh...@la...> Copyright (c) 2001 by Phil Dawes <pd...@us...> All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR 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. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. --- NEW FILE: ChangeLog --- 2004-02-11 Phil Dawes <pd...@us...> * bike/query/getTypeOf.py: rewrote resolveImportedModuleOrPackage to use purely getModuleOrPackageUsingFQN searches. (doesnt use getTypeOf Root searching any more) * bike/query/common.py: rewrote getLogicalLine to handle multilines that parse seperately. (But was submitted by Peter Astrand) 2004-02-10 Phil Dawes <pd...@us...> * bike/query/getTypeOf.py: Added functionality to search from the current directory if looking for an import and scope is a module 2004-02-10 Phil Dawes <pd...@us...> * bike/refactor/moveToModule.py: Added handling of individual 'from a.foo import theFunction'. [...1989 lines suppressed...] 2000-09-01 18:22 jhermann * README: Additions by shae 2000-08-19 01:35 eris * README: new dir structure by snibril aka Jürgen Herrman first stab at a tree matcher in common.py 2000-08-01 01:44 jhermann * README: Added a readme dummy --- NEW FILE: README --- Bicycle Repair Man - a Python Refactoring Browser ================================================= Copyright (c) 2000 by Shae Erisson <sh...@la...> Copyright (c) 2001-3 by Phil Dawes <pd...@us...> All rights reserved, see COPYING for details. $Id: README,v 1.7 2003/08/24 19:48:43 pdawes Exp $ ----------------------------------------------------------------------------- Bicycle Repair Man is the Python Refactoring Browser, helping Pythonistas everywhere glide over the gory details of refactoring their code. Watch him extract jumbled code into well ordered classes. Gasp, as he renames all occurrences of a method. Thank You, Bicycle Repair Man! execute ./testall.py to run all the tests see INSTALL for installation instructions (uses distutils). see README.idle, README.emacs etc.. for instructions on how to integrate bicyclerepairman into supported IDEs. ----------------------------------------------------------------------------- What's Python? Python is a programming language. To find out more about it, go to the Python Homepage at http://www.python.org/ What's a Refactoring Browser? A Refactoring Browser is an editor that automates Refactorings. The first Refactoring Browser was written by Dr. Don Roberts and Dr. John Brant at the University of Illinois in Urbana-Champagne. Dr. Don Roberts wrote his Ph.D. thesis on the design and implementation of the Refactoring Browser. For more detail, read the aforementioned thesis at http://st-www.cs.uiuc.edu/~droberts/thesis.pdf What's a Refactoring? A Refactoring is a behaviour preserving change to source code. Some Refactorings are RenameVariable, RenameClass, RenameMethod, PullUpMethod, and PushDownVariable. Lots of people say it's very easy to just type a different name in where your class, method, or variable is defined. That's not always a refactoring though. The Refactoring Browser is smart enough to rename every reference to your class, method or variable. If you've ever renamed a variable and broken classes in widely scattered parts of your system, you might be happier using a Refactoring Browser. A Refactoring Browser operates on any of method, function, class, or variable. It can add, delete, rename, move up down or sideways, inline and abstract. There are some operations that are specific to one of the three types, such as abstracting a variable into accessors, or turing several lines of code into a separate method. For more information on Refactoring, check out the websites of Martin Fowler at http://www.martinfowler.com/ and his Refactoring Site at http://www.refactoring.com/ . Why Bicycle Repair Man? The Bicycle Repair Man was a superhero in a Monty Python skit, his special power was repairing bicycles. --- NEW FILE: NEWS --- Main highlights of each new version. See ChangeLog for a more detailed description of changes. Version 0.9 ----------- This version removes the requirement to load files into bicyclerepairman before refactoring. Instead, it searches the PYTHONPATH (and the path in which the file being queried is in). This allows 'findDefinition' queries to be made on references (e.g. classes, methods) where the definition is in the python library. Version 0.8 ----------- This release improves on the internal type-deduction engine to handle variables and attributes. To reflect this, 'rename' now works on variables and attributes, in addition to methods, functions and classes. This release also adds vim support (thanks to Marius Gedminas and Matt Yeates for this) Version 0.7 ----------- This release includes a totally re-written type querying engine, which is much faster and paves the way for new refactorings. It also adds the 'FindReferences' and 'FindDefinition' query to emacs and idle. Version 0.6 ----------- This release adds undo functionality to the mix, and beefs up the idle and emacs integration so that code is automatically imported into brm when you load a file into a buffer. Version 0.5 ----------- This release adds the ExtractMethod refactoring Version 0.4 ----------- This release adds support for IDLE (see README.idle), and fixes a few bugs. The CLI and GUI interfaces are now deprecated and have been removed from this release. Version 0.3 ----------- This release adds the RenameClass and RenameFunction refactorings. It also contains the initial xemacs integration functionality (see README.xemacs). Version 0.2 ----------- This release adds a simple GUI for renaming methods - run bikegui.py after installation. There's also some upgrades to pyxmi. It should now be able to generate xmi to model all generalizations (including cross-package ones). N.B. pyxmi.py is now called py2xmi.py. See changelog for reasons! Version 0.1 ----------- This is the first release of Bicycle Repair Man. It requires python version 2.2 and above. This version supports a partial implementation of the RenameMethod refactoring through a command line interface. It automatically renames the method and references to the method that it can deduce. It asks you about method references it can't deduce the instance type of. This software should be considered alpha, and may damage your source files - backup your sources before use! See INSTALL for installation and usage instructions. N.B. This package also contains pyxmi - a little python -> xmi tool I cobbled together out of the bicycle repair man parsing package. It generates an xmi file out of a source-file or package-structure, suitable for loading into the argouml tool. See http://argouml.tigris.org. --- NEW FILE: AUTHORS --- Authors ------- Phil Dawes <pd...@us...> - Current Maintainer and Main Author Shae Erisson <sh...@la...> - Original Maintainer The following people have contributed code, bugfixes and patches: Jürgen Hermann <jh...@we...> Canis Lupus Syver Enstad <syv...@on...> Windows emacs patches Mathew Yeates <ma...@co...> VIM support and bug fixes Marius Gedminas <mg...@de...> More VIM support François Pinard <pi...@ir...> Pymacs + help with emacs integration Ender <en...@ob...> Jonathan <jon...@in...> Steve <the...@ya...> Peter Astrand <pe...@ce...> See ChangeLog for more details. --- NEW FILE: __init__.py --- |
