Various cleanup

.github/workflows/ci.yml

@@ -9,11 +9,11 @@ jobs:
   build:
     strategy:
       matrix:
-        pg: [16, 15, 14, 13, 12, 11, 10, 9.6, 9.5, 9.4, 9.3, 9.2, 9.1, '9.0']
+        pg: [16, 15, 14, 13, 12, 11, 10, 9.6, 9.5, 9.4, 9.3, 9.2, 9.1, '9.0', 8.4, 8.3, 8.2]
     name: 🐘 PostgreSQL ${{ matrix.pg }}
     runs-on: ubuntu-latest
     container: pgxn/pgxn-tools
     steps:
       - run: pg-start ${{ matrix.pg }}
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - run: pg-build-test

.gitignore

@@ -8,3 +8,4 @@ regression.out
 !/sql/colnames--*--*.sql
 /colnames-*
 /latest-changes.md
+.vscode/

Changes

@@ -1,6 +1,10 @@
 Revision history for PostgreSQL extension colnames.
 
 1.7.0
+      - Added LICENSE file.
+      - Improved documentation code formatting.
+      - Added pure SQL example to the docs for those who can't install the
+        extension. Thanks to Jim Nasby for the suggestion (#)!
 
 1.6.0  2018-11-10T20:03:01Z
       - Fixed build and test issues on Postgres 11.

LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2011-2024 Andrew Gierth and David E. Wheeler
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement is
+hereby granted, provided that the above copyright notice and this paragraph
+and the following two paragraphs appear in all copies.
+
+IN NO EVENT SHALL ANDREW GIERTH AND DAVID E. WHEELER BE LIABLE TO ANY PARTY
+FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
+LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
+EVEN IF ANDREW GIERTH AND DAVID E. WHEELER HAS BEEN ADVISED OF THE POSSIBILITY
+OF SUCH DAMAGE.
+
+ANDREW GIERTH AND DAVID E. WHEELER SPECIFICALLY DISCLAIMS ANY WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN “AS
+IS” BASIS, AND ANDREW GIERTH AND DAVID E. WHEELER HAS NO OBLIGATIONS TO
+PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

META.json

@@ -11,7 +11,7 @@
       "colnames": {
          "abstract": "Lists the column names in a PostgreSQL RECORD value",
          "file": "sql/colnames.sql",
-         "docfile": "doc/colnames.mmd",
+         "docfile": "doc/colnames.md",
          "version": "1.1.0"
       }
    },

Makefile

@@ -7,7 +7,7 @@ DISTVERSION  = $(shell grep -m 1 '[[:space:]]\{3\}"version":' META.json | \
 
 DATA         = $(filter-out $(wildcard sql/*--*.sql),$(wildcard sql/*.sql))
 MODULES      = $(patsubst %.c,%,$(wildcard src/*.c))
-DOCS         = $(wildcard doc/*.mmd)
+DOCS         = $(wildcard doc/*.md)
 TESTS        = $(wildcard test/sql/*.sql)
 REGRESS      = $(patsubst test/sql/%.sql,%,$(TESTS))
 REGRESS_OPTS = --inputdir=test

README.md

@@ -6,78 +6,125 @@ colnames 1.7.0
 
 This extension contains a single SQL function, `colnames()`, that takes a
 record value as its argument and returns an array of the names of the columns
-in that record. This can be useful for example in trigger functions, where one
-might need to get the column names in order to generate a query string.
+in that record:
+
+``` psql
+try=# SELECT colnames( ROW(1, 'foo', 458.0) );
+  colnames
+------------
+ {f1,f2,f3}
+```
+
+This can be useful for example in trigger functions, where one might need the
+column names to generate a query string.
+
+### Pure SQL Alternative
+
+Can't use a C extension? Fear not! PostgreSQL 9.3 and later include JSON
+functions get the column names directly:
+
+```psql
+try=# SELECT ARRAY( SELECT json_object_keys( row_to_json( ROW( 1, 3, 'foo' ) ) ) );
+   array
+------------
+ {f1,f2,f3}
+```
+
+Installation
+------------
 
 To build colnames, just do this:
 
-    make
-    make install
-    make installcheck
+``` sh
+make
+make install
+make installcheck
+```
 
 If you encounter an error such as:
 
-    "Makefile", line 8: Need an operator
+```
+"Makefile", line 8: Need an operator
+```
 
 You need to use GNU make, which may well be installed on your system as
 `gmake`:
 
-    gmake
-    gmake installcheck
-    gmake install
+``` sh
+gmake
+gmake installcheck
+gmake install
+```
 
 If you encounter an error such as:
 
-    make: pg_config: Command not found
+```
+make: pg_config: Command not found
+```
 
 Be sure that you have `pg_config` installed and in your path. If you used a
 package management system such as RPM to install PostgreSQL, be sure that the
 `-devel` package is also installed. If necessary tell the build process where
 to find it:
 
-    make PG_CONFIG=/path/to/pg_config
-    make install PG_CONFIG=/path/to/pg_config
-    make installcheck PG_CONFIG=/path/to/pg_config
+``` sh
+make PG_CONFIG=/path/to/pg_config
+make install PG_CONFIG=/path/to/pg_config
+make installcheck PG_CONFIG=/path/to/pg_config
+```
 
 If you encounter an error such as:
 
-    ERROR:  must be owner of database regression
+```
+ERROR:  must be owner of database regression
+```
 
 You need to run the test suite using a super user, such as the default
 "postgres" super user:
 
-    make installcheck PGUSER=postgres
+``` sh
+make installcheck PGUSER=postgres
+```
 
 Once colnames is installed, you can add it to a database. If you're running
 PostgreSQL 9.1.0 or greater, it's a simple as connecting to a database as a
 super user and running:
 
-    CREATE EXTENSION colnames;
+``` sql
+CREATE EXTENSION colnames;
+```
 
 If you've upgraded your cluster to PostgreSQL 9.1 and already had colnames
 installed, you can upgrade it to a properly packaged extension with:
 
-    CREATE EXTENSION colnames FROM unpackaged;
+``` sql
+CREATE EXTENSION colnames FROM unpackaged;
+```
 
 For versions of PostgreSQL less than 9.1.0, you'll need to run the
 installation script:
 
-    psql -d mydb -f /path/to/pgsql/share/contrib/colnames.sql
+``` sh
+psql -d my_db -f /path/to/pgsql/share/contrib/colnames.sql
+```
 
 If you want to install colnames into a specific schema, use the `PGOPTIONS`
 environment variable to specify the schema, like so:
 
-    PGOPTIONS=--search_path=extensions psql -d mydb -f colnames.sql
+``` sh
+PGOPTIONS=--search_path=extensions psql -d my_db -f colnames.sql
+```
 
 Dependencies
 ------------
+
 The `colnames` data type has no dependencies other than PostgreSQL 8.2.0
 or higher.
 
 Copyright and License
 ---------------------
 
-Copyright (c) 2011-2018 Andrew Gierth and David E. Wheeler.
+Copyright (c) 2011-2024 Andrew Gierth and David E. Wheeler.
 
 This module is free software; you can redistribute it and/or modify it under
 the [PostgreSQL License](http://www.opensource.org/licenses/postgresql).
@@ -87,14 +134,14 @@ documentation for any purpose, without fee, and without a written agreement is
 hereby granted, provided that the above copyright notice and this paragraph
 and the following two paragraphs appear in all copies.
 
-In no event shall Andrew Gierth or David E. Wheeler be liable to any party for
-direct, indirect, special, incidental, or consequential damages, including
-lost profits, arising out of the use of this software and its documentation,
-even if Andrew Gierth or David E. Wheeler has been advised of the possibility
-of such damage.
-
-Andrew Gierth and David E. Wheeler specifically disclaim any warranties,
-including, but not limited to, the implied warranties of merchantability and
-fitness for a particular purpose. The software provided hereunder is on an "as
-is" basis, and Andrew Gierth and David E. Wheeler have no obligations to
-provide maintenance, support, updates, enhancements, or modifications.
+IN NO EVENT SHALL ANDREW GIERTH AND DAVID E. WHEELER BE LIABLE TO ANY PARTY
+FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
+LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
+EVEN IF ANDREW GIERTH AND DAVID E. WHEELER HAS BEEN ADVISED OF THE POSSIBILITY
+OF SUCH DAMAGE.
+
+ANDREW GIERTH AND DAVID E. WHEELER SPECIFICALLY DISCLAIMS ANY WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN “AS
+IS” BASIS, AND ANDREW GIERTH AND DAVID E. WHEELER HAS NO OBLIGATIONS TO
+PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

doc/colnames.md

@@ -0,0 +1,96 @@
+colnames 1.1.0
+==============
+
+Synopsis
+--------
+
+``` psql
+try=# CREATE EXTENSION colnames;
+CREATE EXTENSION
+
+try=# SELECT colnames( ROW(1, 'foo', 458.0) );
+  colnames
+------------
+ {f1,f2,f3}
+
+try=# SELECT colnames( ROW(c.*)::pg_collation ) FROM pg_collation c LIMIT 1;
+                                colnames
+-----------------------------------------------------------------------
+ {collname,collnamespace,collowner,collencoding,collcollate,collctype}
+```
+
+Description
+-----------
+
+This extension contains a single SQL function, `colnames()`, that takes a
+record value as its argument and returns an array of the names of the columns
+in that record. This can be useful for example in trigger functions, where one
+might need to get the column names in order to generate a query string.
+
+Usage
+-----
+
+Simply pass a record value to the function and it will return an array of
+the column names for that record:
+
+``` psql
+try=# SELECT colnames( ROW(1, 'foo', 458.0) );
+  colnames
+------------
+ {f1,f2,f3}
+```
+
+Note that this function is not strict; it's legal to pass in a null record of
+a named composite type:
+
+``` psql
+try=# SELECT colnames( NULL::pg_collation );
+                                colnames
+-----------------------------------------------------------------------
+ {collname,collnamespace,collowner,collencoding,collcollate,collctype}
+```
+
+**Warning:** The indexes of the resulting array do **not** necessarily
+correspond to the values one might find when fetching column names from
+`pg_attribute.attnum`, since columns are not returned. The resulting array
+**does** correspond to the order of fields that would be returned by, say,
+`SELECT (rec).*`.
+
+Support
+-------
+
+This library is stored in a public
+[GitHub repository](https://github.com/theory/colnames). Feel free to fork and
+contribute! Please file bug reports via
+[GitHub Issues](https://github.com/theory/colnames/issues/).
+
+Authors
+-------
+
+*   [Andrew Gierth](https://blog.rhodiumtoad.org.uk)
+*   [David E. Wheeler](https://www.justatheory.com/)
+
+Copyright and License
+---------------------
+
+Copyright (c) 2011-2024 Andrew Gierth and David E. Wheeler.
+
+This module is free software; you can redistribute it and/or modify it under
+the [PostgreSQL License](http://www.opensource.org/licenses/postgresql).
+
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement is
+hereby granted, provided that the above copyright notice and this paragraph
+and the following two paragraphs appear in all copies.
+
+IN NO EVENT SHALL ANDREW GIERTH AND DAVID E. WHEELER BE LIABLE TO ANY PARTY
+FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING
+LOST PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
+EVEN IF ANDREW GIERTH AND DAVID E. WHEELER HAS BEEN ADVISED OF THE POSSIBILITY
+OF SUCH DAMAGE.
+
+ANDREW GIERTH AND DAVID E. WHEELER SPECIFICALLY DISCLAIMS ANY WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN “AS
+IS” BASIS, AND ANDREW GIERTH AND DAVID E. WHEELER HAS NO OBLIGATIONS TO
+PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.