From af91e7e35cd8277c3a437d9dfddea4c5c313a656 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Tue, 24 Jan 2017 11:14:41 -0800
Subject: Expose plist to alist functions.

* eval.c (eval_init): Register plist-to-alist and
improper-plist-to-alist intrinsics.

* txr.1: Documented improper plist concept and new
functions.
---
 eval.c |  2 ++
 txr.1  | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/eval.c b/eval.c
index 8adea078..bdb1f0a7 100644
--- a/eval.c
+++ b/eval.c
@@ -5801,6 +5801,8 @@ void eval_init(void)
   reg_fun(intern(lit("copy-alist"), user_package), func_n1(copy_alist));
   reg_fun(intern(lit("prop"), user_package), func_n2(getplist));
   reg_fun(intern(lit("memp"), user_package), func_n2(memp));
+  reg_fun(intern(lit("plist-to-alist"), user_package), func_n1(plist_to_alist));
+  reg_fun(intern(lit("improper-plist-to-alist"), user_package), func_n2(improper_plist_to_alist));
   reg_fun(intern(lit("merge"), user_package), func_n4o(merge_wrap, 2));
   reg_fun(intern(lit("sort"), user_package), func_n3o(sort, 1));
   reg_fun(intern(lit("shuffle"), user_package), func_n1(shuffle));
diff --git a/txr.1 b/txr.1
index 198cca4b..c0ce427b 100644
--- a/txr.1
+++ b/txr.1
@@ -18184,11 +18184,36 @@ function applied to the corresponding
 element of the input list.
 
 .SS* Property Lists
-A property list a flat list of even length consisting of interleaved
+A
+.IR "property list",
+also referred to as a
+.IR plist ,
+is a flat list of even length consisting of interleaved
 pairs of property names (usually symbols) and their values (arbitrary
 objects). An example property list is (:a 1 :b "two") which contains
 two properties, :a having value 1, and :b having value "two".
 
+An
+.I "improper plist"
+represents Boolean properties in a condensed way, as property
+indicators which are not followed by a value. Such properties
+only indicate their presence or absence, which is useful for
+encoding a Boolean value. If it is absent, then the property
+is false. Correctly using an improper plist requires that the
+exact set of Boolean keys is established by convention.
+
+In this document, the unqualified terms
+.I "property list"
+and
+.I "plist"
+refer strictly to an ordinary plist, not to an improper plist.
+
+.TP* "Dialect Note:"
+
+Unlike in some other Lisp dialects, including ANSI Common Lisp,
+symbols do not have property lists in \*(TL. Improper plists
+aren't a concept in ANSI CL.
+
 .coNP Function @ prop
 .synb
 .mets (prop < plist << key )
@@ -18249,6 +18274,47 @@ function, harmonizing with functions in the
 .code member
 family.
 
+.coNP Functions @ plist-to-alist and @ improper-plist-to-alist
+.synb
+.mets (plist-to-alist << plist )
+.mets (improper-plist-to-alist < imp-plist << bool-keys )
+.syne
+.desc
+The functions
+.code plist-to-alist
+and
+.code improper-plist-to-alist
+convert, respectively, a property list and improper property
+list to an association list.
+
+The
+.code plist-to-alist
+function scans
+.meta plist
+and returns the indicator-property pairs as a list of cons
+cells, such that each
+.code car
+is the indicator, and each
+.code cdr
+is the value.
+
+The
+.code improper-plist-to-alist
+is similar, except that it handles the Boolean properties
+which, by convention, aren't followed by a value. The list of
+all such indicators is specified by the
+.code bool-keys
+argument.
+
+.TP* "Examples:"
+.cblk
+  (plist-to-alist '(a 1 b 2))  -->  ((a . 1) (b . 2))
+
+  (improper-plist-to-alist '(:x 1 :blue :y 2) '(:blue))
+  -->  ((:x . 1) (:blue) (:y . 2))
+.cble
+
+
 .SS* List Sorting
 
 Note: these functions operate on lists. The principal sorting function
-- 
cgit v1.2.3