Aldebaran that's cool!

The question I ask myself at this stage is whether I want all the functionality to go into a script or shall I create some high-level functions or even a class and store into the module. I usually prefer the latter and in most cases a class. For example, in your case you need to read the API key from the configuration each time you send for a translation. That can probably be stored in your class. So you get functionality like:

use My::Translator;

my $trans = My::Translator->new(Config => 'config.txt');
my ($ret, $conf) = $trans->translate("abc xyz");
print "output is '$ret' with confidence $conf %\n";
[download]

but even without a class/OOP you get a nice high-level API like:

use My::Translator;
my $conf = Config::Tiny...
my $prep = My::Translator::prepare_with_some_transformations("abc xyz"
+);
my ($ret, $conf) = My::Translator::translate($prep, $conf);
print "output is '$ret' (via $prep) with confidence $conf %\n";
[download]

btw, if you have any scripts you want installed via make install, then insert an EXE_FILES => ['bin/myscript.pl'] into Makefile.PL as a parameter to WriteMakefile() (e.g. just below PL_FILES => {},. In this way make install will install your script(s) along with any module files.

Edit: I also find useful setting temporarily (when doing my own tests) INSTALL_BASE => '$ENV{HOME}".'/usr', as a parameter to WriteMakefile() will install this module in user's own /home/user/usr dir which does not require admin rights.

I was hoping to see a response from bliako, as I've been nibbling away at his recent meditation git-push target for Makefile (via ExtUtils::MakeMaker). This response gets long without even trying, so more between readmore tags:

Read more... (18 kB)

Thanks for your comments,

then insert an EXE_FILES => 'bin/myscript.pl' into Makefile.PL

Is this the bin directory where 1.myscript.pl should end up?

This is the path where each of the scripts you want installed system-wide (or user-dir-wide) LIVE NOW, in your module file structure. Their destination/installed dir is decided by the maker - you do not need to worry about that right now. Beware, I said EXE_FILES => ['bin/myscript.pl'], i.e. one or more scripts go into an array-ref (you need to enclose yours within square brackets). It's correct in your Makefile.PL but you cited it slightly wrong that's all.

WARNING: Setting ABSTRACT via file 'lib/translate.pm' failed

see What does this ABSTRACT warning from MakeMaker mean?

My first question is whether I had to use

require Exporter;

our @ISA = qw(Exporter);
our @EXPORT =
  qw(  get_config get_trans get_from_lang get_to_lang reverse_trans);
[download]

No you didn't have to but it is considered good practice not to "pollute the namespace of your module's users". Without exporting something, its access can be done via its full qualifier e.g. translate::get_from_lang();. You can not call that sub by using the shorter: get_from_lang(). Because it is not exported to the namespace of your module's users, unless you did so explicitly via the our @EXPORT mechanism. See also Selecting What to Export.

Directory t/ contains all the test files run when you do make test. A few have already been created automatically by ExtUtils::MakeMaker and check for example if loading the module succeeds. In t/ you can add your own test files. For example there could be a test file which checks the functionality of get_config. I would call that test file t/01-get_config.t and could have something like this inside it:

# t/01-get_config.t
use strict;
use warnings;

use lib 'blib/lib';

use Test::More;
use translate;
my $num_tests = 0;
my $ini_path = qw( /home/bob/Documents/html_template_data/3.values.ini
+ );
my $sub_hash = "google";

my $key = get_config($ini_path, $sub_hash);
ok(defined $key, "get_config() : key defined"); $num_tests++;
ok($key eq 'blahblah', "get_config() : key has correct value"); $num_t
+ests++;
# END
done_testing($num_tests);
[download]

After a user downloads your module, they should make test prior to installing it in order to make sure that the module works fine on their system (as opposed to working fine on author's system). So you must include as many test files as necessary to cover every aspect of your module's functionality. Perhaps as a minimum you should test the functionality of all your functions (exported/public or private). The more the better but not necessarily. Test files also help you to make sure that it works after you make a small change here or there: make a change, then run the tests. does it work? then your change *seems* not to have broken something. *seems*: always in relation to how well and comprehensive your test files are.

Also, your module accesses a remote website. Testing this on a user's machine may not be a good idea, not without their permission perhaps. It will also fail without network access. I do not know what's considered a good practice in this situation.

Directory xt/ should contain all the test files meant to be for author's use only. That is, the module user should not be concerned with running those. Only the author would find running them useful. You may have no author tests at all.

There are many approaches and opinions about Testing. Perhaps you will find this useful I am most likely to install a new module from CPAN if:.

Use git (github or your own server) to host your code for collaboration and as a version control system, i.e. to register incrementally your changes to your code so that you can rollback at any time.

Disclaimer: please note that my knowledge of the above is at most average and seriously lacking commercial experience. It has been gained from doing my own projects, without peer-review from colleagues or supervisors as others here working for companies do every day. I am saying this not because of you doing something wrong on my advice (@&%^% that) but because there are battle-hardened veteran monks who are real experts and i think you should ask them too, or they should intervene if i am dispensing wrong or rubbish advice.

bw, bliako