/ Check-in [209afb8d]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Begin revamping the ".help" command in the command-line shell so that it can accept an argument and will do a search for commands that match that argument.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 209afb8d06466536863b89a8acb9a1a18477a06331d8cce95fc6380e1666b6f5
User & Date: drh 2018-09-26 16:53:51
Context
2018-09-26
18:02
Further improvements to the ".help" command in the CLI. check-in: edc3d18e user: drh tags: trunk
16:53
Begin revamping the ".help" command in the command-line shell so that it can accept an argument and will do a search for commands that match that argument. check-in: 209afb8d user: drh tags: trunk
16:05
Tweak spellfix.c so that if SQLITE_SPELLFIX_5BYTE_MAPPINGS is defined at compile time the Transliteration structure has space for 5 byte (instead of 4 byte) mappings. check-in: cbaf5b6c user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/shell.c.in.

  3331   3331       sqlite3_free(zErr);
  3332   3332       free(zQ2);
  3333   3333     }
  3334   3334     return rc;
  3335   3335   }
  3336   3336   
  3337   3337   /*
  3338         -** Text of a help message
         3338  +** Text of help messages.
         3339  +**
         3340  +** The help text for each individual command begins with a line that starts
         3341  +** with ".".  Subsequent lines are supplimental information.
         3342  +**
         3343  +** There must be two or more spaces between the end of the command and the
         3344  +** start of the description of what that command does.
  3339   3345   */
  3340         -static char zHelp[] =
         3346  +static const char *(azHelp[]) = {
  3341   3347   #if defined(SQLITE_HAVE_ZLIB) && !defined(SQLITE_OMIT_VIRTUALTABLE)
  3342         -  ".archive ...           Manage SQL archives: \".archive --help\" for details\n"
         3348  +  ".archive ...             Manage SQL archives",
         3349  +  "   Each command must have exactly one of the following options:",
         3350  +  "     -c, --create               Create a new archive",
         3351  +  "     -u, --update               Update or add files to an existing archive",
         3352  +  "     -t, --list                 List contents of archive",
         3353  +  "     -x, --extract              Extract files from archive",
         3354  +  "   Optional arguments:",
         3355  +  "     -v, --verbose              Print each filename as it is processed",
         3356  +  "     -f FILE, --file FILE       Operate on archive FILE (default is current db)",
         3357  +  "     -a FILE, --append FILE     Operate on FILE opened using the apndvfs VFS",
         3358  +  "     -C DIR, --directory DIR    Change to directory DIR to read/extract files",
         3359  +  "     -n, --dryrun               Show the SQL that would have occurred",
         3360  +  "   Examples:",
         3361  +  "     .ar -cf archive.sar foo bar  # Create archive.sar from files foo and bar",
         3362  +  "     .ar -tf archive.sar          # List members of archive.sar",
         3363  +  "     .ar -xvf archive.sar         # Verbosely extract files from archive.sar",
         3364  +  "   See also:",
         3365  +  "      http://sqlite.org/cli.html#sqlar_archive_support",
  3343   3366   #endif
  3344   3367   #ifndef SQLITE_OMIT_AUTHORIZATION
  3345         -  ".auth ON|OFF           Show authorizer callbacks\n"
  3346         -#endif
  3347         -  ".backup ?DB? FILE      Backup DB (default \"main\") to FILE\n"
  3348         -  "                         Add \"--append\" to open using appendvfs.\n"
  3349         -  ".bail on|off           Stop after hitting an error.  Default OFF\n"
  3350         -  ".binary on|off         Turn binary output on or off.  Default OFF\n"
  3351         -  ".cd DIRECTORY          Change the working directory to DIRECTORY\n"
  3352         -  ".changes on|off        Show number of rows changed by SQL\n"
  3353         -  ".check GLOB            Fail if output since .testcase does not match\n"
  3354         -  ".clone NEWDB           Clone data into NEWDB from the existing database\n"
  3355         -  ".databases             List names and files of attached databases\n"
  3356         -  ".dbconfig ?op? ?val?   List or change sqlite3_db_config() options\n"
  3357         -  ".dbinfo ?DB?           Show status information about the database\n"
  3358         -  ".dump ?TABLE? ...      Dump the database in an SQL text format\n"
  3359         -  "                         If TABLE specified, only dump tables matching\n"
  3360         -  "                         LIKE pattern TABLE.\n"
  3361         -  ".echo on|off           Turn command echo on or off\n"
  3362         -  ".eqp on|off|full       Enable or disable automatic EXPLAIN QUERY PLAN\n"
  3363         -  ".excel                 Display the output of next command in a spreadsheet\n"
  3364         -  ".exit                  Exit this program\n"
  3365         -  ".expert                EXPERIMENTAL. Suggest indexes for specified queries\n"
         3368  +  ".auth ON|OFF             Show authorizer callbacks",
         3369  +#endif
         3370  +  ".backup ?DB? FILE        Backup DB (default \"main\") to FILE",
         3371  +  "       --append            Use the appendvfs",
         3372  +  ".bail on|off             Stop after hitting an error.  Default OFF",
         3373  +  ".binary on|off           Turn binary output on or off.  Default OFF",
         3374  +  ".cd DIRECTORY            Change the working directory to DIRECTORY",
         3375  +  ".changes on|off          Show number of rows changed by SQL",
         3376  +  ".check GLOB              Fail if output since .testcase does not match",
         3377  +  ".clone NEWDB             Clone data into NEWDB from the existing database",
         3378  +  ".databases               List names and files of attached databases",
         3379  +  ".dbconfig ?op? ?val?     List or change sqlite3_db_config() options",
         3380  +  ".dbinfo ?DB?             Show status information about the database",
         3381  +  ".dump ?TABLE? ...        Dump the database in an SQL text format",
         3382  +  "     TABLE is LIKE pattern for the tables to dump",
         3383  +  ".echo on|off             Turn command echo on or off",
         3384  +  ".eqp on|off|full         Enable or disable automatic EXPLAIN QUERY PLAN",
         3385  +  ".excel                   Display the output of next command in a spreadsheet",
         3386  +  ".exit                    Exit this program",
         3387  +  ".expert                  EXPERIMENTAL. Suggest indexes for specified queries",
  3366   3388   /* Because explain mode comes on automatically now, the ".explain" mode
  3367   3389   ** is removed from the help screen.  It is still supported for legacy, however */
  3368         -/*".explain ?on|off|auto? Turn EXPLAIN output mode on or off or to automatic\n"*/
  3369         -  ".fullschema ?--indent? Show schema and the content of sqlite_stat tables\n"
  3370         -  ".headers on|off        Turn display of headers on or off\n"
  3371         -  ".help                  Show this message\n"
  3372         -  ".import FILE TABLE     Import data from FILE into TABLE\n"
         3390  +/*".explain ?on|off|auto?   Turn EXPLAIN output mode on or off or to automatic",*/
         3391  +  ".fullschema ?--indent?   Show schema and the content of sqlite_stat tables",
         3392  +  ".headers on|off          Turn display of headers on or off",
         3393  +  ".help ?-all? ?PATTERN?   Show help text for PATTERN",
         3394  +  ".import FILE TABLE       Import data from FILE into TABLE",
  3373   3395   #ifndef SQLITE_OMIT_TEST_CONTROL
  3374         -  ".imposter INDEX TABLE  Create imposter table TABLE on index INDEX\n"
         3396  +  ".imposter INDEX TABLE    Create imposter table TABLE on index INDEX",
  3375   3397   #endif
  3376         -  ".indexes ?TABLE?       Show names of all indexes\n"
  3377         -  "                         If TABLE specified, only show indexes for tables\n"
  3378         -  "                         matching LIKE pattern TABLE.\n"
         3398  +  ".indexes ?TABLE?         Show names of indexes",
         3399  +  "                           If TABLE is specified, only show indexes for",
         3400  +  "                           tables matching TABLE using the LIKE operator.",
  3379   3401   #ifdef SQLITE_ENABLE_IOTRACE
  3380         -  ".iotrace FILE          Enable I/O diagnostic logging to FILE\n"
         3402  +  ".iotrace FILE            Enable I/O diagnostic logging to FILE",
  3381   3403   #endif
  3382         -  ".limit ?LIMIT? ?VAL?   Display or change the value of an SQLITE_LIMIT\n"
  3383         -  ".lint OPTIONS          Report potential schema issues. Options:\n"
  3384         -  "                         fkey-indexes     Find missing foreign key indexes\n"
         3404  +  ".limit ?LIMIT? ?VAL?     Display or change the value of an SQLITE_LIMIT",
         3405  +  ".lint OPTIONS            Report potential schema issues.",
         3406  +  "     Options:",
         3407  +  "        fkey-indexes     Find missing foreign key indexes",
  3385   3408   #ifndef SQLITE_OMIT_LOAD_EXTENSION
  3386         -  ".load FILE ?ENTRY?     Load an extension library\n"
  3387         -#endif
  3388         -  ".log FILE|off          Turn logging on or off.  FILE can be stderr/stdout\n"
  3389         -  ".mode MODE ?TABLE?     Set output mode where MODE is one of:\n"
  3390         -  "                         ascii    Columns/rows delimited by 0x1F and 0x1E\n"
  3391         -  "                         csv      Comma-separated values\n"
  3392         -  "                         column   Left-aligned columns.  (See .width)\n"
  3393         -  "                         html     HTML <table> code\n"
  3394         -  "                         insert   SQL insert statements for TABLE\n"
  3395         -  "                         line     One value per line\n"
  3396         -  "                         list     Values delimited by \"|\"\n"
  3397         -  "                         quote    Escape answers as for SQL\n"
  3398         -  "                         tabs     Tab-separated values\n"
  3399         -  "                         tcl      TCL list elements\n"
  3400         -  ".nullvalue STRING      Use STRING in place of NULL values\n"
  3401         -  ".once (-e|-x|FILE)     Output for the next SQL command only to FILE\n"
  3402         -  "                         or invoke system text editor (-e) or spreadsheet (-x)\n"
  3403         -  "                         on the output.\n"
  3404         -  ".open ?OPTIONS? ?FILE? Close existing database and reopen FILE\n"
  3405         -  "                         The --new option starts with an empty file\n"
  3406         -  "                         Other options: --readonly --append --zip\n"
  3407         -  ".output ?FILE?         Send output to FILE or stdout\n"
  3408         -  ".print STRING...       Print literal STRING\n"
  3409         -  ".prompt MAIN CONTINUE  Replace the standard prompts\n"
  3410         -  ".quit                  Exit this program\n"
  3411         -  ".read FILENAME         Execute SQL in FILENAME\n"
  3412         -  ".restore ?DB? FILE     Restore content of DB (default \"main\") from FILE\n"
  3413         -  ".save FILE             Write in-memory database into FILE\n"
  3414         -  ".scanstats on|off      Turn sqlite3_stmt_scanstatus() metrics on or off\n"
  3415         -  ".schema ?PATTERN?      Show the CREATE statements matching PATTERN\n"
  3416         -  "                          Add --indent for pretty-printing\n"
  3417         -  ".selftest ?--init?     Run tests defined in the SELFTEST table\n"
  3418         -  ".separator COL ?ROW?   Change the column separator and optionally the row\n"
  3419         -  "                         separator for both the output mode and .import\n"
         3409  +  ".load FILE ?ENTRY?       Load an extension library",
         3410  +#endif
         3411  +  ".log FILE|off            Turn logging on or off.  FILE can be stderr/stdout",
         3412  +  ".mode MODE ?TABLE?       Set output mode",
         3413  +  "   MODE is one of:",
         3414  +  "     ascii    Columns/rows delimited by 0x1F and 0x1E",
         3415  +  "     csv      Comma-separated values",
         3416  +  "     column   Left-aligned columns.  (See .width)",
         3417  +  "     html     HTML <table> code",
         3418  +  "     insert   SQL insert statements for TABLE",
         3419  +  "     line     One value per line",
         3420  +  "     list     Values delimited by \"|\"",
         3421  +  "     quote    Escape answers as for SQL",
         3422  +  "     tabs     Tab-separated values",
         3423  +  "     tcl      TCL list elements",
         3424  +  ".nullvalue STRING        Use STRING in place of NULL values",
         3425  +  ".once (-e|-x|FILE)       Output for the next SQL command only to FILE",
         3426  +  "     If FILE begins with '|' then open as a pipe",
         3427  +  "     Other options:",
         3428  +  "       -e    Invoke system text editor",
         3429  +  "       -x    Open in a spreadsheet",
         3430  +  ".open ?OPTIONS? ?FILE?   Close existing database and reopen FILE",
         3431  +  "     Options:",
         3432  +  "        --append      Use appendvfs to append database to the end of FILE",
         3433  +  "        --new         Initialize FILE to an empty database",
         3434  +  "        --readonly    Open FILE readonly",
         3435  +  "        --zip         FILE is a ZIP archive",
         3436  +  ".output ?FILE?           Send output to FILE or stdout if FILE is omitted",
         3437  +  "     If FILE begins with '|' then open it as a pipe.",
         3438  +  ".print STRING...         Print literal STRING",
         3439  +  ".prompt MAIN CONTINUE    Replace the standard prompts",
         3440  +  ".quit                    Exit this program",
         3441  +  ".read FILE               Read input from FILE",
         3442  +  ".restore ?DB? FILE       Restore content of DB (default \"main\") from FILE",
         3443  +  ".save FILE               Write in-memory database into FILE",
         3444  +  ".scanstats on|off        Turn sqlite3_stmt_scanstatus() metrics on or off",
         3445  +  ".schema ?PATTERN?        Show the CREATE statements matching PATTERN",
         3446  +  "     Options:",
         3447  +  "         --indent            Try to pretty-print the schema",
         3448  +  ".selftest ?--init?       Run tests defined in the SELFTEST table",
         3449  +  ".separator COL ?ROW?     Change the column and row separators",
  3420   3450   #if defined(SQLITE_ENABLE_SESSION)
  3421         -  ".session CMD ...       Create or control sessions\n"
         3451  +  ".session CMD ...         Create or control sessions",
  3422   3452   #endif
  3423         -  ".sha3sum ?OPTIONS...?  Compute a SHA3 hash of database content\n"
         3453  +  ".sha3sum ?OPTIONS...?    Compute a SHA3 hash of database content",
  3424   3454   #ifndef SQLITE_NOHAVE_SYSTEM
  3425         -  ".shell CMD ARGS...     Run CMD ARGS... in a system shell\n"
         3455  +  ".shell CMD ARGS...       Run CMD ARGS... in a system shell",
  3426   3456   #endif
  3427         -  ".show                  Show the current values for various settings\n"
  3428         -  ".stats ?on|off?        Show stats or turn stats on or off\n"
         3457  +  ".show                    Show the current values for various settings",
         3458  +  ".stats ?on|off?          Show stats or turn stats on or off",
  3429   3459   #ifndef SQLITE_NOHAVE_SYSTEM
  3430         -  ".system CMD ARGS...    Run CMD ARGS... in a system shell\n"
  3431         -#endif
  3432         -  ".tables ?TABLE?        List names of tables\n"
  3433         -  "                         If TABLE specified, only list tables matching\n"
  3434         -  "                         LIKE pattern TABLE.\n"
  3435         -  ".testcase NAME         Begin redirecting output to 'testcase-out.txt'\n"
  3436         -  ".timeout MS            Try opening locked tables for MS milliseconds\n"
  3437         -  ".timer on|off          Turn SQL timer on or off\n"
  3438         -  ".trace FILE|off        Output each SQL statement as it is run\n"
  3439         -  ".vfsinfo ?AUX?         Information about the top-level VFS\n"
  3440         -  ".vfslist               List all available VFSes\n"
  3441         -  ".vfsname ?AUX?         Print the name of the VFS stack\n"
  3442         -  ".width NUM1 NUM2 ...   Set column widths for \"column\" mode\n"
  3443         -  "                         Negative values right-justify\n"
  3444         -;
         3460  +  ".system CMD ARGS...      Run CMD ARGS... in a system shell",
         3461  +#endif
         3462  +  ".tables ?TABLE?          List names of tables matching LIKE pattern TABLE",
         3463  +  ".testcase NAME           Begin redirecting output to 'testcase-out.txt'",
         3464  +  ".timeout MS              Try opening locked tables for MS milliseconds",
         3465  +  ".timer on|off            Turn SQL timer on or off",
         3466  +  ".trace FILE|off          Output each SQL statement as it is run",
         3467  +  ".vfsinfo ?AUX?           Information about the top-level VFS",
         3468  +  ".vfslist                 List all available VFSes",
         3469  +  ".vfsname ?AUX?           Print the name of the VFS stack",
         3470  +  ".width NUM1 NUM2 ...     Set column widths for \"column\" mode",
         3471  +  "     Negative values right-justify",
         3472  +};
         3473  +
         3474  +/*
         3475  +** Output help text.
         3476  +**
         3477  +** zPattern describes the set of commands for which help text is provided.
         3478  +** If zPattern is NULL, then show all commands, but only give a one-line
         3479  +** description of each.
         3480  +**
         3481  +** Return the number of matches.
         3482  +*/
         3483  +static int showHelp(FILE *out, const char *zPattern){
         3484  +  int i, j;
         3485  +  int n = 0;
         3486  +  char *zPat;
         3487  +  if( zPattern==0 || zPattern[0]=='0' ){
         3488  +    /* Show all commands, but only one line per command */
         3489  +    for(i=0; i<ArraySize(azHelp); i++){
         3490  +      if( azHelp[i][0]=='.' ){
         3491  +        utf8_printf(out, "%s\n", azHelp[i]);
         3492  +        n++;
         3493  +      }
         3494  +    }
         3495  +  }else{
         3496  +    /* Look for commands that for which zPattern is an exact prefix */
         3497  +    zPat = sqlite3_mprintf(".%s*", zPattern);
         3498  +    for(i=0; i<ArraySize(azHelp); i++){
         3499  +      if( sqlite3_strglob(zPat, azHelp[i])==0 ){
         3500  +        utf8_printf(out, "%s\n", azHelp[i]);
         3501  +        while( i<ArraySize(azHelp)-1 && azHelp[i+1][0]!='.' ){
         3502  +          i++;
         3503  +          utf8_printf(out, "%s\n", azHelp[i]);
         3504  +        }
         3505  +        n++;
         3506  +      }
         3507  +    }
         3508  +    sqlite3_free(zPat);
         3509  +    if( n ) return n;
         3510  +
         3511  +    /* Look for commands that contain zPattern anywhere */
         3512  +    zPat = sqlite3_mprintf("%%%s%%", zPattern);
         3513  +    for(i=0; i<ArraySize(azHelp); i++){
         3514  +      if( azHelp[i][0]=='.' ) j = i;
         3515  +      if( sqlite3_strlike(zPat, azHelp[i], 0)==0 ){
         3516  +        utf8_printf(out, "%s\n", azHelp[j]);
         3517  +        while( j<ArraySize(azHelp)-1 && azHelp[j+1][0]!='.' ){
         3518  +          j++;
         3519  +          utf8_printf(out, "%s\n", azHelp[j]);
         3520  +        }
         3521  +        i = j;
         3522  +        n++;
         3523  +      }
         3524  +    }
         3525  +    sqlite3_free(zPat);
         3526  +  }
         3527  +  return n;
         3528  +}
  3445   3529   
  3446   3530   #if defined(SQLITE_ENABLE_SESSION)
  3447   3531   /*
  3448   3532   ** Print help information for the ".sessions" command
  3449   3533   */
  3450   3534   void session_help(ShellState *p){
  3451   3535     raw_printf(p->out,
................................................................................
  4937   5021     sqlite3 *db;                    /* Database containing the archive */
  4938   5022   };
  4939   5023   
  4940   5024   /*
  4941   5025   ** Print a usage message for the .ar command to stderr and return SQLITE_ERROR.
  4942   5026   */
  4943   5027   static int arUsage(FILE *f){
  4944         -  raw_printf(f,
  4945         -"\n"
  4946         -"Usage: .ar [OPTION...] [FILE...]\n"
  4947         -"The .ar command manages sqlar archives.\n"
  4948         -"\n"
  4949         -"Examples:\n"
  4950         -"  .ar -cf archive.sar foo bar    # Create archive.sar from files foo and bar\n"
  4951         -"  .ar -tf archive.sar            # List members of archive.sar\n"
  4952         -"  .ar -xvf archive.sar           # Verbosely extract files from archive.sar\n"
  4953         -"\n"
  4954         -"Each command line must feature exactly one command option:\n"
  4955         -"  -c, --create               Create a new archive\n"
  4956         -"  -u, --update               Update or add files to an existing archive\n"
  4957         -"  -t, --list                 List contents of archive\n"
  4958         -"  -x, --extract              Extract files from archive\n"
  4959         -"\n"
  4960         -"And zero or more optional options:\n"
  4961         -"  -v, --verbose              Print each filename as it is processed\n"
  4962         -"  -f FILE, --file FILE       Operate on archive FILE (default is current db)\n"
  4963         -"  -a FILE, --append FILE     Operate on FILE opened using the apndvfs VFS\n"
  4964         -"  -C DIR, --directory DIR    Change to directory DIR to read/extract files\n"
  4965         -"  -n, --dryrun               Show the SQL that would have occurred\n"
  4966         -"\n"
  4967         -"See also: http://sqlite.org/cli.html#sqlar_archive_support\n"
  4968         -"\n"
  4969         -);
         5028  +  showHelp(f,"archive");
  4970   5029     return SQLITE_ERROR;
  4971   5030   }
  4972   5031   
  4973   5032   /*
  4974   5033   ** Print an error message for the .ar command to stderr and return 
  4975   5034   ** SQLITE_ERROR.
  4976   5035   */
................................................................................
  5069   5128       { "directory", 'C', AR_SWITCH_DIRECTORY, 1 },
  5070   5129       { "dryrun",    'n', AR_SWITCH_DRYRUN,    0 },
  5071   5130     };
  5072   5131     int nSwitch = sizeof(aSwitch) / sizeof(struct ArSwitch);
  5073   5132     struct ArSwitch *pEnd = &aSwitch[nSwitch];
  5074   5133   
  5075   5134     if( nArg<=1 ){
         5135  +    utf8_printf(stderr, "Wrong number of arguments.  Usage:\n");
  5076   5136       return arUsage(stderr);
  5077   5137     }else{
  5078   5138       char *z = azArg[1];
  5079   5139       if( z[0]!='-' ){
  5080   5140         /* Traditional style [tar] invocation */
  5081   5141         int i;
  5082   5142         int iArg = 2;
................................................................................
  6087   6147       }else{
  6088   6148         raw_printf(stderr, "Usage: .headers on|off\n");
  6089   6149         rc = 1;
  6090   6150       }
  6091   6151     }else
  6092   6152   
  6093   6153     if( c=='h' && strncmp(azArg[0], "help", n)==0 ){
  6094         -    utf8_printf(p->out, "%s", zHelp);
         6154  +    if( nArg>=2 ){
         6155  +      int n = showHelp(p->out, azArg[1]);
         6156  +      if( n==0 ){
         6157  +        utf8_printf(p->out, "Nothing matches '%s'\n", azArg[1]);
         6158  +      }
         6159  +    }else{
         6160  +      showHelp(p->out, 0);
         6161  +    }
  6095   6162     }else
  6096   6163   
  6097   6164     if( c=='i' && strncmp(azArg[0], "import", n)==0 ){
  6098   6165       char *zTable;               /* Insert data into this table */
  6099   6166       char *zFile;                /* Name of file to extra content from */
  6100   6167       sqlite3_stmt *pStmt = NULL; /* A statement */
  6101   6168       int nCol;                   /* Number of columns in the table */

Changes to test/shell1.test.

   374    374     # look for a few of the possible help commands
   375    375     list [regexp {.help} $res] \
   376    376          [regexp {.quit} $res] \
   377    377          [regexp {.show} $res]
   378    378   } {1 1 1}
   379    379   do_test shell1-3.10.2 {
   380    380     # we allow .help to take extra args (it is help after all)
   381         -  set res [catchcmd "test.db" ".help BAD"]
          381  +  set res [catchcmd "test.db" ".help *"]
   382    382     # look for a few of the possible help commands
   383    383     list [regexp {.help} $res] \
   384    384          [regexp {.quit} $res] \
   385    385          [regexp {.show} $res]
   386    386   } {1 1 1}
   387    387   
   388    388   # .import FILE TABLE     Import data from FILE into TABLE