App::Modular - modularization framework for perl programs
package App::Modular::Module::Test; use base qw(App::Modular::Module); sub say_hello { print "Hello, dear user!"; }; package main; use App::Modular; my $modul = instance App::Modular; $modul->module('Test')->say_hello(); exit;
App::Modular aims to provide a framework which should it make very easy to programmes to create any kind of modular program.
It supports:
module dependency solving
autoloading of modules
event handling (implemented as a contributed App::Modular module)
The usage description is split into two parts, one describing what the main program has to do in order to work with App::Modular, one describing how to create a module. The explanation is based on an example; I suggest you to try to build a little modular script yourself and you'll soon understand how App::Modular works. First, we will create a little module that we'll use in the main program to greet the user.
Modules come in the form of perl modules; however, they are not expected to be in one of the inlcude (@INC) directories, but rather in a specific directory like "/usr/local/lib/app-modular/sample". Their extension does not default to ".pm" but to ".mom" (App::Modular Module).
Every module should have App::Modular::Module as a base class, as it inherits some basic methods then automatically. As a package namespace, you MUST use App::Modular::Module::*, as App::Modular converts the package/file name in a way that would brake otherwise.
App::Modular::Module
App::Modular::Module::*
But now, that's enough talking - let's proceed to some real code:
#!/usr/bin/perl -w # File: Printer.mom use strict; package App::Modular::Module::Printer; use base qw(App::Modular::Module); sub printer { shift; App::Modular->instance()->mlog(99, "printer printing!"); print(join ' ', @_); }; 1;
As you will have noticed, the module only provides one method - a method to print a string or an array to stdout. That's not really much. Anyway, it's enough for our first test: we can see some action.
Now we just need some work for our little bet... Here it comes:
#!/usr/bin/perl -w # File: AppModularSample.pl use strict; package main; use App::Modular 0.001_001; my $mod = instance App::Modular; $mod -> module_directory ('.'); $mod -> module_extension ('.mom'); $mod -> module('Printer') -> printer ('Hello,' 'world!', 'How are you?');
Now that we know how to write a simple module, we can advance to some more complicated.
!!!FIXME!!! Here should be an example using module dependencies.
Meanwhile, see the fererence for App::Modular::Modul->depends() and the bugs section of this document.
In this man page, you will only find the method descriptions fror hte App::Modular object; the standard functions of the application modules can be found in App::Modular::Module.
Returns the one and only instance of App::Modular (inherited from Class::Singleton).
Set the logging level (if the number given here is >= the value given to the logging function mlog, the message will be logged.
Return value: (int) current log level
print stack backtrace on debug output? (returns setting, and sets the value if the optional argument is given)
Return value: (bool) value of logtrace
Do some logging (if the given leven is <= the maximum logging level set before)
Note: Depending on the setting of logtrace the messages will either contain a function stack backtrace or not.
Return value: void
Set/Get status of autoloading (true => modules will be loaded automatically when needed; false => no module will ever be loaded without the explicit command).
Return value: (bool) current setting of autoload
Unload a App::Modular module. (Internally, this function will delete the reference to the module, hence perl's garbage collector will destroy the object)
Return value: (void)
Get/set the directory that contains the App::Modular modules.
Return value: (string) current setting
Get/set the extension that is common to all App::Modular modules (e.g. if the module is named Printer and the file is saved as Printer.mom, the extension is '.mom').
Return value: (string) current value
Is the module named module_name loaded in the system?
Return value: (bool) true if loaded
Load the module named module_name or from the file named module_path.
Return value: undef on failure; reference to the module object on success
Returns an array containing the names of all loaded modules. If a pattern is given, only the names mathing it are returned.
Will unload all modules. (Or to be exact, will call module_deregister for every single loaded module).
Print a list of all modules matching pattern (if given) or just all loaded modules (if no pattern was given) to the log.
Register all modules in module_dir with extension module_ext (the standards are used for these two variables if nothing is given here). If recurs it true, it will recursively walk trough all subdirs, with the effect of loading modules in a nested namespace, too (e.g. Input::Reader, found at $module_dir/Input/Reader$module_ext). Note: module_dir and module_ext will only be valid during this procedure; they will NOT be set as defaults!
Return value: (array of strings) names of all modules loaded
The modulariyer code usees the following log levels: (in general they are all between 0 and 100)
Documentation
Documentation should be much better, user-friendly and elaborate.
Testing
This set of modules is tested in a quite limited fashion; I use it in production code, however at the moment of this writing no one else tested it. If you have any reports, positive or negative, I would be pleased to hear about your experiences.
Logging
The logging mechanism is quite ugly; however, I do not have any idea how a better one could look like - if you have ideas, please contact me.
Dependency handling not 100% accurate
The pre-requisites of a module are only loaded after the module has been loaded and initialized. This results in the module being unable to call functions of its pre-requisites during initialization.
(c) 2003-2005 Baltasar Cevc (baltasar A.T. cevc-topp .D.O.T. de)
Permission to use this software is granted under the terms of the perlartistic Perl Artistic License, which can should be accessible via the perldoc perlartistic command and the file COPYING provided with this package.
perldoc perlartistic
DISCLAIMER: THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. IF YOU USE THIS SOFTWARE, YOU DO SO AT YOUR OWN RISK.
App::Modular::Module(3pm), App::Modular::Module::Events(3pm)
Similar Modules: Module::Pluggable, Object::Meta::Plugin, OpenPlugin, Template:::Plugin
To install App::Modular, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Modular
CPAN shell
perl -MCPAN -e shell install App::Modular
For more information on module installation, please visit the detailed CPAN module installation guide.