Add a --sort flag to hath and document/test why it was needed after all.

[hath.git] / doc / man1 / hath.1

diff --git a/doc/man1/hath.1 b/doc/man1/hath.1
index 6e7a618c61adbaaf7ac2cf9ccd0abb85dec56264..69b362fe17079601c155d330918b91e48e61532c 100644 (file)
--- a/doc/man1/hath.1
+++ b/doc/man1/hath.1
@@ -4,12 +4,12 @@
 hath \- Manipulate network blocks in CIDR notation
 .SH SYNOPSIS
 
 hath \- Manipulate network blocks in CIDR notation
 .SH SYNOPSIS
 

-\fBhath\fR [\fBregexed|reduced|duped|diffed\fR] [\fB\-h\fR] [\fB-i \fIFILE\fR] \fI<input>\fR
+\fBhath\fR [\fBregexed|reduced|duped|diffed|listed\fR] [\fB\-hb\fR] \fI<input>\fR

 .SH INPUT
 .P
 .SH INPUT
 .P

-The \fIinput\fR (default: stdin) should be a list of CIDR blocks,
-separated by whitespace. Empty lines will be ignored, but otherwise,
-malformed entries will cause an error to be displayed.
+The \fIinput\fR (stdin) should be a list of CIDR blocks, separated by
+whitespace. Empty lines will be ignored, but otherwise, malformed
+entries will cause an error to be displayed.

 .SH DESCRIPTION
 .P
 Hath is a Haskell program for working with network blocks in CIDR
 .SH DESCRIPTION
 .P
 Hath is a Haskell program for working with network blocks in CIDR


@@ -25,67 +25,64 @@ consecutive /24s, they might combine into a larger /23.
 View the result of block combination in a useful way.
 .IP \(bu
 List them.
 View the result of block combination in a useful way.
 .IP \(bu
 List them.

-.IP \(bu
-Find their associated PTR records.

 .P
 .P

-Hath does just that. It takes as its input (via stdin, or a file with
-the -i parameter) a list of CIDR blocks.
+Hath does just that. It takes as its input (via stdin) a list of CIDR
+blocks.

 .SH MODES
 .P
 Hath has several modes:
 .IP \(bu 2
 \fBRegexed\fR
 .SH MODES
 .P
 Hath has several modes:
 .IP \(bu 2
 \fBRegexed\fR

-.P
+

 This computes a (Perl-compatible) regular expression matching
 the input CIDR blocks. It's the default mode of operation.
 This computes a (Perl-compatible) regular expression matching
 the input CIDR blocks. It's the default mode of operation.

-.P
+

 .nf
 .nf

-.I $ hath <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
-([^\.0-9](10)\.(0)\.(0)\.(0)[^\.0-9]|[^\.0-9](10)\.(0)\.(1)
-\.(0)[^\.0-9])
+.I $ echo \(dq10.0.0.0/29 10.0.0.8/29\(dq | hath
+((10)\.(0)\.(0)\.(15|14|13|12|11|10|9|8|7|6|5|4|3|2|1|0))

 .fi
 .IP \(bu 2
 \fBReduced\fR
 .fi
 .IP \(bu 2
 \fBReduced\fR

-.P
+

 This combines small blocks into larger ones where possible, and
 eliminates redundant blocks. The output should be equivalent to
 the input, though.
 This combines small blocks into larger ones where possible, and
 eliminates redundant blocks. The output should be equivalent to
 the input, though.

-.P
+

 .nf
 .nf

-.I $ hath reduced <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath reduced

 10.0.0.0/23
 .fi
 .IP \(bu 2
 \fBDuped\fR
 10.0.0.0/23
 .fi
 .IP \(bu 2
 \fBDuped\fR

-.P
+

 Shows only the blocks that would be removed by reduce; that is, it
 shows the ones that would get combined into larger blocks or are
 simply redundant.
 Shows only the blocks that would be removed by reduce; that is, it
 shows the ones that would get combined into larger blocks or are
 simply redundant.

-.P
+

 .nf
 .nf

-.I $ hath duped <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath duped

 10.0.0.0/24
 10.0.1.0/24
 .fi
 .IP \(bu 2
 \fBDiffed\fR
 10.0.0.0/24
 10.0.1.0/24
 .fi
 .IP \(bu 2
 \fBDiffed\fR

-.P
+

 Shows what would change if you used reduce. Uses diff-like
 notation.
 Shows what would change if you used reduce. Uses diff-like
 notation.

-.P
+

 .nf
 .nf

-.I $ hath diffed <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+.I $ echo \(dq10.0.0.0/24 10.0.1.0/24\(dq | hath diffed

 -10.0.0.0/24
 -10.0.1.0/24
 +10.0.0.0/23
 .fi
 .IP \(bu 2
 \fBListed\fR
 -10.0.0.0/24
 -10.0.1.0/24
 +10.0.0.0/23
 .fi
 .IP \(bu 2
 \fBListed\fR

-.P
+

 List the IP addresses contained within the given CIDRs.
 List the IP addresses contained within the given CIDRs.

-.P
+

 .nf
 .nf

-.I $ hath listed <<< \(dq192.168.0.240/29\(dq
+.I $ echo 192.168.0.240/29 | hath listed

 192.168.0.240
 192.168.0.241
 192.168.0.242
 192.168.0.240
 192.168.0.241
 192.168.0.242


@@ -95,39 +92,83 @@ List the IP addresses contained within the given CIDRs.
 192.168.0.246
 192.168.0.247
 .fi
 192.168.0.246
 192.168.0.247
 .fi

-.IP \(bu 2
-\fBReversed\fR
-.P
-Perform reverse DNS (PTR) lookups on the IP addresses contained within
-the given CIDRs.
+.SH EXAMPLES

 .P
 .P

+Use the \(dqdig\(dq command to look up the PTR records for a netblock:
+

 .nf
 .nf

-.I $ hath reversed <<< \(dq198.41.0.4/30\(dq
-198.41.0.4: a.root-servers.net.
-198.41.0.5:
-198.41.0.6: rs.internic.net.
-198.41.0.7:
+.I $ echo 198.41.0.4/30 | hath listed | xargs -I{} dig +noall +answer -x '{}'
+4.0.41.198.in-addr.arpa. 897   IN      PTR     a.root-servers.net.
+6.0.41.198.in-addr.arpa. 900   IN      PTR     rs.internic.net.

 .fi
 .fi

-.P
-The DNS lookups are usually the bottleneck for this mode, but we can
-perform them in parallel. Simply pass the number of threads to the GHC
-runtime on the command line; for example, the following will perform
-25 lookups in parallel:
-.P
+.SH OPTIONS
+
+.IP \fB\-\-barriers\fR,\ \fB\-b\fR
+(regexed mode only)
+
+Place barriers in front/back of the regex to prevent, for
+example, '127.0.0.1' from matching '127.0.0.100'. The downside is that
+the resulting regexp will match something that is not an IP address.
+This can interfere with things like \fIgrep -o\fR.
+
+Without \fB\-\-barriers\fR, you can match things you shouldn't:
+

 .nf
 .nf

-.I $ hath reversed +RTS -N25 <<< \(dq198.41.0.4/24\(dq
-198.41.0.4: a.root-servers.net.
-198.41.0.5:
-198.41.0.6: rs.internic.net.
-\(pc\(pc\(pc
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath)
+127.0.0.100

 .fi
 .fi

-.P
-Each of the modes also supports a present-tense flavor; the following
-are equivalent to their counterparts: \fBregex\fR, \fBreduce\fR,
-\fBdupe\fR, \fBdiff\fR, \fBlist\fR, \fBreverse\fR.

 
 

-.SH OPTIONS
+Using \fB\-\-barriers\fR can prevent this:
+
+.nf
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath -b)
+.I $ echo $?
+1
+.fi
+
+But, this may also cause the regex to match something that isn't an IP
+address:
+
+.nf
+.I $ echo x127.0.0.1x | grep -Po $(echo 127.0.0.1/32 | hath -b)
+x127.0.0.1x
+.fi
+.IP \fB\-\-normalize\fR,\ \fB\-n\fR
+(reduced mode only)
+
+Normalize the output representation of CIDRs by zeroing the host
+bits. This option only has an effect in \(dqreduced\(dq mode, because
+in the \(dqduped\(dq or \(dqdiffed\(dq modes, it would be confusing to
+see CIDRs that you did not input in the first place being removed.
+
+.nf
+.I $ echo 127.0.0.1/8 | hath reduced
+127.0.0.1/8
+.I $ echo 127.0.0.1/8 | hath reduced --normalize
+127.0.0.0/8
+.fi
+.IP \fB\-\-sort\fR,\ \fB\-s\fR
+(reduced mode only)
+
+Sort the output CIDRs numerically by octet. The \(dqsort\(dq utility
+doesn't understand IP addresses, so the default pipe-to-sort approach
+fails in some cases:
+
+.nf
+.I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced | sort
+10.0.121.32/28
+10.0.93.248/29
+.I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced | sort -n
+10.0.121.32/28
+10.0.93.248/29
+.fi
+
+That failure justifies adding the additional option to hath:
+
+.nf
+.I $ echo \(dq10.0.121.32/28 10.0.93.248/29\(dq | hath reduced --sort
+10.0.93.248/29
+10.0.121.32/28
+.SH BUGS

 
 

-.IP \fB\-\-input\fR,\ \fB\-i\fR
-Specify the input file containing a list of CIDRs, rather than using
-stdin (the default).
+Send bugs to michael@orlitzky.com.