There are a lot of things happening in the world of GNU Hyperbole. Here is a list of recent videos with introductions on various features. Even though I wrote a long post about my explorations in Hyperbole I feel like I don't have a good grasp of it. But now Hyperbole integrates with Denote which I also use and have written about.
So rather than diving in headfirst, I'm going to show a small example I use every day. It has to do with environment variables… specifically, AWS. Why did I use Hyperbole here? Because one keystroke turns a minute or two of fiddly, error-prone editing into a single action. I put a little bit of plain text in my .envrc file, and that text becomes a button. I can put the cursor on it, hit M-RET, and the old credentials are swapped out for the new ones, cleaned up, saved, and loaded into direnv. No command name to remember, no keybinding to set up, and the button sits right next to what it needs to act on. It’s not flashy, but it’s the kind of small win that, combined with other small wins, makes a big difference.
As I have said before, I use direnv in projects to set project-specific configurations. One thing I need to do every day is refresh my AWS credentials. Inside my .envrc file is this:
export AWS_ACCESS_KEY_ID="old_key"
export AWS_SECRET_ACCESS_KEY="old_secret"
export AWS_SESSION_TOKEN="old_token"
The workflow is simple:
- Go to the corporate AWS portal
- Find your environment and click "Access Keys"
- You can see your new credentials on the screen and, under 'macOS and Linux' you can just click a button to copy the exports commands to your clipboard.
- Go to the
.envrcfile and paste the new creds in. - Remove the old creds, which should be under the new ones.
- Remove the
^Mafter every line that AWS puts in, for reasons unknown - Run
M-x envrc-allow
Simple but… there are a lot of manual keystrokes in 4-7. And sometimes I muck it up – I delete too much, or delete the old before yanking in the new, so I don't know what is what in my kill ring. So sometimes I have to start over. I needed a way to automate some of this and for that - I use Hyperbole and the fact you can use implicit buttons to run elisp functions.
Here is the Elisp I cooked up:
(defun mh/aws-refresh-credentials ()
"Replace the AWS credential lines below the current line with the clipboard.
Deletes the lines directly beneath the current line that contain
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS_SESSION_TOKEN
(case-insensitive, so `aws_access_key_id = ...' works too), then
inserts the clipboard contents underneath the current line,
stripping trailing whitespace and carriage returns from every
inserted line."
(interactive)
(let ((cred-re ".*aws_\\(access_key_id\\|secret_access_key\\|session_token\\)")
(case-fold-search t))
(save-excursion
(forward-line 1)
;; If the current line was the last one in the buffer, make room.
(unless (bolp) (insert "\n"))
;; 1. Delete the old credential lines.
(while (and (not (eobp)) (looking-at-p cred-re))
(delete-line))
;; 2. Yank the clipboard, cleaned of trailing whitespace/CRs.
(let ((text (string-trim-right
(replace-regexp-in-string "[ \t\r]+$" "" (current-kill 0)))))
(insert text "\n"))))
(save-buffer)
(when (fboundp 'envrc-allow) (envrc-allow)))
An important part of this function is that it works relative to the line that I am on. I don't have to make a region or anything. And also note that envrc-allow is always run at the end, because I have to run that to make sure direnv refreshes.
Then I set that function up as an implicit button in my file, which sounds really technical but it's not – I literally type in # <mh/aws-refresh-credentials> just before those export lines. The <..> specifies that I'm making an action button, which helps Hyperbole pick it up. So my .envrc file looks like
# <mh/aws-refresh-credentials>
export AWS_ACCESS_KEY_ID="old_key"
export AWS_SECRET_ACCESS_KEY="old_secret"
export AWS_SESSION_TOKEN="old_token"
Now the workflow is:
- Go to the corporate AWS portal
- Find your environment and click "Access Keys"
- You can see your new credentials on the screen and, under 'macOS and Linux' you can just click a button to copy the exports commands to your clipboard.
- Go to the
.envrcfile, put your cursor inmh/aws-refresh-credentialsand hit M-RET, which is the "action key" in Hyperbole. That key tells Hyperbole "do something with this".
My AWS credentials are now updated with no more tweaking. A simple use, but powerful because it does a lot of manual work for me every day. I think that is the heart of Hyperbole – it does a lot of little things that make your workflows more seamless. And the button lives in the file exactly where I need it. And if I need it somewhere else, I can just put that same text there and have that button.
Next up: I will talk about using Hyperbole and Denote together.