2 # Support for external plugins written in other languages.
3 # Communication via XML RPC to a pipe.
4 # See externaldemo for an example of a plugin that uses this.
5 package IkiWiki::Plugin::external;
20 return unless defined $plugin;
22 my ($plugin_read, $plugin_write);
23 my $pid = open2($plugin_read, $plugin_write,
24 IkiWiki::possibly_foolish_untaint($plugin));
26 # open2 doesn't respect "use open ':utf8'"
27 binmode($plugin_read, ':utf8');
28 binmode($plugin_write, ':utf8');
30 $plugins{$plugin}={in => $plugin_read, out => $plugin_write, pid => $pid,
32 $RPC::XML::ENCODING="utf-8";
34 rpc_call($plugins{$plugin}, "import");
37 sub rpc_write ($$) { #{{{
41 $fh->print($string."\n");
45 sub rpc_call ($$;@) { #{{{
50 my $req=RPC::XML::request->new($command, @_);
51 rpc_write($plugin->{out}, $req->as_string);
53 # process incoming rpc until a result is available
54 while ($_ = $plugin->{in}->getline) {
56 while ($plugin->{accum} =~ /^\s*(<\?xml\s.*?<\/(?:methodCall|methodResponse)>)\n(.*)/s) {
58 my $r = RPC::XML::Parser->new->parse($1);
59 error("XML RPC parser failure: $r") unless ref $r;
60 if ($r->isa('RPC::XML::response')) {
62 if ($r->is_fault($value)) {
63 # throw the error as best we can
64 print STDERR $value->string."\n";
67 elsif ($value->isa('RPC::XML::array')) {
68 return @{$value->value};
70 elsif ($value->isa('RPC::XML::struct')) {
71 my %hash=%{$value->value};
73 # XML-RPC v1 does not allow for
74 # nil/null/None/undef values to be
75 # transmitted, so until
76 # XML::RPC::Parser honours v2
77 # (<nil/>), external plugins send
78 # a hash with one key "null" pointing
80 if (exists $hash{null} &&
82 int(keys(%hash)) == 1) {
94 my @args=map { $_->value } @{$r->args};
96 # When dispatching a function, first look in
97 # IkiWiki::RPC::XML. This allows overriding
98 # IkiWiki functions with RPC friendly versions.
100 if (exists $IkiWiki::RPC::XML::{$name}) {
101 $ret=$IkiWiki::RPC::XML::{$name}($plugin, @args);
103 elsif (exists $IkiWiki::{$name}) {
104 $ret=$IkiWiki::{$name}(@args);
107 error("XML RPC call error, unknown function: $name");
110 # XML-RPC v1 does not allow for nil/null/None/undef
111 # values to be transmitted, so until XML::RPC::Parser
112 # honours v2 (<nil/>), send a hash with one key "null"
113 # pointing to an empty string.
114 if (! defined $ret) {
118 my $string=eval { RPC::XML::response->new($ret)->as_string };
119 if ($@ && ref $ret) {
120 # One common reason for serialisation to
121 # fail is a complex return type that cannot
122 # be represented as an XML RPC response.
123 # Handle this case by just returning 1.
124 $string=eval { RPC::XML::response->new(1)->as_string };
127 error("XML response serialisation failed: $@");
129 rpc_write($plugin->{out}, $string);
136 package IkiWiki::RPC::XML;
139 sub getvar ($$$) { #{{{
141 my $varname="IkiWiki::".shift;
145 my $ret=$varname->{$key};
150 sub setvar ($$$;@) { #{{{
152 my $varname="IkiWiki::".shift;
157 my $ret=$varname->{$key}=$value;
162 sub getstate ($$$$) { #{{{
168 return $IkiWiki::pagestate{$page}{$id}{$key};
171 sub setstate ($$$$;@) { #{{{
178 return $IkiWiki::pagestate{$page}{$id}{$key}=$value;
181 sub getargv ($) { #{{{
187 sub setargv ($@) { #{{{
194 sub inject ($@) { #{{{
195 # Bind a given perl function name to a particular RPC request.
199 if (! exists $params{name} || ! exists $params{call}) {
200 die "inject needs name and call parameters";
203 IkiWiki::Plugin::external::rpc_call($plugin, $params{call}, @_)
205 eval qq{*$params{name}=\$sub};
206 memoize($params{name}) if $params{memoize};
211 # the call parameter is a function name to call, since XML RPC
212 # cannot pass a function reference
216 my $callback=$params{call};
217 delete $params{call};
219 IkiWiki::hook(%params, call => sub {
220 my $ret=IkiWiki::Plugin::external::rpc_call($plugin, $callback, @_);
225 sub pagespec_match ($@) { #{{{
226 # convert pagespec_match's return object into a XML RPC boolean
229 return RPC::XML::boolean->new(0 + IkiWiki::pagespec_march(@_));