NAME

Acme::Crux - The CTK::App of the next generation

SYNOPSIS

use Acme::Crux;

DESCRIPTION

The CTK::App of the next generation

new

my $app = Acme::Crux->new(
    project     => 'MyApp',
    moniker     => 'myapp',

    options     => {foo => 'bar'},

    plugins     => { foo => 'MyApp::Foo', bar => 'MyApp::Bar' },
    preload     => 'Config, Log',

    cachedir    => '/var/cache/myapp',
    configfile  => '/etc/myapp/myapp.conf',
    datadir     => '/var/lib/myapp',
    docdir      => '/usr/share/doc/myapp',
    lockdir     => '/var/lock/myapp',
    logdir      => '/var/log/myapp',
    logfile     => '/var/log/myapp/myapp.log',
    pidfile     => '/var/run/myapp/myapp.pid',
    root        => '/etc/myapp',
    rundir      => '/var/run/myapp',
    sharedir    => '/usr/share/myapp',
    spooldir    => '/var/spool/myapp',
    tempdir     => '/tmp/myapp',
    webdir      => '/var/www/myapp',

    debug       => 0,
    test        => 0,
    verbose     => 0,
);

ATTRIBUTES

This class implements the following attributes

cachedir

cachedir => '/var/cache/myapp'

Cache dir for project cache files

$app = $app->cachedir( "/path/to/cache/dir" );
my $cachedir = $app->cachedir;

Default: /var/cache/<MONIKER>

configfile

configfile => '/etc/myapp/myapp.conf'

Path to the configuration file of your project

$app = $app->configfile( "/path/to/config/file.conf" );
my $configfile = $app->configfile;

Default: /etc/<MONIKER>/<MONIKER>.conf

datadir

datadir => '/var/lib/myapp'

Data dir of project

$app = $app->datadir( "/path/to/data/dir" );
my $datadir = $app->datadir;

Default: /var/lib/<MONIKER>

debug

debug => 1
debug => 'on'
debug => 'yes'

Debug mode

Default: 0

docdir

docdir => '/usr/share/doc/myapp'

Doc dir for project documentation

$app = $app->docdir( "/path/to/docs/dir" );
my $docdir = $app->docdir;

Default: /usr/share/doc/<MONIKER>

lockdir

lockdir => '/var/lock/myapp'

Lock dir for project lock files

$app = $app->lockdir( "/path/to/lock/dir" );
my $lockdir = $app->lockdir;

Default: /var/lock/<MONIKER>

logdir

logdir => '/var/log/myapp'

Log dir for project logging

$app = $app->logdir( "/path/to/log/dir" );
my $logdir = $app->logdir;

Default: /var/log/<MONIKER>

logfile

logfile => '/var/log/myapp/myapp.log'

Path to the log file

$app = $app->logfile( "/path/to/file.log" );
my $logfile = $app->logfile;

Default: /var/log/<MONIKER>/<MONIKER>.log

moniker

moniker => 'myapp'

This attribute sets moniker of project name.

Moniker SHOULD contains only symbols: a-z, 0-9, '_', '-', '.'

$app = $app->moniker( 'myapp' );
my $moniker = $app->moniker;

Default: decamelized version of the project attribute

options

options => {foo => 'bar'}

Command-line options, or any hash-ref structure with options. See Getopt::Long

$app = $app->options({ foo => 'bar' });
my $options = $app->options;

Default: {}

pidfile

pidfile => '/var/run/myapp/myapp.pid'

Path to the pid file

$app = $app->pidfile( "/path/to/file.pid" );
my $pidfile = $app->pidfile;

Default: /var/run/<MONIKER>/<MONIKER>.pid

preload, preload_plugins

preload => [qw/foo bar baz/]
preload => "foo bar baz"
preload => "foo, bar, baz"
preload => "foo; bar; baz"

This attribute sets list of preloading plugins. Each specified plugin will be loaded and registered during application creation automatically

Default preloading plugins: Config, Log

plugins

plugins => { foo => 'MyApp::Foo', bar => 'MyApp::Bar' }

This attribute defines specified plugins only. NOTE! This attribute NOT performs automatic loading and register specified plugins!

See the "plugin" method below if you want to load and register a plugin

$app = $app->plugins(
    foo => 'MyApp::Foo',
    bar => 'MyApp::Bar',
);
my $plugins = $app->plugins;

Default plugins:

Config  Acme::Crux::Plugin::Config
Log     Acme::Crux::Plugin::Log

project

project => 'MyApp'

Name of project

$app = $app->project( 'MyApp' );
my $project = $app->project;

Default: script name (without file extension) or invocant class

root

root => '/etc/myapp'

Root dir of project

$app = $app->root( "/etc/myapp" );
my $root = $app->root;

Default: /etc/<MONIKER>

rundir

rundir => '/var/run/myapp'

Run dir for project pid files

$app = $app->rundir( "/path/to/run/dir" );
my $rundir = $app->rundir;

Default: /var/run/<MONIKER>

sharedir

sharedir => '/usr/share/myapp'

Share dir for project

$app = $app->sharedir( "/path/to/share/dir" );
my $sharedir = $app->sharedir;

Default: /usr/share/<MONIKER>

spooldir

spooldir => '/var/spool/myapp'

Spool is the dir for project pool data

$app = $app->spooldir( "/path/to/spool/dir" );
my $spooldir = $app->spooldir;

Default: /var/spool/<MONIKER>

tempdir

tempdir => '/tmp/myapp'

Temp dir for project temporary files

$app = $app->tempdir( "/path/to/temp/dir" );
my $tempdir = $app->tempdir;

Default: /tmp/<MONIKER>

test

test => 1
test => 'on'
test => 'yes'

Test mode

Default: 0

verbose

verbose => 1
verbose => 'on'
verbose => 'yes'

Verbose mode

Default: 0

webdir

webdir => '/var/www/myapp'

Web dir for project web files (DocumentRoot)

$app = $app->webdir( "/path/to/webdoc/dir" );
my $webdirr = $app->webdir;

Default: /var/www/<MONIKER>

METHODS

This class implements the following methods

startup

This is your main hook into the application, it will be called at application startup. Meant to be overloaded in a subclass.

This method is called immediately after creating the instance and returns it

NOTE: Please use only in your subclasses!

sub startup {
    my $self = shift;

    . . .

    return $self; # REQUIRED!
}

debugmode

$app->debugmode;

Returns debug flag. 1 - on, 0 - off

begin

my $timing_begin = $app->begin;

This method sets timestamp for "elapsed"

my $timing_begin = $app->begin;
# ... long operations ...
my $elapsed = $app->elapsed( $timing_begin );

elapsed

my $elapsed = $app->elapsed;

my $timing_begin = [gettimeofday];
# ... long operations ...
my $elapsed = $app->elapsed( $timing_begin );

Return fractional amount of time in seconds since unnamed timstamp has been created while start application

my $elapsed = $app->elapsed;
$app->log->debug("Database stuff took $elapsed seconds");

For formatted output:

$app->log->debug(sprintf("%+.*f sec", 4, $app->elapsed));

error

my $error = $app->error;

Returns error string if occurred any errors while working with application

$app = $app->error( "error text" );

Sets new error message and returns object

exedir

my $exedir = $app->exedir;

Gets exedir value

handlers

my @names = $app->handlers;

Returns list of names of registered handlers

my @names_and_aliases = $app->handlers(1);

Returns list of aliases and names of registered handlers

lookup_handler

my $handler = $app->lookup_handler($name)
    or die "Handler not found";

Lookup handler by name or aliase. Returns handler or undef while error

option, opt, getopt

my $value = $app->option("key");

Returns option value by key

my $options = $app->option;

Returns hash-ref structure to all options

See "options"

orig

my $origin_args = $app->orig;

Returns hash-ref structure to all origin arguments

plugin

$app->plugin(foo => 'MyApp::Plugin::Foo');
$app->plugin(foo);
$app->plugin(foo => 'MyApp::Plugin::Foo', {bar => 123, baz => 'test'});
$app->plugin(foo => 'MyApp::Plugin::Foo', bar => 123, baz => 'test');
$app->plugin(foo, undef, {bar => 123, baz => 'test'});

Load a plugin by name or pair - name and class

pwd

my $pwd = $app->pwd;

This method returns current/working directory

register_handler

use parent qw/Acme::Crux/;

__PACKAGE__->register_handler(
    handler     => "foo",
    aliases     => "one, two",
    description => "Foo handler",
    params => {
        param1 => "test",
        param2 => 123,
    },
    code => sub {
### CODE:
    my $self = shift; # App
    my $meta = shift; # Meta data
    my @args = @_; # Arguments

    print Acrux::Util::dumper({
        meta => $meta,
        args => \@args,
    });

    return 1;
});

Method for register new handler

Example output while running:

$app->run('one', abc => 123, def => 456); # returns 1

{
  "args" => ["abc", 123, "def", 456],
  "meta" => {
    "aliases" => ["one", "two"],
    "description" => "Foo handler",
    "name" => "foo",
    "params" => {
        "param1" => "test",
        "param2" => 123
    }
  },
  "name" => "foo"
}

This method supports the following options:

aliases, alias

aliases => 'foo bar baz'
aliases => 'foo, bar, baz'
aliases => [qw/foo bar baz/]
alias => 'foo'

Sets aliases list for handler lookup

code

code => sub {
    my ($self, $meta, @args) = @_;
    # . . .
}

Sets code oh handler

description

description => 'Short description, abstract or synopsis'

handler, name

handler => 'version'
name => 'version'

Sets handler name. Default to 'default'

params, parameters

params => { foo => 'bar' }

List of handler parameters. All handler parameters will passed to $meta

register_method

$app->register_method($namespace, $method, sub { 1 });
$app->register_method($method => sub { 1 });
__PACKAGE__->register_method($namespace, $method, sub { 1 });

This method performs register the new method in your namespace

By default use current application namespace

register_plugin

$app->register_plugin('foo', 'MyApp::Plugin::Foo');
$app->register_plugin('foo', 'MyApp::Plugin::Foo', {bar => 123});
$app->register_plugin('foo', 'MyApp::Plugin::Foo', bar => 123);

Load a plugin and run register method, optional arguments are passed through

run

By default this method is alias for "run_handler" method.

This method meant to be overloaded in a subclass

run_handler

my $result = $app->run_handler("foo",
    foo => "one",
    bar => 1
) or die $app->error;

Runs handler by name and returns result of it handler running

silentmode

$app->silentmode;

Returns the verbose flag in the opposite value. 0 - verbose, 1 - silent.

See "verbosemode"

testmode

$app->testmode;

Returns test flag. 1 - on, 0 - off

verbosemode

$app->verbosemode;

Returns verbose flag. 1 - on, 0 - off

See "silentmode"

PLUGINS

The following plugins are included in the Acrux distribution

Acme::Crux::Plugin::Config

Config => Acme::Crux::Plugin::Config

Acrux::Config configuration plugin

Acme::Crux::Plugin::Log

Log => Acme::Crux::Plugin::Log

Acrux::Log logging plugin

TO DO

See TODO file

AUTHOR

Serż Minus (Sergey Lepenkov) https://www.serzik.com <abalama@cpan.org>

COPYRIGHT

LICENSE

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

See LICENSE file and https://dev.perl.org/licenses/

To install Acrux, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Acrux

CPAN shell

perl -MCPAN -e shell
install Acrux

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

new

ATTRIBUTES

cachedir

configfile

datadir

debug

docdir

lockdir

logdir

logfile

moniker

options

pidfile

preload, preload_plugins

plugins

project

root

rundir

sharedir

spooldir

tempdir

test

verbose

webdir

METHODS

startup

debugmode

begin

elapsed

error

exedir

handlers

lookup_handler

option, opt, getopt

orig

plugin

pwd

register_handler

register_method

register_plugin

run

run_handler

silentmode

testmode

verbosemode

PLUGINS

TO DO

SEE ALSO

AUTHOR

COPYRIGHT

LICENSE

Module Install Instructions