summary refs log blame commit diff stats
path: root/HACKING
blob: 85f44ed684ac00ea299fbc75e9009cc8f68d84f0 (plain) (tree)


















                                                                          
                      

                                                                       
                                                            


















                                                            
                           

                              
                              



                                                                      


                                                                              








                                                             
Guidelines on Code Modification
===============================

Coding Style
------------

* Use syntax compatible to both python 2.6 and 3.1.
* Use docstrings with pydoc in mind
* Follow the style guide for python code:
    http://www.python.org/dev/peps/pep-0008/
* Although this guide suggests otherwise, tabs are used for indentation
    of code and docstrings.  In other documents (readme, etc), use spaces.


Patches
-------

Send patches, created with "git format-patch", to the email adress

    romanz@lavabit.com

If you plan to do major changes, or many changes over time, I encourage
you to create a fork on GitHub, Gitorious or any other site.


Common Changes
--------------

* Change which files are previewed in the auto preview:
In ranger/gui/widget/browsercolumn.py
the constant PREVIEW_BLACKLIST

* Adding options:
In ranger/defaults/options.py
add the default value, like: my_option = True
In ranger/shared/settings.py
add the name of your option to the constant ALLOWED_SETTINGS

The setting is now accessible at self.settings.my_option,
assuming <self> is a "SettingsAware" object.

* Change commands:
ranger/defaults/commands.py

* Create aliases for commands:
In ranger/defaults/commands.py
at the bottom, write something like: alias(exit=quit)

* Adding colorschemes:
Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py
and modify it according to your needs.  Alternatively, mimic the jungle
colorscheme.  It subclasses the default scheme and just modifies a few things.
In ranger/defaults/options.py (or ~/.ranger/options.py), change
    colorscheme = colorschemes.default
to: colorscheme = colorschemes.myscheme

* Change which files are considered to be "hidden":
In ranger/defaults/options.py
change the hidden_filter regular expression.

* Change the key map:
Modify ranger/defaults/keys.py.  This should be self-explanatory.
Check out ranger/core/actions.py for the most common actions, of course
you can also use your own functions.

* Change the file type => application associations:
In ranger/defaults/apps.py
modify the method app_default.
The variable "f" is a filesystem-object with attributes like mimetype,
extension, etc.  For a full list, check ranger/fsobject/fsobject.py

* Change the file extension => mime type associations:
Modify ranger/data/mime.types
and run ranger/data/generate.py to compile it.


Version Numbering
-----------------

X.Y.Z, where:

* X: Milestones
* Y: Stable versions
* Z: Experimental versions
span> screen, [add 1, 1] # contents of sandbox editor render-all screen, env, render # run it assume-console [ press F4 ] event-loop screen, console, env, resources screen-should-contain [ . run (F4) . . . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . . . . . ] # click at left edge of 'copy' button assume-console [ left-click 3, 19 ] run [ event-loop screen, console, env ] # it copies into editor screen-should-contain [ . run (F4) . .add 1, 1 . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . . . . . ] # cursor should be in the right place assume-console [ type [0] ] run [ event-loop screen, console, env, resources ] screen-should-contain [ . run (F4) . .0add 1, 1 . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . . . . . ] ] scenario copy-a-sandbox-to-editor-2 [ local-scope trace-until 50/app # trace too long assume-screen 50/width, 10/height # empty recipes assume-resources [ ] env:&:environment <- new-programming-environment resources, screen, [add 1, 1] # contents of sandbox editor render-all screen, env, render # run it assume-console [ press F4 ] event-loop screen, console, env, resources screen-should-contain [ . run (F4) . . . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . . . . . ] # click at right edge of 'copy' button (just before 'delete') assume-console [ left-click 3, 33 ] run [ event-loop screen, console, env, resources ] # it copies into editor screen-should-contain [ . run (F4) . .add 1, 1 . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . . . . . ] # cursor should be in the right place assume-console [ type [0] ] run [ event-loop screen, console, env, resources ] screen-should-contain [ . run (F4) . .0add 1, 1 . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . . . . . ] ] after <global-touch> [ # support 'copy' button { copy?:bool <- should-attempt-copy? click-row, click-column, env break-unless copy? copy?, env <- try-copy-sandbox click-row, env break-unless copy? screen <- render-sandbox-side screen, env, render screen <- update-cursor screen, current-sandbox, env loop +next-event } ] # some preconditions for attempting to copy a sandbox def should-attempt-copy? click-row:num, click-column:num, env:&:environment -> result:bool [ local-scope load-inputs # are we below the sandbox editor? click-sandbox-area?:bool <- click-on-sandbox-area? click-row, env return-unless click-sandbox-area?, false # narrower, is the click in the columns spanning the 'copy' button? first-sandbox:&:editor <- get *env, current-sandbox:offset assert first-sandbox, [!!] sandbox-left-margin:num <- get *first-sandbox, left:offset sandbox-right-margin:num <- get *first-sandbox, right:offset _, _, copy-button-left:num, copy-button-right:num, _ <- sandbox-menu-columns sandbox-left-margin, sandbox-right-margin copy-button-vertical-area?:bool <- within-range? click-column, copy-button-left, copy-button-right return-unless copy-button-vertical-area?, false # finally, is sandbox editor empty? current-sandbox:&:editor <- get *env, current-sandbox:offset result <- empty-editor? current-sandbox ] def try-copy-sandbox click-row:num, env:&:environment -> clicked-on-copy-button?:bool, env:&:environment [ local-scope load-inputs # identify the sandbox to copy, if the click was actually on the 'copy' button sandbox:&:sandbox <- find-sandbox env, click-row return-unless sandbox, false clicked-on-copy-button? <- copy true text:text <- get *sandbox, data:offset current-sandbox:&:editor <- get *env, current-sandbox:offset current-sandbox <- insert-text current-sandbox, text # reset scroll *env <- put *env, render-from:offset, -1 ] def find-sandbox env:&:environment, click-row:num -> result:&:sandbox [ local-scope load-inputs curr-sandbox:&:sandbox <- get *env, sandbox:offset { break-unless curr-sandbox start:num <- get *curr-sandbox, starting-row-on-screen:offset found?:bool <- equal click-row, start return-if found?, curr-sandbox curr-sandbox <- get *curr-sandbox, next-sandbox:offset loop } return null/not-found ] def click-on-sandbox-area? click-row:num, env:&:environment -> result:bool [ local-scope load-inputs first-sandbox:&:sandbox <- get *env, sandbox:offset return-unless first-sandbox, false first-sandbox-begins:num <- get *first-sandbox, starting-row-on-screen:offset result <- greater-or-equal click-row, first-sandbox-begins ] def empty-editor? editor:&:editor -> result:bool [ local-scope load-inputs head:&:duplex-list:char <- get *editor, data:offset first:&:duplex-list:char <- next head result <- not first ] def within-range? x:num, low:num, high:num -> result:bool [ local-scope load-inputs not-too-far-left?:bool <- greater-or-equal x, low not-too-far-right?:bool <- lesser-or-equal x, high result <- and not-too-far-left? not-too-far-right? ] scenario copy-fails-if-sandbox-editor-not-empty [ local-scope trace-until 50/app # trace too long assume-screen 50/width, 10/height # empty recipes assume-resources [ ] env:&:environment <- new-programming-environment resources, screen, [add 1, 1] # contents of sandbox editor render-all screen, env, render # run it assume-console [ press F4 ] event-loop screen, console, env, resources screen-should-contain [ . run (F4) . . . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . ] # type something into the sandbox editor, then click on the 'copy' button assume-console [ left-click 2, 20 # put cursor in sandbox editor type [0] # type something left-click 3, 20 # click 'copy' button ] run [ event-loop screen, console, env ] # copy doesn't happen screen-should-contain [ . run (F4) . .0 . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . ] # cursor should be in the right place assume-console [ type [1] ] run [ event-loop screen, console, env, resources ] screen-should-contain [ . run (F4) . .01 . .──────────────────────────────────────────────────. .0 edit copy delete . .add 1, 1 . .2 . .──────────────────────────────────────────────────. . . ] ]