about summary refs log tree commit diff
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-55b5ff3097da4c98f0eea2d2f28d9a87cd60c51a.tar.gz
arr-55b5ff3097da4c98f0eea2d2f28d9a87cd60c51a.tar.xz
arr-55b5ff3097da4c98f0eea2d2f28d9a87cd60c51a.zip
add manpage and README HEAD master
-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/