NAME

Config::Context - Add <Location> and <LocationMatch> style context matching to hierarchical configfile formats such as Config::General, XML::Simple and Config::Scoped

VERSION

Version 0.10

SYNOPSIS

Apache-style configs (via Config::General)

use Config::Context;

my $config_text = '

    <Location /users>
        title = "User Area"
    </Location>

    <LocationMatch \.*(jpg|gif|png)$>
        image_file = 1
    </LocationMatch>

';

my $conf = Config::Context->new(
    string        => $config_text,
    driver        => 'ConfigGeneral',
    match_sections => [
        {
            name          => 'Location',
            match_type    => 'path',
        },
        {
            name          => 'LocationMatch',
            match_type    => 'regex',
        },
    ],
);

my %config = $conf->context('/users/~mary/index.html');

use Data::Dumper;
print Dumper(\%config);
--------
$VAR1 = {
    'title'         => 'User Area',
    'image_file'    => undef,
};

my %config = $conf->context('/users/~biff/images/flaming_logo.gif');
print Dumper(\%config);
--------
$VAR1 = {
    'title'         => 'User Area',
    'image_file'    => 1,
};

XML configs (via XML::Simple)

use Config::Context;

my $config_text = '
    <opt>

      <Location name="/users">
        <title>User Area</title>
      </Location>

      <LocationMatch name="\.*(jpg|gif|png)$">
        <image_file>1</image_file>
      </LocationMatch>

    </opt>
';

my $conf = Config::Context->new(
    string        => $config_text,
    driver        => 'XMLSimple',
    match_sections => [
        {
            name          => 'Location',
            match_type    => 'path',
        },
        {
            name          => 'LocationMatch',
            match_type    => 'regex',
        },
    ],
);

my %config = $conf->context('/users/~mary/index.html');

use Data::Dumper;
print Dumper(\%config);
--------
$VAR1 = {
    'title'         => 'User Area',
    'image_file'    => undef,
};

my %config = $conf->context('/users/~biff/images/flaming_logo.gif');
print Dumper(\%config);
--------
$VAR1 = {
    'title'         => 'User Area',
    'image_file'    => 1,
};

Config::Scoped style configs

use Config::Context;

my $config_text = '
    Location /users {
        user_area = 1
    }

    LocationMatch '\.*(jpg|gif|png)$' {
        image_file = 1
    }
';

my $conf = Config::Context->new(
    string        => $config_text,
    driver        => 'ConfigScoped',
    match_sections => [
        {
            name          => 'Location',
            match_type    => 'path',
        },
        {
            name          => 'LocationMatch',
            match_type    => 'regex',
        },
    ],
);

my %config = $conf->context('/users/~mary/index.html');

use Data::Dumper;
print Dumper(\%config);
--------
$VAR1 = {
    'title'         => 'User Area',
    'image_file'    => undef,
};

my %config = $conf->context('/users/~biff/images/flaming_logo.gif');
print Dumper(\%config);
--------
$VAR1 = {
    'title'         => 'User Area',
    'image_file'    => 1,
};

DESCRIPTION

Introduction

This module provides a consistent interface to many hierarchical configuration file formats such as Config::General, XML::Simple and Config::Scoped.

It also provides Apache-style context matching. You can include blocks of configuration that match or not based on run-time parameters.

For instance (using Config::General syntax):

company_name      = ACME
in_the_users_area = 0

<Location /users>
    in_the_users_area = 1
</Location>

At runtime, if Location is within /users, then the configuration within the <Location> block is merged into the top level. Otherwise, the block is ignored.

So if Location is /users/gary, the configuration is reduced to:

{
    company_name      => 'ACME',
    in_the_users_area => 1,
}

But if Location is outside of the /users area (e.g. /admin/documents.html), the configuration is reduced to:

{
    company_name      => 'ACME',
    in_the_users_area => 0,
}

The exact mechanics of how Location matches /users is extensively customizable. You can configure a particular block to match based on exact string matches, a substring, a path, or a regex.

This kind of context-based matching was inspired by Apache's context-based configuration files.

Config::Context works with Apache-style config files (via Config::General), XML documents (via XML::Simple), and Config::Scoped config files. You select the type config file with the driver option to new.

The examples in this document use Config::General (Apache-style) syntax. For details on other configuration formats, see the documentation for the appropriate driver.

For a real world example of Config::Context in action, see CGI::Application::Plugin::Config::Context, which determines configurations based on the URL of the request, the name of the Perl Module, and the virtual host handling the web request.

The Default Section

Config values that appear outside of any block act like defaults. Values in matching sections are merged with the default values. For instance:

private_area = 0
client_area  = 0

<Location /admin>
    private_area = 1
</Location>

<Location /clients>
    client_area  = 1
</Location>

# Admin Area URL
my %config = $conf->context('/admin/index.html');
use Data::Dumper;
print Dumper(\%config);
$VAR1 = {
    'private_area' => 1,
    'client_area' => 0,
};

# Client Area URL
my %config = $conf->context('/clients/index.html');
print Dumper(\%config);
$VAR1 = {
    'private_area' => 0,
    'client_area'  => 1,
};

# Neither Client nor Admin
my %config = $conf->context('/public/index.html');
print Dumper(\%config);
$VAR1 = {
    'private_area' => 0,
    'client_area'  => 0,
};

When using the Config::Context::ConfigScoped driver, you must be careful with the use of the default section, since Config::Scoped does its own inheritance from the global scope into named sections. See the documentation for Config::Context::ConfigScoped for more information.

Subsections are preserved

When a block matches, and its configuration is merged into the top level, any subsections that it contained are preserved along with single values. For instance:

# Default config
private_area = 0
client_area  = 0
<page_settings>
    title       = "The Widget Emporium"
    logo        = logo.gif
    advanced_ui = 0
</page_settings>

# Admin config
<Location /admin>
    private_area = 1
    <page_settings>
        title       = "The Widget Emporium - Admin Area"
        logo        = admin_logo.gif
        advanced_ui = 1
    </page_settings>
</Location>

# Client config
<Location /clients>
    client_area  = 1
    <page_settings>
        title = "The Widget Emporium - Wholesalers"
        logo  = client_logo.gif
    </page_settings>
</Location>

# Admin Area URL
my %config = $conf->context('/admin/index.html');

use Data::Dumper;
print Dumper(\%config);
--------
$VAR1 = {
    'page_settings' => {
                        'advanced_ui' => '1',
                        'title' => 'The Widget Emporium - Admin Area',
                        'logo' => 'admin_logo.gif'
                       },
    'private_area' => '1',
    'client_area' => '0'
};

# Client Area URL
my %config = $conf->context('/clients/index.html');

print Dumper(\%config);
--------
$VAR1 = {
    'page_settings' => {
                        'advanced_ui' => '0',
                        'title' => 'The Widget Emporium - Wholesalers',
                        'logo' => 'client_logo.gif'
                       },
    'client_area' => '1',
    'private_area' => '0'
};

# Neither Client nor Admin
my %config = $conf->context('/public/index.html');

print Dumper(\%config);
--------
$VAR1 = {

    'page_settings' => {
                        'advanced_ui' => '0',
                        'title' => 'The Widget Emporium',
                        'logo' => 'logo.gif'
                       },
    'client_area' => '0',
    'private_area' => '0'

};

Multiple Sections Matching

Often more than one section will match the target string. When this happens, the matching sections are merged together using the Hash::Merge module. Typically this means that sections that are merged later override the values set in earlier sections. (But you can change this behaviour. See "Changing Hash::Merge behaviour" below.)

The order of merging matters. The sections are merged first according to each section's merge_priority value (lowest values are merged first), and second by the length of the substring that matched (shortest matches are merged first). If you don't specify merge_priority for any section, they all default to a priority of 0 which means all sections are treated equally and matches are prioritized based soley on the length of the matching strings.

When two sections have the same priority, the section with the shorter match is merged first. The idea is that longer matches are more specific, and should have precidence.

The order of sections in the config file is ignored.

For instance, if your config file looks like this:

<Dir /foo/bar/baz>
    # section 1
</Dir>

<Path /foo>
    # section 2
</Path>

<Dir /foo/bar>
    # section 3
</Dir>

<Directory /foo/bar/baz/bam>
    # section 4
</Directory>

...and you construct your $conf object like this:

my $conf         = Config::Context->new(
    driver         => 'ConfigGeneral',
    match_sections => [
        { name    => 'Directory',  match_type => 'path' merge_priority => 1 },
        { name    => 'Dir',        match_type => 'path' merge_priority => 1 },
        { name    => 'Path',       match_type => 'path' merge_priority => 2 },
    ],
);

...then the target string '/foo/bar/baz/bam/boom' would match all sections the order of 1, 3, 4, 2.

Matching Context based on More than one String

You have different sections match against different run time values. For instance, you could match some sections against the day of the week and other sections against weather:

my $config = '

weekend    = 0
background = ''

<Day Saturday>
    weekend = 1
</Day>

<Weekday Sunday>
    weekend = 1
</Weekday>

<Weather sunny>
    sky = blue
</Weather>

<Weather cloudy>
    sky = grey
</Weather>
';

my $conf = Config::Context->new(
    driver         => 'ConfigGeneral',
    match_sections => [
        { name => 'Day',      section_type => 'day',     match_type => 'path' },
        { name => 'Weekday',  section_type => 'day',     match_type => 'path' },
        { name => 'Weather',  section_type => 'weather', match_type => 'regex' },
    ],
);

my %config = $conf->context(day => 'Friday', weather => 'sunny');

print Dumper(\%config);
--------
$VAR1 = {
    'weekend' => 0,
    'sky'     => 'blue',
};

my %config = $conf->context(day => 'Sunday', weather => 'partially cloudy');

print Dumper(\%config);
--------
$VAR1 = {

    'weekend' => 1,
    'sky'     => 'grey',
};

Matching other path-like strings

You can use Config::Context to match other hierarchical strings besides paths and URLs. For instance you could specify a path_separator of :: and use the path feature to match against Perl modules:

my $config_text = "

    is_core_module 0
    <Module NET::FTP>
        is_core_module 1
        author         Nathan Torkington
    </Module>

    <Module NET::FTPServer>
        author Richard Jone
    </Module>

";

my $conf = Config::Context->new(
    driver         => 'ConfigGeneral',
    string         => $config_text,
    match_sections => [
        {
            name           => 'Module',
            path_separator => '::',
            match_type     => 'path',
        },
    ],
);

my %config = $conf->context('Net::FTP');

use Data::Dumper;
print Dumper(\%config);
--------
$VAR1 = {
    'is_core_module' => 1,
    'author'         => 'Nathan Torkington',
};

Nested Matching

You can have matching sections within matching sections:

<Site bookshop>
    <Location /admin>
        admin_area = 1
    </Location>
</Site>
<Site recordshop>
    <Location /admin>
        admin_area = 1
    </Location>
</Site>

Enable this feature by setting nesting_depth parameter to new, or by calling $conf->nesting_depth($some_value).

Note: see the documentation of Config::Context::ConfigScoped for the limitations of nesting with Config::Scoped files.

CONSTRUCTOR

new(...)

Creates and returns a new Config::Context object.

The configuration can be read from a file, parsed from a string, or can be generated from a perl data struture.

To read from a config file:

my $conf = Config::Context->new(
    file           => 'somefile.conf',
    driver         => 'ConfigGeneral',
    match_sections => [
       {  name  => 'Directory',  match_type => 'path' },
    ],
);

To parse from a string:

my $text = '
    in_the_users_area = 0
    <Directory /users>
        in_the_users_area = 1
    </Directory>
';

my $conf = Config::Context->new(
    string         => $text,
    driver         => 'ConfigGeneral',
    match_sections => [
       {  name => 'Directory',    match_type => 'path' },
    ],
);

To generate from an existing Perl data structure:

my %config = (
    'in_the_user_area' => '0'
    'Location' => {
        '/users' => {
            'in_the_user_area' => '1'
        },
    },
);

my $conf = Config::Context->new(
    config         => \%config,
    driver         => 'ConfigGeneral',
    match_sections => [
       {  name => 'Directory',    match_type => 'path' },
    ],
);

The parameters to new are described below:

file

The config file.

string

A string containing the configuration to be parsed. If string is specified then file is ignored.

config

A Perl multi-level data structure containing the configuration. If config is specified, then both file and string are ignored.

driver

Which Config::Context driver should parse the config. Currently supported drivers are:

driver            module name
------            -----------
ConfigGeneral     Config::Context::ConfigGeneral
ConfigScoped      Config::Context::ConfigScoped
XMLSimple         Config::Context::XMLSimple

driver_options

Options to pass directly on to the driver. This is a multi-level hash, where the top level keys are the driver names:

my $conf = Config::Context->new(
    driver => 'ConfigScoped',
    driver_options => {
       ConfigGeneral => {
           -AutoLaunder => 1,
       },
       ConfigScoped = > {
           warnings => {
               permissions  => 'off',
           }
       },
    },
);

In this example the options under ConfigScoped will be passed to the ConfigScoped driver. (The options under ConfigGeneral will be ignored because driver is not set to 'ConfigGeneral'.)

match_sections

The match_sections parameter defines how Config::Context matches runtime values against configuration sections.

match_sections takes a list of specification hashrefs. Each specification has the following fields:

name

The name of the section. For a name of 'Location', the section would look like:

<Location /somepath>
</Location>

match_type

Specifies the method by which the section strings should match the target string.

The valid types of matches are 'exact', 'substring', 'regex', 'path', and 'hierarchical'

exact

The config section string matches only if it is equal to the target string. For instance:

# somefile.conf
<Site mysite>
    ...
</Site>
...

my $conf = Config::Context->new(
    driver         => 'ConfigGeneral'
    match_sections => [
        {
            name       => 'Site',
            match_type => 'exact',
        },
    ],
    file => 'somefile.conf',
);

In this case, only the exact string mysite would match the section.

substring

The config section string is tested to see if it is a substring of the target string. For instance:

# somefile.conf
<Location foo>
    ...
</Location>

...

my $conf = Config::Context->new(
    driver         => 'ConfigGeneral'
    match_sections => [
        {
            name       => 'LocationMatch',
            match_type => 'substring',
        },
    ],
    file => 'somefile.conf',
);

In this case, the following target strings would all match:

/foo
big_foo.html
/hotfood

regex

The config section string is treated as a regular expression against which the target string is matched. For instance:

# somefile.conf
<LocationMatch (\.jpg)|(\.gif)(\.png)$>
    Image = 1
</LocationMatch>

...

my $conf = Config::Context->new(
    driver         => 'ConfigGeneral'
    match_sections => [
        {
            name       => 'LocationMatch',
            match_type => 'regex',
        },
    ],
    file        => 'somefile.conf',
);

my %config = $conf->context('banner.jpg');

The regex can contain any valid Perl regular expression. So to match case-insensitively you can use the (?i:) syntax:

<LocationMatch (?i:/UsErS)>
    UserDir = 1
</LocationMatch>

Also note that the regex is not tied to the beginning of the target string by default. So for regexes involving paths you will probably want to do so explicitly:

<LocationMatch ^/users>
    UserDir = 1
</LocationMatch>

path

This method is useful for matching paths, URLs, Perl Modules and other hierarchical strings.

The config section string is tested against the the target string. It matches if the following are all true:

The section string is a substring of the target string
The section string starts at the first character of the target string
In the target string, the section string is followed immediately by path_separator or the end-of-string.

For instance:

# somefile.conf
<Location /foo>
</Location>

...

my $conf = Config::Context->new(
    driver         => 'ConfigGeneral'
    match_sections => [
        {
            name       => 'LocationMatch',
            match_Type => 'path',
        },
    ],
    file        => 'somefile.conf',
);

In this case, the following target strings would all match:

/foo
/foo/
/foo/bar
/foo/bar.txt

But the following strings would not match:

/foo.txt
/food
/food/bar.txt
foo.txt

hierarchical

A synonym for 'path'.

path_separator

The path separator when matching hierarchical strings (paths, URLs, Module names, etc.). It defaults to '/'.

This parameter is ignored unless the match_type is 'path' or 'hierarchical'.

section_type

Allows you to match certain sections against certain run time values. For instance, you could match some sections against a given filesystem path and some sections against a Perl module name, using the same config file.

# somefile.conf
# section 1
<FileMatch \.pm$>
    Perl_Module      = 1
    Core_Module      = 1
    Installed_Module = 0
</FileMatch>

# section 2
<FileMatch ^/.*/lib/perl5/site_perl>
    Core_Module = 0
</FileMatch>

# section 3
# Note the whitespace at the end of the section name, to prevent File from
# being parsed as a stand-alone block by Config::General
<File /usr/lib/perl5/ >
    Installed_Module = 1
</File>

# section 4
<Module NET::FTP>
    FTP_Module = 1
</Module>

my $conf = Config::Context->new(
    driver         => 'ConfigGeneral'
    match_sections => [
        {
            name         => 'FileMatch',
            match_type   => 'regex',
            section_type => 'file',
        },
        {
            name         => 'File',
            match_type   => 'path',
            section_type => 'file',
        },
        {
            name         => 'Module',
            match_type   => 'path',
            separator    => '::',
            section_type => 'module',
        },
    ],
    file        => 'somefile.conf',

    # need to turn off C-style comment parsing because of the
    # */ in the name of section 2
    driver_options => {
        ConfigGeneral => {
            -CComments => 0,
        }
    },
);

my %config = $conf->context(
    file   => '/usr/lib/perl5/site_perl/5.6.1/NET/FTP/Common.pm',
    module => 'NET::FTP::Common',
);

This tests /usr/lib/perl5/site_perl/5.6.1/NET/FTP/Common.pm against sections 1, 2 and 3 (and merging them in the order of shortest to longest match, i.e. 1, 3, 2).

Then it tests 'NET::FTP::Common' against section 4 (which also matches). The resulting configuration is:

use Data::Dumper;
print Dumper(\%config);
--------
$VAR1 = {
    'Perl_Module'      => 1,
    'Core_Module'      => 0,
    'FTP_Module'       => 1,
    'Installed_Module' => 1,
};

Another example:

my %config = $conf->context(
    file   => '/var/www/cgi-lib/FTP/FTPServer.pm',
    module => 'NET::FTPServer',
);

This tests /var/www/cgi-lib/NET/FTPServer.pm against sections 1, 2 and 3, and matches only against section 1. Then it matches 'NET::FTPServer' against section 4 (which does not match). The result is:

use Data::Dumper;
print Dumper(\%config);
--------
$VAR1 = {
    'Perl_Module'      => 1,
    'Core_Module'      => 0,
    'FTP_Module'       => 0,
    'Installed_Module' => 0,
};

If a section_type is not specified in a match_sections block, then target strings of a named type will not match it.

For another example, see "Matching Context based on More than one String", above.

Matching by section_type is used in CGI::Application::Plugin::Config::Context to determine configurations based both on the URL of the request and of the name of the Perl Module and runmode handling the request.

trim_section_names

By default, section names are trimmed of leading and trailing whitespace before they are used to match. This is to allow for sections like:

<Path /foo/bar/ >
</Path>

The whitespace at the end of the section name is necessary to prevent Config::General's parser from thinking that the first tag is an empty <Path /> block.

<Path /foo/bar/>  # Config::General parses this as <Path />
</Path>           # Config::General now considers this to be spurious

If leading and trailing whitespace is significant to your matches, you can disable trimming by setting trim_section_names to 0 or undef.

merge_priority

Sections with a lower merge_priority are merged before sections with a higher merge_priority. If two or more sections have the same merge_priority they are weighted the same and they are merged according to the "best match" against the target string (i.e. the longest matching substring).

See the description above under "Multiple Sections Matching".

nesting_depth

This option alows you to match against nested structures.

# stories.conf
<Story Three Little Pigs>
    antagonist = Big Bad Wolf
    moral      = obey the protestant work ethic
</Story>

<Location /aesop>
    <Story Wolf in Sheep's Clothing>
        antagonist = Big Bad Wolf
        moral      = appearances are deceptive
    </Story>
</Location>

<Story Little Red Riding Hood>
    antagonist = Big Bad Wolf

    <Location /perrault>
        moral      = never talk to strangers
    </Location>

    <Location /grimm>
        moral      = talk to strangers and then chop them up
    </Location>
</Story>


my $conf = Config::Context->new(
    match_sections => [
        {
            name         => 'Story',
            match_type   => 'substring',
            section_type => 'story',
        },
        {
            name         => 'Location',
            match_type   => 'path',
            section_type => 'path',
        },
    ],
    file          => 'stories.conf',
    nesting_depth => 2,
);

$config = $conf->context(
    story => 'Wolf in Sheep\'s Clothing',
    path  => '/aesop/wolf-in-sheeps-clothing',
);

use Data::Dumper;
print Dumper($config);
--------
$VAR1 = {
    'antagonist' => 'Big Bad Wolf',
    'moral'      => 'appearances are deceptive'
};

You can also change the nesting depth by calling $self->nesting_depth($depth) after you have constructed the Config::Context object.

lower_case_names

Attempts to force all section and key names to lower case. If lower_case_names is true, then the following sections would all match 'location':

<Location /somepath>
</Location>

<loCATtion /somepath>
</Location>

<lOcAtion /somepath>
</LOCATION>

Note: the XMLSimple driver does not support this option.

cache_config_files

Whether or not to cache configuration files. Enabled, by default. This option is useful in a persistent environment such as mod_perl. See "Config File Caching" under "ADVANCED USAGE", below.

stat_config

If config file caching is enabled, this option controls how often the config files are checked to see if they have changed. The default is 60 seconds. This option is useful in a persistent environment such as mod_perl. See "Config File Caching" under "ADVANCED USAGE", below.

METHODS

raw()

Returns the raw configuration data structure as read by the driver, before any context matching is performed.

context( $target_string )

Returns the merged configuration of all sections matching $target_string, according to the rules set up in match_sections in new(). All match_sections are included, regardless of their section_type.

context( $type => $target_string )

Returns the merged configuration matching $target_string, based only the match_sections that have a section_type of $type.

context( $type1 => $target_string1, $type2 => $target_string2 )

Returns the merged configuration of all sections of section_type $type1 matching $target_string1 and all sections of section_type $type2 matching $target_string2.

The order of the parameters to context() is retained, so $type1 sections will be matched first, followed by $type2 sections.

context( )

If you call context without parameters, it will return the same configuration that was generated by the last call to context.

If you call context in a scalar context, you will receive a reference to the config hash:

my $config = $conf->context($target_string);
my $value  = $config->{'somekey'};

In a list context, context returns a hash:

my %config = $conf->context($target_string);
my $value  = $config{'somekey'};

files

Returns a list of all the config files read, including any config files included in the main file.

nesting_depth()

Changes the default nesting depth, for matching nested structures. See the nesting_depth parameter to new.

clear_file_cache

Clears the internal file cache. Class method.

Config::Context->clear_file_cache;
$conf->clear_file_cache;

ADVANCED USAGE

Config File Caching

By default each config file is read only once when the conf object is first initialized. Thereafter, on each init, the cached config is used.

This means that in a persistent environment like mod_perl, the config file is parsed on the first request, but not on subsequent requests.

If enough time has passed (sixty seconds by default) the config file is checked to see if it has changed. If it has changed, then the file is reread.

If the driver supports it, any included files will be checked for changes along the main file. If you use Config::General, you must use version 2.28 or greater for this feature to work correctly.

To disable caching of config files pass a false value to the cache_config_files parameter to new, e.g:

my $conf = Config::Context->new(
    cache_config_files => 0,
    # ... other options here ...
);

To change how often config files are checked for changes, change the value of the stat_config paramter to init, e.g.:

my $conf = Config::Context->new(
    stat_config => 1, # check the config file every second
    # ... other options here ...
);

Internally the configuration cache is implemented by a hash, keyed by the absolute path of the configuration file. This means that if you have two applications running in the same process that both use the same configuration file, they will use the same cache.

However, matching is performed on the config retrieved from the cache, so the two applications could each use different matching options creating different configurations from the same file.

Changing Hash::Merge behaviour

Matching sections are merged together using the Hash::Merge module. If you want to change how this module does its work you can call subroutines in the Hash::Merge package directly. For instance, to change the merge strategy so that earlier sections have precidence over later sections, you could call:

# Note American Spelling :)
Hash::Merge::set_behavior('RIGHT_PRECEDENT')

You should do this before you call context().

For more information on how to change merge options, see the Hash::Merge docs.

AUTHOR

Michael Graham, <mag-perl@occamstoothbrush.com>

BUGS

Please report any bugs or feature requests to bug-config-context@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

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

To install Config::Context, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Config::Context

CPAN shell

perl -MCPAN -e shell
install Config::Context

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)