Skip to content

Commit a653226

Browse files
kenshawkenshaw
committed
Rework to help (\?) meta command
1 parent 8d0370a commit a653226

File tree

6 files changed

+782
-709
lines changed

6 files changed

+782
-709
lines changed

‎README.md

+109-89
Original file line numberDiff line numberDiff line change
@@ -699,104 +699,124 @@ Type "help" for help.
699699
700700
(not connected)=> \?
701701
General
702-
\q quit usql
703-
\copyright show usql usage and distribution terms
704-
\drivers display information about available database drivers
702+
\q quit usql
703+
\quit alias for \q
704+
\copyright show usage and distribution terms for usql
705+
\drivers show database drivers available to usql
705706
706-
Query Execute
707-
\g [(OPTIONS)] [FILE] or ; execute query (and send results to file or |pipe)
708-
\go [(OPTIONS)] [FILE] alias for \g
709-
\G [(OPTIONS)] [FILE] as \g, but forces vertical output mode
710-
\ego [(OPTIONS)] [FILE] alias for \G
711-
\gx [(OPTIONS)] [FILE] as \g, but forces expanded output mode
712-
\gexec execute query and execute each value of the result
713-
\gset [PREFIX] execute query and store results in usql variables
714-
\crosstabview [(OPTIONS)] [COLUMNS] execute query and display results in crosstab
715-
\chart CHART [(OPTIONS)] execute query and display results as a chart
716-
\watch [(OPTIONS)] [DURATION] execute query every specified interval
717-
\bind [PARAM]... set query parameters
707+
Help
708+
\? [commands] show help on usql's meta (backslash) commands
709+
\? options show help on usql command-line options
710+
\? variables show help on special usql variables
718711

719-
Query Buffer
720-
\e [FILE] [LINE] edit the query buffer (or file) with external editor
721-
\edit [-exec] edit the query (or exec) buffer
722-
\p show the contents of the query buffer
723-
\raw show the raw (non-interpolated) contents of the query buffer
724-
\exec show the contents of the exec buffer
725-
\r reset (clear) the query buffer
726-
\w FILE write query buffer to file
712+
Connection
713+
\c DSN or \c NAME connect to dsn or named database connection
714+
\c DRIVER PARAMS... connect to database with driver and parameters
715+
\connect alias for \c
716+
\Z close (disconnect) database connection
717+
\disconnect alias for \Z
718+
\password [USER] change password for user
719+
\passwd alias for \password
720+
\conninfo display information about the current database connection
727721

728-
Help
729-
\? [commands] show help on backslash commands
730-
\? options show help on usql command-line options
731-
\? variables show help on special usql variables
722+
Query Execute
723+
\g [(OPTIONS)] [FILE] or ; execute query (and send results to file or |pipe)
724+
\go alias for \g
725+
\G [(OPTIONS)] [FILE] as \g, but forces vertical output mode
726+
\ego alias for \G
727+
\gx [(OPTIONS)] [FILE] as \g, but forces expanded output mode
728+
\gexec execute query and execute each value of the result
729+
\gset [PREFIX] execute query and store results in usql variables
730+
\bind [PARAM]... set query parameters
731+
\timing [on|off] toggle timing of commands
732+
733+
Query View
734+
\crosstab [(OPTIONS)] [COLUMNS] execute query and display results in crosstab
735+
\crosstabview alias for \crosstab
736+
\xtab alias for \crosstab
737+
\chart CHART [(OPTIONS)] execute query and display results as a chart
738+
\watch [(OPTIONS)] [INTERVAL] execute query every specified interval
732739

733-
Input/Output
734-
\copy SRC DST QUERY TABLE copy query from source url to table on destination url
735-
\copy SRC DST QUERY TABLE(A,...) copy query from source url to columns of table on destination url
736-
\echo [-n] [STRING] write string to standard output (-n for no newline)
737-
\qecho [-n] [STRING] write string to \o output stream (-n for no newline)
738-
\warn [-n] [STRING] write string to standard error (-n for no newline)
739-
\o [FILE] send all query results to file or |pipe
740-
\i FILE execute commands from file
741-
\ir FILE as \i, but relative to location of current script
742-
743-
Conditional
744-
\if EXPR begin conditional block
745-
\elif EXPR alternative within current conditional block
746-
\else final alternative within current conditional block
747-
\endif end conditional block
740+
Query Buffer
741+
\e [-raw|-exec] [FILE] [LINE] edit the query buffer, raw (non-interpolated) buffer, the
742+
exec buffer, or a file with external editor
743+
\edit alias for \e
744+
\p [-raw|-exec] show the contents of the query buffer, the raw
745+
(non-interpolated) buffer or the exec buffer
746+
\print alias for \p
747+
\raw alias for \p
748+
\exec alias for \p
749+
\w [-raw|-exec] FILE write the contents of the query buffer, raw
750+
(non-interpolated) buffer, or exec buffer to file
751+
\write alias for \w
752+
\r reset (clear) the query buffer
753+
\reset alias for \r
748754

749755
Informational
750-
\d[S+] [NAME] list tables, views, and sequences or describe table, view, sequence, or index
751-
\da[S+] [PATTERN] list aggregates
752-
\df[S+] [PATTERN] list functions
753-
\di[S+] [PATTERN] list indexes
754-
\dm[S+] [PATTERN] list materialized views
755-
\dn[S+] [PATTERN] list schemas
756-
\dp[S] [PATTERN] list table, view, and sequence access privileges
757-
\ds[S+] [PATTERN] list sequences
758-
\dt[S+] [PATTERN] list tables
759-
\dv[S+] [PATTERN] list views
760-
\l[+] list databases
761-
\ss[+] [TABLE|QUERY] [k] show stats for a table or a query
762-
763-
Formatting
764-
\pset [NAME [VALUE]] set table output option
765-
\a toggle between unaligned and aligned output mode
766-
\C [STRING] set table title, or unset if none
767-
\f [STRING] show or set field separator for unaligned query output
768-
\H toggle HTML output mode
769-
\T [STRING] set HTML <table> tag attributes, or unset if none
770-
\t [on|off] show only rows
771-
\x [on|off|auto] toggle expanded output
756+
\d[S+] [NAME] list tables, views, and sequences or describe table, view,
757+
sequence, or index
758+
\da[S+] [PATTERN] list aggregates
759+
\df[S+] [PATTERN] list functions
760+
\di[S+] [PATTERN] list indexes
761+
\dm[S+] [PATTERN] list materialized views
762+
\dn[S+] [PATTERN] list schemas
763+
\dp[S] [PATTERN] list table, view, and sequence access privileges
764+
\ds[S+] [PATTERN] list sequences
765+
\dt[S+] [PATTERN] list tables
766+
\dv[S+] [PATTERN] list views
767+
\l[+] list databases
768+
\ss[+] [TABLE|QUERY] [k] show stats for a table or a query
772769

773-
Transaction
774-
\begin begin a transaction
775-
\begin -read-only ISOLATION begin a transaction with isolation level
776-
\commit commit current transaction
777-
\rollback rollback (abort) current transaction
770+
Variables
771+
\set [NAME [VALUE]] set usql application variable, or show all usql application
772+
variables if no parameters
773+
\unset NAME unset (delete) usql application variable
774+
\pset [NAME [VALUE]] set table print formatting option, or show all print
775+
formatting options if no parameters
776+
\a toggle between unaligned and aligned output mode
777+
\C [TITLE] set table title, or unset if none
778+
\f [SEPARATOR] show or set field separator for unaligned query output
779+
\H toggle HTML output mode
780+
\T [ATTRIBUTES] set HTML <table> tag attributes, or unset if none
781+
\t [on|off] show only rows
782+
\x [on|off|auto] toggle expanded output
783+
\cset [NAME [URL]] set named connection, or show all named connections if no
784+
parameters
785+
\cset NAME DRIVER PARAMS... set named connection for driver and parameters
786+
\prompt [-TYPE] VAR [PROMPT] prompt user to set application variable
778787

779-
Connection
780-
\c DSN connect to database url
781-
\c DRIVER PARAMS... connect to database with driver and parameters
782-
\cset show named connections
783-
\cset NAME DSN set named connection
784-
\cset NAME DRIVER PARAMS... define named connection for database driver
785-
\Z close database connection
786-
\password [USER] change password for user
787-
\conninfo display information about the current database connection
788-
789-
Operating System
790-
\cd [DIR] change the current working directory
791-
\getenv VARNAME ENVVAR fetch environment variable
792-
\setenv NAME [VALUE] set or unset environment variable
793-
\! [COMMAND] execute command in shell or start interactive shell
794-
\timing [on|off] toggle timing of commands
788+
Input/Output
789+
\echo [-n] [MESSAGE]... write message to standard output (-n for no newline)
790+
\qecho [-n] [MESSAGE]... write message to \o output stream (-n for no newline)
791+
\warn [-n] [MESSAGE]... write message to standard error (-n for no newline)
792+
\o [FILE] send all query results to file or |pipe
793+
\out alias for \o
794+
\copy SRC DST QUERY TABLE copy results of query from source database into table on
795+
destination database
796+
\copy SRC DST QUERY TABLE(A,...) copy results of query from source database into table's
797+
columns on destination database
798+
799+
Control/Conditional
800+
\i FILE execute commands from file
801+
\include alias for \i
802+
\ir FILE as \i, but relative to location of current script
803+
\include_relative alias for \ir
804+
\if EXPR begin conditional block
805+
\elif EXPR alternative within current conditional block
806+
\else final alternative within current conditional block
807+
\endif end conditional block
795808
796-
Variables
797-
\prompt [-TYPE] VAR [PROMPT] prompt user to set variable
798-
\set [NAME [VALUE]] set internal variable, or list all if no parameters
799-
\unset NAME unset (delete) internal variable
809+
Transaction
810+
\begin [-read-only [ISOLATION]] begin transaction, with optional isolation level
811+
\commit commit current transaction
812+
\rollback rollback (abort) current transaction
813+
\abort alias for \rollback
814+
815+
Operating System/Environment
816+
\! [COMMAND] execute command in shell or start interactive shell
817+
\cd [DIR] change the current working directory
818+
\getenv VARNAME ENVVAR fetch environment variable
819+
\setenv NAME [VALUE] set or unset environment variable
800820
```
801821
802822
Parameters passed to commands [can be backticked][backticks].

‎env/list.go

+35-33
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import (
1616

1717
// Listing writes a formatted listing of the special environment variables to
1818
// w, separated in sections based on variable type.
19-
func Listing(w io.Writer) {
19+
func Listing(w io.Writer) error {
2020
varsWithDesc := make([]string, len(varNames))
2121
for i, v := range varNames {
2222
varsWithDesc[i] = v.String()
@@ -48,46 +48,17 @@ func Listing(w io.Writer) {
4848
if configExtra != "" {
4949
configExtra = " (" + configExtra + ")"
5050
}
51-
52-
template := `List of specially treated variables
53-
54-
%s variables:
55-
Usage:
56-
%[1]s --set=NAME=VALUE
57-
or \set NAME VALUE inside %[1]s
58-
59-
%[2]s
60-
61-
Display settings:
62-
Usage:
63-
%[1]s --pset=NAME[=VALUE]
64-
or \pset NAME [VALUE] inside %[1]s
65-
66-
%[3]s
67-
68-
Environment variables:
69-
Usage:
70-
NAME=VALUE [NAME=VALUE] %[1]s ...
71-
or \setenv NAME [VALUE] inside %[1]s
72-
73-
%[4]s
74-
75-
Connection variables:
76-
Usage:
77-
%[1]s --cset NAME[=DSN]
78-
or \cset NAME [DSN] inside %[1]s
79-
or \cset NAME DRIVER PARAMS... inside %[1]s
80-
or define in %[5]s%[6]s
81-
`
8251
fmt.Fprintf(
83-
w, template,
52+
w,
53+
variableTpl,
8454
text.CommandName,
8555
strings.TrimRightFunc(strings.Join(varsWithDesc, ""), unicode.IsSpace),
8656
strings.TrimRightFunc(strings.Join(pvarsWithDesc, ""), unicode.IsSpace),
8757
strings.TrimRightFunc(strings.Join(envVarsWithDesc, ""), unicode.IsSpace),
8858
configDir,
8959
configExtra,
9060
)
61+
return nil
9162
}
9263

9364
func buildConfigDir(configName string) (string, string) {
@@ -295,3 +266,34 @@ var envVarNames = []varName{
295266
`shell used by the \! command`,
296267
},
297268
}
269+
270+
const variableTpl = `List of specially treated variables
271+
272+
%s variables:
273+
Usage:
274+
%[1]s --set=NAME=VALUE
275+
or \set NAME VALUE inside %[1]s
276+
277+
%[2]s
278+
279+
Display settings:
280+
Usage:
281+
%[1]s --pset=NAME[=VALUE]
282+
or \pset NAME [VALUE] inside %[1]s
283+
284+
%[3]s
285+
286+
Environment variables:
287+
Usage:
288+
NAME=VALUE [NAME=VALUE] %[1]s ...
289+
or \setenv NAME [VALUE] inside %[1]s
290+
291+
%[4]s
292+
293+
Connection variables:
294+
Usage:
295+
%[1]s --cset NAME[=DSN]
296+
or \cset NAME [DSN] inside %[1]s
297+
or \cset NAME DRIVER PARAMS... inside %[1]s
298+
or define in %[5]s%[6]s
299+
`

‎gen.go

+25-26
Original file line numberDiff line numberDiff line change
@@ -365,42 +365,42 @@ func parseDriverInfo(tag, filename string) (DriverInfo, error) {
365365

366366
// desc is a meta command description.
367367
type desc struct {
368-
Name string
369-
Params string
370-
Desc string
371-
Func string
372-
Hidden bool
373-
Alias string
368+
Func string
369+
Name string
370+
Params string
371+
Desc string
372+
Hidden bool
373+
Deprecated bool
374374
}
375375

376376
func newDesc(funcName, alias string, v []string) desc {
377-
name, params, descstr := v[0], "", ""
378-
switch len(v) {
379-
case 1:
377+
name, params, descstr, hidden := v[0], "", "", false
378+
switch n := len(v); {
379+
case n == 1:
380380
if i := strings.Index(name, ":"); i != -1 {
381381
name, alias = name[:i], name[i+1:]
382382
}
383-
case 2:
383+
case n == 2:
384384
descstr = v[1]
385-
case 3:
385+
case n >= 3:
386386
params, descstr = v[1], v[2]
387387
}
388+
if descstr == "" {
389+
hidden, descstr = true, `alias for \`+alias
390+
}
388391
return desc{
389-
Name: name,
390-
Params: params,
391-
Desc: descstr,
392-
Func: funcName,
393-
Alias: alias,
392+
Func: funcName,
393+
Name: name,
394+
Params: params,
395+
Desc: descstr,
396+
Hidden: hidden,
397+
Deprecated: v[len(v)-1] == "DEPRECATED",
394398
}
395399
}
396400

397401
func (d desc) String() string {
398-
if d.Desc != "" {
399-
s := strings.ReplaceAll(fmt.Sprintf("%q", d.Desc), "{{CommandName}}", `" + text.CommandName + "`)
400-
return fmt.Sprintf("{%q, %q, %s, %s, %t}", d.Name, d.Params, s, d.Func, false)
401-
}
402-
s := `alias for \` + d.Alias
403-
return fmt.Sprintf("{%q, %q, %q, %s, %t}", d.Name, d.Params, s, d.Func, true)
402+
s := strings.ReplaceAll(d.Desc, "{{CommandName}}", "` + text.CommandName + `")
403+
return fmt.Sprintf("{%s, `%s`, `%s`, `%s`, %t, %t}", d.Func, d.Name, d.Params, s, d.Hidden, d.Deprecated)
404404
}
405405

406406
func findCommand(name string) string {
@@ -647,17 +647,16 @@ var baseOrder = map[string]int{
647647
var sections = []string{
648648
"General",
649649
"Help",
650+
"Connection",
650651
"Query Execute",
651-
//"Query View",
652+
"Query View",
652653
"Query Buffer",
653654
"Informational",
654655
"Variables",
655-
"Connection",
656-
"Conditional",
657656
"Input/Output",
657+
"Control/Conditional",
658658
"Transaction",
659659
"Operating System/Environment",
660-
//"Formatting",
661660
}
662661

663662
// regexps.

0 commit comments

Comments
 (0)