Rework option set of oid2name

oid2name has done little effort to keep an interface consistent with
other binary utilities:
- -H was used instead of -h/-host.  This option is now marked as
deprecated, still its output is accepted to be backward-compatible.
- -P has been removed from the code, and was still documented.
- All options gain long aliases, making connection options more similar
to other binaries.
- Document environment variables which could be used: PGHOST, PGPORT and
PGUSER.

A basic set of TAP tests is added on the way, and documentation is
cleaned up to be more consistent with other things.

Author: Tatsuro Yamada
Reviewed-by: Michael Paquier
Discussion: https://postgr.es/m/c7e7f25c-1747-cd0f-9335-390bc97b2db5@lab.ntt.co.jp

5 files changed, 146 insertions, 69 deletions

diff --git a/contrib/oid2name/.gitignore b/contrib/oid2name/.gitignore
index fdefde108dd..0410fb7afad 100644
--- a/contrib/oid2name/.gitignore
+++ b/contrib/oid2name/.gitignore
@@ -1 +1,3 @@
 /oid2name
+
+/tmp_check/
diff --git a/contrib/oid2name/Makefile b/contrib/oid2name/Makefile
index 3eef8f60bea..77b72880f5b 100644
--- a/contrib/oid2name/Makefile
+++ b/contrib/oid2name/Makefile
@@ -19,3 +19,9 @@ top_builddir = ../..
 include $(top_builddir)/src/Makefile.global
 include $(top_srcdir)/contrib/contrib-global.mk
 endif
+
+check:
+	$(prove_check)
+
+installcheck:
+	$(prove_installcheck)
diff --git a/contrib/oid2name/oid2name.c b/contrib/oid2name/oid2name.c
index 63e360c4c56..aa122ca0e98 100644
--- a/contrib/oid2name/oid2name.c
+++ b/contrib/oid2name/oid2name.c
@@ -14,6 +14,8 @@
 #include "fe_utils/connect.h"
 #include "libpq-fe.h"
 #include "pg_getopt.h"
+#include "getopt_long.h"
+
 
 /* an extensible array to keep track of elements to show */
 typedef struct
@@ -60,8 +62,28 @@ void		sql_exec_dumpalltbspc(PGconn *, struct options *);
 void
 get_opts(int argc, char **argv, struct options *my_opts)
 {
+	static struct option long_options[] = {
+		{"dbname", required_argument, NULL, 'd'},
+		{"host", required_argument, NULL, 'h'},
+		{"host", required_argument, NULL, 'H'}, /* deprecated */
+		{"filenode", required_argument, NULL, 'f'},
+		{"indexes", no_argument, NULL, 'i'},
+		{"oid", required_argument, NULL, 'o'},
+		{"port", required_argument, NULL, 'p'},
+		{"quiet", no_argument, NULL, 'q'},
+		{"tablespaces", no_argument, NULL, 's'},
+		{"system-objects", no_argument, NULL, 'S'},
+		{"table", required_argument, NULL, 't'},
+		{"username", required_argument, NULL, 'U'},
+		{"version", no_argument, NULL, 'V'},
+		{"extended", no_argument, NULL, 'x'},
+		{"help", no_argument, NULL, '?'},
+		{NULL, 0, NULL, 0}
+	};
+
 	int			c;
 	const char *progname;
+	int			optindex;
 
 	progname = get_progname(argv[0]);
 
@@ -93,7 +115,7 @@ get_opts(int argc, char **argv, struct options *my_opts)
 	}
 
 	/* get opts */
-	while ((c = getopt(argc, argv, "H:p:U:d:t:o:f:qSxish")) != -1)
+	while ((c = getopt_long(argc, argv, "d:f:h:H:io:p:qsSt:U:x", long_options, &optindex)) != -1)
 	{
 		switch (c)
 		{
@@ -102,39 +124,40 @@ get_opts(int argc, char **argv, struct options *my_opts)
 				my_opts->dbname = pg_strdup(optarg);
 				break;
 
-				/* specify one tablename to show */
-			case 't':
-				add_one_elt(optarg, my_opts->tables);
-				break;
-
-				/* specify one Oid to show */
-			case 'o':
-				add_one_elt(optarg, my_opts->oids);
-				break;
-
 				/* specify one filenode to show */
 			case 'f':
 				add_one_elt(optarg, my_opts->filenodes);
 				break;
 
-				/* don't show headers */
-			case 'q':
-				my_opts->quiet = true;
-				break;
-
 				/* host to connect to */
-			case 'H':
+			case 'H':			/* deprecated */
+			case 'h':
 				my_opts->hostname = pg_strdup(optarg);
 				break;
 
+				/* also display indexes */
+			case 'i':
+				my_opts->indexes = true;
+				break;
+
+				/* specify one Oid to show */
+			case 'o':
+				add_one_elt(optarg, my_opts->oids);
+				break;
+
 				/* port to connect to on remote host */
 			case 'p':
 				my_opts->port = pg_strdup(optarg);
 				break;
 
-				/* username */
-			case 'U':
-				my_opts->username = pg_strdup(optarg);
+				/* don't show headers */
+			case 'q':
+				my_opts->quiet = true;
+				break;
+
+				/* dump tablespaces only */
+			case 's':
+				my_opts->tablespaces = true;
 				break;
 
 				/* display system tables */
@@ -142,9 +165,14 @@ get_opts(int argc, char **argv, struct options *my_opts)
 				my_opts->systables = true;
 				break;
 
-				/* also display indexes */
-			case 'i':
-				my_opts->indexes = true;
+				/* specify one tablename to show */
+			case 't':
+				add_one_elt(optarg, my_opts->tables);
+				break;
+
+				/* username */
+			case 'U':
+				my_opts->username = pg_strdup(optarg);
 				break;
 
 				/* display extra columns */
@@ -152,16 +180,6 @@ get_opts(int argc, char **argv, struct options *my_opts)
 				my_opts->extended = true;
 				break;
 
-				/* dump tablespaces only */
-			case 's':
-				my_opts->tablespaces = true;
-				break;
-
-			case 'h':
-				help(progname);
-				exit(0);
-				break;
-
 			default:
 				fprintf(stderr, _("Try \"%s --help\" for more information.\n"), progname);
 				exit(1);
@@ -176,20 +194,22 @@ help(const char *progname)
 		   "Usage:\n"
 		   "  %s [OPTION]...\n"
 		   "\nOptions:\n"
-		   "  -d DBNAME      database to connect to\n"
-		   "  -f FILENODE    show info for table with given file node\n"
-		   "  -H HOSTNAME    database server host or socket directory\n"
-		   "  -i             show indexes and sequences too\n"
-		   "  -o OID         show info for table with given OID\n"
-		   "  -p PORT        database server port number\n"
-		   "  -q             quiet (don't show headers)\n"
-		   "  -s             show all tablespaces\n"
-		   "  -S             show system objects too\n"
-		   "  -t TABLE       show info for named table\n"
-		   "  -U NAME        connect as specified database user\n"
-		   "  -V, --version  output version information, then exit\n"
-		   "  -x             extended (show additional columns)\n"
-		   "  -?, --help     show this help, then exit\n"
+		   "  -f, --filenode=FILENODE    show info for table with given file node\n"
+		   "  -i, --indexes              show indexes and sequences too\n"
+		   "  -o, --oid=OID              show info for table with given OID\n"
+		   "  -q, --quiet                quiet (don't show headers)\n"
+		   "  -s, --tablespaces          show all tablespaces\n"
+		   "  -S, --system-objects       show system objects too\n"
+		   "  -t, --table=TABLE          show info for named table\n"
+		   "  -V, --version              output version information, then exit\n"
+		   "  -x, --extended             extended (show additional columns)\n"
+		   "  -?, --help                 show this help, then exit\n"
+		   "\nConnection options:\n"
+		   "  -d, --dbname=DBNAME        database to connect to\n"
+		   "  -h, --host=HOSTNAME        database server host or socket directory\n"
+		   "  -H                         same as -h, deprecated option\n"
+		   "  -p, --port=PORT            database server port number\n"
+		   "  -U, --username=USERNAME    connect as specified database user\n"
 		   "\nThe default action is to show all database OIDs.\n\n"
 		   "Report bugs to <pgsql-bugs@postgresql.org>.\n",
 		   progname, progname);
diff --git a/contrib/oid2name/t/001_basic.pl b/contrib/oid2name/t/001_basic.pl
new file mode 100644
index 00000000000..fa2c5743f63
--- /dev/null
+++ b/contrib/oid2name/t/001_basic.pl
@@ -0,0 +1,12 @@
+use strict;
+use warnings;
+
+use TestLib;
+use Test::More tests => 8;
+
+#########################################
+# Basic checks
+
+program_help_ok('oid2name');
+program_version_ok('oid2name');
+program_options_handling_ok('oid2name');
diff --git a/doc/src/sgml/oid2name.sgml b/doc/src/sgml/oid2name.sgml
index dd875281c81..c7ebd61c6bf 100644
--- a/doc/src/sgml/oid2name.sgml
+++ b/doc/src/sgml/oid2name.sgml
@@ -60,41 +60,48 @@
    <variablelist>
 
     <varlistentry>
-     <term><option>-f</option> <replaceable>filenode</replaceable></term>
-     <listitem><para>show info for table with filenode <replaceable>filenode</replaceable></para></listitem>
+     <term><option>-f <replaceable class="parameter">filenode</replaceable></option></term>
+     <term><option>--filenode=<replaceable class="parameter">filenode</replaceable></option></term>
+     <listitem><para>show info for table with filenode <replaceable>filenode</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-i</option></term>
-     <listitem><para>include indexes and sequences in the listing</para></listitem>
+     <term><option>--indexes</option></term>
+     <listitem><para>include indexes and sequences in the listing.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-o</option> <replaceable>oid</replaceable></term>
-     <listitem><para>show info for table with OID <replaceable>oid</replaceable></para></listitem>
+     <term><option>-o <replaceable class="parameter">oid</replaceable></option></term>
+     <term><option>--oid=<replaceable class="parameter">oid</replaceable></option></term>
+     <listitem><para>show info for table with OID <replaceable>oid</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-q</option></term>
-     <listitem><para>omit headers (useful for scripting)</para></listitem>
+     <term><option>--quiet</option></term>
+     <listitem><para>omit headers (useful for scripting).</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-s</option></term>
-     <listitem><para>show tablespace OIDs</para></listitem>
+     <term><option>--tablespaces</option></term>
+     <listitem><para>show tablespace OIDs.</para></listitem>
     </varlistentry>
 
     <varlistentry>
      <term><option>-S</option></term>
+     <term><option>--system-objects</option></term>
      <listitem><para>include system objects (those in
       <option>information_schema</option>, <option>pg_toast</option>
-      and <option>pg_catalog</option> schemas)
+      and <option>pg_catalog</option> schemas).
      </para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-t</option> <replaceable>tablename_pattern</replaceable></term>
-     <listitem><para>show info for table(s) matching <replaceable>tablename_pattern</replaceable></para></listitem>
+     <term><option>-t <replaceable class="parameter">tablename_pattern</replaceable></option></term>
+     <term><option>--table=<replaceable class="parameter">tablename_pattern</replaceable></option></term>
+     <listitem><para>show info for table(s) matching <replaceable class="parameter">tablename_pattern</replaceable>.</para></listitem>
     </varlistentry>
 
     <varlistentry>
@@ -109,8 +116,9 @@
 
     <varlistentry>
      <term><option>-x</option></term>
+     <term><option>--extended</option></term>
      <listitem><para>display more information about each object shown: tablespace name,
-      schema name, and OID
+      schema name, and OID.
      </para></listitem>
     </varlistentry>
 
@@ -133,29 +141,34 @@
 
    <variablelist>
     <varlistentry>
-     <term><option>-d</option> <replaceable>database</replaceable></term>
-     <listitem><para>database to connect to</para></listitem>
+     <term><option>-d <replaceable class="parameter">database</replaceable></option></term>
+     <term><option>--dbname=<replaceable class="parameter">database</replaceable></option></term>
+     <listitem><para>database to connect to.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-H</option> <replaceable>host</replaceable></term>
-     <listitem><para>database server's host</para></listitem>
+     <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
+     <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
+     <listitem><para>database server's host.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-p</option> <replaceable>port</replaceable></term>
-     <listitem><para>database server's port</para></listitem>
+     <term><option>-H <replaceable class="parameter">host</replaceable></option></term>
+     <listitem><para>database server's host.  Use of this parameter is
+     <emphasis>deprecated</emphasis> as of
+     <productname>PostgreSQL</productname> 12.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-U</option> <replaceable>username</replaceable></term>
-     <listitem><para>user name to connect as</para></listitem>
+     <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
+     <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
+     <listitem><para>database server's port.</para></listitem>
     </varlistentry>
 
     <varlistentry>
-     <term><option>-P</option> <replaceable>password</replaceable></term>
-     <listitem><para>password (deprecated &mdash; putting this on the command line
-      is a security hazard)</para></listitem>
+     <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
+     <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
+     <listitem><para>user name to connect as.</para></listitem>
     </varlistentry>
 
    </variablelist>
@@ -189,6 +202,30 @@
  </refsect1>
 
  <refsect1>
+  <title>Environment</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><envar>PGHOST</envar></term>
+    <term><envar>PGPORT</envar></term>
+    <term><envar>PGUSER</envar></term>
+
+    <listitem>
+     <para>
+      Default connection parameters.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <para>
+   This utility, like most other <productname>PostgreSQL</productname>
+   utilities, also uses the environment variables supported by
+   <application>libpq</application> (see <xref linkend="libpq-envars"/>).
+  </para>
+ </refsect1>
+
+ <refsect1>
   <title>Notes</title>
 
   <para>