expose print_usage_text() as public method

diff --git a/Changes b/Changes
index 62ab73e..92df66d 100644 (file)
--- a/Changes
+++ b/Changes
@@ -3,6 +3,8 @@ Revision history for Perl extension MooseX-Getopt
 {{$NEXT}}
  - documentation and tests amended to prefer usage of 'trait' over 'metaclass'
    as much as possible
+ - print_usage_text() exposed as a public method, to make it easier for
+   consuming classes to modify the behaviour when usage text is printed
 
 0.47      2012-08-30 16:37:59 PDT-0700
  - re-release to remove double $VERSION declarations

diff --git a/lib/MooseX/Getopt.pm b/lib/MooseX/Getopt.pm
index 6ad6e1c..364e507 100644 (file)
--- a/lib/MooseX/Getopt.pm
+++ b/lib/MooseX/Getopt.pm
@@ -236,6 +236,14 @@ L<Getopt::Long::Descriptive> is used).
 This accessor contains the boolean state of the --help, --usage and --?
 options (true if any of these options were passed on the command line).
 
+=method B<print_usage_text>
+
+This method is called internally when the C<help_flag> state is true.
+It prints the text from the C<usage> object (see above) to stdout and then the
+program terminates normally.  You can apply a method modification (see
+L<Moose::Manual::MethodModifiers>) if different behaviour is desired, for
+example to include additional text.
+
 =method B<meta>
 
 This returns the role meta object.

diff --git a/lib/MooseX/Getopt/Basic.pm b/lib/MooseX/Getopt/Basic.pm
index 0f8a7c5..f0b06bc 100644 (file)
--- a/lib/MooseX/Getopt/Basic.pm
+++ b/lib/MooseX/Getopt/Basic.pm
@@ -73,7 +73,7 @@ sub process_argv {
 
     # did the user request usage information?
     if ( $processed{usage} and $params->{help_flag} ) {
-        $class->_getopt_full_usage($processed{usage});
+        $class->print_usage_text($processed{usage});
     }
 
     return MooseX::Getopt::ProcessedArgv->new(
@@ -152,11 +152,17 @@ sub _getopt_spec_exception {
     die @$warnings, $exception;
 }
 
-sub _getopt_full_usage {
+#(this is already documented in MooseX::Getopt. But FIXME later, via RT#82195)
+=for Pod::Coverage
+    print_usage_text
+=cut
+sub print_usage_text {
     my ($self, $usage) = @_;
     print $usage->text;
     exit 0;
 }
+# maintained for backwards compatibility only
+sub _getopt_full_usage { shift->print_usage_text(@_) }
 
 sub _usage_format {
     return "usage: %c %o";

diff --git a/t/104_override_usage.t b/t/104_override_usage.t
index 9820614..517d8aa 100644 (file)
--- a/t/104_override_usage.t
+++ b/t/104_override_usage.t
@@ -1,7 +1,7 @@
 use strict;
 use warnings;
 
-use Test::More tests => 5;
+use Test::More tests => 6;
 use Test::Trap;
 use Test::NoWarnings 1.04 ':early';
 
@@ -40,3 +40,19 @@ USAGE
     is($trap->die, join("\n", 'Unknown option: q', $usage), 'usage is printed on unknown option');
 }
 
+{
+    Class::MOP::class_of('MyScript')->add_before_method_modifier(
+        print_usage_text => sub {
+            print "--- DOCUMENTATION ---\n";
+        },
+    );
+
+    local @ARGV = ('--help');
+    trap { MyScript->new_with_options };
+    is(
+        $trap->stdout,
+        join("\n", '--- DOCUMENTATION ---', $usage),
+        'additional text included before normal usage string',
+    );
+}
+

diff --git a/t/107_no_auto_help.t b/t/107_no_auto_help.t
index e3b2132..e2064c7 100644 (file)
--- a/t/107_no_auto_help.t
+++ b/t/107_no_auto_help.t
@@ -49,7 +49,7 @@ use Test::Fatal 0.003;
 END {
     ok(!$fail_on_exit, 'getoptions() lives');
 
-    # cancel the non-zero exit status from _getopt_full_usage()
+    # cancel the non-zero exit status from print_usage_text()
     exit 0;
 }