[pmwiki-devel] Proposal: "Directives" Registry

Ben Wilson dausha at gmail.com
Thu Aug 9 07:46:35 CDT 2007


There are quite a few recipes that use the (:directive args:) markup.
In each case, raw input is passed to the acting routine, which is
sometimes processed via ParseArgs(). I would like to suggest a change
to PmWiki that may improve recipe construction a tad. I believe a
cursory glance at some recipes using directives will show the same
behavior being executed. I argue that the DRY principle supports
refactoring this behavior.

What I propose is to have PmWiki automatically parse (:directive
args:), where 'directive' is a key to a Directive Registry that maps
to the correspondnig function, and 'args' are already processed via
ParseArgs(). There would be a RegisterDirective() function to help add
new directives. This has the advantage of not requiring recipe authors
to use Markup(), write the regex, etc. Below is a simple description
of the $DirectiveRegistry and its register function. Then, a short
example of registering a custom directive, and how the directive would
be accessed.

$DirectiveRegistry = array(
    'pagelist' => 'FmtPageList',
function RegisterDirective($key, $func) {
    global $DirectiveRegistry;
    $DirectiveRegistry[$key] = $func;

(IN RECIPE): RegisterDirective('gma-map', 'GmaMap');
(ALLOWS): (:gma-map(.*?):)

function ProcessDirective($directive, $args) {
    global $pagename, $DirectiveRegistry;
    if (!$DirectiveRegistry[$directive]) return "(:$directive $args:)";
    $opts = ParseArgs($args);
    $fn = $DirectiveRegistry[$directive];
    return $fn($pagename, $opts);

I would argue moving to this behavior would necessitate a 2.3-series,
or maybe even a 3.0-series. Probably the former. This is too much new
behavior to fit into the 2.2 beta series, which should probably be
near stable.

I understand that this move would necessitate changing how PmWiki
handles some directives internally. A quick "grep '(:' *" in the
scripts directory shows 30-40 standard directives that would have to
be evaluated. One apparent mitigation would be to have this directive
registry execute after all standard directives.

I also understand that this might break quite a few custom recipe
directives. However, those could be identified early enough and a hit
list posted. Identification would be Patrick performing a grep on the
uploads/Cookbook directory to find the culprits, then posting the
output to a wiki page "recipes needing change in 2.3." Leave it to the
Community (er, us) to patch the recipes.

Why would I propose a radical move? With PmWiki's malliability, it has
become a wiki-based web-app framework. I mean, I hacked a new XToDo
recipe (adding and listing only currently) in less than an hour. Due
to the number of directives-based recipes I've authored over the past
three years, I am surprised I hadn't created a library to do this
before---but I probably will now if there is insufficient interest to
modify the core.

Patrick, if this suggestion has legs, I would be willing to create a
new "directives_registry.php" for submission/donation to the core.
I've crawled through PmWiki enough to get close to your style, but my
goal in the creation would be to give you a head start---I would
assume what I offer would need some improvement. I anticipate the
first step is the directives_registry.php to be a recipe first to
build interest. I will probably write that up this evening (EDT) and
publish the recipe. However, I wanted to announce my ambition for the
registry up-front.

Ben Wilson
"Words are the only thing which will last forever" Churchill

More information about the pmwiki-devel mailing list