aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Neukirchen <chneukirchen@gmail.com>2016-02-14 16:25:10 +0100
committerChristian Neukirchen <chneukirchen@gmail.com>2016-02-14 16:25:10 +0100
commit55b5ff3097da4c98f0eea2d2f28d9a87cd60c51a (patch)
treec190ee3d33dddd486f9cddd13495e354546207d1
parent2f00c5b600d7222ed9093718025a06f29d04d690 (diff)
downloadarr-master.tar.gz
arr-master.tar.xz
arr-master.zip
add manpage and READMEHEADmaster
-rw-r--r--Makefile2
-rw-r--r--README91
-rw-r--r--arr.1156
3 files changed, 249 insertions, 0 deletions
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..9cc103c
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,2 @@
+README: arr.1
+ mandoc -Tutf8 $< | col -bx >$@
diff --git a/README b/README
new file mode 100644
index 0000000..a3ed8b5
--- /dev/null
+++ b/README
@@ -0,0 +1,91 @@
+ARR(1) General Commands Manual ARR(1)
+
+NAME
+ arr – (re)arrange and select fields on each line
+
+SYNOPSIS
+ arr [-0] [-P | -p padding] expr [files ...]
+
+DESCRIPTION
+ arr unifies and extends the features of cut(1), paste(1), and provides an
+ alternative to dicer(5).
+
+ arr will read one line (or zero separated string, when -0 is used) from
+ each file passed on the command line, and then print the result of
+ expanding expr.
+
+ By default, reading continues until all files are exhausted. Ended files
+ continue generating empty strings, or padding when -p is used. When -P
+ is used, reading stops as soon as one file is exhausted.
+
+FORMATTING EXPRESSIONS
+ expr is read as a string containing escape sequences ‘%{...}’ which are
+ parsed according to the following EBNF:
+
+ <expr> ::= <fields> (("|" <char> | "*") <fields>)* ("&" <char>)?
+ <fields> ::= "~"? <field> ("," <field>)*
+ <field> ::= "-"? ""+ | ("-"? ""+)? ":" ("-"? ""+)?
+
+ Fields are specified by their position, negative numbers count from the
+ end. Field ranges are written like n:m where n and m are optional and
+ default to 1 and -1 respectively. If n is bigger than m, fields are
+ expanded in reverse order.
+
+ Field ranges are combined using , and an initial ~ negates the whole set
+ of field selections.
+
+ Selected fields are joined with the last separator, and then split on c
+ when |c is used. Alternatively, * splits byte-wise. A final &c joins
+ the selected fields using c again.
+
+ The first set of fields corresponds to the lines read from each file.
+
+EXIT STATUS
+ The arr utility exits 0 on success, and >0 if an error occurs.
+
+EXAMPLES
+ Print all users from /etc/passwd (read: ‘take line from file 1, split on
+ :, print field 1.’):
+
+ arr '%{1|:1}' /etc/passwd
+
+ List all basenames of shells used (read ‘take line from file 1, split on
+ :, take last field, split on /, take last field.’):
+
+ arr '%{1|:-1|/-1}' /etc/passwd | sort -u
+
+ Remove the TLD from a list of domains:
+
+ arr '%{1|.~-1}'
+
+ Generate PTR addresses for a list of IPv4s:
+
+ arr '%{1|.-1:1}.in-addr.arpa'
+
+ Only print the first 80 chars of each line:
+
+ arr '%{1*:80}'
+
+ Double space text:
+
+ arr '%{1*:& }'
+
+ Format a phone number:
+
+ echo 8005551212 | arr '(%{1*1:3})%{1*4:6}-%{1*7:}'
+
+SEE ALSO
+ cut(1), paste(1), dicer(5)
+
+AUTHORS
+ Christian Neukirchen <chneukirchen@gmail.com>
+
+LICENSE
+ arr is in the public domain.
+
+ To the extent possible under law, the creator of this work has waived all
+ copyright and related or neighboring rights to this work.
+
+ http://creativecommons.org/publicdomain/zero/1.0/
+
+Linux 4.3.4_1 February 14, 2016 Linux 4.3.4_1
diff --git a/arr.1 b/arr.1
new file mode 100644
index 0000000..46098f0
--- /dev/null
+++ b/arr.1
@@ -0,0 +1,156 @@
+.Dd February 14, 2016
+.Dt ARR 1
+.Os
+.Sh NAME
+.Nm arr
+.Nd (re)arrange and select fields on each line
+.Sh SYNOPSIS
+.Nm
+.Op Fl 0
+.Op Fl P | Fl p Ar padding
+.Ar expr
+.Op Ar files\ ...
+.Sh DESCRIPTION
+.Nm
+unifies and extends the features of
+.Xr cut 1 ,
+.Xr paste 1 ,
+and provides an alternative to
+.Xr dicer 5 .
+.Pp
+.Nm
+will read one line (or zero separated string, when
+.Fl 0
+is used) from each
+.Ar file
+passed on the command line,
+and then print the result of expanding
+.Ar expr .
+.Pp
+By default, reading continues until all files are exhausted.
+Ended files continue generating empty strings,
+or
+.Ar padding
+when
+.Fl p
+is used.
+When
+.Fl P
+is used, reading stops as soon as one file is exhausted.
+.Sh FORMATTING EXPRESSIONS
+.Ar expr
+is read as a string containing escape sequences
+.Ql "%{...}"
+which are parsed according to the following EBNF:
+.Bd -literal -offset indent
+<expr> ::= <fields> (("|" <char> | "*") <fields>)* ("&" <char>)?
+<fields> ::= "~"? <field> ("," <field>)*
+<field> ::= "-"? "\d"+ | ("-"? "\d"+)? ":" ("-"? "\d"+)?
+.Ed
+.Pp
+Fields are specified by their position,
+negative numbers count from the end.
+Field ranges are written like
+.Cm Ar n Ns Cm ":" Ns Ar m
+where
+.Ar n
+and
+.Ar m
+are optional and default to 1 and -1 respectively.
+If
+.Ar n
+is bigger than
+.Ar m ,
+fields are expanded in reverse order.
+.Pp
+Field ranges are combined using
+.Cm ","
+and an initial
+.Cm "~"
+negates the whole set of field selections.
+.Pp
+Selected fields are joined with the last separator,
+and then split on
+.Ar c
+when
+.Cm "|" Ns Ar c
+is used.
+Alternatively,
+.Cm "*"
+splits byte-wise.
+A final
+.Cm "&" Ns Ar c
+joins the selected fields using
+.Ar c
+again.
+.Pp
+The first set of fields corresponds to the lines read from each file.
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Print all users from
+.Pa /etc/passwd
+(read:
+.So
+take line from file 1, split on
+.Cm ":" ,
+print field 1.
+.Sc ) :
+.Bd -literal -offset indent
+arr '%{1|:1}' /etc/passwd
+.Ed
+.Pp
+List all basenames of shells used
+(read
+.So
+take line from file 1, split on
+.Cm ":" ,
+take last field,
+split on
+.Cm "/" ,
+take last field.
+.Sc ) :
+.Bd -literal -offset indent
+arr '%{1|:-1|/-1}' /etc/passwd | sort -u
+.Ed
+.Pp
+Remove the TLD from a list of domains:
+.Bd -literal -offset indent
+arr '%{1|.~-1}'
+.Ed
+.Pp
+Generate PTR addresses for a list of IPv4s:
+.Bd -literal -offset indent
+arr '%{1|.-1:1}.in-addr.arpa'
+.Ed
+.Pp
+Only print the first 80 chars of each line:
+.Bd -literal -offset indent
+arr '%{1*:80}'
+.Ed
+.Pp
+Double space text:
+.Bd -literal -offset indent
+arr '%{1*:& }'
+.Ed
+.Pp
+Format a phone number:
+.Bd -literal -offset indent
+echo 8005551212 | arr '(%{1*1:3})%{1*4:6}-%{1*7:}'
+.Ed
+.Sh SEE ALSO
+.Xr cut 1 ,
+.Xr paste 1 ,
+.Xr dicer 5
+.Sh AUTHORS
+.An Christian Neukirchen Aq Mt chneukirchen@gmail.com
+.Sh LICENSE
+.Nm
+is in the public domain.
+.Pp
+To the extent possible under law,
+the creator of this work
+has waived all copyright and related or
+neighboring rights to this work.
+.Pp
+.Lk http://creativecommons.org/publicdomain/zero/1.0/