Source

ropemacs / README.txt

Ali Gholami Rudi 3e6d774 



Ali Gholami Rudi 21bb0b3 

Ali Gholami Rudi df95cd6 
Ali Gholami Rudi 0fec651 

Ali Gholami Rudi 7a65aec 
Ali Gholami Rudi c25ffb4 

Ali Gholami Rudi c7e1bce 


Ali Gholami Rudi 019a727 


















Ali Gholami Rudi bb0a4c0 
Ali Gholami Rudi c25ffb4 


Ali Gholami Rudi 86b9df0 
Ali Gholami Rudi c25ffb4 
Ali Gholami Rudi 93d3a6a 
Ali Gholami Rudi bd76aa6 
Ali Gholami Rudi c25ffb4 
Ali Gholami Rudi 8a157c5 




Ali Gholami Rudi cf914f1 
Ali Gholami Rudi 92f9696 
Ali Gholami Rudi 8a157c5 
Ali Gholami Rudi 0596e42 





Ali Gholami Rudi df95cd6 
Ali Gholami Rudi 408afe1 
Ali Gholami Rudi 0596e42 
Ali Gholami Rudi 8a157c5 
Ali Gholami Rudi 0596e42 
Ali Gholami Rudi 8a157c5 







Ali Gholami Rudi df95cd6 
Ali Gholami Rudi 0596e42 
Ali Gholami Rudi df95cd6 
Ali Gholami Rudi 7a65aec 

Ali Gholami Rudi a944b7d 
Ali Gholami Rudi 0596e42 
Ali Gholami Rudi 914ba8a 










Ali Gholami Rudi 98e80a1 

Ali Gholami Rudi 8a157c5 
Ali Gholami Rudi 98e80a1 





Ali Gholami Rudi 8a157c5 

Ali Gholami Rudi 0596e42 


Ali Gholami Rudi 52eb73a 


Ali Gholami Rudi 0596e42 

Ali Gholami Rudi 408afe1 


Ali Gholami Rudi 0596e42 


Ali Gholami Rudi df95cd6 

Ali Gholami Rudi 0596e42 

Ali Gholami Rudi df95cd6 



Ali Gholami Rudi 0596e42 


Ali Gholami Rudi c25ffb4 
Ali Gholami Rudi 4779a1b 







Ali Gholami Rudi abd8020 


Ali Gholami Rudi 4779a1b 

Ali Gholami Rudi 107e15b 


Ali Gholami Rudi 638e68b 
Ali Gholami Rudi efdaa40 



Ali Gholami Rudi 107e15b 
Ali Gholami Rudi 8a157c5 
Ali Gholami Rudi 638e68b 


Ali Gholami Rudi efdaa40 


















Ali Gholami Rudi e69566b 


Ali Gholami Rudi efdaa40 
Ali Gholami Rudi 107e15b 

Ali Gholami Rudi 0193528 



Ali Gholami Rudi 9fb32fb 


Ali Gholami Rudi 0193528 

Ali Gholami Rudi 638e68b 

Ali Gholami Rudi 107e15b 
Ali Gholami Rudi af64e98 



Ali Gholami Rudi 8a157c5 
Ali Gholami Rudi 638e68b 
Ali Gholami Rudi af64e98 



















Ali Gholami Rudi 71052b6 
Ali Gholami Rudi af64e98 
Ali Gholami Rudi 71052b6 
Ali Gholami Rudi af64e98 



Ali Gholami Rudi 71052b6 


Ali Gholami Rudi af64e98 
Ali Gholami Rudi 15489ae 

Ali Gholami Rudi 638e68b 


Ali Gholami Rudi af64e98 
Ali Gholami Rudi 15489ae 


Ali Gholami Rudi 71052b6 
Ali Gholami Rudi 15489ae 
Ali Gholami Rudi 71052b6 
Ali Gholami Rudi 15489ae 
Ali Gholami Rudi 0cd1cbd 
Ali Gholami Rudi 71052b6 

Ali Gholami Rudi 15489ae 
Ali Gholami Rudi af64e98 
Ali Gholami Rudi 52eb73a 



































































Ali Gholami Rudi 9e61e60 

Ali Gholami Rudi 52eb73a 








Ali Gholami Rudi ed16a87 
Ali Gholami Rudi 52eb73a 
Ali Gholami Rudi ed16a87 
Ali Gholami Rudi 52eb73a 


Ali Gholami Rudi 437aa89 

Ali Gholami Rudi c25ffb4 
Ali Gholami Rudi 74229c3 


Ali Gholami Rudi 5698224 
Ali Gholami Rudi 7c10849 





Ali Gholami Rudi 838906b 
Ali Gholami Rudi bbde358 

Ali Gholami Rudi 7c10849 

Ali Gholami Rudi 0981726 
Ali Gholami Rudi 5698224 
Ali Gholami Rudi 7c10849 





Ali Gholami Rudi 203bff6 
Ali Gholami Rudi 8a157c5 
Ali Gholami Rudi 7c10849 


Ali Gholami Rudi 5698224 
Ali Gholami Rudi 7c10849 


Ali Gholami Rudi ed16a87 




Ali Gholami Rudi 8acbcd1 

Ali Gholami Rudi 2ddc567 
Ali Gholami Rudi 0981726 


Ali Gholami Rudi 8aad57d 

Ali Gholami Rudi ec75198 










Ali Gholami Rudi 8aad57d 



Ali Gholami Rudi 7c10849 
Ali Gholami Rudi ec75198 
Ali Gholami Rudi 7c10849 
Ali Gholami Rudi 8aad57d 


Ali Gholami Rudi 0596e42 

Ali Gholami Rudi cf7cd18 

Ali Gholami Rudi 0fec651 
Ali Gholami Rudi cf7cd18 

Ali Gholami Rudi 0fec651 
Ali Gholami Rudi cf7cd18 

Ali Gholami Rudi 0fec651 
Ali Gholami Rudi 86b9df0 



  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
=========================
 ropemacs, rope in emacs
=========================

Ropemacs is an emacs mode that uses rope_ library to provide features
like refactorings and code-assists.  You should install rope_ library
and pymacs_ before using ropemacs.

.. _`rope`: http://rope.sf.net/
.. _pymacs: http://pymacs.progiciels-bpi.ca/pymacs.html


New Features
============

Changes since 0.5c6:

* added rope-jump-to-global
* added ropemacs-completing-read-function variable
* better error reporting

Some of the changes since 0.4:

* added ropemacs menu
* added ropemacs minor mode
* filtering refactoring resources
* added introduce method object refactoring
* added auto-import support
* added support for introduce factory refactoring
* added use function refactoring
* added rope-jump-to-global command
* added rope-show-call-doc command
* added rope-find-file-other-window command


Setting Up
==========

After installing pymacs, add these lines to your ``~/.emacs`` file::

  (require 'pymacs)
  (pymacs-load "ropemacs" "rope-")

Note that rope and ropemacs should be in your ``PYTHONPATH`` for this
to work.

Loading Lazily
--------------

If you want to load ropemacs only when you really need it, you can use
a function like this in your ``~/.emacs``::

  (defun load-ropemacs ()
    "Load pymacs and ropemacs"
    (interactive)
    (require 'pymacs)
    (pymacs-load "ropemacs" "rope-")
    ;; Automatically save project python buffers before refactorings
    (setq ropemacs-confirm-saving 'nil)
  )
  (global-set-key "\C-xpl" 'load-ropemacs)

And execute ``load-ropemacs`` (or use ``C-x p l``) whenever you want
to use ropemacs.


Not Installing
--------------

If you don't want to install rope library and ropemacs you can extract
them somewhere and add these lines to your ``.emacs``::

  ;; Add this before loading pymacs if you haven't installed rope and ropemacs
  (setq pymacs-load-path '("/path/to/rope"
                           "/path/to/ropemacs"))


Multiple Python Versions
------------------------

Rope needs at least Python2.5.  If you have older versions of Python
you can use ``PYMACS_PYTHON`` environment variable.  You can add::

  (setenv "PYMACS_PYTHON" "python2.5")

to force pymacs to use Python2.5.


Ropemacs Minor Mode
-------------------

Rope registers its local keys when ``ropemacs-mode`` is enabled.  By
default it is enabled using ``python-mode`` hook (this hook is
available if you are using Emacs' ``python.el`` or XEmacs'
``python-mode.el``).  If you want to enable it in other major modes
either execute ``ropemacs-mode`` manually or call it in some other
hook.


Getting Started
===============

Refactoring Dialog
------------------

Rope refactorings use a special kind of dialog.  When you start a
refactoring, you'll be asked to confirm saving modified python
buffers; you can change it by using ``ropemacs-confirm-saving``
variable.  Adding ``(setq ropemacs-confirm-saving 'nil)`` to your
``.emacs`` file, will make emacs save them without asking.

After that depending on the refactoring, you'll be asked about the
essential information a refactoring needs to know (like the new name
in rename refactoring).  You can skip it by prefixing the refactoring;
this can be useful when using batchset command (described later).

Next you'll see the base prompt of a refactoring dialog that shows
something like "Choose what to do".  By entering the name of a
refactoring option you can set its value.  After setting each option
you'll be returned back to the base prompt.  Finally, you can ask rope
to perform, preview or cancel the refactoring.

See keybinding_ section and try the refactorings yourself.


Finding Files
-------------

By using ``rope-find-file`` (``C-x p f`` by default), you can search
for files in your project.  When you complete the minibuffer you'll
see all files in the project; files are shown as their reversed paths.
For instance ``projectroot/docs/todo.txt`` is shown like
``todo.txt<docs``.  This way you can find files faster in your
project.  ``rope-find-file-other-window`` (``C-x p 4 f``) opens the
file in the other window.  With prefix, these commands show python
files only.


Code-Assist
-----------

``rope-code-assist`` command (``M-/`` by default) will let you select
from a list of completions.  If prefixed (``C-u M-/``), ropemacs
inserts the common prefix, automatically.  If a numeric argument is
given, rope will insert the common prefix for that many of the first
proposals.

``rope-lucky-assist`` command (``M-?``) does not ask anything;
instead, it inserts the first proposal.  By prefixing it, you can
choose which proposal to insert.  ``C-u 1 M-?`` uses the second
propsal, for instance.

Here::

  xxaa = None
  xxab = None
  xxba = None
  xxbb = None

  x^

consider cursor is at ``^`` position.  This table shows what happens
when code-assist commands are used:

============  ==========  =======================
Key           Inserts     Minibuffer Completions
============  ==========  =======================
M-/                       xxaa, xxab, xxba, xxbb
C-u M-/       x           xxaa, xxab, xxba, xxbb
C-u 2 M-/     xa          xxaa, xxab
M-?           xaa
C-u 1 M-/     xab
C-u 3 M-/     xbb
============  ==========  =======================


Finding Occurrences
-------------------

The find occurrences command (``C-c f`` by default) can be used to
find the occurrences of a python name.  If ``unsure`` option is
``yes``, it will also show unsure occurrences; unsure occurrences are
indicated with a ``?`` mark in the end.


Dialog ``batchset`` Command
---------------------------

When you use rope dialogs there is a command called ``batchset``.  It
can be used to set many configs at the same time.  After selecting
this command from dialog base prompt, you are asked to enter a string.

``batchset`` strings can set the value of configs in two ways.  The
single line form is like this::

  name1 value1
  name2 value2

That is the name of config is followed its value.  For multi-line
values you can use::

  name1
   line1
   line2

  name2
   line3

Each line of the definition should start with a space or a tab.  Note
that blank lines before the name of config definitions are ignored.

``batchset`` command is useful when performing refactorings with long
configs, like restructurings::

  pattern ${pycore}.create_module(${project}.root, ${name})

  goal generate.create_module(${project}, ${name})

  imports
   from rope.contrib import generate

  args
   pycore: type=rope.base.pycore.PyCore
   project: type=rope.base.project.Project

.. ignore the two-space indents

This is a valid ``batchset`` string for restructurings.  When using
batchset, you usually want to skip initial questions.  That can be
done by prefixing refactorings.

Just for the sake of completeness, the reverse of the above
restructuring can be::

  pattern ${create_module}(${project}, ${name})

  goal ${project}.pycore.create_module(${project}.root, ${name})

  args
   create_module: name=rope.contrib.generate.create_module
   project: type=rope.base.project.Project


Enabling Autoimport
-------------------

Rope can propose and automatically import global names in other
modules.  But this feature disabled by default.  Before using it, you
should add::

  (setq ropemacs-enable-autoimport 't)

to your ``~/.emacs`` file.  After enabling, rope maintains a cache of
global names for each project.  It updates the cache only when modules
are changed; if you want to cache all your modules at once, use
``rope-generate-autoimport-cache``.  It will cache all of the modules
inside the project plus those whose names are listed in
``ropemacs-autoimport-modules`` list::

  # add the name of modules you want to autoimport
  (setq ropemacs-autoimport-modules '("os" "shutil"))

Now if you are in a buffer that contains::

  rmtree

and you execute ``ropemacs-auto-import`` you'll end up with::

  from shutil import rmtree
  rmtree

Also ``rope-code-assist`` and ``rope-lucky-assist`` propose
auto-imported names by using ``name : module`` style.  Selecting them
will import the module automatically.


Filtering Resources
-------------------

Some refactorings, restructuring and find occurrences take an option
called resources.  This option can be used to limit the resources on
which a refactoring should be applied.

It uses a simple format: each line starts with either '+' or '-'.
Each '+' means include the file (or its children if it's a folder)
that comes after it.  '-' has the same meaning for exclusion.  So
using::

  +rope
  +ropetest
  -rope/contrib

means include all python files inside ``rope`` and ``ropetest``
folders and their subfolder, but those that are in ``rope/contrib``.
Or::

  -ropetest
  -setup.py

means include all python files inside the project but ``setup.py`` and
those under ``ropetest`` folder.


Variables
---------

* ``ropemacs-confirm-saving``: If non-nil, you have to confirm saving all
  modified python files before refactorings; otherwise they are saved
  automatically. Defaults to ``t``.
* ``ropemacs-codeassist-maxfixes``: The maximum number of syntax errors
  to fix for code assists.  The default value is ``1``.
* ``ropemacs-separate-doc-buffer``: Should ``rope-show-doc`` use a
  separate buffer or the minibuffer.  Defaults to ``t``.

* ``ropemacs-local-prefix``: The prefix for ropemacs refactorings.
  Defaults to ``C-c r``.
* ``ropemacs-global-prefix``: The prefix for ropemacs project commands
  Defaults to ``C-x p``.
* ``ropemacs-enable-shortcuts``: Shows whether to bind ropemacs
  shortcuts keys.  Defaults to ``t``.

* ``ropemacs-enable-autoimport``: Shows whether to enable autoimport.
  Defaults to ``nil``.
* ``ropemacs-autoimport-modules``: The name of modules whose global
  names should be cached.  `rope-generate-autoimport-cache' reads
  this list and fills its cache.


Keybinding
----------

Uses almost the same keybinding as ropeide.  Note that global commands
have a ``C-x p`` prefix and commands have a ``C-c r`` prefix.  You can
change that (see variables_ section).

================  ============================
Key               Command
================  ============================
C-x p o           rope-open-project
C-x p k           rope-close-project
C-x p f           rope-find-file
C-x p 4 f         rope-find-file-other_window
C-x p u           rope-undo
C-x p r           rope-redo
C-x p c           rope-project-config
C-x p n [mpfd]    rope-create-(module|package|file|directory)
                  rope-write-project

C-c r r           rope-rename
C-c r l           rope-extract-variable
C-c r m           rope-extract-method
C-c r i           rope-inline
C-c r v           rope-move
C-c r x           rope-restructure
C-c r u           rope-use-function
C-c r f           rope-introduce-factory
C-c r 1 r         rope-rename-current-module
C-c r 1 v         rope-move-current-module
C-c r 1 p         rope-module-to-package

C-c r o           rope-organize-imports
C-c r n [vfcmp]   rope-generate-(variable|function|class|module|package)

C-c r a /         rope-code-assist
C-c r a g         rope-goto-definition
C-c r a d         rope-show-doc
C-c r a f         rope-find-occurrences
C-c r a ?         rope-lucky-assist
C-c r a j         rope-jump-to-global
C-c r a c         rope-show-call-doc
                  rope-analyze-module

                  rope-auto-import
                  rope-generate-autoimport-cache
===============   ============================


Shortcuts
---------

Some commands are used very frequently; specially the commands in
code-assist group.  You can define your own shortcuts like this::

  (define-key ropemacs-local-keymap "\C-cg" 'rope-goto-definition)

Rope itself comes with a few shortcuts.  These shortcuts will be used
only when ropemacs-enable-shortcuts is non-nil.

================  ============================
Key               Command
================  ============================
M-/               rope-code-assist
M-?               rope-lucky-assist
C-c g             rope-goto-definition
C-c d             rope-show-doc
C-c f             rope-find-occurrences
================  ============================


Contributing
============

Send your bug reports, feature requests and patches to `rope-dev (at)
googlegroups.com`_.

.. _`rope-dev (at) googlegroups.com`: http://groups.google.com/group/rope-dev


License
=======

This program is under the terms of GPL (GNU General Public License).
Have a look at ``COPYING`` file for more information.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.