High Level API

Now we are going to build a program that displays words passed as arguments surrounded by stars. Star number can be changed by a command line option.

 1 (*stars.pas*)
 2 program Stars;
 3 {$mode objfpc}{$h+}
 4 uses
 5   Classes, CmdLine, SysUtils;
 6
 7 var
 8   ShowHelp : Boolean;
 9   NStars : LongInt = 1;
10   I: Integer;
11   S : String;
12 begin
13   DefineSimpleOption('h', 'help', @ShowHelp, 'display help and exit.',
14     [ofStopScan]);
15   DefineLongIntOption('s', 'stars', @NStars, 'number of stars', 'INT',
16     [ofOnlyOnce]);
17
18   InitializeCommandLineScan;
19
20   try
21     ScanCommandLine;
22   except
23     on E: ECmdLineError do
24     begin
25       WriteErrorMessage(E.Message, true);
26       Halt(1);
27     end;
28   end;
29   WriteLn('NStars=', NStars, '[', Low(LongInt), '..', High(LongInt), ']');
30   if ShowHelp then
31     DisplayHelp
32   else
33   begin
34     for I := 1 to ArgumentCount do
35     begin
36       if NStars > 0 then
37         S := StringOfChar('*', NStars)
38       else
39         S := '';
40
41       WriteLn(S, ArgumentStr(I), S);
42     end;
43   end;
44
45   FinalizeCommandLineScan;
46 end.

Lines 7-8: We create two variables, ShowHelp and NStars, that will be updated automatically according to the parameters read on the command line.

Line 13: We create the option that will be used to display help. It's a simple option, ie an option for wich we only want to know if its present or not. The first parameter ('h') is the short option char. For options without short option char #0 should be used. The second parameter is the long option string. It can be an empty string if there is no long option. The third parameter is the address of a boolean that will be set to true if the option is present and set to false otherwise. The fourth parameter is an help string wich is displayed when DisplayHelp is called. The last parameters tells to the command line scanner that it has to stop when this option is encountered.

Line 14: Now we create the option that will set the number of stars to show. It is a longint option, ie an option that expects an integer value in the range [-2147483648..2147483647]. The first parameter ('s') is the short option char. For options without short option char #0 should be used. The second parameter is the long option string. It can be an empty string if there is no long option. The third parameter is the address of a longint that will be set to the option value if present and left untouched otherwise. The fourth and fifth parameters are used when DisplayHelp is called. The sixth parameter tells the scanner that this option can appear only once on the command line.

Line 18: Once all options are defined, we initialize the scanner by calling InitializeCommandLineScan.

Line 21: Now we run the scanner.

Lines 23-27: If the scan fails it throws a ECmdLineError exception. We catch it, and print an error message and an invitation to display help for the command (WriteErrorMessage).

Lines 30-31: We display the command help page, if necessary, by calling DisplayHelp.

Lines 34-42: Now we display each argument surrounded the required number of stars.Arguments are all the elements of the command line which have not been recognized until now.

Line 45: Calling FinalizeCommandLineScan is optional unless you want to define new option and start a new command line analysis.

This program is short but powerful. It can be run without parameter :

------------------------------------------------------------------------------
~$ ./stars fpc lazarus
*fpc*
*lazarus*
------------------------------------------------------------------------------

It accepts several ways to ask for 5 stars :

------------------------------------------------------------------------------
~$ ./stars -s 5 fpc lazarus
~$ ./stars -s=5 fpc lazarus
~$ ./stars -s5 fpc lazarus
~$ ./stars --stars=5 fpc lazarus
~$ ./stars --stars 5 fpc lazarus
------------------------------------------------------------------------------

In case of error it displays a classical error message.

------------------------------------------------------------------------------
~$ ./stars -z fpc lazarus
stars: unrecognized option '-z'
Try `stars --help' for more information.
------------------------------------------------------------------------------

It displays a classical help screen when needed.

------------------------------------------------------------------------------
~$ ./stars --help
Usage: stars [OPTIONS] [ARGUMENTS]
Options:
  -h, --help       display this help and exit.
  -s, --stars=INT  number of stars
------------------------------------------------------------------------------