API Reference

Class TParameters

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleParameters

Declaration

type TParameters = class(TCastleStringList)

Description

Storing and processing command-line parameters and options. For simple processing, you can just read values of this list, checking count with comfortable methods like CheckHigh. For more involved processing, use the Parse function, that does a whole job for you based on a simple specification of allowed options.

Some terminology:

Parameter

Command-line parameters list is given directly by the OS to our program. These are the contents of this list, initialized from the standard Pascal ParamStr/ParamCount. They can be modified to remove the already-handled parameters.

Option

Options are things encoded by the user in the parameters. Examples:

  • Command-line 

    castle-model-viewer --navigation Walk

    passes two parameters (--navigation and Walk) for castle-model-viewer, and these two parameters form one option: --navigation=Walk.

  • Command-line 

    castle-model-viewer -hv

    passes one parameter (-hv) for castle-model-viewer, and inside this parameter two options are encoded: -h and -v.

The very idea of this unit is to decode "options" from the "parameters".

Argument

Argument is a part of the option, that clarifies what this option does. For example in --navigation=Walk, "Walk" is the argument and "--navigation" is the option long name.

Some options don't take any arguments, some take optional argument, some take required argument, some have a couple of arguments. TOptionArgument type allows you to specify all this.

For simple programs, you can directly parse command-line by looking at our parameters strings. For more involved cases, using Parse method has a lot of advantages:

  • Less error-prone, and your program's code stays simple.

  • We automatically handle special parameter -- that is a standard way to mark the end of the options. (Useful for users that have filenames that start with "-" character.)

  • We automatically detect and make exceptions with nice messages on various errors. For example unrecognized options are clearly reported (so they will not mistaken for e.g. missing filenames by your program).

  • We automatically allow combining of short options, so user can use -abc instead of -a -b -c.

  • We have a simple interface, where you simply specify what options you want, long and short option names, option arguments and such.

See [https://castle-engine.io/common_options.php] for a user description how short and long options are expected to be given on the command-line.

Hierarchy

Overview

Methods

Public function High: Integer;
Public procedure CheckHigh(ParamValue: integer);
Public procedure CheckHighAtLeast(ParamValue: integer);
Public procedure CheckHighAtMost(ParamValue: integer);
Public function IsPresent(const A: array of string): boolean;
Public procedure Parse(const AOptions: POption_Array; const OptionsCount: Integer; const OptionProc: TOptionProc; const OptionProcData: Pointer; const ParseOnlyKnownOptions: boolean = false); overload;
Public procedure Parse(const AOptions: array of TOption; const OptionProc: TOptionProc; const OptionProcData: Pointer; const ParseOnlyKnownOptions: boolean = false); overload;

Description

Methods

Public function High: Integer;

This item has no description.

Public procedure CheckHigh(ParamValue: integer);

Does the number of parameters (High) satisfy given condition.

Exceptions raised
EInvalidParams
When High is wrong.
Public procedure CheckHighAtLeast(ParamValue: integer);

This item has no description.

Public procedure CheckHighAtMost(ParamValue: integer);

This item has no description.

Public function IsPresent(const A: array of string): boolean;

Is one of given strings present on the parameters list. Looks inside Strings[1..High], case sensitive.

Public procedure Parse(const AOptions: POption_Array; const OptionsCount: Integer; const OptionProc: TOptionProc; const OptionProcData: Pointer; const ParseOnlyKnownOptions: boolean = false); overload;

Parse command-line parameters. Given a specification of your command-line options (in AOptions), we will find and pass these options to your OptionProc callback. The handled options will be removed from the Parameters list.

After running this, you should treat the remaining Parameters as "normal" parameters, usually a filenames to open by your program or such.

See also TOption for a specification of an option, and see TOptionArgument for a specification of an option argument, and see TOptionProc for a specification what your OptionProc callback gets.

Note that a single dash parameter is left alone, without making any exceptions, as this is a standard way of telling "standard input" or "standard output" for some programs.

Note that a double dash parameter -- is handled and removed from the Parameters list, and signals an end of options.

You should not modify Parameters list when this function is running, in particular do not modify it from your OptionProc callback. Also, do not depend on when the handled options are exactly removed from the Parameters list (before or after OptionProc callback).

We never touch here the Strings[0] value, we look only at the Strings[1] to Strings[High].

ParseOnlyKnownOptions = True makes this procedure work a little differently, it's designed to allow you to process some options and leave the rest options not handled (without making any error):

  1. The "known" short options (in Options param) are recognized only if they are not combined with other options. E.g. if you allow '-c' in Options, we will handle '-c' parameter, but 'c' will be ignored in combined '-abc' parameter.

  2. All unknown short and long options are ignored, without making any error.

  3. The special -- is handled (signals the end of options), but it's not removed from the Parameters.

The ParseOnlyKnownOptions = True is useful if you want to handle some command-line options, but you still want to leave final options parsing to a later code. For example TCastleWindow.ParseParameters parses some window parameters (like –geometry), leaving your program-specific stuff in peace.

Note that ParseOnlyKnownOptions = True isn't an absolutely fool-proof solution, for example the command-line castle-model-viewer –navigation –geometry 800x600 Walk is actually invalid. But we will handle it, by first detecting and removing –geometry 800x600 from TCastleWindow.ParseParameters, and then detecting and removing –navigation Walk from castle-model-viewer code. Basically, processing by Parse many times is not fool-proof in some weird situations.

Exceptions raised
EInvalidShortOption
On invalid (unknown) short option name.
EInvalidLongOption
On invalid long option name.
EExcessiveOptionArgument
When an option gets too many arguments, this may happen for options with oaNone or oaRequiredXSeparate that are specified with –option=argument form.
EMissingOptionArgument
When an option gets too few arguments, this may happen when argument for oaRequired option is missing, or when too few arguments are given for oaRequiredXSeparate option.
EInvalidParams
On invalid parameter without an option, like -=argument or –=argument.
Public procedure Parse(const AOptions: array of TOption; const OptionProc: TOptionProc; const OptionProcData: Pointer; const ParseOnlyKnownOptions: boolean = false); overload;

This item has no description.

Generated by PasDoc 0.16.0-snapshot.

Copyright Michalis Kamburelis and Castle Game Engine Contributors.

This webpage is also open-source and we welcome pull requests to improve it.

We use cookies for analytics. See our privacy policy.