Castle Game Engine: CastleParameters: Class TParameters

# 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
          view3dscene --navigation Walk
  - passes two parameters (`--navigation` and `Walk`) for view3dscene, and these two parameters form one option: `--navigation=Walk`. Command-line
          view3dscene -hv
passes one parameter (`-hv`) for view3dscene, 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 [http://castle-engine.sourceforge.net/common_options.php] for a user description how short and long options are expected to be given on the command-line. ## Hierarchy TStringList TCastleStringList TParameters ## Overview ### Methods
| `function High: Integer;`
| `procedure CheckHigh(ParamValue: integer);`
| `procedure CheckHighAtLeast(ParamValue: integer);`
| `procedure CheckHighAtMost(ParamValue: integer);`
| `function IsPresent(const A: array of string): boolean;`
| `procedure Parse(Options: POption_Array; OptionsCount: Integer; OptionProc: TOptionProc; OptionProcData: Pointer; ParseOnlyKnownLongOptions: boolean = false); overload;`
| `procedure Parse(const Options: array of TOption; OptionProc: TOptionProc; OptionProcData: Pointer; ParseOnlyKnownLongOptions: boolean = false); overload;`
## Description ### Methods
| `function High: Integer;`
| `procedure CheckHigh(ParamValue: integer);`
Does the number of parameters (High) satisfy given condition. ###### Exceptions raised EInvalidParams When High is wrong.
| `procedure CheckHighAtLeast(ParamValue: integer);`
| `procedure CheckHighAtMost(ParamValue: integer);`
| `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.
| `procedure Parse(Options: POption_Array; OptionsCount: Integer; OptionProc: TOptionProc; OptionProcData: Pointer; ParseOnlyKnownLongOptions: boolean = false); overload;`
Parse command-line parameters. Given a specification of your command-line options (in Options), 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]. ParseOnlyKnownLongOptions = `True` makes this procedure work a little differently, it's designed to allow you to process some long options and leave the rest options not handled (without making any error): All short options are ignored then. All unknown long options are also ignored, without making any error. The special -- is handled (signals the end of options), but it's not removed from the Parameters. The ParseOnlyKnownLongOptions = `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 TCastleWindowBase.ParseParameters parses some window parameters (like –geometry), leaving your program-specific stuff in peace. Note that ParseOnlyKnownLongOptions = `True` isn't an absolutely fool-proof solution, for example the command-line `view3dscene –navigation –geometry 800x600 Walk` is actually invalid. But we will handle it, by first detecting and removing `–geometry 800x600` from TCastleWindowBase.ParseParameters, and then detecting and removing `–navigation Walk` from view3dscene 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`.
| `procedure Parse(const Options: array of TOption; OptionProc: TOptionProc; OptionProcData: Pointer; ParseOnlyKnownLongOptions: boolean = false); overload;`
Generated by PasDoc 0.13.0 on 2013-08-17 21:27:13