Mascip

lib/Debuggit.pm

@@ -136,7 +136,13 @@ included modules.  See L<Debuggit::Manual/"The DEBUG Constant"> for full details
 
 =head2 Functions exported
 
-Only L</debuggit> is exported.
+The L</debuggit> function is exported. The Alias parameter can be used to provide a shorter alias for calling this function, for example:
+
+    use Debuggit Alias => 'dbg';  # The dbg() function is now an alias to debuggit()
+    # And then:
+    dbg("This message will be printed");
+
+The user is warned that the alias that they choose might conflict with other modules. More warning and advice are given in the L<Debuggit::Manual/"Creating an alias for the debuggit() function"> page.
 
 =cut
 
@@ -182,7 +188,14 @@ sub import
         *{ join('::', $caller_package, 'debuggit') } = sub {};
         *Debuggit::add_func = sub {} unless Debuggit->can('add_func');
     }
-}
+
+    # User-defined Alias for the debuggit() function
+    if ( my $debuggit_alias = $opts{Alias} ) { 
+        *{ join('::', $caller_package, $debuggit_alias) } 
+            = sub { goto &{ join('::', $caller_package, 'debuggit') } } 
+    }
+
+}   # End import()
 
 
 sub _setup_funcs

lib/Debuggit/Manual.pm

@@ -146,6 +146,18 @@ lot of flexibility has been built into it as well.  Read on to see how to adjust
 of C<debuggit>.
 
 
+=head2 Creating an alias for the debuggit function
+
+If you are feeling lazy, you can create an alias for the debuggit function. "debuggit" is not that long to type, but some of us are just very lazy... So here is how to do it:
+
+    use Debuggit Alias => 'dbg';  # The dbg() function is now an alias to debuggit()
+    # And then:
+    dbg("This message will be printed");
+
+The user is warned that the alias that they choose might conflict with other modules. If you call your debugging function "print" or "eval", expect some surpises: this module will not warn you if this happens.
+
+The smaller the alias, the more convenient it is but the more likely it is to create conflicts. That is why the name "debuggit" was chosen as a default. At least one user of this module uses the alias "dbg", because it's shorter. It's up to you.
+
 =head2 The basics
 
 =head4 debuggit([level =>] arg[, ...])

t/alias.t

@@ -0,0 +1,41 @@
+my $DESC = '';
+
+## Without Alias
+use Debuggit;
+
+use strict;
+use warnings;
+use Test::More      0.88                            ;
+use Test::Exception 0.31                            ;
+sub TEST { $DESC = shift }  # Handy test function
+
+TEST "The dbg() function does not exist natively"; {
+    throws_ok { dbg("any message") } qr/Undefined subroutine/, $DESC;
+}
+
+## With an alias
+package WithAlias;
+use Debuggit DEBUG => 1, Alias => 'dbg';
+
+use strict;
+use warnings;
+use Test::More      0.88                            ;
+use Test::Exception 0.31                            ;
+use Test::Output    0.16                            ;
+sub TEST { $DESC = shift }  # Handy test function
+
+TEST "The bad_name() function does not exist natively"; {
+    throws_ok { bad_name("any message") } qr/Undefined subroutine/, $DESC;
+}
+
+TEST "The dbg() function exists, if it was created with the Alias argument"; {
+    lives_ok { dbg("any message") } $DESC;
+}
+
+TEST "Display correct output with dbg() alias (simple use case)"; {
+    my $message = 'expected output';
+    stderr_is { debuggit($message); } "$message\n", $DESC;
+}
+
+done_testing;
+

t/fallthrough.t

@@ -13,19 +13,27 @@ eval {
     use strict;
     use warnings;
 
-    use Debuggit;
+    use Debuggit(Alias => 'dbg');
 
     sub test
     {
         debuggit(2 => $_[0]);
     }
 
+    sub test_with_alias
+    {
+        dbg(2 => $_[0]);
+    }
+
     1;
 };
 
 
 my $output = 'expected output';
-stderr_is { Fallthrough::test($output); } "$output\n", "got fallthrough output";
+stderr_is { Fallthrough::test($output); } "$output\n", 
+    "got fallthrough output";
+stderr_is { Fallthrough::test_with_alias($output); } "$output\n", 
+    "got fallthrough output with_alias";
 
 
 done_testing;

t/override.t

@@ -13,7 +13,7 @@ eval {
     use strict;
     use warnings;
 
-    use Debuggit DEBUG => 2;
+    use Debuggit DEBUG => 2, Alias => 'dbg';
 
     sub print_it
     {
@@ -25,14 +25,21 @@ eval {
         debuggit(2 => $_[0]);
     }
 
+    sub test_with_alias
+    {
+        dbg(2 => $_[0]);
+    }
+
     1;
 };
 
 
 stdout_is { Override::print_it() } 'DEBUG is 2', "DEBUG overrides successfully";
 
 my $output = 'expected output';
-stderr_is { Override::test($output) } "$output\n", "got override output";
-
+stderr_is { Override::test($output) } "$output\n", 
+    "got override output";
+stderr_is { Override::test_with_alias($output) } "$output\n", 
+    "got override output, with Alias";
 
 done_testing;