Skip to content

Commit 07c8651

Browse files
anarazelanarazel
committed
Add new psql help topics, accessible to both --help and \?.
Add --help=<topic> for the commandline, and \? <topic> as a backslash command, to show more help than the invocations without parameters do. "commands", "variables" and "options" currently exist as help topics describing, respectively, backslash commands, psql variables, and commandline switches. Without parameters the help commands show their previous topic. Some further wordsmithing or extending of the added help content might be needed; but there seems little benefit delaying the overall feature further. Author: Pavel Stehule, editorialized by many Reviewed-By: Andres Freund, Petr Jelinek, Fujii Masao, MauMau, Abhijit Menon-Sen and Erik Rijkers. Discussion: CAFj8pRDVGuC-nXBfe2CK8vpyzd2Dsr9GVpbrATAnZO=2YQ0s2Q@mail.gmail.com, CAFj8pRA54AbTv2RXDTRxiAd8hy8wxmoVLqhJDRCwEnhdd7OUkw@mail.gmail.com
1 parent 0709b7e commit 07c8651

File tree

6 files changed

+224
-63
lines changed

6 files changed

+224
-63
lines changed

‎doc/src/sgml/ref/psql-ref.sgml‎

Lines changed: 18 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -560,11 +560,17 @@ EOF
560560

561561
<varlistentry>
562562
<term><option>-?</></term>
563-
<term><option>--help</></term>
563+
<term><option>--help[=<replaceable class="parameter">topic</>]</option></term>
564564
<listitem>
565565
<para>
566-
Show help about <application>psql</application> command line
567-
arguments, and exit.
566+
Show help about <application>psql</application> and exit. The optional
567+
<replaceable class="parameter">topic</> parameter (defaulting
568+
to <literal>options</literal>) selects which part of psql is
569+
explained: <literal>commands</> describes <application>psql</>'s
570+
backslash commands; <literal>options</> describes the commandline
571+
switches that can be passed to <application>psql</>;
572+
and <literal>variables</> shows help about about psql configuration
573+
variables.
568574
</para>
569575
</listitem>
570576
</varlistentry>
@@ -2574,10 +2580,17 @@ testdb=&gt; <userinput>\setenv LESS -imx4F</userinput>
25742580

25752581

25762582
<varlistentry>
2577-
<term><literal>\?</literal></term>
2583+
<term><literal>\? [ <replaceable class="parameter">topic</> ]</literal></term>
25782584
<listitem>
25792585
<para>
2580-
Shows help information about the backslash commands.
2586+
Shows help information. The optional
2587+
<replaceable class="parameter">topic</> parameter
2588+
(defaulting to <literal>commands</>) selects which part of psql is
2589+
explained: <literal>commands</> describes <application>psql</>'s
2590+
backslash commands; <literal>options</> describes the commandline
2591+
switches that can be passed to <application>psql</>;
2592+
and <literal>variables</> shows help about about psql configuration
2593+
variables.
25812594
</para>
25822595
</listitem>
25832596
</varlistentry>

‎src/bin/psql/command.c‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1491,7 +1491,19 @@ exec_command(const char *cmd,
14911491

14921492
/* \? -- slash command help */
14931493
else if (strcmp(cmd, "?") == 0)
1494-
slashUsage(pset.popt.topt.pager);
1494+
{
1495+
char *opt0 = psql_scan_slash_option(scan_state,
1496+
OT_NORMAL, NULL, false);
1497+
1498+
if (!opt0 || strcmp(opt0, "commands") == 0)
1499+
slashUsage(pset.popt.topt.pager);
1500+
else if (strcmp(opt0, "options") == 0)
1501+
usage(pset.popt.topt.pager);
1502+
else if (strcmp(opt0, "variables") == 0)
1503+
helpVariables(pset.popt.topt.pager);
1504+
else
1505+
slashUsage(pset.popt.topt.pager);
1506+
}
14951507

14961508
#if 0
14971509

‎src/bin/psql/help.c‎

Lines changed: 162 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -46,11 +46,12 @@
4646
#define ON(var) (var ? _("on") : _("off"))
4747

4848
void
49-
usage(void)
49+
usage(unsigned short int pager)
5050
{
5151
const char *env;
5252
const char *user;
5353
char *errstr;
54+
FILE *output;
5455

5556
/* Find default user, in case we need it. */
5657
user = getenv("PGUSER");
@@ -64,77 +65,83 @@ usage(void)
6465
}
6566
}
6667

67-
printf(_("psql is the PostgreSQL interactive terminal.\n\n"));
68-
printf(_("Usage:\n"));
69-
printf(_(" psql [OPTION]... [DBNAME [USERNAME]]\n\n"));
68+
output = PageOutput(59, pager);
69+
70+
fprintf(output, _("psql is the PostgreSQL interactive terminal.\n\n"));
71+
fprintf(output, _("Usage:\n"));
72+
fprintf(output, _(" psql [OPTION]... [DBNAME [USERNAME]]\n\n"));
7073

71-
printf(_("General options:\n"));
74+
fprintf(output, _("General options:\n"));
7275
/* Display default database */
7376
env = getenv("PGDATABASE");
7477
if (!env)
7578
env = user;
76-
printf(_(" -c, --command=COMMAND run only single command (SQL or internal) and exit\n"));
77-
printf(_(" -d, --dbname=DBNAME database name to connect to (default: \"%s\")\n"), env);
78-
printf(_(" -f, --file=FILENAME execute commands from file, then exit\n"));
79-
printf(_(" -l, --list list available databases, then exit\n"));
80-
printf(_(" -v, --set=, --variable=NAME=VALUE\n"
81-
" set psql variable NAME to VALUE\n"));
82-
printf(_(" -V, --version output version information, then exit\n"));
83-
printf(_(" -X, --no-psqlrc do not read startup file (~/.psqlrc)\n"));
84-
printf(_(" -1 (\"one\"), --single-transaction\n"
79+
fprintf(output, _(" -c, --command=COMMAND run only single command (SQL or internal) and exit\n"));
80+
fprintf(output, _(" -d, --dbname=DBNAME database name to connect to (default: \"%s\")\n"), env);
81+
fprintf(output, _(" -f, --file=FILENAME execute commands from file, then exit\n"));
82+
fprintf(output, _(" -l, --list list available databases, then exit\n"));
83+
fprintf(output, _(" -v, --set=, --variable=NAME=VALUE\n"
84+
" set psql variable NAME to VALUE e.g.: -v ON_ERROR_STOP=1\n"));
85+
fprintf(output, _(" -V, --version output version information, then exit\n"));
86+
fprintf(output, _(" -X, --no-psqlrc do not read startup file (~/.psqlrc)\n"));
87+
fprintf(output, _(" -1 (\"one\"), --single-transaction\n"
8588
" execute as a single transaction (if non-interactive)\n"));
86-
printf(_(" -?, --help show this help, then exit\n"));
87-
88-
printf(_("\nInput and output options:\n"));
89-
printf(_(" -a, --echo-all echo all input from script\n"));
90-
printf(_(" -b, --echo-errors echo failed commands\n"));
91-
printf(_(" -e, --echo-queries echo commands sent to server\n"));
92-
printf(_(" -E, --echo-hidden display queries that internal commands generate\n"));
93-
printf(_(" -L, --log-file=FILENAME send session log to file\n"));
94-
printf(_(" -n, --no-readline disable enhanced command line editing (readline)\n"));
95-
printf(_(" -o, --output=FILENAME send query results to file (or |pipe)\n"));
96-
printf(_(" -q, --quiet run quietly (no messages, only query output)\n"));
97-
printf(_(" -s, --single-step single-step mode (confirm each query)\n"));
98-
printf(_(" -S, --single-line single-line mode (end of line terminates SQL command)\n"));
99-
100-
printf(_("\nOutput format options:\n"));
101-
printf(_(" -A, --no-align unaligned table output mode\n"));
102-
printf(_(" -F, --field-separator=STRING\n"
89+
fprintf(output, _(" -?, --help[=options] show this help, then exit\n"));
90+
fprintf(output, _(" --help=variables show a list of all specially treated variables, then exit\n"));
91+
fprintf(output, _(" --help=commands show a list of backslash commands, then exit\n"));
92+
93+
fprintf(output, _("\nInput and output options:\n"));
94+
fprintf(output, _(" -a, --echo-all echo all input from script\n"));
95+
fprintf(output, _(" -b, --echo-errors echo failed commands\n"));
96+
fprintf(output, _(" -e, --echo-queries echo commands sent to server\n"));
97+
fprintf(output, _(" -E, --echo-hidden display queries that internal commands generate\n"));
98+
fprintf(output, _(" -L, --log-file=FILENAME send session log to file\n"));
99+
fprintf(output, _(" -n, --no-readline disable enhanced command line editing (readline)\n"));
100+
fprintf(output, _(" -o, --output=FILENAME send query results to file (or |pipe)\n"));
101+
fprintf(output, _(" -q, --quiet run quietly (no messages, only query output)\n"));
102+
fprintf(output, _(" -s, --single-step single-step mode (confirm each query)\n"));
103+
fprintf(output, _(" -S, --single-line single-line mode (end of line terminates SQL command)\n"));
104+
105+
fprintf(output, _("\nOutput format options:\n"));
106+
fprintf(output, _(" -A, --no-align unaligned table output mode\n"));
107+
fprintf(output, _(" -F, --field-separator=STRING\n"
103108
" field separator for unaligned output (default: \"%s\")\n"),
104109
DEFAULT_FIELD_SEP);
105-
printf(_(" -H, --html HTML table output mode\n"));
106-
printf(_(" -P, --pset=VAR[=ARG] set printing option VAR to ARG (see \\pset command)\n"));
107-
printf(_(" -R, --record-separator=STRING\n"
110+
fprintf(output, _(" -H, --html HTML table output mode\n"));
111+
fprintf(output, _(" -P, --pset=VAR[=ARG] set printing option VAR to ARG (see \\pset command)\n"));
112+
fprintf(output, _(" -R, --record-separator=STRING\n"
108113
" record separator for unaligned output (default: newline)\n"));
109-
printf(_(" -t, --tuples-only print rows only\n"));
110-
printf(_(" -T, --table-attr=TEXT set HTML table tag attributes (e.g., width, border)\n"));
111-
printf(_(" -x, --expanded turn on expanded table output\n"));
112-
printf(_(" -z, --field-separator-zero\n"
114+
fprintf(output, _(" -t, --tuples-only print rows only\n"));
115+
fprintf(output, _(" -T, --table-attr=TEXT set HTML table tag attributes (e.g., width, border)\n"));
116+
fprintf(output, _(" -x, --expanded turn on expanded table output\n"));
117+
fprintf(output, _(" -z, --field-separator-zero\n"
113118
" set field separator for unaligned output to zero byte\n"));
114-
printf(_(" -0, --record-separator-zero\n"
119+
fprintf(output, _(" -0, --record-separator-zero\n"
115120
" set record separator for unaligned output to zero byte\n"));
116121

117-
printf(_("\nConnection options:\n"));
122+
fprintf(output, _("\nConnection options:\n"));
118123
/* Display default host */
119124
env = getenv("PGHOST");
120-
printf(_(" -h, --host=HOSTNAME database server host or socket directory (default: \"%s\")\n"),
125+
fprintf(output, _(" -h, --host=HOSTNAME database server host or socket directory (default: \"%s\")\n"),
121126
env ? env : _("local socket"));
122127
/* Display default port */
123128
env = getenv("PGPORT");
124-
printf(_(" -p, --port=PORT database server port (default: \"%s\")\n"),
129+
fprintf(output, _(" -p, --port=PORT database server port (default: \"%s\")\n"),
125130
env ? env : DEF_PGPORT_STR);
126131
/* Display default user */
127132
env = getenv("PGUSER");
128133
if (!env)
129134
env = user;
130-
printf(_(" -U, --username=USERNAME database user name (default: \"%s\")\n"), env);
131-
printf(_(" -w, --no-password never prompt for password\n"));
132-
printf(_(" -W, --password force password prompt (should happen automatically)\n"));
135+
fprintf(output, _(" -U, --username=USERNAME database user name (default: \"%s\")\n"), env);
136+
fprintf(output, _(" -w, --no-password never prompt for password\n"));
137+
fprintf(output, _(" -W, --password force password prompt (should happen automatically)\n"));
133138

134-
printf(_("\nFor more information, type \"\\?\" (for internal commands) or \"\\help\" (for SQL\n"
139+
fprintf(output, _("\nFor more information, type \"\\?\" (for internal commands) or \"\\help\" (for SQL\n"
135140
"commands) from within psql, or consult the psql section in the PostgreSQL\n"
136141
"documentation.\n\n"));
137-
printf(_("Report bugs to <pgsql-bugs@postgresql.org>.\n"));
142+
fprintf(output, _("Report bugs to <pgsql-bugs@postgresql.org>.\n"));
143+
144+
ClosePager(output);
138145
}
139146

140147

@@ -159,11 +166,18 @@ slashUsage(unsigned short int pager)
159166
fprintf(output, _(" \\copyright show PostgreSQL usage and distribution terms\n"));
160167
fprintf(output, _(" \\g [FILE] or ; execute query (and send results to file or |pipe)\n"));
161168
fprintf(output, _(" \\gset [PREFIX] execute query and store results in psql variables\n"));
162-
fprintf(output, _(" \\h [NAME] help on syntax of SQL commands, * for all commands\n"));
163169
fprintf(output, _(" \\q quit psql\n"));
164170
fprintf(output, _(" \\watch [SEC] execute query every SEC seconds\n"));
165171
fprintf(output, "\n");
166172

173+
fprintf(output, _("Help\n"));
174+
175+
fprintf(output, _(" \\? [commands] description of all psql backslash commands\n"));
176+
fprintf(output, _(" \\? options description of all psql commandline options\n"));
177+
fprintf(output, _(" \\? variables description of all psql configuration variables\n"));
178+
fprintf(output, _(" \\h [NAME] help on syntax of SQL commands, * for all commands\n"));
179+
fprintf(output, "\n");
180+
167181
fprintf(output, _("Query Buffer\n"));
168182
fprintf(output, _(" \\e [FILE] [LINE] edit the query buffer (or file) with external editor\n"));
169183
fprintf(output, _(" \\ef [FUNCNAME [LINE]] edit function definition with external editor\n"));
@@ -280,6 +294,106 @@ slashUsage(unsigned short int pager)
280294
}
281295

282296

297+
/*
298+
* helpVariables
299+
*
300+
* show list of available variables (options) from command line
301+
*/
302+
void
303+
helpVariables(unsigned short int pager)
304+
{
305+
FILE *output;
306+
307+
output = PageOutput(81, pager);
308+
309+
fprintf(output, _("List of specially treated variables.\n"));
310+
311+
fprintf(output, _("psql variables:\n"));
312+
fprintf(output, _("Usage:\n"));
313+
fprintf(output, _(" psql --set=NAME=VALUE\n or \\set NAME VALUE in interactive mode\n\n"));
314+
315+
fprintf(output, _(" AUTOCOMMIT if set, successful SQL commands are automatically committed\n"));
316+
fprintf(output, _(" COMP_KEYWORD_CASE determine the case used to complete SQL keywords\n"
317+
" [lower, upper, preserve-lower, preserve-upper]\n"));
318+
fprintf(output, _(" DBNAME the currently connected database name\n"));
319+
fprintf(output, _(" ECHO control what input is written to standard output\n"
320+
" [all, errors, none, queries]\n"));
321+
fprintf(output, _(" ECHO_HIDDEN display internal queries executed by backslash commands when it is set\n"
322+
" or with [noexec] just show without execution\n"));
323+
fprintf(output, _(" ENCODING current client character set encoding\n"));
324+
fprintf(output, _(" FETCH_COUNT the number of result rows to fetch and display at a time\n"
325+
" (default: 0=unlimited)\n"));
326+
fprintf(output, _(" HISTCONTROL control history list [ignorespace, ignoredups, ignoreboth]\n"));
327+
fprintf(output, _(" HISTFILE file name used to store the history list\n"));
328+
fprintf(output, _(" HISTSIZE the number of commands to store in the command history\n"));
329+
fprintf(output, _(" HOST the currently connected database server\n"));
330+
fprintf(output, _(" IGNOREEOF if unset, sending an EOF to interactive session terminates application\n"));
331+
fprintf(output, _(" LASTOID the value of last affected OID\n"));
332+
fprintf(output, _(" ON_ERROR_ROLLBACK if set, an error doesn't stop a transaction (uses implicit SAVEPOINTs)\n"));
333+
fprintf(output, _(" ON_ERROR_STOP stop batch execution after error\n"));
334+
fprintf(output, _(" PORT server port of the current connection\n"));
335+
fprintf(output, _(" PROMPT1 specify the standard psql prompt\n"));
336+
fprintf(output, _(" PROMPT2 specify the prompt used when a statement continues from a previous line\n"));
337+
fprintf(output, _(" PROMPT3 specify the prompt used during COPY ... FROM STDIN\n"));
338+
fprintf(output, _(" QUIET run quietly (same as -q option)\n"));
339+
fprintf(output, _(" SINGLELINE end of line terminates SQL command mode (same as -S option)\n"));
340+
fprintf(output, _(" SINGLESTEP single-step mode (same as -s option)\n"));
341+
fprintf(output, _(" USER the currently connected database user\n"));
342+
fprintf(output, _(" VERBOSITY control verbosity of error reports [default, verbose, terse]\n"));
343+
344+
fprintf(output, _("\nDisplay influencing variables:\n"));
345+
fprintf(output, _("Usage:\n"));
346+
fprintf(output, _(" psql --pset=NAME[=VALUE]\n or \\pset NAME [VALUE] in interactive mode\n\n"));
347+
348+
fprintf(output, _(" border border style (number)\n"));
349+
fprintf(output, _(" columns set the target width for the wrapped format\n"));
350+
fprintf(output, _(" expanded (or x) toggle expanded output\n"));
351+
fprintf(output, _(" fieldsep field separator for unaligned output (default '|')\n"));
352+
fprintf(output, _(" fieldsep_zero set field separator in unaligned mode to zero\n"));
353+
fprintf(output, _(" format set output format [unaligned, aligned, wrapped, html, latex, ..]\n"));
354+
fprintf(output, _(" footer enable or disable display of the table footer [on, off]\n"));
355+
fprintf(output, _(" linestyle set the border line drawing style [ascii, old-ascii, unicode]\n"));
356+
fprintf(output, _(" null set the string to be printed in place of a null value\n"));
357+
fprintf(output, _(" numericlocale enable or disable display of a locale-specific character to separate\n"
358+
" groups of digits [on, off]\n"));
359+
fprintf(output, _(" pager control when an external pager is used [yes, no, always]\n"));
360+
fprintf(output, _(" recordsep specify the record (line) separator to use in unaligned output format\n"));
361+
fprintf(output, _(" recordsep_zero set the record separator to use in unaligned output format to a zero byte.\n"));
362+
fprintf(output, _(" tableattr (or T) specify attributes for table tag in html format or proportional\n"
363+
" column width of left aligned data type in latex format\n"));
364+
fprintf(output, _(" title set the table title for any subsequently printed tables\n"));
365+
fprintf(output, _(" tuples_only if set, only actual table data is shown\n"));
366+
367+
fprintf(output, _("\nEnvironment variables:\n"));
368+
fprintf(output, _("Usage:\n"));
369+
370+
#ifndef WIN32
371+
fprintf(output, _(" NAME=VALUE [NAME=VALUE] psql ...\n or \\setenv NAME [VALUE] in interactive mode\n\n"));
372+
#else
373+
fprintf(output, _(" set NAME=VALUE\n psql ...\n or \\setenv NAME VALUE in interactive mode\n\n"));
374+
#endif
375+
376+
fprintf(output, _(" COLUMNS number of columns for wrapped format\n"));
377+
fprintf(output, _(" PAGER name of external pager program\n"));
378+
fprintf(output, _(" PGAPPNAME same as the application_name connection parameter\n"));
379+
fprintf(output, _(" PGDATABASE same as the dbname connection parameter\n"));
380+
fprintf(output, _(" PGHOST same as the host connection parameter\n"));
381+
fprintf(output, _(" PGPORT same as the port connection parameter\n"));
382+
fprintf(output, _(" PGUSER same as the user connection parameter\n"));
383+
fprintf(output, _(" PGPASSWORD connection password (not recommended)\n"));
384+
fprintf(output, _(" PGPASSFILE password file name\n"));
385+
fprintf(output, _(" PSQL_EDITOR, EDITOR, VISUAL\n"
386+
" editor used by the \\e and \\ef commands\n"));
387+
fprintf(output, _(" PSQL_EDITOR_LINENUMBER_ARG\n"
388+
" how to specify a line number when invoking the editor\n"));
389+
fprintf(output, _(" PSQL_HISTORY alternative location for the command history file\n"));
390+
fprintf(output, _(" PSQLRC alternative location for the user's .psqlrc file\n"));
391+
fprintf(output, _(" SHELL shell used by the \\! command\n"));
392+
fprintf(output, _(" TMPDIR directory for temporary files\n"));
393+
394+
ClosePager(output);
395+
}
396+
283397

284398
/*
285399
* helpSQL -- help with SQL commands

‎src/bin/psql/help.h‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,12 @@
88
#ifndef HELP_H
99
#define HELP_H
1010

11-
void usage(void);
11+
void usage(unsigned short int pager);
1212

1313
void slashUsage(unsigned short int pager);
1414

15+
void helpVariables(unsigned short int pager);
16+
1517
void helpSQL(const char *topic, unsigned short int pager);
1618

1719
void print_copyright(void);

0 commit comments

Comments
 (0)