Start adding support for positional arguments in Man help (#91)

airline-help/airline-help-man/src/main/java/com/github/rvesse/airline/help/man/ManCommandUsageGenerator.java

@@ -131,7 +131,7 @@ protected <T> void outputOptions(TroffPrinter printer, CommandMetadata command,
 
         // Arguments
         // Must start the list if there are no visible options
-        helper.outputArguments(printer, command.getArguments(), optionsOutput == 0, parserConfig);
+        helper.outputArguments(printer, command.getPositionalArguments(), command.getArguments(), optionsOutput == 0, parserConfig);
     }
 
     /**
@@ -204,7 +204,7 @@ protected List<OptionMetadata> outputSynopsis(TroffPrinter printer, String progr
             printer.print(" [ ");
             printer.printBold("--");
             printer.print(" ] ");
-            this.helper.outputArgumentsSynopsis(printer, command.getArguments());
+            this.helper.outputArgumentsSynopsis(printer, command.getPositionalArguments(), command.getArguments());
         }
 
         printer.println();

airline-help/airline-help-man/src/main/java/com/github/rvesse/airline/help/man/ManUsageHelper.java

@@ -33,6 +33,7 @@
 import com.github.rvesse.airline.model.ArgumentsMetadata;
 import com.github.rvesse.airline.model.OptionMetadata;
 import com.github.rvesse.airline.model.ParserMetadata;
+import com.github.rvesse.airline.model.PositionalArgumentMetadata;
 import com.github.rvesse.airline.restrictions.ArgumentsRestriction;
 import com.github.rvesse.airline.restrictions.OptionRestriction;
 
@@ -90,11 +91,12 @@ public int outputOptions(TroffPrinter printer, List<OptionMetadata> options, boo
         return output;
     }
 
-    public <T> void outputArguments(TroffPrinter printer, ArgumentsMetadata arguments, boolean startList,
+    public <T> void outputArguments(TroffPrinter printer, List<PositionalArgumentMetadata> posArgs, ArgumentsMetadata arguments, boolean startList,
             ParserMetadata<T> parserConfig) throws IOException {
-        if (arguments != null) {
+        boolean needsArgsSeparator = (posArgs != null && posArgs.size() > 0) || arguments != null;
+
+        if (needsArgsSeparator) {
             // Arguments separator option
-
             if (startList) {
                 printer.startTitledList();
             } else {
@@ -108,6 +110,33 @@ public <T> void outputArguments(TroffPrinter printer, ArgumentsMetadata argument
             printer.println(
                     "This option can be used to separate command-line options from the list of arguments (useful when arguments might be mistaken for command-line options)");
             printer.endList();
+        } else {
+            return;
+        }
+
+        if (posArgs != null && posArgs.size() > 0) {
+            for (PositionalArgumentMetadata posArg : posArgs) {
+                // Argument name
+                printer.nextTitledListItem();
+                printer.printItalic(posArg.getTitle());
+
+                // Description
+                printer.startPlainList();
+                printer.println(posArg.getDescription());
+
+                // Restrictions
+                List<HelpHint> hints = sortArgumentsRestrictions(arguments.getRestrictions());
+                for (HelpHint hint : hints) {
+                    // Safe to cast back to ArgumentsRestriction as must have come
+                    // from an ArgumentsRestriction to start with
+                    outputArgumentsRestriction(printer, arguments, (ArgumentsRestriction) hint, hint);
+                }
+                printer.endList();
+            }
+        }
+
+        if (arguments != null) {
+
 
             // Arguments name(s)
             printer.nextTitledListItem();
@@ -125,9 +154,10 @@ public <T> void outputArguments(TroffPrinter printer, ArgumentsMetadata argument
                 outputArgumentsRestriction(printer, arguments, (ArgumentsRestriction) hint, hint);
             }
             printer.endList();
-
-            printer.endList();
         }
+
+        // End list of options and arguments
+        printer.endList();
     }
 
     /**
@@ -175,7 +205,8 @@ protected void outputArgumentsRestriction(TroffPrinter printer, ArgumentsMetadat
      *            Troff printer
      * @param section
      *            Help section
-     * @throws IOException Thrown if there is a problem generating usage output
+     * @throws IOException
+     *             Thrown if there is a problem generating usage output
      */
     public void outputHelpSection(TroffPrinter printer, HelpSection section) throws IOException {
         if (section.getFormat() == HelpFormat.NONE_PRINTABLE)
@@ -332,18 +363,37 @@ public void outputOptionSynopsis(TroffPrinter printer, OptionMetadata option) {
         }
     }
 
-    public void outputArgumentsSynopsis(TroffPrinter printer, ArgumentsMetadata arguments) {
-        if (!arguments.isRequired()) {
-            printer.print("[ ");
+    public void outputArgumentsSynopsis(TroffPrinter printer, List<PositionalArgumentMetadata> posArgs,
+            ArgumentsMetadata arguments) {
+        if (posArgs != null) {
+            for (PositionalArgumentMetadata posArg : posArgs) {
+                if (!posArg.isRequired()) {
+                    printer.print("[ ");
+                }
+                printer.printItalic(posArg.getTitle());
+                printer.print(" ");
+                if (!posArg.isRequired()) {
+                    printer.print("]");
+                }
+            }
         }
 
-        for (String title : arguments.getTitle()) {
-            printer.printItalic(title);
-            printer.print(" ");
-        }
+        if (arguments != null) {
+            if (posArgs != null && posArgs.size() > 0) {
+                printer.print(" ");
+            }
+            if (!arguments.isRequired()) {
+                printer.print("[ ");
+            }
 
-        if (!arguments.isRequired()) {
-            printer.print("]");
+            for (String title : arguments.getTitle()) {
+                printer.printItalic(title);
+                printer.print(" ");
+            }
+
+            if (!arguments.isRequired()) {
+                printer.print("]");
+            }
         }
     }
 

airline-help/airline-help-man/src/test/java/com/github/rvesse/airline/help/man/ArgsManPositionalArgs.java

@@ -0,0 +1,37 @@
+/**
+ * Copyright (C) 2010-16 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.github.rvesse.airline.help.man;
+
+import java.util.List;
+
+import com.github.rvesse.airline.annotations.Arguments;
+import com.github.rvesse.airline.annotations.Command;
+import com.github.rvesse.airline.annotations.PositionalArgument;
+import com.github.rvesse.airline.annotations.restrictions.Required;
+
+@Command(name = "args-man-pos-args")
+public class ArgsManPositionalArgs {
+
+    @PositionalArgument(title = "File", position = PositionalArgument.FIRST, description = "File to operate on")
+    @Required
+    public String file;
+
+    @PositionalArgument(title = "Mode", position = PositionalArgument.SECOND, description = "File mode to set")
+    public Integer mode;
+
+    @Arguments(title = "ExtraArg", description = "Additional arguments")
+    public List<String> arguments;
+}

airline-help/airline-help-man/src/test/java/com/github/rvesse/airline/help/man/TestHelpMan.java

@@ -914,6 +914,41 @@ public void testManArgsOnly_01() throws IOException {
         //@formatter:on
     }
 
+    public void testManArgsOnly_02() throws IOException {
+        SingleCommand<ArgsManPositionalArgs> command = singleCommand(ArgsManPositionalArgs.class);
+        ByteArrayOutputStream out = new ByteArrayOutputStream();
+        new ManCommandUsageGenerator().usage(null, null, "test", command.getCommandMetadata(), null, out);
+
+        //@formatter:off
+        assertEquals(new String(out.toByteArray(), utf8),
+                StringUtils.join(new String[] {
+                        ".TH \"test\" \"1\" \"\" \"\" \"\"",
+                        ".SH NAME",
+                        ".IP \"\" 0",
+                        "\\fBtest\\fR",
+                        ".SH SYNOPSIS",
+                        ".IP \"\" 0",
+                        "\\fBtest\\fR  [ \\fB\\-\\-\\fR ] \\fIFile\\fR [ \\fIMode\\fR ] [ \\fIExtraArg\\fR ]",
+                        ".SH OPTIONS",
+                        ".RS",
+                        ".TP",
+                        "\\fB\\-\\-\\fR",
+                        ".RS",
+                        ".IP \"\" 4",
+                        "This option can be used to separate command\\-line options from the list of arguments (useful when arguments might be mistaken for command\\-line options)",
+                        ".RE",
+                        ".TP",
+                        "\\fIExtraArg\\fR",
+                        ".RS",
+                        ".IP \"\" 4",
+                        "Additional arguments",
+                        ".RE",
+                        ".IP \"\" 0",
+                        ""
+                }, '\n'));
+        //@formatter:on
+    }
+
     public void testManNone_01() throws IOException {
         SingleCommand<ArgsManNone> command = singleCommand(ArgsManNone.class);
         ByteArrayOutputStream out = new ByteArrayOutputStream();