pascli

Interface ICommandBuilder

Description
Hierarchy
Fields
Methods
Properties

Unit

Command.Interfaces

Declaration

type ICommandBuilder = interface(IInterface)

Description

Interface that represents the CommandBuilder, its main purpose is to configure the arguments, commands and options accepted by the tool. Central point of the library, responsible for comparing and validating the parameters passed via the command line against the configured parameters, later executing the callback linked to the localized command.

Attributes
GUID['{5CD580B0-B965-4467-B665-CDFDF61651F1}']

Hierarchy

Overview

Methods

Public function AddCommand(const ACommand: string; const ADescription: string = ''; ACallback: TCommandCallback = nil; AConstraints: TCommandConstraints = []): ICommandBuilder; overload;
Public function AddCommand(const ACommand: TAddCommandCallback): ICommandBuilder; overload;
Public function GetCommands: TArray<ICommand>;
Public function GetCommandsFound: Integer;
Public function GetDefaultCommand: ICommand;
Public function Description(const ADescription: string): ICommandBuilder;
Public function CheckConstraints(AConstraints: TCommandConstraints): ICommandBuilder;
Public function OnExecute(ACallback: TCommandCallback): ICommandBuilder;
Public function AddArgument(const ADescription: string; AConstraint: TArgumentConstraint): ICommandBuilder;
Public function GetArguments: TArray<IArgument>;
Public function AddOption(const AFlag, AName, ADescription: string; ANotAllowedFlags: TArray<string> = nil; AConstraint: TOptionConstraint = ocNoValue): ICommandBuilder;
Public procedure Parse;
Public function Validate: TArray<string>;
Public procedure Execute;
Public function Run: ICommandBuilder;
Public function CommandSelected: ICommand;
Public function SetCommandSelected(ACommand: ICommand): ICommandBuilder;
Public function CommandAsArgument: ICommand;
Public function SetCommandAsArgument(ACommand: ICommand): ICommandBuilder;
Public function GetParsedOptions: TArray<IOption>;
Public function CheckOption(const AOption: string): Boolean; overload;
Public function CheckOption(const AOption: string; out AValue: string): Boolean; overload;
Public function GetParsedArguments: TArray<IArgument>;
Public function GetRawArguments: TArray<string>;
Public function GetRawOptions: TArray<string>;
Public function ExeName: string;
Public function HasCommands: Boolean;
Public function HasArguments: Boolean;
Public function HasOptions: Boolean;
Public function GetInputLn: TInputLnCallback;
Public procedure SetInputLn(AValue: TInputLnCallback);
Public function GetOutput: TOutputCallback;
Public procedure SetOutput(AValue: TOutputCallback);
Public function GetOutputColor: TOutputColorCallback;
Public procedure SetOutputColor(AValue: TOutputColorCallback);
Public function UseArguments(AArguments: TArray<string>): ICommandBuilder;
Public function UseColorTheme(ATheme: TColorTheme): ICommandBuilder;
Public function GetColorTheme: TColorTheme;
Public procedure SetColorTheme(AValue: TColorTheme);
Public function GetTitle: string;
Public procedure SetTitle(AValue: string);
Public function GetUseShortDescriptions: boolean;
Public procedure SetUseShortDescriptions(AValue: boolean);
Public function GetState: string;
Public procedure SetState(AValue: string);

Properties

Public property Commands: TArray<ICommand> read GetCommands;
Public property Arguments: TArray<IArgument> read GetArguments;
Public property ParsedOptions: TArray<IOption> read GetParsedOptions;
Public property ParsedArguments: TArray<IArgument> read GetParsedArguments;
Public property InputLn: TInputLnCallback read GetInputLn write SetInputLn;
Public property Output: TOutputCallback read GetOutput write SetOutput;
Public property OutputColor: TOutputColorCallback read GetOutputColor write SetOutputColor;
Public property ColorTheme: TColorTheme read GetColorTheme write SetColorTheme;
Public property Title: string read GetTitle write SetTitle;
Public property UseShortDescriptions: boolean read GetUseShortDescriptions write SetUseShortDescriptions;
Public property State: string read GetState write SetState;

Description

Methods

Public function AddCommand(const ACommand: string; const ADescription: string = ''; ACallback: TCommandCallback = nil; AConstraints: TCommandConstraints = []): ICommandBuilder; overload;

Adds a command that will be available to the user of the command line application.

Parameters
ACommand
Command name as it will be provided by the user via command line parameter.
ADescription
Command description that will be displayed to the user as usage info.
ACallback
Callback procedure that will be invoked by the CommandBuilder if the validation was successful and the command informed match the command name.
AConstraints
Validation constraints for command usage, may set to default, may require a required argument, a required option. Check TCommandConstraint for existing constraints.
Public function AddCommand(const ACommand: TAddCommandCallback): ICommandBuilder; overload;

Using a callback to add a command to the CommandBuilder. The main purpose of this method is to allow the use of the fluent interface. Ex: CommandBuilder.AddCommand(@Command.Usage.Registry);

Parameters
ACommand
Command callback that will be invoked by CommandBuilder to add the command.
Public function GetCommands: TArray<ICommand>;

Returns the list of commands configured in CommandBuilder.

Public function GetCommandsFound: Integer;

Returns the number of commands found among the arguments passed as parameters after Parse.

Public function GetDefaultCommand: ICommand;

Returns the default command if one has been configured.

Public function Description(const ADescription: string): ICommandBuilder;

Set the description for the last command that was added.

Description of the command that best describes its purpose.</summay

Public function CheckConstraints(AConstraints: TCommandConstraints): ICommandBuilder;

Set the constraints for the last command that was added.

Parameters
AConstraints
Validation constraints for command usage, may set to default, may require a required argument, a required option. Check TCommandConstraint for existing constraints.
Public function OnExecute(ACallback: TCommandCallback): ICommandBuilder;

Set the callback for the last command that was added.

Parameters
ACallback
Callback procedure that will be invoked by the CommandBuilder
Public function AddArgument(const ADescription: string; AConstraint: TArgumentConstraint): ICommandBuilder;

Adds an argument to allow the user to pass a text argument via the command line.

Parameters
ADescription
Description of the argument to inform the user of the correct usage info about it.
AConstraint
Constraints to check if the argument is optional or mandatory.
Public function GetArguments: TArray<IArgument>;

Returns the list of arguments configured in CommandBuilder.

Public function AddOption(const AFlag, AName, ADescription: string; ANotAllowedFlags: TArray<string> = nil; AConstraint: TOptionConstraint = ocNoValue): ICommandBuilder;

Adds an option to the last added command. For both the short and long options, "-" must not be entered at the beginning of them.

Parameters
AFlag
Represents the option as a single letter, i.e. a short option.
AName
Represents the option as a word, that is, a long option, it does not accept spaces, but "-' can be used for compound names.
ADescription
Description of the option that best defines your objective. It can be displayed to the user when the user requests information through the help command for example.
ANotAllowedFlags
Array of flags not supported for use in conjunction with this option. Only the short option without the "-" is accepted.
AConstraint
Option constraint that will be validated against the options provided by the user in order to guarantee that the command is being used correctly.
Public procedure Parse;

Parses parameters passed via command line, matching command names and arguments for further validation.

Public function Validate: TArray<string>;

Validates the parsed parameters, checking the configured constraints and other validations such as duplicity, excess arguments, combination of existing options, invalid options, etc.

Public procedure Execute;

Invokes the callback procedure configured for the command found once parse and validation have been successful. It passes the CommandBuilder itself as a parameter to the callback so that it is possible to call the CheckOption method to validate the presence of a certain option, or to obtain the value of an expected argument through the Arguments[n].Value property.

Public function Run: ICommandBuilder;

Executes the TCommandBuilder.Parse, TCommandBuilder.Validade and TCommandBuilder.Execute methods to process all parameters provided by the user and call the correct callback command or to print validation messages.

Public function CommandSelected: ICommand;

Returns the selected command after Parse.

Public function SetCommandSelected(ACommand: ICommand): ICommandBuilder;

Manually set the selected command. Mostly used for test purpose.

Public function CommandAsArgument: ICommand;

Returns a possible command that was passed as an argument to another command. Value is available after Parse.

Public function SetCommandAsArgument(ACommand: ICommand): ICommandBuilder;

Manually set the command as argument. Mostly used for test purpose.

Public function GetParsedOptions: TArray<IOption>;

Returns the list of valid options found after parse.

Public function CheckOption(const AOption: string): Boolean; overload;

Returns true if the option provided through command line by user matches the the parameter AOption. This method is usually used within the callback procedure of a given command to customize its processing.

Ex: 

if ABuilder.CheckOption('v') then 
begin
  // do something
end;

Parameters
AOption
Can be provided short option or long option without leading dashes.
Public function CheckOption(const AOption: string; out AValue: string): Boolean; overload;

Returns true if the option provided through command line by user matches the the parameter AOption. This method is usually used within the callback procedure of a given command to customize its processing.

Ex: 

var
  LValue: string;
begin
  if ABuilder.CheckOption('v', LValue) then 
  begin
    // do something
    WriteLn('Option d value is ', LValue);
  end;

Parameters
AOption
Can be provided short option or long option without leading dashes.
AValue
Returns the value of the option if it was provided by the user.
Public function GetParsedArguments: TArray<IArgument>;

Build a list of IArguments related to selected command, if there are more than one argument provided the list will match one argument parameter by order of the command builder configuration

Public function GetRawArguments: TArray<string>;

Returns a list of raw arguments passed as parameters

Public function GetRawOptions: TArray<string>;

Returns a list of raw options passed as parameters

Public function ExeName: string;

Returns exe name that will be used as command line shell name to start the application. It´s used to outputs usage info.

Public function HasCommands: Boolean;

Returns True if CommandBuilder has at least one command configured.

Public function HasArguments: Boolean;

Returns True if CommandBuilder has at least one argument configured.

Public function HasOptions: Boolean;

Returns True if CommandBuilder has any option configured in any command.

Public function GetInputLn: TInputLnCallback;
 
Public procedure SetInputLn(AValue: TInputLnCallback);
 
Public function GetOutput: TOutputCallback;
 
Public procedure SetOutput(AValue: TOutputCallback);
 
Public function GetOutputColor: TOutputColorCallback;
 
Public procedure SetOutputColor(AValue: TOutputColorCallback);
 
Public function UseArguments(AArguments: TArray<string>): ICommandBuilder;

Allows to inject external arguments instead of reading from ParamStr(). Mainly used for testing purposes.

Parameters
AArguments
Array of strings containing the arguments, the options must be passed with the leading dashes.
Public function UseColorTheme(ATheme: TColorTheme): ICommandBuilder;

Allows to use a different color theme for the too. Returns the CommandBuilder to allow the use of fluent interface.

Parameters
ATheme
Color theme to be used.
Public function GetColorTheme: TColorTheme;
 
Public procedure SetColorTheme(AValue: TColorTheme);
 
Public function GetTitle: string;
 
Public procedure SetTitle(AValue: string);
 
Public function GetUseShortDescriptions: boolean;
 
Public procedure SetUseShortDescriptions(AValue: boolean);
 
Public function GetState: string;
 
Public procedure SetState(AValue: string);
 

Properties

Public property Commands: TArray<ICommand> read GetCommands;

Returns the list of commands configured in CommandBuilder.

Public property Arguments: TArray<IArgument> read GetArguments;

Returns the list of arguments configured in CommandBuilder.

Public property ParsedOptions: TArray<IOption> read GetParsedOptions;

Returns the list of valid options found after parse.

Public property ParsedArguments: TArray<IArgument> read GetParsedArguments;

Build a list of IArguments related to selected command, if there are more than one argument provided the list will match one argument parameter by order of the command builder configuration

Public property InputLn: TInputLnCallback read GetInputLn write SetInputLn;

Callback procedure used to capture user input. A default callback is provided by the library, but it can be overridden for testing purposes primarily. Should return user input.

Public property Output: TOutputCallback read GetOutput write SetOutput;

Callback procedure that is intended to output text to the console, or other desired output. The library provides a standard callback that simply calls WriteLn, but it can be overridden so that the output is redirected to a file, a test function, etc.

Public property OutputColor: TOutputColorCallback read GetOutputColor write SetOutputColor;

Callback procedure that is intended to output text to the console usings colors. The library provides a standard callback that simply calls Write before change console color, but it can be overridden so that the output is redirected to a file, a test function, etc.

Public property ColorTheme: TColorTheme read GetColorTheme write SetColorTheme;

Color theme that should be used to output colors of commands, a standard theme is provided by Command.Colors unit. Should be changed prior to application execution

Public property Title: string read GetTitle write SetTitle;

Application title, should be customized and is displayer on usage info to the user

Public property UseShortDescriptions: boolean read GetUseShortDescriptions write SetUseShortDescriptions;

Display only the first line usage description for command usage, the user needs to use help command to see full command description. Default value is false to preserve original function.

Public property State: string read GetState write SetState;

State that can be set by user commands allowing better communication between commands and the application.

Generated by PasDoc 0.16.0.