doc/todo/pagespec_aliases.mdwn

   1 [[!tag patch wishlist]]I quite often find myself repeating a boiler-plate
   2 [[ikiwiki/pagespec]] chunk, e.g.
   3
   4     and !*.png and !*.jpg...
   5
   6 it would be quite nice if I could conveniently bundle them together into a
   7 pagespec "alias", and instead write
   8
   9     and !image()...
  10
  11 I wrote the following plugin to achieve this:
  12
  13     commit f3a9dd113338fe5d2b717de1dc69679ff74e2f8d
  14     Author: Jon Dowland <jmtd@debian.org>
  15     Date:   Tue May 3 17:40:16 2011 +0100
  16
  17         new plugin: alias.pm - pagespec aliases
  18
  19     diff --git a/IkiWiki/Plugin/alias.pm b/IkiWiki/Plugin/alias.pm
  20     new file mode 100644
  21     index 0000000..b8d4574
  22     --- /dev/null
  23     +++ b/IkiWiki/Plugin/alias.pm
  24     @@ -0,0 +1,47 @@
  25     +package IkiWiki::Plugin::alias;
  26     +
  27     +use warnings;
  28     +use strict;
  29     +use IkiWiki '3.00';
  30     +
  31     +sub import {
  32     +  hook(type => "getsetup", id=> "alias", call => \&getsetup);
  33     +  hook(type => "checkconfig", id=> "alias", call => \&checkconfig);
  34     +}
  35     +
  36     +sub getsetup () {
  37     +    return
  38     +        plugin => {
  39     +            description => "allows the definition of pagespec aliases",
  40     +            safe => 1,
  41     +            rebuild => 1,
  42     +            section => "misc",
  43     +        },
  44     +        pagespec_aliases => {
  45     +            type => "string",
  46     +            example => {"image" => "*jpg or *jpeg or *png or *gif or *ico" },
  47     +            description => "a set of mappings from alias name to pagespec",
  48     +            safe => 1,
  49     +            rebuild => 0,
  50     +        },
  51     +}
  52     +
  53     +sub checkconfig () {
  54     +    no strict 'refs';
  55     +    no warnings 'redefine';
  56     +
  57     +    if ($config{pagespec_aliases}) {
  58     +        foreach my $key (keys %{$config{pagespec_aliases}}) {
  59     +            my $value = ${$config{pagespec_aliases}}{$key};
  60     +            # XXX: validate key?
  61     +            my $subname = "IkiWiki::PageSpec::match_$key";
  62     +            *{ $subname } = sub {
  63     +              my $path = shift;
  64     +              return IkiWiki::pagespec_match($path, $value);
  65     +            }
  66     +        }
  67     +    }
  68     +}
  69     +
  70     +1;
  71
  72 I need to reflect on this a bit more before I send a pull request.  In
  73 particular I imagine the strict/warnings stuff will make you puke.  Also, I'm
  74 not sure whether I should name-grab 'alias' since [[todo/alias_directive]] is
  75 an existing wishlist item.
  76
  77 > I think it would make sense to have "pagespec" in the name somehow.
  78 >
  79 > No, the strict/warnings does not make me puke. Have you read my perl
  80 > code? :-P
  81 >
  82 > Note that your XXX is right. It would be a security hole to not validate
  83 > `$key`, as anyone with websetup access could cause it to run arbitrary
  84 > perl code.
  85 >
  86 > Well, except that websetup doesn't currently support configuring hashes
  87 > like used here. Which is a pity, but has led me to try to avoid using
  88 > such hashes in the setup file.
  89 >
  90 > Have you considered not defining the pagespec aliases in the setup file, but
  91 > instead as directives on pages in the wiki? Using pagestate could store
  92 > up the aliases that have been defined. It could however, be hard to get
  93 > the dependencies right; any page that uses a pagespec containing
  94 > an alias `foo` would need to somehow depend on the page where the alias
  95 > was defined. --[[Joey]]
  96
  97 Here's an example setup chunk:
  98
  99      pagespec_aliases:
 100        image: "*.png or *.jpg or *.jpeg or *.gif or *.ico"
 101        helper: "*.css or *.js"
 102        boring: "image() or helper()"
 103
 104 The above demonstrates self-referential dynamic pagespec aliases.  It doesn't work,
 105 however, to add ' or internal()' to `boring`, for some reason.
 106
 107 -- [[Jon]]
 108
 109 > Probably needs to be `or internal(*)` --[[Joey]]
 110
 111 > another useful pagespec alias for large maps:
 112
 113        basewiki: "sandbox or templates or templates/* or ikiwiki or ikiwiki/* or shortcuts or recentchanges or wikiicons/*"
 114
 115 > -- [[Jon]]
 116
 117 >> Useful indeed! --[[Joey]]