view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        # @depends.modules+ 'Another::Yet'
        #
        # @author.name:     'Mitchell Cooper'
        # @author.website:  'https://github.com/cooper'
        #
        package M::My::Module;
        
        use warnings;
        use strict;
        use 5.010;
        
        # Auto-exported variables
        our ($api, $mod);
        
        # Default initializer
        sub init {
            say 'Loading ', $mod->name;
            
            # indicates load success
            return 1;
        }
        
        # Default deinitializer
        sub void {
            say 'Bye!';
            
            # indicates unload success
            return 1;
        }
        
        # Package must return module object
        $mod;

DESCRIPTION

    Perl provides a simple way to load dependencies. But what about
    upgrading or unloading? API Engine makes it easy to create an
    excessively versatile Perl application capable of adapting dynamically
    with the user's ever-changing needs.

 Module management

    Modules are Perl packages which can be easily loaded, unloaded, and
    reloaded. API Engine automatically tracks the changes made by each
    module and reverts them upon unload, leaving no trace. With API Engine
    used properly, it is even possible to reload your entire program
    without restarting it.

    Modules themselves can determine the necessity of additional code which
    may be dynamically added and removed through the use of submodules.

 Dependency resolution

    API Engine automatically resolves dependencies of both modules and
    normal Perl packages. It loads and unloads dependencies in the proper
    order. It is also possible to specify that a submodule is automatically
    loaded and unloaded in conjunction with some top-level module.

 Event management

    API Engine is Evented in that it tracks all Evented::Object callbacks
    attached from within modules and automatically removes them upon
    unloading. This allows you to employ events excessively without
    constantly worrying about their eventual disposal.

METHODS

 Evented::API::Engine->new(%opts)

    Creates a new instance of the Evented API Engine. This single object
    will be used throughout the life of the application.

        my $api = Evented::API::Engine->new(
            mod_inc  => [ 'mod', '/usr/share/something/mod' ],
            features => [ qw(io-async something-else)       ],
            modules  => [ $conf->keys_for_block('modules')  ]
        );

    Parameters

      * %opts - optional, constructor options.

    %opts - API Engine options

      * \@mod_inc - list of module search directories

      * \@features - optional, list of feature names to enable immediately

      * \@modules - optional, list of names of toplevel modules to load
      immediately

      * \&log_sub - optional, code to be called for API Engine log messages

      * $developer - optional, if true, module info will be written to JSON
      metadata files. your program should include a developer mode option
      which in turn enables this.

    Returns API Engine.

 $api->load_modules(@mod_names)

    Loads one or more modules at once.

    This is preferred over calling ->load_module() several times in a row
    because it skips common dependencies which have already been attempted.

    Parameters

      * @mod_names - list of module names to load

    Returns

    Module objects for those which loaded successfully.

 $api->load_module($mod_name, $dirs)

    Loads a toplevel module.

    Parameters

      * $mod_name - name of the module to load.