From 44651f1d53eae494f71e0b0c71674663902732f7 Mon Sep 17 00:00:00 2001
From: Stephan Hennig <sh2d@arcor.de>
Date: Tue, 7 May 2013 20:00:01 +0200
Subject: doc: Some user whatsit related documentation fixes.

---
 luatexbase-attr.dtx | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

(limited to 'luatexbase-attr.dtx')

diff --git a/luatexbase-attr.dtx b/luatexbase-attr.dtx
index d19240b..c6a7040 100644
--- a/luatexbase-attr.dtx
+++ b/luatexbase-attr.dtx
@@ -443,7 +443,11 @@ end
 luatexbase.unset_attribute = unset_attribute
 %    \end{macrocode}
 %
-%    User whatsit allocation (experimental).
+%   Allocation of user-defined whatsit nodes (experimental).
+%   User-defined whatsit nodes (or user whatsits) are ignored by the
+%   \luatex engine. They can thus be used to store information in
+%   node lists without doing any harm. User whatsits can be
+%   distinguished by an id that is stored in node field |user_id|.
 %
 %    \begin{macrocode}
 --- cf. luatexref-t.pdf, sect. 8.1.4.25
@@ -457,18 +461,18 @@ local anonymous_whatsits  = 0
 local anonymous_prefix    = "anon"
 %    \end{macrocode}
 %
-%    The whatsit allocation is split into two functions:
+%    User whatsit allocation is split into two functions:
 %    \verb|new_user_whatsit_id| registers a new id (an integer)
 %    and returns it. It is up to the user what he actually does
 %    with the return value.
 %
-%    Registering whatsits without a name, though supported, is
+%    Registering user whatsits without a name, though supported, is
 %    not exactly good style. In these cases we generate a name
 %    from a counter.
 %
-%    In addition to the whatsit name, it is possible and even
+%    In addition to the user whatsit name, it is possible and even
 %    encouraged to specify the name of the package that will be
-%    using the whatsit as the second argument.
+%    using the user whatsit as the second argument.
 %
 %    \begin{macrocode}
 --- string -> string -> int
@@ -512,7 +516,7 @@ luatexbase.new_user_whatsit_id = new_user_whatsit_id
 %    \end{macrocode}
 %
 %    \verb|new_user_whatsit| first registers a new id and then also
-%    creates the corresponding whatsit of subtype “user defined”.
+%    creates the corresponding whatsit node of subtype “user-defined”.
 %    We return a nullary function that delivers copies of the whatsit.
 %
 %    \begin{macrocode}
@@ -528,7 +532,7 @@ luatexbase.new_user_whatsit         = new_user_whatsit
 luatexbase.new_user_whatsit_factory = new_user_whatsit --- for Stephan
 %    \end{macrocode}
 %
-%    If one knows the name of a whatsit, its corresponding id
+%    If one knows the name of a user whatsit, its corresponding id
 %    can be retrieved by means of \verb|get_user_whatsit_id|.
 %
 %    \begin{macrocode}
@@ -545,11 +549,11 @@ luatexbase.get_user_whatsit_id = get_user_whatsit_id
 %    The inverse lookup is also possible via \verb|get_user_whatsit_name|.
 %    Here it finally becomes obvious why it is beneficial to supply a package
 %    name -- it adds information about who created and might be relying on the
-%    whatsit in question. First return value is the whatsit name, the second
-%    the package identifier it was registered with.
+%    user whatsit in question. First return value is the user whatsit name, the
+%    second the package identifier it was registered with.
 %
-%    We issue a warning and return empty strings in case the asked whatsit is
-%    unregistered.
+%    We issue a warning and return empty strings in case the argument
+%    doesn't correspond to a registered user whatsit id.
 %
 %    \begin{macrocode}
 --- int | fun | node -> (string, string)
-- 
cgit v1.2.3


From 3260c403de194f3001e1ffac32ab32c7bc79d481 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg42.2a@gmail.com>
Date: Thu, 16 May 2013 21:52:25 +0200
Subject: add function to retrieve attribute unset value

---
 luatexbase-attr.dtx | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'luatexbase-attr.dtx')

diff --git a/luatexbase-attr.dtx b/luatexbase-attr.dtx
index c6a7040..499677d 100644
--- a/luatexbase-attr.dtx
+++ b/luatexbase-attr.dtx
@@ -434,6 +434,8 @@ luatexbase.new_attribute = new_attribute
 %    \end{macrocode}
 %
 %    Unset an attribute the correct way depending on \luatex's version.
+%    The constant \verb+unset_value+ can be retrieved by calling
+%    \verb+get_unset_value()+ to apply to nodes.
 %
 %    \begin{macrocode}
 local unset_value = (luatexbase.luatexversion < 37) and -1 or -2147483647
@@ -441,6 +443,7 @@ function unset_attribute(name)
     tex.setattribute(attributes[name], unset_value)
 end
 luatexbase.unset_attribute = unset_attribute
+luatexbase.get_unset_value = function () return unset_value end
 %    \end{macrocode}
 %
 %   Allocation of user-defined whatsit nodes (experimental).
-- 
cgit v1.2.3


From f173f5c12fe3f8741451ae643ab56320c112fc52 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg42.2a@gmail.com>
Date: Tue, 7 May 2013 18:05:45 +0200
Subject: make user whatsit generators accept an optional argument of type node

---
 luatexbase-attr.dtx | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

(limited to 'luatexbase-attr.dtx')

diff --git a/luatexbase-attr.dtx b/luatexbase-attr.dtx
index 499677d..3e01827 100644
--- a/luatexbase-attr.dtx
+++ b/luatexbase-attr.dtx
@@ -529,10 +529,24 @@ local new_user_whatsit = function (name, package)
     local whatsit    = newnode(whatsit_t, user_defined_t)
     whatsit.user_id  = id
     --- unit -> node_t
-    return function ( ) return copynode(whatsit) end, id
+    local generator = function (proto)
+        local res
+        if proto then
+            local proto_id = proto.user_id
+            if proto_id ~= id then --- mismatch
+                warning("overriding user_id %d of whatsit prototype (now: %d)",
+                        proto.user_id, id)
+            end
+            res = copynode(proto)
+            res.user_id = id
+        else
+            res = copynode(whatsit)
+        end
+        return res
+    end
+    return generator, id
 end
 luatexbase.new_user_whatsit         = new_user_whatsit
-luatexbase.new_user_whatsit_factory = new_user_whatsit --- for Stephan
 %    \end{macrocode}
 %
 %    If one knows the name of a user whatsit, its corresponding id
-- 
cgit v1.2.3


From a9178223ec8b11a5de7937e3bd5f4492eb6ceea6 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg42.2a@gmail.com>
Date: Fri, 17 May 2013 17:37:18 +0200
Subject: have ``new_user_whatsit()`` accept prototype as first argument

---
 luatexbase-attr.dtx | 39 ++++++++++++++++-----------------------
 1 file changed, 16 insertions(+), 23 deletions(-)

(limited to 'luatexbase-attr.dtx')

diff --git a/luatexbase-attr.dtx b/luatexbase-attr.dtx
index 3e01827..f10e2de 100644
--- a/luatexbase-attr.dtx
+++ b/luatexbase-attr.dtx
@@ -262,7 +262,7 @@ See the aforementioned source file(s) for copyright and licensing information.
 %
 %    \subsubsection{Primitives needed}
 %
-%    First load \pk{luatexbase-modutils} (hence \pk{luatexbase-loader} 
+%    First load \pk{luatexbase-modutils} (hence \pk{luatexbase-loader}
 %    and \pk{luatexbase-compat}), and make sure \pk{luatex.sty} is loaded too.
 %
 %    \begin{macrocode}
@@ -523,28 +523,22 @@ luatexbase.new_user_whatsit_id = new_user_whatsit_id
 %    We return a nullary function that delivers copies of the whatsit.
 %
 %    \begin{macrocode}
---- string -> string -> (unit -> node_t, int)
-local new_user_whatsit = function (name, package)
-    local id         = new_user_whatsit_id(name, package)
-    local whatsit    = newnode(whatsit_t, user_defined_t)
-    whatsit.user_id  = id
-    --- unit -> node_t
-    local generator = function (proto)
-        local res
-        if proto then
-            local proto_id = proto.user_id
-            if proto_id ~= id then --- mismatch
-                warning("overriding user_id %d of whatsit prototype (now: %d)",
-                        proto.user_id, id)
-            end
-            res = copynode(proto)
-            res.user_id = id
-        else
-            res = copynode(whatsit)
+--- (string | node_t) -> string -> ((unit -> node_t) * int)
+local new_user_whatsit = function (req, package)
+    local id, whatsit
+    if type(req) == "string" then
+        id              = new_user_whatsit_id(req, package)
+        whatsit         = newnode(whatsit_t, user_defined_t)
+        whatsit.user_id = id
+    else -- node
+        id      = req.user_id
+        whatsit = copynode(req)
+        if not whatsit_ids[id] then
+            warning("whatsit id %d unregistered; "
+                    .. "inconsistencies may arise", id)
         end
-        return res
     end
-    return generator, id
+    return function () return copynode(whatsit) end, id
 end
 luatexbase.new_user_whatsit         = new_user_whatsit
 %    \end{macrocode}
@@ -632,7 +626,7 @@ local dump_registered_whatsits = function (asked_package)
     --- mess up line breaking, so concatenation is unusable ...
     local first = true
     for i=1, #whatsit_list do
-        if first then 
+        if first then
             first = false
         else -- indent
             texiowrite_nl"  "
@@ -647,7 +641,6 @@ luatexbase.dump_registered_whatsits = dump_registered_whatsits
 %    \begin{macrocode}
 luatexbase.newattribute            = new_attribute
 luatexbase.newuserwhatsit          = new_user_whatsit
-luatexbase.newuserwhatsitfactory   = new_user_whatsit_factory
 luatexbase.newuserwhatsitid        = new_user_whatsit_id
 luatexbase.getuserwhatsitid        = get_user_whatsit_id
 luatexbase.getuserwhatsitname      = get_user_whatsit_name
-- 
cgit v1.2.3


From e824f2826911dc90e022c522b8ad6531447c5219 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg42.2a@gmail.com>
Date: Fri, 17 May 2013 17:49:08 +0200
Subject: document alternate behavior of ``new_user_whatsit()``

---
 luatexbase-attr.dtx | 5 +++++
 1 file changed, 5 insertions(+)

(limited to 'luatexbase-attr.dtx')

diff --git a/luatexbase-attr.dtx b/luatexbase-attr.dtx
index f10e2de..638cd31 100644
--- a/luatexbase-attr.dtx
+++ b/luatexbase-attr.dtx
@@ -522,6 +522,11 @@ luatexbase.new_user_whatsit_id = new_user_whatsit_id
 %    creates the corresponding whatsit node of subtype “user-defined”.
 %    We return a nullary function that delivers copies of the whatsit.
 %
+%    Alternatively, the first argument can be a whatsit node that
+%    will then be used as prototype. Note that in this case a
+%    \emph{copy} of the prototype will be stored in the closure,
+%    eliminating side-effects.
+%
 %    \begin{macrocode}
 --- (string | node_t) -> string -> ((unit -> node_t) * int)
 local new_user_whatsit = function (req, package)
-- 
cgit v1.2.3


From 4804f72d73d764f3320742348273bd2b98d7f306 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <phg42.2a@gmail.com>
Date: Fri, 17 May 2013 17:55:38 +0200
Subject: reintroduce checks for prototype validity

---
 luatexbase-attr.dtx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'luatexbase-attr.dtx')

diff --git a/luatexbase-attr.dtx b/luatexbase-attr.dtx
index 638cd31..5b7288f 100644
--- a/luatexbase-attr.dtx
+++ b/luatexbase-attr.dtx
@@ -535,7 +535,7 @@ local new_user_whatsit = function (req, package)
         id              = new_user_whatsit_id(req, package)
         whatsit         = newnode(whatsit_t, user_defined_t)
         whatsit.user_id = id
-    else -- node
+    elseif req.id == whatsit_t and req.subtype == user_defined_t then
         id      = req.user_id
         whatsit = copynode(req)
         if not whatsit_ids[id] then
-- 
cgit v1.2.3

