pg_query 2.1.0 → 4.2.1

data/ext/pg_query/pg_query_outfuncs_protobuf.c

@@ -150,33 +150,93 @@ _outOidList(PgQuery__OidList* out, const List *node)
 // TODO: Add Bitmapset
 
 static void
-_outInteger(PgQuery__Integer* out, const Value *node)
+_outInteger(PgQuery__Integer* out, const Integer *node)
 {
-  out->ival = node->val.ival;
+  out->ival = node->ival;
 }
 
 static void
-_outFloat(PgQuery__Float* out, const Value *node)
+_outFloat(PgQuery__Float* out, const Float *node)
 {
-  out->str = node->val.str;
+  out->fval = node->fval;
 }
 
 static void
-_outString(PgQuery__String* out, const Value *node)
+_outBoolean(PgQuery__Boolean* out, const Boolean *node)
 {
-  out->str = node->val.str;
+  out->boolval = node->boolval;
 }
 
 static void
-_outBitString(PgQuery__BitString* out, const Value *node)
+_outString(PgQuery__String* out, const String *node)
 {
-  out->str = node->val.str;
+  out->sval = node->sval;
 }
 
 static void
-_outNull(PgQuery__Null* out, const Value *node)
+_outBitString(PgQuery__BitString* out, const BitString *node)
 {
-  // Null has no fields
+  out->bsval = node->bsval;
+}
+
+static void
+_outAConst(PgQuery__AConst* out, const A_Const *node)
+{
+  out->isnull = node->isnull;
+  out->location = node->location;
+
+  if (!node->isnull) {
+    switch (nodeTag(&node->val.node)) {
+      case T_Integer: {
+        PgQuery__Integer *value = palloc(sizeof(PgQuery__Integer));
+        pg_query__integer__init(value);
+        value->ival = node->val.ival.ival;
+
+        out->val_case = PG_QUERY__A__CONST__VAL_IVAL;
+        out->ival = value;
+        break;
+      }
+      case T_Float: {
+        PgQuery__Float *value = palloc(sizeof(PgQuery__Float));
+        pg_query__float__init(value);
+        value->fval = pstrdup(node->val.fval.fval);
+
+        out->val_case = PG_QUERY__A__CONST__VAL_FVAL;
+        out->fval = value;
+        break;
+      }
+      case T_Boolean: {
+        PgQuery__Boolean *value = palloc(sizeof(PgQuery__Boolean));
+        pg_query__boolean__init(value);
+        value->boolval = node->val.boolval.boolval;
+
+        out->val_case = PG_QUERY__A__CONST__VAL_BOOLVAL;
+        out->boolval = value;
+        break;
+      }
+      case T_String: {
+        PgQuery__String *value = palloc(sizeof(PgQuery__String));
+	pg_query__string__init(value);
+	value->sval = pstrdup(node->val.sval.sval);
+
+	out->val_case = PG_QUERY__A__CONST__VAL_SVAL;
+	out->sval = value;
+	break;
+      }
+      case T_BitString: {
+        PgQuery__BitString *value = palloc(sizeof(PgQuery__BitString));
+	pg_query__bit_string__init(value);
+	value->bsval = pstrdup(node->val.bsval.bsval);
+
+	out->val_case = PG_QUERY__A__CONST__VAL_BSVAL;
+	out->bsval = value;
+	break;
+      }
+      default:
+        // Unreachable
+        Assert(false);
+    }
+  }
 }
 
 #include "pg_query_enum_defs.c"

data/ext/pg_query/pg_query_parse.c

@@ -42,7 +42,7 @@ PgQueryInternalParsetreeAndError pg_query_raw_parse(const char* input)
 
 	PG_TRY();
 	{
-		result.tree = raw_parser(input);
+		result.tree = raw_parser(input, RAW_PARSE_DEFAULT);
 
 #ifndef DEBUG
 		// Save stderr for result

data/ext/pg_query/pg_query_parse_plpgsql.c

@@ -18,7 +18,7 @@ typedef struct {
 	PgQueryError* error;
 } PgQueryInternalPlpgsqlFuncAndError;
 
-static PgQueryInternalPlpgsqlFuncAndError pg_query_raw_parse_plpgsql(CreateFunctionStmt* stmt);
+static PgQueryInternalPlpgsqlFuncAndError pg_query_raw_parse_plpgsql(Node* stmt);
 
 static void add_dummy_return(PLpgSQL_function *function)
 {
@@ -73,6 +73,36 @@ static void plpgsql_compile_error_callback(void *arg)
 				   plpgsql_error_funcname, plpgsql_latest_lineno());
 }
 
+static PLpgSQL_function *compile_do_stmt(DoStmt* stmt)
+{
+	char *proc_source = NULL;
+	const ListCell *lc;
+	char *language = "plpgsql";
+
+	assert(IsA(stmt, DoStmt));
+
+	foreach(lc, stmt->args)
+	{
+		DefElem* elem = (DefElem*) lfirst(lc);
+
+		if (strcmp(elem->defname, "as") == 0) {
+
+			assert(IsA(elem->arg, String));
+			proc_source = strVal(elem->arg);
+		} else if (strcmp(elem->defname, "language") == 0) {
+			language = strVal(elem->arg);
+		}
+	}
+
+	assert(proc_source != NULL);
+
+	if(strcmp(language, "plpgsql") != 0) {
+		return (PLpgSQL_function *) palloc0(sizeof(PLpgSQL_function));
+	}
+	return plpgsql_compile_inline(proc_source);
+
+}
+
 static PLpgSQL_function *compile_create_function_stmt(CreateFunctionStmt* stmt)
 {
 	char *func_name;
@@ -87,6 +117,7 @@ static PLpgSQL_function *compile_create_function_stmt(CreateFunctionStmt* stmt)
 	const ListCell *lc, *lc2, *lc3;
 	bool is_trigger = false;
 	bool is_setof = false;
+	char *language = "plpgsql";
 
 	assert(IsA(stmt, CreateFunctionStmt));
 
@@ -105,10 +136,16 @@ static PLpgSQL_function *compile_create_function_stmt(CreateFunctionStmt* stmt)
 			{
 				proc_source = strVal(lfirst(lc2));
 			}
+		} else if (strcmp(elem->defname, "language") == 0) {
+			language = strVal(elem->arg);
 		}
 	}
 
-	assert(proc_source);
+	assert(proc_source != NULL);
+
+	if(strcmp(language, "plpgsql") != 0) { 
+		return (PLpgSQL_function *) palloc0(sizeof(PLpgSQL_function));
+	}
 
 	if (stmt->returnType != NULL) {
 		foreach(lc3, stmt->returnType->names)
@@ -179,6 +216,26 @@ static PLpgSQL_function *compile_create_function_stmt(CreateFunctionStmt* stmt)
 	plpgsql_DumpExecTree = false;
 	plpgsql_start_datums();
 
+	/* Setup parameter names */
+	foreach(lc, stmt->parameters)
+	{
+		FunctionParameter *param = lfirst_node(FunctionParameter, lc);
+		if (param->name != NULL)
+		{
+			char buf[32];
+			PLpgSQL_type *argdtype;
+			PLpgSQL_variable *argvariable;
+			PLpgSQL_nsitem_type argitemtype;
+			snprintf(buf, sizeof(buf), "$%d", foreach_current_index(lc) + 1);
+			argdtype = plpgsql_build_datatype(UNKNOWNOID, -1, InvalidOid, NULL);
+			argvariable = plpgsql_build_variable(param->name ? param->name : buf, 0, argdtype, false);
+			argitemtype = argvariable->dtype == PLPGSQL_DTYPE_VAR ? PLPGSQL_NSTYPE_VAR : PLPGSQL_NSTYPE_REC;
+			plpgsql_ns_additem(argitemtype, argvariable->dno, buf);
+			if (param->name != NULL)
+				plpgsql_ns_additem(argitemtype, argvariable->dno, param->name);
+		}
+	}
+
 	/* Set up as though in a function returning VOID */
 	function->fn_rettype = VOIDOID;
 	function->fn_retset = is_setof;
@@ -253,7 +310,7 @@ static PLpgSQL_function *compile_create_function_stmt(CreateFunctionStmt* stmt)
 	return function;
 }
 
-PgQueryInternalPlpgsqlFuncAndError pg_query_raw_parse_plpgsql(CreateFunctionStmt* stmt)
+PgQueryInternalPlpgsqlFuncAndError pg_query_raw_parse_plpgsql(Node* stmt)
 {
 	PgQueryInternalPlpgsqlFuncAndError result = {0};
 	MemoryContext cctx = CurrentMemoryContext;
@@ -286,7 +343,13 @@ PgQueryInternalPlpgsqlFuncAndError pg_query_raw_parse_plpgsql(CreateFunctionStmt
 
 	PG_TRY();
 	{
-		result.func = compile_create_function_stmt(stmt);
+		if (IsA(stmt, CreateFunctionStmt)) {
+			result.func = compile_create_function_stmt((CreateFunctionStmt *) stmt);
+		} else if (IsA(stmt, DoStmt)){
+			result.func = compile_do_stmt((DoStmt *) stmt);
+		} else {
+			elog(ERROR, "Unexpected node type for PL/pgSQL parsing: %d", nodeTag(stmt));
+		}
 
 #ifndef DEBUG
 		// Save stderr for result
@@ -334,36 +397,36 @@ PgQueryInternalPlpgsqlFuncAndError pg_query_raw_parse_plpgsql(CreateFunctionStmt
 	return result;
 }
 
-typedef struct createFunctionStmts
+typedef struct plStmts
 {
-	CreateFunctionStmt **stmts;
+	Node **stmts;
 	int stmts_buf_size;
 	int stmts_count;
-} createFunctionStmts;
+} plStmts;
 
-static bool create_function_stmts_walker(Node *node, createFunctionStmts *state)
+static bool stmts_walker(Node *node, plStmts *state)
 {
 	bool result;
 	MemoryContext ccxt = CurrentMemoryContext;
 
 	if (node == NULL) return false;
 
-	if (IsA(node, CreateFunctionStmt))
+	if (IsA(node, CreateFunctionStmt) || IsA(node, DoStmt))
 	{
 		if (state->stmts_count >= state->stmts_buf_size)
 		{
 			state->stmts_buf_size *= 2;
-			state->stmts = (CreateFunctionStmt**) repalloc(state->stmts, state->stmts_buf_size * sizeof(CreateFunctionStmt*));
+			state->stmts = (Node**) repalloc(state->stmts, state->stmts_buf_size * sizeof(Node*));
 		}
-		state->stmts[state->stmts_count] = (CreateFunctionStmt *) node;
+		state->stmts[state->stmts_count] = (Node *) node;
 		state->stmts_count++;
 	} else if (IsA(node, RawStmt)) {
-		return create_function_stmts_walker((Node *) ((RawStmt *) node)->stmt, state);
+		return stmts_walker((Node *) ((RawStmt *) node)->stmt, state);
 	}
 
 	PG_TRY();
 	{
-		result = raw_expression_tree_walker(node, create_function_stmts_walker, (void*) state);
+		result = raw_expression_tree_walker(node, stmts_walker, (void*) state);
 	}
 	PG_CATCH();
 	{
@@ -381,7 +444,7 @@ PgQueryPlpgsqlParseResult pg_query_parse_plpgsql(const char* input)
 	MemoryContext ctx = NULL;
 	PgQueryPlpgsqlParseResult result = {0};
 	PgQueryInternalParsetreeAndError parse_result;
-	createFunctionStmts statements;
+	plStmts statements;
 	size_t i;
 
 	ctx = pg_query_enter_memory_context();
@@ -394,10 +457,10 @@ PgQueryPlpgsqlParseResult pg_query_parse_plpgsql(const char* input)
 	}
 
 	statements.stmts_buf_size = 100;
-	statements.stmts = (CreateFunctionStmt**) palloc(statements.stmts_buf_size * sizeof(CreateFunctionStmt*));
+	statements.stmts = (Node**) palloc(statements.stmts_buf_size * sizeof(Node*));
 	statements.stmts_count = 0;
 
-	create_function_stmts_walker((Node*) parse_result.tree, &statements);
+	stmts_walker((Node*) parse_result.tree, &statements);
 
 	if (statements.stmts_count == 0) {
 		result.plpgsql_funcs = strdup("[]");

data/ext/pg_query/pg_query_readfuncs_protobuf.c

@@ -74,6 +74,12 @@
 
 static Node * _readNode(PgQuery__Node *msg);
 
+static String *
+_readString(PgQuery__String* msg)
+{
+	return makeString(pstrdup(msg->sval));
+}
+
 #include "pg_query_enum_defs.c"
 #include "pg_query_readfuncs_defs.c"
 
@@ -96,17 +102,45 @@ static Node * _readNode(PgQuery__Node *msg)
 		case PG_QUERY__NODE__NODE_INTEGER:
 			return (Node *) makeInteger(msg->integer->ival);
 		case PG_QUERY__NODE__NODE_FLOAT:
-			return (Node *) makeFloat(pstrdup(msg->float_->str));
+			return (Node *) makeFloat(pstrdup(msg->float_->fval));
+		case PG_QUERY__NODE__NODE_BOOLEAN:
+			return (Node *) makeBoolean(msg->boolean->boolval);
 		case PG_QUERY__NODE__NODE_STRING:
-			return (Node *) makeString(pstrdup(msg->string->str));
+			return (Node *) makeString(pstrdup(msg->string->sval));
 		case PG_QUERY__NODE__NODE_BIT_STRING:
-			return (Node *) makeBitString(pstrdup(msg->bit_string->str));
-		case PG_QUERY__NODE__NODE_NULL:
-			{
-				Value *v = makeNode(Value);
-				v->type = T_Null;
-				return (Node *) v;
+			return (Node *) makeBitString(pstrdup(msg->bit_string->bsval));
+		case PG_QUERY__NODE__NODE_A_CONST: {
+			A_Const *ac = makeNode(A_Const);
+			ac->location = msg->a_const->location;
+
+			if (msg->a_const->isnull) {
+				ac->isnull = true;
+			} else {
+				switch (msg->a_const->val_case) {
+					case PG_QUERY__A__CONST__VAL_IVAL:
+						ac->val.ival = *makeInteger(msg->a_const->ival->ival);
+						break;
+					case PG_QUERY__A__CONST__VAL_FVAL:
+						ac->val.fval = *makeFloat(pstrdup(msg->a_const->fval->fval));
+						break;
+					case PG_QUERY__A__CONST__VAL_BOOLVAL:
+						ac->val.boolval = *makeBoolean(msg->a_const->boolval->boolval);
+						break;
+					case PG_QUERY__A__CONST__VAL_SVAL:
+						ac->val.sval = *makeString(pstrdup(msg->a_const->sval->sval));
+						break;
+					case PG_QUERY__A__CONST__VAL_BSVAL:
+						ac->val.bsval = *makeBitString(pstrdup(msg->a_const->bsval->bsval));
+						break;
+					case PG_QUERY__A__CONST__VAL__NOT_SET:
+					case _PG_QUERY__A__CONST__VAL__CASE_IS_INT_SIZE:
+						Assert(false);
+						break;
+				}
 			}
+
+			return (Node *) ac;
+		}
 		case PG_QUERY__NODE__NODE_LIST:
 			return (Node *) _readList(msg->list);
 		case PG_QUERY__NODE__NODE__NOT_SET:

data/ext/pg_query/pg_query_ruby.c

@@ -14,7 +14,7 @@ VALUE pg_query_ruby_fingerprint(VALUE self, VALUE input);
 VALUE pg_query_ruby_scan(VALUE self, VALUE input);
 VALUE pg_query_ruby_hash_xxh3_64(VALUE self, VALUE input, VALUE seed);
 
-void Init_pg_query(void)
+__attribute__((visibility ("default"))) void Init_pg_query(void)
 {
 	VALUE cPgQuery;
 

data/ext/pg_query/pg_query_scan.c

@@ -101,8 +101,9 @@ PgQueryScanResult pg_query_scan(const char* input)
       output_tokens[i]->token = tok;
 
       switch (tok) {
-      #define PG_KEYWORD(a,b,c) case b: output_tokens[i]->keyword_kind = c + 1; break;
+      #define PG_KEYWORD(a,b,c,d) case b: output_tokens[i]->keyword_kind = c + 1; break;
       #include "parser/kwlist.h"
+      #undef PG_KEYWORD
       default: output_tokens[i]->keyword_kind = 0;
       }
     }

data/ext/pg_query/pg_query_split.c

@@ -59,8 +59,9 @@ PgQuerySplitResult pg_query_split_with_scanner(const char* input)
     {
       int tok = core_yylex(&yylval, &yylloc, yyscanner);
       switch (tok) {
-      #define PG_KEYWORD(a,b,c) case b: is_keyword = true; break;
+      #define PG_KEYWORD(a,b,c,d) case b: is_keyword = true; break;
       #include "parser/kwlist.h"
+      #undef PG_KEYWORD
       default: is_keyword = false;
       }
       if (is_keyword)
@@ -88,7 +89,7 @@ PgQuerySplitResult pg_query_split_with_scanner(const char* input)
     {
       int tok = core_yylex(&yylval, &yylloc, yyscanner);
       switch (tok) {
-      #define PG_KEYWORD(a,b,c) case b: is_keyword = true; break;
+      #define PG_KEYWORD(a,b,c,d) case b: is_keyword = true; break;
       #include "parser/kwlist.h"
       default: is_keyword = false;
       }

data/ext/pg_query/src_backend_catalog_namespace.c

@@ -16,7 +16,7 @@
  * and implementing search-path-controlled searches.
  *
  *
- * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
  * IDENTIFICATION
@@ -62,6 +62,7 @@
 #include "utils/inval.h"
 #include "utils/lsyscache.h"
 #include "utils/memutils.h"
+#include "utils/snapmgr.h"
 #include "utils/syscache.h"
 #include "utils/varlena.h"
 
@@ -213,6 +214,7 @@ static void RemoveTempRelations(Oid tempNamespaceId);
 static void RemoveTempRelationsCallback(int code, Datum arg);
 static void NamespaceCallback(Datum arg, int cacheid, uint32 hashvalue);
 static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
+						   bool include_out_arguments, int pronargs,
 						   int **argnumbers);
 
 
@@ -355,6 +357,12 @@ static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
  * of additional args (which can be retrieved from the function's
  * proargdefaults entry).
  *
+ * If include_out_arguments is true, then OUT-mode arguments are considered to
+ * be included in the argument list.  Their types are included in the returned
+ * arrays, and argnumbers are indexes in proallargtypes not proargtypes.
+ * We also set nominalnargs to be the length of proallargtypes not proargtypes.
+ * Otherwise OUT-mode arguments are ignored.
+ *
  * It is not possible for nvargs and ndargs to both be nonzero in the same
  * list entry, since default insertion allows matches to functions with more
  * than nargs arguments while the variadic transformation requires the same
@@ -365,7 +373,8 @@ static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
  * first any positional arguments, then the named arguments, then defaulted
  * arguments (if needed and allowed by expand_defaults).  The argnumbers[]
  * array can be used to map this back to the catalog information.
- * argnumbers[k] is set to the proargtypes index of the k'th call argument.
+ * argnumbers[k] is set to the proargtypes or proallargtypes index of the
+ * k'th call argument.
  *
  * We search a single namespace if the function name is qualified, else
  * all namespaces in the search path.  In the multiple-namespace case,
@@ -389,7 +398,7 @@ static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
  * such an entry it should react as though the call were ambiguous.
  *
  * If missing_ok is true, an empty list (NULL) is returned if the name was
- * schema- qualified with a schema that does not exist.  Likewise if no
+ * schema-qualified with a schema that does not exist.  Likewise if no
  * candidate is found for other reasons.
  */
 
@@ -403,6 +412,10 @@ static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
  * the function, in positions after the last positional argument, and there
  * are defaults for all unsupplied arguments.
  *
+ * If include_out_arguments is true, we are treating OUT arguments as
+ * included in the argument list.  pronargs is the number of arguments
+ * we're considering (the length of either proargtypes or proallargtypes).
+ *
  * The number of positional arguments is nargs - list_length(argnames).
  * Note caller has already done basic checks on argument count.
  *
@@ -427,8 +440,7 @@ static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
  *		Given a possibly-qualified operator name and exact input datatypes,
  *		look up the operator.  Returns InvalidOid if not found.
  *
- * Pass oprleft = InvalidOid for a prefix op, oprright = InvalidOid for
- * a postfix op.
+ * Pass oprleft = InvalidOid for a prefix op.
  *
  * If the operator name is not schema-qualified, it is sought in the current
  * namespace search path.  If the name is schema-qualified and the given
@@ -450,8 +462,8 @@ static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
  * namespace case, we arrange for entries in earlier namespaces to mask
  * identical entries in later namespaces.
  *
- * The returned items always have two args[] entries --- one or the other
- * will be InvalidOid for a prefix or postfix oprkind.  nargs is 2, too.
+ * The returned items always have two args[] entries --- the first will be
+ * InvalidOid for a prefix oprkind.  nargs is always 2, too.
  */
 #define SPACE_PER_OP MAXALIGN(offsetof(struct _FuncCandidateList, args) + \
 							  2 * sizeof(Oid))
@@ -676,7 +688,7 @@ static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
 
 /*
  * QualifiedNameGetCreationNamespace
- *		Given a possibly-qualified name for an object (in List-of-Values
+ *		Given a possibly-qualified name for an object (in List-of-Strings
  *		format), determine what namespace the object should be created in.
  *		Also extract and return the object name (last component of list).
  *
@@ -709,7 +721,7 @@ static bool MatchNamedCall(HeapTuple proctup, int nargs, List *argnames,
  * This is used primarily to form error messages, and so we do not quote
  * the list elements, for the sake of legibility.
  *
- * In most scenarios the list elements should always be Value strings,
+ * In most scenarios the list elements should always be String values,
  * but we also allow A_Star for the convenience of ColumnRef processing.
  */
 char *

data/ext/pg_query/src_backend_catalog_pg_proc.c

@@ -9,7 +9,7 @@
  * pg_proc.c
  *	  routines to support manipulation of the pg_proc relation
  *
- * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
  *
@@ -38,8 +38,11 @@
 #include "mb/pg_wchar.h"
 #include "miscadmin.h"
 #include "nodes/nodeFuncs.h"
+#include "parser/analyze.h"
 #include "parser/parse_coerce.h"
 #include "parser/parse_type.h"
+#include "pgstat.h"
+#include "rewrite/rewriteHandler.h"
 #include "tcop/pquery.h"
 #include "tcop/tcopprot.h"
 #include "utils/acl.h"

data/ext/pg_query/src_backend_commands_define.c

@@ -10,7 +10,7 @@
  *	  Support routines for various kinds of object creation.
  *
  *
- * Portions Copyright (c) 1996-2020, PostgreSQL Global Development Group
+ * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
  *
@@ -92,6 +92,11 @@ defGetInt32(DefElem *def)
  */
 
 
+/*
+ * Extract an OID value from a DefElem.
+ */
+
+
 /*
  * Extract a possibly-qualified name (as a List of Strings) from a DefElem.
  */
@@ -115,3 +120,8 @@ defGetInt32(DefElem *def)
  * Extract a list of string values (otherwise uninterpreted) from a DefElem.
  */
 
+
+/*
+ * Raise an error about a conflicting DefElem.
+ */
+

data/ext/pg_query/src_backend_nodes_bitmapset.c

@@ -23,7 +23,7 @@
  * bms_is_empty() in preference to testing for NULL.)
  *
  *
- * Copyright (c) 2003-2020, PostgreSQL Global Development Group
+ * Copyright (c) 2003-2022, PostgreSQL Global Development Group
  *
  * IDENTIFICATION
  *	  src/backend/nodes/bitmapset.c
@@ -233,6 +233,8 @@ bms_free(Bitmapset *a)
 
 /*
  * bms_nonempty_difference - do sets have a nonempty difference?
+ *
+ * i.e., are any members set in 'a' that are not also set in 'b'.
  */