pascli

Class TCommandBuilder

Description
Hierarchy
Fields
Methods
Properties

Unit

Command.Builder

Declaration

type TCommandBuilder = class(TInterfacedObject, ICommandBuilder)

Description

Class that implements the ICommandBuilder interface, 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 by the command line with the configured parameters, later executing the callback linked to the localized command.

Hierarchy

Overview

Methods

Public constructor Create(AExeName: String);
Public class function New(ATitle: String): ICommandBuilder;
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 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 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 GetCommandsFound: Integer;
Public function GetDefaultCommand: ICommand;
Public function CheckOption(const AOption: string): Boolean; overload;
Public function CheckOption(const AOption: string; out AValue: string): Boolean; overload;
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 UseArguments(AArguments: TArray<string>): ICommandBuilder;
Public function UseColorTheme(ATheme: TColorTheme): ICommandBuilder;

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 constructor Create(AExeName: String);

Default class constructor. Creates an instance with a exe name that will be displayed to the user when using commands like UsageCommand or VersionCommand.

Parameters
AExeName
Program name without extension. It´s automatically provided by TCommandApp during the initialization.
Public class function New(ATitle: String): ICommandBuilder;

A class factory for command builder. It allows the initialization of the builder with a brief description and will extract the application executable name that will be used to display usage info on how to use the tool.

Parameters
ATitle
Brief description of the tool. It will be displayed on the UsageCommand command.
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. This command will be added to the TCommandBuilder.Commands property.

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. Ex: [ccDefault, ccNoArgumentsButCommands]
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 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. This argument will be added to the TCommandBuilder.Arguments property. After parse the value can be obtained through the value property of an item in the arguments array.

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 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.

Note
Do not use leading "-" for short or long options

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 TCommandBuilder 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 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 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 GetRawArguments: TArray<string>;

Returns a list of raw arguments passed as parameters, including invalid arguments.

Public function GetRawOptions: TArray<string>;

Returns a list of raw options passed as parameters, including invalid options.

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 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.

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, can be customized and is displayed as part usage info to the user through the command UsageCommand.

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.