Implement help subcommands

README.md

@@ -720,6 +720,8 @@ always appreciated][contributing]!
 
 #### Variables and Interpolation
 
+To see the list of specially treated variables, run the `\? variables` command.
+
 `usql` supports client-side interpolation of variables that can be `\set` and
 `\unset`:
 

drivers/completer/completer.go

@@ -509,6 +509,9 @@ func (c completer) complete(previousWords []string, text []rune) [][]rune {
 		TailMatches(MATCH_CASE, previousWords, `\pset`, `*`, `*`) {
 		return nil
 	}
+	if TailMatches(MATCH_CASE, previousWords, `\?`) {
+		return CompleteFromList(text, "commands", "options", "variables")
+	}
 	// is suggesting basic sql commands better than nothing?
 	return CompleteFromList(text, c.sqlCommands...)
 }

env/types.go

@@ -16,7 +16,177 @@ import (
 	"github.com/xo/usql/text"
 )
 
-// Vars is a map of variables.
+type varName struct {
+	name string
+	desc string
+}
+
+func (v varName) String() string {
+	return fmt.Sprintf("  %s\n    %s\n", v.name, v.desc)
+}
+
+var varNames = []varName{
+	{
+		"ECHO_HIDDEN",
+		"if set, display internal queries executed by backslash commands; if set to \"noexec\", just show them without execution",
+	},
+	{
+		"ON_ERROR_STOP",
+		"stop batch execution after error",
+	},
+	{
+		"PROMPT1",
+		"specifies the standard " + text.CommandName + " prompt",
+	},
+	{
+		"QUIET",
+		"run quietly (same as -q option)",
+	},
+	{
+		"ROW_COUNT",
+		"number of rows returned or affected by last query, or 0",
+	},
+}
+
+var pvarNames = []varName{
+	{
+		"border",
+		"border style (number)",
+	},
+	{
+		"columns",
+		"target width for the wrapped format",
+	},
+	{
+		"csv_fieldsep",
+		`field separator for CSV output (default ",")`,
+	},
+	{
+		"expanded",
+		"expanded output [on, off, auto]",
+	},
+	{
+		"fieldsep",
+		`field separator for unaligned output (default "|")`,
+	},
+	{
+		"fieldsep_zero",
+		"set field separator for unaligned output to a zero byte",
+	},
+	{
+		"footer",
+		"enable or disable display of the table footer [on, off]",
+	},
+	{
+		"format",
+		"set output format [unaligned, aligned, wrapped, vertical, html, asciidoc, csv, json, ...]",
+	},
+	{
+		"linestyle",
+		"set the border line drawing style [ascii, old-ascii, unicode]",
+	},
+	{
+		"null",
+		"set the string to be printed in place of a null value",
+	},
+	{
+		"numericlocale",
+		"enable display of a locale-specific character to separate groups of digits",
+	},
+	{
+		"pager_min_lines",
+		"minimum number of lines required in the output to use a pager, 0 to disable (default)",
+	},
+	{
+		"pager",
+		"control when an external pager is used [on, off, always]",
+	},
+	{
+		"recordsep",
+		"record (line) separator for unaligned output",
+	},
+	{
+		"recordsep_zero",
+		"set record separator for unaligned output to a zero byte",
+	},
+	{
+		"tableattr",
+		"specify attributes for table tag in html format, or proportional column widths for left-aligned data types in latex-longtable format",
+	},
+	{
+		"time",
+		`format used to display time/date column values (default "RFC3339Nano")`,
+	},
+	{
+		"title",
+		"set the table title for subsequently printed tables",
+	},
+	{
+		"tuples_only",
+		"if set, only actual table data is shown",
+	},
+	{
+		"unicode_border_linestyle",
+		"set the style of Unicode line drawing [single, double]",
+	},
+	{
+		"unicode_column_linestyle",
+		"set the style of Unicode line drawing [single, double]",
+	},
+	{
+		"unicode_header_linestyle",
+		"set the style of Unicode line drawing [single, double]",
+	},
+}
+
+var envVarNames = []varName{
+	{
+		text.CommandUpper() + "_EDITOR, EDITOR, VISUAL",
+		"editor used by the \\e, \\ef, and \\ev commands",
+	},
+	{
+		text.CommandUpper() + "_EDITOR_LINENUMBER_ARG",
+		"how to specify a line number when invoking the editor",
+	},
+	{
+		text.CommandUpper() + "_HISTORY",
+		"alternative location for the command history file",
+	},
+	{
+		text.CommandUpper() + "_PAGER, PAGER",
+		"name of external pager program",
+	},
+	{
+		text.CommandUpper() + "_SHOW_HOST_INFORMATION",
+		"display host information when connecting to a database",
+	},
+	{
+		text.CommandUpper() + "RC",
+		"alternative location for the user's .usqlrc file",
+	},
+	{
+		"SYNTAX_HL",
+		"enable syntax highlighting",
+	},
+	{
+		"SYNTAX_HL_FORMAT",
+		"chroma library formatter name",
+	},
+	{
+		"SYNTAX_HL_STYLE",
+		`chroma library style name (default "monokai")`,
+	},
+	{
+		"SYNTAX_HL_OVERRIDE_BG",
+		"enables overriding the background color of the chroma styles",
+	},
+	{
+		"SHELL",
+		"shell used by the \\! command",
+	},
+}
+
+// Vars is a map of variables to their values.
 type Vars map[string]string
 
 // Set sets a variable name.
@@ -380,3 +550,52 @@ func max(a, b int) int {
 	}
 	return b
 }
+
+// Listing writes the formatted variables listing to w, separated into different
+// sections for all known variables.
+func Listing(w io.Writer) {
+	varsWithDesc := make([]string, len(varNames))
+	for i, v := range varNames {
+		varsWithDesc[i] = v.String()
+	}
+	pvarsWithDesc := make([]string, len(pvarNames))
+	for i, v := range pvarNames {
+		pvarsWithDesc[i] = v.String()
+	}
+	envVarsWithDesc := make([]string, len(envVarNames))
+	for i, v := range envVarNames {
+		envVarsWithDesc[i] = v.String()
+	}
+	template := `
+List of specially treated variables
+
+%s variables:
+Usage:
+  %s --set=NAME=VALUE
+  or \set NAME VALUE inside %s
+
+%s
+
+
+Display settings:
+Usage:
+  %s --pset=NAME[=VALUE]
+  or \pset NAME [VALUE] inside %s
+
+%s
+
+Environment variables:
+Usage:
+  NAME=VALUE [NAME=VALUE] %s ...
+  or \setenv NAME [VALUE] inside %s
+
+%s
+
+`
+	fmt.Fprintf(
+		w, template,
+		text.CommandName, text.CommandName, text.CommandName, strings.Join(varsWithDesc, "\n"),
+		text.CommandName, text.CommandName, strings.Join(pvarsWithDesc, "\n"),
+		text.CommandName, text.CommandName, strings.Join(envVarsWithDesc, "\n"),
+	)
+}

metacmd/cmds.go

@@ -14,6 +14,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/alecthomas/kingpin"
 	"github.com/xo/dburl"
 	"github.com/xo/usql/drivers"
 	"github.com/xo/usql/env"
@@ -49,7 +50,21 @@ func init() {
 				"? ": {"show help on special variables", "variables"},
 			},
 			Process: func(p *Params) error {
-				Listing(p.Handler.IO().Stdout())
+				name, err := p.Get(false)
+				if err != nil {
+					return err
+				}
+				switch name {
+				default:
+					Listing(p.Handler.IO().Stdout())
+				case "commands":
+					Listing(p.Handler.IO().Stdout())
+				case "options":
+					// FIXME: decouple
+					kingpin.Usage()
+				case "variables":
+					env.Listing(p.Handler.IO().Stdout())
+				}
 				return nil
 			},
 		},