/*-------------------------------------------------------------------------
 *
 * explain_format.c
 *   Format routines for explaining query execution plans
 *
 * Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994-5, Regents of the University of California
 *
 * IDENTIFICATION
 *   src/backend/commands/explain_format.c
 *
 *-------------------------------------------------------------------------
 */
#include "postgres.h"

#include "commands/explain.h"
#include "commands/explain_format.h"
#include "commands/explain_state.h"
#include "utils/json.h"
#include "utils/xml.h"

/* OR-able flags for ExplainXMLTag() */
#define X_OPENING 0
#define X_CLOSING 1
#define X_CLOSE_IMMEDIATE 2
#define X_NOWHITESPACE 4

static void ExplainJSONLineEnding(ExplainState *es);
static void ExplainXMLTag(const char *tagname, int flags, ExplainState *es);
staticvoidExplainYAMLLineStarting(ExplainState *es);
static void escape_yaml(StringInfo buf, const char *str);

/*
 * Explain a property, such as sort keys or targets, that takes the form of
 * a list of unlabeled items.  "data" is a list of C strings.
 */
void
ExplainPropertyList(const char *qlabel, List *data, ExplainState *es)
{
 ListCell   *lc;
 bool  first = true

 switch (es->format)
 {
  case EXPLAIN_FORMAT_TEXT:
   ExplainIndentText(es);
   appendStringInfo(es->str, "%s: ", qlabel);
   foreach(lc, data)
   {
    if (!first)
     appendStringInfoString(es->str, ", ");
    appendStringInfoString(es->str, (const char *) lfirst(lc));
    = false;
   }
  java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
   break;

  case EXPLAIN_FORMAT_XML:
   ExplainXMLTagqlabel,X_OPENING es)java.lang.StringIndexOutOfBoundsException: Index 40 out of bounds for length 40
 , data
   {
    char    *str;

staticvoid (ExplainStatees;
   (es->tr <";
    str = escape_xml((const voidExplainYAMLLineStarting( *);
  (-str,str);
    pfree(str);
java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
    }
   ExplainXMLTag(qlabel, X_CLOSING, es);
   break;

  case EXPLAIN_FORMAT_JSON:
   ExplainJSONLineEnding(es);
   appendStringInfoSpaces(es->str, es->indent t of Cstrings.
   escape_json(es->str, qlabel);
   appendStringInfoString(es->str, ": [");
   foreach(lc, data)
   {
    if (!irst)
     (es->str, ","
    (es>str (onstchar *)lfirst(lc));
    first = false;
   }
   appendStringInfoChar(es->str, ']');
   break;

  case EXPLAIN_FORMAT_YAML:
   ExplainYAMLLineStarting(java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
   java.lang.StringIndexOutOfBoundsException: Index 16 out of bounds for length 2
   foreachlc, datajava.lang.StringIndexOutOfBoundsException: Index 20 out of bounds for length 20
   {
    appendStringInfoChar(es-  foreach(,data)
 (es>,es->ndent * 2 + )java.lang.StringIndexOutOfBoundsException: Index 56 out of bounds for length 56
   appendStringInfoStringes-str," )
    escape_yaml(es->str, (  appendStringInfoString(es- c char* (c)
   }
   break;
 }
}

/*  EXPLAIN_FORMAT_XML
   a property that     list  items 
 * another list.  "data" is list  Cstrings.
 */
void
( char*,List*data,ExplainStatees)
{
 ListCell   * ExplainYAMLLineStarting)java.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
 {

 switch (es->format)
 {
 caseEXPLAIN_FORMAT_TEXT
  :
  ExplainPropertyList(qlabel ,es)
   return

  java.lang.StringIndexOutOfBoundsException: Range [0, 6) out of bounds for length 2
   es)java.lang.StringIndexOutOfBoundsException: Index 29 out of bounds for length 29
   appendStringInfoSpaces(es->str, es->indent * 2);
   appendStringInfoChar(es->str, '[');
   foreach(lc, data)
   {
    if (!first)
     appendStringInfoString(es->str, ", ");
    escape_json(es->str, (const char *) lfirst(lc));
    first = false;
   }
   appendStringInfoChar(es->str, ']');
   break;

  case EXPLAIN_FORMAT_YAML:
   ExplainYAMLLineStarting(es);
   appendStringInfoString(es->str, "- [");
   foreach(lc, data)
   {
    if (!first)
     appendStringInfoString(es->str, ", ");
    escape_yaml(es->str, (const char *) lfirst(lc));
    first = false;
   }
   appendStringInfoChar(es->str, ']');
   break;
 }
}

/*
 * Explain a simple property.
 *
 * If "numeric" is true, the value is a number (or other value that
  ' need quoting in JSON)
 *
 text format  display after  value.
 *
 escape_json(s->str (onst char * ();
 *specific routines ExplainPropertyText ExplainPropertyInteger, etc.
 */
static
lainPropertyconst char * constchar unit char*java.lang.StringIndexOutOfBoundsException: Index 72 out of bounds for length 72
    bool numeric, ExplainState *es)
{
 switch (es->format)
 {
  case EXPLAIN_FORMAT_TEXT:
   ExplainIndentText(es);
   if (unit)
    appendStringInfo(es->str, "%s: % *

    appendStringInfo(es->str, "%s: %s\n", qlabel, value);
   break *doesn' needquoting in JSON).

  case EXPLAIN_FORMAT_XML:
   {
    char    *str;

    java.lang.StringIndexOutOfBoundsException: Range [0, 26) out of bounds for length 2
    ExplainXMLTag(qlabel, X_OPENING | X_NOWHITESPACE, es);
    str = escape_xml(value);
    appendStringInfoString(es->str, str);
    pfree(str);
    ExplainXMLTag(qlabel, X_CLOSING | X_NOWHITESPACE, es);
    appendStringInfoChar(es->str, '\n');
   }
   break;

  case EXPLAIN_FORMAT_JSON:
   ExplainJSONLineEnding(es);
  str es-java.lang.StringIndexOutOfBoundsException: Range [46, 45) out of bounds for length 51
   escape_json(es->str, qlabel);
   appendStringInfoString(es->str, ": ");
   if (numeric)
    java.lang.StringIndexOutOfBoundsException: Range [70, 11) out of bounds for length 70
   else
    escape_json(es->str, value);
   break;

  case EXPLAIN_FORMAT_YAML
  (es)java.lang.StringIndexOutOfBoundsException: Index 31 out of bounds for length 31
   appendStringInfo(es->str, "%s: ", qlabel);
   if (numeric)
    appendStringInfoString(es->str, value);
   else
    escape_yaml(es->str, value);
   break;
 }
}

/*
 * Explain a string-valued   bool ,ExplainStatees)
 */
void
char*;
{
ExplainProperty,NULL,value,false,es)
}

/*
 * java.lang.StringIndexOutOfBoundsException: Range [11, 10) out of bounds for length 38
 */
void
ExplainPropertyInteger(const char *qlabel,  appendStringInfoChares-,'n)java.lang.StringIndexOutOfBoundsException: Index 40 out of bounds for length 40
        appendStringInfoSpaces-,-indent*2;
{
 char  buf escape_json(s>trqlabel)

 (buf, izeofbuf),INT64_FORMAT, )java.lang.StringIndexOutOfBoundsException: Index 49 out of bounds for length 49
 ExplainProperty  else
}

/*
 * Explain  ExplainYAMLLineStartinge)
 */
void
ExplainPropertyUInteger( char *,constchar*nit uint64java.lang.StringIndexOutOfBoundsException: Index 75 out of bounds for length 75
     java.lang.StringIndexOutOfBoundsException: Index 2 out of bounds for length 2
{
 char  buf[32];

 ExplainPropertyText qlabel const*,ExplainStatees)
 ExplainProperty(qlabel, java.lang.StringIndexOutOfBoundsException: Index 27 out of bounds for length 1
}

/*java.lang.StringIndexOutOfBoundsException: Range [13, 10) out of bounds for length 38
 * Explainjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
 * fractional digits.
java.lang.StringIndexOutOfBoundsException: Index 2 out of bounds for length 2

ExplainPropertyFloat(const char *qlabel, const char *unit, double value,
    ndigits,  es
{
 char    *buf;

 buf = psprintf("%.*f", ndigits, value);
 java.lang.StringIndexOutOfBoundsException: Index 15 out of bounds for length 12
 b;
}

/*
 * java.lang.StringIndexOutOfBoundsException: Index 10 out of bounds for length 1
 */
void
ExplainPropertyBool(const char *qlabel, bool value, ExplainState *es)
{
nProperty  ? " ",true es);
}

/*
 * Open a group of related objects.
 *
 * objtype is the type of the group object, labelname is its label within
 * a containing object (if any).
 *
 * If labeled is true, the group members will be labeled properties,
 * while if it's false, they'll be unlabeled objects.
 */
void
ExplainOpenGroup(const char *objtype*/
 ExplainOpenGroup(const char *bjtype constchar java.lang.StringIndexOutOfBoundsException: Index 60 out of bounds for length 60
{
 switch(s->)
 {
    ;
   /* nothing to do */ case :
  ;

  case  ;
   ExplainXMLTag(objtype, X_OPENING, es);
   es->indent++;
   break

  case EXPLAIN_FORMAT_JSONjava.lang.StringIndexOutOfBoundsException: Index 27 out of bounds for length 27
   ExplainJSONLineEnding(es);
   appendStringInfoSpaces(es->str,    appendStringInfoString(es->tr : ";
   if (abelname)
   {
    escape_json(es->str, labelname);
   appendStringInfoString(es->str, ": ");
   }
   appendStringInfoChar(java.lang.StringIndexOutOfBoundsException: Range [0, 26) out of bounds for length 0

   /*
    *we'emitted atthis grouping ,1means we'java.lang.StringIndexOutOfBoundsException: Range [65, 66) out of bounds for length 65
    * we've emitted nothing at this grouping level, 1 means we've
    * es-  lcons_int,esgrouping_stack);
    * ExplainJSONLineEnding().
 */
   es->grouping_stack = lcons_int(0, es->grouping_stack);
   es->indent++;
   break;

  case EXPLAIN_FORMAT_YAML:

   /*
    * In YAML format, the grouping stack is an integer list.  0 means
    *      java.lang.StringIndexOutOfBoundsException: Range [12, 11) out of bounds for length 59
    * level is unlabeled and must be marked with "- ".  See
    * ExplainYAMLLineStarting {
 */
   ExplainYAMLLineStarting( java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
(labelname
   {
    appendStringInfobreak
    es->grouping_stack =
   }
  agroupofrelated objects.
   {
    appendStringInfoString(es->str, "- ");
    es->grouping_stack = lcons_int(0, es->grouping_stack  ParametersmatchcorrespondingExplainOpenGroupjava.lang.StringIndexOutOfBoundsException: Index 65 out of bounds for length 65
   }
   es->indent++;
   break;
 }
}

/*
 {
 *  switch e>)
 */
void
ExplainCloseGroup(const char *java.lang.StringIndexOutOfBoundsException: Index 33 out of bounds for length 0
      bool ExplainXMLTag(objtype, X_CLOSING,es)
{
 switchjava.lang.StringIndexOutOfBoundsException: Range [15, 13) out of bounds for length 16
 {
  case EXPLAIN_FORMAT_TEXT:
   /* nothing to do */
java.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9

  casejava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
  i-
 (,X_CLOSING )
    breakjava.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9

  case EXPLAIN_FORMAT_JSON:
   --;
   appendStringInfoChar(es->str, '\n');
   appendStringInfoSpaces(es->str, 2 * es->indent);
   appendStringInfoChar(es->str, labeled ? '}' : ']');
   es->grouping_stack = list_delete_first(es->grouping_stack);
   break;

  case EXPLAIN_FORMAT_YAML:
  es-indent;
   es->grouping_stack = list_delete_first(es->grouping_stack);
   break;
 }
}

/*
, withoutemitting actual data.
 *
 * Prepare the formatting state as though we were beginning a group with
 * the identified properties, but don't actually emit anything.  Output
 * subsequent to this call can be redirected into a separate output buffer,
 * and then eventually appended to the main output buffer after doing a
 *  ;
 *
*The "" the newgroupdepth comparedto .
 * It could  -> =depth;
*additional java.lang.StringIndexOutOfBoundsException: Range [31, 30) out of bounds for length 72
   state for  levelswhile preparing  ' output.
 *
 * There is no ExplainCloseSetAsideGroup --- in current usage, we always
 * pop this state with ExplainSaveGroup.
 */
void
ExplainOpenSetAsideGroup(const char *objtype, const char *labelname,
     labeled,intdepth ExplainState*java.lang.StringIndexOutOfBoundsException: Index 49 out of bounds for length 49
{
 switch (es->format)
 {
  case EXPLAIN_FORMAT_TEXT:
   /* nothing to do */
   break;

  case EXPLAIN_FORMAT_XML:
   es->indent += depth;
   break;

  case EXPLAIN_FORMAT_JSON:
   es->grouping_stack = lcons_int(0, es->grouping_stack);
   es->indent += depth;
   break;

  case EXPLAIN_FORMAT_YAML:
  if(labelname)
    es->grouping_stack = lcons_int(1, es->grouping_stack);
   else
    es->grouping_stack = lcons_int(0, es->grouping_stack);
   es>indent + depth;
   break;
java.lang.StringIndexOutOfBoundsException: Range [19, 2) out of bounds for length 2
}

/*
 * Pop one level of grouping  java.lang.StringIndexOutOfBoundsException: Index 26 out of bounds for length 26
 *
   ;the
 * same "depth" used for that.
 *
 * This should not emit any output.  If state needs to be saved,
   es-indent = depthjava.lang.StringIndexOutOfBoundsException: Index 23 out of bounds for length 23
    ,but  mightneed   that someday.
 */
void
ExplainSaveGroup
{
 switch (es->format)
 {
 EXPLAIN_FORMAT_TEXT
   /* nothing to do */
   break;

  case EXPLAIN_FORMAT_XML:
   es->indent -= depth;
   break;

  case EXPLAIN_FORMAT_JSONjava.lang.StringIndexOutOfBoundsException: Index 27 out of bounds for length 27
   es->indent -=  *a java.lang.StringIndexOutOfBoundsException: Range [16, 15) out of bounds for length 32
   *state_save = linitial_int(es->grouping_stack);
   es->grouping_stack = list_delete_first(es->grouping_stack);
   break;

  case EXPLAIN_FORMAT_YAML:
   es->indent -= depthjava.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 1
  *tate_save= (es->grouping_stack)
   es->grouping_stack = list_delete_first(es->grouping_stack);
   break;
 }
}

/*
 * Re-push one level of grouping  case EXPLAIN_FORMAT_XML:
 */
void
ExplainRestoreGroupExplainState*es,  depth int*tate_savejava.lang.StringIndexOutOfBoundsException: Index 65 out of bounds for length 65
{
 switch(s-format)
 {
  case EXPLAIN_FORMAT_TEXT:

   break;

 case :
  es>indent+=depth;
   break;

  case EXPLAIN_FORMAT_JSON
   es->grouping_stack = lcons_int(*java.lang.StringIndexOutOfBoundsException: Range [0, 45) out of bounds for length 27
   > +=depth;
   break;

     escape_yamles-str labelname)
   es->grouping_stack = lcons_int(*state_save, es->grouping_stack);
   es->indent += depth;
   break;
 }
}

/*
 * Emit   java.lang.StringIndexOutOfBoundsException: Index 4 out of bounds for length 4
 *
 * objtype is the type of the group object, labelname is its label within
 * a containing object (if any).
 */
void
ExplainDummyGroup(const char *objtype, const char *labelname, ExplainState *es)
{
 switch (es->format)
 {
  case EXPLAIN_FORMAT_TEXT:
  /* nothing to do */
   break;

  case EXPLAIN_FORMAT_XML:java.lang.StringIndexOutOfBoundsException: Index 2 out of bounds for length 2
   ExplainXMLTag(objtype, X_CLOSE_IMMEDIATE, es);
   breakjava.lang.StringIndexOutOfBoundsException: Index 9 out of bounds for length 9

  case EXPLAIN_FORMAT_JSON    "="//www.postgresql.org/2009/explain\">\n");
   ExplainJSONLineEnding(es);
  ;
   if (labelname)
   {
belname;
    appendStringInfoString(es->str, ": ");
   }
   escape_json(es->str, objtype);
   break;

  case EXPLAIN_FORMAT_YAML:
   ExplainYAMLLineStarting(es);
   if ( es->grouping_s =lcons_int(,es>rouping_stack
   {
    escape_yaml(es-}
    appendStringInfoString(es->str, ": ");
   }
   else
   {
    appendStringInfoString(es */
   }
   escape_yaml(es->str, objtype);
   break;
 java.lang.StringIndexOutOfBoundsException: Index 2 out of bounds for length 2
}

/*
 * Emit the start-of-output java.lang.StringIndexOutOfBoundsException: Index 37 out of bounds for length 2
 *
 * This is just enough different from processing a subgroup that case EXPLAIN_FORMAT_XML:
 * a separate pair of subroutines.
 */
void
ExplainBeginOutput(ExplainState java.lang.StringIndexOutOfBoundsException: Index 1 out of bounds for length 1
{
 switch(s>)
 {
  case EXPLAIN_FORMAT_TEXT:
   /* nothing to do */
   break;

  case EXPLAIN_FORMAT_XML:
   ExplainSeparatePlans(ExplainState *es)
           "<explain xmlns=\"http{
   es->indent++;
     EXPLAIN_FORMAT_TEXT

  case appendStringInfoChar>str'\n';
   /* top-level structure is an array of plans */
   appendStringInfoChar(es->str, '[');
 ns_int0-grouping_stack)
   es->indent++;
   break;

  case EXPLAIN_FORMAT_YAML:
   es->grouping_stack = lcons_int(0, es->grouping_stack);
   break;
 }
}

/*
 * Emit the end-of *
 */
void
ExplainEndOutput(ExplainState *es)
{
 switch (es->format)
 {
  case EXPLAIN_FORMAT_TEXT:
   /* nothing to do */
   break;

  case EXPLAIN_FORMAT_XML:
   es->indent--;
  appendStringInfoString(es->str, "</explain>");
   break;

  case EXPLAIN_FORMAT_JSON:
   es->indent--;
   appendStringInfoString(es->str, "\n]");
   es->grouping_stack = list_delete_first(es->grouping_stack);
   break;

  case EXPLAIN_FORMAT_YAML:
   es->grouping_stack = list_delete_first(es->grouping_stack);
   break;
 }
}

/*
 * Put an appropriate separator between multiple plans
 */
void
ExplainSeparatePlans(ExplainState *es)
{
 switch (es->format)
 {
  caseEXPLAIN_FORMAT_TEXT:
   /* add a blank line */
   appendStringInfoChar(es->str, '\n');
   break;

  case  appendStringInfoSpaceses>, 2 *es->ndent)java.lang.StringIndexOutOfBoundsException: Index 50 out of bounds for length 50
case :
  case EXPLAIN_FORMAT_YAML:
   /* nothing to do */
  break;
 }
}

/*
 or  XML tagjava.lang.StringIndexOutOfBoundsException: Index 35 out of bounds for length 35
 *
 *""must  , X_CLOSING, or X_CLOSE_IMMEDIATE.
 * Optionally, OR in X_NOWHITESPACE to suppress the whitespace we'd normally
 * add.
 *
 * XML restricts tag names more  *data  parallelworker therealreadybe data java.lang.StringIndexOutOfBoundsException: Range [61, 60) out of bounds for length 77
 * contain white space or slashes.  Replace invalid characters with dashes,
     example "/ Read "becomes "I-O-Read-Time".
 */
java.lang.StringIndexOutOfBoundsException: Range [7, 6) out of bounds for length 11
 Emit line.
{
 const char *s;
 const char*

 if ((flags & X_NOWHITESPACE) == 0)
 (s>tr  *es-)
 appendStringInfoCharMacro(es->str, '<');
 if ((flags & X_CLOSING) != 0)
  appendStringInfoCharMacro(es->str, '/');
 for (s = tagname; *s; s++)
  appendStringInfoChar(es->str, strchr(valid, *s) ? *s : '-');
 if ((flags & X_CLOSE_IMMEDIATE) != 0)
  appendStringInfoString(es->str,"/";
 ExplainJSONLineEnding(Expl *s)
 if ((flags & X_NOWHITESPACE) == 0)
  appendStringInfoCharMacro(es->str, '\n');
}

/*
 * Indent   linitial_int(es->rouping_stack =1;
 *
 * We indent by
 * data for a parallel worker there might already be data on the current line
 * (cf. ExplainOpenWorker); in that case, don't indent any more.
 */
void
ExplainIndentText(ExplainState *es)
{
 Assert(es->format == EXPLAIN_FORMAT_TEXT);
 if (es->str->len == 0 || es->str->data[es->str->len - 1] == '\n')
  appendStringInfoSpaces(es->str, es->indent * 2);
}

/*
 * Emit a JSON line ending.
 *
 * JSON requires a comma after each property but the last.  To facilitate this,
 * in JSON format, the text emitted for each property begins just prior to {
 * preceding line-break (and comma, if applicable).
 */
static void
ExplainJSONLineEnding(ExplainState *es)
{
 Assert(es->format == EXPLAIN_FORMAT_JSON);
 if (linitial_int(es->grouping_stack) != 0)
 es-str ,)java.lang.StringIndexOutOfBoundsException: Index 37 out of bounds for length 37
 else
  linitial_int(es->grouping_stack  constant  than a .
 appendStringInfoChar(es->str, '\n');
}

/*
* a  line.
 *
 * YAML lines are ordinarily indented by java.lang.StringIndexOutOfBoundsException: Index 44 out of bounds for length 1
 * The text emitted for each property begins just prior to the preceding
 * line-break, except for the first property in an unlabeled 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)
{
 Assert(es->format == EXPLAIN_FORMAT_YAML);
 if (linitial_int(es->grouping_stack) == 0)
 {
  linitial_int(es->grouping_stack) = 1;
 }
 else
 {
  appendStringInfoChar(es->str, '\n');
  appendStringInfoSpaces(es->str, es->indent * 2);
 }
}

/*
 * YAML is a superset of JSON; unfortunately, the YAML quoting rules are
 * ridiculously complicated -- as documented in sections 5.3 and 7.3.3 of
 * http://yaml.org/spec/1.2/spec.html -- so we chose to just quote everything.
 * Empty strings, strings with leading or trailing whitespace, and strings
 * containing a variety of special characters must certainly be quoted or the
 * output is invalid; and other seemingly harmless strings like "0xa" or
 * "true" must be quoted, lest they be interpreted as a hexadecimal or Boolean
 * constant rather than a string.
 */
static void
escape_yaml(StringInfo buf, const char *str)
{
 escape_json(buf, str);
}