Several fixes for EXPLAIN (FORMAT YAML), plus one for EXPLAIN (FORMAT JSON).

ExplainSeparatePlans() was busted for both JSON and YAML output - the present
code is a holdover from the original version of my machine-readable explain
patch, which didn't have the grouping_stack machinery.  Also, fix an odd
distribution of labor between ExplainBeginGroup() and ExplainYAMLLineStarting()
when marking lists with "- ", with each providing one character.  This broke
the output format for multi-query statements.  Also, fix ExplainDummyGroup()
for the YAML output format.

Along the way, make the YAML format use escape_yaml() in situations where the
JSON format uses escape_json().  Right now, it doesn't matter because all the
values are known not to need escaping, but it seems safer this way.  Finally,
I added some comments to better explain what the YAML output format is doing.

Greg Sabino Mullane reported the issues with multi-query statements.
Analysis and remaining cleanups by me.

diff --git a/src/backend/commands/explain.c b/src/backend/commands/explain.c
index e63b8579d84ce340a708462c4513f6a1250d7e32..f4a6aa4e71584d045d74af87d2be0d47002025ef 100644 (file)
--- a/src/backend/commands/explain.c
+++ b/src/backend/commands/explain.c
@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1994-5, Regents of the University of California
  *
  * IDENTIFICATION
- *   $PostgreSQL: pgsql/src/backend/commands/explain.c,v 1.196 2009/12/15 04:57:47 rhaas Exp $
+ *   $PostgreSQL: pgsql/src/backend/commands/explain.c,v 1.197 2009/12/16 22:16:16 rhaas Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -1694,10 +1694,7 @@ ExplainProperty(const char *qlabel, const char *value, bool numeric,
        case EXPLAIN_FORMAT_YAML:
            ExplainYAMLLineStarting(es);
            appendStringInfo(es->str, "%s: ", qlabel);
-           if (numeric)
-               appendStringInfoString(es->str, value);
-           else
-               escape_yaml(es->str, value);
+           escape_yaml(es->str, value);
            break;
    }
 }
@@ -1785,15 +1782,23 @@ ExplainOpenGroup(const char *objtype, const char *labelname,
            break;
 
        case EXPLAIN_FORMAT_YAML:
+
+           /*
+            * In YAML format, the grouping stack is an integer list.  0 means
+            * we've emitted nothing at this grouping level AND this grouping
+            * level is unlabelled and must be marked with "- ".  See
+            * ExplainYAMLLineStarting().
+            */
            ExplainYAMLLineStarting(es);
            if (labelname)
            {
-               appendStringInfo(es->str, "%s:", labelname);
+               escape_yaml(es->str, labelname);
+               appendStringInfoChar(es->str, ':');
                es->grouping_stack = lcons_int(1, es->grouping_stack);
            }
            else
            {
-               appendStringInfoChar(es->str, '-');
+               appendStringInfoString(es->str, "- ");
                es->grouping_stack = lcons_int(0, es->grouping_stack);
            }
            es->indent++;
@@ -1868,8 +1873,15 @@ ExplainDummyGroup(const char *objtype, const char *labelname, ExplainState *es)
        case EXPLAIN_FORMAT_YAML:
            ExplainYAMLLineStarting(es);
            if (labelname)
-               appendStringInfo(es->str, "%s:", labelname);
-           appendStringInfoString(es->str, objtype);
+           {
+               escape_yaml(es->str, labelname);
+               appendStringInfoString(es->str, ": ");
+           }
+           else
+           {
+               appendStringInfoString(es->str, "- ");
+           }
+           escape_yaml(es->str, objtype);
            break;
    }
 }
@@ -1946,18 +1958,14 @@ ExplainSeparatePlans(ExplainState *es)
    switch (es->format)
    {
        case EXPLAIN_FORMAT_TEXT:
-       case EXPLAIN_FORMAT_YAML:
            /* add a blank line */
            appendStringInfoChar(es->str, '\n');
            break;
 
        case EXPLAIN_FORMAT_XML:
-           /* nothing to do */
-           break;
-
        case EXPLAIN_FORMAT_JSON:
-           /* must have a comma between array elements */
-           appendStringInfoChar(es->str, ',');
+       case EXPLAIN_FORMAT_YAML:
+           /* nothing to do */
            break;
    }
 }
@@ -2011,6 +2019,12 @@ ExplainJSONLineEnding(ExplainState *es)
 
 /*
  * Indent a YAML line.
+ *
+ * YAML lines are ordinarily indented by two spaces per indentation level.
+ * The text emitted for each property begins just prior to the preceding
+ * line-break, except for the first property in an unlabelled group, for which
+ * it begins immediately after the "- " that introduces the group.  The first
+ * property of the group appears on the same line as the opening "- ".
  */
 static void
 ExplainYAMLLineStarting(ExplainState *es)
@@ -2018,7 +2032,6 @@ ExplainYAMLLineStarting(ExplainState *es)
    Assert(es->format == EXPLAIN_FORMAT_YAML);
    if (linitial_int(es->grouping_stack) == 0)
    {
-       appendStringInfoChar(es->str, ' ');
        linitial_int(es->grouping_stack) = 1;
    }
    else
@@ -2074,7 +2087,8 @@ escape_json(StringInfo buf, const char *str)
 }
 
 /*
- * YAML is a superset of JSON: if we find quotable characters, we call escape_json
+ * YAML is a superset of JSON: if we find quotable characters, we call
+ * escape_json.  If not, we emit the property unquoted for better readability.
  */
 static void
 escape_yaml(StringInfo buf, const char *str)