SQLite

** This file contains code to implement the "tclshext" shell extension
** for use with the extensible "sqlite3" CLI shell. On *Nix, build thusly:
     tool/mkshellc.tcl ext/misc/tclshext.c.in > tclshext.c
     gcc -shared -fPIC -O2 -I. -Isrc -I/usr/include/tcl8.6 tclshext.c \
       -o tclshext.so -ltcl8.6
** Later TCL versions can be used if desired.
  "TCL scripting support is added with a registerScripting() call in the\n"
  "ShellExtensionAPI, per ScriptingSupport interface requirements. This\n"
  "support lasts until the scripting object destructor is called.\n"
*/
static const char * const zTclHelp =
  "This extension adds these features to the host shell:\n"
  " 1. TCL scripting support is added.\n"
  " 2. TCL commands are added: udb shdb now_interactive get_tcl_group ..\n"
  " 3. The .tcl and .unknown dot commands are added.\n"
  " 4. If built with Tk capability, the gui TCL command will be added if\n"
  "  this extension was loaded using the shell via: .load ... -shext -tk .\n"
  "  Any other arguments beyond -shext are in TCL's argv variable.\n"
  "Operation:\n"
  " Shell input groups beginning with \"..\" are treated as TCL input, in\n"
  " these ways: (1) When a bare \"..\" is entered, a TCL REPL loop is run\n"
  " until the end of input is seen; (2) When \"..D ...\" is entered, (where\n"
  " \"D\" is a dot-command name), the D dot command will be run in its normal\n"
  " fashion, but its arguments will be collected according to TCL parsing\n"
  " rules then expanded as usual for TCL commands; and (3) when \".. T ...\"\n"

/* Provide help for users of this scripting implementation. */
DERIVED_METHOD(const char *, help, ScriptSupport,TclSS, 1,( int more )){
  (void)(pThis);
  switch( more ){
  case 0:
    return "Provides TCL scripting support for SQLite extensible shell.\n";
  case 1: return zTclHelp;
  }
  return 0;
}

/* Not doing this yet. */
DERIVED_METHOD(int,  configure, ScriptSupport,TclSS,
               4,( ShellExState *pSES, char **pzErr,

  }else{
    Tcl_SetResult(interp, "too many arguments", TCL_STATIC);
    return TCL_ERROR;
  }
}

#ifndef SHELL_OMIT_TK
static int numEventLoops = 0;
static int inOuterLoop = 0;

static int exitThisTkGUI(void *pvSS, Tcl_Interp *interp,
                         int nArgs, const char *azArgs[]){
  if( numEventLoops==0 && !inOuterLoop ){
    int ec = 0;
    if( nArgs>=2 ){
      if( azArgs[1] && sscanf(azArgs[1], "%d", &ec)!=1 ){
        ec = 1;
        fprintf(stderr, "Exit: %d\n", ec);
      }else{
        const char *zA = (azArgs[1])? azArgs[1] : "null";
        fprintf(stderr, "Exit: \"%s\"\n", azArgs[1]);
      }
    }else{
      fprintf(stderr, "Exit without argument\n");
    }
    fprintf(stderr, "Exit: \"%s\"\n", azArgs[1]);
    // exit(ec);
  }
  --numEventLoops;
  return TCL_BREAK;
}

static void runTclEventLoop(void){
  int inOuter = inOuterLoop;
  int nmw = Tk_GetNumMainWindows();
  /* This runs without looking at stdin. So it cannot be a REPL, yet.
   * Unless user has created something for it to do, it does nothing. */
  /* Tk_MapWindow(Tk_MainWindow(interpKeep.pInterp)); */
  ++numEventLoops;
  inOuterLoop = 1;
  while( nmw  > 0 ) {
    Tcl_DoOneEvent(0);
    nmw = Tk_GetNumMainWindows();
    /* if( nmw==1 ){ */
    /*   Tk_UnmapWindow(Tk_MainWindow(interpKeep.pInterp)); */
    /*   nmw = Tk_GetNumMainWindows(); */
    /*   break; */
    /* } */
  }
  if( nmw==0 ){
    fprintf(stderr,
            "Tk application and its root window destroyed. Restarting Tk.\n");
    Tk_Init(interpKeep.pInterp);
  }
  --numEventLoops;
  inOuterLoop = inOuter;
}

static int runTkGUI(void *pvSS, Tcl_Interp *interp,
                    int nArgs, const char *azArgs[]){
  (void)(pvSS); /* ShellExState *psx = (ShellExState *)pvSS; */
  Tcl_SetMainLoop(runTclEventLoop);
  runTclEventLoop();
  return TCL_OK;
}
#endif

#define UNKNOWN_RENAME "::_original_unknown"

/* C implementation of TCL ::unknown to (maybe) delegate to dot commands */
static int unknownDotDelegate(void *pvSS, Tcl_Interp *interp,

      Tcl_Eval(interp, "rename unknown "UNKNOWN_RENAME);
      Tcl_CreateCommand(interp, "unknown", unknownDotDelegate, psx, 0);
      /* Define this proc so that ".." either gets to the TCL REPL loop
       * or does nothing (if already in it), as a user convenience. */
      Tcl_Eval(interp, "proc .. {} {}");
#ifndef SHELL_OMIT_TK
      if( ldTk ){
        /* Create a proc to launch GUI programs, in faint mimicry of wish. 
         *
         * Its first argument, pgmName is the name to be given to the GUI
         * program that may be launched, used for error reporting and to
         * become the value of the ::argv0 that it sees.
         *
         * Its second argument, pgmSetup, will be executed as a list (of
         * a command and its arguments) to setup the GUI program. It may
         * do anything necessary to prepare for the GUI program to be
         * run by running a Tk event loop. It may be an empty list, in
         * which case pgmName must name a list serving the same purpose.
         *
         * Subsequent arguments to this proc will be passed to the GUI
         * program in the ::argv/::argc variable pair it sees.
         *
         * If only two empty arguments are provided to this proc, (whether
         * as defaulted or explictly passed), the GUI event loop will be
         * run with whatever conditions have been setup prior to the call.
         * (This is perfectly legitimate; this "gui" proc provides a way
         * to package GUI preparation and separate it from GUI run.)
         *
         * It is the responsibility of whatever setup code is run, if any,
         * to leave Tk objects and variables set so that when a GUI event
         * loop is run, some useful GUI program runs and can terminate.
         *
         * Before running the setup code, a variable, ::isHost, is set 
         * true to possibly inform the setup code that it should avoid
         * exit and exec calls. Setup code which is designed for either
         * hosted or standalone use, when run with $::isHost!=0, may opt
         * to leave variables ::exitCode and ::resultValue set which are
         * taken to indicate pseudo-exit status and a string result to
         * be used for error reporting or possibly other purposes.
         *
         * If the above responsibilities cannot be met, setup code should
         * fail in some way so that its execution produces a TCL error or
         * follows the ::exitCode and ::resultValue convention. Otherwise,
         * annoying sqlite3 shell hangs or abrupt exits may result.
         */
        TCL_CSTR_LITERAL(const char * const zGui =){
          proc gui {{pgmName ""} {pgmSetup {}} args} {
            unset -nocomplain ::exitCode
            set ::tcl_interactive [now_interactive]
            set saveArgs [list $::argv0 $::argc $::argv]
            if {"$pgmName" ne ""} {
              set ::argv0 $pgmName
            } else {set ::argv0 "?"}
            set ::argv $args
            set ::argc [llength $args]
            if {[llength $pgmSetup] == 0 && $pgmName ne ""} {
              if { [catch {set ::programSetup [subst "\$$pgmName"]}] } {
                foreach {::argv0 ::argc ::argv} $saveArgs {}
                return -code 1 "Error: pgmSetup empty, and pgmName does not\
                   name a list that might be\n executed in\
                   its place. Consult tclshext doc on using the gui command."
              }
            } elseif {[llength $pgmSetup] == 0 && $pgmName eq ""} {
              unset -nocomplain ::programSetup
            } else {
              set ::programSetup $pgmSetup
            }
            if {[info exists ::programSetup] && [llength $::programSetup] > 0} {
              set rc [catch {uplevel #0 {
                {*}$::programSetup
              }} result options]
              if {$rc==1} {
                puts stderr "gui setup failed: $result"
                puts stderr [dict get $options -errorinfo]
              } elseif {[info exists ::exitCode] && $::exitCode!=0} {
                puts stderr "gui setup failed: $::resultValue"
              } else { run_gui_event_loop }
            } else {
              run_gui_event_loop
            }
            foreach {::argv0 ::argc ::argv} $saveArgs {}
          }
        };
        /* Create a command which nearly emuluates Tk_MainLoop(). It runs a
         * GUI event loop, so does not return until either: all Tk top level
         * windows are destroyed, which causes and error return, or the Tk
         * app has called the replacement exit routine described next. */
        Tcl_CreateCommand(interp, "run_gui_event_loop", runTkGUI, psx, 0);
        Tcl_Eval(interp, "rename exit process_exit");
        Tcl_CreateCommand(interp, "exit", exitThisTkGUI, psx, 0);
        Tcl_Eval(interp, zGui);
        Tcl_SetMainLoop(runTclEventLoop);
        zAppName = "tclshext_tk";
      }
#endif
      Tcl_SetVar2Ex(interp, "::argv0", NULL,
                    Tcl_NewStringObj(zAppName,-1), TCL_GLOBAL_ONLY);
      Tcl_SetVar2Ex(interp, "::argc", NULL,
                    Tcl_NewIntObj(tnarg), TCL_GLOBAL_ONLY);
      Tcl_SetVar2Ex(interp, "::argv", NULL, targv, TCL_GLOBAL_ONLY);
      Tcl_SetVar2Ex(interp, "::tcl_interactive", NULL,
                    Tcl_NewIntObj(pExtHelpers->nowInteractive(psx)),
                    TCL_GLOBAL_ONLY);
      Tcl_SetVar2Ex(interp, "::isHosted", NULL,
                    Tcl_NewIntObj(1), TCL_GLOBAL_ONLY);
      pShExtLink->eid = sqlite3_tclshext_init;
    }
    if( rc==SQLITE_OK ){
      pShExtLink->extensionDestruct = Tcl_TakeDown;
      pShExtLink->pvExtensionObject = &interpKeep;
    }else{
      Tcl_TakeDown(&interpKeep);

  /* shell event subscription list */
  int numSubscriptions;  /* Number of active entries in below list */
  struct EventSubscription {
    ExtensionId eid;
    void *pvUserData;
    ShellEventNotify eventHandler;
  } *pSubscriptions;     /* The current shell event subscriptions */
  u8 bDbDispatch;        /* Cache fact of dbShell dispatch table */
#endif

  ShellExState *pSXS;    /* Pointer to companion, exposed shell state */
} ShellInState;

/*
** Limit input nesting via .read or any other input redirect.
** It's not too expensive, so a generous allowance can be made.
*/
#define MAX_INPUT_NESTING 25

/*
** This procedure updates the bSafeMode flag after completion of any
** operation (meta-command, SQL submission, or script execution) that
** counts as one for which safe mode might be suspended.
** bSafeModeFuture has 3 states salient here:
** equal 0 => Safe mode is and will remain inactive.
** equal 1 => Safe mode is and will remain active.
** N > 1 => Safe mode is suspended for N-1 operations.
*/
static void updateSafeMode(ShellInState *psi){
  switch( psi->bSafeModeFuture ){

  if( (psi->flgProgress & SHELL_PROGRESS_QUIET)==0 ){
    raw_printf(psi->out, "Progress %u\n", psi->nProgress);
  }
  return 0;
}
#endif /* SQLITE_OMIT_PROGRESS_CALLBACK */

/* For debugging or experimentation, the shell DB can be made file-based. */
#ifndef SHELL_DB_FILE
# define SHELL_DB_STORE ":memory:"
#else
# define SHELL_DB_STORE SHELL_STRINGIFY(SHELL_DB_FILE)
#endif

#define SHELL_DISP_SCHEMA "main"
#define SHELL_DISP_TAB "ShellCommands"
#define SHELL_DISP_VIEW "ShellActiveCmds"

/*
** Ensure dbShell exists and return SQLITE_OK,
** or complain and return SQLITE_ERROR.
*/
static int ensure_shell_db(ShellExState *psx){
  if( psx->dbShell!=0 ) return SQLITE_OK;
  else{
    int rc = sqlite3_open(SHELL_DB_STORE, &psx->dbShell);
    if( rc!=SQLITE_OK ){
      utf8_printf(STD_ERR, "Shell DB open failure: %s\n", sqlite3_errstr(rc));
      return SQLITE_ERROR;
    }
#ifndef SQLITE_NOHAVE_SYSTEM
    sqlite3_create_function(psx->dbShell, "edit", 1,
                            SQLITE_UTF8, 0, editFunc, 0, 0);
    sqlite3_create_function(psx->dbShell, "edit", 2,
                            SQLITE_UTF8, 0, editFunc, 0, 0);
#endif
    return rc;
  }
}

/* Tell whether the above-created table exists, return true iff exists. */
static int dispatch_table_exists(sqlite3 *dbs){
  return sqlite3_table_column_metadata
    (dbs, SHELL_DISP_SCHEMA, SHELL_DISP_TAB, 0, 0, 0, 0, 0, 0)==SQLITE_OK;
}

static int ensure_dispatch_table(ShellExState *psx){
  int rc = ensure_shell_db(psx);
  if( rc==SQLITE_OK ){
    char *zErr = 0;
    int rc1, rc2;
    if( dispatch_table_exists(psx->dbShell) ) return rc;
    /* Create the dispatch table and view on it. */
#ifdef SHELL_DB_FILE
    sqlite3_exec(psx->dbShell, "DROP TABLE IF EXISTS "SHELL_DISP_TAB, 0,0,0);
    sqlite3_exec(psx->dbShell, "DROP VIEW IF EXISTS "SHELL_DISP_VIEW, 0,0,0);
#endif
    rc1 = sqlite3_exec(psx->dbShell, "CREATE TABLE "SHELL_DISP_TAB"("
                       "name TEXT, extIx INT, cmdIx INT,"
                       "PRIMARY KEY(extIx,cmdIx)) WITHOUT ROWID", 0, 0, &zErr);
    rc2 = sqlite3_exec(psx->dbShell,
                       "CREATE VIEW "SHELL_DISP_VIEW
                       " AS SELECT s.name AS name,"
                       " max(s.extIx) AS extIx, s.cmdIx AS cmdIx"
                       " FROM "SHELL_DISP_TAB" s GROUP BY name",
                       0, 0, &zErr);
    if( rc1!=SQLITE_OK || rc2!=SQLITE_OK || zErr!=0 ){
      utf8_printf(STD_ERR, "Shell DB init failure, %s\n", zErr? zErr : "?");
      rc = SQLITE_ERROR;
    }else rc = SQLITE_OK;
    sqlite3_free(zErr);
  }
  return rc;
}

/*
** Skip over whitespace, returning remainder.
*/
static const char *skipWhite( const char *z ){
  while( IsSpace(*z) ) ++z;
  return z;
}

  char c = *zName;
  switch( c ){
  case '$': case ':': case '@': case '?': return PTU_Binding;
  default: return isalpha(c)? PTU_Script : PTU_Nil;
  }
}

#ifndef SQLITE_NOHAVE_SYSTEM
/* Possibly using a -editor=X argument and env-var VISUAL, attempt
 * to get the zEditor shell state member set iff not already set.
 * If there is no such argument, the env-var is retrieved if set.
 * If the argument is -editor=X or --editor=X, use that and leave
 * the zEditor member set accordingly. Returns are:
 * 0 => editor set, zEd was not the -editor option
 * 1 => editor set, zEd consumed as -editor option
 * -1 => editor not set, and error/advice message issued.
 *
 * This implements an undocumented fall-back for the .vars and
 * .parameters edit subcommands, so that users need not restart
 * a shell session to get an editor specified upon need for it. */
int attempt_editor_set(ShellInState *psi, char *zDot, const char *zEd){
  if( psi->zEditor==0 ){
    const char *zE = getenv("VISUAL");
    if( zE!=0 ) psi->zEditor = smprintf("%s", zE);
  }
  if( zEd && zEd[0]=='-' ){
    zEd += 1 + (zEd[1]=='-');
    if( strncmp(zEd,"editor=",7)==0 ){
      sqlite3_free(psi->zEditor);
      /* Accept an initial -editor=? option. */
      psi->zEditor = smprintf("%s", zEd+7);
      return 1;
    }
  }
  if( psi->zEditor==0 ){
    utf8_printf(STD_ERR,
                "Either set env-var VISUAL to name an"
                " editor and restart, or rerun\n "
                ".%s edit with an initial edit option,"
                " --editor=EDITOR_COMMAND .\n", zDot);
    return -1;
  }
  return 0;
}
#endif

/* The table kept for user DBs if .parameter command is used usefully. */
#define PARAM_TABLE_NAME "sqlite_parameters"
#define PARAM_TABLE_SCHEMA "temp"
#define PARAM_TABLE_SNAME PARAM_TABLE_SCHEMA"."PARAM_TABLE_NAME

/* The table kept for the shell DB if .vars command is used usefully. */
#define SHVAR_TABLE_NAME "sqlite_variables"
#define SHVAR_TABLE_SCHEMA "main"
#define SHVAR_TABLE_SNAME SHVAR_TABLE_SCHEMA"."SHVAR_TABLE_NAME

#ifndef SH_KV_STORE_NAME
/* Name for table keeping user's saved parameters */
# define SH_KV_STORE_NAME "SQLiteShell_KeyValuePairs"
#endif
#ifndef SH_KV_STORE_SCHEMA
/* Schema name used to attach saved parameters DB during load/save */
# define SH_KV_STORE_SCHEMA "SQLiteShell"
#endif
#define SH_KV_STORE_SNAME SH_KV_STORE_SCHEMA"."SH_KV_STORE_NAME

/* Create the TEMP table used to store parameter bindings */
static void param_table_init(sqlite3 *db){
  DbProtectState dps = allow_sys_schema_change(db);
  sqlite3_exec(db,
    "CREATE TABLE IF NOT EXISTS "PARAM_TABLE_SNAME"(\n"
    "  key TEXT PRIMARY KEY,\n"
    "  value,\n"
    "  uses INT DEFAULT (0)" /* aka PTU_Binding */
    ") WITHOUT ROWID;",
    0, 0, 0);
  restore_sys_schema_protection( db, &dps );
}

/* Tell whether the above-created table exists, return true iff exists. */
static int param_table_exists( sqlite3 *db ){
  return sqlite3_table_column_metadata
    (db, PARAM_TABLE_SCHEMA, PARAM_TABLE_NAME, 0, 0, 0, 0, 0, 0)==SQLITE_OK;
}

/* Create the shell DB table used to store shell variables or scripts */
static int shvars_table_init(sqlite3 *db){
  DbProtectState dps = allow_sys_schema_change(db);
  int rc = sqlite3_exec(db,
    "CREATE TABLE IF NOT EXISTS "SHVAR_TABLE_SNAME"(\n"
    "  key TEXT PRIMARY KEY,\n"
    "  value,\n"
    "  uses INT DEFAULT (0)" /* aka PTU_Binding */
    ") WITHOUT ROWID;",
    0, 0, 0);
  restore_sys_schema_protection( db, &dps );
  return rc!=SQLITE_OK;
}

/* Tell whether the above-created table exists, return true iff exists. */
static int shvars_table_exists( sqlite3 *db ){
  return sqlite3_table_column_metadata
    (db, SHVAR_TABLE_SCHEMA, SHVAR_TABLE_NAME, 0, 0, 0, 0, 0, 0)==SQLITE_OK;
}

/* Make shell vars table exist. */
static int ensure_shvars_table(sqlite3 *dbs){
  if( shvars_table_exists(dbs) ) return SQLITE_OK;
  else return shvars_table_init(dbs);
}

/*
** Bind parameters on a prepared statement.
**
** Parameter bindings are taken from a TEMP table of the form:
**
**    CREATE TEMP TABLE
**    sqlite_parameters(key TEXT PRIMARY KEY, value, uses INT)

/* Register a meta-command, to be called during extension load/init. */
static int register_meta_command(ShellExState *p,
                                 ExtensionId eid, MetaCommand *pMC){
  ShellInState *psi = ISS(p);
  ShExtInfo *psei = pending_ext_info(psi);
  const char *zSql
    = "INSERT INTO "SHELL_DISP_TAB"(name, extIx, cmdIx) VALUES(?, ?, ?)";
  int ie = psi->ixExtPending;
  assert(psi->pShxLoaded!=0 && p->dbShell!=0);
  if( pMC==0 ) return SQLITE_ERROR;
  else{
    const char *zName = pMC->pMethods->name(pMC);
    sqlite3_stmt *pStmt;
    int nc = psei->numMetaCommands;

                             ExtensionId eid, ImportHandler *pIH){
  return SQLITE_ERROR;
}

static int register_scripting(ShellExState *p, ExtensionId eid,
                              ScriptSupport *pSS){
  ShellInState *psi = ISS(p);
  if( psi->scriptXid!=0 || psi->script!=0 ){
    /* Scripting support already provided. Only one provider is allowed. */
    return SQLITE_BUSY;
  }
  if( eid==0 || pSS==0 || psi->ixExtPending==0 ){
    /* Scripting addition allowed only when sqlite3_*_init() runs. */
    return SQLITE_MISUSE;
  }
  psi->script = pSS;
  psi->scriptXid = eid;
  return SQLITE_OK;
}

    break;
  default:
    pv = 0;
  }
  if( pv==0 ) sqlite3_result_null(context);
  else sqlite3_result_pointer(context, pv, SHELLEXT_API_POINTERS, 0);
}







/* Do the initialization needed for use of dbShell for command lookup
 * and dispatch and for I/O handler lookup and dispatch.
 */
static int begin_db_dispatch(ShellExState *psx){
  ShellInState *psi = ISS(psx);
  sqlite3_stmt *pStmt = 0;
  int ic, rc1, rc2;
  int rc = 0;
  char *zErr = 0;
  const char *zSql;
  ShExtInfo sei = {0};
  /* Consider: Store these dynamic arrays in the DB as indexed-into blobs. */
  assert(psx->dbShell==0 || (psi->numExtLoaded==0 && psi->pShxLoaded==0));
  rc = ensure_shell_db(psx);
  if( rc!=SQLITE_OK ){
    utf8_printf(STD_ERR, "Error: Shell DB uncreatable. Best to .quit soon.\n");
    return SQLITE_ERROR;
  }
  if( ensure_dispatch_table(psx)!=SQLITE_OK ) return 1;

  psi->pShxLoaded = (ShExtInfo *)sqlite3_malloc(2*sizeof(ShExtInfo));
  sei.ppMetaCommands
    = (MetaCommand **)sqlite3_malloc((numCommands+2)*sizeof(MetaCommand *));
  sei.ppExportHandlers
    = (ExportHandler **)sqlite3_malloc(2*sizeof(ExportHandler *));
  sei.ppImportHandlers
    = (ImportHandler **)sqlite3_malloc(2*sizeof(ImportHandler *));
  if( sei.ppMetaCommands==0||sei.ppExportHandlers==0||sei.ppImportHandlers==0
      || psi->pShxLoaded==0 ){
    shell_out_of_memory();
  }
  sei.numExportHandlers = 0;
  sei.numImportHandlers = 0;
  for( ic=0; ic<numCommands; ++ic ){
    sei.ppMetaCommands[ic] = builtInCommand(ic);
  }
  sei.numMetaCommands = ic;
  psi->pShxLoaded[psi->numExtLoaded++] = sei;


















  zSql = "INSERT INTO "SHELL_DISP_TAB"(name, extIx, cmdIx) VALUES(?, 0, ?)";
  rc1 = sqlite3_prepare_v2(psx->dbShell, zSql, -1, &pStmt, 0);
  rc2 = sqlite3_exec(psx->dbShell, "BEGIN TRANSACTION", 0, 0, &zErr);
  if( rc1!=SQLITE_OK || rc2!=SQLITE_OK ) return 1;
  assert(sei.numMetaCommands>0);
  for( ic=0; ic<sei.numMetaCommands; ++ic ){
    MetaCommand *pmc = sei.ppMetaCommands[ic];
    const char *zName = pmc->pMethods->name(pmc);
    sqlite3_reset(pStmt);
    sqlite3_bind_text(pStmt, 1, zName, -1, 0);
    sqlite3_bind_int(pStmt, 2, ic);
    rc = sqlite3_step(pStmt);
    if( rc!=SQLITE_DONE ){
      sqlite3_exec(psx->dbShell, "ABORT", 0, 0, 0);
      break;
    }
  }
  sqlite3_finalize(pStmt);
  if( rc!=SQLITE_DONE ) return 1;
  rc = sqlite3_exec(psx->dbShell, "COMMIT", 0, 0, &zErr);
  sqlite3_enable_load_extension(psx->dbShell, 1);
  sqlite3_free(zErr);
  psi->bDbDispatch = 1;

  return SQLITE_OK;
}

/* Call one loaded extension's destructors, in reverse order
 * of their objects' creation, then free the tracking dyna-arrays.
 */
static void free_one_shext_tracking(ShExtInfo *psei){

  ShellInState *psi = ISS(psx);
  /* save script support state for possible fallback if load fails */
  ScriptSupport *pssSave = psi->script;
  ExtensionId ssiSave = psi->scriptXid;
  int rc;

  if( pzErr ) *pzErr = 0;
  if( psx->dbShell==0 || ISS(psx)->numExtLoaded==0 ){
    rc = begin_db_dispatch(psx);
    if( rc!=SQLITE_OK ) return rc;
    assert(ISS(psx)->numExtLoaded==1 && psx->dbShell!=0);
  }
  psi->ixExtPending = psi->numExtLoaded;
  sqlite3_create_function(psx->dbShell, "shext_pointer", 1,
                          SQLITE_DIRECTONLY|SQLITE_UTF8,

DISPATCHABLE_COMMAND( nullvalue ? 2 2 ){
  sqlite3_snprintf(sizeof(ISS(p)->nullValue), ISS(p)->nullValue, "%.*s",
                   (int)ArraySize(ISS(p)->nullValue)-1, azArg[1]);
  return DCR_Ok;
}

/* Helper functions for .parameter and .vars commands
 */

struct keyval_row { char * value; int uses; int hits; };

static int kv_find_callback(void *pData, int nc, char **pV, char **pC){
  assert(nc>=1);
  assert(strcmp(pC[0],"value")==0);
  struct keyval_row *pParam = (struct keyval_row *)pData;
  assert(pParam->value==0); /* key values are supposedly unique. */
  if( pParam->value!=0 ) sqlite3_free( pParam->value );
  pParam->value = smprintf("%s", pV[0]); /* source owned by statement */
  if( nc>1 ) pParam->uses = (int)integerValue(pV[1]);
  ++pParam->hits;
  return 0;
}

 * If it is an empty list, all parameters will be saved or loaded.
 * Otherwise, only the named parameters are transferred, if they exist.
 * It is not an error to specify a name that cannot be transferred
 * because it does not exist in the source table.
 *
 * Returns are SQLITE_OK for success, or other codes for failure.
 */
static int kv_xfr_table(sqlite3 *db, const char *zStoreDbName,
                        int bSaveNotLoad, ParamTableUse ptu,
                        const char *azNames[], int nNames){
  int rc = 0;
  char *zSql = 0; /* to be sqlite3_free()'ed */
  sqlite3_str *sbCopy = 0;
  const char *zHere = 0;
  const char *zThere = SH_KV_STORE_SNAME;
  const char *zTo;
  const char *zFrom;
  sqlite3 *dbStore = 0;
  int openFlags = (bSaveNotLoad)
    ? SQLITE_OPEN_URI|SQLITE_OPEN_READWRITE|SQLITE_OPEN_CREATE
    : SQLITE_OPEN_READONLY;

  switch( ptu ){
  case PTU_Binding: zHere = PARAM_TABLE_SNAME; break;
  case PTU_Script:  zHere = SHVAR_TABLE_SNAME; break;
  default: assert(0); return 1;
  }
  zTo = (bSaveNotLoad)? zThere : zHere;
  zFrom = (bSaveNotLoad)? zHere : zThere;
  /* Ensure store DB can be opened and/or created appropriately. */
  rc = sqlite3_open_v2(zStoreDbName, &dbStore, openFlags, 0);
  if( rc!=SQLITE_OK ){
    utf8_printf(STD_ERR, "Error: Cannot %s key/value store DB %s\n",
                bSaveNotLoad? "open/create" : "read", zStoreDbName);
    return rc;
  }
  /* Ensure it has the kv store table, or handle its absence. */
  assert(dbStore!=0);
  if( sqlite3_table_column_metadata
      (dbStore, "main", SH_KV_STORE_NAME, 0, 0, 0, 0, 0, 0)!=SQLITE_OK ){
    if( !bSaveNotLoad ){
      utf8_printf(STD_ERR, "Error: No key/value pairs ever stored in DB %s\n",
                  zStoreDbName);
      rc = 1;
    }else{
      /* The saved parameters table is not there yet; create it. */
      const char *zCT =
        "CREATE TABLE IF NOT EXISTS "SH_KV_STORE_NAME"(\n"
        "  key TEXT PRIMARY KEY,\n"
        "  value,\n"
        "  uses INT\n"
        ") WITHOUT ROWID;";
      rc = sqlite3_exec(dbStore, zCT, 0, 0, 0);
      if( rc!=SQLITE_OK ){
        utf8_printf(STD_ERR, "Cannot create table %s. Nothing saved.", zThere);
      }
    }
  }
  sqlite3_close(dbStore);
  if( rc!=0 ) return rc;

  zSql = smprintf("ATTACH %Q AS %s;", zStoreDbName, SH_KV_STORE_SCHEMA);
  shell_check_oom(zSql);
  rc = sqlite3_exec(db, zSql, 0, 0, 0);
  sqlite3_free(zSql);
  if( rc!=SQLITE_OK ) return rc;

  sbCopy = sqlite3_str_new(db);
  sqlite3_str_appendf
      (sbCopy, "INSERT OR REPLACE INTO %s(key,value,uses)"
       "SELECT key, value, uses FROM %s WHERE key ", zTo, zFrom);
  append_in_clause(sbCopy, azNames, azNames+nNames);
  zSql = sqlite3_str_finish(sbCopy);
  shell_check_oom(zSql);
  rc = sqlite3_exec(db, zSql, 0, 0, 0);
  sqlite3_free(zSql);

  sqlite3_exec(db, "DETACH "SH_KV_STORE_SCHEMA";", 0, 0, 0);
  return rc;
}

/* Default locations of kv store DBs for .parameters and .vars save/load. */
static const char *zDefaultParamStore = "~/sqlite_params.sdb";
static const char *zDefaultVarStore = "~/sqlite_vars.sdb";

/* Possibly generate a derived path from input spec, with defaulting
 * and conversion of leading (or only) tilde as home directory.
 * The above-set default is used for zSpec NULL, "" or "~".
 * When return is 0, there is an error; what needs doing cannnot be done.
 * If the return is exactly the input, it must not be sqlite3_free()'ed.
 * If the return differs from the input, it must be sqlite3_free()'ed.
 */
  static const char *kv_store_path(const char *zSpec, ParamTableUse ptu){
  if( zSpec==0 || zSpec[0]==0 || strcmp(zSpec,"~")==0 ){
    const char *zDef;
    switch( ptu ){
    case PTU_Binding: zDef = zDefaultParamStore; break;
    case PTU_Script:  zDef = zDefaultVarStore; break;
    default: return 0;
    }
    return home_based_path(zDef);
  }else if ( zSpec[0]=='~' ){
    return home_based_path(zSpec);
  }
  return zSpec;
}

/* Load some or all kv pairs. Arguments are "load FILE ?NAMES?". */
static int kv_pairs_load(sqlite3 *db, ParamTableUse ptu,
                         const char *azArg[], int nArg){
  const char *zStore = kv_store_path((nArg>1)? azArg[1] : 0, ptu);
  if( zStore==0 ){
    utf8_printf(STD_ERR, "Cannot form parameter load path. Nothing loaded.\n");
    return DCR_Error;
  }else{
    const char **pzFirst = (nArg>2)? azArg+2 : 0;
    int nNames = (nArg>2)? nArg-2 : 0;
    int rc = kv_xfr_table(db, zStore, 0, ptu, pzFirst, nNames);
    if( nArg>1 && zStore!=azArg[1] ) sqlite3_free((void*)zStore);
    return rc;
  }
}

/* Save some or all parameters. Arguments are "save FILE ?NAMES?". */
static int kv_pairs_save(sqlite3 *db, ParamTableUse ptu,
                         const char *azArg[], int nArg){
  const char *zStore = kv_store_path((nArg>1)? azArg[1] : 0, ptu);
  if( zStore==0 ){
    utf8_printf(STD_ERR, "Cannot form parameter save path. Nothing saved.\n");
    return DCR_Error;
  }else{
    const char **pzFirst = (nArg>2)? azArg+2 : 0;
    int nNames = (nArg>2)? nArg-2 : 0;
    int rc = kv_xfr_table(db, zStore, 1, ptu, pzFirst, nNames);
    if( nArg>1 && zStore!=azArg[1] ) sqlite3_free((void*)zStore);
    return rc;
  }
}

#ifndef SQLITE_NOHAVE_SYSTEM
/*
 * Edit one named value in the parameters or shell variables table.
 * If it does not yet exist, create it. If eval is true, the value
 * is treated as a bare expression, otherwise it is a text value.
 * The "uses" argument sets the 3rd column in the selected table,
 * and serves to select which of the two tables is modified.
 */
static int edit_one_kvalue(sqlite3 *db, char *name, int eval,
                           ParamTableUse uses, const char * zEditor){
  struct keyval_row kvRow = {0,0,0};
  int rc;
  char * zVal = 0;
  const char *zTab = 0;
  char * zSql = 0;

  switch( uses ){
  case PTU_Script:  zTab = SHVAR_TABLE_SNAME; break;
  case PTU_Binding: zTab = PARAM_TABLE_SNAME; break;
  default: assert(0);
  }
  zSql = smprintf("SELECT value, uses FROM %s "
                  "WHERE key=%Q AND uses=%d", zTab, name, uses);
  shell_check_oom(zSql);
  sqlite3_exec(db, zSql, kv_find_callback, &kvRow, 0);
  sqlite3_free(zSql);
  assert(kvRow.hits<2);
  if( kvRow.hits==1 && kvRow.uses==uses){
    /* Editing an existing value of same kind. */
    sqlite3_free(kvRow.value);
    if( eval!=0 ){
      zSql = smprintf("SELECT edit(value, %Q) FROM %s "

                      "WHERE key=%Q AND uses=%d", zEditor, zTab, name, uses);
      shell_check_oom(zSql);
      zVal = db_text(db, zSql, 1);
      sqlite3_free(zSql);
      zSql = smprintf("UPDATE %s SET value=(SELECT %s) "

                      "WHERE key=%Q AND uses=%d", zTab, zVal, name, uses);
    }else{
      zSql = smprintf("UPDATE %s SET value=edit(value, %Q) WHERE"

                      " key=%Q AND uses=%d", zTab, zEditor, name, uses);
    }
  }else{
    /* Editing a new value of same kind. */
    assert(kvRow.value==0 || kvRow.uses!=uses);
    if( eval!=0 ){

      zSql = smprintf("SELECT edit('-- %q%s', %Q)", name, "\n", zEditor);
      zVal = db_text(db, zSql, 1);
      sqlite3_free(zSql);
      zSql = smprintf("INSERT INTO %s(key,value,uses)"

         " VALUES (%Q,(SELECT %s LIMIT 1),%d)",
         zTab, name, zVal, uses);
    }else{
      zSql = smprintf("INSERT INTO %s(key,value,uses)"

                      " VALUES (%Q,edit('-- %q;%s', %Q),%d)",
                      zTab, name, name, "\n", zEditor, uses);
    }
  }
  shell_check_oom(zSql);


  rc = sqlite3_exec(db, zSql, 0, 0, 0);
  sqlite3_free(zSql);
  sqlite3_free(zVal);
  return rc!=SQLITE_OK;
}
#endif

/* Space-join values in an argument list. *valLim is not included. */
char *values_join( char **valBeg, char **valLim ){
  char *z = 0;
  const char *zSep = 0;
  while( valBeg < valLim ){
    z = smprintf("%z%s%s", z, zSep, *valBeg);
    zSep = " ";
    ++valBeg;
  }
  return z;
}
























static struct ParamSetOpts {
  const char cCast;
  const char *zTypename;
  int evalKind;
} param_set_opts[] = {
  /* { 'q', 0, 2 }, */

    ++zArg;
    if( zArg[0]=='-' ) ++zArg;
    if( zArg[0]!=0 && zArg[1]==0 ) return zArg[0];
  }
  return 0;
}

/* Most of .vars set
 * Return SQLITE_OK on success, else SQLITE_ERROR.
 */
static int shvar_set(sqlite3 *db, char *name, char **valBeg, char **valLim){
  int rc = SQLITE_OK;
  char *zValGlom = (valLim-valBeg>1)? values_join(valBeg, valLim) : 0;
  sqlite3_stmt *pStmtSet = 0;
  char *zValue = (zValGlom==0)? *valBeg : zValGlom;
  char *zSql
    = smprintf("REPLACE INTO "SHVAR_TABLE_SNAME"(key,value,uses)"
               "VALUES(%Q,%Q,%d);", name, zValue, PTU_Script);
  shell_check_oom(zSql);
  rc = sqlite3_prepare_v2(db, zSql, -1, &pStmtSet, 0);
  assert(rc==SQLITE_OK);
  sqlite3_free(zSql);
  rc = (SQLITE_DONE==sqlite3_step(pStmtSet))? SQLITE_OK : SQLITE_ERROR;
  sqlite3_finalize(pStmtSet);
  sqlite3_free(zValGlom);
  return rc;
}


/* Most of the .parameter set subcommand (per help text)
 */
static int param_set(sqlite3 *db, char cCast,
                     char *name, char **valBeg, char **valLim){

  char *zSql = 0;
  int rc = SQLITE_OK, retries = 0, needsEval = 1;
  char *zValGlom = (valLim-valBeg>1)? values_join(valBeg, valLim) : 0;
  sqlite3_stmt *pStmtSet = 0;
  const char *zCastTo = 0;
  char *zValue = (zValGlom==0)? *valBeg : zValGlom;
  if( cCast ){
    struct ParamSetOpts *pSO = param_set_opts;
    for(; pSO-param_set_opts < ArraySize(param_set_opts); ++pSO ){
      if( cCast==pSO->cCast ){
        zCastTo = pSO->zTypename;
        needsEval = pSO->evalKind > 0;
        break;
      }
    }
  }
  if( needsEval ){
    if( zCastTo!=0 ){
      zSql = smprintf
        ( "REPLACE INTO "PARAM_TABLE_SNAME"(key,value,uses)"
          " VALUES(%Q,CAST((%s) AS %s),%d);",
          name, zValue, zCastTo, PTU_Binding );
    }else{
      zSql = smprintf
        ( "REPLACE INTO "PARAM_TABLE_SNAME"(key,value,uses)"
          "VALUES(%Q,(%s),%d);", name, zValue, PTU_Binding );
    }
    shell_check_oom(zSql);
    rc = sqlite3_prepare_v2(db, zSql, -1, &pStmtSet, 0);
    sqlite3_free(zSql);
  }
  if( !needsEval || rc!=SQLITE_OK ){
    /* Reach here when value either requested to be cast to text, or must be. */
    sqlite3_finalize(pStmtSet);
    pStmtSet = 0;
    zSql = smprintf
      ( "REPLACE INTO "PARAM_TABLE_SNAME"(key,value,uses)"
        "VALUES(%Q,%Q,%d);", name, zValue, PTU_Binding );
    shell_check_oom(zSql);
    rc = sqlite3_prepare_v2(db, zSql, -1, &pStmtSet, 0);
    assert(rc==SQLITE_OK);
    sqlite3_free(zSql);
  }
  sqlite3_step(pStmtSet);
  sqlite3_finalize(pStmtSet);
  sqlite3_free(zValGlom);
  return rc;
}

/* list or ls subcommand for .parameter and .vars dot-commands */
static void list_pov_entries(ShellExState *psx, ParamTableUse ptu, u8 bShort,
                             char **pzArgs, int nArg){
  sqlite3_stmt *pStmt = 0;

  sqlite3_str *sbList;
  int len = 0, rc;
  char *zFromWhere = 0;
  char *zSql = 0;
  sqlite3 *db;
  const char *zTab;

  switch( ptu ){
  case PTU_Binding:
    db = DBX(psx);
    zTab = PARAM_TABLE_SNAME;
    break;
  case PTU_Script:
    db = psx->dbShell;
    zTab = SHVAR_TABLE_NAME;
    break;
  default: assert(0); return;
  }
  sbList = sqlite3_str_new(db);
  sqlite3_str_appendf(sbList, "FROM ");
  sqlite3_str_appendf(sbList, zTab);
  sqlite3_str_appendf(sbList, " WHERE (uses=?1) AND ");
  append_glob_terms(sbList, "key",
                    (const char **)pzArgs, (const char **)pzArgs+nArg);
  zFromWhere = sqlite3_str_finish(sbList);
  shell_check_oom(zFromWhere);
  zSql = smprintf("SELECT max(length(key)) %s", zFromWhere);
  shell_check_oom(zSql);
  rc = sqlite3_prepare_v2(db, zSql, -1, &pStmt, 0);

  ".parameter CMD ...       Manage SQL parameter bindings and scripts table",
  "   clear ?NAMES?           Erase all or only given named parameters",
#ifndef SQLITE_NOHAVE_SYSTEM
  "   edit ?OPT? NAME ...     Use edit() to create or alter parameter NAME",
  "      OPT may be -t to use edited value as text or -e to evaluate it.",
#endif
  "   init                    Initialize TEMP table for bindings and scripts",
  "   list ?PATTERNS?         List current DB parameters table binding values",
  "      Alternatively, to list just some or all names: ls ?PATTERNS?",
  "   load ?FILE? ?NAMES?     Load some or all named parameters from FILE",
  "      If FILE missing, empty or '~', it defaults to ~/sqlite_params.sdb",
  "   save ?FILE? ?NAMES?     Save some or all named parameters into FILE",
  "      If FILE missing, empty or '~', it defaults to ~/sqlite_params.sdb",
  "   set ?TOPT? NAME VALUE   Give SQL parameter NAME a value of VALUE",
  "      NAME must begin with one of $,:,@,? for bindings, VALUE is the space-",

  "      joined argument list. TOPT may be one of {-b -i -n -r -t} to cast the",
  "      effective value to BLOB, INT, NUMERIC, REAL or TEXT respectively.",
  "   unset ?NAMES?           Remove named parameter(s) from parameters table",
];
DISPATCHABLE_COMMAND( parameter 2 2 0 ){
  int rc = 0;
  open_db(p,0);
  sqlite3 *db = DBX(p);

      sqlite3_exec(db, zSql, 0, 0, 0);
      sqlite3_free(zSql);
    }
  }else
#ifndef SQLITE_NOHAVE_SYSTEM
  /* .parameter edit ?NAMES?
  ** Edit the named parameters. Any that do not exist are created.

  */
  if( strcmp(azArg[1],"edit")==0 ){
    ShellInState *psi = ISS(p);
    int ia = 2;
    int eval = 0;
    int edSet;

    if( !INSOURCE_IS_INTERACTIVE(psi->pInSource) ){
      utf8_printf(STD_ERR, "Error: "
                  ".parameter edit can only be used interactively.\n");
      return DCR_Error;
    }
    param_table_init(db);





    edSet = attempt_editor_set(psi, azArg[0], (nArg>2)? azArg[2] : 0 );













    if( edSet < 0 ) return DCR_Error;
    else ia += edSet;

    /* Future: Allow an option whereby new value can be evaluated
     * the way that .parameter set ... does.
     */
    while( ia < nArg ){
      ParamTableUse ptu;
      char *zA = azArg[ia];
      char cf = (zA[0]=='-')? zA[1] : 0;
      if( cf!=0 && zA[2]==0 ){
        ++ia;
        switch( cf ){
        case 'e': eval = 1; continue;
        case 't': eval = 0; continue;
        default:
          utf8_printf(STD_ERR, "Error: bad .parameter name: %s\n", zA);

          return DCR_Error;
        }
      }
      ptu = classify_param_name(zA);
      if( ptu!=PTU_Binding ){
        utf8_printf(STD_ERR, "Error: "
                    "%s cannot be a binding parameter name.\n", zA);
        return DCR_Error;
      }
      rc = edit_one_kvalue(db, zA, eval, ptu, psi->zEditor);
      ++ia;
      if( rc!=0 ) return DCR_Error;
    }
  }else
#endif

  /* .parameter init
  ** Make sure the TEMP table used to hold bind parameters exists.
  ** Create it if necessary.
  */
  if( nArg==2 && strcmp(azArg[1],"init")==0 ){
    param_table_init(db);
  }else

  /* .parameter list|ls
  ** List all or selected bind parameters.
  ** list displays names, values and uses.
  ** ls displays just the names.
  */
  if( nArg>=2 && ((strcmp(azArg[1],"list")==0)
                  || (strcmp(azArg[1],"ls")==0)) ){
    list_pov_entries(p, PTU_Binding, azArg[1][1]=='s', azArg+2, nArg-2);
  }else

  /* .parameter load
  ** Load all or named parameters from specified or default (DB) file.
  */
  if( strcmp(azArg[1],"load")==0 ){
    param_table_init(db);
    rc = kv_pairs_load(db, PTU_Binding, (const char **)azArg+1, nArg-1);
  }else

  /* .parameter save
  ** Save all or named parameters into specified or default (DB) file.
  */
  if( strcmp(azArg[1],"save")==0 ){
    rc = kv_pairs_save(db, PTU_Binding, (const char **)azArg+1, nArg-1);
  }else

  /* .parameter set NAME VALUE
  ** Set or reset a bind parameter.  NAME should be the full parameter
  ** name exactly as it appears in the query.  (ex: $abc, @def).  The
  ** VALUE can be in either SQL literal notation, or if not it will be
  ** understood to be a text string.
  */
  if( nArg>=4 && strcmp(azArg[1],"set")==0 ){
    char cCast = option_char(azArg[2]);
    int inv = 2 + (cCast != 0);
    ParamTableUse ptu = classify_param_name(azArg[inv]);
    if( ptu!=PTU_Binding ){
      utf8_printf(STD_ERR,
                  "Error: %s is not a usable parameter name.\n", azArg[inv]);
      rc = 1;
    }else{
      param_table_init(db);
      rc = param_set(db, cCast, azArg[inv], &azArg[inv+1], &azArg[nArg]);

      if( rc!=SQLITE_OK ){
        utf8_printf(STD_ERR, "Error: %s\n", sqlite3_errmsg(db));
        rc = 1;
      }
    }
  }else

  {  /* If no command name and arg count matches, show a syntax error */
    showHelp(ISS(p)->out, "parameter", p);
    return DCR_CmdErred;
  }

  return DCR_Ok | (rc!=0);
}

/*****************
 * The .print, .progress and .prompt commands
 */
CONDITION_COMMAND( progress !defined(SQLITE_OMIT_PROGRESS_CALLBACK) );
COLLECT_HELP_TEXT[

    }
  }else{
    goto teach_fail;
  }
  return DCR_Ok;
}

/*****************
 * The .vars command
 */
COLLECT_HELP_TEXT[
  ".vars ?OPTIONS? ...      Manipulate and display shell variables",
  "   clear ?NAMES?           Erase all or only given named variables",
#ifndef SQLITE_NOHAVE_SYSTEM
  "   edit ?-e? NAME        Use edit() to create or alter variable NAME",
  "      With a -e option, the edited value is evaluated as a SQL expression.",
#endif
  "   list ?PATTERNS?         List shell variables table values",
  "      Alternatively, to list just some or all names: ls ?PATTERNS?",
  "   load ?FILE? ?NAMES?     Load some or all named variables from FILE",
  "      If FILE missing, empty or '~', it defaults to ~/sqlite_vars.sdb",
  "   save ?FILE? ?NAMES?     Save some or all named variables into FILE",
  "      If FILE missing, empty or '~', it defaults to ~/sqlite_vars.sdb",
  "   set NAME VALUE          Give shell variable NAME a value of VALUE",
  "      NAME must begin with a letter to be executable by .x, Other leading",
  "      characters have special uses. VALUE is the space-joined arguments.",
  "   unset ?NAMES?           Remove named variables(s) from variables table",
];
DISPATCHABLE_COMMAND( vars 2 1 0 ){
  DotCmdRC rv = DCR_Ok;
  sqlite3 *dbs = p->dbShell;
  const char *zCmd = (nArg>1)? azArg[1] : "ls";
  int rc = 0;
  int ncCmd = strlen30(zCmd);

  if( *zCmd>'e' && ncCmd<2 ) return DCR_Ambiguous|1;
#define SUBCMD(scn) (strncmp(zCmd, scn, ncCmd)==0)

  /* This could be done lazily, but with more code. */
  if( (dbs && ensure_shvars_table(dbs)!=SQLITE_OK) ){
    return DCR_Error;
  }else{
    if( ensure_shell_db(p)!=SQLITE_OK ) return DCR_Error;
    dbs = p->dbShell;
    assert(dbs!=0);
    if( ensure_shvars_table(dbs)!=SQLITE_OK ) return DCR_Error;
  }

  /* .vars clear  and  .vars unset ?NAMES?
  **  Delete some or all key/value pairs from the shell variables table.
  **  Without any arguments, clear deletes them all and unset does nothing.
  */
  if( SUBCMD("clear") || SUBCMD("unset") ){
    if( (nArg>2 || zCmd[0]=='c') ){
      sqlite3_str *sbZap = sqlite3_str_new(dbs);
      char *zSql;
      sqlite3_str_appendf
        (sbZap, "DELETE FROM "SHVAR_TABLE_SNAME" WHERE key ");
      append_in_clause(sbZap,
                       (const char **)&azArg[2], (const char **)&azArg[nArg]);
      zSql = sqlite3_str_finish(sbZap);
      shell_check_oom(zSql);
      rc = sqlite3_exec(dbs, zSql, 0, 0, 0);
      sqlite3_free(zSql);
    }
#ifndef SQLITE_NOHAVE_SYSTEM
  }else if( SUBCMD("edit") ){
    ShellInState *psi = ISS(p);
    int ia = 2;
    int eval = 0;
    int edSet;

    if( !INSOURCE_IS_INTERACTIVE(psi->pInSource) ){
      utf8_printf(STD_ERR, "Error: "
                  ".vars edit can only be used interactively.\n");
      return DCR_Error;
    }
    edSet = attempt_editor_set(psi, azArg[0], (nArg>2)? azArg[2] : 0 );
    if( edSet < 0 ) return DCR_Error;
    else ia += edSet;
    while( ia < nArg ){
      ParamTableUse ptu;
      char *zA = azArg[ia];
      char cf = (zA[0]=='-')? zA[1] : 0;
      if( cf!=0 && zA[2]==0 ){
        ++ia;
        switch( cf ){
        case 'e': eval = 1; continue;
        case 't': eval = 0; continue;
        default:
          utf8_printf(STD_ERR, "Error: bad .vars edit option: %s\n", zA);
          return DCR_Error;
        }
      }
      ptu = classify_param_name(zA);
      if( ptu!=PTU_Script ){
        utf8_printf(STD_ERR,
                    "Error: %s cannot be a shell variable name.\n", zA);
        return DCR_Error;
      }
      rc = edit_one_kvalue(dbs, zA, eval, ptu, psi->zEditor);
      ++ia;
      if( rc!=0 ) return DCR_Error;
    }
#endif
  }else if( SUBCMD("list") || SUBCMD("ls") ){
    int nTailArgs = nArg - 1 - (nArg>1);
    char **pzTailArgs = azArg + 1 + (nArg>1);
    list_pov_entries(p, PTU_Script, zCmd[1]=='s', pzTailArgs, nTailArgs);
  }else if( SUBCMD("load") ){
    rc = kv_pairs_load(dbs, PTU_Script, (const char **)azArg+1, nArg-1);
  }else if( SUBCMD("save") ){
    rc = kv_pairs_save(dbs, PTU_Script, (const char **)azArg+1, nArg-1);
  }else if( SUBCMD("set") ){
    ParamTableUse ptu;
    if( nArg<4 ) return DCR_Missing;
    ptu = classify_param_name(azArg[2]);
    if( ptu!=PTU_Script ){
      utf8_printf(STD_ERR,
                  "Error: %s is not a valid shell variable name.\n", azArg[2]);
      rc = 1;
    }else{
      rc = shvar_set(dbs, azArg[2], &azArg[3], &azArg[nArg]);
      if( rc!=SQLITE_OK ){
        utf8_printf(STD_ERR, "Error: %s\n", sqlite3_errmsg(dbs));
        rc = 1;
      }
    }
  }else{
    showHelp(ISS(p)->out, "vars", p);
    return DCR_CmdErred;
  }
  return DCR_Ok | (rv!=0) | (rc!=0);
#undef SUBCMD
}

/*****************
 * The .vfsinfo, .vfslist, .vfsname and .version commands
 */
COLLECT_HELP_TEXT[
  ".version                 Show a variety of version info",
  ".vfsinfo ?AUX?           Information about the top-level VFS",
  ".vfslist                 List all available VFSes",

  }
  return rc;
}

DISPATCHABLE_COMMAND( x ? 1 0 ){
  int ia, nErrors = 0;
  sqlite3_stmt *pStmt = 0;
  sqlite3 *dbs = p->dbShell;
  DotCmdRC rv = DCR_Ok;
  enum { AsVar, AsString, AsFile } evalAs = AsVar;

  for( ia=1; ia < nArg; ++ia ){
    char *zSubmit = 0;
    const char *zOpt = azArg[ia];
    if ( *zOpt == '-' ){
      static const char *azOpts[] = { "p", "s", "f" };
      int io = ArraySize(azOpts);
      while( io > 0 ){
        if( optionMatch(zOpt, azOpts[--io]) ){
          evalAs = io;
          zOpt = 0;
          break;
        }
      }
      if( zOpt==0 ) continue;
    }
    switch( evalAs ){
    case AsVar:
      if( pStmt==0 ){
        int rc;


        if( dbs==0 || !shvars_table_exists(dbs) ){
          utf8_printf(STD_ERR,





                      "\".x vname\" can only be done after .var set ... .\n");
          return DCR_Error;
        }
        rc = sqlite3_prepare_v2(dbs, "SELECT value FROM "SHVAR_TABLE_SNAME
                                " WHERE key=$1 AND uses=1", -1, &pStmt, 0);
        if( rc!=SQLITE_OK ){
          utf8_printf(STD_ERR, SHVAR_TABLE_SNAME" is wrongly created.\n");
          return DCR_Error;
        }
      }
      if( isalpha(azArg[ia][0]) ){
        int rc = sqlite3_reset(pStmt);
        rc = sqlite3_bind_text(pStmt, 1, azArg[ia], -1, 0);
        rc = sqlite3_step(pStmt);

              if( rv>DCR_Error ) break;
            }
          }else{
            continue; /* All white (or OOM), ignore. */
          }
        }else{
          utf8_printf(STD_ERR,
                      "Skipping var '%s' (not set and executable.)\n",
                      azArg[ia]);
          ++nErrors;
        }
      }else{
        utf8_printf(STD_ERR,
                    "Skipping badly named %s. Run \".help x\"\n", azArg[ia]);
        ++nErrors;

} MetaMatchIter;

/* Prepare an iterator that will produce a sequence of MetaCommand
 * pointers whose referents names match the given cmdFragment. */
static MetaMatchIter findMatchingMetaCmds(const char *cmdFragment,
                                          ShellExState *psx){
  MetaMatchIter rv = { psx, 0, 0 };
  if( psx->dbShell==0 || ISS(psx)->bDbDispatch==0 ){
    rv.zPattern = smprintf("%s*", cmdFragment? cmdFragment : "");
    shell_check_oom((void *)rv.zPattern);
    rv.pMC = (MetaCommand *)command_table;
  }else{
    /* Prepare rv.stmt to yield results glob-matching cmdFragment. */
    const char *zSql =
      "SELECT name, extIx, cmdIx FROM "SHELL_DISP_VIEW" "
      "WHERE name glob (?||'*') ORDER BY name";
    sqlite3_prepare_v2(psx->dbShell, zSql, -1, &rv.stmt, 0);
    sqlite3_bind_text(rv.stmt, 1, cmdFragment? cmdFragment : "", -1, 0);
  }
  return rv;
}
/* Produce the next MetaCommand pointer from the iterator, or 0 if no next. */

** If shell extensions are loaded, the match must be long enough to
** result in a unique lookup.
*/
MetaCommand *findMetaCommand(const char *cmdName, ShellExState *psx,
                             /* out */ int *pnFound){
  if( pnFound ) *pnFound = 0;
#if SHELL_DYNAMIC_EXTENSION
  if( ISS(psx)->bDbDispatch ){
    int rc;
    int extIx = -1, cmdIx = -1, nf = 0;
    sqlite3_stmt *pStmt = 0;
    const char *zSql = "SELECT COUNT(*), extIx, cmdIx"
      " FROM "SHELL_DISP_VIEW" WHERE name glob (?||'*')";
    rc = sqlite3_prepare_v2(psx->dbShell, zSql, -1, &pStmt, 0);
    sqlite3_bind_text(pStmt, 1, cmdName, -1, 0);
    rc = sqlite3_step(pStmt);
    nf = sqlite3_column_int(pStmt, 0);
    extIx = sqlite3_column_int(pStmt, 1);
    cmdIx = sqlite3_column_int(pStmt, 2);
    sqlite3_finalize(pStmt);

      } /* end glom another line */
    } /* end group collection loop */
    /* Here, the group is fully collected or known to be incomplete forever. */
    switch( disposition ){
    case Dumpable:
      echo_group_input(psi, *pzLineUse);
#if SHELL_DYNAMIC_EXTENSION
      if( inKind==Script && pSS!=0 ) pSS->pMethods->resetCompletionScan(pSS);
#endif
      break;
    case Runnable:
      switch( inKind ){
      case Sql:
        /* runOneSqlLine() does its own echo when requested. */
        nErrors += runOneSqlLine(XSS(psi), *pzLineUse,

        break;
      }
#if SHELL_DYNAMIC_EXTENSION
      case Script: {
        char *zErr = 0;
        DotCmdRC dcr;
        assert(pSS!=0);
        pSS->pMethods->resetCompletionScan(pSS);
        dcr = pSS->pMethods->runScript(pSS, *pzLineUse+nLeadWhite,
                                       XSS(psi), &zErr);
        if( dcr!=DCR_Ok || zErr!=0 ){
          /* ToDo: Handle errors more informatively and like dot commands. */
          nErrors += (dcr!=DCR_Ok);
          if( zErr!=0 ){
            utf8_printf(STD_ERR, "Error: %s\n", zErr);

        termKind = DCR_Exit;
      }
      break;
    case Erroneous:
      utf8_printf(STD_ERR, "Error: Input incomplete at line %d of \"%s\"\n",
                  psi->pInSource->lineno, psi->pInSource->zSourceSay);
#if SHELL_DYNAMIC_EXTENSION
      if( inKind==Script && pSS!=0 ) pSS->pMethods->resetCompletionScan(pSS);
#endif
      ++nErrors;
      break;
    case Ignore:
      break;
    default: assert(0);
    }

  DECORATE_METHOD(Derived,help), \
  DECORATE_METHOD(Derived,argsCheck), \
  DECORATE_METHOD(Derived,execute) \
}

/* This function pointer has the same signature as the sqlite3_X_init()
 * function that is called as SQLite3 completes loading an extension.
 * It is used as a process-unique identifier for a loaded extension.
 */
typedef int (*ExtensionId)
  (sqlite3 *, char **, const struct sqlite3_api_routines *);

typedef struct Prompts {
  const char *zMain;
  const char *zContinue;

set ::topDir [file dir [file dir [file normal $argv0]]]
set runMode normal

set ::lineTags 0 ; # 0 => none, 1 => source change, 2 => line syncs, 3 => more

set ::tclGenerate 0
set ::invokeLeadWhite ""
set ::verbosity 0
set ::inFiles {}
set ::topInfile "?"
set ::presumedOutfile "?"
set ::targetProgram "?"
set ::defaultInfile "src/shell.c.in"
array set ::incTypes [list "*" "$::topDir/$::defaultInfile"]

  COMMENT {\s+(.*)$} \
  CONDITION_COMMAND {^\(\s*(\w+)\s+([^;]+)\);} \
  DISPATCH_CONFIG {^\[} \
  DISPATCHABLE_COMMAND {^\(([\w\? ]+)\)(\S)\s*$} \
  EMIT_METACMD_INIT {^\((\d*)\)} \
  INCLUDE {^(?:\(\s*(\w+)\s*\))|(?:\s+([\w./\\]+)\M)} \
  IGNORE_COMMANDS {^\(\s*([-+\w ]*)\)\s*;\s*} \
  TCL_CSTR_LITERAL {^\(([ \w*=]+)\)(\S)\s*$} \
]
# Names of the subcaptures as formal parameter to macro procs.
# COMMENT tailCapture_Commentary
# CONDITION_COMMAND tailCapture_Cmd_Condition
# CONFIGURE_DISPATCH tailCapture_Empty
# COLLECT_HELP_TEXT tailCapture_Empty
# DISPATCHABLE_COMMAND tailCapture_ArgsGlom_TrailChar
# EMIT_METACMD_INIT tailCapture_Indent
# IGNORED_COMMANDS tailCapture_SignedCmdGlom
# INCLUDE tailCapture_IncType_Filename

array set ::macroUsages [list \
  COLLECT_HELP_TEXT "\[\n   <help text lines>\n  \];" \
  COMMENT " <arbitrary characters to end of line>" \
  CONDITION_COMMAND "( name pp_expr );" \
  DISPATCH_CONFIG "\[\n   <NAME=value lines>\n  \];" \
  DISPATCHABLE_COMMAND \
    "( name args... ){\n   <implementation code lines>\n  }" \
  EMIT_METACMD_INIT "( indent );" \
  INCLUDE {( <inc_type> )} \
  SKIP_COMMANDS "( <signed_names> );" \
  TCL_CSTR_LITERAL \
    "( C string literal decl = ) {\n <TCL code lines>\n };" \
]
# RE for early discard of non-macro lines, matching all above keywords
set ::macroKeywordTailRE \
 {^\s{0,40}((?:(?:CO)|(?:DI)|(?:EM)|(?:IN)|(?:TCL)|(?:SK))[A-Z_]+)\M(.+)$}

########
# Macro procs, general signature and usage:
# inSrc is a triple, { input_filename open_input_stream input_lines_consumed }.
# Arg 2 is the macro tail as RE-captured by one of ::macroTailREs .
# ostrm is the open output stream for all regular output.
# The number of input lines consumed, including macro invocation, is returned.

    if {[regexp {^\s*(\w+)=(.+)$} $line ma k v]} {
      set ::dispCfg($k) $v
    }
  }
  return $iAte
}

# Translate a TCL line into a quoted/escaped C string literal line.
set ::bs "\\"
set ::dbs "\\\\"
set ::dq "\""
proc tcl2c {line} {
  regsub -all $::dbs $line {\\\\} line
  regsub -all $::dq $line "$::bs$::dq" line
  regsub {^\s*} $line "&$::dq" line
  return "$line${::bs}n$::dq"
}

proc TCL_CSTR_LITERAL {inSrc tailCapture ostrm} {
  # Collect and translate TCL code into a C string literal definition.
  # The macro call, TCL_CSTR_LITERAL( ... = ){, will name and declare
  # the type of the literal, and introduce the TCL lines, while lines
  # that follow, upto but not including one beginning with }, will be
  # quoted and escaped as needed to get the same logical content as a
  # multi-line initializer for the declared C string variable.
  foreach { srcFile istrm srcPrecLines } $inSrc break
  set litdef [lindex $tailCapture 0]
  set tc [lindex $tailCapture 1]
  if {$tc ne $::lb} {
    yap_usage "TCL_CSTR_LITERAL($litdef)$tc" TCL_CSTR_LITERAL
    incr $::iShuffleErrors
    return 0
  }
  set iAte 1
  set oIndent ""
  set firstIndent -1
  set clLines [list "$::invokeLeadWhite$litdef"]
  while {![eof $istrm]} {
    set tclLine [gets $istrm]
    incr iAte
    if {[regexp "^\\s*$::rb\\s*\;$" $tclLine]} {
      regsub "^(\\s*)$::rb" $tclLine {\1} tclLine
      lappend clLines $tclLine
      break
    }
    set lrt [string trimright $tclLine]
    set lt [string trimleft $lrt]
    if {$lt eq ""} {
      lappend clLines ""
      continue
    }
    lappend clLines [tcl2c $tclLine]
  }
  emit_sync $clLines $ostrm $srcPrecLines $srcFile
  return $iAte;
}

proc DISPATCHABLE_COMMAND {inSrc tailCapture ostrm} {
  # Generate and emit a function definition, maybe wrapped as set by
  # CONDITION_COMMAND(), and generate/collect its dispatch table entry,
  # as determined by its actual arguments and DISPATCH_CONFIG parameters.
  foreach { srcFile istrm srcPrecLines } $inSrc break
  set args [lindex $tailCapture 0]
  set tc [lindex $tailCapture 1]

# This function may consume additional lines via triple inSrc.
proc do_macro {inSrc lx ostrm} {
  if {![regexp $::macroKeywordTailRE $lx ma macro tail] \
          || ![info exists ::macroTailREs($macro)]} {
    return 0
  }
  # It's an attempted macro invocation line. Process or fail and yap.
  # First, capture its leading space for those macros respecting indent.
  regexp {^(\s*)} $lx ma ::invokeLeadWhite
  # Second, separate the tail according to this macro's RE for such.
  set tailCap [regexp -inline $::macroTailREs($macro) $tail]
  # Third, call like-named proc with args captured by the corresponding RE.
  return [$macro $inSrc [lrange $tailCap 1 end] $ostrm]
}

array set ::typedefsSeen {}
array set ::includesDone {}

# Filter redundant typedefs and certain includes and qualifiers, in place.