Reliably getting access to a prefix's arguments in :description's during refresh

[jdtsmith]

With :refresh-suffixes t you can use lambda functions in :descriptions for infix options as well as suffixes (or even sections). This allows providing much more "guidance" to users. E.g. in the new gptel-menu, instead of just "Return", we say:

The technique I've been using for this, which works both before and after "export" of transient-current-command is as follows:

(defmacro with-transient-args (func)
  "Call FUNC with transient args."
  (let ((argsvar (make-symbol "arg")))
    `(let ((,argsvar
	    (or (and transient-current-command (transient-args transient-current-command))
		;; not yet exported, simulate
		(let* ((transient-current-command (oref transient--prefix command))
		       (transient-current-suffixes transient--suffixes))
		  (transient-args transient-current-command)))))
      (funcall #',func ,argsvar))))

I do not like the use of the internal transient--prefix|suffixes variables, so was delighted to see this post mentioning transient-current-object. I can replace transient--prefix with (transient-prefix-object) and that works fine. But I still need to bind transient-current-suffixes like that, or it will result in infinite recursion when wrapped functions are called.

I'm not sure why but I conjecture that the suffixes are being re-built from scratch, which calls a suffix's :description lambda, which indeed calls the same function again.

Is there a simpler/better/more future-proof way to do this?

[tarsius]

I would like to see the branch where you use that macro. Also please create a prefix whose sole purpose is to demonstrate the issue at hand.

Update: Is that what you are looking for?:

(transient-define-prefix demo ()
  :refresh-suffixes t
  [:description
   (lambda () (format "Active arguments: %S" (transient-get-value)))
   ("-a" "a" "-a")
   ("-b" "b" "-b")
   (transient-echo-arguments)])

[jdtsmith]

Update: I just tried transient-get-value and it seems to work, both when the prefix is active and in the return action!

(defun my/one-val ()
  (let ((args (transient-get-value)))
    (when-let ((val (transient-arg-value "--oneval=" args)))
      (string-to-number val))))

But honestly I'm not sure I understand it. Is it returning the same thing transient-args would return? It doesn't seem to reference the current prefix at all. This seems like a super-powered peer of transient-args which would be incredibly useful for people building dynamic transients. IS IT REALLY THAT EASY!? Paging @karthink.

++++

You can see GPTEL's recent commit which incorporated this technique here.

Here's a highly contrived example, using the value of one infix to live-update various descriptions, an :inapt-if-not, and the return action. Here I don't get infinite recursion if transient-current-suffixes is omitted, but some of the descriptions do not update if that's missing.

(defun my/one-val ()
  (let ((args
         (or (and transient-current-command (transient-args transient-current-command))
	     ;; not yet exported, consult current prefix object
	     (let* ((transient-current-command
                     (oref (transient-prefix-object) command))
		    (transient-current-suffixes transient--suffixes))
	       (transient-args transient-current-command)))))
    (when-let ((val (transient-arg-value "--oneval=" args)))
      (string-to-number val))))

(defun my/return-action (val)
  (interactive (list (my/one-val)))
  (message "Returned with %s %s" (if val "one-val!" "another :/") val))

(transient-define-prefix my/responsive-prefix ()
  :refresh-suffixes t
  :value (lambda () `(,(format "--oneval=%d" (random 10))))
  
  [:description
   (lambda () (if-let ((v (my/one-val)) ( (and v (> v 5)))) "Good Options" "Bad Options"))
   (("-o" "--oneval=") :description "One Value")
   (("-a" "--anotherval=") :description "Another Value"
    :inapt-if-not (lambda () (my/one-val)))]

  ["Action:"
   ("RET" my/return-action
    :description
    (lambda ()
      (let ((ov (my/one-val)))
        (if ov "Do one action" "Do another action"))))])

[tarsius]

But honestly I'm not sure I understand it. Is it returning the same thing transient-args would return?

As the docstring mentions, it does not include the values of "unsavable" suffixes. That's because it was original intended to be used when saving values. If and once someone needs those unsavable values too, then I can add an argument to not strip those.

It doesn't seem to reference the current prefix at all.

When a prefix created, the individual values of its suffixes are set based on its value. This is the only time the "live" value of the prefix is sure to be up-to-date. When the user changes the value of a suffix, this does not change the value of the prefix. When a suffix requests the value of the prefix from which it was invoked, that value has to be collected, transient-args does that.

Look at transient-args and the functions it calls to see how it does that. It is very little code. Just about four functions in (which are defined right next to each other) and after reading ten or so lines of code, you can see the values being collected.

The code-path not taken in this case are for when the suffix was not invoked from its usual prefix. In that case transient-args needs to know the prefix so that it can get the set/save/default value of that prefix. It also needs to know the prefix when invoked from a prefix, to determine whether it happens to be the prefix whose value we are interested in. (If a user for some reason adds a diff suffix command to the log menu, then we don't want to pass log arguments to git diff.)

In your case you want to do something with the value of the current prefix, from code clearly associated with the current prefix. There is no need to detect whether it is the correct prefix; it by definition is. Since the live value lives inside the individual suffixes, there is no need to deal with the prefix and we can go straight to collecting the suffix values. That's what transient-get-value does.

This seems like a super-powered peer of transient-args which would be incredibly useful for people building dynamic transients.

It's less "powerful". It only collects the value of the suffixes of the current prefix, whatever that may be. transient-args on the other hand can validate the identity of the prefix and fall back to the set/saved/default value. But "power" is really beside the point. These functions both return "the value" but are intended to be used at different times.

[jdtsmith]

OK, thanks for the explanation. I have read the code but the confusion among prefix/prefix command/infix/suffix makes it hard for me to reason about. We've talked about that over the years.

These functions both return "the value" but are intended to be used at different times.

For a single prefix, I claim it is more powerful than transient-args in that it can provide infix values [1] both "during" and "after". But I take your point about nested prefixes. In any case, it's working great for my application (and would for @karthink's as well!).

[1] Which I think you call suffix values... confusing because "proper" suffixes, the kind that exit the prefix, have no value...

[tarsius]

OK, thanks for the explanation. I have read the code but the confusion among prefix/prefix command/infix/suffix makes it hard for me to reason about. We've talked about that over the years.

These functions both return "the value" but are intended to be used at different times.

For a single prefix, I claim it is more powerful than transient-args in that it can provide infix values [1] both "during" and "after".

"after" it might return the set/saved/default value of the wrong prefix, so you should not be used at this time.

[1] Which I think you call suffix values... confusing because "proper" suffixes, the kind that exit the prefix, have no value...

Maybe I have accidentally called the prefix value "suffix value" before, but not intentionally.

[jdtsmith]

By "after" in meant a suffix's return action function, but maybe that's still considered "during". The confusion is infix vs. suffix not prefix vs. suffix. So a prefix's value is the aggregate value of all of its infixes (and sub-prefix infixes). Anyway, I think I have a slightly better mental model now.

[tarsius]

By "after" in meant a suffix's return action function, but maybe that's still considered "during".

Yeah, it is in the "pre-commands"/"return action functions" where it is decided whether transient-args can be used by the command. They either call transient--export or they don't.

(defun transient--export ()
  (setq transient-current-prefix transient--prefix)
  (setq transient-current-command (oref transient--prefix command))
  (setq transient-current-suffixes transient--suffixes)
  (transient--history-push transient--prefix))

The pre-commands (called on pre-command-hook) also control (via their return value) whether the menu is exited or not. The menu is ultimately exited using a function on post-command-hook. But transient--export is called directly in the pre-commands; i.e., before the actual command runs. After (and if) that has happened, then transient-current-prefix et al., and ultimately transient-args can be used to access the "active" value, much like one would access the current-prefix-arg.

The function on post-command-hook which decides whether to exit the menu is transient--post-command. Note how that also sets the variables (were set non-nil in transient--export) to nil again.

In other words, these variables are only ever have a meaninfull (i.e., non-nil) value while a command is being called, and only if it was called from the a prefix, and only if the pre-command did actually call transient--export. Only if all that is the case does transient-args return the "active" value of "the prefix". Otherwise it returns the set/saved/default value of the prefix (which is useful if the command is invoked directly, instead of from the appropriate menu). transient-args is for use "in commands", like current-prefix-arg is. That is, in their interactive form and/or their function body.

transient-get-value returns the value of the current menu while the menu is still active. Instead of that we could theoretically use (oref transient--prefix value); but that doesn't work given the current implementation because the value of that slot is not being kept up-to-date.

transient-get-value was originally intended to be used when saving the value of the menu for future invocations. It is also used when suspending a menu (ultimately another form of saving the value).

But it turned out that it may also be necessary to access the active value of the active menu, when doing "other menu things" as well, e.g., what you are doing: displaying the active value in an aggregated form instead / in addition to displaying each "value-bearing" suffix's (~= infix) value individually.

Put differently, transient-get-value is for side-effects, for visualizing state. transient-args is for passing values to consumers such as git or a LLM.

[jdtsmith]

Thanks very much for this detailed rationale and explanation.