manual: Document transient-scope

1 files changed, 41 insertions, 0 deletions

diff --git a/docs/transient.org b/docs/transient.org
index 2a9dbc2..5c27813 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -1383,6 +1383,47 @@ function, which for infix arguments serves about the same purpose as
   used if you need the objects (as opposed to just their values) and
   if the current command is not being invoked from {{{var(PREFIX)}}}.
 
+** Using Prefix Scope
+
+Some transients have a sort of secondary value, called a scope.  A
+prefix's scope can be accessed using ~transient-scope~; similar to how
+its value can be accessed using ~transient-args~.
+
+- Function: transient-scope prefixes classes ::
+
+  This function returns the scope of the active or current transient
+  prefix command.
+
+  If optional PREFIXES and CLASSES are both nil, return the scope of
+  the prefix currently being setup, making this variation useful, e.g.,
+  in ~:if*~ predicates.  If no prefix is being setup, but the current
+  command was invoked from some prefix, then return the scope of that.
+
+  If PREFIXES is non-nil, it must be a prefix command or a list of such
+  commands.  If CLASSES is non-nil, it must be a prefix class or a list
+  of such classes.  When this function is called from the body or the
+  ~interactive~ form of a suffix command, PREFIXES and/or CLASSES should
+  be non-nil.  If either is non-nil, try the following in order:
+
+  - If the current suffix command was invoked from a prefix, which
+    appears in PREFIXES, return the scope of that prefix.
+
+  - If the current suffix command was invoked from a prefix, and its
+    class derives from one of the CLASSES, return the scope of that
+    prefix.
+
+  - If a prefix is being setup and it appears in PREFIXES, return its
+    scope.
+
+  - If a prefix is being setup and its class derives from one of the
+    CLASSES, return its scope.
+
+  - Finally try to return the default scope of the first command in
+    PREFIXES.  This only works if that slot is set in the respective
+    class definition or using its `transient-init-scope' method.
+
+  If no prefix matches, return nil.
+
 ** Current Suffix Command
 
 - Function: transient-suffix-object command ::