NAME

WWW::Lk4 - rule- and data-based transformation of URLs

SYNOPSIS

use WWW::Lk4;
$lk4 = WWW::Lk4->new(
    'config_file' => $conf,
    'data_dir'    => $dir,
    ...
);
$lk4->let('$foo' => 'bar');
$lk4->let('foo(bar)' => \&baz);
%result = $lk4->resolve('/absolute/uri/path');

DESCRIPTION

WWW::Lk4 resolves URIs into target URIs.

It is suitable for use in a general link redirection service.

METHODS

new

$lk4 = WWW::Lk4->new(
    'config_file' => $conf,
    'data_dir'    => $dir,
    ...
);

Which config files are read may be overridden by specifying config_file or config_dir arguments (or both):

$lk4 = WWW::Lk4->new(
    'config_file' => '/etc/lk4/foo/main.conf',
    'config_dir'  => '/etc/lk4/foo/includes',
);

If config_file is used but not config_dir, then config_dir will be set to the value of config_file with .d substituted for .conf.

The names of config files within config_dir must match the glob *.conf or they will be ignored.

read_config_file

$lk4->read_config_file($f);

let

$lk4->let('$foo' => 'bar');
$lk4->let('foo(bar)' => \&baz);

Define a variable or function. This is not normally required, as you can accomplish the same thing using a Perl function in a config file.

resolve

%result = $lk4->resolve($uri);
if (!$result{ok}) {
    print "Error: $result{message}\n";
}
elsif ($result{uri}) {
    print "URI: $result{uri}\n";
}
elsif ($result{menu}) {
    print "Menu: $result{menu}{title}\n";
}

CONFIGURATION

Config files contain this stuff...

under

under introduces a scope under which URIs beginning with a particular prefix may be resolved. For example:

under /doc {
    forward /<docid>        to http://public.example.org/read?docID=<docid>
    forward /<docid>/secret to http://secret.example.org/read?docID=<docid>
}

This would redirect /doc/12345 to http://public.example.org/read?docID=12345 and /doc/98765/secret to http://secret.example.org/read?docID=98765.

An under block may contain any directive, not just redirect; those directives will apply only to URIs that fall under the given prefix.

function

A function takes zero or more inputs and produces an output. You can use this, for example, to map library names to proxy prefixes

function base(name) {
    main  -> http://example.net
    smith -> http://smith.example.net
    jones -> http://jones.example.net
}
forward /foo/<name>/<docid> to <base(name)>/foo/<docid>

Functions may be defined in a data file:

function new(docid) from doc-id-mapping
forward /doc/<docid> to http://new.example.org/doc/<new(docid)>

Functions may be written in Perl:

function qux(docid) :perl {
    my ($docid) = @_;
    my $uri = ...;
    return $uri;
}

menu

A menu is a list of URIs to present to the user. Example:

under /doc {
    menu pdf_or_text(docid) {
        title Alternatives
        item /pdf/<docid>.pdf   "PDF"
        item /txt/<docid>.txt   "Text"
    }
    forward /<docid> to :menu pdf_or_text(docid)
}

FILES

Default config files are as follows:

/usr/local/lk4/conf/lk4.conf

/usr/local/lk4/conf/lk4.d/*.conf

BUGS

Functions must be called using arguments whose names match the formal parameter names with which the function was declared. Ditto menus.

AUTHOR

Paul Hoffman <paul@flo.org>.

LICENCE AND COPYRIGHT

Copyright (c) 2012 Fenway Libraries Online.

This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.