1Applify(3) User Contributed Perl Documentation Applify(3)
2
6 Applify - Write object oriented scripts with ease
7
9 0.23
10
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
17 #!/usr/bin/perl
18 use Applify;
19 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 documentation __FILE__;
25 version 1.23;
26 sub generate_exit_value {
28 return int rand 100;
29 }
30 # app {...}; must be the last statement in the script
32 app {
33 my ($app, @extra) = @_;
34 my $exit_value = 0;
35 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 if($app->dry_run) {
41 die 'Will not run script';
42 }
43 return $app->generate_exit_value;
45 };
46
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 • new()
52 An object constructor. This method will not be auto generated if any
54 of the classes given to "extends" has the method new().
55 • run()
57 This method is basically the code block given to "app".
59 • Other methods
61 Other methods defined in the script file will be accesible from $app
63 inside "app{}".
64 • _script()
66 This is an accessor which return the Applify object which is refered
68 to as $script in this documentation.
69 NOTE: This accessor starts with an underscore to prevent conflicts
71 with "options".
72 • Other accessors
74 Any "option" (application option) will be available as an accessor on
76 the application object.
77
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 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 • $type
93 Used to define value types for this input. Can be:
95 | $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 • $name
106 The name of an application option. This name will also be used as
108 accessor name inside the application. Example:
109 # define an application option:
111 option file => some_file => '...';
112 # call the application from command line:
114 > myapp.pl --some-file /foo/bar
115 # run the application code:
117 app {
118 my $app = shift;
119 print $app->some_file # prints "/foo/bar"
120 return 0;
121 };
122 • $documentation
124 Used as description text when printing the usage text.
126 • $default
128 Either a plain value or a code ref that can be used to generate a
130 value.
131 option str => passwd => "Password file", "/etc/passwd";
133 option str => passwd => "Password file", sub { "/etc/passwd" };
134 • @args
136 • "alias"
138 Used to define an alias for the option. Example:
140 option inc => verbose => "Output debug information", alias => "v";
142 • "required"
144 The script will not start if a required field is omitted.
146 • "n_of"
148 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 • "isa"
154 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 Example using a class:
160 option file => output => "output file", isa => "Mojo::File";
162 The output() attribute will then later return an object of
164 Mojo::File, instead of just a plain string.
165 Example using Type::Tiny:
167 use Types::Standard "Int";
169 option num => age => "Your age", isa => Int;
170 • Other
172 Any other Moose attribute argument may/will be supported in future
174 release.
175 documentation
177 documentation __FILE__; # current file
178 documentation '/path/to/file';
179 documentation 'Some::Module';
180 Specifies where to retrieve documentaion from when giving the "--man"
182 option to your script.
183 version
185 version 'Some::Module';
186 version $num;
187 Specifies where to retrieve the version number from when giving the
189 "--version" option to your script.
190 extends
192 extends @classes;
193 Specify which classes this application should inherit from. These
195 classes can be Moose based.
196 hook
198 hook before_exit => sub { my ($script, $exit_value) = @_ };
199 hook before_options_parsing => sub { my ($script, $argv) = @_ };
200 Defines a hook to run.
202 • before_exit
204 Called right before exit($exit_value) is called by Applify. Note that
206 this hook will not be called if an exception is thrown.
207 • before_options_parsing
209 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 hook before_options_parsing => sub {
215 shift->option_parser->configure(bundling no_pass_through);
216 };
217 subcommand
219 subcommand list => 'provide a listing objects' => sub {
220 option flag => long => 'long listing';
221 option flag => recursive => 'recursively list objects';
222 };
223 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 sub command_create {
230 my ($app, @extra) = @_;
231 ## do creating
232 return 0;
233 }
234 sub command_list {
236 my ($app, @extra) = @_;
237 ## do listing
238 return 0;
239 }
240 app {
242 my ($app, @extra) = @_;
243 ## fallback when no command given.
244 $app->_script->print_help;
245 return 0;
246 };
247 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 app
257 app CODE;
258 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 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
270 option_parser
271 $script = $script->option_parser(Getopt::Long::Parser->new);
272 $parser = $script->option_parser;
273 You can specify your own option parser if you have special needs. The
275 default is:
276 Getopt::Long::Parser->new(config => [qw(no_auto_help no_auto_version pass_through)]);
278 options
280 $array_ref = $script->options;
281 Holds the application options given to "option".
283
285 new
286 $script = Applify->new({options => $array_ref, ...});
287 Object constructor. Creates a new object representing the script meta
289 information.
290 print_help
292 Will print "options" to selected filehandle (STDOUT by default) in a
293 normalized matter. Example:
294 Usage:
296 --foo Foo does this and that
297 * --bar Bar does something else
298 --help Print this help text
300 --man Display manual for this application
301 --version Print application name and version
302 print_version
304 Will print "version" to selected filehandle (STDOUT by default) in a
305 normalized matter. Example:
306 some-script.pl version 1.23
308 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
318 Jan Henning Thorsen - "jhthorsen@cpan.org"
319 Roy Storey - "kiwiroy@cpan.org"
321perl v5.36.0 2023-01-19 Applify(3)