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.