Venus::Config

Config Class

Config Class for Perl 5

method: from_file method: from_json method: from_json_file method: from_perl method: from_perl_file method: from_yaml method: from_yaml_file method: metadata method: reify method: resolve method: services

package main;

use Venus::Config;

my $config = Venus::Config->new;

# $config = $config->from_file('app.pl');

# my $name = $config->resolve('name');

# "..."

This package provides methods for loading Perl, YAML, and JSON configuration files, fetching configuration information, and building objects with dependency injection.

Venus::Kind::Utility

Venus::Role::Buildable Venus::Role::Valuable

The from_file method load a Perl, YAML, or JSON configuration file, based on the file extension, and returns a new Venus::Config object.

from_file(Str $path) (Config)

{ since => '1.95', }

=example-1 from_file

package main;

use Venus::Config;

my $config = Venus::Config->from_file('t/conf/test.perl');

# bless(..., 'Venus::Config')

The from_json method returns a new Venus::Config object based on the JSON string provided.

from_json(Str $data) (Config)

{ since => '1.95', }

=example-1 from_json

# given: synopsis

package main;

$config = $config->from_json(q(
{
  "$metadata": {
    "tmplog": "/tmp/log"
  },
  "$services": {
    "log": { "package": "Venus/Path", "argument": { "$metadata": "tmplog" } }
  }
}
));

# bless(..., 'Venus::Config')

# my $log = $config->resolve('log');

The from_json_file method uses Venus::Path to return a new Venus::Config object based on the file provided.

from_json_file(Str $file) (Config)

{ since => '1.95', }

=example-1 from_json_file

# given: synopsis

package main;

$config = $config->from_json_file('t/conf/test.json');

# bless(..., 'Venus::Config')

# my $log = $config->resolve('log');

The from_perl method returns a new Venus::Config object based on the Perl string provided.

from_perl(Str $data) (Config)

{ since => '1.95', }

=example-1 from_perl

# given: synopsis

package main;

$config = $config->from_perl(q(
{
  '$metadata' => {
    tmplog => "/tmp/log"
  },
  '$services' => {
    log => { package => "Venus/Path", argument => { '$metadata' => "tmplog" } }
  }
}
));

# bless(..., 'Venus::Config')

# my $log = $config->resolve('log');

The from_perl_file method uses Venus::Path to return a new Venus::Config object based on the file provided.

from_perl_file(Str $file) (Config)

{ since => '1.95', }

=example-1 from_perl_file

# given: synopsis

package main;

$config = $config->from_perl_file('t/conf/test.perl');

# bless(..., 'Venus::Config')

# my $log = $config->resolve('log');

The from_yaml method returns a new Venus::Config object based on the YAML string provided.

from_yaml(Str $data) (Config)

{ since => '1.95', }

=example-1 from_yaml

# given: synopsis

package main;

$config = $config->from_yaml(q(
'$metadata':
  tmplog: /tmp/log
'$services':
  log:
    package: "Venus/Path"
    argument:
      '$metadata': tmplog
));

# bless(..., 'Venus::Config')

# my $log = $config->resolve('log');

The from_yaml_file method uses Venus::Path to return a new Venus::Config object based on the YAML string provided.

from_yaml_file(Str $file) (Config)

{ since => '1.95', }

=example-1 from_yaml_file

# given: synopsis

package main;

$config = $config->from_yaml_file('t/conf/test.yaml');

# bless(..., 'Venus::Config')

# my $log = $config->resolve('log');

The metadata method returns the $metadata section of the configuration data if no name is provided, otherwise returning the specific metadata keyed on the name provided.

metadata(Str $name) (Any)

{ since => '1.95', }

=example-1 metadata

# given: synopsis

package main;

my $metadata = $config->metadata;

# {}

The reify method resolves and returns an object or value based on the service name provided.

reify(Str $name) (Any)

{ since => '1.95', }

=example-1 reify

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$metadata' => {
    tmplog => "/tmp/log"
  },
  '$services' => {
    log => {
      package => "Venus/Path",
      argument => {
        '$metadata' => "tmplog"
      }
    }
  }
});

my $reify = $config->reify('tmp');

# undef

The resolve method resolves and returns an object or value based on the configuration key or service name provided.

resolve(Str $name) (Any)

{ since => '1.95', }

=example-1 resolve

package main;

use Venus::Config;

my $config = Venus::Config->new({
  name => 'app',
  log => '/tmp/log/app.log',
  '$metadata' => {
    tmplog => "/tmp/log",
    varlog => "/var/log"
  },
  '$services' => {
    log => {
      package => "Venus/Path",
      argument => '.'
    },
    tmp_log => {
      package => "Venus/Path",
      extends => 'log',
      argument => {
        '$metadata' => "tmplog"
      }
    },
    var_log => {
      package => "Venus/Path",
      extends => 'log',
      argument => {
        '$metadata' => "varlog"
      }
    }
  }
});

my $result = $config->resolve;

# undef

The services method returns the $services section of the configuration data if no name is provided, otherwise returning the specific service keyed on the name provided.

services(Str $name) (Any)

{ since => '1.95', }

=example-1 services

# given: synopsis

package main;

my $services = $config->services;

# {}

This package supports resolving services as callbacks to be passed around and/or resolved by other services. The $callback directive is used to specify the name of a service to be resolved and passed as an argument.

{ since => '1.95', }

=example-1 $callback

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    log => {
      package => "Venus/Path",
      argument => '.',
    },
    lazy_log => {
      package => "Venus/Code",
      argument => {
        '$callback' => 'log',
      }
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('lazy_log');

# bless(..., 'Venus::Code')

# my $return = $result->call;

# bless(..., 'Venus::Path')

This package supports inlining environment variables as arguments to services. The $envvar directive is used to specify the name of an environment variable, and can also be used in metadata for reusability.

{ since => '1.95', }

=example-1 $envvar

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    home => {
      package => "Venus/Path",
      argument => {
        '$envvar' => 'home',
      }
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('home');

# bless(..., 'Venus::Path')

This package supports inlining the result of a service resolution and function call as arguments to services. The # delimited $function directive is used to specify the name of an existing service on the right-hand side, and an arbitrary function to be call on the result on the left-hand side.

{ since => '1.95', }

=example-1 $function

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    filespec => {
      package => 'File/Spec/Functions',
    },
    tempdir => {
      package => "Venus/Path",
      argument => {
        '$function' => 'filespec#tmpdir',
      }
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('tempdir');

# bless(..., 'Venus::Path')

This package supports inlining configuration data as arguments to services. The $metadata directive is used to specify the name of a stashed configuration value or data structure.

{ since => '1.95', }

=example-1 $metadata

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$metadata' => {
    home => '/home/ubuntu',
  },
  '$services' => {
    home => {
      package => "Venus/Path",
      argument => {
        '$metadata' => 'home',
      }
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('home');

# bless(..., 'Venus::Path')

This package supports inlining the result of a service resolution and method call as arguments to services. The # delimited $method directive is used to specify the name of an existing service on the right-hand side, and an arbitrary method to be call on the result on the left-hand side.

{ since => '1.95', }

=example-1 $method

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    filespec => {
      package => 'File/Spec',
    },
    tempdir => {
      package => "Venus/Path",
      argument => {
        '$method' => 'filespec#tmpdir',
      }
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('tempdir');

# bless(..., 'Venus::Path')

This package supports inlining the result of a service resolution and routine call as arguments to services. The # delimited $routine directive is used to specify the name of an existing service on the right-hand side, and an arbitrary routine to be call on the result on the left-hand side.

{ since => '1.95', }

=example-1 $routine

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    filespec => {
      package => 'File/Spec',
    },
    tempdir => {
      package => "Venus/Path",
      argument => {
        '$routine' => 'filespec#tmpdir',
      }
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('tempdir');

# bless(..., 'Venus::Path')

This package supports inlining resolved services as arguments to other services. The $service directive is used to specify the name of a service to be resolved and passed as an argument.

{ since => '1.95', }

=example-1 $service

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    'path' => {
      'package' => 'Venus/Path',
    },
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('path');

# bless(..., 'Venus::Path')

This package supports providing static and/or dynamic arguments during object construction from metadata or other services.

{ since => '1.95', }

=example-1 #argument

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    'date' => {
      'package' => 'Venus/Date',
      'argument' => 570672000,
    },
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('date');

# bless(..., 'Venus::Date')

This package supports transforming the way static and/or dynamic arguments are passed to the operation during object construction. Acceptable options are array or arrayref (which provides an arrayref), hash or hashref (which provides a hashref), or list (which provides a flattened list of arguments).

{ since => '1.95', }

=example-1 #argument_as

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    'date' => {
      'package' => 'Venus/Date',
      'argument' => {
        year => 1988,
        month => 2,
        day => 1,
      },
      argument_as => 'list',
    },
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('date');

# bless(..., 'Venus::Date')

This package supports specifying multiple build steps as function, method, and routine calls and chaining them together. Each build step supports any directive that can be used outside of a build step. Each build step can be configured, with the return directive, to use a particular value to chain the next subroutine call. Acceptable return values are class (package name string), result (scalar return value from the current build step), and self (instantiated package). Additionally, you can use the inject directive (with any value accepted by argument_as) to override the default arguments using the arguments provided to the "reify" or "resolve" method.

{ since => '1.95', }

=example-1 #builder

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    datetime => {
      package => "Venus/Date",
      builder => [
        {
          method => 'new',
          argument => 570672000,
          return => 'self',
        },
        {
          method => 'string',
          return => 'result',
        }
      ],
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('datetime');

# "1988-02-01T00:00:00Z"

This package supports configuring services and metadata in the service of building objects and values.

{ since => '1.95', }

=example-1 #config

package main;

use Venus::Config;

my $config = Venus::Config->new({
  'name' => 'app',
  'secret' => '...',
  '$metadata' => {
    home => {
      '$envvar' => 'home',
    }
  },
  '$services' => {
    date => {
      package => "Venus/Date",
    },
    path => {
      package => "Venus/Path",
      argument => {
        '$metadata' => 'home',
      },
    }
  }
});

# bless(..., 'Venus::Config')

# my $path = $config->resolve('path');

# bless(..., 'Venus::Path')

# my $name = $config->resolve('name');

# "app"

This package supports specifying constructors other than the traditional new routine. A constructor is always called with the package name as the invocant.

{ since => '1.95', }

=example-1 #constructor

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    path => {
      package => "Venus/Path",
      constructor => "new",
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('path');

# bless(..., 'Venus::Path')

This package supports extending services in the definition of other services, recursively compiling service configurations and eventually executing the requested compiled service.

{ since => '1.95', }

=example-1 #extends

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    log => {
      package => "Venus/Log",
      argument => {
        level => "trace",
      },
    },
    development_log => {
      package => "Venus/Log",
      extends => "log",
      builder => [
        {
          method => "new",
          return => "self",
          inject => "hash",
        }
      ],
    },
    production_log => {
      package => "Venus/Log",
      extends => "log",
      argument => {
        level => "error",
      },
      builder => [
        {
          method => "new",
          return => "self",
          inject => "hash",
        }
      ],
    },
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('development_log');

# bless(..., 'Venus::Log')

# my $level = $result->level;

# "trace"

# $result = $config->resolve('production_log');

# bless(..., 'Venus::Log')

# $level = $result->level;

# "error"

This package supports specifying construction as a function call, which when called does not provide an invocant.

{ since => '1.95', }

=example-1 #function

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    foo_hex => {
      package => "Digest/MD5",
      function => "md5_hex",
      argument => "foo",
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('foo_hex');

# "acbd18db4cc2f85cedef654fccc4a4d8"

This package supports different lifecycle options which determine when services are built and whether they're persisted. Acceptable lifecycle values are singleton (which caches the result once encountered) and eager (which caches the service upon the first execution of any service).

{ since => '1.95', }

=example-1 #lifecycle

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    match => {
      package => "Venus/Match",
      argument => {
        'a'..'h'
      },
      builder => [
        {
          method => "new",
          return => "result",
        },
        {
          method => "data",
          return => "result",
          inject => "hash",
        }
      ],
      lifecycle => 'eager',
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('thing');

# undef

# my $result = $config->resolve('match');

# bless(..., 'Venus::Match')

This package supports specifying data and structures which can be used in the construction of multiple services.

{ since => '1.95', }

=example-1 #metadata

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$metadata' => {
    'homedir' => '/home',
    'tempdir' => '/tmp',
  },
  '$services' => {
    home => {
      package => "Venus/Path",
      argument => {
        '$metadata' => 'homedir',
      },
    },
    temp => {
      package => "Venus/Path",
      argument => {
        '$metadata' => 'tempdir',
      },
    },
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('home');

# bless(..., 'Venus::Path')

# my $result = $config->resolve('temp');

# bless(..., 'Venus::Path')

This package supports specifying construction as a method call, which when called provides the package or object instance as the invocant.

{ since => '1.95', }

=example-1 #method

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    date => {
      package => "Venus/Date",
      argument => 570672000,
      method => "new",
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('date');

# bless(..., 'Venus::Date')

This package supports specifying construction as a function call, which when called provides the package as the invocant.

{ since => '1.95', }

=example-1 #routine

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    date => {
      package => "Venus/Date",
      argument => 570672000,
      routine => "new",
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('date');

# bless(..., 'Venus::Date')

This package supports defining services to be constructed on-demand or automatically on instantiation.

{ since => '1.95', }

=example-1 #service

package main;

use Venus::Config;

my $config = Venus::Config->new({
  '$services' => {
    path => {
      package => "Venus/Path",
    }
  }
});

# bless(..., 'Venus::Config')

# my $result = $config->resolve('path');

# bless(..., 'Venus::Path')

t/Venus.t: pdml: authors t/Venus.t: pdml: license

cpanm Venus

perl -MCPAN -e shell
install Venus