Lite.pm

filter: Statementstmt 74.6% 1180 / 1581 Branchbran 54.2% 398 / 734 Conditioncond 55.2% 89 / 161 MC/DCmcdc 40.4% 38 / 94 Subroutinesub 84.6% 99 / 117 Podpod 100% 50 / 50 totaltotal 67.7% 1854 / 2737 CC 494 SCAR 60.7
CC
494
Cov
67%
_module_str
3906.0
embed
462.0
expand_keys
96.3
CRAP 434.4
↑ Summary Lite/Object.pm »
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:
↑ Summary Lite/Object.pm »