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

[James Richters]

That sounds like a great idea!!  Yes I know how tedious it is.    Here are some things I like to do.

I always use color on my console app text…  Yes it makes it more tedious because I have to have a whole bunch of textcolor() commands, but it makes it more readable and useful. I also like to center justify the list, so there is a clear division of commands on the left of the justification and definitions on the right.  Here is an example:
https://drive.google.com/file/d/1cyEqPUh-CkGYwP8VHXnKPtYwYpH5_ZRY/view?usp=sharing


I also like to use box characters around my help boxes.. and of course in a way that makes the task even more tedious... I am only happy if the box has an exactly one character space between the box and the widest entry... and again using color so the box and the contents of the box are all different colors like this:
https://drive.google.com/file/d/1cD5r3tIJWdFCQVwIFpKvtQ5LyD6uEnWL/view?usp=sharing

Yes I know my formatting is off…  if it wasn’t so tedious I would fix it  :)   I skip the box characters a lot of times because they are so tedious, but I would prefer them… if only there was some automated way to generate a nice clean help menu with a nice even box around it with exactly one space between the box and the widest entry….. 

For the title, I rename the window title with SetConsoleTitle()
I use colors in the version.  Here is an example of both of these:
https://drive.google.com/file/d/1c5oHb6S2MO3x-cMNMwd2U9GQJCqGnTYt/view?usp=sharing

so as you can see, my #1 item in my wish list is the ability to assign colors, but I don’t know if that’s cross platform.. Can Linux even change colors in the console window?   Almost all my programs are on Windows 10.  I also don’t know if SetConsoleTitle() can be done cross platform, that might be a windows function as well.


James


-----Original Message-----
From: fpc-pascal <fpc-pascal-bounces at lists.freepascal.org> On Behalf Of Graeme Geldenhuys via fpc-pascal
Sent: Thursday, November 19, 2020 7:33 PM
To: FPC-Pascal users discussions <fpc-pascal at lists.freepascal.org>
Cc: Graeme Geldenhuys <mailinglists at geldenhuys.co.uk>
Subject: [fpc-pascal] I'm working on automated Help Output for console apps

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 _______________________________________________
fpc-pascal maillist  -  fpc-pascal at lists.freepascal.org <mailto:fpc-pascal at lists.freepascal.org>  https://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freepascal.org/pipermail/fpc-pascal/attachments/20201120/81352de3/attachment-0001.htm>