1Applify(3)            User Contributed Perl Documentation           Applify(3)
2
3
4

NAME

6       Applify - Write object oriented scripts with ease
7

VERSION

9       0.22
10

DESCRIPTION

12       This module should keep all the noise away and let you write scripts
13       very easily. These scripts can even be unit tested even though they are
14       defined directly in the script file and not in a module.
15

SYNOPSIS

17         #!/usr/bin/perl
18         use Applify;
19
20         option file => input_file => 'File to read from';
21         option dir => output_dir => 'Directory to write files to';
22         option flag => dry_run => 'Use --no-dry-run to actually do something', 1;
23
24         documentation __FILE__;
25         version 1.23;
26
27         sub generate_exit_value {
28           return int rand 100;
29         }
30
31         # app {...}; must be the last statement in the script
32         app {
33           my ($app, @extra) = @_;
34           my $exit_value = 0;
35
36           print "Extra arguments: @extra\n" if(@extra);
37           print "Will read from: ", $app->input_file, "\n";
38           print "Will write files to: ", $app->output_dir, "\n";
39
40           if($app->dry_run) {
41             die 'Will not run script';
42           }
43
44           return $app->generate_exit_value;
45         };
46

APPLICATION CLASS

48       This module will generate an application class, which $app inside the
49       "app" block is an instance of. The class will have these methods:
50
51       • "new()"
52
53         An object constructor. This method will not be auto generated if any
54         of the classes given to "extends" has the method "new()".
55
56       • "run()"
57
58         This method is basically the code block given to "app".
59
60       • Other methods
61
62         Other methods defined in the script file will be accesible from $app
63         inside "app{}".
64
65       • "_script()"
66
67         This is an accessor which return the Applify object which is refered
68         to as $script in this documentation.
69
70         NOTE: This accessor starts with an underscore to prevent conflicts
71         with "options".
72
73       • Other accessors
74
75         Any "option" (application option) will be available as an accessor on
76         the application object.
77

EXPORTED FUNCTIONS

79   option
80         option $type => $name => $documentation;
81         option $type => $name => $documentation, $default;
82         option $type => $name => $documentation, $default, @args;
83         option $type => $name => $documentation, @args;
84
85       This function is used to define options which can be given to this
86       application. See "SYNOPSIS" for example code. This function can also be
87       called as a method on $script. Additionally, similar to Moose
88       attributes, a "has_$name" method will be generated, which can be called
89       on $app to determine if the "option" has been set, either by a user or
90       from the $default.
91
92       • $type
93
94         Used to define value types for this input. Can be:
95
96           | $type | Example             | Attribute value |
97           |-------|---------------------|-----------------|
98           | bool  | --foo, --no-foo     | foo=1, foo=0    |
99           | flag  | --foo, --no-foo     | foo=1, foo=0    |
100           | inc   | --verbose --verbose | verbose=2       |
101           | str   | --name batwoman     | name=batwoman   |
102           | int   | --answer 42         | answer=42       |
103           | num   | --pie 3.14          | pie=3.14        |
104
105       • $name
106
107         The name of an application option. This name will also be used as
108         accessor name inside the application. Example:
109
110           # define an application option:
111           option file => some_file => '...';
112
113           # call the application from command line:
114           > myapp.pl --some-file /foo/bar
115
116           # run the application code:
117           app {
118             my $app = shift;
119             print $app->some_file # prints "/foo/bar"
120             return 0;
121           };
122
123       • $documentation
124
125         Used as description text when printing the usage text.
126
127       • $default
128
129         Either a plain value or a code ref that can be used to generate a
130         value.
131
132           option str => passwd => "Password file", "/etc/passwd";
133           option str => passwd => "Password file", sub { "/etc/passwd" };
134
135       • @args
136
137         • "alias"
138
139           Used to define an alias for the option. Example:
140
141             option inc => verbose => "Output debug information", alias => "v";
142
143         • "required"
144
145           The script will not start if a required field is omitted.
146
147         • "n_of"
148
149           Allow the option to hold a list of values. Examples: "@", "4",
150           "1,3".  See "Options-with-multiple-values" in Getopt::Long for
151           details.
152
153         • "isa"
154
155           Can be used to either specify a class that the value should be
156           instantiated as, or a Type::Tiny object that will be used for
157           coercion and/or type validation.
158
159           Example using a class:
160
161             option file => output => "output file", isa => "Mojo::File";
162
163           The "output()" attribute will then later return an object of
164           Mojo::File, instead of just a plain string.
165
166           Example using Type::Tiny:
167
168             use Types::Standard "Int";
169             option num => age => "Your age", isa => Int;
170
171         • Other
172
173           Any other Moose attribute argument may/will be supported in future
174           release.
175
176   documentation
177         documentation __FILE__; # current file
178         documentation '/path/to/file';
179         documentation 'Some::Module';
180
181       Specifies where to retrieve documentaion from when giving the "--man"
182       option to your script.
183
184   version
185         version 'Some::Module';
186         version $num;
187
188       Specifies where to retrieve the version number from when giving the
189       "--version" option to your script.
190
191   extends
192         extends @classes;
193
194       Specify which classes this application should inherit from. These
195       classes can be Moose based.
196
197   hook
198         hook before_exit            => sub { my ($script, $exit_value) = @_ };
199         hook before_options_parsing => sub { my ($script, $argv) = @_ };
200
201       Defines a hook to run.
202
203       • before_exit
204
205         Called right before "exit($exit_value)" is called by Applify. Note
206         that this hook will not be called if an exception is thrown.
207
208       • before_options_parsing
209
210         Called right before $argv is parsed by "option_parser". $argv is an
211         array-ref of the raw options given to your application. This hook
212         allows you to modify "option_parser". Example:
213
214           hook before_options_parsing => sub {
215             shift->option_parser->configure(bundling no_pass_through);
216           };
217
218   subcommand
219         subcommand list => 'provide a listing objects' => sub {
220           option flag => long => 'long listing';
221           option flag => recursive => 'recursively list objects';
222         };
223
224         subcommand create => 'create a new object' => sub {
225           option str => name => 'name of new object', required => 1;
226           option str => description => 'description for the object', required => 1;
227         };
228
229         sub command_create {
230           my ($app, @extra) = @_;
231           ## do creating
232           return 0;
233         }
234
235         sub command_list {
236           my ($app, @extra) = @_;
237           ## do listing
238           return 0;
239         }
240
241         app {
242           my ($app, @extra) = @_;
243           ## fallback when no command given.
244           $app->_script->print_help;
245           return 0;
246         };
247
248       This function allows for creating multiple related sub commands within
249       the same script in a similar fashion to "git". The "option", "extends"
250       and "documentation" exported functions may sensibly be called within
251       the subroutine. Calling the function with no arguments will return the
252       running subcommand, i.e. a valid $ARGV[0]. Non valid values for the
253       subcommand given on the command line will result in the help being
254       displayed.
255
256   app
257         app CODE;
258
259       This function will define the code block which is called when the
260       application is started. See "SYNOPSIS" for example code. This function
261       can also be called as a method on $script.
262
263       IMPORTANT: This function must be the last function called in the script
264       file for unit tests to work. Reason for this is that this function runs
265       the application in void context (started from command line), but
266       returns the application object in list/scalar context (from "do" in
267       perlfunc).
268

ATTRIBUTES

270   option_parser
271         $script = $script->option_parser(Getopt::Long::Parser->new);
272         $parser = $script->option_parser;
273
274       You can specify your own option parser if you have special needs. The
275       default is:
276
277         Getopt::Long::Parser->new(config => [qw(no_auto_help no_auto_version pass_through)]);
278
279   options
280         $array_ref = $script->options;
281
282       Holds the application options given to "option".
283

METHODS

285   new
286         $script = Applify->new({options => $array_ref, ...});
287
288       Object constructor. Creates a new object representing the script meta
289       information.
290
291   print_help
292       Will print "options" to selected filehandle (STDOUT by default) in a
293       normalized matter. Example:
294
295         Usage:
296            --foo      Foo does this and that
297          * --bar      Bar does something else
298
299            --help     Print this help text
300            --man      Display manual for this application
301            --version  Print application name and version
302
303   print_version
304       Will print "version" to selected filehandle (STDOUT by default) in a
305       normalized matter. Example:
306
307         some-script.pl version 1.23
308
309   import
310       Will export the functions listed under "EXPORTED FUNCTIONS". The
311       functions will act on a Applify object created by this method.
312
314       This library is free software. You can redistribute it and/or modify it
315       under the same terms as Perl itself.
316

AUTHORS

318       Jan Henning Thorsen - "jhthorsen@cpan.org"
319
320       Roy Storey - "kiwiroy@cpan.org"
321
322
323
324perl v5.32.1                      2021-01-26                        Applify(3)
Impressum