From: Ian Jackson <ian@liberator.relativity.greenend.org.uk>
Date: Sat, 22 Aug 2009 13:21:04 +0000 (+0100)
Subject: Query planner and dumpqueryresults doc strings; dumpqueryresults improved
X-Git-Tag: 3.4~149
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~yarrgweb/git?p=ypp-sc-tools.db-test.git;a=commitdiff_plain;h=0a273ee819a0c5807ed112051da10c19dfa09f70

Query planner and dumpqueryresults doc strings; dumpqueryresults improved
---

diff --git a/yarrg/web/dumpqueryresults b/yarrg/web/dumpqueryresults
index c653d81..8860ace 100644
--- 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>
+
+<%method start>
+<%args>
+$sth
+$qa => undef
+</%args>
+%	if (!$qa || $qa->{'debug'}) {
 <table frame=box rules=all>
 <tr>
-% foreach my $field (@{ $sth->{NAME} }) {
+%		foreach my $field (@{ $sth->{NAME} }) {
 <th><% $field |h %>
-% }
+%		}
 </tr>
-% my @row;
-% while (@row=$sth->fetchrow_array) {
+%	}
+</%method>
+
+<%method row>
+<%args>
+$sth
+$row
+$qa => undef
+</%args>
+%	if (!$qa || $qa->{'debug'}) {
 <tr>
-% foreach my $cell (@row) {
+%		foreach my $field (@{ $sth->{NAME} }) {
+%			my $cell= $row->{$field};
 <td>
 <% $cell |h %>
 </td>
-% }
+%		}
 </tr>
-% }
+%	}
+</%method>
+
+<%method end>
+<%args>
+$qa => undef
+</%args>
+%	if (!$qa || $qa->{'debug'}) {
 </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 e154f2c..407cc8c 100644
--- 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