moved "doc/examples" to "examples" for more visibility

11 files changed, 221 insertions, 0 deletions

diff --git a/examples/README b/examples/README
new file mode 100644
index 00000000..ca514853
--- /dev/null
+++ b/examples/README
@@ -0,0 +1,8 @@
+The files in this directory contain applications or extensions of ranger which
+are put here for your inspiration and as references.
+
+In order to use a plugin from this directory, you need to copy it to
+~/.config/ranger/plugins/
+
+Note that if you update ranger to a new minor version (for example,
+from 1.6.* to 1.7.0), your outdated plugins WILL break and crash ranger.
diff --git a/examples/bash_automatic_cd.sh b/examples/bash_automatic_cd.sh
new file mode 100644
index 00000000..465c9c80
--- /dev/null
+++ b/examples/bash_automatic_cd.sh
@@ -0,0 +1,21 @@
+# Compatible with ranger 1.4.2 through 1.6.*
+#
+# Automatically change the directory in bash after closing ranger
+#
+# This is a bash function for .bashrc to automatically change the directory to
+# the last visited one after ranger quits.
+# To undo the effect of this function, you can type "cd -" to return to the
+# original directory.
+
+function ranger-cd {
+    tempfile="$(mktemp)"
+    /usr/bin/ranger --choosedir="$tempfile" "${@:-$(pwd)}"
+    test -f "$tempfile" &&
+    if [ "$(cat -- "$tempfile")" != "$(echo -n `pwd`)" ]; then
+        cd -- "$(cat "$tempfile")"
+    fi
+    rm -f -- "$tempfile"
+}
+
+# This binds Ctrl-O to ranger-cd:
+bind '"\C-o":"ranger-cd\C-m"'
diff --git a/examples/bash_subshell_notice.sh b/examples/bash_subshell_notice.sh
new file mode 100644
index 00000000..bc44d5a8
--- /dev/null
+++ b/examples/bash_subshell_notice.sh
@@ -0,0 +1,7 @@
+# Compatible with ranger 1.5.3 through 1.6.*
+#
+# Change the prompt when you open a shell from inside ranger
+#
+# Add this line to your .bashrc for it to work.
+
+[ -n "$RANGER_LEVEL" ] && PS1="$PS1"'(in ranger) '
diff --git a/examples/plugin_chmod_keybindings.py b/examples/plugin_chmod_keybindings.py
new file mode 100644
index 00000000..0ab975ed
--- /dev/null
+++ b/examples/plugin_chmod_keybindings.py
@@ -0,0 +1,20 @@
+# Compatible with ranger 1.6.*
+#
+# This plugin serves as an example for adding key bindings through a plugin.
+# It could replace the ten lines in the rc.conf that create the key bindings
+# for the "chmod" command.
+
+import ranger.api
+old_hook_init = ranger.api.hook_init
+
+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"
+    for mode in list('ugoa') + ['']:
+        for perm in "rwxXst":
+            fm.execute_console(command.format('-', mode, perm))
+            fm.execute_console(command.format('+', mode, perm))
+
+ranger.api.hook_init = hook_init
diff --git a/examples/plugin_file_filter.py b/examples/plugin_file_filter.py
new file mode 100644
index 00000000..b9bea1f3
--- /dev/null
+++ b/examples/plugin_file_filter.py
@@ -0,0 +1,21 @@
+# Compatible since ranger 1.6.1, git commit c82a8a76989c
+#
+# This plugin hides the directories "/boot", "/sbin", "/proc" and "/sys" unless
+# the "show_hidden" option is activated.
+
+# Save the original filter function
+import ranger.container.directory
+old_accept_file = ranger.container.directory.accept_file
+
+HIDE_FILES = ("/boot", "/sbin", "/proc", "/sys")
+
+# Define a new one
+def custom_accept_file(file, filters):
+    if not file.fm.settings.show_hidden and file.path in HIDE_FILES:
+        return False
+    else:
+        return old_accept_file(file, filters)
+
+# Overwrite the old function
+import ranger.container.directory
+ranger.container.directory.accept_file = custom_accept_file
diff --git a/examples/plugin_hello_world.py b/examples/plugin_hello_world.py
new file mode 100644
index 00000000..a803e21b
--- /dev/null
+++ b/examples/plugin_hello_world.py
@@ -0,0 +1,23 @@
+# Compatible with ranger 1.6.*
+#
+# This is a sample plugin that displays "Hello World" in ranger's console after
+# it started.
+
+# We are going to extend the hook "ranger.api.hook_ready", so first we need
+# to import ranger.api:
+import ranger.api
+
+# Save the previously existing hook, because maybe another module already
+# extended that hook and we don't want to lose it:
+old_hook_ready = ranger.api.hook_ready
+
+# Create a replacement for the hook that...
+def hook_ready(fm):
+    # ...does the desired action...
+    fm.notify("Hello World")
+    # ...and calls the saved hook.  If you don't care about the return value,
+    # simply return the return value of the previous hook to be safe.
+    return old_hook_ready(fm)
+
+# Finally, "monkey patch" the existing hook_ready function with our replacement:
+ranger.api.hook_ready = hook_ready
diff --git a/examples/plugin_new_macro.py b/examples/plugin_new_macro.py
new file mode 100644
index 00000000..159a92f2
--- /dev/null
+++ b/examples/plugin_new_macro.py
@@ -0,0 +1,19 @@
+# Compatible with ranger 1.6.*
+#
+# This plugin adds the new macro %date which is substituted with the current
+# date in commands that allow macros.  You can test it with the command
+# ":shell echo %date; read"
+
+# Save the original macro function
+import ranger.core.actions
+old_get_macros = ranger.core.actions.Actions._get_macros
+
+# Define a new macro function
+import time
+def get_macros_with_date(self):
+       macros = old_get_macros(self)
+       macros['date'] = time.strftime('%m/%d/%Y')
+       return macros
+
+# Overwrite the old one
+ranger.core.actions.Actions._get_macros = get_macros_with_date
diff --git a/examples/plugin_new_sorting_method.py b/examples/plugin_new_sorting_method.py
new file mode 100644
index 00000000..6b41b0e1
--- /dev/null
+++ b/examples/plugin_new_sorting_method.py
@@ -0,0 +1,9 @@
+# Compatible with ranger 1.6.*
+#
+# This plugin adds the sorting algorithm called 'random'.  To enable it, type
+# ":set sort=random" or create a key binding with ":map oz set sort=random"
+
+from ranger.container.directory import Directory
+from random import random
+Directory.sort_dict['random'] = lambda path: random()
+
diff --git a/examples/rifle_different_file_opener.conf b/examples/rifle_different_file_opener.conf
new file mode 100644
index 00000000..4a8250b8
--- /dev/null
+++ b/examples/rifle_different_file_opener.conf
@@ -0,0 +1,9 @@
+# Compatible with ranger 1.6.*
+#
+# Replace your rifle.conf with this file to use xdg-open as your file opener.
+# This is, of course, adaptable for use with any other file opener.
+else = xdg-open "$1"
+
+# You need an "editor" and "pager" in order to use certain functions in ranger:
+label editor = "$EDITOR" -- "$@"
+label pager  = "$PAGER" -- "$@"
diff --git a/examples/rifle_sxiv.sh b/examples/rifle_sxiv.sh
new file mode 100755
index 00000000..6307f1c2
--- /dev/null
+++ b/examples/rifle_sxiv.sh
@@ -0,0 +1,48 @@
+#!/bin/sh
+# Compatible with ranger 1.6.*
+#
+# This script searches image files in a directory, opens them all with sxiv and
+# sets the first argument to the first image displayed by sxiv.
+#
+# This is supposed to be used in rifle.conf as a workaround for the fact that
+# sxiv takes no file name arguments for the first image, just the number.  Copy
+# this file somewhere into your $PATH and add this at the top of rifle.conf:
+#
+#   mime ^image, has sxiv, X, flag f = path/to/this/script -- "$@"
+#
+# Implementation notes: this script is quite slow because of POSIX limitations
+# and portability concerns. First calling the shell function 'abspath' is
+# quicker than calling 'realpath' because it would fork a whole process, which
+# is slow. Second, we need to append a file list to sxiv, which can only be done
+# properly in two ways: arrays (which are not POSIX) or \0 sperated
+# strings. Unfortunately, assigning \0 to a variable is not POSIX either (will
+# not work in dash and others), so we cannot store the result of listfiles to a
+# variable.
+
+if [ $# -eq 0 ]; then
+    echo "Usage: ${0##*/} PICTURES"
+    exit
+fi
+
+[ "$1" == '--' ] && shift
+
+abspath () {
+    case "$1" in
+        /*) printf "%s\n" "$1";;
+        *)  printf "%s\n" "$PWD/$1";;
+    esac
+}
+
+listfiles () {
+    find -L "$(dirname "$target")" -maxdepth 1 -type f -iregex \
+      '.*\(jpe?g\|bmp\|png\|gif\)$' -print0 | sort -z
+}
+
+target="$(abspath "$1")"
+count="$(listfiles | grep -m 1 -ZznF "$target" | cut -d: -f1)"
+
+if [ -n "$count" ]; then
+    listfiles | xargs -0 sxiv -n "$count" --
+else
+    sxiv -- "$@" # fallback
+fi
diff --git a/examples/vim_file_chooser.vim b/examples/vim_file_chooser.vim
new file mode 100644
index 00000000..aa3af763
--- /dev/null
+++ b/examples/vim_file_chooser.vim
@@ -0,0 +1,36 @@
+" Compatible with ranger 1.4.2 through 1.6.*
+"
+" Add ranger as a file chooser in vim
+"
+" If you add this code to the .vimrc, ranger can be started using the command
+" ":RangerChooser" or the keybinding "<leader>r".  Once you select one or more
+" files, press enter and ranger will quit again and vim will open the selected
+" files.
+
+function! RangeChooser()
+    let temp = tempname()
+    " The option "--choosefiles" was added in ranger 1.5.1. Use the next line
+    " with ranger 1.4.2 through 1.5.0 instead.
+    "exec 'silent !ranger --choosefile=' . shellescape(temp)
+    exec 'silent !ranger --choosefiles=' . shellescape(temp)
+    if !filereadable(temp)
+        redraw!
+        " Nothing to read.
+        return
+    endif
+    let names = readfile(temp)
+    if empty(names)
+        redraw!
+        " Nothing to open.
+        return
+    endif
+    " Edit the first item.
+    exec 'edit ' . fnameescape(names[0])
+    " Add any remaning items to the arg list/buffer list.
+    for name in names[1:]
+        exec 'argadd ' . fnameescape(name)
+    endfor
+    redraw!
+endfunction
+command! -bar RangerChooser call RangeChooser()
+nnoremap <leader>r :<C-U>RangerChooser<CR>