Class ACommandLineOptionDictionary

DescriptionHierarchyFieldsMethodsProperties

Unit

Declaration

type ACommandLineOptionDictionary = class(ASymbolTable)

Description

This class represents a dictionary of command-line options. It provides a way to organize and manage instances of ACommandLineOption and its descendants.

The dictionary allows new options to be created on the fly, and it also allows abbreviations to be defined for those options. The abbreviated forms of the options are inserted into the top level of the underlying tree, like the full version of the option, but their Parent node pointer is set to point to the full version of the option that they represent. When the various value and option lookup routines are called, they automatically return the parent if an abbreviated form of the option is requested.

Hierarchy

  • ASymbolTable
  • ACommandLineOptionDictionary

Overview

Methods

Public function init: boolean; override;
Public function add(const ThisOption: ACommandLineOption; const abbreviations: array of string; const freeOnFailure: boolean = true): ACommandLineOption; virtual;
Public function printUsageTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; virtual;
Public function RequiredOptionNames: AStringList; virtual;
Public function FirstCleanRequiredOption: ACommandLineOption; virtual;
Public function RestArgumentNames: AStringList; virtual;
Public function FirstCleanRestArgument: ACommandLineOption; virtual;
Public function handleDirtiedOptions: boolean; virtual;
Public function Option(const key: string): ACommandLineOption; virtual;
Public function valueOf(const key: string): Variant; virtual;
Public function valueOf(const key: string; const defaultValue: Variant): Variant; virtual;
Public function setValueOf(const key: string; const newValue: Variant): Variant; virtual;

Description

Methods

Public function init: boolean; override;

Initializer

Public function add(const ThisOption: ACommandLineOption; const abbreviations: array of string; const freeOnFailure: boolean = true): ACommandLineOption; virtual;

Add a new entry to the dictionary.

This method is designed allow new options to be constructed on the fly and inserted into the dictionary. If abbreviations contains one or more strings that represent abbreviations for ThisOption, then these abbreviations will also be entered into the dictionary.

As with other instances of ABinaryTree, ACommandLineOptionDictionary does not allow duplicate entries. If the new entry has the same name as one already in the list and freeOnFailure is True, then the new entry will be freed instead of being inserted into the list.

Returns

A reference to the dictionary entry that has been created and inserted or, if an entry with the same name was already present in the list, a reference to that entry. The caller should NOT attempt to free this reference; that will be done when the dictionary is destroyed.

Public function printUsageTo(const Dest: ATextOutputStream; prefix: AnsiString = ''; suffix: AnsiString = ''): TStreamIOSize; virtual;

Print option usage information to the specified stream.

This method iterates through each option in the dictionary and, so long as the option is not an instance of ACommandLineAbbreviation, it calls Dest.printWrapped to print the usage string generated by a call to ACommandLineOption.usageString.

Returns

The total number of bytes printed to Dest.

Public function RequiredOptionNames: AStringList; virtual;

Retrieve a list of all required options.

This method iterates through each option in the dictionary and, so long as the option is not an instance of ACommandLineAbbreviation, it calls ACommandLineOption.required to determine whether or not the option is required. If so, the name of the option is added to the list returned.

If no options are required, this method will return an empty list.

Public function FirstCleanRequiredOption: ACommandLineOption; virtual;

Retrieve a reference to the first required option that has not been set.

This method iterates through each option in the dictionary and, so long as the option is not an instance of ACommandLineAbbreviation, it calls ACommandLineOption.required, to determine if the option is required; and, if so, it then calls ACommandLineOption.dirty to determine whether the option has been set by the user. If ACommandLineOption.dirty returns False, then a reference to that option is returned.

If all required options have been set, or if there are no required options, this method returns Nil.

The caller should NOT attempt to free the reference returned by this routine.

Public function RestArgumentNames: AStringList; virtual;

Retrieve a list of all rest argument names.

This method iterates through each option in the dictionary and, so long as the option is not an instance of ACommandLineAbbreviation, it tests to see whether ovtRest is in the list of flags returned by ACommandLineOption.optionType. If so, the name of the option is added to the list returned.

If no rest arguments have been specified, this method will return an empty list.

Public function FirstCleanRestArgument: ACommandLineOption; virtual;

Retrieve a reference to the first rest argument that has not been set.

This method iterates through each option in the dictionary and, so long as the option is not an instance of ACommandLineAbbreviation, it tests to see whether ovtRest is in the list of flags returned by ACommandLineOption.optionType. If so, it calls ACommandLineOption.dirty to test whether the option has been set, and checks whether ovtList is in the list of flags returned by ACommandLineOption.optionType. If the option has not been set OR if it is a list option, then a reference to the option is returned.

If no rest arguments have been specified, or if every rest argument has been filled, this method will return Nil.

Public function handleDirtiedOptions: boolean; virtual;

Call handlers for each option that has been dirtied and which also has a handler specified for it.

If any of the handlers returns False, this method exits immediately and returns False. This method will only return True if all handlers return True.

Public function Option(const key: string): ACommandLineOption; virtual;

Retrieve a reference to the named option.

key may refer to the full form or an abbreviated form of the desired option.

Returns

A reference to the named option. The caller should NOT attempt to free this reference; that will be done when the dictionary is destroyed. If the option specified by key is not found, this method returns Nil.

Public function valueOf(const key: string): Variant; virtual;

Retrieve the value of the named option.

key may refer to either the full form or an abbreviated form of a given option.

Returns

The current value of the option named by key. If no such option was found in the list, this method returns Variants.null.

Public function valueOf(const key: string; const defaultValue: Variant): Variant; virtual;

Retrieve the value of the named option and, if that value is not found, return the default value specified.

key may refer to either the full form or an abbreviated form of a given option.

Returns

The current value of the option named by key. If no such option was found in the list, this method returns defaultValue.

Public function setValueOf(const key: string; const newValue: Variant): Variant; virtual;

Set the value of the named option.

key may refer to either the full form or an abbreviated form of a given option.

Returns

The previous value of the option named by key. If no such option was found in the list, this method returns Variants.null.


Generated by PasDoc 0.13.0 on 2015-06-25 11:07:51