Bulletproof the test suite and examples; version bump the cabal file.

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

diff --git a/doc/man1/hath.1 b/doc/man1/hath.1
index 3050385bdc82fde4cd23318f284910db8e73c1dc..6e4ef3700b669ae7d4e69c00e0bebd36fd07cdb3 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
 
-\fBhath\fR [\fBregexed|reduced|duped|diffed\fR] [\fB\-h\fR] [\fB-i \fIFILE\fR] \fI<input>\fR
+\fBhath\fR [\fBregexed|reduced|duped|diffed|listed|reversed\fR] [\fB\-hb\fR] \fI<input>\fR
 .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
@@ -23,9 +23,13 @@ Combine small blocks into larger ones. For example, if you have two
 consecutive /24s, they might combine into a larger /23.
 .IP \(bu
 View the result of block combination in a useful way.
+.IP \(bu
+List them.
+.IP \(bu
+Find their associated PTR records.
 .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:
@@ -36,9 +40,8 @@ This computes a (Perl-compatible) regular expression matching
 the input CIDR blocks. It's the default mode of operation.
 .P
 .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
@@ -48,7 +51,7 @@ eliminates redundant blocks. The output should be equivalent to
 the input, though.
 .P
 .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
@@ -59,7 +62,7 @@ shows the ones that would get combined into larger blocks or are
 simply redundant.
 .P
 .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
@@ -70,7 +73,7 @@ Shows what would change if you used reduce. Uses diff-like
 notation.
 .P
 .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
@@ -81,7 +84,7 @@ notation.
 List the IP addresses contained within the given CIDRs.
 .P
 .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
@@ -98,19 +101,56 @@ Perform reverse DNS (PTR) lookups on the IP addresses contained within
 the given CIDRs.
 .P
 .nf
-.I $ hath reversed <<< \(dq198.41.0.4\/30\(dq
+.I $ echo 198.41.0.4/30 | hath reversed
 198.41.0.4: a.root-servers.net.
 198.41.0.5:
 198.41.0.6: rs.internic.net.
 198.41.0.7:
 .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.
+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
+.nf
+.I $ echo 198.41.0.4/24 | hath reversed +RTS -N25
+198.41.0.4: a.root-servers.net.
+198.41.0.5:
+198.41.0.6: rs.internic.net.
+\(pc\(pc\(pc
+.fi
 
 .SH OPTIONS
 
-.IP \fB\-\-input\fR,\ \fB\-i\fR
-Specify the input file containing a list of CIDRs, rather than using
-stdin (the default).
+.IP \fB\-\-barriers\fR,\ \fB\-b\fR
+(regexed mode only) place barriers in front/back of the regex to
+prevent e.g. '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, and this messes up e.g. \fIgrep -o\fR.
+
+.P
+Without \fB\-\-barriers\fR, you can match things you shouldn't:
+
+.nf
+.I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath)
+127.0.0.100
+.fi
+
+.P
+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
+
+.P
+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