diff options
| -rw-r--r-- | doc/ranger.1 | 117 | ||||
| -rw-r--r-- | doc/ranger.pod | 103 | ||||
| -rw-r--r-- | examples/plugin_chmod_keybindings.py | 10 | ||||
| -rw-r--r-- | ranger/api/__init__.py | 28 | ||||
| -rw-r--r-- | ranger/core/fm.py | 9 | ||||
| -rw-r--r-- | ranger/core/main.py | 3 |
6 files changed, 183 insertions, 87 deletions
diff --git a/doc/ranger.1 b/doc/ranger.1 index 0e56551d..1bbcd349 100644 --- a/doc/ranger.1 +++ b/doc/ranger.1 @@ -124,7 +124,7 @@ .\" ======================================================================== .\" .IX Title "RANGER 1" -.TH RANGER 1 "ranger-1.5.5" "12/02/2012" "ranger manual" +.TH RANGER 1 "ranger-1.5.5" "12/03/2012" "ranger manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -185,7 +185,7 @@ Open ranger with \fItargetfile\fR selected. .IX Item "--copy-config=file" Create copies of the default configuration files in your local configuration directory. Existing ones will not be overwritten. Possible values: \fIall\fR, -\&\fIrc\fR, \fIapps\fR, \fIcommands\fR, \fIoptions\fR, \fIscope\fR. +\&\fIrc\fR, \fIcommands\fR, \fIscope\fR. .IP "\fB\-\-list\-unused\-keys\fR" 14 .IX Item "--list-unused-keys" List common keys which are not bound to any action in the \*(L"browser\*(R" context. @@ -220,6 +220,8 @@ Print the version and exit. Print a list of options and exit. .SH "CONCEPTS" .IX Header "CONCEPTS" +This part explains how certain parts of ranger work and how they can be used +efficiently. .SS "\s-1TAGS\s0" .IX Subsection "TAGS" Tags are single characters which are displayed left of a filename. You can use @@ -272,7 +274,7 @@ are in different directories: .Ve .PP Macros for file paths are generally shell-escaped so they can be used in the -:shell command. +\&\f(CW\*(C`shell\*(C'\fR command. .SS "\s-1BOOKMARKS\s0" .IX Subsection "BOOKMARKS" Type \fBm<key>\fR to bookmark the current directory. You can re-enter this @@ -285,40 +287,78 @@ to the last directory. So typing \*(L"``\*(R" gets you back to where you were be Bookmarks are selectable when tabbing in the :cd command. .PP Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same. +.SS "\s-1RIFLE\s0" +.IX Subsection "RIFLE" +Rifle is the file opener of ranger. It can be used as a standalone program or +a python module. It is located at \fIranger/ext/rifle.py\fR. In contrast to +other, more simple file openers, rifle can automatically find installed +programs so it can be used effectively out of the box on a variety of systems. +.PP +It's configured in \fIrifle.conf\fR through a list of conditions and commands. +For each line the conditions are checked and if they are met, the respective +command is taken into consideration. By default, simply the first matching +rule is used. In ranger, you can list and choose rules by typing \*(L"r\*(R" or simply +by typing \*(L"<rulenumber><enter>\*(R". If you use rifle standalone, you can list all +rules with the \*(L"\-l\*(R" option and pick a rule with \*(L"\-p <number>\*(R". +.PP +The rules, along with further documentation, are contained in +\&\fIranger/config/rifle.conf\fR. .SS "\s-1FLAGS\s0" .IX Subsection "FLAGS" Flags give you a way to modify the behavior of the spawned process. They are -used in the commands :open_with (key \*(L"r\*(R") and :shell (key \*(L"!\*(R"). +used in the commands \f(CW\*(C`:open_with\*(C'\fR (key \*(L"r\*(R") and \f(CW\*(C`:shell\*(C'\fR (key \*(L"!\*(R"). .PP -.Vb 7 -\& s Silent mode. Output will be discarded. -\& d Detach the process. (Run in background) -\& p Redirect output to the pager -\& w Wait for an Enter\-press when the process is done +.Vb 4 +\& f Fork the process. (Run in background) \& c Run the current file only, instead of the selection \& r Run application with root privilege (requires sudo) \& t Run application in a new terminal window .Ve .PP -By default, all the flags are off unless specified otherwise in the \fIapps.py\fR -configuration file. You can specify as many flags as you want. An uppercase -flag negates the effect: \*(L"ddcccDs\*(R" is equivalent to \*(L"cs\*(R". -.PP -The \*(L"t\*(R" flag looks for the environment variable \s-1TERMCMD\s0, and uses it as the -terminal command, if it's not set it'll use xterm. -.PP -Examples: \f(CW\*(C`:open_with p\*(C'\fR will pipe the output of that process into -the pager. \f(CW\*(C`:shell \-w df\*(C'\fR will run \*(L"df\*(R" and wait for you to press Enter before -switching back to ranger. -.SS "\s-1MODES\s0" -.IX Subsection "MODES" -By specifying a mode (a positive integer), you can tell ranger what to do with -a file when running it. You can specify which mode to use by typing <mode>l or -<mode><Enter> or :open_with <mode>. The default mode is 0. -.PP -Examples: \f(CW\*(C`l\*(C'\fR (mode zero) to list the contents of an archive, \f(CW\*(C`1l\*(C'\fR (mode one) -to extract an archive. See the \fIapps.py\fR configuration file for all programs -and modes. +There are some additional flags that can currently be used only in the \f(CW\*(C`shell\*(C'\fR +command: (for example \f(CW\*(C`:shell \-w df\*(C'\fR) +.PP +.Vb 3 +\& p Redirect output to the pager +\& s Silent mode. Output will be discarded. +\& w Wait for an Enter\-press when the process is done +.Ve +.PP +By default, all the flags are off unless specified otherwise in the +\&\fIrifle.conf\fR configuration file. You can specify as many flags as you want. +An uppercase flag negates the effect: \*(L"ffcccFsf\*(R" is equivalent to \*(L"cs\*(R". +.PP +The terminal program name for the \*(L"t\*(R" flag is taken from the environment +variable \f(CW$TERMCMD\fR. If it doesn't exist, it tries to extract it from \f(CW$TERM\fR and +uses \*(L"xterm\*(R" as a fallback if that fails. +.PP +Examples: \f(CW\*(C`:open_with c\*(C'\fR will open the file that you currently point at, even +if you have selected other files. \f(CW\*(C`:shell \-w df\*(C'\fR will run \*(L"df\*(R" and wait for +you to press Enter before switching back to ranger. +.SS "\s-1PLUGINS\s0" +.IX Subsection "PLUGINS" +ranger's plugin system consists of python files which are located in +\&\fI~/.config/ranger/plugins/\fR and are imported in alphabetical order when +starting ranger. A plugin changes rangers behavior by overwriting or extending +a function that ranger uses. This allows you to change pretty much every part +of ranger, but there is no guarantee that things will continue to work in +future versions as the source code evolves. +.PP +There are some hooks that are specifically made for the use in plugins. They +are functions that start with hook_ and can be found throughout the code. +.PP +.Vb 1 +\& grep \*(Aqdef hook_\*(Aq \-r /path/to/rangers/source +.Ve +.PP +Also try: +.PP +.Vb 1 +\& pydoc ranger.api +.Ve +.PP +The \fIexamples\fR directory contains several sample plugins, including a well +documented hello-world plugin using hooks in a compatibility-friendly way. .SH "KEY BINDINGS" .IX Header "KEY BINDINGS" Key bindings are defined in the file \fIranger/config/rc.conf\fR. Check this @@ -472,8 +512,8 @@ directory, by clicking on the preview. Enter a directory or run a file. .IP "Scroll Wheel" 4 .IX Item "Scroll Wheel" -Scrolls up or down. You can point at the column of the parent directory to -switch directories. +Scrolls up or down. You can point at the column of the parent directory while +scrolling to switch directories. .SH "SETTINGS" .IX Header "SETTINGS" This section lists all built-in settings of ranger. The valid types for the @@ -897,24 +937,23 @@ When starting ranger with the \fB\-\-clean\fR option, it will not access or crea any of these files. .SS "\s-1CONFIGURATION\s0" .IX Subsection "CONFIGURATION" -.IP "commands.py" 10 -.IX Item "commands.py" -A python module that defines commands which can be used in ranger's console by -typing \*(L":\*(R". .IP "rc.conf" 10 .IX Item "rc.conf" Contains a list of commands which are executed on startup. Mostly key bindings and settings are defined here. +.IP "commands.py" 10 +.IX Item "commands.py" +A python module that defines commands which can be used in ranger's console by +typing \*(L":\*(R" or in the rc.conf file. .IP "rifle.conf" 10 .IX Item "rifle.conf" This is the configuration file for the built-in file launcher called \*(L"rifle\*(R". .IP "scope.sh" 10 .IX Item "scope.sh" This is a script that handles file previews. When the options -\&\fIuse_preview_script\fR and \fIpreview_files\fR or, respectively, -\&\fIpreview_directories\fR are set, the program specified in the option -\&\fIpreview_script\fR is run and its output and/or exit code determines rangers -reaction. +\&\fIuse_preview_script\fR and \fIpreview_files\fR are set, the program specified in +the option \fIpreview_script\fR is run and its output and/or exit code determines +rangers reaction. .IP "colorschemes/" 10 .IX Item "colorschemes/" Colorschemes can be placed here. @@ -949,7 +988,7 @@ with T. To assign a named tag, type "<tagname>. These environment variables have an effect on ranger: .IP "\s-1RANGER_LEVEL\s0" 8 .IX Item "RANGER_LEVEL" -Ranger sets this environment variable to \*(L"1\*(R" or increments it if it already +ranger sets this environment variable to \*(L"1\*(R" or increments it if it already exists. External programs can determine whether they were spawned from ranger by checking for this variable. .IP "\s-1EDITOR\s0" 8 diff --git a/doc/ranger.pod b/doc/ranger.pod index 6903c030..219d2f0b 100644 --- a/doc/ranger.pod +++ b/doc/ranger.pod @@ -75,7 +75,7 @@ Open ranger with I<targetfile> selected. Create copies of the default configuration files in your local configuration directory. Existing ones will not be overwritten. Possible values: I<all>, -I<rc>, I<apps>, I<commands>, I<options>, I<scope>. +I<rc>, I<commands>, I<scope>. =item B<--list-unused-keys> @@ -124,6 +124,9 @@ Print a list of options and exit. =head1 CONCEPTS +This part explains how certain parts of ranger work and how they can be used +efficiently. + =head2 TAGS Tags are single characters which are displayed left of a filename. You can use @@ -175,7 +178,7 @@ are in different directories: @diff %c %f Macros for file paths are generally shell-escaped so they can be used in the -:shell command. +C<shell> command. =head2 BOOKMARKS @@ -190,39 +193,72 @@ Bookmarks are selectable when tabbing in the :cd command. Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same. +=head2 RIFLE + +Rifle is the file opener of ranger. It can be used as a standalone program or +a python module. It is located at F<ranger/ext/rifle.py>. In contrast to +other, more simple file openers, rifle can automatically find installed +programs so it can be used effectively out of the box on a variety of systems. + +It's configured in F<rifle.conf> through a list of conditions and commands. +For each line the conditions are checked and if they are met, the respective +command is taken into consideration. By default, simply the first matching +rule is used. In ranger, you can list and choose rules by typing "r" or simply +by typing "<rulenumber><enter>". If you use rifle standalone, you can list all +rules with the "-l" option and pick a rule with "-p <number>". + +The rules, along with further documentation, are contained in +F<ranger/config/rifle.conf>. + =head2 FLAGS Flags give you a way to modify the behavior of the spawned process. They are -used in the commands :open_with (key "r") and :shell (key "!"). +used in the commands C<:open_with> (key "r") and C<:shell> (key "!"). - s Silent mode. Output will be discarded. - d Detach the process. (Run in background) - p Redirect output to the pager - w Wait for an Enter-press when the process is done + f Fork the process. (Run in background) c Run the current file only, instead of the selection r Run application with root privilege (requires sudo) t Run application in a new terminal window -By default, all the flags are off unless specified otherwise in the F<apps.py> -configuration file. You can specify as many flags as you want. An uppercase -flag negates the effect: "ddcccDs" is equivalent to "cs". +There are some additional flags that can currently be used only in the C<shell> +command: (for example C<:shell -w df>) + + p Redirect output to the pager + s Silent mode. Output will be discarded. + w Wait for an Enter-press when the process is done + +By default, all the flags are off unless specified otherwise in the +F<rifle.conf> configuration file. You can specify as many flags as you want. +An uppercase flag negates the effect: "ffcccFsf" is equivalent to "cs". -The "t" flag looks for the environment variable TERMCMD, and uses it as the -terminal command, if it's not set it'll use xterm. +The terminal program name for the "t" flag is taken from the environment +variable $TERMCMD. If it doesn't exist, it tries to extract it from $TERM and +uses "xterm" as a fallback if that fails. -Examples: C<:open_with p> will pipe the output of that process into -the pager. C<:shell -w df> will run "df" and wait for you to press Enter before -switching back to ranger. +Examples: C<:open_with c> will open the file that you currently point at, even +if you have selected other files. C<:shell -w df> will run "df" and wait for +you to press Enter before switching back to ranger. -=head2 MODES +=head2 PLUGINS -By specifying a mode (a positive integer), you can tell ranger what to do with -a file when running it. You can specify which mode to use by typing <mode>l or -<mode><Enter> or :open_with <mode>. The default mode is 0. +ranger's plugin system consists of python files which are located in +F<~/.config/ranger/plugins/> and are imported in alphabetical order when +starting ranger. A plugin changes rangers behavior by overwriting or extending +a function that ranger uses. This allows you to change pretty much every part +of ranger, but there is no guarantee that things will continue to work in +future versions as the source code evolves. -Examples: C<l> (mode zero) to list the contents of an archive, C<1l> (mode one) -to extract an archive. See the F<apps.py> configuration file for all programs -and modes. +There are some hooks that are specifically made for the use in plugins. They +are functions that start with hook_ and can be found throughout the code. + + grep 'def hook_' -r /path/to/rangers/source + +Also try: + + pydoc ranger.api + +The F<examples> directory contains several sample plugins, including a well +documented hello-world plugin using hooks in a compatibility-friendly way. @@ -443,8 +479,8 @@ Enter a directory or run a file. =item Scroll Wheel -Scrolls up or down. You can point at the column of the parent directory to -switch directories. +Scrolls up or down. You can point at the column of the parent directory while +scrolling to switch directories. =back @@ -956,16 +992,16 @@ any of these files. =over 10 -=item commands.py - -A python module that defines commands which can be used in ranger's console by -typing ":". - =item rc.conf Contains a list of commands which are executed on startup. Mostly key bindings and settings are defined here. +=item commands.py + +A python module that defines commands which can be used in ranger's console by +typing ":" or in the rc.conf file. + =item rifle.conf This is the configuration file for the built-in file launcher called "rifle". @@ -973,10 +1009,9 @@ This is the configuration file for the built-in file launcher called "rifle". =item scope.sh This is a script that handles file previews. When the options -I<use_preview_script> and I<preview_files> or, respectively, -I<preview_directories> are set, the program specified in the option -I<preview_script> is run and its output and/or exit code determines rangers -reaction. +I<use_preview_script> and I<preview_files> are set, the program specified in +the option I<preview_script> is run and its output and/or exit code determines +rangers reaction. =item colorschemes/ @@ -1030,7 +1065,7 @@ These environment variables have an effect on ranger: =item RANGER_LEVEL -Ranger sets this environment variable to "1" or increments it if it already +ranger sets this environment variable to "1" or increments it if it already exists. External programs can determine whether they were spawned from ranger by checking for this variable. diff --git a/examples/plugin_chmod_keybindings.py b/examples/plugin_chmod_keybindings.py index c04cc492..62ca6c58 100644 --- a/examples/plugin_chmod_keybindings.py +++ b/examples/plugin_chmod_keybindings.py @@ -2,11 +2,11 @@ # It could replace the ten lines in the rc.conf that create the key bindings # for the "chmod" command. -import ranger.core.fm -old_init_hook = ranger.core.fm.init_hook +import ranger.api +old_hook_init = ranger.api.hook_init -def init_hook(fm): - old_init_hook(fm) +def hook_init(fm): + old_hook_init(fm) # Generate key bindings for the chmod command command = "map {0}{1}{2} shell -d chmod {1}{0}{2} %s" @@ -15,4 +15,4 @@ def init_hook(fm): fm.execute_console(command.format('-', mode, perm)) fm.execute_console(command.format('+', mode, perm)) -ranger.core.fm.init_hook = init_hook +ranger.api.hook_init = hook_init diff --git a/ranger/api/__init__.py b/ranger/api/__init__.py index cc64a7c0..1121197a 100644 --- a/ranger/api/__init__.py +++ b/ranger/api/__init__.py @@ -1,4 +1,28 @@ """ -Files in this module contain helper functions used in -configuration files. +Files in this module contain helper functions used in configuration files. """ + +# Hooks for use in plugins: + +def hook_init(fm): + """ + Parameters: + fm = the file manager instance + Return Value: + ignored + + This hook is executed after fm is initialized but before fm.ui is + initialized. You can safely print to stdout and have access to fm to add + keybindings and such. + """ + +def hook_ready(fm): + """ + Parameters: + fm = the file manager instance + Return Value: + ignored + + This hook is executed after the user interface is initialized. You should + NOT print anything to stdout anymore from here on. Use fm.notify instead. + """ diff --git a/ranger/core/fm.py b/ranger/core/fm.py index b32e5730..3c100532 100644 --- a/ranger/core/fm.py +++ b/ranger/core/fm.py @@ -14,7 +14,7 @@ import socket import stat import sys -import ranger +import ranger.api from ranger.core.actions import Actions from ranger.core.tab import Tab from ranger.container.tags import Tags @@ -28,9 +28,6 @@ from ranger.ext.signals import SignalDispatcher from ranger import __version__ from ranger.core.loader import Loader -def init_hook(): - pass - class FM(Actions, SignalDispatcher): input_blocked = False input_blocked_until = 0 @@ -126,8 +123,6 @@ class FM(Actions, SignalDispatcher): self.notify(text, bad=True) self.run = Runner(ui=self.ui, logfunc=mylogfunc, fm=self) - init_hook() - def destroy(self): debug = ranger.arg.debug if self.ui: @@ -250,6 +245,8 @@ class FM(Actions, SignalDispatcher): has_throbber = hasattr(ui, 'throbber') zombies = self.run.zombies + ranger.api.hook_ready(self) + try: while True: loader.work() diff --git a/ranger/core/main.py b/ranger/core/main.py index df2a922e..dd07bff8 100644 --- a/ranger/core/main.py +++ b/ranger/core/main.py @@ -13,7 +13,7 @@ load_default_config = True def main(): """initialize objects and run the filemanager""" import locale - import ranger + import ranger.api from ranger.core.shared import FileManagerAware, SettingsAware from ranger.core.fm import FM @@ -115,6 +115,7 @@ def main(): # Run the file manager fm.initialize() + ranger.api.hook_init(fm) fm.ui.initialize() if arg.cmd: |