README


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

Ranger v.1.0.4
==============

Ranger

   A keeper, guardian, or soldier who ranges over a region
   to protect the area or enforce the law.

This is the filemanager Chuck Norris the Texas Ranger would use
if he had a computer with a unix-like operating system.  (He doesn't
trust computers though and prefers to do the calculations himself.)

After all, as a professional ranger, he needs a broad overview of his
territory, and the multi-column display of ranger provides just that,
rather than restricting you to the current directory only.
You can preview the content of the selected file or directory, copy or move
files around with the VIM-like commands dd and yy, execute predefined
applications when opening a file, etc...

Everything is fully customizable and written in Python (2.6 and 3.1
compatible) using curses for the text-based user interface.


About
-----

* Author:          Roman Zimbelmann
* Email:           romanz@lavabit.com
* Website:         http://savannah.nongnu.org/projects/ranger
* Git repo:        http://git.savannah.gnu.org/cgit/ranger.git
* Version:         1.0.4


Features
--------

* Multi-column display
* Preview of the selected file/directory
* Common file operations (create/chmod/copy/delete/...)
* Quickly find files or text inside files
* VIM-like console and hotkeys
* Open files in external programs
* Mouse support
* Change the directory of your shell after exiting ranger
* Bookmarks


Dependencies
------------

* A Unix-like Operating System
* Python 2.6 or 3.1
* Python curses module  (often but not always included with Python)


Bugs and Feature Requests
-------------------------

Report bugs and feature requests on savannah:
    https://savannah.nongnu.org/bugs/?func=additem&group=ranger

Alternatively you can send an email to romanz@lavabit.com.

Please include as much relevant information as possible.
Using ranger with the --debug option will abort the program and
print tracebacks rather than a red message in the statusbar.
If this applies to you, please include such a traceback in your report.


Getting Started
---------------

If you just want to check out ranger without installing it, type

    ./ranger.py --clean

in the top directory of ranger.  By using the --clean switch, it will
leave no trace on your system whatsoever.

To properly install it, follow the instructions in the INSTALL file,
then type:

    ranger

You should see 4 columns.  The third is the directory where you are at
the moment.  To the left, there are the directories above the current
working directory, and the column on the right is a preview of the selected
file/directory.

Now use the arrow keys to navigate, press enter to open a file.

A list of commands with short descriptions can be viewed by
pressing "?" inside the program and following the instructions.
The file ranger/defaults/keys.py contains all key combinations, so that's
another place you may want to check out.


Opening Files with Ranger
-------------------------

If you use the same applications like me, you'll be able to open
files by pressing the right arrow key.  If not, you will have to
specify them in ranger/defaults/apps.py.  It's explained
in the docstrings how exactly to do that.

Once you've set up your applications, you can also use ranger to
open files from the shell:
    ranger blabla.pdf


Customizing Ranger
------------------

The file ranger/defaults/options.py contains most of the options.
apps.py defines how files are run, keys.py defines keybindings.

The files in ranger/defaults/ can be copied into ~/.ranger/ for per-user
modifications.  Colorschemes can be placed in ~/.ranger/colorschemes.

The configuration files should be self-explanatory.  If you need more
information, check out the source code.

Also, see the file HACKING for more detailed instructions on
modifying the program.


Tips
----

Change the directory of your parent shell when you exit ranger:

ranger() {
    $(which ranger) $@ &&
    cd "$(grep \^\' ~/.ranger/bookmarks | cut -b3-)"
}

This can be put into your ~/.bashrc or something similar.
#!/bin/sh
# Build and test all included Mu and SubX programs on Linux:
#   translate them into ELF binaries
#   if possible, compare the generated binaries with what's already in git
#   run/test the ELF binaries in emulated mode
#   run/test the ELF binaries in native mode
#
# Example usage:
#   test_apps
#   test_apps record  # don't compare with what's in git

set -e
cd `dirname $0`

echo "== translating using the bootstrap C++ translator"

# example programs

echo ex1
bootstrap/bootstrap translate 000init.subx ex1.subx  -o ex1
{
  bootstrap/bootstrap run ex1  ||  ret=$?
  test $ret -eq 42  # life, the universe and everything
}
{
  chmod +x ex1
  ./ex1  ||  ret=$?
  test $ret -eq 42  # life, the universe and everything
}

echo ex2
bootstrap/bootstrap translate 000init.subx ex2.subx  -o ex2
{
  bootstrap/bootstrap run ex2  ||  ret=$?
  test $ret -eq 7  # 3 + 4
}
{
  chmod +x ex2
  ./ex2  ||  ret=$?
  test $ret -eq 7  # 3 + 4
}

echo ex3
bootstrap/bootstrap translate 000init.subx ex3.subx  -o ex3
{
  bootstrap/bootstrap run ex3  ||  ret=$?
  test $ret -eq 55  # 1 + 2 + ... + 10
}
{
  chmod +x ex3
  ./ex3  ||  ret=$?
  test $ret -eq 55  # 1 + 2 + ... + 10
}

echo ex4
bootstrap/bootstrap translate 000init.subx ex4.subx  -o ex4
{
  echo a | bootstrap/bootstrap run ex4 >ex4.out  ||  true
  test `cat ex4.out` = 'a'
}
{
  chmod +x ex4
  echo a | ./ex4 >ex4.out  ||  true
  test `cat ex4.out` = 'a'
}

echo ex5
bootstrap/bootstrap translate 000init.subx ex5.subx  -o ex5
{
  echo a | bootstrap/bootstrap run ex5 >ex5.out  ||  true
  test `cat ex5.out` = 'a'
}
{
  chmod +x ex5
  echo a | ./ex5 >ex5.out  ||  true
  test `cat ex5.out` = 'a'
}

echo ex6
bootstrap/bootstrap translate 000init.subx ex6.subx  -o ex6
{
  bootstrap/bootstrap run ex6 >ex6.out  ||  true
  test "`cat ex6.out`" = 'Hello world!'
}
{
  chmod +x ex6
  ./ex6 >ex6.out  ||  true
  test "`cat ex6.out`" = 'Hello world!'
}

echo ex7
bootstrap/bootstrap translate 000init.subx ex7.subx  -o ex7
{
  bootstrap/bootstrap run ex7  ||  ret=$?
  test $ret -eq 97  # 'a'
}
{
  chmod +x ex7
  ./ex7  ||  ret=$?
  test $ret -eq 97  # 'a'
}

echo ex8
bootstrap/bootstrap translate 000init.subx ex8.subx  -o ex8
{
  bootstrap/bootstrap run ex8 abcd  ||  ret=$?
  test $ret -eq 4  # length('abcd')
}
{
  chmod +x ex8
  ./ex8 abcd  ||  ret=$?
  test $ret -eq 4  # length('abcd')
}

echo ex9
bootstrap/bootstrap translate 000init.subx ex9.subx  -o ex9
{
  bootstrap/bootstrap run ex9 z x  ||  ret=$?
  test $ret -eq 2  # 'z' - 'x'
}
{
  chmod +x ex9
  ./ex9 z x  ||  ret=$?
  test $ret -eq 2  # 'z' - 'x'
}

echo ex10
bootstrap/bootstrap translate 000init.subx ex10.subx  -o ex10
{
  bootstrap/bootstrap run ex10 abc abc  ||  ret=$?
  test $ret -eq 1  # equal
  bootstrap/bootstrap run ex10 abc abcd  # 0; not equal
}
{
  chmod +x ex10
  ./ex10 abc abc  ||  ret=$?
  test $ret -eq 1  # equal
  ./ex10 abc abcd  # 0; not equal
}

echo ex11
bootstrap/bootstrap translate 000init.subx ex11.subx  -o ex11
{
  bootstrap/bootstrap run ex11
  echo
}
{
  chmod +x ex11
  ./ex11
  echo
}

echo ex12
bootstrap/bootstrap translate 000init.subx ex12.subx  -o ex12
bootstrap/bootstrap run ex12  # final byte of mmap'd address is well-nigh guaranteed to be 0
chmod +x ex12
./ex12

echo ex13
bootstrap/bootstrap translate 000init.subx ex13.subx  -o ex13
{
  bootstrap/bootstrap run ex13  ||  ret=$?
  test $ret -eq 1  # 3 == 3
}
{
  chmod +x ex13
  ./ex13  ||  ret=$?
  test $ret -eq 1  # 3 == 3
}

# Larger apps that use the standard library.

echo factorial
bootstrap/bootstrap translate [01]*.subx factorial.subx  -o factorial
{
  bootstrap/bootstrap run factorial  ||  ret=$?
  test $ret -eq 120  # factorial(5)
  bootstrap/bootstrap run factorial test
  echo
}
{
  chmod +x factorial
  ./factorial  ||  ret=$?
  test $ret -eq 120  # factorial(5)
  ./factorial test
  echo
}

echo random
bootstrap/bootstrap translate [01]*.subx random.subx  -o random
# don't run

# Phases of the self-hosted SubX translator.

for phase in hex survey_elf survey_baremetal labels_baremetal pack assort dquotes tests
do
  echo $phase
  bootstrap/bootstrap translate [01]*.subx subx-params.subx $phase.subx -o $phase
  test "$1" = 'record'  ||  git diff --exit-code $phase
  {
    bootstrap/bootstrap run $phase test
    echo
  }
  {
    chmod +x $phase
    ./$phase test
    echo
  }
done

# Higher-level syntax.

# Certain phases of translation run native beyond this point. We're starting
# to go beyond functionality of the C++ bootstrap_bin.

echo sigils
bootstrap/bootstrap translate [012]*.subx subx-params.subx sigils.subx  -o sigils
test "$1" = 'record'  ||  git diff --exit-code sigils
{
  bootstrap/bootstrap run sigils test
  echo
}
{
  chmod +x sigils
  ./sigils test
  echo
}

echo calls
cat [012]*.subx subx-params.subx calls.subx  |  sigils  > a.sigils
bootstrap/bootstrap translate a.sigils -o calls
test "$1" = 'record'  ||  git diff --exit-code calls
{
  bootstrap/bootstrap run calls test
  echo
}
{
  chmod +x calls
  ./calls test
  echo
}

echo braces
cat [012]*.subx subx-params.subx braces.subx  |  calls  |  sigils  > a.sigils
bootstrap/bootstrap translate a.sigils -o braces
test "$1" = 'record'  ||  git diff --exit-code braces
{
  bootstrap/bootstrap run braces test
  echo
}
{
  chmod +x braces
  ./braces test
  echo
}

echo mu
cat [0-2]*.subx mu.subx  |  braces  |  calls  |  sigils  > a.sigils
bootstrap/bootstrap translate a.sigils -o mu
test "$1" = 'record'  ||  git diff --exit-code mu
{
  bootstrap/bootstrap run mu test
  echo
}
{
  chmod +x mu
  ./mu test
  echo
}

echo "== translating using the self-hosted translator"

# example programs

for n in `seq 1 12`
do
  echo ex$n
  ./translate_subx 000init.subx ex$n.subx
  diff ex$n a.elf
done

# Larger apps that use the standard library.

for app in factorial
do
  echo $app
  ./translate_subx [01]*.subx $app.subx
  diff $app a.elf
done

# Phases of the self-hosted SubX translator.

for app in hex survey_elf survey_baremetal labels_baremetal pack assort dquotes tests
do
  echo $app
  ./translate_subx [01]*.subx subx-params.subx $app.subx
  diff $app a.elf
done

for app in sigils calls braces
do
  echo $app
  ./translate_subx [012]*.subx subx-params.subx $app.subx
  diff $app a.elf
done

# Mu translator
echo mu
./translate_subx [0-2]*.subx mu.subx
diff mu a.elf

# Mu programs

echo ex1.mu
./translate ex1.mu
{
  bootstrap/bootstrap run a.elf  ||  ret=$?
  test $ret -eq 42  # life, the universe and everything
}
{
  ./a.elf  ||  ret=$?
  test $ret -eq 42  # life, the universe and everything
}

echo ex2.mu
./translate ex2.mu
{
  bootstrap/bootstrap run a.elf  ||  ret=$?
  test $ret -eq 7
}
{
  ./a.elf  ||  ret=$?
  test $ret -eq 7
}

echo ex3.mu
./translate ex3.mu
{
  bootstrap/bootstrap run a.elf  ||  ret=$?
  test $ret -eq 55
}
{
  ./a.elf  ||  ret=$?
  test $ret -eq 55
}

echo ex3.2.mu
./translate ex3.2.mu
{
  bootstrap/bootstrap run a.elf  ||  ret=$?
  test $ret -eq 55
}
{
  ./a.elf  ||  ret=$?
  test $ret -eq 55
}

echo factorial.mu
./translate factorial.mu
{
  bootstrap/bootstrap run a.elf  ||  ret=$?
  test $ret -eq 120
  bootstrap/bootstrap run a.elf test
  echo
}
{
  ./a.elf  ||  ret=$?
  test $ret -eq 120
  ./a.elf test
  echo
}

exit 0