NAME

Test::ModuleReady - Simple module for checking that a module is ready for submission.

VERSION

This document describes Test::ModuleReady version 0.0.6

SYNOPSIS

First create a standard perl script that uses the module e.g. ~/module-check.pl

    #!/usr/bin/perl -w
 
    # use the module.
    use Test::ModuleReady;

    # Call the single exported subroutine.
    &module_ready; 

Enter the root directory of your module containing the MANIFEST, README, t/, lib/ etc. then run the perl scripts from this directory e.g. perl ~/module-check.pl. The module will then perform each check in succession printing the result to STDOUT and wait for your to enter carriage-return before proceeding to the next. Thus the initial output will be something like:

    ------------------------------------------------------------
    CHECKING MODULE VERSION NUMBERS

    [*] Found module lib/Statistics/MVA/BayesianLinearDiscrimination.pm
    [*] Version number from README is 0.0.3 
    [*] Version number from module POD is 0.0.1 
    [*] Version number from module $VERSION variable is 0.0.2 

    [*] Version numbers in $VERSION variable, POD and README do not match

    Press carriage return to detect missing and excess files and 'n' carriage return to exit? 
    

Enter carriage-return to proceed.

    ------------------------------------------------------------
    CHECKING FOR EXCESS AND MISSING FILES

    [1] There is a excess file:    './i-exist-but-am-not-mentioned-in-manifest'

    Do you wish to delete the file (d), append (a) it to the MANIFEST or ignore it (i) or exit (q)? a

    Are you sure you wish to append file ./i-exist-but-am-not-mentioned-in-manifest to MANIFEST? y

    Appending file i-exist-but-am-not-mentioned-in-manifest to MANIFEST

    [2] There is a missing file:    './i-do-not-exist'

    Press carriage return to perform dependency check on Makefile.PL and Build.PL and 'n' carriage return to exit?

Just continue...

DESCRIPTION

This module was written to help me prepare updates to modules. I have a nasty habit of over-looking tedious things like checking that the version numbers in the README, POD and $VERSION variable in the module file are all equal. Also not only checking that all the files listed in the MANIFEST but more importantly checking that I haven´t left old .svn repositories, .Rhistory files Vim .swp files etc. have all been deleted. This modules is aimed at addressing these and other house-keeping chores just before submitting a new module release (of course you can just use perl Build.PL; ./Build dist to avoid some of these issues).

    This module:

    (1) Pulls the version numbers from the README, Module POD and Module $VERSION variable and checks they are all equal.
    (2) Reads in the MANIFEST contents and checks that there are missing or extra files in the directory - see Below.
        For missing files it just prints the problem and continues. However, for excess files or directories it asks
        whether you want to ignore it, append it automatically to the MANIFEST file or delete it.
    (3) Scans the Module.pm file for use statements and then cross-references these against the dependencies arguments
        in Makefile.PL and Build.PL making sure you do not forget to include important dependencies. Specifically, for
        every 'use' statement found it prints whether or not it found the appropriate dependency in the PREREQ_PM or
        requires hashes for Makefile.PL and Build.PL respectively.
    (4) Extracts POD sections and checks the length of verbatim sections to make sure they do not have excessing length.
    (5) Runs POD syntax checking using the Pod::Checker module.
    (6) Prompts you for words to ignore before running spell-check using Test::Spelling/Test::More modules.
    (7) Checks the Module.pm syntax using the basic Perl interpreter syntax check.
    (8) Runs: perl Build.pl; ./Build disttest to use Builds much superior testing facilities and generate the META.yml.
    (9) If your happy with the results it runs: ./Build dist to generate the tar file.

This module does not recurse into the working directory and consequently if you choose to keep an excess directory it will totally ignore everything below. Instead the module takes the MANIFEST file contents and generates a hash of directories as keys and anonymous arrays containing the directory contents as values. It then enters each of those directories and checks the supposed contents against their actual contents thereby detecting missing and excess files/dirs. For example the MANIFEST file:

    Build.PL
    Changes
    MANIFEST
    Makefile.PL
    README
    lib/Statistics/MVA/BayesianLinearDiscrimination.pm
    t/00.load.t
    t/pod.t

Generates a hash of dirs to contents as (output generated using Data::TreeDraw.

    HASH REFERENCE (0)
    |  
    |__'lib/'=>ARRAY REFERENCE (1) [ '->{lib/}' ]
    |    |  
    |    |__SCALAR = 'Statistics' (2)  [ '->{lib/}[0]' ]
    |  
    |__'lib/Statistics/'=>ARRAY REFERENCE (1) [ '->{lib/Statistics/}' ]
    |    |  
    |    |__SCALAR = 'MVA' (2)  [ '->{lib/Statistics/}[0]' ]
    |  
    |__'./'=>ARRAY REFERENCE (1) [ '->{./}' ]
    |    |  
    |    |__SCALAR = 'MANIFEST' (2)  [ '->{./}[0]' ]
    |    |  
    |    |__SCALAR = 'lib' (2)  [ '->{./}[1]' ]
    |    |  
    |    |__SCALAR = 'Changes' (2)  [ '->{./}[2]' ]
    |    |  
    |    |__SCALAR = 'Build.PL' (2)  [ '->{./}[3]' ]
    |    |  
    |    |__SCALAR = 'Makefile.PL' (2)  [ '->{./}[4]' ]
    |    |  
    |    |__SCALAR = 'README' (2)  [ '->{./}[5]' ]
    |    |  
    |    |__SCALAR = 't' (2)  [ '->{./}[6]' ]
    |  
    |__'lib/Statistics/MVA/'=>ARRAY REFERENCE (1) [ '->{lib/Statistics/MVA/}' ]
    |    |  
    |    |__SCALAR = 'BayesianLinearDiscrimination.pm' (2)  [ '->{lib/Statistics/MVA/}[0]' ]
    |  
    |__'t/'=>ARRAY REFERENCE (1) [ '->{t/}' ]
         |  
         |__SCALAR = '00.load.t' (2)  [ '->{t/}[0]' ]
         |  
         |__SCALAR = 'pod.t' (2)  [ '->{t/}[1]' ]

DEPENDENCIES 'Carp' => '1.08', 'Pod::Checker' => '1.45', 'Test::More' => '0.94', 'Test::Spelling' => '0.11',

BUGS

Let me know.

TO DO

Have a options to skip steps. Use a more powerful tar mechanism. Extract POD using proper module tools and not regexps.

AUTHOR

Daniel S. T. Hughes <dsth@cantab.net>

LICENCE AND COPYRIGHT

Copyright (c) 2010, Daniel S. T. Hughes <dsth@cantab.net>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

Because this software is licensed free of charge, there is no warranty for the software, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the software "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair, or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the software as permitted by the above licence, be liable to you for damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if such holder or other party has been advised of the possibility of such damages.

cpanm Test::ModuleReady

perl -MCPAN -e shell
install Test::ModuleReady