Mention fallback output in help/readme

Author: riquito

README.md

@@ -53,7 +53,8 @@ FLAGS:
 
 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:]
 
@@ -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 <new> Replace the delimiter with the provided text
     -t, --trim <type>             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:
     --trim and --compress-delimiter are applied before --fields or similar

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

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)

src/help.rs

@@ -29,7 +29,8 @@ FLAGS:
 
 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:]
 
@@ -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 <type>             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:
     --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");