[fpc-pascal] I'm working on automated Help Output for console apps

[Graeme Geldenhuys]

Hi,

I'm working on a automated help output writer(s) for console apps.
Thus no more tedious and ugly output when you do: myapp -h

My aims:
 * I write a lot of console apps, so this would be very useful to me.
 * Ability to swap out the help formatter. It's interface based, so
   custom implementations can easily be created.
 * Auto align help options and descriptions - the most annoying thing to
   do manually. ;-)
 * Ability to define console width in which to format and wrap the help
   output, but has a default value.
 * The idea is loosely base on the Java version found in Apache Commons.

When it's done I'll obviously shared it as open source somewhere.

With that said, below is how I currently use it. It uses the Builder design
pattern so gives it the Chain Invocations syntax. I know it's not something
often seen in Pascal programs, but it makes it very easy to read and easy
to use/type, especially with code completion editors like Lazarus IDE.

For those console programmers out there... Is there anything in console help
output that you like or wish you had. That way I could possibly add it and
make this even more useful to a wider audience.

I'm still working on AppName, Version and Usage output.

Example code:
==========================
var
  optionlist: TOptions;
  helpFormatter: IHelpFormatter;
  header: string;
  footer: string;
begin
  optionlist := TOptions.Create;

  optionlist.add(TOption.Builder
            .isRequired
            .withDescription('The file to be processed')
            .hasArg
            .withArgName('file')
            .withLongOpt('file')
            .build('f'));    // build() always takes the mandatory short option.

  optionlist.add(TOption.Builder
            .withLongOpt('help')
            .withArgName('test')  // this is ignored because .hasArg was not specified
            .build('h'));

  optionlist.add(TOption.Builder
            .withDescription('Print the version of the application')
            .withLongOpt('version')
            .build('v'));

  header := 'Do something useful with an input file' + LineEnding;
  footer := LineEnding + 'Please report issues at http://example.com/issues';

  helpFormatter := TBasicHelpFormatter.Create();

  // sample outputs with increasing verbosity

  writeln('===========================   (1)');
  helpFormatter.printHelp(optionlist);

  writeln('===========================   (2)');
  helpFormatter.printHelp('DocView v1.0', optionlist);

  writeln('===========================   (3)');
  helpFormatter.printHelp('DocView v1.0', header, optionlist, footer);

  writeln('========== the end =================');
  optionlist.Free;
end;
==========================


And here is the example output for the 3 options so far:

===========================   (1)
* -f,--file <FILE>    The file to be processed
  -h,--help
  -v,--version        Print the version of the application

* indicates required parameters
===========================   (2)
DocView v1.0
* -f,--file <FILE>    The file to be processed
  -h,--help
  -v,--version        Print the version of the application

* indicates required parameters
===========================   (3)
DocView v1.0
Do something useful with an input file

* -f,--file <FILE>    The file to be processed
  -h,--help
  -v,--version        Print the version of the application

* indicates required parameters

Please report issues at http://example.com/issues
========== the end =================



Regards,
  Graeme

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://fpgui.sourceforge.net/

My public PGP key:  http://tinyurl.com/graeme-pgp