From b0aa310c836729f7dcaa37616d139c7571ff5e3d Mon Sep 17 00:00:00 2001 From: Ryan Geary Date: Wed, 1 Apr 2020 16:32:19 -0400 Subject: Update documentation for v0.1.4 --- Cargo.lock | 2 +- Cargo.toml | 2 +- readme.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++++---------- src/opt.rs | 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 "] 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] ... 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 Specify field separator other than whitespace + -f, --field-separator Specify field separator other than whitespace, using Rust `regex` syntax -i, --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 ``` 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, - /// 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, -- cgit v1.2.3