| 1 | package App::Framework::Lite ; | ||
| 2 | |||
| 3 | =head1 NAME | ||
| 4 | |||
| 5 | App::Framework::Lite - A lightweight framework for creating applications | ||
| 6 | |||
| 7 | =head1 SYNOPSIS | ||
| 8 | |||
| 9 | use App::Framework::Lite ; | ||
| 10 | |||
| 11 | go() ; | ||
| 12 | |||
| 13 | sub app | ||
| 14 | { | ||
| 15 | my ($app, $opts_href, $args_href) = @_ ; | ||
| 16 | |||
| 17 | # options | ||
| 18 | my %opts = $app->options() ; | ||
| 19 | |||
| 20 | # aplication code here.... | ||
| 21 | } | ||
| 22 | |||
| 23 | |||
| 24 | =head1 DESCRIPTION | ||
| 25 | |||
| 26 | App::Framework::Lite is a framework for quickly developing application scripts, where the majority of the mundane script setup, | ||
| 27 | documentation jobs are performed by the framework (under direction from simple text definitions stored in the script). This leaves | ||
| 28 | the developer to concentrate on the main job of implementing the application. | ||
| 29 | |||
| 30 | The module also provides the facility of embedding itself into a copy of the original script, creating a self-contained stand-alone | ||
| 31 | script (for further details see L</EMBEDDING>). | ||
| 32 | |||
| 33 | Note that this module provides a subset of the the facilities provided by L<App::Framework>, In particular, it provides the L<App::Framework::Features:Args>, | ||
| 34 | L<App::Framework::Features:Options>, and L<App::Framework::Features:Data> features. | ||
| 35 | |||
| 36 | To jump straight in to developing applications, please see L<App::Framework::Lite::GetStarted>. | ||
| 37 | |||
| 38 | =head2 Capabilities | ||
| 39 | |||
| 40 | The application framework provides the following capabilities: | ||
| 41 | |||
| 42 | =over 2 | ||
| 43 | |||
| 44 | =item Options definition | ||
| 45 | |||
| 46 | Text definition of options in application, providing command line options, help pages, options checking. | ||
| 47 | |||
| 48 | Also supports variables in options definition, the variables being replaced by other option values, application field values, | ||
| 49 | or environment variables. | ||
| 50 | |||
| 51 | =item Arguments definition | ||
| 52 | |||
| 53 | Text definition of arguments in application, providing command line arguments, help pages, arguments checking, file/directory | ||
| 54 | creation, file/directory existence, file opening | ||
| 55 | |||
| 56 | Also supports variables in arguments definition, the variables being replaced by other argument values, option values, application field values, | ||
| 57 | or environment variables. | ||
| 58 | |||
| 59 | =item Named data sections | ||
| 60 | |||
| 61 | Multiple named __DATA__ sections, the data being readily accessible by name from the application. | ||
| 62 | |||
| 63 | Variables can be used in the data definitions, the variables being replaced by command line option values, application field values, | ||
| 64 | or environment variables. | ||
| 65 | |||
| 66 | |||
| 67 | =item Application directories | ||
| 68 | |||
| 69 | The framework automatically adds the location of the script (following any links) to the Perl search path. This means that perl modules | ||
| 70 | can be created in subdirectories under the application's script making the application self-contained. | ||
| 71 | |||
| 72 | The directories used for loading personalities/extensions/features also include the script install directory, meaning that new personalities/extensions/features | ||
| 73 | can also be provided with a script. | ||
| 74 | |||
| 75 | =back | ||
| 76 | |||
| 77 | |||
| 78 | =head2 Using This Module | ||
| 79 | |||
| 80 | The minimum you need is: | ||
| 81 | |||
| 82 | use App::Framework::Lite ; | ||
| 83 | |||
| 84 | Optionally, you can specify arguments to the underlying features by appending a string to the 'use' pragma. For exanmple: | ||
| 85 | |||
| 86 | use App::Framework::Lite '+Args(open=none)' ; | ||
| 87 | |||
| 88 | |||
| 89 | =head3 Creating Application Object | ||
| 90 | |||
| 91 | There are two ways of creating an application object and running it. The normal way is: | ||
| 92 | |||
| 93 | # Create application and run it | ||
| 94 | App::Framework::Lite->new()->go() ; | ||
| 95 | |||
| 96 | As an alternative, the framework creates a subroutine in the calling namespace called B<go()> which does the same thing: | ||
| 97 | |||
| 98 | # Create application and run it | ||
| 99 | go() ; | ||
| 100 | |||
| 101 | You can use whatever takes your fancy. Either way, the application object will end up calling the user-defined application subroutines | ||
| 102 | |||
| 103 | |||
| 104 | |||
| 105 | =head3 Application Subroutines | ||
| 106 | |||
| 107 | Once the application object has been created it can then be run by calling the 'go()' method. go() calls the application's registered functions | ||
| 108 | in turn: | ||
| 109 | |||
| 110 | =over 2 | ||
| 111 | |||
| 112 | =item * app_start() | ||
| 113 | |||
| 114 | Called at the start of the application. You can use this for any additional set up (usually of more use to extension developers) | ||
| 115 | |||
| 116 | =item * app() | ||
| 117 | |||
| 118 | Called once all of the arguments and options have been processed | ||
| 119 | |||
| 120 | =item * app_end() | ||
| 121 | |||
| 122 | Called when B<app()> terminates or returns (usually of more use to extension developers) | ||
| 123 | |||
| 124 | =back | ||
| 125 | |||
| 126 | The framework looks for these 3 functions to be defined in the script file. The functions B<app_start> and B<app_end> are optional, but it is expected that B<app> will be defined | ||
| 127 | (otherwise nothing happens!). | ||
| 128 | |||
| 129 | =head3 Setup | ||
| 130 | |||
| 131 | The application settings are entered into the __DATA__ section at the end of the file. All program settings are grouped under sections which are introduced by '[section]' style headings. There are many | ||
| 132 | different settings that can be set using this mechanism, but the framework sets most of them to useful defaults. | ||
| 133 | |||
| 134 | For more details see L</Options> and L</Args>. | ||
| 135 | |||
| 136 | =head4 Summary | ||
| 137 | |||
| 138 | This should be a single line, concise summary of what the script does. It's used in the terse man page created by pod2man. | ||
| 139 | |||
| 140 | =head4 Description | ||
| 141 | |||
| 142 | As you'd expect, this should be a full description, user-guide etc. on what the script does and how to do it. Notice that this example | ||
| 143 | has used one (of many) of the variables available: $name (which expands to the script name, without any path or extension). | ||
| 144 | |||
| 145 | |||
| 146 | =head4 Example | ||
| 147 | |||
| 148 | An example script setup is: | ||
| 149 | |||
| 150 | __DATA__ | ||
| 151 | |||
| 152 | [SUMMARY] | ||
| 153 | |||
| 154 | An example of using the application framework | ||
| 155 | |||
| 156 | [ARGS] | ||
| 157 | |||
| 158 | * infile=f Input file | ||
| 159 | |||
| 160 | Should be set to the input file | ||
| 161 | |||
| 162 | * indir=d Input dir | ||
| 163 | |||
| 164 | Should be set to the input dir | ||
| 165 | |||
| 166 | [OPTIONS] | ||
| 167 | |||
| 168 | -table=s Table [default=listings2] | ||
| 169 | |||
| 170 | Sql table name | ||
| 171 | |||
| 172 | -database=s Database [default=tvguide] | ||
| 173 | |||
| 174 | Sql database name | ||
| 175 | |||
| 176 | |||
| 177 | [DESCRIPTION] | ||
| 178 | |||
| 179 | B<$name> is an example script. | ||
| 180 | |||
| 181 | |||
| 182 | =head2 Args | ||
| 183 | |||
| 184 | Args feature that provides command line arguments handling. | ||
| 185 | |||
| 186 | Command line arguments are defined once in a text format and this text format generates both the command line arguments data, but also the man pages, | ||
| 187 | help text etc. Defining the expected arguments and their types allows the module to check for the existence of the program arguments and their correctness. | ||
| 188 | |||
| 189 | =head3 Argument Definition | ||
| 190 | |||
| 191 | Arguments are specified in the application __DATA__ section in the format: | ||
| 192 | |||
| 193 | * <name>=<specification> <Summary> <optional default setting> | ||
| 194 | |||
| 195 | <Description> | ||
| 196 | |||
| 197 | The parts of the specification are defined below. | ||
| 198 | |||
| 199 | =head4 name | ||
| 200 | |||
| 201 | The name defines the name of the key to use to access the argument value in the arguments hash. The application framework | ||
| 202 | passes a reference to the argument hash as the third parameter to the application subroutine B<app> (see L</Script Usage>) | ||
| 203 | |||
| 204 | =head4 specification | ||
| 205 | |||
| 206 | The specification is in the format: | ||
| 207 | |||
| 208 | [ <direction> ] [ <binary> ] <type> [ <multiple> ] | ||
| 209 | |||
| 210 | The optional I<direction> is only valid for file or directory types. For a file or directory types, if no direction is specified then | ||
| 211 | it is assumed to be input. Direction can be one of: | ||
| 212 | |||
| 213 | =over 4 | ||
| 214 | |||
| 215 | =item < | ||
| 216 | |||
| 217 | An input file or directory | ||
| 218 | |||
| 219 | =item > | ||
| 220 | |||
| 221 | An output file or directory | ||
| 222 | |||
| 223 | =item >> | ||
| 224 | |||
| 225 | An output appended file | ||
| 226 | |||
| 227 | =back | ||
| 228 | |||
| 229 | An optional 'b' after the direction specifies that the file is binary mode (only used when the type is file). | ||
| 230 | |||
| 231 | The B<type> must be specified and may be one of: | ||
| 232 | |||
| 233 | =over 4 | ||
| 234 | |||
| 235 | =item f | ||
| 236 | |||
| 237 | A file | ||
| 238 | |||
| 239 | =item d | ||
| 240 | |||
| 241 | A directory | ||
| 242 | |||
| 243 | =item s | ||
| 244 | |||
| 245 | Any string | ||
| 246 | |||
| 247 | =back | ||
| 248 | |||
| 249 | Additionally, an optional multiple can be specified. If used, this can only be specified on the last argument. When it is used, this tells the | ||
| 250 | application framework to use the last argument as an ARRAY, pushing all subsequent specified arguments onto this. Accessing the argument | ||
| 251 | in the script returns the ARRAY ref containing all of the command line argument values. | ||
| 252 | |||
| 253 | Multiple can be: | ||
| 254 | |||
| 255 | =over 4 | ||
| 256 | |||
| 257 | =item '@' | ||
| 258 | |||
| 259 | One or more items | ||
| 260 | |||
| 261 | =item '*' | ||
| 262 | |||
| 263 | Zero or more items. There is also a special case (the real reason for *) where the argument specification is of the form '<f*' (input file multiple). Here, if the script user does not | ||
| 264 | specify any arguments on the command line for this argument then the framework opens STDIN and provides it as a file handle. | ||
| 265 | |||
| 266 | =back | ||
| 267 | |||
| 268 | |||
| 269 | =head4 summary | ||
| 270 | |||
| 271 | The summary is a simple line of text used to summarise the argument. It is used in the man pages in 'usage' mode. | ||
| 272 | |||
| 273 | =head4 default | ||
| 274 | |||
| 275 | Defaults values are optional. If they are defined, they are in the format: | ||
| 276 | |||
| 277 | [default=<value>] | ||
| 278 | |||
| 279 | When a default is defined, if the user does not specify a value for an argument then that argument takes on the defualt value. | ||
| 280 | |||
| 281 | Also, all subsequent arguments must also be defined as optional. | ||
| 282 | |||
| 283 | =head4 description | ||
| 284 | |||
| 285 | The summary is multiple lines of text used to fully describe the option. It is used in the man pages in 'man' mode. | ||
| 286 | |||
| 287 | =head3 Feature Options | ||
| 288 | |||
| 289 | The Args feature allows control over how it opens files. By default, any input or output file definitions also create equivalent file handles | ||
| 290 | (the files being opened for read/write automatically). These file handles are made available only in the arguments HASH. The key name for the handle | ||
| 291 | being the name of the argument with the suffix '_fh'. | ||
| 292 | |||
| 293 | For example, the following definition: | ||
| 294 | |||
| 295 | [ARGS] | ||
| 296 | |||
| 297 | * file=f Input file | ||
| 298 | |||
| 299 | A simple input directory name (directory must exist) | ||
| 300 | |||
| 301 | * out=>f Output file (file will be created) | ||
| 302 | |||
| 303 | An output filename | ||
| 304 | |||
| 305 | And the command line arguments: | ||
| 306 | |||
| 307 | infile.txt outfile.txt | ||
| 308 | |||
| 309 | Results in the arguments HASH: | ||
| 310 | |||
| 311 | 'file' => 'infile.txt' | ||
| 312 | 'out' => 'outfile.txt' | ||
| 313 | 'file_fh' => <file handle of 'infile.txt'> | ||
| 314 | 'out_fh' => <file handle of 'outfile.txt'> | ||
| 315 | |||
| 316 | If this behaviour is not required, then you can get the framework to open just input files, output files, or none by using the 'open' option. | ||
| 317 | |||
| 318 | Specify this in the App::Framework 'use' line as an argument to the Args feature: | ||
| 319 | |||
| 320 | # Open no file handles | ||
| 321 | use App::Framework '+Args(open=none)' ; | ||
| 322 | |||
| 323 | # Open only input file handles | ||
| 324 | use App::Framework '+Args(open=in)' ; | ||
| 325 | |||
| 326 | # Open only output file handles | ||
| 327 | use App::Framework '+Args(open=out)' ; | ||
| 328 | |||
| 329 | # Open all file handles (the default) | ||
| 330 | use App::Framework '+Args(open=all)' ; | ||
| 331 | |||
| 332 | =head3 Variable Expansion | ||
| 333 | |||
| 334 | Argument values can contain variables, defined using the standard Perl format: | ||
| 335 | |||
| 336 | $<name> | ||
| 337 | ${<name>} | ||
| 338 | |||
| 339 | When the argument is used, the variable is expanded and replaced with a suitable value. The value will be looked up from a variety of possible sources: | ||
| 340 | object fields (where the variable name matches the field name) or environment variables. | ||
| 341 | |||
| 342 | The variable name is looked up in the following order, the first value found with a matching name is used: | ||
| 343 | |||
| 344 | =over 4 | ||
| 345 | |||
| 346 | =item * | ||
| 347 | |||
| 348 | Argument names - the values of any other arguments may be used as variables in arguments | ||
| 349 | |||
| 350 | =item * | ||
| 351 | |||
| 352 | Option names - the values of any command line options may be used as variables in arguments | ||
| 353 | |||
| 354 | =item * | ||
| 355 | |||
| 356 | Application fields - any fields of the $app object may be used as variables | ||
| 357 | |||
| 358 | =item * | ||
| 359 | |||
| 360 | Environment variables - if no application fields match the variable name, then the environment variables are used | ||
| 361 | |||
| 362 | =back | ||
| 363 | |||
| 364 | |||
| 365 | |||
| 366 | =head2 Script Usage | ||
| 367 | |||
| 368 | The application framework passes a reference to the argument HASH as the third parameter to the application subroutine B<app>. Alternatively, | ||
| 369 | the script can call the app object's alias to the args accessor, i.e. the B<args> method which returns the arguments value list. Yet another | ||
| 370 | alternative is to call the args accessor method directly. These alternatives are shown below: | ||
| 371 | |||
| 372 | |||
| 373 | sub app | ||
| 374 | { | ||
| 375 | my ($app, $opts_href, $args_href) = @_ ; | ||
| 376 | |||
| 377 | # use parameter | ||
| 378 | my $infile = $args_href->{infile} | ||
| 379 | |||
| 380 | # access alias | ||
| 381 | my @args = $app->args() ; | ||
| 382 | $infile = $args[0] ; | ||
| 383 | |||
| 384 | # access alias | ||
| 385 | @args = $app->Args() ; | ||
| 386 | $infile = $args[0] ; | ||
| 387 | |||
| 388 | ($infile) = $app->args('infile') ; | ||
| 389 | |||
| 390 | # feature object | ||
| 391 | @args = $app->feature('Args')->args() ; | ||
| 392 | $infile = $args[0] ; | ||
| 393 | } | ||
| 394 | |||
| 395 | |||
| 396 | |||
| 397 | =head3 Examples | ||
| 398 | |||
| 399 | With the following script definition: | ||
| 400 | |||
| 401 | [ARGS] | ||
| 402 | |||
| 403 | * file=f Input file | ||
| 404 | |||
| 405 | A simple input file name (file must exist) | ||
| 406 | |||
| 407 | * dir=d Input directory | ||
| 408 | |||
| 409 | A simple input directory name (directory must exist) | ||
| 410 | |||
| 411 | * out=>f Output file (file will be created) | ||
| 412 | |||
| 413 | An output filename | ||
| 414 | |||
| 415 | * outdir=>d Output directory | ||
| 416 | |||
| 417 | An output directory name (path will be created) | ||
| 418 | |||
| 419 | * append=>>f Output file append | ||
| 420 | |||
| 421 | An output filename (an existing file will be appended; otherwise file will be created) | ||
| 422 | |||
| 423 | * array=<f* All other args are input files | ||
| 424 | |||
| 425 | Any other command line arguments will be pushced on to this array. | ||
| 426 | |||
| 427 | The following command line arguments: | ||
| 428 | |||
| 429 | infile.txt indir outfile.txt odir append.txt file1.txt file2.txt file3.txt | ||
| 430 | |||
| 431 | Give the arguments HASH values: | ||
| 432 | |||
| 433 | 'file' => 'infile.txt' | ||
| 434 | 'file_fh' => <infile.txt file handle> | ||
| 435 | 'dir' => 'indir' | ||
| 436 | 'out' => 'outfile.txt' | ||
| 437 | 'out_fh' => <outfile.txt file handle> | ||
| 438 | 'outdir' => 'odir' | ||
| 439 | 'append' => 'append.txt' | ||
| 440 | 'append_fh'=> <append.txt file handle> | ||
| 441 | 'array' => [ | ||
| 442 | 'file1.txt' | ||
| 443 | 'file2.txt' | ||
| 444 | 'file3.txt' | ||
| 445 | ] | ||
| 446 | 'array_fh' => [ | ||
| 447 | <file1.txt file handle> | ||
| 448 | <file2.txt file handle> | ||
| 449 | <file3.txt file handle> | ||
| 450 | ] | ||
| 451 | |||
| 452 | |||
| 453 | An example script that uses the I<multiple> arguments, along with the default 'open' behaviour is: | ||
| 454 | |||
| 455 | sub app | ||
| 456 | { | ||
| 457 | my ($app, $opts_href, $args_href) = @_ ; | ||
| 458 | |||
| 459 | foreach my $fh (@{$args_href->{array_fh}}) | ||
| 460 | { | ||
| 461 | while (my $data = <$fh>) | ||
| 462 | { | ||
| 463 | # do something ... | ||
| 464 | } | ||
| 465 | } | ||
| 466 | } | ||
| 467 | |||
| 468 | __DATA__ | ||
| 469 | [ARGS] | ||
| 470 | * array=f@ Input file | ||
| 471 | |||
| 472 | |||
| 473 | This script can then be called with one or more filenames and each file will be processed. Or it can be called with no | ||
| 474 | filenames and STDIN will then be used. | ||
| 475 | |||
| 476 | |||
| 477 | =head2 Options | ||
| 478 | |||
| 479 | Options feature that provides command line options handling. | ||
| 480 | |||
| 481 | Options are defined once in a text format and this text format generates | ||
| 482 | both the command line options data, but also the man pages, help text etc. | ||
| 483 | |||
| 484 | =head3 Option Definition | ||
| 485 | |||
| 486 | Options are specified in the application __DATA__ section in the format: | ||
| 487 | |||
| 488 | -<name><specification> <Summary> <optional default setting> | ||
| 489 | |||
| 490 | <Description> | ||
| 491 | |||
| 492 | These user-specified options are added to the application framework options (defined dependent on whatever core/features/extensions are installed). | ||
| 493 | Also, the user may over ride default settings and descriptions on any application framework options by re-defining them in the script. | ||
| 494 | |||
| 495 | The parts of the specification are defined below. | ||
| 496 | |||
| 497 | =head4 name | ||
| 498 | |||
| 499 | The name defines the option name to be used at the command line, along with any command line option aliases (e.g. -log or -l, -logfile etc). Using the | ||
| 500 | option in the script is via a HASH where the key is the 'main' option name. | ||
| 501 | |||
| 502 | Where an option has one or more aliases, this list of names is separated by '|'. By default, the first name defined is the 'main' option name used | ||
| 503 | as the option HASH key. This may be overridden by quoting the name that is required to be the main name. | ||
| 504 | |||
| 505 | For example, the following name definitions: | ||
| 506 | |||
| 507 | -log|logfile|l | ||
| 508 | -l|'log'|logfile | ||
| 509 | -log | ||
| 510 | |||
| 511 | Are all access by the key 'log' | ||
| 512 | |||
| 513 | =head4 specification | ||
| 514 | |||
| 515 | (Note: This is a subset of the specification supported by L<Getopt::Long>). | ||
| 516 | |||
| 517 | The specification is optional. If not defined, then the option is a boolean value - is the user specifies the option on the command line | ||
| 518 | then the option value is set to 1; otherwise the option value is set to 0. | ||
| 519 | |||
| 520 | When the specification is defined, it is in the format: | ||
| 521 | |||
| 522 | [ <flag> ] <type> [ <desttype> ] | ||
| 523 | |||
| 524 | The option requires an argument of the given type. Supported types | ||
| 525 | are: | ||
| 526 | |||
| 527 | =over 4 | ||
| 528 | |||
| 529 | =item s | ||
| 530 | |||
| 531 | String. An arbitrary sequence of characters. It is valid for the | ||
| 532 | argument to start with C<-> or C<-->. | ||
| 533 | |||
| 534 | =item i | ||
| 535 | |||
| 536 | Integer. An optional leading plus or minus sign, followed by a | ||
| 537 | sequence of digits. | ||
| 538 | |||
| 539 | =item o | ||
| 540 | |||
| 541 | Extended integer, Perl style. This can be either an optional leading | ||
| 542 | plus or minus sign, followed by a sequence of digits, or an octal | ||
| 543 | string (a zero, optionally followed by '0', '1', .. '7'), or a | ||
| 544 | hexadecimal string (C<0x> followed by '0' .. '9', 'a' .. 'f', case | ||
| 545 | insensitive), or a binary string (C<0b> followed by a series of '0' | ||
| 546 | and '1'). | ||
| 547 | |||
| 548 | =item f | ||
| 549 | |||
| 550 | Real number. For example C<3.14>, C<-6.23E24> and so on. | ||
| 551 | |||
| 552 | =back | ||
| 553 | |||
| 554 | The I<desttype> can be C<@> or C<%> to specify that the option is | ||
| 555 | list or a hash valued. This is only needed when the destination for | ||
| 556 | the option value is not otherwise specified. It should be omitted when | ||
| 557 | not needed. | ||
| 558 | |||
| 559 | The I<flag>, if used, can be C<dev:> to specify that the option is meant for application developer | ||
| 560 | use only. In this case, the option will not be shown in the normal help and man pages, but will | ||
| 561 | only be shown when the -man-dev option is used. | ||
| 562 | |||
| 563 | =head4 summary | ||
| 564 | |||
| 565 | The summary is a simple line of text used to summarise the option. It is used in the man pages in 'usage' mode. | ||
| 566 | |||
| 567 | =head3 default | ||
| 568 | |||
| 569 | Defaults values are optional. If they are defined, they are in the format: | ||
| 570 | |||
| 571 | [default=<value>] | ||
| 572 | |||
| 573 | When a default is defined, if the user does not specify a value for an option then that option takes on the defualt value. | ||
| 574 | |||
| 575 | =head4 description | ||
| 576 | |||
| 577 | The summary is multiple lines of text used to fully describe the option. It is used in the man pages in 'man' mode. | ||
| 578 | |||
| 579 | =head3 Variable Expansion | ||
| 580 | |||
| 581 | Option values and default values can contain variables, defined using the standard Perl format: | ||
| 582 | |||
| 583 | $<name> | ||
| 584 | ${<name>} | ||
| 585 | |||
| 586 | When the option is used, the variable is expanded and replaced with a suitable value. The value will be looked up from a variety of possible sources: | ||
| 587 | object fields (where the variable name matches the field name) or environment variables. | ||
| 588 | |||
| 589 | The variable name is looked up in the following order, the first value found with a matching name is used: | ||
| 590 | |||
| 591 | =over 4 | ||
| 592 | |||
| 593 | =item * | ||
| 594 | |||
| 595 | Option names - the values of any other options may be used as variables in options | ||
| 596 | |||
| 597 | =item * | ||
| 598 | |||
| 599 | Application fields - any fields of the $app object may be used as variables | ||
| 600 | |||
| 601 | =item * | ||
| 602 | |||
| 603 | Environment variables - if no application fields match the variable name, then the environment variables are used | ||
| 604 | |||
| 605 | =back | ||
| 606 | |||
| 607 | =head3 Script Usage | ||
| 608 | |||
| 609 | The application framework passes a reference to the options HASH as the second parameter to the application subroutine B<app>. Alternatively, | ||
| 610 | the script can call the app object's alias to the options accessor, i.e. the B<options> method which returns the options hash. Yet another | ||
| 611 | alternative is to call the options accessor method directly. These alternatives are shown below: | ||
| 612 | |||
| 613 | |||
| 614 | sub app | ||
| 615 | { | ||
| 616 | my ($app, $opts_href, $args_href) = @_ ; | ||
| 617 | |||
| 618 | # use parameter | ||
| 619 | my $log = $opts_href->{log} | ||
| 620 | |||
| 621 | # access alias | ||
| 622 | my %options = $app->options() ; | ||
| 623 | $log = $options{log} ; | ||
| 624 | |||
| 625 | # access alias | ||
| 626 | %options = $app->Options() ; | ||
| 627 | $log = $options{log} ; | ||
| 628 | |||
| 629 | # feature object | ||
| 630 | %options = $app->feature('Options')->options() ; | ||
| 631 | $log = $options{log} ; | ||
| 632 | } | ||
| 633 | |||
| 634 | |||
| 635 | |||
| 636 | =head3 Examples | ||
| 637 | |||
| 638 | With the following script definition: | ||
| 639 | |||
| 640 | [OPTIONS] | ||
| 641 | |||
| 642 | -n|'name'=s Test name [default=a name] | ||
| 643 | |||
| 644 | String option, accessed as $opts_href->{name}. | ||
| 645 | |||
| 646 | -nomacro Do not create test macro calls | ||
| 647 | |||
| 648 | Boolean option, accessed as $opts_href->{nomacro} | ||
| 649 | |||
| 650 | -log=s Override default [default=another default] | ||
| 651 | |||
| 652 | Over rides the default log option (specified by the framework) | ||
| 653 | |||
| 654 | -int=i An integer | ||
| 655 | |||
| 656 | Example of integer option | ||
| 657 | |||
| 658 | -float=f An float | ||
| 659 | |||
| 660 | Example of float option | ||
| 661 | |||
| 662 | -array=s@ An array | ||
| 663 | |||
| 664 | Example of an array option | ||
| 665 | |||
| 666 | -hash=s% A hash | ||
| 667 | |||
| 668 | Example of a hash option | ||
| 669 | |||
| 670 | The following command line options are valid: | ||
| 671 | |||
| 672 | -int 1234 -float 1.23 -array a -array b -array c -hash key1=val1 -hash key2=val2 -nomacro | ||
| 673 | |||
| 674 | Giving the options HASH values: | ||
| 675 | |||
| 676 | 'name' => 'a name' | ||
| 677 | 'nomacro' => 1 | ||
| 678 | 'log' => 'another default' | ||
| 679 | 'int' => 1234 | ||
| 680 | 'float' => 1.23 | ||
| 681 | 'array' => [ 'a', 'b', 'c' ] | ||
| 682 | 'hash' => { | ||
| 683 | 'key1' => 'val1', | ||
| 684 | 'key2' => 'val2', | ||
| 685 | } | ||
| 686 | |||
| 687 | |||
| 688 | =head2 Data | ||
| 689 | |||
| 690 | After the settings (described above), one or more extra data areas can be created by starting that area with a new __DATA__ line. | ||
| 691 | |||
| 692 | The __DATA__ section at the end of the script is used by the application framework to allow the script developer to define | ||
| 693 | various settings for his/her script. This setup is split into "headed" sections of the form: | ||
| 694 | |||
| 695 | [ <section name> ] | ||
| 696 | |||
| 697 | <settings> | ||
| 698 | |||
| 699 | In general, the <section name> is the name of a field value in the application, and <settings> is some text that the field will be set to. Sections | ||
| 700 | of this type are: | ||
| 701 | |||
| 702 | =over 4 | ||
| 703 | |||
| 704 | =item B<[SUMMARY]> - Application summary text | ||
| 705 | |||
| 706 | A single line summary of the application. Used for man pages and usage summary. | ||
| 707 | |||
| 708 | (Stored in the application's I<summary> field). | ||
| 709 | |||
| 710 | =item B<[DESCRIPTION]> - Application description text | ||
| 711 | |||
| 712 | Multiple line description of the application. Used for man pages. | ||
| 713 | |||
| 714 | (Stored in the application's I<description> field). | ||
| 715 | |||
| 716 | =item B<[SYNOPSIS]> - Application synopsis [I<optional>] | ||
| 717 | |||
| 718 | Multiple line synopsis of the application usage. By default the application framework creates this if it is not specified. | ||
| 719 | |||
| 720 | (Stored in the application's I<synopsis> field). | ||
| 721 | |||
| 722 | =item B<[NAME]> - Application name [I<optional>] | ||
| 723 | |||
| 724 | Name of the application usage. By default the application framework creates this if it is not specified. | ||
| 725 | |||
| 726 | (Stored in the application's I<name> field). | ||
| 727 | |||
| 728 | =back | ||
| 729 | |||
| 730 | __DATA__ sections that have special meaning are: |