/ 
Data-Tubes-0.740
River stage one • 1 direct dependent • 1 total dependent
/ tubergen

NAME

tubergen - generate Data::Tubes programs

USAGE

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]

EXAMPLES

# 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

DESCRIPTION

This program helps you getting started with Data::Tubes quickly. It's a minting program that generates a new script with all batteries included:

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.

Preamble

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.

Command Line Handling

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.

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.

Business Logic

This is where your business logic is supposed to be written, which is only yours.

Embedded Modules

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;

  • 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);

  • 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__.

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...

POD

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.

OPTIONS

--abstract text
-A text

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.

--author name
-a name

the name of the author of the program, used to initialize the POD section of the newly minted program. This option is required.

--email email-address
-e email-address

the email address of the author of the program, used to initialize the POD section of the newly minted program. This option is required.

--help

print a somewhat more verbose help, showing usage, this description of the options and some examples from the synopsis.

--man

print out the full documentation for the script.

--name program-name
-n program-name

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.

--output filename
-o filename

the filename where the program should be saved. Defaults to the value assigned to name.

--usage

print a concise usage line and exit.

--version

print the version of the script.

--year year
-y year

The year to set for starting the copyright of the newly minted program in the relevant POD section. Defaults to the current year.

DIAGNOSTICS

tubergen will complain if any of the required option is missing. It will also complain if you try to define unknown options.

CONFIGURATION AND ENVIRONMENT

tubergen requires no configuration files or environment variables.

BUGS AND LIMITATIONS

No bugs have been reported, but you can do this through Issues at https://github.com/polettix/Data-Tubes/issues.

AUTHOR

Flavio Poletti polettix@cpan.org

LICENCE AND COPYRIGHT

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.