Eli Zaretskii writes: >> From: sbaugh@catern.com >> Date: Sat, 23 Sep 2023 20:24:07 +0000 (UTC) >> Cc: 65902@debbugs.gnu.org, sbaugh@janestreet.com, jporterbugs@gmail.com >> >> > IIUC, this kind of solution is fine by me, but the protocol of >> > accessing and using server-eval-args-left in the Lisp expressions >> > specified on the emacsclient command line should be well-documented to >> > avoid any confusion and UB. >> >> Added a docstring and included it in NEWS. I would have put it in the >> manual, but it seems rather niche to put in the Emacs manual and I >> didn't see a natural place to put it in the Emacs Lisp manual. > > The natural place is in the Emacs user manual, in "emacsclient > Options", where --eval is described. Where else? Ah true, obvious, I added it there. >> Passing arbitrary arguments to functions through emacsclient --eval >> requires complicated escaping to avoid them being parsed as Lisp (as >> seen in emacsclient-mail.desktop before this change). >> >> This new variable server-eval-args-left allows access to the arguments >> before they are parsed as Lisp. By removing arguments from the >> variable before they're parsed, a snippet of Lisp can consume >> arguments, as in emacsclient-mail.desktop. >> >> org-protocol might be able to use this as well, which might allow it >> to drop its current advice on server-visit-files. > > The right place to keep this information is in the manual and the doc > strings, not just in the Git commit log message. Done. >> +(defvar server-eval-args-left nil >> + "List of eval args not yet processed. >> + >> +When the server receives a request to eval one or more strings, >> +it stores them in this variable. Then, until this variable is >> +nil, it `pop's a string from this variable and evaluates it with >> +`server-eval-and-print'. Adding or removing strings from this >> +variable during this process will affect what is evaluated. > > This describes the implementation rather than the intended usage. Fixed. >> +This allows an expression passed to \"emacsclient --eval\" to >> +consume one or more subsequent arguments before they're parsed or >> +evaluated, with (pop server-eval-args-left). This is useful if >> +those arguments are arbitrary strings which should not be >> +evaluated. > > This describes a way of using this, but without the important part: > that any processed argument _must_ be popped, or it will be evaluated > again. See the doc string of command-line-functions for what I have > in mind. > > All in all, I think this should be rewritten in terms of how to use > this, and the result moved to the Emacs manual, leaving just the > minimum here. Done. >> +See also `command-line-args-left' for a similar variable which >> +works for command line invocations of \"emacs\".") > > This "see also" is not useful, because the doc string of > command-line-args-left is minimal and doesn't add any information > (which is okay, since that variable is basically meant for internal > Emacs handling of command-line arguments, unlike this one). Okay, fair, probably that should point at `argv' instead. >> --- a/lisp/startup.el >> +++ b/lisp/startup.el >> @@ -120,7 +120,10 @@ command-switch-alist >> "List of command-line args not yet processed. >> This is a convenience alias, so that one can write (pop argv) >> inside of --eval command line arguments in order to access >> -following arguments.")) >> +following arguments. >> + >> +See also `server-eval-args-left' for a similar variable which >> +works for invocations of \"emacsclient --eval\".")) > > And neither is this, because the use cases of the two variables are > almost completely unrelated. The docstring of argv says: This is a convenience alias, so that one can write (pop argv) inside of --eval command line arguments in order to access following arguments. That is exactly the same way this new variable is used. And in fact it's used for the exact same purpose in message-mailto. The reason "emacs" doesn't require complicated escaping is because message-mailto does (pop command-line-args-left) internally. I agree that argv/command-line-args-left has other use cases besides this one. But one of argv's use cases is the exact same use case of server-eval-args-left.