1Applify(3) User Contributed Perl Documentation Applify(3)
2
6 Applify - Write object oriented scripts with ease
7
9 0.16
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($self, @extra) = @_;
34 my $exit_value = 0;
35 print "Extra arguments: @extra\n" if(@extra);
37 print "Will read from: ", $self->input_file, "\n";
38 print "Will write files to: ", $self->output_dir, "\n";
39 if($self->dry_run) {
41 die 'Will not run script';
42 }
43 return $self->generate_exit_value;
45 };
46
48 This module will generate an application class, which $self inside the
49 "app" block refer to. This class will have:
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 $self
63 inside "app{}".
64 · "_script()"
66 This is an accessor which return the Applify object which is refered
68 to as $self 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 $self. Additionally, similar to Moose attributes,
88 a "has_$name" method will be generated, which can be called on $self to
89 determine if the "option" has been set, either by a user or from the
90 $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 $self = shift;
119 print $self->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 subcommand
198 subcommand list => 'provide a listing objects' => sub {
199 option flag => long => 'long listing';
200 option flag => recursive => 'recursively list objects';
201 };
202 subcommand create => 'create a new object' => sub {
204 option str => name => 'name of new object', required => 1;
205 option str => description => 'description for the object', required => 1;
206 };
207 sub command_create {
209 my ($self, @extra) = @_;
210 ## do creating
211 return 0;
212 }
213 sub command_list {
215 my ($self, @extra) = @_;
216 ## do listing
217 return 0;
218 }
219 app {
221 my ($self, @extra) = @_;
222 ## fallback when no command given.
223 $self->_script->print_help;
224 return 0;
225 };
226 This function allows for creating multiple related sub commands within
228 the same script in a similar fashion to "git". The "option", "extends"
229 and "documentation" exported functions may sensibly be called within
230 the subroutine. Calling the function with no arguments will return the
231 running subcommand, i.e. a valid $ARGV[0]. Non valid values for the
232 subcommand given on the command line will result in the help being
233 displayed.
234 app
236 app CODE;
237 This function will define the code block which is called when the
239 application is started. See "SYNOPSIS" for example code. This function
240 can also be called as a method on $self.
241 IMPORTANT: This function must be the last function called in the script
243 file for unit tests to work. Reason for this is that this function runs
244 the application in void context (started from command line), but
245 returns the application object in list/scalar context (from "do" in
246 perlfunc).
247
249 option_parser
250 $self = $self->option_parser(Getopt::Long::Parser->new);
251 $parser = $self->option_parser;
252 You can specify your own option parser if you have special needs. The
254 default is:
255 Getopt::Long::Parser->new(config => [qw(no_auto_help no_auto_version pass_through)]);
257 options
259 $array_ref = $self->options;
260 Holds the application options given to "option".
262
264 new
265 $self = $class->new({options => $array_ref, ...});
266 Object constructor. Creates a new object representing the script meta
268 information.
269 print_help
271 Will print "options" to selected filehandle (STDOUT by default) in a
272 normalized matter. Example:
273 Usage:
275 --foo Foo does this and that
276 * --bar Bar does something else
277 --help Print this help text
279 --man Display manual for this application
280 --version Print application name and version
281 print_version
283 Will print "version" to selected filehandle (STDOUT by default) in a
284 normalized matter. Example:
285 some-script.pl version 1.23
287 import
289 Will export the functions listed under "EXPORTED FUNCTIONS". The
290 functions will act on a Applify object created by this method.
291
293 This library is free software. You can redistribute it and/or modify it
294 under the same terms as Perl itself.
295
297 Jan Henning Thorsen - "jhthorsen@cpan.org"
298 Roy Storey - "kiwiroy@cpan.org"
300perl v5.30.0 2019-08-11 Applify(3)