Class TCommandLineReader

Description
Hierarchy
Fields
Methods
Properties

Unit

rcmdline

Declaration

type TCommandLineReader = class(TObject)

Description

A command line reader class that checks for valid arguments and automatically prints a formatted help.



Usage:

  1. Declare all allowed arguments with the corresponding DeclareXXXX functions

  2. Call parse to explicitely read the actual command line (optionally)

  3. Use readXXX to read a declared argument

On the command line arguments can be given in different ways, e.g. 

--name=value
/name=value
--name value
/name value
--name="value"
/name="value"

Declared flags can be changed with –enable-flag or –disable-flag or –flag where latter option negates the default value.
File names are checked for spaces, so it is not always necessary to surround them with quotes.

Internally, the allowed command line arguments are called both "properties" and "options".

Example: 

var cmdline: TCommandLineReader;
begin
  cmdline := TCommandLineReader.create;

  //Initial declaration of some command line parameters:
  cmdline.declareString('name', 'An example string property');
  cmdline.declareString('foo', 'Another example string property', 'bar');
  cmdline.declareInt('count', 'An example integer property', 123);
  cmdline.declareFlag('flag', 'An example boolean property');

  //cmdline.parse();



  //1. Parsing some command line options
  cmdline.parse('--name="some name" --count 9');

  cmdline.readString('name'); //some name
  cmdline.readString('foo');  //bar
  cmdline.readInt('count');   //9
  cmdline.readFlag('flag');   //false

  cmdline.existsProperty('name'); //true
  cmdline.existsProperty('foo');  //false




  //2. Parsing some other command line options
  cmdline.parse('--foo barbar --flag');

  cmdline.readString('name'); //
  cmdline.readString('foo');  //barbar
  cmdline.readInt('count');   //123
  cmdline.readFlag('flag');   //true

  cmdline.existsProperty('name'); //false
  cmdline.existsProperty('foo');  //true




  //3. Parsing some other command line options
  cmdline.parse('--help');

  //prints automatically generated help to stdout and halts:
  {
  The following command line options are valid:

  --name=<string> 	An example string property
  --foo=<string>  	Another example string property (default: bar)
  --count=<int>   	An example integer property (default: 123)
  --flag          	An example boolean property
  }




  //4. Some more advanced usage
  cmdline.addAbbreviation('f'); //abbreviation for the last option (--flag)
  cmdline.allowDOSStyle := true; //DOS slash options. Default is only true on Windows

  cmdline.parse('/name "x y z" -f /count=1 /foo="abc"');
  cmdline.readString('name'); //x y z
  cmdline.readString('foo');  //abc
  cmdline.readInt('count');   //1
  cmdline.readFlag('flag');   //true

  cmdline.existsProperty('name'); //true
  cmdline.existsProperty('foo');  //true

Hierarchy

Overview

Fields

Public language:TCommandLineReaderLanguage;
Public onShowError: TCommandLineReaderShowError;
Public showErrorAutomatically: boolean;
Public allowDOSStyle: boolean;

Methods

Public constructor create;
Public destructor destroy; override;
Public function availableOptions:string;
Public procedure reset();
Public procedure parse(autoReset: boolean = true); overload; virtual;
Public procedure parse(const s:string; skipFirst: boolean = false; autoReset: boolean = true); overload; virtual;
Public procedure parse(const args:TStringArray; autoReset: boolean = true); overload; virtual;
Public procedure beginDeclarationCategory(category: string);
Public procedure declareFlag(const name,description:string;flagNameAbbreviation:char;default:boolean=false); overload;
Public procedure declareFlag(const name,description:string;default:boolean=false); overload;
Public procedure declareFile(const name,description:string;default:string=''); overload;
Public procedure declareInt(const name,description:string;value: longint=0); overload;
Public procedure declareString(const name,description:string;value: string=''); overload;
Public procedure declareFloat(const name,description:string;value: extended=0); overload;
Public procedure addAbbreviation(const abbreviation: char; const originalName: string = '');
Public procedure addEnumerationValues(const originalName: string; const enumeration: array of string); overload;
Public procedure addEnumerationValues(const enumeration: array of string); overload;
Public function readString(const name:string):string; overload;
Public function readInt(const name:string):longint; overload;
Public function readFloat(const name:string):extended; overload;
Public function readFlag(const name:string):boolean; overload;
Public function existsProperty(const name:string):boolean;
Public function readNamelessFiles():TStringArray;
Public function readNamelessString():TStringArray;
Public function readNamelessInt():TLongintArray;
Public function readNamelessFloat():TFloatArray;
Public function readNamelessFlag():TBooleanArray;

Properties

Public property onOptionRead: TOptionReadEvent read FOnOptionRead write FOnOptionRead;
Public property onCustomOptionInterpretation: TOptionInterpretationEvent read FOnOptionInterpretation write FOnOptionInterpretation;
Public property allowOverrides: boolean read FAllowOverrides write FAllowOverrides;

Description

Fields

Public language:TCommandLineReaderLanguage;
 
Public onShowError: TCommandLineReaderShowError;

Event called when an invalid option is found during parsing of the command line.

Public showErrorAutomatically: boolean;

Automatically show an error message when the parsing finds an invalid option.

Public allowDOSStyle: boolean;

Allow /name value option syntax.

Methods

Public constructor create;
 
Public destructor destroy; override;
 
Public function availableOptions:string;

Returns a human-readable summary about the declared options.
It is automatically printed when an unknown option is given by the user.

Public procedure reset();

Resets all options to their default values.

Public procedure parse(autoReset: boolean = true); overload; virtual;

Reads the standard command line parameters.

Public procedure parse(const s:string; skipFirst: boolean = false; autoReset: boolean = true); overload; virtual;

Reads the command line parameters from the string s.

Public procedure parse(const args:TStringArray; autoReset: boolean = true); overload; virtual;

Reads the command line parameters from the array args.

Public procedure beginDeclarationCategory(category: string);

Adds a new option category. The category is printed in the –help and availableOptions output

Public procedure declareFlag(const name,description:string;flagNameAbbreviation:char;default:boolean=false); overload;

DeclareFlag declares a boolean property.
Example:
declareFlag('flag', 'description', 'f', true);
Following command-line options are then allowed: 

--enable-flag      =>     flag:=true
--disable-flag     =>     flag:=false
--flag             =>     flag:=not default
-xfy               =>     flag:=not default  (when flags x and y have also been declared)

Public procedure declareFlag(const name,description:string;default:boolean=false); overload;

Overloaded DeclareFlag without a single letter abbreviation.

Public procedure declareFile(const name,description:string;default:string=''); overload;

DeclareFile declares a file name property.

Example:
declareFile('file', 'description');
Following command-line options are then allowed: 

--file C:\test                  =>     file:=C:\test
--file 'C:\test'                =>     file:=C:\test
--file "C:\test"                =>     file:=C:\test
--file='C:\test'                =>     file:=C:\test
--file="C:\test"                =>     file:=C:\test
--file C:\Program Files\a.exe   =>     file:=C:\Program
                                       or file:=C:\Program Files\a.exe if C:\Program does not exist

Public procedure declareInt(const name,description:string;value: longint=0); overload;

DeclareInt declares an integer property.

Example:
declareInt('prop', 'description');
Following command-line options are then allowed: 

--prop 123                  =>     prop:=123
--prop '123'                =>     prop:=123
--prop "123"                =>     prop:=123
--prop='123'                =>     prop:=123
--prop="123"                =>     prop:=123

Public procedure declareString(const name,description:string;value: string=''); overload;

DeclareString declares a string property.
See declareInt for a related example.

Public procedure declareFloat(const name,description:string;value: extended=0); overload;

DeclareFloat declares a float property.
See declareInt for a related example.

Public procedure addAbbreviation(const abbreviation: char; const originalName: string = '');

Allows to use -abbreviation=... additionally to –originalName=...
With windows style /abbreviation and /originalName will behave in the same way (only single letter abbreviations are allowed like in unix commands).

Public procedure addEnumerationValues(const originalName: string; const enumeration: array of string); overload;

Only allow certain values for property originalName.

Public procedure addEnumerationValues(const enumeration: array of string); overload;

Only allow certain values for the last property.

Public function readString(const name:string):string; overload;

Reads a previously declared string property.

Public function readInt(const name:string):longint; overload;

Reads a previously declared int property.

Public function readFloat(const name:string):extended; overload;

Reads a previously declared float property.

Public function readFlag(const name:string):boolean; overload;

Reads a previously declared boolean property.

Public function existsProperty(const name:string):boolean;

Tests if a declared property named name has been found on the command line.

Public function readNamelessFiles():TStringArray;

Reads all file names that are given on the command line and do not belong to a declared option (doesn't check for non existing files, yet).

Public function readNamelessString():TStringArray;

Reads all strings that are given on the command line and do not belong to a declared option.

Public function readNamelessInt():TLongintArray;

Reads all integers that are given on the command line and do not belong to a declared option.

Public function readNamelessFloat():TFloatArray;

Reads all floats that are given on the command line and do not belong to a declared option.

Public function readNamelessFlag():TBooleanArray;

Reads all booleans (true, false) that are given on the command line and do not belong to a declared option.

Properties

Public property onOptionRead: TOptionReadEvent read FOnOptionRead write FOnOptionRead;

Event called when an option has been parsed. (e.g. to read all values if an option is given multiple times) name contains the declared name of the property (not necessarily the same as the name the user used). value the value read.

Public property onCustomOptionInterpretation: TOptionInterpretationEvent read FOnOptionInterpretation write FOnOptionInterpretation;

Event called when an option is being parsed. (e.g. to allow custom abbreviations of names).
name contains the read name of the property.
value the value read; or the next value for boolean options (which will ignored).
args all arguments.
argpos the current argument.

Public property allowOverrides: boolean read FAllowOverrides write FAllowOverrides;

If the same option may be given multiple times. Only the last value is stored.

Generated by PasDoc 0.16.0.