EmacsConf CFP ending and a completing-read example
I updated a simple (but occasional favorite) custom command the other day and it looks like it might be a useful "simple" example for others. Meanwhile, we are coming right up on the closing of the Call for Proposals period for EmacsConf 2025, so I wanted to shout about that.
EmacsConf 2025!
This year's EmacsConf is right around the corner but there is still one more day to submit a talk! (Also: we have been known to show a bit of leniency toward our submissions deadline, especially if you let us know something will be coming in a little late.) Speaking on behalf of everyone helping with the conference: we'd love to hear from you! Can't wait for Dec 6-7th!
insert-shrug: a completing read example
For years I've a stilly command that I enjoy: insert-shrug. It inserts amusing text into current buffer at point. Over time I've added to the possible outputs. The other day, while doing this, I decided it had outgrown using a prefix argument to select among options for what to insert. I would press C-u C-x M-p for the tablefip, or whatever. Too much to remember, really.
Enter completing-read.
The job of the completing-read function is to collect user-input. It supports Emacs' usual interfaces for that, including usually taking input from the mode-line but, more importantly, obeying whatever customizations the user has setup regarding how to do things such as show a list of possible completions.
Looking back on the change after a couple of days of nothing bad happening, I think it's a nice "in the wild" example for completing-read. And, as I say: fun!
First: Variables
Having a separate variable for completing-read to store history prevents mixing with prior input for other commands.
(defvar insert-shrug-history nil "History for `insert-shrug'")Previously the list of possible outputs for the function was hard-coded into the program: adding this variable made all sorts of sense irrespective of my goal of having less to remember.
(defvar insert-shrug-shrugs
'("shrug" "¯\\_(ツ)_/¯"
"shades" "( •_•). ( •_•)>⌐□-□. (⌐□_□)"
"fliptable" "(┛ಠ_ಠ)┛彡┻━┻"
"unfliptable" "┏━┓┏━┓┏━┓ ︵ /(^.^/)"
"catyay" "＼(≧▽≦)／"
"joy" "(っಠ‿ಠ)っ"
"facebook" "(╯°□°)╯︵ ʞooqǝɔɐℲ"
)
"Things for insert-shrug to insert, plist.")Now: Function
That setup, creating a function to prompt for and insert one of these is short and sweet:
(defun insert-shrug (&optional arg)
"Insert a shrug or, with ARG, something else."
;; completing read returns a value, interactive needs a list
(interactive
(list (completing-read "Emit: " ;; prompt
insert-shrug-shrugs ;; valid values
nil ;; no predicate function
t ;; entry must be from list
nil ;; entry area starts empty
insert-shrug-history ;; hist var
"shrug"))) ;; empty input becomes "shrug"
(insert (format "%s" (or (plist-get insert-shrug-shrugs arg 'string=) ""))))
;; bind it to a key. why not..
(global-set-key (kbd "C-x M-p") 'insert-shrug)That's it! The above is slightly modified from what I actually use: I added some comments for the post. Here's the actual change to my init stuffs: https://git.sr.ht/~mplscorwin/dotfiles/commit/20f97d4ee8523e1d3299ff7a70b7cccf76c2ab38
You read more about build completion within Emacs by evaluating (info (elisp)Completion") and regarding completing-read by typing C-h f completing read RET.
The same resources are available online (so, without installing Emacs) from https://gnu.org where documentation from latest stable release of each internally hosted GNU package is published. There you will (also) find the elisp manual entry for Completion and the elisp function reference entry for completing-read, however be aware that GNU.org along with everything hosted by the Free Software Foundation has been under a sustained, heavy DDoS attack for quite some time. Things often slower than we would like, rebooting, etc.
See you at EmacsConf! 🐢🐌