sfuhrm/args2all

Converts args4j/JCommander descriptor classes to markdown or manpages

Args2All

Converts machine readable command line parser library class annotations (args4j, JCommander) into a variety of human readable text documents. To put it in other words: You document your options for i.e. args4j, and then you can extract the information for other documents using this tool from your Java classes.

The main purpose is to reduce overhead when documenting software.

Two examples can be seen below.

Command line parsing libraries supported

Currently the following command line libraries are supported:

• Args4j
• JCommander
• PicoCLI

Command line options

Usage is as follows:

java -jar target/args2all-0.0.1-jar-with-dependencies.jar <OPTIONS>

Where the possible options are listed here (args2all-generated):

• -charset, -C = CHARSET

  The charset encoding to use for the output file.

• -class, -c = CLASS

  Name of the annotated class to read. The annotations are from a library like args4j or JCommander. Note that the class must be loadable from the programs context, meaning reachable from the classpath.

  Required

• -help, -h

  Show the command line help.

• -out, -o = FILE

  The output where to write the result to.

  Required

• -template, -t

  The template to use for output. This is the output flavor you are desiring to generate.

Output formats supported

The all in Args2all is quite limited at the moment. Please read the current options in the next sections.

Markdown

Outputs a markdown text that is inspired by the layout of UN*X manual pages.

Here's an example of the program itself:

Markdown code can be seen here.

Manpage

Outputs a partial manual page / troff page that can be used as a template. The parts of the file that need to be filled are marked as pseudo-variables, for example $DESCRIPTION.

Here's an example of the program itself:

Manpage code can be seen here.

XML

Outputs a XML dump that can be used for example in XML stylesheets.

XML page example is located here.

Warnings

It is possible that the library versions used with Args2all are not compatible with the versions you're using in the classes you've compiled. To get around this problem, adjust the problematic library versions to be the same on both sides.

License

Copyright 2017 Stephan Fuhrmann

Licensed under the GNU GENERAL PUBLIC LICENSE 2.0. Please see the licensing conditions under LICENSE or at https://www.gnu.org/licenses/gpl-2.0.html.

args2all's Issues

Create i18n / translation templates

Use the existing CLI options to create templates for other languages, following the idea of Java resource bundles.

Standards validation for command line options

Validate the command line options against certain rules.
Examples:

• "-h" is usually equivalent to "-help" or "--help" and should have the help flag set
• "-v" is verbose
• no wild mixing of "-foo" and "--foo"

Picocli cooperation

I like the args2all initiative very much! Don't hesitate to let me know if there is any way picocli can be improved to make life easier for args2all.

For example, you might be interested in using some of the classes in the picocli Help API to do text layout or use ANSI colours. If you want these to be more generic I’m open for suggestions.

If args2all is ready to open to the public I can link to it from the picocli project landing page (the readme).

That’s just some examples, other ideas welcome.

Bash Completion generator

Create Bash completion files after reading the Java CLI annotations.

Convert argslibrary1 to argslibrary2

Create a converter from one args library to another (i.e. args4j to picocli).
Think of the situation you want to have a single args library in your enterprise used and want to convert misc projects to this library.

The task "just" requires to write output templates for each args library.