make setargv take an array
[ikiwiki] / 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,
24                 IkiWiki::possibly_foolish_untaint($plugin));
25
26         # open2 doesn't respect "use open ':utf8'"
27         binmode($plugin_read, ':utf8');
28         binmode($plugin_write, ':utf8');
29
30         $plugins{$plugin}={in => $plugin_read, out => $plugin_write, pid => $pid,
31                 accum => ""};
32         $RPC::XML::ENCODING="utf-8";
33
34         rpc_call($plugins{$plugin}, "import");
35 } #}}}
36
37 sub rpc_write ($$) { #{{{
38         my $fh=shift;
39         my $string=shift;
40
41         $fh->print($string."\n");
42         $fh->flush;
43 } #}}}
44
45 sub rpc_call ($$;@) { #{{{
46         my $plugin=shift;
47         my $command=shift;
48
49         # send the command
50         my $req=RPC::XML::request->new($command, @_);
51         rpc_write($plugin->{out}, $req->as_string);
52
53         # process incoming rpc until a result is available
54         while ($_ = $plugin->{in}->getline) {
55                 $plugin->{accum}.=$_;
56                 while ($plugin->{accum} =~ /^\s*(<\?xml\s.*?<\/(?:methodCall|methodResponse)>)\n(.*)/s) {
57                         $plugin->{accum}=$2;
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')) {
61                                 my $value=$r->value;
62                                 if ($r->is_fault($value)) {
63                                         # throw the error as best we can
64                                         print STDERR $value->string."\n";
65                                         return "";
66                                 }
67                                 elsif ($value->isa('RPC::XML::array')) {
68                                         return @{$value->value};
69                                 }
70                                 elsif ($value->isa('RPC::XML::struct')) {
71                                         return %{$value->value};
72                                 }
73                                 else {
74                                         return $value->value;
75                                 }
76                         }
77
78                         my $name=$r->name;
79                         my @args=map { $_->value } @{$r->args};
80
81                         # When dispatching a function, first look in 
82                         # IkiWiki::RPC::XML. This allows overriding
83                         # IkiWiki functions with RPC friendly versions.
84                         my $ret;
85                         if (exists $IkiWiki::RPC::XML::{$name}) {
86                                 $ret=$IkiWiki::RPC::XML::{$name}($plugin, @args);
87                         }
88                         elsif (exists $IkiWiki::{$name}) {
89                                 $ret=$IkiWiki::{$name}(@args);
90                         }
91                         else {
92                                 error("XML RPC call error, unknown function: $name");
93                         }
94
95                         my $string=eval { RPC::XML::response->new($ret)->as_string };
96                         if ($@ && ref $ret) {
97                                 # One common reason for serialisation to
98                                 # fail is a complex return type that cannot
99                                 # be represented as an XML RPC response.
100                                 # Handle this case by just returning 1.
101                                 $string=eval { RPC::XML::response->new(1)->as_string };
102                         }
103                         if ($@) {
104                                 error("XML response serialisation failed: $@");
105                         }
106                         rpc_write($plugin->{out}, $string);
107                 }
108         }
109
110         return undef;
111 } #}}}
112
113 package IkiWiki::RPC::XML;
114 use Memoize;
115
116 sub getvar ($$$) { #{{{
117         my $plugin=shift;
118         my $varname="IkiWiki::".shift;
119         my $key=shift;
120
121         no strict 'refs';
122         my $ret=$varname->{$key};
123         use strict 'refs';
124         return $ret;
125 } #}}}
126
127 sub setvar ($$$;@) { #{{{
128         my $plugin=shift;
129         my $varname="IkiWiki::".shift;
130         my $key=shift;
131         my $value=shift;
132
133         no strict 'refs';
134         my $ret=$varname->{$key}=$value;
135         use strict 'refs';
136         return $ret;
137 } #}}}
138
139 sub getstate ($$$$) { #{{{
140         my $plugin=shift;
141         my $page=shift;
142         my $id=shift;
143         my $key=shift;
144
145         return $IkiWiki::pagestate{$page}{$id}{$key};
146 } #}}}
147
148 sub setstate ($$$$;@) { #{{{
149         my $plugin=shift;
150         my $page=shift;
151         my $id=shift;
152         my $key=shift;
153
154         return $IkiWiki::pagestate{$page}{$id}{$key}=@_;
155 } #}}}
156
157 sub getargv ($) { #{{{
158         my $plugin=shift;
159
160         return \@ARGV;
161 } #}}}
162
163 sub setargv ($@) { #{{{
164         my $plugin=shift;
165         my $array=shift;
166
167         @ARGV=@$array;
168 } #}}}
169
170 sub inject ($@) { #{{{
171         # Bind a given perl function name to a particular RPC request.
172         my $plugin=shift;
173         my %params=@_;
174
175         if (! exists $params{name} || ! exists $params{call}) {
176                 die "inject needs name and call parameters";
177         }
178         my $sub = sub {
179                 IkiWiki::Plugin::external::rpc_call($plugin, $params{call}, @_)
180         };
181         eval qq{*$params{name}=\$sub};
182         memoize($params{name}) if $params{memoize};
183         return 1;
184 } #}}}
185
186 sub hook ($@) { #{{{
187         # the call parameter is a function name to call, since XML RPC
188         # cannot pass a function reference
189         my $plugin=shift;
190         my %params=@_;
191
192         my $callback=$params{call};
193         delete $params{call};
194
195         IkiWiki::hook(%params, call => sub {
196                 my $ret=IkiWiki::Plugin::external::rpc_call($plugin, $callback, @_);
197                 return $ret;
198         });
199 } #}}}
200
201 sub pagespec_match ($@) { #{{{
202         # convert pagespec_match's return object into a XML RPC boolean
203         my $plugin=shift;
204
205         return RPC::XML::boolean->new(0 + IkiWiki::pagespec_march(@_));
206 } #}}}
207
208 1