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