Add command-line help to all tools.

Unify naming of warc-file arguments.

Author: sebastian-nagel

README.md

@@ -153,6 +153,12 @@ Create a new file containing only html responses with status 200:
 
     java -jar jwarc.jar filter ':status == 200 && http:content-type =~ "text/html(;.*)?"' example.warc > pages.warc 
 
+All available tools are listed per
+
+    java -jar jwarc.jar
+
+and every tool provides a command-line help if called with the option `--help`.
+
 ## API Quick Reference
 
 See the [javadoc](https://www.javadoc.io/doc/org.netpreserve/jwarc) for more details.

src/org/netpreserve/jwarc/tools/ExtractTool.java

@@ -79,7 +79,7 @@ private static void writeBody(WritableByteChannel out, ReadableByteChannel body)
 
     private static void usage(int exitValue) {
         System.err.println();
-        System.err.println("ExtractTool [-h] [--payload | --headers] filename offset ...");
+        System.err.println("ExtractTool [-h] [--payload | --headers] warc-file offset...");
         System.err.println();
         System.err.println("Options:");
         System.err.println();

src/org/netpreserve/jwarc/tools/FilterTool.java

@@ -10,8 +10,8 @@ public class FilterTool {
     public static void main(String[] args) throws Exception {
         try {
             String[] files;
-            if (args.length == 0) {
-                System.err.println("Usage: jwarc filter <expression> [warc-file]...");
+            if (args.length == 0 || Utils.hasHelpFlag(args)) {
+                System.err.println("Usage: jwarc filter <expression> [warc-file...]");
                 System.err.println("  e.g. jwarc filter 'warc-type == \"response\" && http:content-type =~ \"image/.*\" && :status == 200' example.warc");
                 System.exit(1);
                 return;

src/org/netpreserve/jwarc/tools/ListTool.java

@@ -6,7 +6,9 @@
 import java.nio.file.Paths;
 
 public class ListTool {
+
     public static void main(String[] args) throws IOException {
+        Utils.showUsage(args, 1, ListTool.class, "warc-file...", "List records in WARC file(s)");
         for (String arg : args) {
             try (WarcReader reader = new WarcReader(Paths.get(arg))) {
                 for (WarcRecord record : reader) {

src/org/netpreserve/jwarc/tools/RecordTool.java

@@ -11,6 +11,10 @@
 
 public class RecordTool {
     public static void main(String[] args) throws Exception {
+        Utils.showUsage(args, 1, RecordTool.class, "uri...",
+                "Record pages and page dependencies using headless Chrome or the browser executable"
+                        + "\ndefined by the environment variable BROWSER (default: \"google-chrome\")."
+                        + "\n\nWARC output is written to stdout.");
         try (ServerSocket socket = new ServerSocket(0, -1, InetAddress.getLoopbackAddress())) {
             WarcRecorder recorder = new WarcRecorder(socket, new WarcWriter(System.out));
             new Thread(recorder::listen).start();

src/org/netpreserve/jwarc/tools/SavebackTool.java

@@ -57,7 +57,7 @@ public static void main(String[] args) throws IOException {
     }
 
     private static void usage() {
-        System.err.println("Usage: jwarc saveback wayback-url ...");
+        System.err.println("Usage: jwarc saveback wayback-url...");
         System.err.println("Reconstructs WARC records from wayback or pywb replayed pages");
         System.err.println("Intended to be used with the id_ option: .../wayback/20060101010000id_/http://example.org/");
         System.err.println();

src/org/netpreserve/jwarc/tools/ScreenshotTool.java

@@ -13,6 +13,11 @@
 
 public class ScreenshotTool {
     public static void main(String[] args) throws Exception {
+        Utils.showUsage(args, 1, ScreenshotTool.class, "warc-file...",
+                "Take a screenshot of each page in the given WARCs."
+                        + "\n\nThe browser executable defined by the environment variable BROWSER"
+                        + "\nis used to take the screenshots (default: \"google-chrome\")."
+                        + "\n\nWARC output is written to stdout.");
         List<Path> warcs = Stream.of(args).map(Paths::get).collect(Collectors.toList());
         try (WarcWriter warcWriter = new WarcWriter(System.out);
              WarcRenderer renderer = new WarcRenderer(new CaptureIndex(warcs))) {

src/org/netpreserve/jwarc/tools/ServeTool.java

@@ -11,7 +11,7 @@
 
 public class ServeTool {
     public static void main(String[] args) throws Exception {
-        if (args.length == 0) {
+        if (args.length == 0 || Utils.hasHelpFlag(args)) {
             System.err.println("Usage: WarcTool serve <warc-files>");
             System.err.println("Obeys environment variable PORT.");
             System.exit(1);

src/org/netpreserve/jwarc/tools/Utils.java

@@ -3,6 +3,7 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.net.URL;
+import java.util.Arrays;
 import java.util.Properties;
 
 class Utils {
@@ -18,4 +19,23 @@ static String getJwarcVersion() {
         }
         return properties.getProperty("version");
     }
+
+    static boolean hasHelpFlag(String[] args) {
+        return Arrays.stream(args).anyMatch(arg -> arg.equals("-h") || arg.equals("--help") || arg.equals("-?"));
+    }
+
+    static void showUsage(String[] args, int minArgs, Class<?> cls, String arguments, String description) {
+        if (hasHelpFlag(args) || args.length < minArgs) {
+            System.err.println("");
+            System.err.println(cls.getSimpleName() + " [-h] " + arguments);
+            System.err.println("");
+            System.err.println(description);
+            System.err.println("");
+            System.err.println("Options:");
+            System.err.println("");
+            System.err.println(" -h / --help\tshow usage message and exit");
+            System.err.println("");
+            System.exit(0);
+        }
+    }
 }

src/org/netpreserve/jwarc/tools/ValidateTool.java

@@ -23,7 +23,7 @@
 import java.util.function.Consumer;
 
 
-public class ValidateTool extends WarcTool {
+public class ValidateTool {
 
     private final static MediaType DNS = MediaType.parse("text/dns");
 
@@ -294,7 +294,7 @@ boolean validate(Path warcFile) {
 
     private static void usage(int exitValue) {
         System.err.println("");
-        System.err.println("ValidateTool [-h] [-v] filename...");
+        System.err.println("ValidateTool [-h] [-v] warc-file...");
         System.err.println("");
         System.err.println("Options:");
         System.err.println("");