First commit, implementation complete.

Gonna release it on PGXN.

.gitignore

@@ -0,0 +1 @@
+results/

META.json

@@ -0,0 +1,38 @@
+{
+   "name": "pair",
+   "abstract": "A key/value pair data type",
+   "description": "This library contains a single PostgreSQL extension, a key/value pair data type called `pair`, along with a convenience function for constructing key/value pairs.",
+   "version": "0.1.0",
+   "maintainer": [
+      "David E. Wheeler <theory@pgxn.org>"
+   ],
+   "license": "postgresql",
+   "provides": {
+      "pgtap": {
+         "file": "sql/pair.sql",
+         "version": "0.1.0"
+      }
+   },
+   "resources": {
+      "bugtracker": {
+         "web": "http://github.com/theory/kv-pair/issues/"
+      },
+      "repository": {
+        "url":  "git://github.com/theory/kv-pair.git",
+        "web":  "http://github.com/theory/kv-pair/",
+        "type": "git"
+      }
+   },
+   "generated_by": "David E. Wheeler",
+   "meta-spec": {
+      "version": "1.0.0",
+      "url": "http://github.com/theory/pgxn/wiki/PGXN-Meta-Spec"
+   },
+   "tags": [
+      "variadic function",
+      "ordered pair",
+      "pair",
+      "key value",
+      "key value pair"
+   ]
+}

Makefile

@@ -0,0 +1,16 @@
+DATA = sql/pair.sql sql/uninstall_pair.sql
+TESTS = $(wildcard test/sql/*.sql)
+REGRESS = $(patsubst test/sql/%.sql,%,$(TESTS))
+REGRESS_OPTS = --inputdir=test
+DOCS = doc/pair.txt
+
+ifdef NO_PGXS
+subdir = contrib/citext
+top_builddir = ../..
+include $(top_builddir)/src/Makefile.global
+include $(top_srcdir)/contrib/contrib-global.mk
+else
+PG_CONFIG = pg_config
+PGXS := $(shell $(PG_CONFIG) --pgxs)
+include $(PGXS)
+endif

README.md

@@ -0,0 +1,84 @@
+pair 0.1.0
+==========
+
+This library contains a single PostgreSQL extension, a key/value pair data
+type called `pair`, along with a convenience function for constructing
+key/value pairs. It's just a simple thing, really: a two-value composite type
+that can store any type of value in its slots, which are named "k" and "v".
+
+The `pair` data type was created as an inspiration, as documented in
+[this blog post](http://justatheory.com/computers/databases/postgresql/key-value-pairs.html).
+Give it a read if you're interested in the context of its creation.
+
+To build it, just do this:
+
+    make
+    make installcheck
+    make install
+
+If you encounter an error such as:
+
+    "Makefile", line 8: Need an operator
+
+You need to use GNU make, which may well be installed on your system as
+`gmake`:
+
+    gmake
+    gmake install
+    gmake installcheck
+
+If you encounter an error such as:
+
+    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:
+
+    env PG_CONFIG=/path/to/pg_config make && make installcheck && make install
+
+And finally, if all that fails (and if you're on PostgreSQL 8.1 or lower, it
+likely will), copy the entire distribution directory to the `contrib/`
+subdirectory of the PostgreSQL source tree and try it there without
+`pg_config`:
+
+    env NO_PGXS=1 make && make installcheck && make install
+
+If you encounter an error such as:
+
+    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
+
+Dependencies
+------------
+The `pair` date type has no dependencies other than PostgreSQL.
+
+Copyright and License
+---------------------
+
+Copyright (c) 2010 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 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 David E. Wheeler has been advised of the possibility of such damage.
+
+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 David E. Wheeler has no obligations to provide maintenance, support,
+updates, enhancements, or modifications.
+

doc/pair.txt

@@ -0,0 +1,126 @@
+pair 0.1.0
+==========
+
+Synopsis
+--------
+
+    % SELECT pair('foo', 'bar');
+        pair    
+    ------------
+     (foo,bar)
+
+     % SELECT 'foo' ~> 'bar';
+         pair    
+     ------------
+      (foo,bar)
+
+Description
+-----------
+
+This library contains a single PostgreSQL extension, a key/value pair data
+type called `pair`, along with a convenience function for constructing
+key/value pairs. It's just a simple thing, really: a two-value composite type
+that can store any type of value in its slots, which are named "k" and "v".
+
+So what's it good for? Well, the main idea is if you have a custom function to
+which you'd like to be able to pass any number of key/value pairs. You could
+use [hstore](http://www.postgresql.org/docs/current/static/hstore.html) of
+course, but maybe it's overkill, or you need to guarantee the order in which
+the pairs are passed. If so, then this extension is for you.
+
+The `pair` data type was created as an inspiration, as documented in
+[this blog post](http://justatheory.com/computers/databases/postgresql/key-value-pairs.html).
+Give it a read if you're interested in the context of its creation.
+
+Usage
+-----
+There are two ways to construct key/value pairs: Via the `pair()` function:
+
+    % SELECT pair('foo', 'bar');
+        pair    
+    ------------
+     (foo,bar)
+
+Or by using the `~>` operator:
+
+    % SELECT 'foo' ~> 'bar';
+        pair    
+    ------------
+     (foo,bar)
+
+To access the values, just use the `k` and `v` column names:
+
+    SELECT ('foo' ~> 'bar').k;
+      k  
+    -----
+     foo
+    (1 row)
+
+    SELECT ('foo' ~> 'bar').v;
+      v  
+    -----
+     bar
+
+KInd of ugly, huh? Well pairs aren't very useful on their own. Where they
+really come into their own is when used as the last parameter to a variadic
+function.
+
+For example, say you wanted a function to store any number of key/value pairs
+in a table. Here's what it might look like:
+
+    CREATE OR REPLACE FUNCTION store(
+        params variadic pair[]
+    ) RETURNS VOID LANGUAGE plpgsql AS $$
+    DECLARE
+        param pair;
+    BEGIN
+        FOR param IN SELECT * FROM unnest(params) LOOP
+            UPDATE kvstore
+               SET value = param.v,
+             WHERE key = param.k;
+            CONTINUE WHEN FOUND;
+            INSERT INTO kvstore (key, value) VALUES (param.k, param.v);
+        END LOOP;
+    END;
+    $$;
+
+And to use it, pass in any number of pairs you like:
+
+    SELECT store( 'foo' ~> 'bar', 'baz' ~> 1 );
+
+Support
+-------
+
+This library is stored in an open [GitHub
+repository](http://github.com/theory/kv-pair). Feel free to fork and
+contribute! Please file bug reports via [GitHub
+Issues](http://github.com/theory/kv-pair/issues/).
+
+Author
+------
+
+[David E. Wheeler](http://justatheory.com/)
+
+Copyright and License
+---------------------
+
+Copyright (c) 2010 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 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 David E. Wheeler has been advised of the possibility of such damage.
+
+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 David E. Wheeler has no obligations to provide maintenance, support,
+updates, enhancements, or modifications.

sql/pair.sql

@@ -0,0 +1,45 @@
+-- Adjust this setting to control where the objects get created.
+SET search_path = public;
+
+SET client_min_messages = warning;
+
+BEGIN;
+
+CREATE TYPE pair AS ( k text, v text );
+
+CREATE OR REPLACE FUNCTION pair(anyelement, text)
+RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::pair';
+
+CREATE OR REPLACE FUNCTION pair(text, anyelement)
+RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::pair';
+
+CREATE OR REPLACE FUNCTION pair(anyelement, anyelement)
+RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::pair';
+
+CREATE OR REPLACE FUNCTION pair(text, text)
+RETURNS pair LANGUAGE SQL AS 'SELECT ROW($1, $2)::pair;';
+
+CREATE OPERATOR ~> (
+	LEFTARG   = text,
+	RIGHTARG  = anyelement,
+	PROCEDURE = pair
+);
+
+CREATE OPERATOR ~> (
+	LEFTARG   = anyelement,
+	RIGHTARG  = text,
+	PROCEDURE = pair
+);
+
+CREATE OPERATOR ~> (
+	LEFTARG   = anyelement,
+	RIGHTARG  = anyelement,
+	PROCEDURE = pair
+);
+
+CREATE OPERATOR ~> (
+	LEFTARG   = text,
+	RIGHTARG  = text,
+	PROCEDURE = pair
+);
+

sql/uninstall_pair.sql

@@ -0,0 +1,20 @@
+-- Adjust this setting to control where the objects get created.
+SET search_path = public;
+
+SET client_min_messages = warning;
+
+BEGIN;
+
+DROP OPERATOR ~> (text, text);
+DROP OPERATOR ~> (anyelement, anyelement);
+DROP OPERATOR ~> (anyelement, text);
+DROP OPERATOR ~> (text, anyelement);
+
+DROP FUNCTION pair(text, text);
+DROP FUNCTION pair(anyelement, anyelement);
+DROP FUNCTION pair(text, anyelement);
+DROP FUNCTION pair(anyelement, text);
+
+DROP TYPE pair CASCADE;
+
+COMMIT;