]> sipb.mit.edu Git - ikiwiki.git/blob - IkiWiki/Plugin/external.pm
memoization for injected RPC functions is a very, very good thing
[ikiwiki.git] / 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 use Memoize;
111
112 sub getvar ($$$) { #{{{
113         my $plugin=shift;
114         my $varname="IkiWiki::".shift;
115         my $key=shift;
116
117         no strict 'refs';
118         my $ret=$varname->{$key};
119         use strict 'refs';
120         return $ret;
121 } #}}}
122
123 sub setvar ($$$;@) { #{{{
124         my $plugin=shift;
125         my $varname="IkiWiki::".shift;
126         my $key=shift;
127
128         no strict 'refs';
129         my $ret=$varname->{$key}=@_;
130         use strict 'refs';
131         return $ret;
132 } #}}}
133
134 sub inject ($@) { #{{{
135         # Bind a given perl function name to a particular RPC request.
136         my $plugin=shift;
137         my %params=@_;
138
139         if (! exists $params{name} || ! exists $params{call}) {
140                 die "inject needs name and call parameters";
141         }
142         my $sub = sub {
143                 IkiWiki::Plugin::external::rpc_call($plugin, $params{call}, @_)
144         };
145         eval qq{*$params{name}=\$sub};
146         memoize($params{name}) if $params{memoize};
147         return 1;
148 } #}}}
149
150 sub hook ($@) { #{{{
151         # the call parameter is a function name to call, since XML RPC
152         # cannot pass a function reference
153         my $plugin=shift;
154         my %params=@_;
155
156         my $callback=$params{call};
157         delete $params{call};
158
159         IkiWiki::hook(%params, call => sub {
160                 IkiWiki::Plugin::external::rpc_call($plugin, $callback, @_)
161         });
162 } #}}}
163
164 sub pagespec_match ($@) { #{{{
165         # convert pagespec_match's return object into a XML RPC boolean
166         my $plugin=shift;
167
168         return RPC::XML::boolean->new(0 + IkiWiki::pagespec_march(@_));
169 } #}}}
170
171 1