/ 
rig-0.01_03
/ rig

NAME

rig - Bundle up your favorite modules and imports into one call

SYNOPSIS

In your /home/user/.perlrig yaml file:

common:
   use:
      - strict
      - warnings
      - List::Util:
         - first
         - max
      - Data::Dumper

Back in your code:

use rig common;

# same as:
#   use strict;
#   use warnings;
#   use List::Util qw/first max/;
#   use Data::Dumper;

# now, have a ball:

print first { $_ > 10 } @ary; # from List::Utils;
print Dumper $foo;  # from Data::Dumper

DESCRIPTION

This module allows you to organize and bundle your favorite modules, thus reducing the recurring task of useing them in your programs, and implicitly requesting imports by default.

You can rig your bundles in 2 places:

  • A file called .perlrig in your home or current working directory.

  • Packages undeneath the rig::task::<rig_task_name>

IMPLEMENTATION

This module uses lots of internal gotos to trick modules to think they're being loaded by the original caller, and not by rig itself. And hooks to keep modules orderly loading.

Modules that don't have an import() method, are instead evalled into the caller's package.

This is a hacky, and I'm certainly open to suggestions on how to make loading modules more generic and effective.

USAGE

Code

use rig -file   => '/tmp/.rig';           # explicitly use a file
use rig -path   => qw(. /home/me /opt);
use rig -engine => 'base';
use rig -jit    => 1;

use rig moose, strictness, modernity;

use rig 'kensho';
use rig 'kensho::strictive';    # looks for rig::task::kensho::strictive
use rig 'signes';
use rig 'debugging';

.perlrig YAML structure

<task>:
   use:
      - <module> [min_version]
      - <module>:
         - <import1>
         - <import2>
         - ...
   also: <task2> [, <task3> ... ]

use section

  • Lists modules to be used.

  • Checks module versions.

  • Lists imports.

also section

Used to bundle tasks into each other.

Examples

moose:
   use:
      - Moose 0.92
      - Moose::Autobox
      - autodie
      - Method::Signatures
      - Try::Tiny
goo:
   use:
      - strict
      - warnings
      - Data::Dumper
      - feature:
         - say
         - switch
      - Data::Alias
      - autodie
bam:
   use:
      - List::Util:
         - first
         - max
         - min
      - Scalar::Util:
          - refaddr
      - Carp:
         - cluck
         - croak

The .perlrig file

The .perlrig file is where you keep your favorite rigs.

As mentioned earlier, rig looks for a .perlrig file in two directories by default:

* The current working directory.
* Your home directory.

Important: only one rig file is loaded per perl interpreter instance. This will probably change in the future, as .perlrig file merging should be implemented.

Structure

It could have had room to put your funky startup code, but it doesn't. This module is about order and parseability.

Having a structured file written in plain yaml makes it easier for worldly parsers to parse the file and understand your configuration.

Writing your own parser

Although this distribution only comes with a yaml parser for the .perlrig file. you can still write your own parser if you like:

package rig::parser::xml;
use base 'rig::parser::base';

sub parse { return .... } 

# meanwhile in Gotham City:

package main;
use rig -parser => 'xml';
use rig 'fav-in-xml';

Global settings

Use the $ENV{PERLRIG_FILE} variable to tell rig where to find your file.

$ export PERLRIG_FILE=/etc/myrig
$ perl foo_that_rigs.pl

rig::task:: modules

A more distribution-friendly way of wiring up module bundles for your application is to ship them as part of the rig::task:: namespace.

package rig::task::myfav;

sub rig {
     return {
      use => [
         'strict',
         { 'warnings'=> [ 'FATAL','all' ] }
      ],
      also => 'somethingelse',
   };
}

This is the recommended way to ship a rig with your distribution.

CAVEATS

Although short, the api and yaml specs are still unstable and are subject to change. Mild thought has been put into it as to support modifications without major deprecations.

Startup Cost

There's an upfront load time (on the first use rig it finds) while rig looks for, parses and processes your .perlrig file. Subsequent calls won't look for any more files, as it's structure will remain loaded in memory.

Ordered Load

As of right now, module loading order tends to get messed up easily. This will probably be fixed, as the author's intention is to load modules following the order set by the user in the .perlrig and use rig statements.

TODO

  • Straighten out and optimize internals.

  • Test many more modules for edge cases.

  • More verbs besides use and also, such as require, etc.

  • A cookbook of some sort, with everyday examples.

  • More tests.

  • Fix load sequence.