Merge branch 'release/0.2.0'

Author: xen0n

Cargo.lock

@@ -1,24 +1,22 @@
 [package]
-name = "autojump-rs"
-version = "0.1.0"
+name = "autojump"
+version = "0.2.0"
 authors = ["Wang Xuerui <git@xen0n.name>"]
-
-
-[workspace]
-members = ["src/autojump", "src/autojump-data", "src/autojump-match", "src/autojump-utils"]
+description = "A Rust port and drop-in replacement of autojump"
+repository = "https://github.com/xen0n/autojump-rs"
+readme = "README.md"
+license = "GPL-3.0+"
+include = ["src/*.rs", "Cargo.toml", "build.rs"]
+build = "build.rs"
 
 
 [dependencies]
-autojump = { path = "src/autojump", version = "0.1.0" }
-autojump-data = { path = "src/autojump-data", version = "0.1.0" }
-autojump-match = { path = "src/autojump-match", version = "0.1.0" }
-autojump-utils = { path = "src/autojump-utils", version = "0.1.0" }
-
-rustc-serialize = "0.3"
+atomicwrites = "0.0.14"
 docopt = "0.6"
-docopt_macros = "0.6"
+regex = "0.1"
+rustc-serialize = "0.3"
+strsim = "0.5"
 
 
-[[bin]]
-name = "autojump"
-path = "src/autojump-cli/main.rs"
+[build-dependencies]
+walkdir = "0.1"

Cargo.toml

@@ -12,21 +12,80 @@ which is GPL, either version 3 or any later version. See [LICENSE](LICENSE)
 for details.
 
 
-## FAQ
+## Install
 
-#### Why Rust?
+This isn't published on crates.io yet, but you can always clone the repository
+and `cargo build --release` yourself. Assuming you already have original
+`autojump` installed and properly set up, it's only a simple matter of putting
+the result executable on your `$PATH`, overriding the original script. (You
+may need to do a `hash -r` before using in your currently open shells, of
+course.)
 
-Primarily for two reasons:
 
-* The author is really tired of `autojump` breakage inside Python virtualenvs, and
-* Rust is simply *awesome* for CLI applications, with its performance and (code) slickness!
+## Features
 
+Why do a port when the original version works? Primarily for two reasons:
 
-#### Is the port compatible, bug-for-bug?
+* The author is *really* tired of `autojump` breakage inside Python virtualenvs, and
+* Rust is simply *awesome* for CLI applications, with its performance and (code) slickness!
 
-The on-disk format of the text database should be identical. That said, edge
-cases certainly exist. The author is developing and using this on Linux, so
-other platforms may need a little more love.
+Indeed, being written in a compiled language, **`autojump-rs` is very light on
+modern hardware**. As the program itself is very short-running, the overhead of
+setting up and tearing down a whole Python VM could be overwhelming,
+especially on less capable hardware. With `autojump-rs` this latency is
+greatly reduced. Typical running time is like this on the author's Core
+i7-2670QM laptop, with a directory database of 256 entries:
+
+```
+$ time ./autojump/bin/autojump au
+/home/xenon/src/autojump-rs
+./autojump/bin/autojump au  0.05s user 0.02s system 96% cpu 0.080 total
+
+$ time ./autojump-rs/target/release/autojump au
+/home/xenon/src/autojump-rs
+./autojump-rs/target/release/autojump au  0.02s user 0.00s system 94% cpu 0.020 total
+```
+
+The time savings are more pronounced on less powerful hardware, where every
+cycle shaved off counts. On a Loongson 3A2000 box running at 1.0 GHz the
+timings are like this, with a database of the same size:
+
+```
+$ time ./autojump/bin/autojump au
+/opt/store/src/autojump-rs
+./autojump/bin/autojump au  0.15s user 0.02s system 97% cpu 0.178 total
+
+$ time ./autojump-rs/target/release/autojump au
+/opt/store/src/autojump-rs
+./autojump-rs/target/release/autojump au  0.04s user 0.01s system 96% cpu 0.051 total
+```
+
+And, of course, the program no longer interacts with Python in any way, so the
+virtualenv-related crashes are no more. Say goodbye to the dreaded
+`ImportError`'s *showing every `$PS1` in a virtualenv with the system-default
+Python*!
+
+```
+# bye and you won't be missed!
+Traceback (most recent call last):
+  File "/usr/lib/python-exec/python2.7/autojump", line 43, in <module>
+    from autojump_data import dictify
+ImportError: No module named autojump_data
+```
+
+
+## Compatibility
+
+All of the command line flags and arguments are now implemented, and behave
+exactly like the original. Being a drop-in replacement, all other shell
+features like tab completion should work too. (Except `jc` and `jco`; see
+below.)
+
+As for the text database, the on-disk format should be identical. (Actually
+there is a little difference in the representation of floats, but it doesn't
+matter.) However, as the author is developing and using this on Linux, other
+platforms may need a little more love, although all the libraries used are
+lovingly cross-platform. (Patches are welcome, of course!)
 
 That said, there're some IMO very minor deviations from the original Python
 implementation. These are:
@@ -38,17 +97,38 @@ implementation. These are:
     [`docopt.rs`][docopt.rs] library, as is shown in `crates.io` statistics
     and GitHub activities. So it's necessary to re-arrange the help messages
     at least, as the `docopt` family of argument parsers mandate a specific
-    style for them.
+    style for them. However this shouldn't be any problem, just that it's
+    different. Again, who looks at the usage screen all the day? XD
+
+*   Different algorithm chosen for fuzzy matching.
+
+    The Python version uses the [`difflib.SequenceMatcher`][difflib] algorithm
+    for its fuzzy matches. Since it's quite a bit of complexity, I chose to
+    leverage the [`strsim`][strsim-rs] library instead. The [Jaro-Winkler
+    distance][jaro] is computed between every filename and the last part of
+    query needles respectively, and results are filtered based on that.
 
-    Also, due to [a limitation][docopt-limitation] optional flag arguments
-    are not supported, so it's required to provide the weights when you do
-    `--increase` or `--decrease`. The original defaults are `10` and `15`
-    respectively, so you can manually specify them in the meantime.
+*   `jc` doesn't work correctly at the moment.
+
+    Exact reason may be different filtering logic involved, but I'm not very
+    sure about this one. I only use plain `j` mostly, so if you're heavily
+    reliant on `jc` and its friends please open an issue!
 
 
 [rust-argparse]: https://github.com/tailhook/rust-argparse
 [docopt.rs]: https://github.com/docopt/docopt.rs
-[docopt-limitation]: https://github.com/docopt/docopt.rs/issues/167
+[difflib]: https://docs.python.org/3.5/library/difflib.html
+[strsim-rs]: https://github.com/dguo/strsim-rs
+[jaro]: https://en.wikipedia.org/wiki/Jaro%E2%80%93Winkler_distance
+
+
+## Future plans
+
+After initial porting, it's now time to re-organize the code to be more
+library-like (rather than application-like) and Rustic. After that the project
+would likely be published on crates.io. Hell I even want to write a `fasd`
+backend too, but I don't presently have *that* much free time. Anyway,
+contributions and bug reports are welcome!
 
 
 <!-- vim:set ai et ts=4 sw=4 sts=4 fenc=utf-8: -->

README.md

@@ -0,0 +1,61 @@
+// NOTE: This is just `rustfmt`'s `build.rs` taken verbatim.
+// `rustfmt` is dual-licensed under the Apache License 2.0 and the MIT
+// license.
+
+extern crate walkdir;
+
+use std::env;
+use std::fs::File;
+use std::io::Write;
+use std::path::Path;
+use std::process::Command;
+
+use walkdir::WalkDir;
+
+fn main() {
+    let out_dir = env::var("OUT_DIR").unwrap();
+    let dest_path = Path::new(&out_dir).join("git_info.rs");
+    let mut f = File::create(&dest_path).unwrap();
+
+    writeln!(f,
+             "const COMMIT_HASH: Option<&'static str> = {:?};",
+             git_head_sha1())
+        .unwrap();
+    writeln!(f,
+             "const WORKTREE_CLEAN: Option<bool> = {:?};",
+             git_tree_is_clean())
+        .unwrap();
+
+    // cargo:rerun-if-changed requires one entry per individual file.
+    for entry in WalkDir::new("src") {
+        let entry = entry.unwrap();
+        println!("cargo:rerun-if-changed={}", entry.path().display());
+    }
+}
+
+// Returns `None` if git is not available.
+fn git_head_sha1() -> Option<String> {
+    Command::new("git")
+        .arg("rev-parse")
+        .arg("--short")
+        .arg("HEAD")
+        .output()
+        .ok()
+        .and_then(|o| String::from_utf8(o.stdout).ok())
+        .map(|mut s| {
+            let len = s.trim_right().len();
+            s.truncate(len);
+            s
+        })
+}
+
+// Returns `None` if git is not available.
+fn git_tree_is_clean() -> Option<bool> {
+    Command::new("git")
+        .arg("status")
+        .arg("--porcelain")
+        .arg("--untracked-files=no")
+        .output()
+        .ok()
+        .map(|o| o.stdout.is_empty())
+}