IkiWiki/Plugin/external.pm

   1 #!/usr/bin/perl
   2 # Support for external plugins written in other languages.
   3 # Communication via XML RPC a pipe.
   4 # See externaldemo for an example of a plugin that uses this.
   5 package IkiWiki::Plugin::external;
   6
   7 use warnings;
   8 use strict;
   9 use IkiWiki 2.00;
  10 use RPC::XML;
  11 use RPC::XML::Parser;
  12 use IPC::Open2;
  13 use IO::Handle;
  14
  15 my %plugins;
  16
  17 sub import { #{{{
  18         my $self=shift;
  19         my $plugin=shift;
  20         return unless defined $plugin;
  21
  22         my ($plugin_read, $plugin_write);
  23         my $pid = open2($plugin_read, $plugin_write, $plugin);
  24
  25         # open2 doesn't respect "use open ':utf8'"
  26         binmode($plugin_read, ':utf8');
  27         binmode($plugin_write, ':utf8');
  28
  29         $plugins{$plugin}={in => $plugin_read, out => $plugin_write, pid => $pid,
  30                 accum => ""};
  31
  32         rpc_call($plugins{$plugin}, "import");
  33 } #}}}
  34
  35 sub rpc_write ($$) { #{{{
  36         my $fh=shift;
  37         my $string=shift;
  38
  39         $fh->print($string."\n");
  40         $fh->flush;
  41 } #}}}
  42
  43 sub rpc_call ($$;@) { #{{{
  44         my $plugin=shift;
  45         my $command=shift;
  46
  47         # send the command
  48         my $req=RPC::XML::request->new($command, @_);
  49         rpc_write($plugin->{out}, $req->as_string);
  50
  51         # process incoming rpc until a result is available
  52         while ($_ = $plugin->{in}->getline) {
  53                 $plugin->{accum}.=$_;
  54                 while ($plugin->{accum} =~ /^\s*(<\?xml\s.*?<\/(?:methodCall|methodResponse)>)\n(.*)/s) {
  55                         $plugin->{accum}=$2;
  56                         my $r = RPC::XML::Parser->new->parse($1);
  57                         error("XML RPC parser failure: $r") unless ref $r;
  58                         if ($r->isa('RPC::XML::response')) {
  59                                 my $value=$r->value;
  60                                 if ($value->isa('RPC::XML::array')) {
  61                                         return @{$value->value};
  62                                 }
  63                                 elsif ($value->isa('RPC::XML::struct')) {
  64                                         return %{$value->value};
  65                                 }
  66                                 elsif ($value->isa('RPC::XML::fault')) {
  67                                         die $value->string;
  68                                 }
  69                                 else {
  70                                         return $value->value;
  71                                 }
  72                         }
  73
  74                         my $name=$r->name;
  75                         my @args=map { $_->value } @{$r->args};
  76
  77                         # When dispatching a function, first look in
  78                         # IkiWiki::RPC::XML. This allows overriding
  79                         # IkiWiki functions with RPC friendly versions.
  80                         my $ret;
  81                         if (exists $IkiWiki::RPC::XML::{$name}) {
  82                                 $ret=$IkiWiki::RPC::XML::{$name}($plugin, @args);
  83                         }
  84                         elsif (exists $IkiWiki::{$name}) {
  85                                 $ret=$IkiWiki::{$name}(@args);
  86                         }
  87                         else {
  88                                 error("XML RPC call error, unknown function: $name");
  89                         }
  90
  91                         my $string=eval { RPC::XML::response->new($ret)->as_string };
  92                         if ($@ && ref $ret) {
  93                                 # One common reason for serialisation to
  94                                 # fail is a complex return type that cannot
  95                                 # be represented as an XML RPC response.
  96                                 # Handle this case by just returning 1.
  97                                 $string=eval { RPC::XML::response->new(1)->as_string };
  98                         }
  99                         if ($@) {
 100                                 error("XML response serialisation failed: $@");
 101                         }
 102                         rpc_write($plugin->{out}, $string);
 103                 }
 104         }
 105
 106         return undef;
 107 } #}}}
 108
 109 package IkiWiki::RPC::XML;
 110
 111 sub getvar ($$$) { #{{{
 112         my $plugin=shift;
 113         my $varname="IkiWiki::".shift;
 114         my $key=shift;
 115
 116         no strict 'refs';
 117         my $ret=$varname->{$key};
 118         use strict 'refs';
 119         return $ret;
 120 } #}}}
 121
 122 sub setvar ($$$;@) { #{{{
 123         my $plugin=shift;
 124         my $varname="IkiWiki::".shift;
 125         my $key=shift;
 126
 127         no strict 'refs';
 128         my $ret=$varname->{$key}=@_;
 129         use strict 'refs';
 130         return $ret;
 131 } #}}}
 132
 133 sub inject ($@) { #{{{
 134         # Bind a given perl function name to a particular RPC request.
 135         my $plugin=shift;
 136         my %params=@_;
 137
 138         if (! exists $params{name} || ! exists $params{call}) {
 139                 die "inject needs name and call parameters";
 140         }
 141         my $sub = sub {
 142                 IkiWiki::Plugin::external::rpc_call($plugin, $params{call}, @_)
 143         };
 144         eval qq{*$params{name}=\$sub};
 145         return 1;
 146 } #}}}
 147
 148 sub hook ($@) { #{{{
 149         # the call parameter is a function name to call, since XML RPC
 150         # cannot pass a function reference
 151         my $plugin=shift;
 152         my %params=@_;
 153
 154         my $callback=$params{call};
 155         delete $params{call};
 156
 157         IkiWiki::hook(%params, call => sub {
 158                 IkiWiki::Plugin::external::rpc_call($plugin, $callback, @_)
 159         });
 160 } #}}}
 161
 162 sub pagespec_match ($@) { #{{{
 163         # convert pagespec_match's return object into a XML RPC boolean
 164         my $plugin=shift;
 165
 166         return RPC::XML::boolean->new(0 + IkiWiki::pagespec_march(@_));
 167 } #}}}
 168
 169 1