tubergen - generate Data::Tubes programs
tubergen [--usage] [--help] [--man] [--version] tubergen --abstract|-A text --author|-a name --email|-e email-address --name|-n program-name --output|-o filename [--year|-y year]
# generate file my-script in current directory shell$ tubergen -n my-script -A 'this script does that' \ -a 'A. U. Thor' -e 'a.u.thor@example.com' # override output filename, e.g. to put in different directory shell$ tubergen -n my-script -A 'this script does that' \ -a 'A. U. Thor' -e 'a.u.thor@example.com' \ -o /path/to/my-script # you can optionally force setting a different year for copyright shell$ tubergen -n my-script -A 'this script does that' \ -a 'A. U. Thor' -e 'a.u.thor@example.com' -y 2020
This program helps you getting started with Data::Tubes quickly. It's a minting program that generates a new script with all batteries included:
Data::Tubes different modules and plugins, of course
Log::Log4perl::Tiny
Template::Perlish
Try::Tiny
The last one is optional in Data::Tubes, but it is extremely handy and allows you using all plugins to their full potential, so why not?
Generating a new program requires you to provide four options:
a name for your program;
an abstract to (briefly) describe what your program does;
the author name;
the email of the author.
This allows kickstarting the POD section of your new program. You can also optionally pass argument output, to set the output filename (which is equal to name by default>) and a year for the copyright notice (the current year is used by default).
After you generate the minted program, you end up with a Perl source file containing the following sections:
an initial, unnamed section that you're supposed to leave AS-IS;
a "Preamble" with housekeeping that will help get the new program started with using the included batteries;
a "Command Line Handling" section for defining how your program accepts its inputs;
a "Business Logic" section for putting your code;
an "Embedded Modules" section with the batteries;
a "POD" section where you can write the documentation for your new program.
You will normally need to mind about "Command Line Handling", "Business Logic" and "POD", although it's good for you to know about all of them. Each part is explained in depth in the sub-sections below.
The preamble is where the initial setup is done so that you can use modules (embedded or local). You can get rid of components you don't need, of course.
If you need to use additional modules, this is probably a good point to do it. Otherwise, you can just use them in the "Business Logic" section, as you see fit.
use
Command line handling is performed via Getopt::Long behind the scenes. Here you have a simplified interface that should (hopefully) be what you need most of the times.
Handling of command line is performed by subroutine get_options, that returns a hash (key-value pairs) or hash reference depending on calling context. In the default section, you get hash %config back.
get_options
%config
Options are defined as a sequence of elements, each of which can be either a string or an array reference. The string alternative is exactly the same as what is accepted by Getopt::Long. The array reference alternative has the following structure:
the first element is the Getopt::Long specification string;
the following elements are key-value pairs that are put in a hash of options. Recognised keys are:
default
a default value for the option. This is used to initialize the returned hash before the command line is analyzed;
fallback
a default value for the option. This is used to initialize the returned hash after the command line is analyzed;
required
this marks whether an option is required or not, set via anything that Perl considers true or false depending on your needs. Default is false.
The difference between "default" and "fallback" is negligible for most options, but you might e.g. set initial values for a multiple-valued option (in which case you will want to set it as "default") or pass a value that would not be considered good for Getopt::Long (e.g. you cannot pre-initialize options with GLOBs, in which case you would choose "fallback"). In general, use "default" unless you really need "fallback".
The newly minted program contains a few examples to get you started. You might want to keep the first one on loglevel though, as it will help you set the logging level of the script automatically.
This is where your business logic is supposed to be written, which is only yours.
Your business logic is supposed to live in section "Business Logic", so you should generally not need to put anything here.
This section contains most of the batteries included. It has the options parsing function get_options and the logic for embedding all modules.
If you want to embed additional pure-Perl modules you are welcome to do this. Just follow the example of the other modules, namely:
add items inside the hash %file_for defined at the top of the BEGIN section;
%file_for
BEGIN
each item's key is a relative file name of the module, as if it was in some lib directory (see shipped modules for an example);
lib
each item's value is a string with the whole contents of your module, where each line is pre-pended with a single space character (ASCII 0x20). This character will be automatically removed and allows you to safely use here-documents, again see the included modules for an effective example;
although not strictly necessary, for your convenience you might want to keep the relative position of different comment markers starting with string __MOBUNDLE__.
__MOBUNDLE__
Example:
BEGIN { my %file_for = ( # __MOBUNDLE_FILES__ # __MOBUNDLE_FILE__ # this is for embedding Some::Module. Note that the # contents of the heredoc is indented by one space at # each line "Some/Module.pm" => <<'END_OF_FILE'; # # Some::Module contents, each line is indented by one space # so that e.g. the following lines will not mess all things # up: my $something = <<'END_OF_FILE' What...ever! END_OF_FILE # The line above is indented, so it is ignored by the # program's heredoc. The real boundary for the included # module is the line below. END_OF_FILE # __MOBUNDLE_FILE__ # # ... REST OF %file_for hash...
This is where you are supposed to write extensive documentation for your new program. There's some scaffolding to get you started, initialized with the required values provided during the minting process. perlpod will be your friend here.
a (brief) text describing what your program does. This parameter that is used to initialize the POD section of the newly minted program. This option is required.
the name of the author of the program, used to initialize the POD section of the newly minted program. This option is required.
the email address of the author of the program, used to initialize the POD section of the newly minted program. This option is required.
print a somewhat more verbose help, showing usage, this description of the options and some examples from the synopsis.
print out the full documentation for the script.
the name assigned to the program. This is used to both initialize the POD section of the newly minted program, and as the file name where it is saved to. You can override the filename with option output. This option is required.
the filename where the program should be saved. Defaults to the value assigned to name.
print a concise usage line and exit.
print the version of the script.
The year to set for starting the copyright of the newly minted program in the relevant POD section. Defaults to the current year.
tubergen will complain if any of the required option is missing. It will also complain if you try to define unknown options.
tubergen requires no configuration files or environment variables.
No bugs have been reported, but you can do this through Issues at https://github.com/polettix/Data-Tubes/issues.
Flavio Poletti polettix@cpan.org
Copyright (c) 2016, Flavio Poletti polettix@cpan.org
This program is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
This program embeds all modules from distribution Data::Tubes, that is Copyright (C) 2016 by Flavio Poletti and licensed under the Artistic License 2.0. See https://metacpan.org/pod/Data::Tubes for further details.
This program embeds Mo and Mo::default from distribution Mo, that is Copyright (c) 2011-2013. Ingy döt Net and licensed under the same terms of Perl itself. See "/www.perl.com/perl/misc/Artistic.html" in See http: for the license and https://metacpan.org/pod/Mo for further details.
This program embeds Log::Log4perl::Tiny, that is Copyright (C) 2010-2016 by Flavio Poletti and licensed under the Artistic License 2.0. See https://metacpan.org/pod/Log::Log4perl::Tiny for further details.
This program embeds Template::Perlish, that is Copyright (C) 2008-2016 by Flavio Poletti and licensed under the Artistic License 2.0. See https://metacpan.org/pod/Template::Perlish for further details.
This program embeds Try::Tiny, that is Copyright (c) 2009 by יובל קוג'מן (Yuval Kogman) and licensed under The MIT (X11) License. See https://metacpan.org/pod/Try::Tiny for further details.
To install Data::Tubes, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Data::Tubes
CPAN shell
perl -MCPAN -e shell install Data::Tubes
For more information on module installation, please visit the detailed CPAN module installation guide.