[elpa] externals/taxy bee2f48: Docs: Add function/macro reference

[ELPA Syncer]

branch: externals/taxy
commit bee2f48d1313e24a07042a10ee8b17efac24221a
Author: Adam Porter <adam@alphapapa.net>
Commit: Adam Porter <adam@alphapapa.net>

    Docs: Add function/macro reference
---
 README.org |  59 ++++++++++++++++++++
 taxy.info  | 180 ++++++++++++++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 201 insertions(+), 38 deletions(-)

diff --git a/README.org b/README.org
index 98498f4..2ccc4e8 100644
--- a/README.org
+++ b/README.org
@@ -433,6 +433,7 @@ Some example applications may be found in the 
[[file:examples/][examples directo
 - [[#modifying-filled-taxys][Modifying filled taxys]]
 - [[#dynamic-taxys][Dynamic taxys]]
 - [[#magit-section][Magit section]]
+- [[#reference][Reference]]
 :END:
 
 A taxy is defined with the ~make-taxy~ constructor, like:
@@ -878,6 +879,64 @@ That shows a buffer like this:
 
 Note that while =taxy-magit-section.el= is installed with the =taxy= package, 
the =magit-section= package is not automatically installed with it.
 
+** Reference
+
+*** Functions
+
+**** taxy-flatten (taxy)
+
+Return a list of items in =taxy= and its sub-taxys.
+
+**** taxy-emptied (taxy)
+
+Return a copy of =taxy= without items.  Omits =taxy=’s items and those of its 
descendant taxys.  Useful when reusing taxy definitions.
+
+**** taxy-fill (items taxy)
+
+Fill =taxy= with =items= according to its definition.
+
+**** taxy-make-take-function (keys aliases)
+
+Return a taxy "take" function for =keys=.  Each of =keys= should be a function 
alias defined in =aliases=, or a list of such =key-fns= (recursively, ad 
infinitum, approximately).  =aliases= should be an alist mapping aliases to 
functions (such as defined with a definer defined by ~taxy-define-key-definer~).
+
+**** taxy-mapc-taxys (fn taxy)
+
+*Alias:* ~taxy-mapc*~
+
+Return =taxy= having applied =fn= to it and its descendants.  Does not copy 
=taxy=.  Destructively modifies =taxy=, if =fn= does.
+
+**** taxy-mapcar-items (fn taxy)
+
+*Alias:* ~taxy-mapcar~
+
+Return copy of =taxy=, having replaced its items with the value of =fn= on 
each.  Replaces every item in =taxy= and its descendants.  Useful to replace 
items with a more useful form after classification.
+
+**** taxy-plain (taxy)
+
+Return a list of the human-readable parts of =taxy=.
+
+**** taxy-size (taxy)
+
+Return the number of items =taxy= holds.  Includes items in =taxy= ’s 
sub-taxys.
+
+**** taxy-sort-items (pred key taxy)
+
+*Alias:* ~taxy-sort~
+
+Sort =taxy= ’s items by =pred= and =key=.  Sorts items in =taxy= and its 
sub-taxys.  =key= is passed to ~cl-sort~, which see.
+
+**** taxy-sort-taxys (pred key taxy)
+
+*Alias:* ~taxy-sort*~
+
+Sort =taxy= ’s sub-taxys by =pred= and =key=.  =key= is passed to ~cl-sort~, 
which see.
+
+*** Macros
+
+**** taxy-define-key-definer (name variable prefix docstring)
+
+Define a macro =name= that defines a key-function-defining macro.  The defined 
macro, having string =docstring=, associates the defined key functions with 
their aliases in an alist stored in symbol =variable=.  The defined key 
functions are named having string =prefix=, which will have a hyphen appended 
to it.  The key functions take one or more arguments, the first of which is the 
item being tested, bound within the function to ~item~.
+
 * Changelog
 :PROPERTIES:
 :TOC:      :depth 0
diff --git a/taxy.info b/taxy.info
index 21e9766..2d45cf9 100644
--- a/taxy.info
+++ b/taxy.info
@@ -61,6 +61,7 @@ Usage
 * Modifying filled taxys::
 * Dynamic taxys::
 * Magit section::
+* Reference::
 
 Dynamic taxys
 
@@ -68,6 +69,11 @@ Dynamic taxys
 * "Chains" of independent, multi-level dynamic taxys: "Chains" of independent 
multi-level dynamic taxys.
 * Defining a classification domain-specific language::
 
+Reference
+
+* Functions::
+* Macros::
+
 Changelog
 
 * 0.7-pre: 07-pre.
@@ -510,7 +516,7 @@ File: README.info,  Node: Usage,  Next: Changelog,  Prev: 
Installation,  Up: Top
 3 Usage
 *******
 
-   • • • • • 
+   • • • • • • 
    A taxy is defined with the ‘make-taxy’ constructor, like:
 
      (make-taxy :name "Numbery"
@@ -553,6 +559,7 @@ replace items in a taxy with, e.g.  a more useful 
representation.
 * Modifying filled taxys::
 * Dynamic taxys::
 * Magit section::
+* Reference::
 
 
 File: README.info,  Node: Reusable taxys,  Next: Threading macros,  Up: Usage
@@ -1003,7 +1010,7 @@ function so that users can pass their own list of keys:
           ("Soccer" "Tennis" "Football" "Baseball"))))))
 
 
-File: README.info,  Node: Magit section,  Prev: Dynamic taxys,  Up: Usage
+File: README.info,  Node: Magit section,  Next: Reference,  Prev: Dynamic 
taxys,  Up: Usage
 
 3.5 Magit section
 =================
@@ -1025,6 +1032,100 @@ package, the ‘magit-section’ package is not 
automatically installed with
 it.
 
 
+File: README.info,  Node: Reference,  Prev: Magit section,  Up: Usage
+
+3.6 Reference
+=============
+
+* Menu:
+
+* Functions::
+* Macros::
+
+
+File: README.info,  Node: Functions,  Next: Macros,  Up: Reference
+
+3.6.1 Functions
+---------------
+
+  1. taxy-flatten (taxy)
+
+     Return a list of items in ‘taxy’ and its sub-taxys.
+
+  2. taxy-emptied (taxy)
+
+     Return a copy of ‘taxy’ without items.  Omits =taxy=’s items and
+     those of its descendant taxys.  Useful when reusing taxy
+     definitions.
+
+  3. taxy-fill (items taxy)
+
+     Fill ‘taxy’ with ‘items’ according to its definition.
+
+  4. taxy-make-take-function (keys aliases)
+
+     Return a taxy "take" function for ‘keys’.  Each of ‘keys’ should be
+     a function alias defined in ‘aliases’, or a list of such ‘key-fns’
+     (recursively, ad infinitum, approximately).  ‘aliases’ should be an
+     alist mapping aliases to functions (such as defined with a definer
+     defined by ‘taxy-define-key-definer’).
+
+  5. taxy-mapc-taxys (fn taxy)
+
+     *Alias:* ‘taxy-mapc*’
+
+     Return ‘taxy’ having applied ‘fn’ to it and its descendants.  Does
+     not copy ‘taxy’.  Destructively modifies ‘taxy’, if ‘fn’ does.
+
+  6. taxy-mapcar-items (fn taxy)
+
+     *Alias:* ‘taxy-mapcar’
+
+     Return copy of ‘taxy’, having replaced its items with the value of
+     ‘fn’ on each.  Replaces every item in ‘taxy’ and its descendants.
+     Useful to replace items with a more useful form after
+     classification.
+
+  7. taxy-plain (taxy)
+
+     Return a list of the human-readable parts of ‘taxy’.
+
+  8. taxy-size (taxy)
+
+     Return the number of items ‘taxy’ holds.  Includes items in ‘taxy’
+     ’s sub-taxys.
+
+  9. taxy-sort-items (pred key taxy)
+
+     *Alias:* ‘taxy-sort’
+
+     Sort ‘taxy’ ’s items by ‘pred’ and ‘key’.  Sorts items in ‘taxy’
+     and its sub-taxys.  ‘key’ is passed to ‘cl-sort’, which see.
+
+  10. taxy-sort-taxys (pred key taxy)
+
+     *Alias:* ‘taxy-sort*’
+
+     Sort ‘taxy’ ’s sub-taxys by ‘pred’ and ‘key’.  ‘key’ is passed to
+     ‘cl-sort’, which see.
+
+
+File: README.info,  Node: Macros,  Prev: Functions,  Up: Reference
+
+3.6.2 Macros
+------------
+
+  1. taxy-define-key-definer (name variable prefix docstring)
+
+     Define a macro ‘name’ that defines a key-function-defining macro.
+     The defined macro, having string ‘docstring’, associates the
+     defined key functions with their aliases in an alist stored in
+     symbol ‘variable’.  The defined key functions are named having
+     string ‘prefix’, which will have a hyphen appended to it.  The key
+     functions take one or more arguments, the first of which is the
+     item being tested, bound within the function to ‘item’.
+
+
 File: README.info,  Node: Changelog,  Next: Development,  Prev: Usage,  Up: Top
 
 4 Changelog
@@ -1288,42 +1389,45 @@ GPLv3
 
 Tag Table:
 Node: Top218
-Node: Examples2123
-Node: Numbery (starting basically)2442
-Node: Lettery (filling incrementally)8203
-Node: Sporty (understanding completely)10717
-Node: Applications16704
-Node: Installation17179
-Node: Usage17492
-Node: Reusable taxys19629
-Node: Threading macros23782
-Node: Modifying filled taxys24321
-Node: Dynamic taxys25139
-Node: Multi-level dynamic taxys27788
-Node: "Chains" of independent multi-level dynamic taxys29981
-Node: Defining a classification domain-specific language32912
-Node: Magit section37075
-Node: Changelog37754
-Node: 07-pre37957
-Node: Additions38069
-Node: 0638252
-Node: Additions (1)38381
-Node: 0539731
-Node: Additions (2)39866
-Node: Fixes40972
-Node: 0441126
-Node: 0341348
-Node: Changes41477
-Node: Fixes (1)41840
-Node: 0242275
-Node: Changes (1)42444
-Node: Additions (3)42736
-Node: Fixes (2)43595
-Node: 0143849
-Node: Development43948
-Node: Copyright assignment44154
-Node: Credits44742
-Node: License44932
+Node: Examples2174
+Node: Numbery (starting basically)2493
+Node: Lettery (filling incrementally)8254
+Node: Sporty (understanding completely)10768
+Node: Applications16755
+Node: Installation17230
+Node: Usage17543
+Node: Reusable taxys19698
+Node: Threading macros23851
+Node: Modifying filled taxys24390
+Node: Dynamic taxys25208
+Node: Multi-level dynamic taxys27857
+Node: "Chains" of independent multi-level dynamic taxys30050
+Node: Defining a classification domain-specific language32981
+Node: Magit section37144
+Node: Reference37841
+Node: Functions37978
+Node: Macros40017
+Node: Changelog40673
+Node: 07-pre40876
+Node: Additions40988
+Node: 0641171
+Node: Additions (1)41300
+Node: 0542650
+Node: Additions (2)42785
+Node: Fixes43891
+Node: 0444045
+Node: 0344267
+Node: Changes44396
+Node: Fixes (1)44759
+Node: 0245194
+Node: Changes (1)45363
+Node: Additions (3)45655
+Node: Fixes (2)46514
+Node: 0146768
+Node: Development46867
+Node: Copyright assignment47073
+Node: Credits47661
+Node: License47851
 
 End Tag Table