causerie

Introduction

Units

Class Hierarchy

Classes, Interfaces, Objects and Records

Types

Variables

Constants

Functions and Procedures

Identifiers

Classes hierarchy graph

Class ACommandLineOption

DescriptionHierarchyFieldsMethodsProperties

Unit

linearc

Declaration

type ACommandLineOption = class(ADictionaryEntry)

Description

This class represents a dynamic command-line option; that is, one which has been defined at runtime, either by reading it from a static definition or programatically. Dynamic command-line options can be grouped together into a dictionary of options, which define the options that are valid and recognized by a program which accepts command-line parameters.

This base class is not likely to be instantiated directly; instead one of its descendants will be used, since these are tailored to a specific type of option.

Hierarchy

Overview

Fields

Protected myDefaultValue: Variant;
Protected myOptionType: AnOptionValueType;
Protected myRequirement: boolean;
Protected myDirtiness: boolean;
Protected myValueDescription: string;
Protected myDescription: string;

Methods

Public constructor named(const thisName: string; const isRequired: boolean; const isRest: boolean; const thisDefaultValue: Variant; const thisDescription: string; const thisValueDescription: string = ''); reintroduce; virtual;
Public function init: boolean; override;
Public destructor destroy; override;
Public function Abbreviations: AStringList; virtual;
Public function usageString: AnsiString; virtual;
Public function shallowCopyFrom(const Other: AnObject): boolean; override;
Public function defaultValue: Variant; virtual;
Public function setValue(const newValue: Variant; const makeDirty: boolean = true): Variant; reintroduce; virtual;
Public function optionType: AnOptionValueType; virtual;
Public function required: boolean; virtual;
Public function setRequired(const flag: boolean): boolean; virtual;
Public function isRestArgument: boolean; virtual;
Public function dirty: boolean; virtual;
Public function setDirty(const flag: boolean): boolean; virtual;
Public function description: string; virtual;
Public function valueDescription: string; virtual;

Description

Fields

Protected myDefaultValue: Variant;

Stores the default value of the option

Protected myOptionType: AnOptionValueType;

Indicates the option type

Protected myRequirement: boolean;

Indicates whether the option is required

Protected myDirtiness: boolean;

Indicates whether the option has been set by the user

Protected myValueDescription: string;

Stores a description of the type of value expected by the option

Protected myDescription: string;

Stores a description of the option

Methods

Public constructor named(const thisName: string; const isRequired: boolean; const isRest: boolean; const thisDefaultValue: Variant; const thisDescription: string; const thisValueDescription: string = ''); reintroduce; virtual;

Construct a new command-line option with the specified name.

This method constructs a new instance of ACommandLineOption with the specified defaultValue. The caller can also set whether the option is required and can provide a description of the option which will be used when the user requests help.

.

Parameters
thisName
specifies the name of the option as it should be supplied on the command-line. It is case-sensitive.
isRequired
indicates whether or not the user MUST supply the option on the command line.
isRest
indicates whether or not the option is a rest argument; if True, then the user need not supply the name of the argument on the command line
thisDefaultValue
is used to set the initial value of the option.
thisDescription
is used to describe the purpose of the option to the user.
thisValueDescription
is used to describe the type of value accepted by the option. If this parameter is left blank, a default description is used, depending on the type of option represented by the new instance.
Public function init: boolean; override;

Initializer

Public destructor destroy; override;

Destroy the option.

This method overrides the behavior inherited from ANode.destroy; it does not attempt to destroy any children of the node. Since any such children represent abbreviated forms of the option, and so are entered into the main dictionary of options, they will be freed along with all other top-level options.

This method still causes the destruction of all older siblings of the node by recursively traversing ACommandLineOption.Previous and freeing each node encountered until a Nil result is found. If this behavior is not desired, then the node should be detached from its siblings by calling ACommandLineOption.detach before this node is freed.

Otherwise, TObject.free can be called on the last option in a list of options and it will cause the destruction of the entire list.

Public function Abbreviations: AStringList; virtual;

Obtain the names of any abbreviations specified for the option.

If an option has an abbreviated form, this abbreviation may be specified on the command line instead of the full name of the option.

Abbreviations are specified at the time the option is entered into an instance of ACommandLineOptionDictionary. This method checks to see whether ACommandLineOption.Child has been set to a value that is not Nil; if so, it traverses the list of children, querying the name of each one. These are inserted into a string list which is subsequently returned to the caller.

Returns

An instance of AStringList that contains the names of all abbreviations specified for the option. The caller is responsible for freeing this list when it is no longer required. If the option has no abbreviations, this method returns Nil.

Public function usageString: AnsiString; virtual;

Construct and return a string representation that describes the name, accepted values, and usage of the option. This0 method is designed to provide assistance to the user when they request help from the command line.

Public function shallowCopyFrom(const Other: AnObject): boolean; override;

Construct a shallow copy of the other object.

This method overrides the behavior inherited from ASymbol.shallowCopyFrom: it calls that routine first, then checks to see whether Other is an instance of ACommandLineOption. If so, it copies the values of ACommandLineOption.required, ACommandLineOption.dirty and ACommandLineOption.description from Other to Self, overwriting the corresponding values in Self.

Note that this method does NOT copy any sibling or child nodes and so cannot be used to create a full copy of any descendant of ANode. Likewise, it does NOT copy the left or right subtrees and so cannot be used to create a full copy of any descendant of ABinaryLeaf.

Public function defaultValue: Variant; virtual;

Retrieve the default value of the option. This is set when the option is constructed and cannot be changed.

Public function setValue(const newValue: Variant; const makeDirty: boolean = true): Variant; reintroduce; virtual;

Set the current value of the option.

If makeDirty is False, then calling this method will not change the dirty flag that indicates the change has been made by the user.

Returns

The previous value of ACommandLineOption.value.

Public function optionType: AnOptionValueType; virtual;

Retrieve the option type. This is set by the option when it is constructed and cannot be changed.

Public function required: boolean; virtual;

Retrieve whether or not the option is required: whether it must be specified on the command-line by the user.

If this routine returns True, then an error will be returned to the user if ACommandLineOption.dirty returns False, since that indicates the option is required but was not set by the user.

Public function setRequired(const flag: boolean): boolean; virtual;

Set whether or not the option is required: whether it must be specified on the command-line by the user.

If an option is required but ACommandLineOption.dirty returns False, then an error will be returned to the user, since that indicates that the option is required but was not set by the user.

Returns

The previous value of ACommandLineOption.required.

Public function isRestArgument: boolean; virtual;

Determine whether or not the option is a rest argument; that is, an option that does not require its name to be provided on the command line.

This method simply checks to see whether ovtRest is in the set of values defined by ACommandLineOption.optionType.

Public function dirty: boolean; virtual;

Retrieve whether or not the option has been set by the user.

If this routine returns True, then the option was found on the command line and its value set from there; otherwise, the option still retains its default value or a value that was not set by the user.

If this method returns False, but ACommandLineOption.required is True, then an error will be returned to the user, since that indicates that the option is required but was not set by the user.

Public function setDirty(const flag: boolean): boolean; virtual;

Set whether or not the option is dirty.

If flag is True, then it indicates that the option and its value were found while parsing the command line – the option has been set by the user.

Returns

The previous value of ACommandLineOption.dirty.

Public function description: string; virtual;

Retrieve a description of the option.

The description returned was set when the option was first constructed and cannot be changed. It is most often presented to the user when the user requests help.

Public function valueDescription: string; virtual;

Retrieve a description of the type of value accepted by the option.

The description returned was set when the option was first constructed and cannot be changed. It is most often presented to the user when the user requests help.

If no description of the value was provided when the option was first constructed, then this method will return the default value established by ACommandLineOption.init.

Generated by PasDoc 0.13.0 on 2015-01-10 17:13:18