Unit linearc

Classes, Interfaces, Objects and Records

Functions and Procedures

Variables

Description

This unit defines a robust parser that can process command-line arguments, as well as ALinearCConsoleApplication, which descends from AConsoleApplication and builds and executes such a parser automatically.

In general, ALinearCParser follows the GNU standards which can be found at:

One notable exception that the parser applies to the standards is that abbreviated options are not limited to a single character.

Uses

Overview

Classes, Interfaces, Objects and Records

Name	Description
Class `ACommandLineOption`	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.
Class `ACommandLineString`	This class represents a command-line option that expects a string value.
Class `ACommandLineAbbreviation`	This class represents the abbreviated form of a command-line option.
Class `AnOptionValueError`	An instance of this exception class is raised by ACommandLineOption.setValue if the value to be set does not conform to the option's definition.
Class `ACommandLineFlag`	This class represents a command-line flag; that is, an option with a value that is only true if the user specifies the name of the option on the command line.
Class `ACommandLineSwitch`	This class represents a command-line switch; that is, an option that accepts a value which may be `True` or `False`.
Class `ACommandLineNumber`	This class represents an option that expectas a numeric value.
Class `ACommandLineIntegerRange`	This class represents an option that expects an integer value which falls between a predefined minimum and maximum.
Class `ACommandLineFloatRange`	This class represents an option that expects a floating-point value which falls between a predefined minimum and maximum.
Class `ACommandLineChoice`	This class represents a command-line option that expects a value to be chosen from a list of pre-defined values.
Class `ACommandLineList`	This class represents an option that can be specified more than once on the command line; each time it occurs, the value specified is added to a list of values.
Class `ACommandLineOptionDictionary`	This class represents a dictionary of command-line options.
Class `TheLinearCLanguage`	This class represents the language specification for a command-line "language" named LinearC.
Class `ALinearCParser`	This class represents a parser for the LinearC language.
Class `ALinearCStatement`	This class represents a single statement that is pared by the LinearC parser.
Class `ALinearCAssignmentStatement`	This class represents an assignment statement in LinearC; that is, the portion of a command line where a value is assigned to a named option.
Class `ALinearCRestArgument`	This class represents a statement in LinearC that is composed entirely of a rest argument; that is, an argument which does not include the name of an existing option.
Class `ALinearCStatementBlock`	This class represents a statement block that is parsed by the LinearC parser.
Class `ALinearCExpression`	This class represents an expression in LinearC.
Class `ALinearCBooleanExpression`	This class represents a boolean expression in LinearC, which is an expression that consists of a single keyword belonging to either RULE_TRUTH or RULE_FALSEHOOD.
Class `ALinearCStringExpression`	This class represents a string expression in LinearC, which is an expression that consists of a single string, delimited by either lcdlQuote1String or lcdlQuote2String.
Class `ALinearCPathExpression`	This class represents a path expression in LinearC, which an expression that begins with a path delimiter, such as lcopDivideString or lcdlBackslashString and which is not contained in quotes (otherwise it would be seen as a string expression).
Class `ALinearCNumericExpression`	This class represents a numeric expression in LinearC, which is an expression that consists of a single number, either integer or floating-point.
Class `ALinearCCompoundExpression`	This class represents a compound expression in LinearC, which can be made up of one or more subexpressions.
Class `ALinearCConsoleApplication`	This class represents a single process running as a console application, which expects to receive arguments on its command line and which can parse those arguments with an instance of ALinearCParser.

Types

AnOptionValueType = set of TOptionValueType;

TOptionValueType = (...);

Constants

clchAcceptedValuesDescription = ' Accepted values are any one of: %s.';

clchDefaultValueDescription = '<value>';

clchErrorValueExpected = 'the option "%s" expects one of the following ' +
    'values:' + lineEnding + #9'%s';

clflDefaultValueDescription = '';

clfrAcceptedValuesDescription = '  Accepted values fall between %f and ' +
    '%f, inclusive.';

clfrDefaultValueDescription = '<number>';

clfrErrorValueExpected = 'the option "%s" expects a value between %f and %f';

clirAcceptedValuesDescription = '  Accepted values fall between %d and ' +
    '%d, inclusive.';

clirDefaultValueDescription = '<integer>';

clirErrorValueExpected = 'the option "%s" expects a value between %d and %d';

clnmDefaultValueDescription = '<number>';

clodPrintHeaderRepresentation = 'Options:';

clopAbbreviationsRepresentation = '%s%s%s';

clopAssignmentOperator = '=';

clopAssignmentRepresentation = '%s%s%s%s';

clopDefaultValueDescription = '<value>';

clopDefaultValueRepresentation = ' Defaults to %s.';

clopDescriptionColumn = 35;

clopErrorValueExpected = 'the option "%s" expects %s';

clopFlagRepresentation = '%s%s';

clopNameColumn = 2;

clopParameterAbbreviationDelimiter = '-';

clopParameterNameDelimiter = '--';

clopStringRepresentation = '%s%s%s';

clstDefaultValueDescription = '<string>';

clswDefaultValueDescription = '<true|false>';

lcappErrorUnsetRequiredOption = 'the option "%s" is required';

lcappHelpDescription = 'Display this usage information.';

lcappHelpLongString = 'help';

lcappHelpShortString = '?';

lcappUsageHelpDescription = 'Enter "%s %s%s" for a description of ' +
    'available options.' + lineEnding;

lcappUsageStringFormat = 'Usage: %s [options] %s' + lineEnding;

lcappVersionDefaultAdditionalItems: array[0..2] of string = (
    vinfLegalCopyright,                 vinfComments, System.lineEnding   );

lcappVersionDescription = 'Display program version information.';

lcappVersionLongString = 'version';

lcappVersionStringFormat = '%s %s' + lineEnding;

lcbxErrorBooleanExpressionExpected = 'expected boolean expression after %s;' +
    ' got %s instead';

lccsDigit = '.$';

lccsLetter = '?/\:';

lccsSpecial = '+-*/!=''"ˆ()\';

lccxErrorInvalidOperation = 'cannot operate on incompatible values: %s and ' +
    '%s';

lcdlBackslash = TOKCAT_SPECIAL + (ord('\') shl 8);

lcdlBackslashString = '\';

lcdlBeginLongOption = lcopMinus + 1;

lcdlBeginShortOption = lcdlBeginLongOption + 1;

lcdlLeftParen = TOKCAT_SPECIAL + (ord('(') shl 8);

lcdlLeftParenString = '(';

lcdlQuote1 = TOKCAT_SPECIAL + (ord('"') shl 8);

lcdlQuote1String = '"';

lcdlQuote2 = TOKCAT_SPECIAL + (ord('''') shl 8);

lcdlQuote2String = '''';

lcdlRightParen = TOKCAT_SPECIAL + (ord(')') shl 8);

lcdlRightParenString = ')';

lckwFalse = TOKCAT_KEYWORD + (ord('f') shl 8);

lckwFalseString = 'false';

lckwNoFull = lckwNoShort + 1;

lckwNoFullString = 'no';

lckwNoShort = lcopNot + 1;

lckwNoShortString = 'n';

lckwOff = lckwOn + 1;

lckwOffString = 'off';

lckwOn = lcopOr + 1;

lckwOnString = 'on';

lckwTrue = TOKCAT_KEYWORD + (ord('t') shl 8);

lckwTrueString = 'true';

lckwYesFull = lckwYesShort + 1;

lckwYesFullString = 'yes';

lckwYesShort = TOKCAT_KEYWORD + (ord('y') shl 8);

lckwYesShortString = 'y';

lcnxErrorInvalidNumber = 'invalid number: %s';

lcopAnd = TOKCAT_KEYWORD + (ord('a') shl 8);

lcopAndString = 'and';

lcopAssign = TOKCAT_SPECIAL + (ord('=') shl 8);

lcOpcodeCount = 27;

lcopDivide = TOKCAT_SPECIAL + (ord('/') shl 8);

lcopDivideString = '/';

lcopExponent = TOKCAT_SPECIAL + (ord('ˆ') shl 8);

lcopExponentString = 'ˆ';

lcopMinus = TOKCAT_SPECIAL + (ord('-') shl 8);

lcopMinusString = '-';

lcopModulo = TOKCAT_KEYWORD + (ord('m') shl 8);

lcopModuloString = 'mod';

lcopNot = TOKCAT_KEYWORD + (ord('n') shl 8);

lcopNotString = 'not';

lcopOr = TOKCAT_KEYWORD + (ord('o') shl 8);

lcopOrString = 'or';

lcopPlus = TOKCAT_SPECIAL + (ord('+') shl 8);

lcopPlusString = '+';

lcopShl = TOKCAT_KEYWORD + (ord('s') shl 8);

lcopShlString = 'shl';

lcopShr = lcopShl + 1;

lcopShrString = 'shr';

lcopTimes = TOKCAT_SPECIAL + (ord('*') shl 8);

lcopTimesString = '*';

lcstWarningUnknownOption = 'ignoring unknown option %s' + lineEnding;

lcxpErrorValidExpressionExpected = 'expected valid expression after %s; ' +
    'got %s instead';

RULE_BEGIN_EXPRESSION = RULE_END_STATEMENT + 1;

RULE_BEGIN_PATH = RULE_DELIMIT_STRING + 1;

RULE_DELIMIT_STRING = RULE_OPERATOR + 1;

RULE_END_EXPRESSION = RULE_BEGIN_EXPRESSION + 1;

RULE_FALSEHOOD = RULE_TRUTH + 1;

RULE_OPERATOR = RULE_UNARY_OPERATORS + 1;

RULE_PRECEDE_ASSIGNMENT = RULE_BEGIN_PATH + 1;

RULE_TRUTH = RULE_END_EXPRESSION + 1;

RULE_UNARY_OPERATORS = RULE_FALSEHOOD + 1;

Description

Types

AnOptionValueType = set of TOptionValueType;

This type is used to contain the flags which indicate what type of value is accepted by an instance of ACommandLineOption.

TOptionValueType = (...);

This enumeration indicates the types of options that can be accepted on the command line:

ovtNone: Indicates an invalid option; not really used
ovtFlag: A flag value, which is assumed to be False unless it is specified on the command-line. A flag value might be specified as --flag when passed on the command line. Represented by instances of ACommandLineFlag.
ovtSwitch: A switch, which may be True or False. Unlike flag values, the value of a switch must be explicitly set on the command line. A switch might be specified as --switch=y or --switch=false when passed on the command line. Represented by instances of ACommandLineSwitch.
ovtNumber: A numeric value, either integer or floating-point. The only constraints on the value are the limits of the int64 or double types. A numeric value might be specified as --value=23 or --value=42.0 when passed on the command line. Represented by instances of ACommandLineNumber.
ovtIntegerRange, ovtFloatRange: A numeric value that must fall between a minimum and maximum value. Represented by instances of ACommandLineIntegerRange and ACommandLineFloatRange.
ovtString: A string value. A string value might be specified as --value=text or --value="text" when passed on the command line. Represented by instances of ACommandLineString.
ovtMultipleChoice: A value that must match one of a list of provided values. Represented by instances of ACommandLineChoice.
ovtList: A value that can be specified more than once on the command line; each occurrence is collected into a list of values. Represented by instances of ACommandLineList.
ovtRest: An argument that is specified without a name preceding it. These are usually used to indicate file names. This value is combined with one of the above values.

Values

ovtNone:
ovtFlag: A flag – a value that is true only if the flag is specified
ovtSwitch: A switch – yes/no, on/off, true/false, etc.
ovtNumber: A numeric value – floating point or integer
ovtIntegerRange: A numeric value that is constrained to a range
ovtFloatRange: A numeric value that is constrained to a range
ovtString: A string value
ovtMultipleChoice: A value that is constrained to a set of values
ovtList: A list item
ovtRest: A rest argument

Constants

clchAcceptedValuesDescription = ' Accepted values are any one of: %s.';

This string controls the format of the extra string appended to the result returned when ACommandLineChoice.usageString is called.

The string placeholder is filled with a list of acceptable values for the option, as returned by calling AVariantList.implode on ACommandLineChoice.AcceptedValues.

clchDefaultValueDescription = '<value>';

This string contains the default description returned by ACommandLineChoice.valueDescription if no other description is set when the option is constructed.

A value description is presented to the user as part of the usage information generated by ACommandLineOption.usageString and should contain a description of the value expected by the option.

clchErrorValueExpected = 'the option "%s" expects one of the following ' +
    'values:' + lineEnding + #9'%s';

This string controls the format of the error message emitted by ACommandLineChoice.setValue in the event that the routine is given a value which is incompatible with the option.

The first string placeholder is filled with the name of the option.

The second string placeholder is filled with a list of accepted values for the option, as returned by calling AVariantList.implode on ACommandLineChoice.AcceptedValues.

clflDefaultValueDescription = '';

This string contains the default description returned by ACommandLineFlag.valueDescription if no other description is set when the option is constructed.

A value description is presented to the user as part of the usage information generated by ACommandLineOption.usageString and should contain a description of the value expected by the option.

In the case of instances of ACommandLineFlag, no value is expected or allowed, so this string is blank.

clfrAcceptedValuesDescription = '  Accepted values fall between %f and ' +
    '%f, inclusive.';

This string controls the format of the extra string appended to the result returned when ACommandLineFloatRange.usageString is called.

The first floating-point placeholder is filled with the minimum value accepted by the option, as returned by a call to ACommandLineFloatRange.minimum.

The second floating-point placeholder is filled with the maximum value accepted by the option, as returned by a call to ACommandLineFloatRange.maximum.

clfrDefaultValueDescription = '<number>';

This string contains the default description returned by ACommandLineFloatRange.valueDescription if no other description is set when the option is constructed.

A value description is presented to the user as part of the usage information generated by ACommandLineOption.usageString and should contain a description of the value expected by the option.

clfrErrorValueExpected = 'the option "%s" expects a value between %f and %f';

This string controls the format of the error message emitted by ACommandLineFloatRange.setValue in the event that the routine is given a value which is incompatible with the option.

The string placeholder is filled with the name of the option.

The first integer placeholder is filled with the value of ACommandLineFloatRange.minimum.

The second integer placeholder is filled with the value of ACommandLineFloatRange.maximum.

clirAcceptedValuesDescription = '  Accepted values fall between %d and ' +
    '%d, inclusive.';

This string controls the format of the extra string appended to the result returned when ACommandLineIntegerRange.usageString is called.

The first integer placeholder is filled with the minimum value accepted by the option, as returned by a call to ACommandLineIntegerRange.minimum.

The second integer placeholder is filled with the maximum value accepted by the option, as returned by a call to ACommandLineIntegerRange.maximum.

clirDefaultValueDescription = '<integer>';

This string contains the default description returned by ACommandLineIntegerRange.valueDescription if no other description is set when the option is constructed.

A value description is presented to the user as part of the usage information generated by ACommandLineOption.usageString and should contain a description of the value expected by the option.

clirErrorValueExpected = 'the option "%s" expects a value between %d and %d';

This string controls the format of the error message emitted by ACommandLineIntegerRange.setValue in the event that the routine is given a value which is incompatible with the option.

The string placeholder is filled with the name of the option.

The first integer placeholder is filled with the value of ACommandLineIntegerRange.minimum.

The second integer placeholder is filled with the value of ACommandLineIntegerRange.maximum.

clnmDefaultValueDescription = '<number>';

This string contains the default description returned by ACommandLineNumber.valueDescription if no other description is set when the option is constructed.

A value description is presented to the user as part of the usage information generated by ACommandLineOption.usageString and should contain a description of the value expected by the option.

clodPrintHeaderRepresentation = 'Options:';

This string controls the format of the header printed when ACommandLineOptionDictionary.printUsageTo is called. It is designed to head the list of options and usage information which is printed when that method is called.

clopAbbreviationsRepresentation = '%s%s%s';

This string controls the format of the string used to indicate to the user what abbreviations may be given instead of the full name of an option. It is part of the string returned to the caller when ACommandLineOption.usageString is called.

The first string placeholder is filled with the value of clopParameterAbbreviationDelimiter.

The second string placeholder is filled with a delimited list of abbreviations, obtained by calling AStringList.implode on the list returned by ACommandLineOption.Abbreviations. Each element in the delimited list is separated by a string that combines the value of llstDefaultDelimiter with the value of clopParameterAbbreviationDelimiter.

The third string placedholder is filled with the value of llstDefaultDelimiter.

clopAssignmentOperator = '=';

This string determines the character that is used to indicate a value should be assigned to a named option. This character is expected to be placed between the name of the option and its value when specified by the user on the command line.

clopAssignmentRepresentation = '%s%s%s%s';

This string controls the format of the string used to indicate to the user which values may be assigned to an option. It is part of the string returned to the caller when ACommandLineOption.usageString is called on an option that is not an instance of ACommandLineFlag.

The first string placeholder is filled with the value of clopParameterNameDelimiter.

The second string placeholder is filled with the name of the option, as returned by a call to ACommandLineOption.name.

The third string placeholder is replaced by the value of clopAssignmentOperator.

The fourth string placeholder contains a description of values that are acceptable for the specific option, as returned by a call to ACommandLineOption.valueDescription.

clopDefaultValueDescription = '<value>';

This string contains the default description returned by ACommandLineOption.valueDescription if no other description is set when the option is constructed.

A value description is presented to the user as part of the usage information generated by ACommandLineOption.usageString and should contain a description of the value expected by the option.

clopDefaultValueRepresentation = ' Defaults to %s.';

This string controls the format of the string used to indicate the default value of an option to the user. It is part of the string returned to the caller when ACommandLineOption.usageString is called, but only if the value of ACommandLineOption.defaultValue is not equal to Variants.null and ACommandLineOption.required is False, since there is little point to specifying a default value for an option that must be specified by the user.

The string placeholder is filled with a string representation of the default value, obtained by calling Variants.varToStr on ACommandLineOption.defaultValue.

clopDescriptionColumn = 35;

This constant is used to determine where the descriptions of command-line options begin when printed to a text-based device, such as a console.

clopErrorValueExpected = 'the option "%s" expects %s';

This string controls the format of the error message issued in the event that ACommandLineOption.setValue is given a value that it cannot use, based on the definition of the option.

The first string placeholder is replaced by the name of the option in question.

The second string placeholder is replaced by a description of the value expected by the option, as returned by a call to ACommandLineOption.valueDescription.

clopFlagRepresentation = '%s%s';

The first string placeholder is filled with the value of clopParameterNameDelimiter.

The second string placeholder is filled with the name of the option, as returned by a call to ACommandLineOption.name.

clopNameColumn = 2;

This constant is used to determine where the names of command-line options begin when printed to a text-based device, such as a console.

clopParameterAbbreviationDelimiter = '-';

This string determines the characters that are used to indicate the abbreviated name of a command line parameter when it is passed on the command line. The abbreviated form of any command line parameter may be specified by prefixing these characters to the abbreviation.

clopParameterNameDelimiter = '--';

This string determines the characters that are used to indicate a parameter name on the command line. All named parameters encountered must be prefixed by these characters.

clopStringRepresentation = '%s%s%s';

This string controls the format of the string returned when ACommandLineOption.usageString is called.

The first string placeholder is filled with the result of calling SysUtils.format on clopAssignmentRepresentation; it is used to indicate to the user what values are acceptable to the option.

The second string placeholder is filled with padding so that the description of the option lines up at the column specified by clopDescriptionColumn.

The third string placeholder is filled with the description of the option, as returned by a call to ACommandLineOption.description.

clstDefaultValueDescription = '<string>';

This string contains the default description returned by ACommandLineString.valueDescription if no other description is set when the option is constructed.

A value description is presented to the user as part of the usage information generated by ACommandLineOption.usageString and should contain a description of the value expected by the option.

clswDefaultValueDescription = '<true|false>';

This string contains the default description returned by ACommandLineSwitch.valueDescription if no other description is set when the option is constructed.

A value description is presented to the user as part of the usage information generated by ACommandLineOption.usageString and should contain a description of the value expected by the option.

lcappErrorUnsetRequiredOption = 'the option "%s" is required';

lcappHelpDescription = 'Display this usage information.';

lcappHelpLongString = 'help';

lcappHelpShortString = '?';

linearcstatements.inc - A descendant of AConsoleApplication that builds and executes a command-line parser automatically.

This file is part of commandline.pp, a library for robust command-line parsing.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License or, at your option, any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABLITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

lcappUsageHelpDescription = 'Enter "%s %s%s" for a description of ' +
    'available options.' + lineEnding;

lcappUsageStringFormat = 'Usage: %s [options] %s' + lineEnding;

lcappVersionDefaultAdditionalItems: array[0..2] of string = (
    vinfLegalCopyright,                 vinfComments, System.lineEnding   );

This array can be used to determine whether and how ALinearCConsoleApplication.printVersionTo prints additional items besides just the program name and version.

Each string is printed to the stream specified. If the strings represent the name of a key that may be in Self.VersionInfo, and if such a key is found, then the value associated with that key is printed. Otherwise, the literal value of the string is printed instead.

If the string to be printed is not contained in tosWrapDefaultBreakCharacters, then it is printed by means of ATextOutputStream.printWrapped; otherwise it is printed as is, by means of ATextOutputStream.print.

lcappVersionDescription = 'Display program version information.';

lcappVersionLongString = 'version';

lcappVersionStringFormat = '%s %s' + lineEnding;

lcbxErrorBooleanExpressionExpected = 'expected boolean expression after %s;' +
    ' got %s instead';

This string controls the format of the error message emitted by ALinearCBooleanExpression.parse when an invalid boolean expression is encountered.

The first string placeholder is filled with the token that occurred just prior to the expected expression, as determined by a call to AToken.toString.

The second string placeholder is filled with the token that should have started a valid expression, as determined by a call to AToken.toString.

lccsDigit = '.$';

This string specifies the characters that LinearC recognizes as beginning a numeric constant. The characters here are added to those defined by plcsTypicalDigit when TheLinearCLanguage.defineCharacterCategories is called.

lccsLetter = '?/\:';

This string specifies the characters that LinearC recognizes as alphanumeric.

lccsSpecial = '+-*/!=''"ˆ()\';

This string specifies the characters that LinearC recognizes as operators or delimiters.

lccxErrorInvalidOperation = 'cannot operate on incompatible values: %s and ' +
    '%s';

This string controls the format of the error message emitted by ALinearCCompoundExpression.performOperation when an attempt is made to peform a mathematical operation on incompatible value types.

The first string placeholder is filled with the value of the left-hand operand, as obtained by calling ALinearCExpression.toString on ALinearCCompoundExpression.PreviousElement.

The second string placeholder is filled with the value of the right-hand operand, as obtained by calling ALinearCExpression.toString on ALinearCCompoundExpression.CurrentElement.

lcdlBackslash = TOKCAT_SPECIAL + (ord('\') shl 8);

lcdlBackslashString = '\';

In order to parse Windows-style paths, the LinearC parser must know about backslash characters.

lcdlBeginLongOption = lcopMinus + 1;

lcdlBeginShortOption = lcdlBeginLongOption + 1;

lcdlLeftParen = TOKCAT_SPECIAL + (ord('(') shl 8);

lcdlLeftParenString = '(';

In order to parse compound expressions, the LinearC parser must know when one expression begins and ends. Since subexpressions are usually contained within parentheses, this string defines one such token.

lcdlQuote1 = TOKCAT_SPECIAL + (ord('"') shl 8);

lcdlQuote1String = '"';

In order to parse strings, the LinearC parser must know when one begins and ends. Since strings are usually delimited by quotation marks, this string defines one such token.

lcdlQuote2 = TOKCAT_SPECIAL + (ord('''') shl 8);

lcdlQuote2String = '''';

In order to parse strings, the LinearC parser must know when one begins and ends. Since strings are usually delimited by quotation marks, this string defines one such token.

lcdlRightParen = TOKCAT_SPECIAL + (ord(')') shl 8);

lcdlRightParenString = ')';

lckwFalse = TOKCAT_KEYWORD + (ord('f') shl 8);

lckwFalseString = 'false';