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

_new_instance (create the instance of App::Modular which will be returned by instance())

DESTROY (cleanup on exit/unload of App::Modular)

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

cpanm App::Modular

perl -MCPAN -e shell
install App::Modular