Document command-line tools

Affects: #73
io7m-com · Sep 29, 2024 · eb60707 · eb60707
1 parent 7a07a60
commit eb60707
Show file tree

Hide file tree

Showing 20 changed files with 693 additions and 7 deletions.
diff --git a/com.io7m.laurel.cmdline/pom.xml b/com.io7m.laurel.cmdline/pom.xml
@@ -38,10 +38,6 @@
       <groupId>com.io7m.quarrel</groupId>
       <artifactId>com.io7m.quarrel.ext.logback</artifactId>
     </dependency>
-    <dependency>
-      <groupId>com.io7m.quarrel</groupId>
-      <artifactId>com.io7m.quarrel.ext.xstructural</artifactId>
-    </dependency>
     <dependency>
       <groupId>com.io7m.seltzer</groupId>
       <artifactId>com.io7m.seltzer.api</artifactId>
@@ -81,7 +77,6 @@
         <configuration>
           <failOnWarning>true</failOnWarning>
           <ignoredUnusedDeclaredDependencies>
-            <ignoredUnusedDeclaredDependency> com.io7m.quarrel:com.io7m.quarrel.ext.xstructural::*</ignoredUnusedDeclaredDependency>
             <ignoredUnusedDeclaredDependency>ch.qos.logback:logback-classic::*</ignoredUnusedDeclaredDependency>
           </ignoredUnusedDeclaredDependencies>
         </configuration>

diff --git a/com.io7m.laurel.cmdline/src/main/java/module-info.java b/com.io7m.laurel.cmdline/src/main/java/module-info.java
@@ -30,4 +30,7 @@
   requires com.io7m.quarrel.ext.logback;
 
   exports com.io7m.laurel.cmdline;
+
+  exports com.io7m.laurel.cmdline.internal
+    to com.io7m.laurel.tests;
 }
diff --git a/com.io7m.laurel.documentation/pom.xml b/com.io7m.laurel.documentation/pom.xml
@@ -22,6 +22,11 @@
   </properties>
 
   <dependencies>
+    <dependency>
+      <groupId>${project.groupId}</groupId>
+      <artifactId>com.io7m.laurel.cmdline</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>${project.groupId}</groupId>
       <artifactId>com.io7m.laurel.filemodel</artifactId>

diff --git a/com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/at-syntax.txt b/com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/at-syntax.txt
@@ -0,0 +1,12 @@
+$ laurel import --input-directory /tmp/data --output-file output.ldb
+
+$ (cat <<EOF
+import
+--input-directory
+/tmp/data
+--output-file
+output.ldb
+EOF
+) > args.txt
+
+$ laurel @args.txt
diff --git a/com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/cmdline.xml b/com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/cmdline.xml
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<Section xmlns="urn:com.io7m.structural:8:0"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         title="Command-Line Interface">
+
+  <Section title="Overview">
+    <Paragraph>
+      The <Term type="package">laurel</Term> package provides a command-line interface for performing tasks such as
+      importing and exporting datasets. The base
+      <Term type="command">laurel</Term>
+      command is broken into a number of subcommands which are documented over the following sections.
+    </Paragraph>
+    <FormalItem title="Command-Line Overview">
+      <Verbatim>
+        <xi:include parse="text"
+                    href="usage.txt"/>
+      </Verbatim>
+    </FormalItem>
+    <Paragraph>
+      All subcommands accept a <Term type="parameter">--verbose</Term> parameter that may be set to one of
+      <Term type="constant">trace</Term>, <Term type="constant">debug</Term>, <Term type="constant">info</Term>,
+      <Term type="constant">warn</Term>, or <Term type="constant">error</Term>. This parameter sets the lower bound for
+      the severity of messages that will be logged. For example, at <Term type="constant">debug</Term> verbosity, only
+      messages of severity <Term type="constant">debug</Term> and above will be logged. Setting the verbosity to
+      <Term type="constant">trace</Term>
+      level effectively causes everything to be logged, and will produce large volumes of debugging output.
+    </Paragraph>
+    <Paragraph id="ec6fd8d1-a6ae-4a4f-b478-48963f6a9ad9">
+      The <Term type="package">laurel</Term> command-line tool uses
+      <LinkExternal target="https://www.io7m.com/software/quarrel/">quarrel</LinkExternal>
+      to parse command-line arguments, and therefore supports placing command-line arguments into a file, one argument
+      per line, and then referencing that file with <Term type="constant">@</Term>. For example:
+    </Paragraph>
+    <FormalItem title="@ Syntax">
+      <Verbatim>
+        <xi:include parse="text"
+                    href="at-syntax.txt"/>
+      </Verbatim>
+    </FormalItem>
+    <Paragraph>
+      All subcommands, unless otherwise specified, yield an exit code of <Term type="constant">0</Term> on success, and
+      a non-zero exit code on failure.
+    </Paragraph>
+  </Section>
+
+  <xi:include href="scmd-import.xml"/>
+  <xi:include href="scmd-export.xml"/>
+
+</Section>
diff --git a/com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/document.css b/com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/document.css
@@ -27,6 +27,7 @@
 }
 
 .button,
+.class,
 .command,
 .constant,
 .element,

diff --git a/...io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/i-captions.xml b/...io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/i-captions.xml
@@ -22,7 +22,7 @@ caption ::= [a-z0-9A-Z_-][a-z0-9A-Z_ \-']*
     </FormalItem>
   </Subsection>
 
-  <Subsection title="Caption Files">
+  <Subsection title="Caption Files" id="d2969342-a3a7-4f8b-88aa-529b09291d61">
     <Paragraph>
       A <Term type="term">caption file</Term> is a file consisting of a comma-separated list of captions. More
       formally, the file conforms to the following format:

diff --git a/com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/main.xml b/com.io7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/main.xml
@@ -22,6 +22,7 @@
   <xi:include href="overview.xml"/>
   <xi:include href="install.xml"/>
   <xi:include href="usage.xml"/>
+  <xi:include href="cmdline.xml"/>
   <xi:include href="implementation.xml"/>
   <xi:include href="license.xml"/>
   <xi:include href="colophon.xml"/>

diff --git a/...documentation/src/main/resources/com/io7m/laurel/documentation/scmd-export-parameters.xml b/...documentation/src/main/resources/com/io7m/laurel/documentation/scmd-export-parameters.xml
@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<Subsection title="Parameters" xmlns="urn:com.io7m.structural:8:0">
+  <FormalItem id="646cbe0e-d54a-3fa0-a90e-7216c452f086" title="--export-images">
+    <Table type="genericTable">
+      <Columns>
+        <Column>Attribute</Column>
+        <Column>Value</Column>
+      </Columns>
+      <Row>
+        <Cell>Name</Cell>
+        <Cell>
+          <Term type="parameter">--export-images</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Type</Cell>
+        <Cell>
+          <Term type="class">java.lang.Boolean</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Default Value</Cell>
+        <Cell>
+          <Term type="constant">true</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Cardinality</Cell>
+        <Cell>
+          <Term type="expression">[1, 1]</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Description</Cell>
+        <Cell>Whether to export images.</Cell>
+      </Row>
+    </Table>
+  </FormalItem>
+  <FormalItem id="af894109-8bbe-39bb-9d1d-93945cdde56f" title="--input-file">
+    <Table type="genericTable">
+      <Columns>
+        <Column>Attribute</Column>
+        <Column>Value</Column>
+      </Columns>
+      <Row>
+        <Cell>Name</Cell>
+        <Cell>
+          <Term type="parameter">--input-file</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Type</Cell>
+        <Cell>
+          <Term type="class">java.nio.file.Path</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Default Value</Cell>
+        <Cell>
+          <Term type="constant"/>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Cardinality</Cell>
+        <Cell>
+          <Term type="expression">[1, 1]</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Description</Cell>
+        <Cell>The input file.</Cell>
+      </Row>
+    </Table>
+  </FormalItem>
+  <FormalItem id="6d3c6a25-699f-3d77-bb00-83a3a5976968" title="--output-directory">
+    <Table type="genericTable">
+      <Columns>
+        <Column>Attribute</Column>
+        <Column>Value</Column>
+      </Columns>
+      <Row>
+        <Cell>Name</Cell>
+        <Cell>
+          <Term type="parameter">--output-directory</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Type</Cell>
+        <Cell>
+          <Term type="class">java.nio.file.Path</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Default Value</Cell>
+        <Cell>
+          <Term type="constant"/>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Cardinality</Cell>
+        <Cell>
+          <Term type="expression">[1, 1]</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Description</Cell>
+        <Cell>The output directory.</Cell>
+      </Row>
+    </Table>
+  </FormalItem>
+  <FormalItem id="0dfd136c-e324-32de-a7c6-388548b84e81" title="--verbose">
+    <Table type="genericTable">
+      <Columns>
+        <Column>Attribute</Column>
+        <Column>Value</Column>
+      </Columns>
+      <Row>
+        <Cell>Name</Cell>
+        <Cell>
+          <Term type="parameter">--verbose</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Type</Cell>
+        <Cell>
+          <Term type="class">com.io7m.quarrel.ext.logback.QLogLevel</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Default Value</Cell>
+        <Cell>
+          <Term type="constant">info</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Cardinality</Cell>
+        <Cell>
+          <Term type="expression">[1, 1]</Term>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell>Description</Cell>
+        <Cell>Set the logging level of the application.</Cell>
+      </Row>
+    </Table>
+  </FormalItem>
+</Subsection>
+
diff --git a/...o7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/scmd-export.xml b/...o7m.laurel.documentation/src/main/resources/com/io7m/laurel/documentation/scmd-export.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<Section xmlns:xi="http://www.w3.org/2001/XInclude" id="bbb8a295-eafb-34e4-b07f-9c7559dd3f95" title="export" xmlns="urn:com.io7m.structural:8:0">
+  <Subsection title="Name">
+    <Paragraph>
+      <Term type="command">export</Term>
+       - Export a dataset into a directory.
+    </Paragraph>
+  </Subsection>
+  <Subsection title="Description">
+    <Paragraph>
+      The 
+      <Term type="command">export</Term>
+       command
+      <Link target="f96c87eb-84a3-4437-bcf7-f1cc338eed00">exports</Link>
+      a dataset.
+    </Paragraph>
+  </Subsection>
+  <xi:include href="scmd-export-parameters.xml"/>
+  <Subsection title="Examples">
+    <FormalItem title="Example" type="example">
+      <Verbatim><![CDATA[
+$ quarrel export --input-file example.ldb --output-directory /tmp/dataset
+]]></Verbatim>
+    </FormalItem>
+  </Subsection>
+</Section>
+