/ 
Devel-GlobalSub-0.02
River stage zero No dependents
/ Devel::GlobalSub

NAME

Devel::GlobalSub - Automagically import a subroutine into all namespaces

VERSION

Version 0.02

SYNOPSIS

*** WARNING ***

This module will allow you to import one or more subroutines into all namespaces automatically.

Please note: This is generally A REALLY BAD IDEA. You should never use this module in production environments. If you need your project to import subroutines into some namespaces, do it the normal way: using Exporter or some other controlled method.

This module should be useful only for development purposes. For example, when you temporarily want a certain subroutine to be available anywhere in a project for debugging purposes.

Using this module for purposes other than development/debugging is a terrible idea. You've been warned.

You can use this module

To ensure this module to properly work, loading it should be the very first thing your code does. Ideally, you shouldn't even use the module in your code, but in your call to Perl (see bellow). If this module is called late, it might not be able to discover all known namespaces and consequently not be able to import your desired subroutines.

First, you want to write a module of your own, where you can define which subroutines will be globally available. Example:

# File: MyGlobalSubs.pm

# Very first thing in your code:
use Devel::GlobalSub qw(global_sub_1 global_sub_2);

sub global_sub_1 {
	print "I'm global_sub_1 being called!\n";
}

sub global_sub_2 {
	print "I'm global_sub_2 being called!\n";
}

1;

Later, the ideal point in time to inject your global functions, is in the call to Perl. Example:

joe@devbox:~$ perl -MMyGlobalSubs some_script.pl

If you need to tell perl where your module is, you can also do this, assuming you have your module at /home/joe/my_perl_libs/MyGlobalSubs.pm:

joe@devbox:~$ perl -I/home/joe/my_perl_libs -MMyGlobalSubs some_script.pl

If that's is not possible for you for any reason, then you can simply call your module in your script. But, it should be the first thing that gets loaded in your code, so it should be also be called in the main script being executed. Example:

#!/usr/bin/perl
# File: some_script.pl

use MyGlobalSubs; # <- Very first thing in your code
use strict;
use warnings;

# ... the rest of your code

EXPORT

None.

SUBROUTINES/METHODS

Devel::GlobalSub->import(@list_of_sub_names)

You shouldn't ever need to call import. This module works only if it is called at compile time. By simply useing it, the import method is automatically invoked, like with any other module. That is:

use Devel::GlobalSub qw(your_global_sub1 your_global_sub_2 your_global_sub_3 etc);

It needs to receive the names of the subroutines you want to export everywhere. For exmaple:

	# File: MyGlobalSubs.pm

    use Devel::GlobalSub qw(global_sub_1 global_sub_2); # Just the names, not references
	use strict;
	use warnings;
	
	# Define the subs you are exporting:
	
	sub global_sub_1 {
		print "I'm global_sub_1 being called!\n";
	}
	
	sub global_sub_2 {
		print "I'm global_sub_2 being called!\n";
	}
	
	1;

If you call this module after having called other modules, you might not see your functions exported everywhere, or at all.

AUTHOR

Francisco Zarabozo, <zarabozo at cpan.org>

BACKGROUND/WHY

As noted at the beginning: This is generally a really bad idea and it shouldn't be ever used as a permanent solution. So, why did I write it?

I work on big projects at my everyday job. Many under platforms like Catalyst or Mojolicious. Some times, I need to do some custom debugging in them and I use some personal debugging modules/functions for that. For example, to send deugging information/messages to a custom file I'm following through `tail -f` in a separate console, away from the rest of the system logging, making it really easy to read for me.

I found myself constantly wanting to use my custom tools, and having to edit each file in the project where I wanted to run them, having to use my custom module on each one, or having to call my subs with fully qualified names.

I wanted something cleaner, quick to type, that didn't need me to add unnecessary, some times dangerous lines to the files. I resolved it with this module. I include it in my call to Perl as:

perl -I/home/me/perllibs -MMyDebuggingModule some_project_startup_script.pl -D

And with that, I can suddenly put a line in the middle of any file in the project like this:

# Some code...
my_debug('Hi there, here are some objects:', $request, $stash, $schema);
# Some more code

After my work is complete, it's a lot easier to search for the lines I need to delete this way. Also, there's no possible way this will run in another machine, as it is not defined anywhere for real.

BUGS

Please report any bugs or feature requests to bug-devel-globalsub at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Devel-GlobalSub. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Devel::GlobalSub

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is copyright (c) 2021 by Francisco Zarabozo.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.