Query planner and dumpqueryresults doc strings; dumpqueryresults improved

diff --git a/yarrg/web/dumpqueryresults b/yarrg/web/dumpqueryresults
index c653d81dea8a315bc6fbcc94bae986a55caeb6c7..8860ace69fa285e7cbde63beb399c75dd7050c7f 100644 (file)
--- a/yarrg/web/dumpqueryresults
+++ b/yarrg/web/dumpqueryresults
@@ -1,20 +1,101 @@
+<%doc>
+
+ This is part of the YARRG website.  YARRG is a tool and website
+ for assisting players of Yohoho Puzzle Pirates.
+
+ Copyright (C) 2009 Ian Jackson <ijackson@chiark.greenend.org.uk>
+ Copyright (C) 2009 Clare Boothby
+
+  YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later).
+  The YARRG website is covered by the GNU Affero GPL v3 or later, which
+   basically means that every installation of the website will let you
+   download the source.
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as
+ published by the Free Software Foundation, either version 3 of the
+ License, or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+ Yohoho and Puzzle Pirates are probably trademarks of Three Rings and
+ are used without permission.  This program is not endorsed or
+ sponsored by Three Rings.
+
+
+ This Mason component is helpful for debugging and developing.  It
+ outputs SQL query results as HTML tables.  You can either:
+    <& dumpqueryresults, sth = $executed_statement_handle &>
+ in which case it will consume the results of the statement and
+ print them unconditionally, or do the equivalent of:
+    <& dumpqueryresults:start, sth => $sth, [ qa => $qa ] &>
+    %  my $row;
+    %  while ($row= $sth->fetchrow_hashref) {
+    <& dumpqueryresults:row, sth => $sth, row => $row, [ qa => $qa ] &>
+    %       do something else with $row
+    %  }
+    <& dumpqueryresults:end, [ qa => $qa ] &>
+ where if you pass $qa, dumpqueryresults will check whether debug
+ is enabled and produce no output if it isn't.  NB you don't want
+ this approach if your loop body produces output because it'll be
+ interleaved with dumpqueryresults' table.
+
+</%doc>

 <%args>
 $sth
 </%args>
 <%args>
 $sth
 </%args>

+
+<%method start>
+<%args>
+$sth
+$qa => undef
+</%args>
+%      if (!$qa || $qa->{'debug'}) {

 <table frame=box rules=all>
 <tr>
 <table frame=box rules=all>
 <tr>

-% foreach my $field (@{ $sth->{NAME} }) {
+%              foreach my $field (@{ $sth->{NAME} }) {

 <th><% $field |h %>
 <th><% $field |h %>

-% }
+%              }

 </tr>
 </tr>

-% my @row;
-% while (@row=$sth->fetchrow_array) {
+%      }
+</%method>
+
+<%method row>
+<%args>
+$sth
+$row
+$qa => undef
+</%args>
+%      if (!$qa || $qa->{'debug'}) {

 <tr>
 <tr>

-% foreach my $cell (@row) {
+%              foreach my $field (@{ $sth->{NAME} }) {
+%                      my $cell= $row->{$field};

 <td>
 <% $cell |h %>
 </td>
 <td>
 <% $cell |h %>
 </td>

-% }
+%              }

 </tr>
 </tr>

-% }
+%      }
+</%method>
+
+<%method end>
+<%args>
+$qa => undef
+</%args>
+%      if (!$qa || $qa->{'debug'}) {

 </table>
 </table>

+%      }
+</%method>
+
+<& SELF:start, sth => $sth &>
+%      my $row;
+%      while ($row= $sth->fetchrow_hashref) {
+<& SELF:row, sth => $sth, row => $row &>
+%      }
+<& SELF:end &>

diff --git a/yarrg/web/routetrade b/yarrg/web/routetrade
index e154f2c6c2c683d434ae182fd33b390051f6aa87..407cc8c5e39b48bb28ac3a6466106e0c0c11afa6 100644 (file)
--- a/yarrg/web/routetrade
+++ b/yarrg/web/routetrade
@@ -1,3 +1,38 @@
+<%doc>
+
+ This is part of the YARRG website.  YARRG is a tool and website
+ for assisting players of Yohoho Puzzle Pirates.
+
+ Copyright (C) 2009 Ian Jackson <ijackson@chiark.greenend.org.uk>
+ Copyright (C) 2009 Clare Boothby
+
+  YARRG's client code etc. is covered by the ordinary GNU GPL (v3 or later).
+  The YARRG website is covered by the GNU Affero GPL v3 or later, which
+   basically means that every installation of the website will let you
+   download the source.
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as
+ published by the Free Software Foundation, either version 3 of the
+ License, or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+ Yohoho and Puzzle Pirates are probably trademarks of Three Rings and
+ are used without permission.  This program is not endorsed or
+ sponsored by Three Rings.
+
+
+ This Mason component is the core trade planner for a specific route.
+
+
+</%doc>

 <%args>
 $dbh
 @islandids
 <%args>
 $dbh
 @islandids