1 line
8.2 KiB
Plaintext
1 line
8.2 KiB
Plaintext
<!-- SC_OFF --><div class="md"><p><code>magit</code> UI is built with <a href="https://github.com/magit/transient">transient</a>. This post and <a href="https://www.reddit.com/r/emacs/comments/m518xh/transient_api_example_alternative_bindings_part_1/">part one</a> were prompted by the lack of API examples in the manual and docs.</p> <p>It's been a while. I was prodded into action. <strong>The resulting widget in this exercise is fun to use and really simple. Run the code and come back!</strong> Eval and press <code>M-p</code> to see the result. Use <code>SPC</code> <code>s</code> and <code>d</code> to add to the sentence or set it directly. <code>m</code> and <code>n</code> will display the constructed sentence in either a message or notification.</p> <h2>What Transient is Great At</h2> <p>First of all, I've reached conclusions about when to use transient vs a modal editing system like <code>meow</code> or <code>evil</code></p> <ol> <li>application UI's that want to own the entire top-level binding space, such as git</li> <li>modal UI's for strings of Emacs commands that <ul> <li>tend to follow each other in direct succession</li> <li>have states that need display</li> <li>have rules about which commands are valid in which context</li> </ul></li> <li>grouping esoteric commands that need to use context and state to further refine organization, which commands are displayed, and how they are displayed</li> </ol> <p>Anything less rich can likely be done with <code>ivy</code>, but if you have to begin hacking with one or the other, <code>transient</code> will be more fun and useful pretty quick. It's just doesn't have as declarative of an API yet.</p> <h2>Making strings of commands</h2> <p>Let's go beyond simple prefix or nested prefix behavior by instead issuing multiple commands to construct a sentence. Doing so means we want the transient to stick around. There's a quick API to accomplish this for a prefix. You just set the <code>transient</code> key to true when calling <code>transient-define-suffix</code>.</p> <p>The example code shows plenty of ways to combine normal Emacs concepts like interactive forms with the transient API.</p> <p>```elisp</p> <pre><code>;; need these loaded (use-package 'notifications) (use-package 'transient) ;; We're going to construct a sentence with a transient. This is where it's stored. (defvar ikaruga--toy-sentence "let's transient!" "Sentence under construction.") ;; First we define a suffix with a dynamic description. This allows us to ;; display the current value. (the transient API could use some more options to ;; display arbitrary values without making a suffix) ;; ;; The interactive form returns a single element list, (SENTENCE) which is then ;; passed into this command. ;; ;; Use transient faces with `propertize' to make your prompts match the feel of ;; other transient behaviors such as switches. (transient-define-suffix ikaruga-sentence (sentence) "Set the sentence from minibuffer read" :transient t :description '(lambda () (concat "set sentence: " (propertize (format "%s" ikaruga--toy-sentence) 'face 'transient-argument))) (interactive (list (read-string "Sentence: " ikaruga--toy-sentence))) (setf ikaruga--toy-sentence sentence)) ;; Next we define some update commands. We don't want these commands to dismiss ;; the transient, so we set their `:transient' slot to t for `transient--do-stay'. ;; https://github.com/magit/transient/blob/master/docs/transient.org#transient-state (transient-define-suffix ikaruga-append-dot () "Append a dot to current sentence" :description "append dot" :transient t ; true equates to `transient--do-stay' (interactive) (setf ikaruga--toy-sentence (concat ikaruga--toy-sentence "•"))) (transient-define-suffix ikaruga-append-snowman () "Append a snowman to current sentence" :description "append snowman" :transient t (interactive) (setf ikaruga--toy-sentence (concat ikaruga--toy-sentence "☃"))) (transient-define-suffix ikaruga-clear () "Clear current sentence" :description "clear" :transient t (interactive) (setf ikaruga--toy-sentence "")) ;; Now we want to consume our sentence. These commands are the terminal verbs ;; of our sentence construction, so they use the default `transient-do-exit' ;; behavior. (transient-define-suffix ikaruga-message () "Send the constructed sentence in a message" :description "show sentence" ; :transient nil ; nil is default, `transient--do-exit' behavior (interactive) (message "constructed sentence: %s" (propertize ikaruga--toy-sentence 'face 'transient-argument)) (setf ikaruga--toy-sentence "")) (transient-define-suffix ikaruga-notify () "Notify with constructed sentence" :description "notify sentence" (interactive) (notifications-notify :title "Constructed Sentence:" :body ikaruga--toy-sentence) (setf ikaruga--toy-sentence "")) ;; To bind all of our transient commands into a full transient (a "prefix"), we ;; just need group names and key-command pairs. To put the input sentence onto ;; its own line, we separate the next two groups into their own vector. You can ;; set the classname key to `transient-columns' or `transient-row' etc for more ;; specific arrangements. (transient-define-prefix ikaruga-sentence-toy () "Create a sentence with several objects and a verb" ["Sentence Toy!" ("SPC" ikaruga-sentence)] [["Transient Suffixes" ("d" ikaruga-append-dot) ("s" ikaruga-append-snowman) "" ; empty string inserts a gap, visually separating the appends from the clear ("c" ikaruga-clear)] ["Non-Transient Suffixes" ("m" ikaruga-message) ("n" ikaruga-notify)]]) (global-set-key (kbd "M-p") 'ikaruga-sentence-toy) </code></pre> <p>```</p> <p><em>edit</em> more compact final form</p> <h3>Compact declaration style!</h3> <p>Properties controlling suffix behavior / display can be set either in the command creation with <code>transient-define-suffix</code> or in the declarative creation of the transient. Since commands ought not know too much about what is binding and invoking them, you will probably prefer this form!</p> <p>Here, all of the <code>transient</code> and <em>simple</em> <code>description</code> keys are moved into the final prefix declaration:</p> <p>```elisp</p> <pre><code>(transient-define-prefix ikaruga-sentence-toy () "Create a sentence with several objects and a verb" ["Sentence Toy!" ("SPC" ikaruga-sentence :transient t)] [["Transient Suffixes" ("d" "append dot" ikaruga-append-dot :transient t) ("s" "append snowman" ikaruga-append-snowman :transient t) "" ; empty string inserts a gap, visually separating the appends from the clear ("c" "clear string" ikaruga-clear :transient t)] ["Non-Transient Suffixes" ("ms" "message sentence" ikaruga-message) ; multi-key bindings :) ("ns" "notify sentence" ikaruga-notify)]]) </code></pre> <p>```</p> <p><em>end edit</em></p> <h2>Next Up</h2> <p>Currently I'm grouping all of my project management and window & buffer manipulation into one modal UI. This will be my next update. I'm working on a package I call <code>ikaruga</code> to include some useful transients, editing commands, and a setup for the <code>meow</code> modal editing system. I'm combining transients with a modal system. The most common commands will live in modal space while the transients will be used to glaze over special modes and groups of related commands that are normally under multiple prefixes.</p> <p>Any other behaviors you really want to see an example for?</p> </div><!-- SC_ON -->   submitted by   <a href="https://www.reddit.com/user/Psionikus"> /u/Psionikus </a> <br/> <span><a href="https://www.reddit.com/r/emacs/comments/pon0ee/transient_api_example_part_2_transientdostay/">[link]</a></span>   <span><a href="https://www.reddit.com/r/emacs/comments/pon0ee/transient_api_example_part_2_transientdostay/">[comments]</a></span> |