Update documentation for v0.1.4v0.1.4

4 files changed, 64 insertions, 15 deletions

diff --git a/Cargo.lock b/Cargo.lock
index fbee6a8..531826d 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -32,7 +32,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 
 [[package]]
 name = "choose"
-version = "0.1.3"
+version = "0.1.4"
 dependencies = [
  "lazy_static 1.4.0 (registry+https://github.com/rust-lang/crates.io-index)",
  "regex 1.3.1 (registry+https://github.com/rust-lang/crates.io-index)",
diff --git a/Cargo.toml b/Cargo.toml
index 36026c6..5958275 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "choose"
-version = "0.1.3"
+version = "0.1.4"
 authors = ["Ryan Geary <rtgnj42@gmail.com>"]
 edition = "2018"
 
diff --git a/readme.md b/readme.md
index e95d8ac..6c0d984 100644
--- a/readme.md
+++ b/readme.md
@@ -1,6 +1,18 @@
 # Choose
 
-This is `choose`, a human-friendly alternative to `awk` and `cut`
+This is `choose`, a human-friendly and fast alternative to `awk` and `cut`
+
+[![`choose` demo](https://asciinema.org/a/315932.png)](https://asciinema.org/a/315932?autoplay=1)
+
+## Features
+- terse field selection syntax similar to Python's list slices
+- negative indexing from end of line
+- optional start/end index
+- zero-indexed
+- reverse ranges
+- slightly faster than `cut` for sufficiently long inputs, much faster than
+  `awk`
+- regular expression field separators using Rust's regex syntax
 
 ## Rationale
 
@@ -13,9 +25,9 @@ for the simplest of programs:
 awk '{print $1}'
 ```
 
-Likewise, `cut` is far from ideal for rapid shell use, because it is difficult
-to get the confusing syntax correct on the first attempt. Field separators and
-ranges are just plain difficult to use.
+Likewise, `cut` is far from ideal for rapid shell use, because of its confusing
+syntax. Field separators and ranges are just plain difficult to get right on the
+first try.
 
 It is for these reasons that I present to you `choose`. It is not meant to be a
 drop-in or complete replacement for either of the aforementioned tools, but
@@ -26,19 +38,20 @@ necessary.
 ## Usage
 
 ```
+$ choose --help
+choose 0.1.4
 `choose` sections from each line of files
 
 USAGE:
     choose [FLAGS] [OPTIONS] <choice>...
 
 FLAGS:
-    -d, --debug        Activate debug mode
+    -x, --exclusive    Use exclusive ranges, similar to array indexing in many programming languages
     -h, --help         Prints help information
-    -n, --inclusive    Use inclusive ranges
     -V, --version      Prints version information
 
 OPTIONS:
-    -f, --field-separator <field-separator>    Specify field separator other than whitespace
+    -f, --field-separator <field-separator>    Specify field separator other than whitespace, using Rust `regex` syntax
     -i, --input <input>                        Input file
 
 ARGS:
@@ -57,19 +70,23 @@ choose -f ':' 0 3 5     # print the 0th, 3rd, and 5th item from a line, where
 choose 2:5              # print everything from the 2nd to 5th item on the line,
                         # exclusive of the 5th
 
-choose -n 2:5           # print everything from the 2nd to 5th item on the line,
-                        # inclusive of the 5th
+choose -x 2:5           # print everything from the 2nd to 5th item on the line,
+                        # exclusive of the 5th
 
 choose :3               # print the beginning of the line to the 3rd item,
                         # exclusive
 
 choose 3:               # print the third item to the end of the line
+
+choose -1               # print the last item from a line
+
+choose -3:-1            # print the last three items from a line
 ```
 
 ## Compilation and Installation
 
-In order to build `choose` you will need rust installed, and you can find
-instructions for that [here](https://www.rust-lang.org/tools/install).
+In order to build `choose` you will need the rust toolchain installed. You can
+find instructions [here](https://www.rust-lang.org/tools/install).
 
 Then, to install:
 
@@ -81,3 +98,35 @@ install target/release/choose <DESTDIR>
 ```
 
 Just make sure DESTDIR is in your path.
+
+### Benchmarking
+
+Benchmarking is performed using the [`bench` utility](https://github.com/Gabriel439/bench).
+
+Benchmarking is based on the assumption that there are five files in `test/`
+that match the glob "long*txt". GitHub doesn't support files big enough in
+normal repos, but for reference the files I'm working with have lengths like
+these:
+
+```
+     1000 test/long.txt
+    19272 test/long_long.txt
+    96360 test/long_long_long.txt
+   963600 test/long_long_long_long.txt
+ 10599600 test/long_long_long_long_long.txt
+```
+
+and content generally like this:
+
+```
+Those an equal point no years do. Depend warmth fat but her but played. Shy and
+subjects wondered trifling pleasant. Prudent cordial comfort do no on colonel as
+assured chicken. Smart mrs day which begin. Snug do sold mr it if such.
+Terminated uncommonly at at estimating. Man behaviour met moonlight extremity
+acuteness direction.
+
+Ignorant branched humanity led now marianne too strongly entrance. Rose to shew
+bore no ye of paid rent form. Old design are dinner better nearer silent excuse.
+She which are maids boy sense her shade. Considered reasonable we affronting on
+expression in. So cordial anxious mr delight. Shot his has must wish from sell
+```
diff --git a/src/opt.rs b/src/opt.rs
index 77ba9fd..77fc710 100644
--- a/src/opt.rs
+++ b/src/opt.rs
@@ -8,11 +8,11 @@ use crate::config::Config;
 #[structopt(name = "choose", about = "`choose` sections from each line of files")]
 #[structopt(setting = structopt::clap::AppSettings::AllowLeadingHyphen)]
 pub struct Opt {
-    /// Specify field separator other than whitespace
+    /// Specify field separator other than whitespace, using Rust `regex` syntax
     #[structopt(short, long)]
     pub field_separator: Option<String>,
 
-    /// Use exclusive ranges, similar to array slicing in many programming languages
+    /// Use exclusive ranges, similar to array indexing in many programming languages
     #[structopt(short = "x", long)]
     pub exclusive: bool,