diff options
author | Ryan Geary <rtgnj42@gmail.com> | 2020-04-01 16:32:19 -0400 |
---|---|---|
committer | Ryan Geary <rtgnj42@gmail.com> | 2020-04-02 10:14:29 -0400 |
commit | b0aa310c836729f7dcaa37616d139c7571ff5e3d (patch) | |
tree | 5fc117477504336a7eabee3f180110add678e919 | |
parent | e78ea2783cf99de0d4dd430af403e88fc1edbf0e (diff) |
Update documentation for v0.1.4v0.1.4
-rw-r--r-- | Cargo.lock | 2 | ||||
-rw-r--r-- | Cargo.toml | 2 | ||||
-rw-r--r-- | readme.md | 71 | ||||
-rw-r--r-- | src/opt.rs | 4 |
4 files changed, 64 insertions, 15 deletions
@@ -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)", @@ -1,6 +1,6 @@ [package] name = "choose" -version = "0.1.3" +version = "0.1.4" authors = ["Ryan Geary <rtgnj42@gmail.com>"] edition = "2018" @@ -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 +``` @@ -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, |