NAME
App::Modular - modularization framework for perl programs
SYNOPSIS
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;
DESCRIPTION
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)
USAGE
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.
A sample Module
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.
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.
Main Program
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?');
Interdependant Modules
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.
REFERENCE
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.
- instance (void)
-
Returns the one and only instance of App::Modular (inherited from Class::Singleton).
- loglevel (int level)
-
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
- logtrace (optional bool logtrace)
-
print stack backtrace on debug output? (returns setting, and sets the value if the optional argument is given)
Return value: (bool) value of logtrace
- mlog (int level, string text)
-
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
- module_autoload
-
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
- module_deregister (string module_name_
-
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)
- module_directory (string path)
-
Get/set the directory that contains the App::Modular modules.
Return value: (string) current setting
- module_extension (string filespec)
-
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
- module_isloaded (string module_name)
-
Is the module named module_name loaded in the system?
Return value: (bool) true if loaded
- module_register (string module_name | module_path)
-
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
- modules ([string regexp_pattern])
-
Returns an array containing the names of all loaded modules. If a pattern is given, only the names mathing it are returned.
- modules_deregister_all (void)
-
Will unload all modules. (Or to be exact, will call module_deregister for every single loaded module).
- modules_list (string regexp_pattern)
-
Print a list of all modules matching pattern (if given) or just all loaded modules (if no pattern was given) to the log.
Return value: (void)
- modules_register_all ( [bool recurs, string module_dir, string module_ext ]);
-
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
- Internal-only use methods
Log levels
The modulariyer code usees the following log levels: (in general they are all between 0 and 100)
- -1 ABSOLUTELY VITAL messages that should never be switched off
- 0 FATAL ERRROR
- 1 ERRORS
- 2 WARNINGS
- 10 information
- 20 notices (more or less unimportant info)
- 80 normal debugging info (external debugging info)
- 99 absolute debug information (system internals)
BUGS
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.
AUTOR
(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.
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.
SEE ALSO
App::Modular::Module(3pm), App::Modular::Module::Events(3pm)
Similar Modules: Module::Pluggable, Object::Meta::Plugin, OpenPlugin, Template:::Plugin