Enhance sqlite3_complete() so that it understands EXPLAIN QUERY PLAN.

Ticket #3828.  Testing is done in TH3. (CVS 6551)

FossilOrigin-Name: 3ac1b15f552fe005630e43a92fffa6a4abd6675d

2 files changed, 19 insertions, 9 deletions

diff --git a/src/complete.c b/src/complete.c
index 8e2dbc234..8993cfd45 100644
--- a/src/complete.c
+++ b/src/complete.c
@@ -16,7 +16,7 @@
 ** separating it out, the code will be automatically omitted from
 ** static links that do not use it.
 **
-** $Id: complete.c,v 1.7 2008/06/13 18:24:27 drh Exp $
+** $Id: complete.c,v 1.8 2009/04/28 04:46:42 drh Exp $
 */
 #include "sqliteInt.h"
 #ifndef SQLITE_OMIT_COMPLETE
@@ -112,7 +112,7 @@ int sqlite3_complete(const char *zSql){
      /* State:       **  SEMI  WS  OTHER EXPLAIN  CREATE  TEMP  TRIGGER  END  */
      /* 0   START: */ {    0,  0,     1,      2,      3,    1,       1,   1,  },
      /* 1  NORMAL: */ {    0,  1,     1,      1,      1,    1,       1,   1,  },
-     /* 2 EXPLAIN: */ {    0,  2,     1,      1,      3,    1,       1,   1,  },
+     /* 2 EXPLAIN: */ {    0,  2,     2,      1,      3,    1,       1,   1,  },
      /* 3  CREATE: */ {    0,  3,     1,      1,      1,    3,       4,   1,  },
      /* 4 TRIGGER: */ {    5,  4,     4,      4,      4,    4,       4,   4,  },
      /* 5    SEMI: */ {    5,  5,     4,      4,      4,    4,       4,   6,  },
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 50bc9757f..def85f7b1 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.444 2009/04/27 18:46:06 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.445 2009/04/28 04:46:42 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -1351,20 +1351,30 @@ void sqlite3_interrupt(sqlite3*);
 /*
 ** CAPI3REF: Determine If An SQL Statement Is Complete {H10510} <S70200>
 **
-** These routines are useful for command-line input to determine if the
-** currently entered text seems to form complete a SQL statement or
+** These routines are useful during command-line input to determine if the
+** currently entered text seems to form a complete SQL statement or
 ** if additional input is needed before sending the text into
-** SQLite for parsing.  These routines return true if the input string
+** SQLite for parsing.  These routines return 1 if the input string
 ** appears to be a complete SQL statement.  A statement is judged to be
-** complete if it ends with a semicolon token and is not a fragment of a
-** CREATE TRIGGER statement.  Semicolons that are embedded within
+** complete if it ends with a semicolon token and is not a prefix of a
+** well-formed CREATE TRIGGER statement.  Semicolons that are embedded within
 ** string literals or quoted identifier names or comments are not
 ** independent tokens (they are part of the token in which they are
-** embedded) and thus do not count as a statement terminator.
+** embedded) and thus do not count as a statement terminator.  Whitespace
+** and comments that follow the final semicolon are ignored.
+**
+** These routines return 0 if the statement is incomplete.  If a
+** memory allocation fails, then SQLITE_NOMEM is returned.
 **
 ** These routines do not parse the SQL statements thus
 ** will not detect syntactically incorrect SQL.
 **
+** If SQLite has not been initialized using [sqlite3_initialize()] prior 
+** to invoking sqlite3_complete16() then sqlite3_initialize() is invoked
+** automatically by sqlite3_complete16().  If that initialization fails,
+** then the return value from sqlite3_complete16() will be non-zero
+** regardless of whether or not the input SQL is complete.
+**
 ** Requirements: [H10511] [H10512]
 **
 ** The input to [sqlite3_complete()] must be a zero-terminated