From d09953ace89a93e6f6159bd65a8cdfa579023311 Mon Sep 17 00:00:00 2001 From: Riccardo Attilio Galli Date: Mon, 26 Feb 2024 00:16:49 -0800 Subject: [PATCH] Mention fallback output in help/readme --- README.md | 8 +++++++- doc/tuc.1 | 46 +++++++++++++++++++++++++++++++++++++++++----- doc/tuc.1.md | 20 ++++++++++++++------ src/help.rs | 10 ++++++++-- 4 files changed, 70 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index a03d329..567fca6 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,8 @@ FLAGS: OPTIONS: -f, --fields Fields to keep, 1-indexed, comma separated. - Use colon to include everything in a range. + Use colon (:) to match a range (inclusive). + Use equal (=) to apply out of bound fallback. Fields can be negative (-1 is the last field). [default 1:] @@ -64,6 +65,7 @@ OPTIONS: -f 3,2 => cb -f 3,1:2 => ca-b -f -3:-2 => b-c + -f 1,8=fallback => afallback To re-apply the delimiter add -j, to replace it add -r (followed by the new delimiter). @@ -84,6 +86,10 @@ OPTIONS: -r, --replace-delimiter Replace the delimiter with the provided text -t, --trim Trim the delimiter (greedy). Valid values are (l|L)eft, (r|R)ight, (b|B)oth + --fallback-oob Generic fallback output for any field that + cannot be found (oob stands for out of bound). + It's overridden by any fallback assigned to a + specific field (see -f for help) Options precedence: --trim and --compress-delimiter are applied before --fields or similar diff --git a/doc/tuc.1 b/doc/tuc.1 index e5a33b1..40efcf3 100644 --- a/doc/tuc.1 +++ b/doc/tuc.1 @@ -67,7 +67,11 @@ Print fields as a JSON array of strings .PD 0 .P .PD -\ \ \ \ \ \ \ Use colon to include everything in a range. +\ \ \ \ \ \ \ Use colon (:) to match a range (inclusive). +.PD 0 +.P +.PD +\ \ \ \ \ \ \ Use equal (=) to apply out of bound fallback. .PD 0 .P .PD @@ -100,6 +104,10 @@ Print fields as a JSON array of strings .P .PD \ \ \ \ \ \ \ \ \ \f[V]-f -3:-2 => b-c\f[R] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ \ \ \f[V]-f 1,8=fallback => afallback\f[R] .PP \ \ \ \ \ \ \ To re-apply the delimiter add -j, to replace .PD 0 @@ -173,6 +181,24 @@ To merge lines, use --no-join .P .PD \ \ \ \ \ \ \ Valid values are (l|L)eft, (r|R)ight, (b|B)oth +.PP +\ \ \ \ \f[B]--fallback-oob\f[R] [fallback] +.PD 0 +.P +.PD +\ \ \ \ \ \ \ Generic fallback output for any field that +.PD 0 +.P +.PD +\ \ \ \ \ \ \ cannot be found (oob stands for out of bound). +.PD 0 +.P +.PD +\ \ \ \ \ \ \ It\[cq]s overridden by any fallback assigned to a +.PD 0 +.P +.PD +\ \ \ \ \ \ \ specific field (see -f for help) .SH OPTIONS PRECEDENCE .PP --trim and --compress-delimiter are applied before --fields or similar @@ -181,15 +207,25 @@ To merge lines, use --no-join --characters and --fields read and allocate memory one line at a time .PP --lines allocate memory one line at a time as long as the requested -fields are ordered and non-negative (e.g.\ -l 1,3:4,4,7), otherwise it -allocates the whole input in memory (it also happens when -p or -m are -being used) +fields are +.PD 0 +.P +.PD +ordered and non-negative (e.g.\ -l 1,3:4,4,7), otherwise it allocates +.PD 0 +.P +.PD +the whole input in memory (it also happens when -p or -m are being used) .PP --bytes allocate the whole input in memory .SH COLORS .PP Help is displayed using colors. -Colors will be suppressed in the following circumstances: +Colors will be suppressed in the +.PD 0 +.P +.PD +following circumstances: .IP \[bu] 2 when the TERM environment variable is not set or set to \[lq]dumb\[rq] .IP \[bu] 2 diff --git a/doc/tuc.1.md b/doc/tuc.1.md index f264785..f47ebbe 100644 --- a/doc/tuc.1.md +++ b/doc/tuc.1.md @@ -54,7 +54,8 @@ OPTIONS | **-f**, **\--fields** [bounds] | Fields to keep, 1-indexed, comma separated. -| Use colon to include everything in a range. +| Use colon (:) to match a range (inclusive). +| Use equal (=) to apply out of bound fallback. | Fields can be negative (-1 is the last field). | [default 1:] @@ -66,6 +67,7 @@ OPTIONS | `-f 3,2 => cb` | `-f 3,1:2 => ca-b` | `-f -3:-2 => b-c` +| `-f 1,8=fallback => afallback` | To re-apply the delimiter add -j, to replace | it add -r (followed by the new delimiter) @@ -100,6 +102,12 @@ OPTIONS | Trim the delimiter (greedy). | Valid values are (l|L)eft, (r|R)ight, (b|B)oth +| **\--fallback-oob** [fallback] +| Generic fallback output for any field that +| cannot be found (oob stands for out of bound). +| It's overridden by any fallback assigned to a +| specific field (see -f for help) + OPTIONS PRECEDENCE ================== @@ -110,17 +118,17 @@ MEMORY CONSUMPTION \--characters and \--fields read and allocate memory one line at a time -\--lines allocate memory one line at a time as long as the requested fields are - ordered and non-negative (e.g. -l 1,3:4,4,7), otherwise it allocates - the whole input in memory (it also happens when -p or -m are being used) +| \--lines allocate memory one line at a time as long as the requested fields are +| ordered and non-negative (e.g. -l 1,3:4,4,7), otherwise it allocates +| the whole input in memory (it also happens when -p or -m are being used) \--bytes allocate the whole input in memory COLORS ====== -Help is displayed using colors. Colors will be suppressed in the -following circumstances: +| Help is displayed using colors. Colors will be suppressed in the +| following circumstances: - when the TERM environment variable is not set or set to "dumb" - when the NO_COLOR environment variable is set (regardless of value) diff --git a/src/help.rs b/src/help.rs index 0135213..e7a174d 100644 --- a/src/help.rs +++ b/src/help.rs @@ -29,7 +29,8 @@ FLAGS: OPTIONS: -f, --fields Fields to keep, 1-indexed, comma separated. - Use colon to include everything in a range. + Use colon (:) to match a range (inclusive). + Use equal (=) to apply out of bound fallback. Fields can be negative (-1 is the last field). [default: 1:] @@ -40,6 +41,7 @@ OPTIONS: -f 3,2 => cb -f 3,1:2 => ca-b -f -3:-2 => b-c + -f 1,8=fallback => afallback To re-apply the delimiter add -j, to replace it add -r (followed by the new delimiter). @@ -61,6 +63,10 @@ OPTIONS: Implies --join -t, --trim Trim the delimiter (greedy). Valid values are (l|L)eft, (r|R)ight, (b|B)oth + --fallback-oob Generic fallback output for any field that + cannot be found (oob stands for out of bound). + It's overridden by any fallback assigned to a + specific field (see -f for help) Options precedence: --trim and --compress-delimiter are applied before --fields or similar @@ -126,7 +132,7 @@ fn get_colored_help(text: &str) -> String { .replace_all(text, "\x1b[33m$0\x1b[0m"); // any example using "-f something" - let text = Regex::new(r#"-(f|l) ('.+'|[0-9,:-]+)"#) + let text = Regex::new(r#"-(f|l) ('.+'|[0-9,:-]+(=[^\s]+)?)"#) .unwrap() .replace_all(&text, "-$1 \x1b[33m$2\x1b[0m");