Summary:
A quick walk through of adjusting the projectile package to use fast file finding and not include git submodules in those file lists.
I rarely use Git📖
submodules. My text editor workflow and mental heuristics assume that a “project” is one Git
repository. I use projectile (with some Consult decoration) to find files within the project. It works great.
Especially with the amazing consult-projectile package.
However in a new project Hyku📖
we’ve started using Git
submodules.
I’ll have more on this novel approach at some future point. For now, it’s a prototype for extending an existing Ruby on Rails📖
application.
With this change, when I look for a file via projectile I get a list that includes the files in the main repository and the files in the very large Git
submodule. Confounding things is that the file names are often quite similar.
I spent an hour or so delving into how to remove submodule files from the file selection.
First, I discovered that by default, projectile’s indexing method is alien; meaning it uses external shell commands to build the list. Looking at the source code, I found that the alien code was using fd📖
with the following args: -H -0 -E .git -tf --strip-cwd-prefix -c never.
Stored in the projectile-git-fd-args variable.
To understand what those all meant, I looked to the man page for fd. The critical switch was the -E .git. That meant to exclude all files from the .git directory.
What I wanted was to also exclude the hyrax-webapp directory i.e.
the Git
submodule’s root directory.
I added the following to my project’s .dir-locals.el:
And gave it a spin. I still saw the files. I did some further digging, and projectile also has discovery of files in Git
submodules. So I needed to configure that.
By default the shell command, stored in projectile-git-submodule-command is git submodule --quiet foreach 'echo $displaypath' | tr '\n' '\0'.
So to work around that, I amended my .dir-locals.el:
Summary:
In this post, I share Errant’s Chase procedure. I then write out the mathematics of calculating the movement dice. And from there provide an Emacs function for calculating movement dice. The chase subsystem is too interesting to ignore the movement dice. The underlying question is “should we care about the movement dice in combat?” I think so, because those dice add to the unpredictability of the game.
I was reading Errant📖
and got curious about the mathematic behind the fiddly Movement Dice. A character’s Movement Dice are derived from their physique, skill, and number of item Slots carried.
The Movement Dice is a proud and odd little rule that impacts movement in combat as well as chases. My conjecture is that the chase mechanic encourages you to throw down your backpack and run; multiple dice are advantageous for escaping.
Of important note, the only time a character’s movement dice matter is during a chase and during combat. Exploration is not based on the movement dice.
Errant’s Chase Procedure
First let’s look at the Chases section of Errant
:
In the case where they are being chased through a dungeon or similarly defined area, or for a short pursuit, the hunt can play out using standard initiative turn rules. However, for longer pursuits, and ones that may take place in broadly abstracted spaces like the wilderness or in cities, the following chase procedure can be used.
In a chase, generally, the participants can be tracked in terms of what side they’re on (i.e. pursuers and fugitives), but some chases may involve multiple parties or characters that need to be tracked separately.
Each initiative turn, the character with the lowest spd or mv on each side makes a movement roll. If the characters are on mounts or vehicles, use the spd of the mount or vehicle.
If the fugitives roll two 4’s, then they escape and the chase ends. If the pursuers roll two 4’s, they have caught the fugitives. In case of a tie, both sides make a movement roll as a tiebreaker.
If either side rolls doubles that are not 4’s, then characters on that side may make melee attack roll, perform a sorcery or miracle, or any other actions they wish.
If any of the results on both side’s movement dice match each other, characters may make ranged attack rolls against the other side. So if the fugitives rolled a 3 and a 4, and the pursuers rolled a 2 and a 3, the 3’s match, and so characters on each side may make ranged attack rolls against characters on the other side.
Dropping items during a chase is a free action. Dropping something the pursuers are interested in (food, money, etc.) may force a morale roll to see if they continue the chase.
Characters on either side may choose to sprint, rolling double their normal amount of movement dice, but they must make a physcheck with a dv equal to their encumbrance to do so. If they fail, they may not make a movement roll this initiative turn.
Characters on either side can choose to split off from their group; they will make movement rolls separately.
At the end of the initiative turn, if the chase has not yet ended, the side that rolled the lowest on their movement roll rolls a d10 for a chasedevelopment that affects them.
We have some high stakes dice rolls where having more movement dice increases your chances of ending the chase or taking meaningful actions during the chase. There’s a press your luck element in choosing to sprint (and garner potentially more dice). There’s also the option to split from the slower characters.
All modeling the absolute chaos of a good old fashioned rout.
On to the Mathematic of It All
With that in mind, we dive into the fiddly bits. We use two attributes (e.g.physique and skill) plus the more fluid number of carried Slots.
Errant
encourages you to calculate your Spd while carrying your backpack and when not carrying your backpack.
The book wants to make it clear just how much that backpack is costing you during a chase.
A character’s ENC (or Encumbrance) is:
When slots > physique, then 4 + slots - physique
Else (4 × slots) ÷ physique rounded down.
A character’s SPD (or Speed) is skill - encumberance. And their movement die is speed + 4 rounded down.
Emacs Lisp Function
The following function prompts for information and provides movement dice while carrying your backpack and when not carrying your backpack.
I suppose it would also be useful to see the effect of discarding things carried in your hands. Because when you’re running maybe discarding that greatsword is a better plan than carrying the dead weight.
I like the chase procedure; and the fiddly bits make the procedure possible. Also given that combat might lead to chase, having a clear understanding of a character’s movement dice helps folks think about the viability of fleeing.
If I don’t want to worry about it, a quick and dirty method could be:
Pick the higher of physique or skill and subtract the slots.
Select the lowest sided-die from the dice chain that has sides greater than the above amount.
Summary:
I take a tour of the text editors I’ve used and why and when I moved on from them. Along the way, I write up some further insights into what I’m looking for and how I practice and explore a new to me editor.
I started working with open-source software in . Having come from a Microsoft Windows and IBM System iSeries📖
environment, I was accustomed to my tools being vendor provided.
In I began my quest to find the software for editing my code. I looked into JEdit, TextWrangler, and BBEDit. I even tried Emacs📖
.
I’ve often wondered what would be different had I chosen Emacs
in . But back then, I didn’t have patience for a tutorial
While I was looking and using these different editors, I learned about Ruby on Rails📖
and saw folks using Textmate📖
.
I adopted Textmate
; it felt intuitive and in those earlier days of Ruby on Rails
it was the defacto editor of so many Rubyists.
To this day, the function of line filter is one that I continue to consider necessary for my editing experience.
In Emacs
, I use consult-lines to replicate this behavior.
In Textmate, I wrote a few snippets, but never a plugin. I did spend time crafting a refined Railscast theme.
Sometime in or I switched from Textmate to Sublime Text📖
. The primary reason for switching was Textmate’s slowness in searching within a large project. I brought forward my Railscast theme.
In , I switched from Sublime Text to Atom📖
. The foundational reason was that Atom was open-source. I again brought forward my modified Railscast theme.https://github.com/jeremyf/vibrant-ink-ruby
I remember practicing Vim📖
but the paradigm did not stick.
I continue to practice on occasion, mostly because remote machines invariably have Vim installed.
I began exploring writing plugins and themes in Atom. I found it clunky as you needed to write configuration/functions in multiple files.
During , I began noticing that Atom was more prone to breakage. And I didn’t like the slow boot time for Atom; especially when I had my GIT_EDITOR configured to atom -w; I would type git commit on the command-line and wait for Atom to boot up so I could type a commit message.
In , I grew tired of Atom’s flakiness, and saw that with Microsoft’s purchase of Github that Visual Studio Code (VS Code 📖)
would likely be getting attention and Atom would further languish.
It was that Github announced they were Sunsetting Atom.
On I stopped using Atom and started using and once again practicing Vim
. Humans, I swear I have tried many times to learn and use Vim. I can fumble around, but modal editing does not work for me.
On , I stopped trying to make Vim my editor and started exploring VS Code
. It reminded me of Atom, Textmate, and Sublime. But there were two things I couldn’t get over:
The default window dressing felt like I might accidentally charge my credit card at some point.
The default commit message input is an HTML type=text element. A design consideration that encourages writing very little for commit messages.
I’ve since learned that configuring the window dressing is somewhat trivial. But that pernicious commit message input remains.
And why was that a big deal? My thinking was that any code editor that has a small input area for entering commit messages was built on the principles that history does not matter.
And would propagate subtle bad habits; such as modeling that folks need not write good commit messages. Good commit messages help expose intent and constraints.
I set aside VS Code
and looked for other options. Emacs
was barely a consideration. But I was running out of viable options.
I spent time practicing, namely working through the tutorial and exploring package archives to find utilities to help me write.
On I switched to Emacs. I tried both Doom and Spacemacs📖
, but settled on building my own configuration.
What this looked like was starting from a baseline install and just writing and coding. When I hit a point where I knew past editors did something, I would begin exploring.
I did this with the mindset of “I am learning and building my tools; so other things will move slower.” In other words, if I had an urgent task to complete, I wouldn’t do this. But if I had some slack in time, I’d take time. Also it was ; I had lots of slack time.
The most fruitful exploration came when I wanted to use the line filter function that was part of Textmate, Sublime, and Atom.
This lead me to Ivy, Counsel, and Swiper; this trio helped me understand Emacs. I could see the interactive functions and their first line doc-strings. That discoverability, paired with Helpful helped me build steam.
Eventually, I switched from the trio of Ivy, Counsel, and Swiper to the quintet of Consult, Marginalia, Vertico, Orderless, and Embark. The reason? The package sizes and design considerations. Namely the quintet of packages built atop the Emacs Application Programming Interface (API 📖)
; creating what is likely to be less maintenance overhead.
As I watch folks use their editors, I’ve discovered one small bit of functionality that Emacs has versus other editors. The concpet of a buffer, separate from the file. I can create a Scratch Buffer to write down a thought or bit of code. I don’t need to fiddle with creating a new file and deciding where that file goes. The Scratch Buffer serves as a somewhat durable place that favors capturing the idea over determining where to file that idea.
I know for myself, if I’m working on something then have an idea partially related, I would lose a lot of concentration and focus if I also had to specify where I write that idea.
Conclusion
These days, I struggle to think of what would prompt me to move from Emacs. I’ve created an environment that works for me; and when I begin to see repeated tasks I spend a bit of time exploring ways to encode them.
Creating functions and packages in Emacs feels far less arduous than it did in Atom and VS Code
. I’m extending my editor at a slower frequency, but that’s a function of maturity.
Summary:
The tools I use for my work are a vital part of me. I spend evenings talking about them with a dear friend. I encourage other folks to practice their tools, hoping that in practicing folks will improve their problem solving skills.
On Thursdays I often have dinner and drinks with my good friend Brandon. We talk about books, music, Zelda, travel, general programming, and Emacs📖
. He’s been using Emacs
for decades, whereas I’m a recent convert.
Since .
This we were again talking about Emacs
. And Brandon wondered the following: “It would be interesting to have a set of tasks we needed to accomplish in the same document, and see how differently we approach the solution.”
We haven’t ever done any pair programming together, but know that our approaches to navigating and editing are different. Because Emacs
is an editor that flows and moves with you. And Brandon and I adopted Emacs
more than two decards apart; so his habits and approaches will likely vary from mine. In part because of the available packages we’ve each adopted and practiced.
More than any other editor I’ve used, I spend time honing and practicing Emacs
.
Part of this is the joy of discovery and thinking through different approaches.
I’m a recent convert to Emacs (started in 2020). I’ve been a professional software developer for years. I gave VS Code a whirl back in 2020, but it didn’t suit me.
What I like about Emacs is that I have an integrated computing environment: writing, reading, and coding. When I get better at using my tools, all aspects benefit. At https://takeonrules.com/about/stats/ you can see an overview of my pre-Emacs stats versus my with Emacs. It’s a game changer for me.
The other bit of Emacs that I adore is how quick it is to extend my editor. I can record a macro or write a function, and save that little snippet of code for future usage. It’s easy to temporarily assign a key combination to a function.
I wasn’t aiming to convince the original poster but instead to get them thinking about their editor.
A question I like to ask the people I mentor, “How many more years do you think you’ll be writing code? Writing in general? Do you think at least for the next 5 years?” All of that is a nudge for them to practice using their tools. A reminder that the tools we use shape what we view as possible or feasible.
Summary:
In this post I walk through a problem I had regarding editing remote files. I describe an interim solution and then how I used kubectl and tramp to later edit the files “locally.”
This week I’ve been wrestling with an integration environment challenge. I need to debug code on a remote demo instance that is configured similar to production. Due to the current constraints, this involves using Secure Shell (SSH 📖)
to edit remote files in a Kubernetes (K8s 📖)
cluster, then restarting the web-server for the cluster, and finally checking logs to see what’s happening.
To say it is tedious is an understatement.
Initial Solution
Further confounding the problem was that I needed to make these changes using Vim📖
. I like Vim
but my Emacs📖
key bindings continually get in the way.
My initial work around was to create a simple interactive Emacs
function:
(defun jf/rancher/rm-then-vim-project-file (&optional filename)
"Kill some text to edit a FILENAME in Rancher."
(interactive)
(let* ((f (or filename (buffer-file-name)))
(relative-name
(concat "./"
(file-relative-name f (projectile-project-root)))))
(kill-new (f-read f))
(kill-new (format "rm %s ; vim %s"
relative-name relative-name))))
The above copies the current file contents. Then copies the command to remove the old file and edit the file in Vim
. The idea being that while I’m in the web User Interface (UI 📖)
, I can past the rm ; vim command to open a clean file and then paste the contents into it.
It’s a bit of a lazy-person’s scp
.
Let’s Go Tramp
I have wanted to be able to SSH
into a K8s
pod. I spent a bit of time and these are my steps for leveraging Emacs
’s Tramp package. We use Rancher📖
for our K8s
management.
brew install fzf (for some fuzzy finding friendlyness)
kubectl krew install ctx
kubectl krew install konfig
kubectl krew install ns
Ensure that ~/.krew/bin is in your $PATH
Ensure that ~/.kube/config file exists (e.g.touch ~/.kube/config)
Rancher
Copy the contents of Rancher’s cluster’s KubeConfig into a local file.
As of the config is available in the top-right menu of the cluster.
For this example, we’ll write the file to ~/kubeconfig.tmp.yml
With that file, add the config to your kubectl (e.g.
kubectl konfig import --save ~/kubeconfig.tmp.yml).
Run kubectl config get-contexts; you should see the cluster you just added to the kubectl konfig.
Run kubectl ctx and set the current context to the cluster you added.
Run kubectl get pods; you should see the named pods. In the case of our Hyku📖
builds you’ll see something along the lines of the following:
❯ kubectl get pods
NAME READY STATUS RESTARTS AGE
palni-palci-demo-nginx-66d86c56c5-pdzn4 1/1 Running 0 11h
palni-palci-demo-pals-84bc48c974-64ztz 1/1 Running 0 69m
palni-palci-demo-pals-84bc48c974-pnvnn 1/1 Running 0 67m
palni-palci-demo-pals-worker-c54c8d69d-pd9p4 1/1 Running 0 69m
palni-palci-demo-redis-master-0 1/1 Running 0 6d7h
Tramp-ing to Those Files
With all of that pre-amble, in EmacsM-x find-file and type /kubernetes:palni-palci-demo-pals-84bc48c974-pnvnn:/. The trailing :/ indicates that we’re looking in the default directory, and with a Rails application you’ll see the usual suspects for directories (e.g.
app/lib/ etc.); begin navigating and editing those files.
If I find myself doing this quite regularly, I’ll likely want to create some helper functions for the find-file.
Summary:
Explaining new functionality added to my random-table.el package. This explanation includes the Emacs Lisp code and some explanation. Ultimately, building these random tables grows my personal GM notebook; encoding logic and making it readily and consistently available (when I have my computer).
, I extended the existing functionality with two features:
Exclude a table from prompting for a roll.
Allow for rudimentary math operands with table results.
Exclude a Table from Prompting for a Roll
Prior to my most recent change, when you pass the universal prefix arg to random-table/roll it would always prompt for rolls on the table. Even if there was one record in the :data element. You would get a prompt that looked like: “Roll 1d1 on Your Named Table:”
With the most recent change, any table that has one element in :data will not prompt for the roll. Also, you can specify :exclude-from-prompt t when registering a table; then any “rolls” on that specific table will not prompt to give the dice value.
Ultimately, the goal is to ask for dice rolls when they might be something the player wants to roll.
Allow for Rudimentary Math Operands with Table Results
In my quest for more random tables and functionality, I worked through Errant📖
’s Hiring Retainers section. Using the Player Character (PC 📖)
’s presence, you look-up the morale base. Then roll 2d6, modified by the offer’s generosity, to then determine the modifier to the morale base.
To perform mathematical operations, I continue to leverage the s-format functionality. That is s-format will evaluate and replace the text of the following format: ${text}.
Below is the definition of a random Henchman for Errant.
I do need to consider randomizing it’s level; higher level henchmen are available at larger urban centers.
Adding this functionality was somewhat quick.
I stumbled on the match-string-no-properties; when I did not pass the text it used the positional data of string-match to look at the buffer’s text. In other words, it was broken without this.
Below is the code that I added for replacer function logic. The \\[\\(.*\\)\\][[:space:]]*\\(-\\|\\+\\|\\*\\)[[:space:]]*\\[\\(.*\\)\\]Regular Expression📖
is a lot to visually parse.
There are three capture regions:
First: The text within square brackets that is to the left of the operand (e.g. second capture region)
Second: The mathematical operand (e.g. -, +, or *; no division just yet)
Third: The text within square brackets that is to the right of the operand (e.g. second capture region)
We use Emacs📖
’s apply function to call the operand as a function. The left operator being the rolled results of the first capture region. The right operator being the results of rolling the third capture region.
Having mathematical operators assumes that the tables are returning number like values.
When registering tables, I now disallow [ and/or ] in the :name of the table. This way I can be more confident that the ${[Table] + [Table Two]} will result in operand logic.
Conclusion
Part of my ongoing reason for doing this is to build up my “Game Master (GM 📖)
notebook” of tables and procedures. In my experience, any of these tables might be useful for inspiration or reducing rules lookup during play.
Summary:
Adding dice rollers that allow for either programatic randomization or prompting the user to manually roll dice and enter the results. A side benefit, is that this feature can help with debugging.
First, invoke the roller with one universal prefix arg (e.g. C-u M-x random-table/roll) to replace all random calls with prompts. That is “Computer asks for a die roll, human provides it, and then evaluates further.”
The default behavior I want is that when I roll on a table Emacs📖
will quietly “roll the underlying dice.” However, if I pass the universal prefix arg (e.g C-u M-x random-table/roll) then Emacs
will prompt me to enter each of the dice rolls.
Code
Below is the code changes to either silently roll or prompt:
;;; Random Table Roller
(cl-defmacro random-table/roller (&rest body &key label &allow-other-keys)
(let ((roller (intern (concat "random-table/roller/" label)))
(docstring (format "Roll %s on given TABLE" label)))
`(defun ,roller (table)
,docstring
(if current-prefix-arg
(read-number (format "Roll %s for %s: " ,label (random-table-name table)))
,@body))))
(defun random-table/roller/default (table)
"Given the TABLE roll randomly on it.
See `random-table/filter/default'.
See `random-table/roller' macro."
;; Constant off by one errors are likely
(let ((faces (length (-list (random-table-data table)))))
(if current-prefix-arg
(read-number (format "Roll 1d%s for %s: " faces (random-table-name table)))
(+ 1 (random faces)))))
;;;; Perhaps not ideal to have one function per roll type. But...having
(random-table/roller :label "1d6" (+ 1 (random 6)))
(random-table/roller :label "2d6" (+ 2 (random 6) (random 6)))
(random-table/roller :label "1d12" (+ 1 (random 12)))
(random-table/roller :label "1d20" (+ 1 (random 20)))
Given that I pass the universal prefix arg (e.g. C-u) when I roll on the Random Attribute table then I will get the prompt “Roll 1d6 for:” and the value I enter will be used for looking up the correct :data element.
Why Introduce This?
First, this refactor was a 30 minute exercise. I spent the most time tracking down the ,@body syntax. In the case of the random-table/roller macro, the body is all parameters that are not named.
Let’s say we have (random-table/roller :label "1d12" (+ 1 (random 12))). The body is (+ 1 (random 12)). And the @body syntax is the non-evaluated textual value of body. In other words, @body is not an integer but is instead the expression.
Second, when I’m playing a solo game, I’m often content to let Emacs
silently roll the dice. However, in encoding the Death and Dismemberment table I can envision a case where I’m running a game and someone else’s character drops to 0 Hit Point (HP 📖)
. I’d imagine that they’d want to roll their fate.
Third, this small scale refactoring helps reinforce the flexibility of the package; that I’ve adequately modeled the process flow and can amend each of the functional points.
Fourth, by adding the ability to specify the random value, it can ease the debugging challenges. In my experience properly testing functions that use randomization to generate output will often require that you not randomize but instead say what the random numbers will be.
Conclusion
I have a few more ideas and see a few edge cases; namely the current_roll functionality. I introduced that, but it’s inadequate. And I need to explore more around it. Namely I want the current_roll for the table on which this was written. Resolving that is necessary for having over-lapping ranges on tables.
I also want to go hunting for some more random tables. One that I’m considering is going so far as to make a random Old School Essentials (OSE 📖)
character using the quick equipment guide from Carcass Crawler Volume 1, Issue 2. I’ve started sketching out how I might capture attribute values, then find qualifying classes and picking one. However, this thought exercise is a large chunk of work for the random-table package.
Summary:
This post walks through encoding a new random table using my Emacs proto-package “random-table.el”. To get the tables working, I needed to do a bit of light refactoring. Ultimately, this example further demonstrates the flexibility of table composition.
Any sufficiently advanced hobby is indistinguishable from work.
I checked out the table. What I liked about the Death and Dismemberment table is that it eliminates death at 0 Hit Point (HP 📖)
and introduces a sub-system that allows for recovery and addresses the damage in excess of current remaining HPs
.
Encoding a New Table
I set about encoding the Death and Dismemberment rules for my Random Table package.
This required a few changes:
I needed the concept of a current_roll. The Death and Dismemberment table.
I wanted dice to be able to return strings and then use those strings as the lookup on the table’s :data.
I did not, at present, worry about the cumulative effects of data. However, I’m seeing how I might do that.
Let’s dig in.
There are five tables to consider for Death and Dismemberment:
Physical
Acid/Fire
Eldritch
Lightning
Non-Lethal
Here’s how I set about encoding that was as follows:
(random-table/register :name "Death and Dismemberment"
:roller #'random-table/roller/prompt-from-table-data
:data '(("Physical" . "${Death and Dismemberment > Physical}")
("Acid/Fire" . "${Death and Dismemberment > Acid/Fire}")
("Eldritch" . "${Death and Dismemberment > Eldritch}")
("Lightning" . "${Death and Dismemberment > Lightning}")
("Non-Lethal" . "${Death and Dismemberment > Non-Lethal}")))
In the case of passing the Death and Dismemberment table, you get the following prompt: “Death and Dismemberment via”. And the list of options are: Physical, Acid/Fire, Eldritch, Lightning, and Non-Lethal.
Once I pick the option, I then evaluate the defined sub-table. Let’s look at Death and Dismemberment > Physical.
(random-table/register :name "Death and Dismemberment > Physical"
:roller (lambda (table) (+ 1 (random 6)))
:private t
:data '(((1) . "Death and Dismemberment > Physical > Arm")
((2) . "Death and Dismemberment > Physical > Leg")
((3 . 4) . "Death and Dismemberment > Physical > Torso")
((5 . 6) . "Death and Dismemberment > Physical > Head")))
This is a rather straight-forward table. Let’s say the :roller returns a 5. We will then evaluate the Death and Dismemberment > Physical > Head table; let’s look at that. The resulting table is rather lengthy.
(random-table/register :name "Death and Dismemberment > Physical > Head"
:roller #'random-table/roller/death-and-dismemberment/damage
:private t
:data '(((1 . 10) . "Head Injury; Rolled ${current_roll}\n- +1 Injury\n- Concussed for +${current_roll} day(s).")
((11 . 15) . "Head Injury; Rolled ${current_roll}\n- +1 Injury\n- Concussed for +${current_roll} day(s).\n- One Fatal Wound.\n- ${Save vs. Skullcracked}")
((16 . 1000) . "Head Injury; Rolled ${current_roll}\n- +1 Injury\n- Concussed for +${current_roll} day(s).\n- ${current_roll} - 14 Fatal Wounds.\n- ${Save vs. Skullcracked}")))
The :roller (e.g. random-table/roller/death-and-dismemberment/damage) is as follows:
We roll a d12, add the number of existing injuries, and accumulated lethal damage. Then look up the result in the :data of Death and Dismemberment > Physical > Head. Let’s say the result is a 12.
Put a pin in this result, we’re going to dive into some additional tables.
We’ll need to roll on the the Save vs. Skullcracked table, which I’ve included below:
(random-table/register :name "Save vs. Skullcracked"
:roller #'random-table/roller/saving-throw
:private t
:data '(("Save" . "Saved against cracked skull…gain a new scar.")
("Fail" . "Failed to save against cracked skull. ${Save vs. Skullcracked > Failure}")))
The :roller (e.g. random-table/roller/saving-throw) will prompt for the saving throw score and any modifier to the roll. Then it will return “Fail” or “Save” depending on the results. See the function.
Let’s say that we “Fail” the saving throw. We now lookup on the Save vs. Skullcracked > Failure table:
(random-table/register :name "Save vs. Skullcracked > Failure"
:private t
:data '("Permanently lose 1 Intelligence."
"Permanently lose 1 Wisdom."
"Permanently lose 1 Charisma."
"Lose your left eye. -1 to Ranged Attack."
"Lose your right eye. -1 to Ranged Attack."
"Go into a coma. You can recover from a coma by making a Con check after 1d6 days, and again after 1d6 weeks if you fail the first check. If you fail both, it is permanent."))
Let’s say we get “Permanently lose 1 Intelligence” for the failed save. Now, working our way back, let’s see what that all evaluates to:
Head Injury; Rolled 12
- +1 Injury
- Concussed for +12 day(s).
- One Fatal Wound.
- Failed to save against cracked skull. Permanently lose 1 Intelligence
The modified d12 roll resulted in a 12; hence the +12 day(s).
Conclusion
The refactoring that I required was nominal; I needed to account for strings and decided that I’d pass the :roller function the random-table structure instead of the :data of a random-table.
In writing this, I started thinking of a few more features.
First, Invoke the roller with one universal prefix arg (e.g. C-u M-x random-table/roll) to replace all random calls with prompts. That is “Computer asks for a die roll, human provides it, and then evaluates further.”
Second, Overlapping ranges for the :data. The :fetcher would look to find all rows that match. Let’s give an example by re-working the Death and Dismemberment > Physical > Head table:
Summary:
A walk-through of a set of Emacs functions that I’ve written to allow for defining and rolling on random tables in my text editor. This involves quite a walk through and quite a bit of emacs-lisp code.
update:
I found a bug in my code and since updated the code and links.
For my solo Role Playing Game (RPG 📖)
sessions I write the game play within Emacs📖
. For each RPG
campaign, I’d craft a few custom functions to roll on random tables. I had some common functions that I used, but the table definition was always ad-hoc…until .
Over the last few weeks, I’ve been working on an Emacs
proto-package that would normalize tables. At present, my proto-package relies on the dice interpreter of the org-d20 package📖
. This package represents refactoring the random table tooling I had made for two different games.Black Sword Hack📖
and The One Ring📖
.
When I invoke random-table/roll, I can select “Coin Toss”, it will add to the kill ring and write a message based on the roll; either “Heads” or “Tails”.
The default reporter kills the value and messages. But you can configure the reporter by setting the random-table/reporter value to a function; see the code for the reporter function.
I could also call random-table/roll and provide the following: “You toss a coin and it lands on ${Coin Toss}”
And will get back: “You toss a coin and it lands on Heads” (assuming you rolled a Heads).
In fact we could register a new table:
(random-table/register :name "Things We Throw"
:data '("Rocks"
"Tantrum"
"Coin and it comes up ${Coin Toss}."))
When we “roll” on that table, when we get the “Coin and…” result, we’ll evaluate rolling on the Coin Toss table. The end result is “Coin and it comes up Heads.”
We can also create ranges, but will need to consider the roller:
The given :roller is effectively 2d6. And we use the rolled values to then find the correct entry in :data. For example, when we roll a 4 we’d return “Unfriendly”.
In the above case, when we roll the “Reaction Roll with Prompt”, Emacs
will prompt for a Modifier. We’ll then use the given modifier to adjust the dice roll.
I also adjusted the range to allow for very large numbers being provided by end-users.
As you register tables, via random-table/register, you add them to the table registry.
A hash assigned to the random-table/storage/tables variable.
The list of tables shown in the M-x random-table/roll can become quite lengthy. To register a table, without adding it to the selection list, add :private t as one of the key word arguments.
Below is the “Name” table. When we roll on the “Name” table we’ll pick a random one. Then roll on a “sub-table”. So as to not clutter the list, we mark those “sub-tables” as :private t.
(random-table/register :name "High Low"
:roller (lambda (&rest args) (list (+ 1 (random 6)) (+ 1 (random 6))))
;; We include this so that we only return the first data element. The
;; dice rolls are for the High Value and Low Value
:fetcher (lambda (data roll) (car data))
:data '("\n- High :: ${High Value}\n- Low :: ${Low Value}")
:store t)
(random-table/register :name "High Value"
:reuse "High Low"
:private t
:filter #'max
:data '("One" "Two" "Three" "Four" "Five" "Six"))
(random-table/register :name "Low Value"
:reuse "High Low"
:private t
:filter #'min
:data '("One" "Two" "Three" "Four" "Five" "Six"))
As of I store the roll in a somewhat naive manner; for a table with :store t, when we “roll on that table” we add to a hash the table name and the results of the roll (e.g. the specific dice as a list). Then until we’ve fully evaluated the roll for that table, we can reference the dice results for that table.
One thing I introduced in the above was the :fetcher and :filter elements. The :filter takes the dice pool (as a list) and returns an integer. The :fetcher takes the integer and looks things up in the provided :data.
;;; random-table --- Roll on some tables. -*- lexical-binding: t -*-
;; Copyright (C) 2023 Jeremy Friesen
;; Author: Jeremy Friesen <jeremy@jeremyfriesen.com>
;; This file is NOT part of GNU Emacs.
;;; Commentary:
;; This package provides a means of registering random tables (see
;; `random-table' and `random-table/register') and then rolling on those tables
;; (see the `random-table/roll').
;;
;; The `random-table/roll' is an `interactive' function that will prompt you to
;; select an expression. You can choose from a list of registered public tables
;; or provide your own text. This package uses the `s-format' to parse the
;; given expression.
;;
;; The guts of the logic is `random-table/evaluate/table' namely how we:
;;
;; - Gather the dice (represented by the :roller)
;; - Filter the dice to a value (represented by the :filter), we might pick a
;; single dice rolled or sum them or whatever.
;; - Fetch the filtered result from the table.
;; - Evaluate the row.
;;
;; Examples:
;; - (random-table/roll "2d6") will roll 2 six-sided dice.
;; - (random-table/roll "There are ${2d6} orcs.") will roll 2 six-sided dice and
;; output the sentence "There are 7 orcs."
;;
;; Tables can reference other tables, using the above string interpolation
;; (e.g. "Roll on ${Your Table}" where "Your Table" is the name of a registered
;; table.). No considerations have been made to check for cyclical references,
;; you my dear human reader, must account for that.
;;; Code:
;;;; Requirements:
(require 'org-d20)
(require 'cl)
;;;; Data Structures and Storage and Defaults
(cl-defstruct random-table
"The definition of a structured random table.
I roll the dice, filter the results, and fetch from the table.
The `random-table/evaluate/table' defines the steps we take to
\"roll on the table.\"
The slots are:
- :name :: the human readable and reference-able name (used for
completing read and the key for the table storage).
- :data :: the tabular data, often as a list of strings. By
design, those list of strings can have interpolation
(e.g. \"${2d6}\" both of dice structures but also of other
tables.
- :roller :: function to roll dice and return list of dice results.
- :filter :: function to filter the list of dice.
- :fetcher :: function that takes two positional arguments (see
`random-table/fetcher/default'.); it is used to fetch the correct entry
from the table.
- :private :: when true, do not show in list of rollable tables.
- :store :: When non-nil, we store the roller's value for the
duration of the table evaluation. Useful for when you have one
roll that you use for multiple tables.
- :reuse :: the :name of a table's stored dice results.
About :reuse and :store
There are cases where we want to use one set of dice roles. For
example, in the \"Oracle (Black Sword Hack)\" table we roll dice
and use those dice results to determine both the answer as well
as whether there are unexpected events. All from the same roll."
name
data
(roller #'random-table/roller/default)
(filter #'random-table/filter/default)
(fetcher #'random-table/fetcher/default)
(private nil)
(store nil)
(reuse nil))
(cl-defun random-table/register (&rest kws &key name data &allow-other-keys)
"Store the DATA, NAME, and all given KWS in a `random-table'."
(let* ((key (intern name))
(struct (apply #'make-random-table :name key :data (-list data) kws)))
(puthash key struct random-table/storage/tables)))
(defvar random-table/storage/results
(make-hash-table)
"An ephemeral storage for dice results of rolling for a table.
As part of the rolling, we both add to and remove those stored
values; that is to say functions are responsible for clean-up.
See `random-table' for discussion about storage and reuse.")
(defvar random-table/storage/tables
(make-hash-table)
"A hash-table of random tables.
The hash key is the \"human readable\" name of the table (as a symbol).
The hash value is the contents of the table.")
(defun random-table/roller/default (&rest data)
"Return list with one element that is between 1 the `length' of the given DATA.
Rollers should return a `list' of values; perhaps the results of
individual dice rolled.
See `random-table/filter/default'."
;; Constant off by one errors are likely
(list (+ 1 (random (length (-list data))))))
(defun random-table/filter/default (&rest rolls)
"Filter the given ROLLS and return an integer.
See `random-table/roller/default'."
(apply #'+ (-list rolls)))
(defun random-table/fetcher/default (data &optional roll)
"Find ROLL on the given table's DATA.
When ROLL is not given, choose a random element from the TABLE."
(if-let ((index (if (integerp roll) roll (car roll))))
;; Sniff out if the first element to see if we're dealing with a table that has ranges.
(if (-cons-pair? (car data))
;; We have a cons-pair, meaning we have multiple rolls mapping to the same
;; result.
(cdr (seq-find
(lambda (row)
(if (-cons-pair? row)
(let ((range (car row)))
(cond
((-cons-pair? range)
(and (>= index (car range)) (<= index (cdr range))))
((listp range)
(member index range))
((integerp range) (= index range))
(t
(error "Expected `cons', `list', or `integer' got %s for row %S." (type-of range) row))))
(member index (car row))))
data))
;; Off by one errors are so very real.
(nth (- index 1) data))
(seq-random-elt data)))
(defvar random-table/reporter
#'random-table/reporter/as-kill-and-message
"The function takes two positional parameters:
- EXPRESSION :: The text to evaluate for \"rolling\"
- RESULT :: The results of those rolls.
See `random-table/reporter/as-kill-and-message'.")
(defun random-table/reporter/as-kill-and-message (expression result)
"Responsible for reporting the EXPRESSION and RESULT.
See `random-table/reporter'."
(let ((text (format "%s :: %s" expression result)))
(kill-new text)
(message text)))
;;;; Interactive
(global-set-key (kbd "H-r") #'random-table/roll)
(defun random-table/roll (text)
"Evaluate the given TEXT by \"rolling\" it.
This can either be a named table or a general text (e.g. 2d6).
Or a combination of multiple tables.
We report that function via `#'random-table/reporter'."
(interactive (list (completing-read "Expression: "
random-table/storage/tables
;; Predicate that filters out non-private tables.
(lambda (name table &rest args) (not (random-table-private table))))))
;; TODO: Consider allowing custom reporter as a function. We already register
;; it in the general case.
(apply random-table/reporter
(list text (random-table/roll/parse-text text))))
(defun random-table/roll/parse-text (text)
"Roll the given TEXT.
Either by evaluating as a `random-table' or via `s-format'."
(if-let* ((table (random-table/get-table text :allow_nil t)))
(random-table/evaluate/table table)
;; We have specified a non-table; roll the text. We'll treat a non-escaped on as a dice text.
(progn
(s-format (if (string-match-p "\\${" text) text (concat "${" text "}"))
#'random-table/roll/parse-text/replacer))))
(defun random-table/roll/parse-text/replacer (text)
"Roll the TEXT; either from a table or as a dice-expression.
This is constructed as the replacer function of `s-format'."
(if-let ((table (random-table/get-table text :allow_nil t)))
(random-table/evaluate/table table)
;; Ensure that we have a dice expression
(if (string-match-p "[0-9]?d[0-9]" text)
(format "%s" (cdr (org-d20--roll text)))
text)))
(defun random-table/evaluate/table (table)
"Evaluate the random TABLE.
See `random-table'."
(let* ((data (random-table-data table))
(name (random-table-name table))
(rolled (random-table/evaluate/table/roll table))
(filtered (apply (random-table-filter table) (-list rolled)))
(row (if filtered (apply (random-table-fetcher table) (list data (-list filtered)))
nil))
(results (or (when row (random-table/roll/parse-text row)) "")))
(remhash (random-table-name table) random-table/storage/results)
results))
(defun random-table/evaluate/table/roll (table)
"Roll on the TABLE, favoring re-using and caching values.
Why cache values? Some tables you roll one set of dice and then
use those dice to lookup on other tables."
(let ((results
(or (when-let ((reuse-table-name (random-table-reuse table)))
(or
(gethash (intern reuse-table-name) random-table/storage/results)
(random-table/evaluate/table/roll
(random-table/get-table reuse-table-name))))
(apply (random-table-roller table) (-list (random-table-data table))))))
(when-let ((stored-table-name (random-table-store table)))
(puthash (random-table-name table) results random-table/storage/results))
results))
(cl-defun random-table/get-table (value &key allow_nil)
"Coerce the given VALUE to a registered `random-table'.
When the given VALUE cannot be found in the
`random-table/stroage/tables' registry we look to ALLOW_NIL.
When ALLOW_NIL is non-nil, we return `nil' when no table is found
in `random-table/stroage/tables' registry.
When ALLOW_NIL is `nil' we raise an `error' when no table was
found in the `random-table/stroage/tables' registry."
(if-let ((table (cond
((random-table-p value)
value)
((symbolp value)
(gethash value random-table/storage/tables))
((stringp value)
(gethash (intern value) random-table/storage/tables))
((integerp value)
value)
(t
(error "Expected %s to be a `random-table', `symbol', `integer', or `string' got %s."
value
(type-of value))))))
table
(unless allow_nil
(error "Could not find table %s; use `random-table/register'." value))))
(defun random-table/dice/parse-spec (spec)
"Convert SPEC to list:
- Number of dice
- Face
- Adder
e.g. \"1d6\" -> (1 6 0) or \"2d10+2\" -> (2 10 2) or \"4dF\" -> (4 \"f\" 0)"
(when (string-match
"^\\([1-9][0-9]*\\)d\\([0-9a-zA-Z]*\\)\\([+-][0-9]*\\)?"
spec)
(list (random-table/dice/string-to-number (match-string 1 spec) 1)
(random-table/dice/string-to-number (match-string 2 spec)
decide-default-dice-facespec)
(random-table/dice/string-to-number (match-string 3 spec) 0))))
(defun random-table/dice/string-to-number (spec default)
(let ((n (if (stringp spec)
(string-to-number spec)
0)))
(cond ((null spec) default)
((> n 0) n)
((string= "+" spec) 0)
((string= "-" spec) 0)
(t spec))))
;; (let ((spec (random-table/dice/parse-spec spec-string)))
;; (apply 'decide-roll-dice-spec (if spec spec '(1 6 0))))
(provide 'random-table)
;;; random-table.el ends here
Conclusion
As I write up this blog post, I’m starting to think of how I might extend this. I certainly would love to move away from the dependency on the org-d20 package for dice rolling. However, it has thus far worked in a pinch.
I’ve also used this as a bit of a code kata. In my mentoring software developers, I often encourage folks to explore writing code for their hobby/hobbies. The idea being that you are likely a suitable domain expert in your hobby and understand the complexities. From that point of knowledge you can explore writing code.
And in this case, I wanted to explore writing more Lisp; partly because I wanted these random tables available in Emacs
during my solo RPG
sessions. But also to delve into a few more concepts Lisp; namely hashes and structs.
I had considered the decide-mode package but a major constraint was the somewhat tricky Black Sword Hack
’s “The Dark God’s Oracle.” The procedure is to ask a yes/no question and choose it’s likelihood:
“Don’t think so”
3d6, keep lowest
“Unlikely”
2d6, keep lower
“Who knows?”
1d6
“Probably”
2d6, keep higher
“Definitely”
3d6, keep highest
From the dice pool you look up the answer to the yes/no. You also check the roll…if there are doubles on the dice, you have a kicker. That bit of “dice” memory was not something I saw, nor wanted to incorporate in another package. Perhaps there’s an algebra/calculus to express this. But for now, I’ve encoded that logic as lambdas.
Summary:
Questions about idiomatic code lead to thinking about how I might use that idiom for navigation; which meant “Time to hack on Emacs” and write up some functions for navigation.
Context
while pairing with a team member, she asked about an idiom she observed. Namely that I wrote code comments as follows:
The first line of the comment block had two # characters (e.g. ##) and then following commented lines begin with #. Here’s an example:
##
# Describe the method
#
# @param value [Object]
# @return [String]
def call(value)
value.to_s
end
I told my team member that I had picked this idiom up from another Samvera📖
developer. I find it aesthetically pleasing. A nice little “cap” to a comment block, gently saying that lines above this one are not part of this chunk.
While talking, I started wondering if that other Samvera
developer, also an Emacs📖
user, had a key-binding and functions for navigating between these items?
I could see the utility of positioning the screen so that the first line is the start of a comment block. Namely, I could see the inline documentation and likely the entire method definition.
So, I wrote up two interactive functions that I bind in the ruby-mode-map.
I also bind them in the ruby-ts-mode-map, but that binding is done just a bit differently, due to load sequence.
Code
The first is a variable definition for the regular expression:
(defvar jf/ruby-mode/comment-header-regexp
"^[[:space:]]*##\\(#\\)*$"
"The regular expression for a Ruby comment header.
I noticed that a fellow Rubyist would start her method comment
blocks with \"##\". I liked how that looked, creating a clear
marker of a comment block.
Then when pairing with a team member she asked about those
comment two \"##\". I said my assumption was that they were used
for navigation. It would make sense as an anchoring point for
positioning the cursor.")
Then I define the move forward function. It checks if I’m already on the starting line of a comment; if so it moves forward one line then searches for the next line who’s first two non-space characters are ##. Finally it positions the cursor to the beginning of that line, repositions the screen so that this first line is the first line displayed in the window. Then pulses to show where the cursor is at.
When no matches are found it moves the cursor to the bottom of the buffer.
(defun jf/ruby-mode/commend-header-forward ()
"Move to next line matching `jf/ruby-mode/comment-header-regexp'."
(interactive)
(when (string-match-p
jf/ruby-mode/comment-header-regexp
(buffer-substring-no-properties
(line-beginning-position)
(line-end-position)))
(forward-line))
(condition-case err
(progn
(search-forward-regexp jf/ruby-mode/comment-header-regexp)
(beginning-of-line)
(recenter scroll-margin t)
(pulsar-pulse-line))
(error (goto-char (point-max)))))
This is similar to the above function, but instead searches backwards.
It looks a little odd, but s-[ default maps to Escape, so on my machine I have the following:
Ctrl + Cmd + [ moves backward
Ctrl + Cmd + ] moves forward
My brain has long mapped the [ and ] with modifiers as navigation keys.
I had considered using interactive search (e.g. isearch-forward) but that is something I haven’t used as much and the regular expression that I defined is not something I’d want to regularly type; though in a pinch searching for ## would be reasonable.
Conclusion
I love pairing with folks who ask questions; ones that bring curiosity to the myriad of assumptions, approaches, and idioms. From those questions grows a greater awareness and shared context. Which, I find, improves the overall experience of software development.
Summary:
A walk through of my functional adjustments to my time tracking in Org Mode. These adjustments leverage functions that I had already developed and align with other existing processes.
Context
As I wrote in
Revisiting My Org-Mode Time Tracking and Laying out a Different Direction, I’m pivoting my time tracking. I want to keep notes in corresponding projects. This should improve the conditions for information transfer when joining and leaving projects. The transfer can be me or others joining the project.
In my workflow I had three primary time tracking functions:
Creating a task
Generating a stand-up report
Summary of hours per project with each task clocked that day
Code
Preliminaries
First, I want get the filenames of all projects. My convention is adding an Org-Mode📖
keyword of PROJECT_PATHS to the document. Using Ripgrep📖
, jf/git-project-paths/dynamic finds those files.
(defun jf/git-project-paths/dynamic ()
"Return a list of code repository paths."
(split-string-and-unquote
(s-trim-right
(shell-command-to-string
(concat
"rg \"^#\\+PROJECT_PATHS: +[^\\.]+\\. +\\\"(~/git/[^/]+/)\\\"\\)\" "
"~/git/org --no-ignore-vcs --replace='$1' "
"--only-matching --no-filename")))
"\n"))
Using jf/git-project-paths/dynamic I then append additional files (via jf/org-mode/agenda-files). These are my pre-existing agenda files.
As time passes, I’ll slowly move content from those files and eventually remove the conditionals.
(defun jf/org-mode/agenda-files ()
"Return a list of note files containing 'agenda' tag.
Uses the fd command (see https://github.com/sharkdp/fd)
We want files to have the 'projects' `denote' keyword."
(let ((projects (mapcar (lambda (el) (cdr el))
(jf/project/list-projects))))
(when (file-exists-p jf/agenda-filename/scientist)
(setq projects (cons jf/agenda-filename/scientist projects)))
(when (file-exists-p jf/agenda-filename/personal)
(setq projects (cons jf/agenda-filename/personal projects)))
projects))
I dynamically update the org-agenda-files with a few different hooks. This ensures consistently updated agenda files.
(defun jf/org-mode/agenda-files-update (&rest _)
"Update the value of `org-agenda-files'."
(setq org-agenda-files (jf/org-mode/agenda-files)))
(advice-add 'org-agenda :before #'jf/org-mode/agenda-files-update)
(advice-add 'org-todo-list :before #'jf/org-mode/agenda-files-update)
(add-hook 'after-init-hook #'jf/org-mode/agenda-files-update)
Prompts for a project (via jf/project/list-projects).
Then prompts for an existing task within that project (via jf/org-mode/existing-tasks).
And starts the clock for that task.
When the task does not already exist, it creates a top-level heading at the bottom of the file.
In writing this, I realize when there is a “Footnotes” headline, I should position just above that location.
The end result is positioning point to the correct spot in the chosen project’s associated file.
(defun jf/org-mode/capture/project-task/find ()
"Find the project file and position to the selected task."
(let* ((project (completing-read "Project: " (jf/project/list-projects)))
(filename (cdar (jf/project/list-projects :project project)))
(tasks (jf/org-mode/existing-tasks filename))
(task-name (completing-read (format "Task for %s: " project) tasks)))
;; Defer finding this file as long as possible.
(find-file filename)
(if-let (task (alist-get task-name tasks nil nil #'string=))
(goto-char (org-element-property :contents-end task))
(progn
(goto-char (point-max))
;; Yes make this a top-level element. It is easy to demote and move
;; around.
(insert "* TODO " task-name " :tasks:\n\n")))))
The jf/project/list-projects function creates an alist with the car of the name of the project and the cdr as the filename for the project.
In writing this, I realize that I should refactor as there’s duplicate behavior. But for now let’s proceed.
Having this alist structure makes the prompting for completing-read very simple.
(cl-defun jf/project/list-projects (&key (project ".+")
(directory org-directory))
"Return a list of `cons' that match the given PROJECT.
The `car' of the `cons' is the project (e.g. \"Take on Rules\").
The `cdr' is the fully qualified path to that projects notes file.
The DIRECTORY defaults to `org-directory' but you can specify otherwise."
(mapcar (lambda (line)
(let* ((slugs (s-split ":" line))
(proj (s-trim (car (cdr slugs))))
(filename (s-trim (car slugs))))
(cons proj filename)))
(split-string-and-unquote
(shell-command-to-string
(concat
"rg \"^#\\+PROJECT_NAME: +(" project ") *$\" " directory
" --only-matching --no-ignore-vcs --with-filename -r '$1' "
"| tr '\n' '@'"))
"@")))
I provide a filename, then search for headlines that are marked as “todo” or one tagged with “tasks.”
(defun jf/org-mode/existing-tasks (&optional filename)
"Return an alist of existing tasks in given FILENAME.
Each member's `car' is title and `cdr' is `org-mode' element.
Members of the sequence either have a tag 'tasks' or are in a todo state."
(with-current-buffer (or (and filename
(find-file-noselect filename))
(current-buffer))
(mapcar (lambda (headline)
(cons (org-element-property :title headline) headline))
(org-element-map
(org-element-parse-buffer 'headline)
'headline
(lambda (headline)
(and
(or
(eq
(org-element-property :todo-type headline) 'todo)
(member "tasks"
(org-element-property :tags headline)))
headline))))))
Generating a Stand-up Report
My previous function relied on the time tracking hierarchy of Year > Month > Day > Project > Task. With my new structure, the previous function would not work.
One pathway, I started pursuing was using the org-ql package📖
. I have the following:
(use-package org-ql
:straight t)
(cl-defun jf/org-mode/clocked-grouped-by-title (&key (from 0) (to 0))
(-group-by (lambda (row) (car row))
(org-ql-query
:from #'org-agenda-files
:select '(list (org-get-title)
(substring-no-properties
(org-get-heading t t)))
:where '(clocked :from from :to to)
:order-by (lambda (a b)
(string= (car a) (car b))))))
It works to get a list that I can further act on. However, I ended up deferring implementing this because the summary of hours function for each week works quite well.
Summary of Hours
Built into Org-Mode
is the clocktable. The introduction of the documentation is as follows: “Org mode can produce quite complex reports based on the time clocking information.”
#+BEGIN: clocktable :scope agenda :tcolumns 1 :link t :block thisweek :narrow 80! :step day :stepskip0 t :fileskip0 t :filetitle t
#+END:
Below is an example of generating the clocktable.
Daily report: [2023-07-28 Fri]
| File | Headline | Time |
|-------+-----------------------------+------|
| | ALL Total time | 0:45 |
|-------+-----------------------------+------|
| Emacs | File time | 0:45 |
| | Refactoring Time Tracking | 0:45 |
Daily report: [2023-07-29 Sat]
| File | Headline | Time |
|-------+-----------------------------+------|
| | ALL Total time | 1:45 |
|-------+-----------------------------+------|
| Emacs | File time | 1:45 |
| | Refactoring Time Tracking | 1:00 |
| | Watch Macros and Prompting | 0:45 |
With the above clocktable parameters, each headline (e.g. “Refactoring Time Tracking” or “Watch Macros and Prompting”) is a link. And the clocktable skips all headlines that doesn’t have clocked time for the “Daily Report.”
And seeing this output, that summary is adequate for reminding me of my daily stand-up. From that, I can contextualize.
In other words, these changes better serve my thinking and note-taking, while providing adequate means of reporting my days work and recording my week’s effort.
On I’m switching teams at Software Services by Scientist.com
. This seems like a good time to change my time-tracking and note-taking processes.
Summary:
Working through my existing note-taking and time-tracking approaches and outlining a new direction; favoring thinking and task cohesion over easier time-reporting.
To sum up, I was using a single agenda file for all of my job’s time tracking. The hierarchy was: Year > Month > Day > Project > Task. When I started a task for a project, I would add a node for the project beneath the given day, then I’d add a task node beneath that project node. I’d track time to that task.
On , I wrote and implemented
Dynamic Org Agenda List Based on Denote Keywords.
I was already using a dynamic function for org-agenda-files; but it was serving a different function.
Which got me thinking about my current practices and functionality. Namely that my single agenda file, with it’s Year > Month > Day > Project > Task hierarchy, was a structure that mirrored the time reporting process and schedule. My workflow was in service to that.
However in playing with a more dynamic setting of the org-agenda-files list, I became curious about how I might revisit this approach. It felt right to:
Move my time tracking into projects.
Keep longer running notes coherent from day to day.
Have my note taking for my job serve thinking and knowledge sharing instead of time reporting constraints.
, I did further reading into Org-Mode’s clock table. And started adjusting the reporting header that I use. Later , while working (and sweating) at the Elkhart County 4-H Fair📖
, I spent more time writing about my desired workflow.
Writing Down Some Goals
My focal goal is to improve the cohesion of my note-taking (and thus thinking). The key way to do that is to stop carrying notes forward from day to day. Instead write those notes to a more canonical location (e.g. a task within a project file).
I want to have the following specific reporting features:
An overview of how many hours I’ve logged for each day of the week
A means to generate my daily stand-up
A means to easily record my hours and brief notes in our time tracking software
I want to have the means to relatively quickly create a new project. I also want a means to continue to quickly start a task by selecting the applicable project.
The function that I most want is as follows: when I start a task, I want to be able to first select an existing project, then either create a new task or select an existing non-completed task on the chosen project. I want to jump to that task.
I like tracking time at the task level, because this helps me generate the daily stand-up as well as provide notes for each day’s recorded time entry.
Conclusion
I had been using a process for quite awhile; it worked for reporting time but was not working as well for thinking and knowledge sharing. I had intuited this for some time, but it was the intersection of playing with even more dynamic org-agenda-files and adjusting my clocktable parameters that I thought through a different approach.
In the coming days, I’ll refactor some functions, introduce different ones, and again shift my workflow. And Org-Mode
and Emacs📖
will continue with me on this journey; themselves flexible and ready to help me in self-discovery.
Boris provide code and explanation to automatically updating the org-agenda-files list with only the files that have a project tag. The org-agenda-files variable defines the files that Org-Mode📖
uses to drive it’s agenda feature set. Show todos, run time reports, etc.
If the number of org-agenda-files becomes too large, then it begins to impact performance of the agenda feature set. Thus keeping a pruned list helps with performance.
I really like the idea and appreciate the implementation. However, I don’t use Org-Roam📖
; instead I used Denote📖
. So I spent a bit of time mapping Boris’s code to my reality.
Below is my walk through.
First, I am going to use a different keyword than “project.” I’m favoring the explicit “agenda”. When the note has that keyword it is part of the agenda.
(defvar jf/org-mode/agenda-keyword
"agenda"
"The `denote' keyword that identifies a note as part of `org-mode' agenda.")
Next up is almost a direct copy of vulpea-project-p; it returns non-nil when there’s a “todo” keyword on any of the nodes.
(defun jf/org-mode/agenda-p ()
"Return non-nil if current buffer has any todo entry.
TODO entries marked as done are ignored, meaning the this
function returns nil if current buffer contains only completed
tasks.
From https://d12frosted.io/posts/2021-01-16-task-management-with-roam-vol5.html"
(when (derived-mode-p 'org-mode)
(org-element-
(org-element-parse-buffer 'headline)
'headline
(lambda (h)
(eq (org-element-property :todo-type h)
'todo))
nil 'first-match)))
This is an echo of Boris’s vulpea-project-update-tag function. It’s interweaves with the functions used in Denote to determine a file’s keywords.
Aspects of the when-let* function could be compressed into a native Denote
function.
Where Org-Roam
uses SQLite for storying and accessing metadata (e.g. the tags/keywords), Denote opts instead for front-matter and file name conventions. What I have below uses the fd📖
program to query the file system for the tags/keywords.
(defvar jf/org-mode/directory-for-agendas
"~/git")
(defun jf/org-mode/agenda-files ()
"Return a list of note files containing 'agenda' tag.
Uses the fd command (see https://github.com/sharkdp/fd)
We want files either begin with the `jf/org-mode/agenda-keyword'
or by `denote' conventions have the keyword. Hence the complex regular
expression."
(let ((default-directory (file-truename
jf/org-mode/directory-for-agendas)))
(s-split "\n"
(s-trim
(shell-command-to-string
(concat "fd --no-ignore --absolute-path --extension org "
"'(^|_)" jf/org-mode/agenda-keyword "[_\\.]'"))))))
Next is similar code to update the org-agenda-files based on their tags.
(defun jf/org-mode/agenda-files-update (&rest _)
"Update the value of `org-agenda-files'."
(setq org-agenda-files (jf/org-mode/agenda-files)))
(advice-add 'org-agenda :before #'jf/org-mode/agenda-files-update)
(advice-add 'org-todo-list :before #'jf/org-mode/agenda-files-update)
Last is the most significant change. Because I’m relying on the file name to encode the keywords, I need to ensure some synchronization. In my experimentation, I ran into problems trying to rename the file during save. With this change, I rename the file when I close/kill it.
Making it Easier to Minimize Risk of Information Loss
In Emacs, when I’m writing a commit message for a repository backed by version control, and I type #123 the bug-reference package overlays that #123 with links to the remote issue. I can then “click” on #123 and jump to the issue at the remote repository; a convenient feature!
However that convenience comes with a cost, namely those terse references do two things:
create low-level lock-in
increase the risk of information loss
If I were to change the host of that repository or transfer ownership, the #123 becomes disconnected from what it once referenced.
I prefer, instead, to use full URLs 📖
. This way there is no ambiguity about what I’m referencing.
Unless of course the remote service breaks links or goes away.
Adding further nuance, due to the nature of my work, I’m often referencing other repository’s issues and pull requests during the writing of a commit.
Enter Automation
I’ve been playing with Completion at Point Functions (CaPFs 📖)
and decided the explore automatically creating those URLs
.
See Completion at Point Function (CAPF) for Org-Mode Links.
The end goal is to have a full URL.
For example https://github.com/samvera/hyrax/issues/6056.
I broke this into two steps:
Create a CaPF
for finding the project
Create a CaPF
for replacing the project and issue with the URL
I settled on the following feature:
Given that I have typed “/hyr”
When I then type {{{kbd(TAB)}}}
Then auto-complete options should include “/hyrax”
I went a step further in my implementation, when I select the project completion candidate I append a # to that. I end up with /hyrax# and the cursor is right after the # character. From which I then have my second CaPF
.
Given that the text before <point> is "/hyrax#123"
When I type {{{kbd(TAB)}}}
Then auto-complete will convert "/hyrax#123"
to "https://github.com/samvera/hyrax/issues/123"
(defun jf/version-control/project-capf ()
"Complete project links."
;; While I'm going to replace "/project" I want to make
;; sure that I don't have any odd hits (for example
;; "/path/to/file")
(when (looking-back "[^[:word:]]/[[:word:][:digit:]_\-]+"
(jf/capf-max-bounds))
(let ((right (point))
(left (save-excursion
;; First check for the project
(search-backward-regexp
"/[[:word:][:digit:]_\-]+"
(jf/capf-max-bounds) t)
(point))))
(list left right
(jf/version-control/known-project-names)
:exit-function
(lambda (text _status)
(delete-char (- (length text)))
(insert text "#"))
:exclusive 'no))))
The above function looks backwards from point, using jf/capf-max-bounds as the bounds of how far back to look. If there’s a match the function then gets the left and right boundaries and calls jf/version-control/known-project-names to get a list of all possible projects that I have on my machine.
The jf/capf-max-bounds function ensures that we don’t attempt to look at a position outside of the buffer. See the below definition:
(cl-defun jf/capf-max-bounds (&key (window-size 40))
"Return the max bounds for `point' based on given WINDOW-SIZE."
(let ((boundary (- (point) window-size)))
(if (> 0 boundary) (point-min) boundary)))
The jf/version-control/known-project-names leverages the projectile package to provides a list of known projects.
I’ve been working at moving away from projectile but the projectile-known-projects variable just works, so I’m continuing my dependency on projectile. I want to migrate towards the built-in project package, but there are a few points that I haven’t resolved.
(cl-defun jf/version-control/known-project-names (&key (prefix "/"))
"Return a list of project, prepending PREFIX to each."
(mapcar (lambda (proj)
(concat prefix (f-base proj)))
projectile-known-projects))
I then add jf/version-control/project-capf to the completion-at-point-functions variable.
I also need to incorporate that elsewhere, based on various modes. But that’s a different exercise.
The above code delivers on the first feature; namely auto completion for projects that sets me up to deliver on the second feature.
Create a CaPF
for replacing the project and issue with the URL
The jf/version-control/issue-capf function below builds on jf/version-control/project-capf convention, working then from having an issue number appended to the text.
(defun jf/version-control/issue-capf ()
"Complete project issue links."
;; While I'm going to replace "/project" I want to make sure that I don't
;; have any odd hits (for example /path/to/file)
(when (looking-back "[^[:word:]]/[[:word:][:digit:]_\-]+#[[:digit:]]+"
(jf/capf-max-bounds))
(let ((right (point))
(left (save-excursion
(search-backward-regexp
"/[[:word:][:digit:]_\-]+#[[:digit:]]+"
(jf/capf-max-bounds) t)
(point))))
(list left right
(jf/version-control/text)
:exit-function
#'jf/version-control/unfurl-issue-to-url
:exclusive 'no))))
I continue to leverage jf/capf-max-bounds querying for all matching version control text within the buffer (via jf/version-control/text):
(defun jf/version-control/text ()
"Find all matches for project and issue."
(s-match-strings-all "/[[:word:][:digit:]_\-]+#[[:digit:]]+" (buffer-string)))
Once we have a match, I use jf/version-control/unfurl-issue-to-url to convert the text into a URL
.
I had originally tried to get #123 to automatically unfurl the issue URL
for the current project. But I set that aside as it wasn’t quite working.
(defun jf/version-control/unfurl-issue-to-url (text _status)
"Unfurl the given TEXT to a URL.
Ignoring _STATUS."
(delete-char (- (length text)))
(let* ((parts (s-split "#" text))
(issue (cadr parts))
(project (or (car parts) (cdr (project-current)))))
(insert (format
(jf/version-control/unfurl-project-as-issue-url-template project)
issue))))
While demonstrating these functions to a co-worker, I said the following:
“The purpose of these URL
unfurling functions is to make it easier to minimize the risk of losing information that might be helpful in understanding how we got here.”
In other words, information is scattered across many places, and verbose URLs
are more likely to be relevant than terse short-hand references.
A future refactor would be to use the bug-reference logic to create the template; but what I have works because I mostly work on Github projects and it’s time to ship it. Also, these CaPFs
are available in other contexts, which helps with writing more expressive inline comments.
my team members began talking prefixing our commit title with the type of commit. The idea being that with consistent prefixing, we can more scan the commit titles to get an overview of what that looks like.
Formatting, missing semi colons, etc; no code change
refactor
Refactoring production code
test
Adding tests, refactoring test; no production code change
chore
Updating build tasks, package manager configs, etc; no production code change
Our proposal was that at the start of next sprint we’d adopt this pattern for one sprint and then assess. We also had a conversation about the fact that those “labels” consume precious space in the 50 character or so title.
So we adjusted our recommendation to use emojis. We established the following:
🎁
feature (A new feature)
🐛
bug fix (A bug fix)
📚
docs (Changes to documentation)
💄
style (Formatting, missing semi colons, etc; no code change)
♻️
refactor (Refactoring production code)
☑️
tests (Adding tests, refactoring test; no production code change)
🧹
chore (Updating build tasks, package manager configs, etc; no production code change)
Which means we were only surrendering 2 characters instead of a possible 8 or so.
Given that we were going to be practicing this, I wanted to have Emacs prompt me to use this new approach.
The jf/version-control/valid-commit-title-prefixes defines the glossary of emojis and their meanings:
(defvar jf/version-control/valid-commit-title-prefixes
'("🎁: feature (A new feature)"
"🐛: bug fix (A bug fix)"
"📚: docs (Changes to documentation)"
"💄: style (Formatting, missing semi colons, etc; no code change)"
"♻️: refactor (Refactoring production code)"
"☑️: tests (Adding tests, refactoring test; no production code change)"
"🧹: chore (Updating build tasks, package manager configs, etc; no production code change)")
"Team 💜 Violet 💜 's commit message guidelines on <2023-05-12 Fri>.")
I then added jf/git-commit-mode-hook which is added as find-file-hook
This hook is fired anytime we find a file and load it into a buffer.
.
(cl-defun jf/git-commit-mode-hook (&key (splitter ":") (padding " "))
"If the first line is empty, prompt for commit type and insert it.
Add PADDING between inserted commit type and start of title. For
the `completing-read' show the whole message. But use the
SPLITTER to determine the prefix to include."
(when (and (eq major-mode 'text-mode)
(string= (buffer-name) "COMMIT_EDITMSG")
;; Is the first line empty?
(save-excursion
(goto-char (point-min))
(beginning-of-line-text)
(looking-at-p "^$")))
(let ((commit-type (completing-read "Commit title prefix: "
jf/version-control/valid-commit-title-prefixes nil t)))
(goto-char (point-min))
(insert (car (s-split splitter commit-type)) padding))))
(add-hook 'find-file-hook 'jf/git-commit-mode-hook)
The jf/git-commit-mode-hook function delivers on the following two scenarios:
Given I am editing a commit message
When I start from an empty message
Then Emacs will prompt me to select the commit type
And will insert an emoji representing that type
Given I am editing a commit message
When I start from a non-empty message
Then Emacs will not prompt me to select the commit type
Conclusion
This function took about 20 minutes to write and helps me create habits around a new process. And if we agree to stop doing it, I’ll remove the hook (maybe keeping the function).
In this practice time, before we commit as a team to doing this, I am already appreciating the improved scanability of the various project’s short-logs. Further this prompt helps remind me to write small commits.
Also, in exploring how to do this function, I continue to think about how my text editor reflects my personal workflows and conventions.
In my Org-Mode writing, I frequently link to existing Denote documents. Some of those documents do not have a public URL 📖
and others do. During the export from Org-Mode to Hugo, via Ox-Hugo, linked documents that have public URLs
will be written up as Hugo shortcodes. And linked documents without public URLs
will be rendered as plain text.
The shortcode logicSee glossary.html shortcode for implementation details.
ensures that each page does not have duplicate A-tags. And in the case of abbreviations, the short code ensures that the first time I render the abbreviation, it renders as: Full Term (Abbreviation) then the next time as Abbreviation; always using the correct ABBR tag and corresponding title attribute.
Another advantage of multiple links in my Org-Mode is that when I shuffle my notes to different files, the backlink utility of Denote and Org-Roam will pick up these new documents
All of this means that my Org-Mode document is littered with links, but on export the resulting to my blog, things become tidier.
So yes, don’t repeat links in blog posts; that’s just a lot of clutter. But for Personal Knowledge Management (PKM 📖)
, spamming the links helps me ensure that I’m able to find when and where I mention things.
I write a lot of things using Org-Mode. One function I have wanted is auto-completion of links that already exist in the current Org-Mode buffer.
I have created custom links for abbreviations, epigraphs, dates, and glossary of terms.
I spent a bit of time writing that function. I remembered Org-Roam’s completion functions, so I started there for inspiration.
Writing Some Emacs Lisp
I looked to org-roam-complete-link-at-point for inspiration. I need a function that returns the text of the links. Along with the text, I would need the raw-link.
Below is jf/org-links-with-text, the function I wrote.
Here’s the link to jf/org-links-with-text.
update:
I updated the jf/org-links-with-text to handle links without labels/text.
(defun jf/org-links-with-text (&optional given-link)
"Return the `distinct-' `org-mode' links in the
`current-buffer'.
Each element of the list will be a `propertize' string where the
string value is the text of the link and the \"link\" property
will be the :raw-link.
When provided a GIVEN-LINK stop processing when we encounter the
first matching link."
(let ((links
(org-element-map
(org-element-parse-buffer)
'link
(lambda (link)
(when-let* ((left (org-element-property :contents-begin link))
(right (org-element-property :contents-end link)))
(let ((returning
(propertize
(buffer-substring-no-properties left right)
'link (org-element-property :raw-link link))))
(if given-link
(when (string= given-link returning)
returning)
returning))))
nil
given-link)))
;; Ensure that we have a distinct list.
(if (listp links)
(-distinct links)
(list links))))
The above loops through all link elements. Assembling a propertized string with each link it encounters. When provided a given-link it halts processing on the first match. And then returns a list of the matches.
I reference Org Element API when writing the function.
Here are some examples of the propertized string section of the code:
Given [[https://orgmode.org][Org-Mode]] then return the string Org-Mode with a 'link property of https://orgmode.org.
Given [[denote:20230506T202945][Title of Note]] then return the string Title of Note with a 'link property of denote:20230506T202945.
In other words, the CAPF function I’m developing will handle all Org-Mode style links.
;; Cribbed from `org-roam' org-roam-complete-link-at-point
(defun jf/org-capf-links ()
"Complete links."
(when (and (thing-at-point 'symbol)
(not (org-in-src-block-p))
(not (save-match-data (org-in-regexp org-link-any-re))))
;; We want the symbol so that links such performing completion on
;; "org-mode" will look for links with the text of org-mode and
;; then replace the text "org-mode" with the returned link.
(let ((bounds (bounds-of-thing-at-point 'symbol)))
(list (car bounds) (cdr bounds)
;; Call without parameters, getting a links (filtered by CAPF
;; magic)
(jf/org-links-with-text)
:exit-function
(lambda (text _status)
;; We want the properties of that link. In the case of one
;; match, the provided text will have the 'link property.
;; However if the
(let ((link (car (jf/org-links-with-text text))))
(delete-char (- (length text)))
(insert "[[" (get-text-property 0 'link link) "]"
"[" text "]]")))
;; Proceed with the next completion function if the returned
;; titles do not match. This allows the default Org capfs or
;; custom capfs of lower priority to run.
:exclusive 'no))))
The above jf/org-capf-links function has three significant parts:
The (when (and… section guards running in a context where things might get confusing.
The (bounds-of-thing-at-point 'symbol) section checks the current item; I could use either 'symbol or 'word; but 'symbol means I can complete or links that have dashes.
The :exit-function, and this is where I spent significant time. In my first round of testing, I had a simple Org-Mode buffer that had one link. When I called the Completion at Point Function (CaPF 📖)
function (via TAB) the lambda’s text parameter would have the propertized value.
However, when I had multiple candidates, and selected one, the lambda’s text parameter would not have the propertized value. Hence, I had to go and find again the property.
Last, I wire this into my Org-Mode.
To test the functions prior, I had already done this.
I use the Corfu and Cape packages. Below is the configuration for my Org-Mode CaPFs
:
(defun jf/org-capf ()
"The `completion-at-point-functions' I envision using for `org-mode'."
(setq-local completion-at-point-functions
(list (cape-super-capf
#'jf/org-capf-links
#'tempel-expand
#'cape-file))))
(add-hook ‘org-mode-hook #’jf/org-capf)
Conclusion
Given that I write between one thousand and four thousand words per day in Org-Mode and I do a lot of linking to code, glossaries, and external sites, I felt it worth the time and energy to write up a CaPF
that could help reduce context shifting.
Now, when I write, I can use my TAB completion to provide link candidates to insert.
, I dug a bit into his Emacs configuration; and experimented with org-tempo. But it wasn’t quite what I wanted.
So, I started cleaning up my my Emacs configuration, moving some functions I no longer use into a “graveyard” file.
During this process, I was looking at a function I had commented out. It overloaded the tilde (e.g. ~) key in Org-Mode
.
When I typed three consecutive tilde it would would replace those three tilde with a source block, position the cursor inside the block and then call org-edit-special to perhaps create a special editing buffer.
Enter the Overload of Back-tick/Grave
After typing the third consecutive back-tick, the following function:
Deletes the three back-ticks.
Prompts for the content to insert.
Positions into the newly inserted content.
Attempts to edit the content in Org-Mode
’s special editing buffer.
(defun dig-my-grave ()
"Three consecutive graves (e.g. “`”) at the start of the line prompts for
inserting content. See `dig-my-grave/templates-alist/org-mode'."
(interactive)
(if (or (and (> (point) 3)
(string= (buffer-substring-no-properties
(- (point) 3) (point)) "\n``"))
;; Account for starting on the first line
(and (= (point) 3)
(string= (buffer-substring-no-properties
(- (point) 2) (point)) "``")))
;; We have just hit our third back-tick at the beginning of the line.
(progn
(delete-char -2)
;; I use the alist-get pattern a lot...perhaps a function?
(let ((value (alist-get (completing-read "Special Content: "
dig-my-grave/templates-alist/org-mode nil t)
dig-my-grave/templates-alist/org-mode nil nil #'string=)))
(cond
;; Let's assume that we're dealing with registered org blocks.
((stringp value)
(insert value) (forward-line -1) (org-edit-special))
;; Trust the function
((commandp value) (call-interactively value))
((functionp value) (funcall value))
((ad-lambda-p) (funcall value))
;; Time for a pull request
(t (error "Unprocessable value %s for #'dig-my-grave" value)))))
(setq last-command-event ?`)
(call-interactively #'org-self-insert-command)))
For the above dig-my-grave function to work, I need map ` to the function.
Near complete control over the environment.
And below is the list of templates; They represent the vast majority of the blocks I use in Emacs📖
:
(defvar dig-my-grave/templates-alist/org-mode
'(("Bash" . "#+begin_src bash :results scalar replace :exports both :tangle yes\n#+end_src")
("Blockquote" . tempel-insert-blockquote_block)
("Details and Summary" . "#+begin_details\n#+begin_summary\n\n#+end_summary\n#+end_details")
("Emacs Lisp" . "#+begin_src emacs-lisp\n#+end_src")
("Org Structure" . org-insert-structure-template)
("Plant UML" . "#+begin_src plantuml\n@startuml\n!theme amiga\n\n@enduml\n#+end_src")
("Ruby" . "#+begin_src ruby\n#+end_src")
("Update" . tempel-insert-update_block))
"A list of `cons' cells with `car' as the label and `cdr' as
the value that we'll insert. Used as the collection for the
`dig-my-grave' `completing-read'.")
There are three functions:
tempel-insert-blockquote_quote
A Tempel template to insert a blockquote block that I export to my blog post.
tempel-insert-update_block
A Tempel template to insert an update block that I export to my blog post.
org-insert-structure-template
The build-in Org-Mode
function to prompt for registered templates.
Now I can repurpose the ingrained Markdown keystrokes for code-blocks into something useful for my Org-Mode
writing that I find easy to remember.
Which has me thinking, what are other ways that I might leverage the above function. The progn function hints at generalization. I suppose I’ll hold this and let my mind wander.
In almost all settings other than Markdown, I don’t type ```; how might I bring this to those other modes. Also, I suspect that I want to add the above to a minor-mode, so that I can disable it; in those few cases where I want to type ```.
As I grow in experience, understanding, and processes, I want my tools to grow with me. And as my growth is unique to myself, there’s an implication that I should be able to extend the tools to match my frame.
And forked a language markdown package to add some Hugo📖
functionality. The process for writing those packages felt obtuse and cumbersome.
I contrast that to my three years working in Emacs📖
. Prior to adopting Emacs
, I hadn’t programmed in Lisp📖
and as of , I have defined 231 functions in my Emacs configuration.
I ran rg "\((cl-)?defun" | wc in the root directory of my Emacs configuration.
These functions help me, in small ways, move fluidly in my day to day writing, reading, coding, and testing.
Looking at the Time Investment
Later in the interview the hosts wonder about the time investment of learning a tool versus the pay-off. I disagree with Amir’s sentiment: “If you’re career trajectory is you want to do 10 years of development and then go into lead and management, then this it’s not worth the investment.”
From where I sit, I can easily say Emacs
has been worth my investment; and will continue to pay dividends for me for years to come. Because I intend to continue writing and reading.
In fact, if I were coding less, I think Emacs
would become even more valuable. I think about Emacs for Writers; when Jay Dixit, a journalist, presented on Emacs
for writing. Watching that, I took notes and sharpened my tools.
After watching that recorded meetup, I setup my abbrev_defs to improve my auto-correction.
I write so many things in Org-Mode📖
and use the multitude of export functions to get the right format for my audience.
Using my jf/formatted-copy-org-to-html with surprising regularity, as I write notes in Emacs
and then paste them into Slack.
Advice for Junior Developers
This is some great advice:
When you’re a junior developer, you don’t have the experience and intuition to make good decisions about how your code needs to be written…Do you invest in design patterns, or elsewhere? You want to invest in your fundamentals.
The fundamentals you have in your control is typing speed; being able to quickly go to code and read it; those mechanical functions.
You’re in your exploration phase. Don’t commit to VS Code
; do Vim
, do Sublime Text
…try it all.
Conclusion
I really appreciate Amir’s four pillars enumeration. It resonates with me and draws into focus what I appreciate about Emacs
and did not appreciate about VS Code
when I last explored using it.
My advice is to broaden your time-frame of consideration for a “text editor”; in my experience I have bounced between developer, manager, and team lead. One constant has been my need to write. As a developer, I’m often writing code. As a manager, I’m more often writing documents. As a lead, I’m writing reviews, technical documents, and tasks breakdowns.
Post Script
, I had breakfast with my dad. He’s one who’s always loved working in the shop; building things. We got to talking about the tools of our trade. And how I use my tools to make more tools.
He nodded in understanding. Knowing what your tools can do, and using them to make more tools, is a virtuous cycle.
During time, I encountered two edge cases that didn’t work with the implementation I originally wrote.
These were self-inflicted edge-cases that related to some idiomatic Ruby 📖
.
The first edge case was as follows:
When I’m writing about or in Ruby📖 code, sometimes I want to grab the qualified method name. For example, let’s say I have the following Ruby code:
module Hello
module World
def foo
:bar
end
def self.call
:yup
end
end
end
The qualified method name for the method #foo would be Hello::World#foo. The qualified method name for the singleton method .call is Hello::World.call.
A Ruby documentation convention is that instance methods are prefix with a # and singleton methods are prefixed with a . or ::.
Using treesit-explore-mode, I was able to quickly refine my recursive queries. Below is treesit’s rendering of the Abstract Syntax Tree (AST 📖) of the above Ruby code:
, in a moment of dreary skies and sleeping dogs, I hacked together the following functions:
jf/treesit/qualified_method_name
Copy the qualified method name to the paste buffer (e.g. the kill-ring).
jf/treesit/module_space
Recurse up from a node to create a list of the module/class ancestors.
(require 'treesit)
(cl-defun jf/treesit/qualified_method_name (&key (type "method"))
"Get the fully qualified name of method at point."
(interactive)
(if-let ((func (treesit-defun-at-point)))
;; Instance method or class method?
(let* ((method_type (if (string= type
(treesit-node-type func))
"#" "."))
(method_name (treesit-node-text
(car (treesit-filter-child
func
(lambda (node)
(string=
"identifier"
(treesit-node-type node)))))))
(module_space (s-join "::"
(-flatten
(jf/treesit/module_space func))))
(qualified_name (concat module_space
method_type
method_name)))
(message qualified_name)
(kill-new (substring-no-properties qualified_name)))
(user-error "No %s at point." type)))
;; An ugly bit of code to recurse upwards from the node to the "oldest"
;; parent. And collect all module/class nodes along the way. This will
;; return a series of nested lists. It's on the originating caller to
;; flatten that list.
(defun jf/treesit/module_space (node)
(when-let* ((parent (treesit-parent-until
node
(lambda (n) (member (treesit-node-type n)
'("class" "module")))))
(parent_name (treesit-node-text
(car (treesit-filter-child
parent (lambda (n)
(string=
"constant"
(treesit-node-type n))))))))
(list (jf/treesit/module_space parent) parent_name)))
This is most certainly a rainy day kind of project; one that helped me learn just a bit more about the treesit package.
Postscript
The list returned by jf/treesit/module_space is '(nil ("Hello" ("World"))); which is a ugly but workable. Perhaps someone will write to me with a refactor of this code.
When I’m writing about or in Ruby 📖
code, sometimes I want to grab the qualified method name. For example, let’s say I have the following Ruby
code:
module Hello
module World
def foo
:bar
end
def self.call
:yup
end
end
end
The qualified method name for the method #foo would be Hello::World#foo. The qualified method name for the singleton method .call is Hello::World.call.
A Ruby
documentation convention is that instance methods are prefix with a # and singleton methods are prefixed with a . or ::.
Using treesit-explore-mode, I was able to quickly refine my recursive queries. Below is treesit’s rendering of the Abstract Syntax Tree (AST 📖)
of the above Ruby
code:
, in a moment of dreary skies and sleeping dogs, I hacked together the following functions:
jf/treesit/qualified_method_name
Copy the qualified method name to the paste buffer (e.g. the kill-ring).
jf/treesit/module_space
Recurse up from a node to create a list of the module/class ancestors.
(require 'treesit)
(cl-defun jf/treesit/qualified_method_name (&key (type "method"))
"Get the fully qualified name of method at point."
(interactive)
(if-let ((func (treesit-defun-at-point)))
;; Instance method or class method?
(let* ((method_type (if (string= type
(treesit-node-type func))
"#" "."))
(method_name (treesit-node-text
(car (treesit-filter-child
func
(lambda (node)
(string=
"identifier"
(treesit-node-type node)))))))
(module_space (s-join "::"
(-flatten
(jf/treesit/module_space func))))
(qualified_name (concat module_space
method_type
method_name)))
(message qualified_name)
(kill-new (substring-no-properties qualified_name)))
(user-error "No %s at point." type)))
;; An ugly bit of code to recurse upwards from the node to the "oldest"
;; parent. And collect all module/class nodes along the way. This will
;; return a series of nested lists. It's on the originating caller to
;; flatten that list.
(defun jf/treesit/module_space (node)
(when-let* ((parent (treesit-parent-until
node
(lambda (n) (member (treesit-node-type n)
'("class" "module")))))
(parent_name (treesit-node-text
(car (treesit-filter-child
parent (lambda (n)
(string=
"constant"
(treesit-node-type n))))))))
(list (jf/treesit/module_space parent) parent_name)))
This is most certainly a rainy day kind of project; one that helped me learn just a bit more about the treesit package.
Postscript
The list returned by jf/treesit/module_space is '(nil ("Hello" ("World"))); which is a ugly but workable. Perhaps someone will write to me with a refactor of this code.
This afternoon, I was exploring some Tree Sitter📖
functions in Emacs📖
. I wanted to take a Ruby 📖
’s method’s signature and create Yardoc stubs from the method parameters.
Requirements
Let’s say I have the following Ruby
method definition:
def call(foo, bar:, baz: :default, **kwargs)
# do stuff
end
I wanted to call a function and update the buffer as follows:
##
# @param foo [Object]
# @param bar [Object]
# @param baz [Object]
# @param kwargs [Object]
def call(foo, bar:, baz: :default, **kwargs)
# do stuff
end
update
I received an email pointing out that I had mixed the treesit (e.g. treesit-inspect-node-at-point) and tree-sitter (e.g. tsc-get-child-by-field) functions.
Gah! I had that in my kill-ring. I also tried the following to no avail:
The email also pointed out that my “Reply by Email” link was broken; so I fixed that.
Thank you dear reader!
The Interlude and Solution
I was encountering problems with tree-sitter functionality.
The tree-sitter package is an external package. The treesit is a built-in package in Emacs
29. I prefer tree-sitter as it’s more performant in my use case.
The following emacs-lisp writes a nil message:
The above, in my reading, should’ve found the node that had the method parameters.
Running into those problems, I took a different path. String parsing and regular expressions. Below is that solution:
(defun jf/ruby-mode/yardoc-ify ()
"Add parameter yarddoc stubs for the current method."
(interactive)
;; Remember where we started.
(save-excursion
;; Goto the beginning of the function
(ruby-beginning-of-defun)
;; Move to just after the first (
(search-forward "(")
;; Move back to just before the (
(backward-char)
;; Select parameters declaration
(mark-sexp)
;; Copy that
(copy-region-as-kill (point) (mark))
;; Split apart the parameters into their identifiers
(let ((identifiers (mapcar (lambda (token)
(replace-regexp-in-string
"[^a-z|_]" ""
(car (s-split " "
(s-trim token)))))
(s-split "," (substring-no-properties
(car kill-ring))))))
;; Go to the beginning of the function again
(ruby-beginning-of-defun)
;; Now insert the identifiers as yardoc
(insert "##\n"
(s-join "\n" (mapcar
(lambda (param)
(concat "# @param "
param
" [Object]"))
identifiers))
"\n"))))
Exploring Functionality by Re-Reading Documentation
When I first adopted the Consult package, I scanned the documentation and setup a basic configuration. I then went about using the basics and hacking functionality. I spent some time reviewing Consult’s documentation.
Below is the original advice-add for my Consult configuration. The functionality was as follows: when I have text highlighted, use the highlighted text for my line search (e.g. consult-line) and file search function (e.g. consult-ripgrep).
(defun jf/consult-first-param-is-initial-text (consult-fn &rest rest)
"Advising function around CONSULT-FN.
The CONSULT-FN's first parameter should be the initial text.
When there's an active region, use that as the first parameter
for CONSULT-FN. Otherwise, use an empty string the first
parameter. This function handles the REST of the parameters."
(interactive)
(apply consult-fn
(when (use-region-p)
(buffer-substring
(region-beginning) (region-end)))
rest))
(defun jf/consult-ripgrep-wrapper (consult-fn &optional dir given-initial)
"Advising function around CONSULT-FN.
DIR and GIVEN-INITIAL match the method signature of `consult-wrapper'."
(interactive "P")
(let ((initial (list (or given-initial
(when (use-region-p)
(buffer-substring (region-beginning)
(region-end)))))))
(apply consult-fn dir initial)))
(advice-add #'consult-line
:around #'jf/consult-first-param-is-initial-text
'((name . "wrapper")))
(advice-add #'consult-ripgrep
:around #'jf/consult-ripgrep-wrapper
'((name . "wrapper"))))
After reading the Consult README, I removed my customization and added the following:
I also took this time to review other functionality; learning about consult history functionality. When I run consult-ripgrep, I can invoke consult-history (which I’ve bound to C-c h). This then shows past searches and lets me pick from them.
I’ve been spending time actively thinking about how I’m using my editor:
Shifting key bindings to ease how my fingers stretch and move.
Reading package customization options.
Practicing new to me navigation shortcuts (looking at you Avy📖
).
Why? Because more than ever my writing is my thinking. And improving my reflexes on moving throughout my editor helps reduce mental friction; which for me reduces fatigue and increases the chances of retention during long-running tasks.
A Quick Intro to Other Open Source Note Taking Tools
Over the I’ve talked with a few folks looking at improving their note-taking game. As part of those conversations, I try to find out their use-case.
Do they want to get better at writing? Are they looking to synchronize notes across their machine? Are they looking at integration with their code and text editor?
For myself, I want my note taking functionality incorporated in my text editor. That way I can further strengthen existing muscle memory short-cuts and perhaps open pathways to consider more.
A personal wiki for Vim—interlinked, plain text files written in a markup language.
Were I using Visual Studio Code📖
, I’d go with Dendron
. If I used Vim📖
, I’d consider VimWiki
or NB
. And if I didn’t write code? I’d consider Logseq
.
All of the above options are open-source, something I consider critical to my note-taking. I do not want vendor lock-in for the information I’m gathering, organizing, and referencing.
Further, each of those applications write notes to your file system in a recoverable manner. If the application goes away, you still have the raw files written in a consistent and mostly portable format.
Documenting my High Level Workflow for Bringing the Bits to the Web
As of I build Take on Rules via a Static Site Generator (SSG 📖)
.Hugo📖
to be precise.
I write locally, run a build process which generates static HTML 📖
pages. I push those pages to a host which is then serves those via a bare-bones web-server.
I cannot express how much I appreciate that my personal blog eschews a complex web application server. My web server has no “keys to the kingdom.” It simply knows about the static pages that I give it to render.
Throughout my days, I’m reading code, writing code, documentation, and commit messages; I’m thinking through different implementation approaches for processes; reading blog posts around my hobbies and my profession; reading books for learning and pleasure. All of which I might be writing down little pointers or notes to what I am doing.
Those little pointers begin to take shape in my mind.
Composing a Blog Post
In Emacs📖
. I start writing my blog post by calling M-x jf/denote-create--blog-posts--default.
I might instead move a note into my blog-post sub-directory; which means it’s something I might make public.
This prompts me to:
Pick the type of link, describe it then insert a link to the corresponding resource. Links can be dates, abbreviations, epigraphs, files, URLs 📖
, and many other things provided by the default Org-Mode
.
org-insert-structure-template
To insert src, details, summary, marginnote, inline_comments
Some custom completion at point functions; in particular auto-completing existing abbreviations; beware when I’m in a list the capf does not work.
Another important function is my jf/org-mode/capture/insert-content-dwim. This builds on the Org-Mode
clocking function.
See Clocking Work Time (The Org Manual) for more documentation on Org-Mode
“clocking.”
When I start a clock on a blog post, I can use jf/org-mode/capture/insert-content-dwim to quickly capture text and context from other buffers.
Leveraging HTML
Semantics via Macro Substitution
Org-Mode
is a great markup format, but it doesn’t map to many semantic elements of HTML
.
Something that I appreciate. And because I’ve chosen semantic markup, I can more readily redesign my site using CSS 📖
.
Each of those macros have corresponding Tempel templates which also provide completing-read functionality by looking up all references on my local file-system.
See my templates file.
, I have just over 3000 entries in my PKM
.
858 of those entries are blog posts I’ve published.
In my
Denote Emacs Configuration blog post, I wrote about the different domains of my PKM
:
blog-posts
the blog posts I write
epigraphs
the epigraphs and quotes I’ve collected
glossary
my link farm of terms and concepts
indices
top-level indices to organize concepts
melange
a general junk drawer
people
people I know or don’t know
scientist
my work
By linking my “to be published” blog posts to internal notes, I can look at my internal notes and see their backlinks. That is what blog posts link to what notes. This is done through the denote-link-backlinks function.
See Denote’s documentation on the Backlinks buffer.
Exporting a Blog Post
I use the Ox-Hugo📖
package for exporting my blog post. I have written several overrides to the export process:
Configure to export back-ticks (e.g. `) for code blocks, instead of indentations.
Override foot note generation for side notes.
Override how I export links, to leverage my glossary and other custom mechanisms.
One advantage in overriding how my blog exports foot notes is that if when I choose to export my blog post into other formats (e.g. a PDF 📖
via LaTeX📖
), I still get foot notes.
Reviewing the Blog Post
With my blog post exported, I switch over to ~/git/takeonrules.source/, a Hugo
project that builds the static site that is Take on Rules.
I run the following Hugo
command: hugo serve -D.
The -D flag tells Hugo
to build and serve both published and draft pages.
This starts a web server which can be accessed at https://localhost:1313.
The default port when locally running Hugo
.
(the default port for Hugo
).
Publishing a Blog Post
Having checked the blog post on my local machine, I run the following command: bundle exec rake one_shot_publish.
That command does many things: first, it runs audits to ensure well-formed content.
Somewhere around version 0.78.0 of Hugo
, I was encountering rendering snafus. If memory serves, it was around the time that the maintainers were switching from one Markdown processor to another.
It also fetches data from my PKM
and generates metadata for my site.
The List of All Tables being one of those.
Eventually it creates the public directory and pushes that to my Virtual Private Server (VPS 📖)
.
Socializing the Blog Post
Sometimes I’ll syndicate to other platforms (e.g. the DEV Community📖
). Other times I’ll post to the corresponding sub-reddit. I might also post a quick link up on Mastodon📖
.
Once upon a time, I would also post to Twitter. But I
Deactivated my Twitter Account.
Conclusion
I wrote this playbook as a meditation on what steps I take to bring things forward from my personal note taking process into blog posts. These days, the notes I take are now readily available to convert into blog posts for sharing.
In this post, I want to show how I added a bit of additional color to my theme for faces assigned by the built-in Emacs📖
29 treesit package.
Introduction
adopting Emacs
, I have used the Modus Themes. I appreciate Protesilaos Stavrou (Prot 📖)
’s focus on accessibility for the Modus Themes as well as a commitment to accessible documentation.
When you dive deeper into the Modus Themes, you see how customizable and extensible the themes are.
I suspect it could be used as a theme-building framework.
I’m favoring treesit modes over other modes as Tree Sitter📖
provides a more robust syntax highlighting.
Below is my treesit and treesit-auto configuration. The treesit package is part of Emacs
29. The treesit-auto package provides automatic translations from non-treesit modes to their corresponding treesit modes.
A very helpful package to help bridge other packages that assume one language mode (e.g. ruby-mode) when treesit sets it to a different mode (e.g. ruby-ts-mode).
Next is the code I use to set my modus-theme.
I prefer the “tinted” variation as the day mode (e.g. “operandi”) it’s a bit gentler on my eyes.
Most importantly is using modus-themes-load-theme, as that is the function that calls the modus-themes-after-load-theme-hook.
More on that in a bit.
An Evening of Hacking to Provide Visual Clues for Varying Contexts
, I was pairing with a co-worker and they were sharing their iTerm2 and Visual Studio Code📖
tab colors. They mentioned that there are plugins for setting the iTerm tab color. Which had me wondering how I might configure my iTerm2 and Emacs📖
to have the same colors for the same project?
How do I create a common canonical source for colors?
After an of hacking, I have a solution that works well for my use-case.
Adjusting the Mode-line Color of Emacs
For Emacs
, I use the Modus Themes by Protesilaos Stavrou📖
. This informed my solution, as I wanted to use the named colors.
I love the modus-theme-list-colours function; it was helpful to see the range that I was working with.
I also use projectile, which provides a useful function for determining the project’s root file (e.g. “Where’s the Git📖
folder located?”)
Emacs configuration for auto-adjusting mode-line colors by project.
(require 'modus-themes)
(require 'projectile)
(defvar jf/project/theme-colors/table
'(("~/git/dotemacs/" . bg-green-subtle)
("~/git/dotzshrc/" . bg-green-nuanced)
("~/git/takeonrules.source/" . bg-magenta-subtle)
("~/git/org/" . bg-sage)
("~/git/britishlibrary/" . bg-blue-intense)
("~/git/adventist-dl/" . bg-yellow-intense)
("~/git/utk-hyku/" . bg-red-intense)
("~/git/bulkrax/" . bg-sage))
"The `car' of each list item should be of begin with \"~/\" and
end with \"/\" (so as to conform to multiple machines and
projectile's interface.")
(cl-defun jf/project/theme-colors/current (&key (default 'bg-blue-subtle))
"Returns a HEX color (e.g. \"#CCDDEE\") for the given project.
The DEFAULT is a named color in the `modus-themes' palette."
(let* ((project-dir (abbreviate-file-name (or (projectile-project-root) "~/")))
(name (alist-get project-dir
jf/project/theme-colors/table
default nil #'string=)))
(modus-themes-get-color-value name)))
(defun jf/project/theme-colors/apply-to-buffer ()
"Apply the the project's colors to the buffer (e.g. 'mode-line-active)"
(unless (active-minibuffer-window)
(progn
(face-remap-add-relative
'mode-line-active
`( :background ,(jf/project/theme-colors/current)
:foreground ,(face-attribute 'default :foreground))))))
;; I need to ensure that I'm not doing this while Emacs is initializing. If I
;; don't have the 'after-init-hook I experience significant drag/failure to
;; initialize.
(add-hook 'after-init-hook
(lambda ()
(add-hook 'buffer-list-update-hook
#'jf/project/theme-colors/apply-to-buffer)
(add-hook 'projectile-after-switch-project-hook
#'jf/project/theme-colors/apply-to-buffer)))
I did this work in three parts:
Change the mode-line-active color once.
Change the mode-line-active color based on a named Modus Theme color.
Change the mode-line-active color when I changed projects or buffers.
Adjusting the Tab Color of iTerm2
With Emacs
resolved, I set about adjust the iTerm2 tabs.
# This function sets the tab color for iTerm based on the "term-color-get"
# results.
function auto_iterm_tag_color_cwd () {
preline="\r\033[A"
# Assumes format of `"#aabbcc"'
hex=`term-color-get`
first="${hex:0:1}"
if [ "#" = "$first" ]; then
hex="${hex:1:6}"
fi
hex_r="${hex:0:2}"
hex_g="${hex:2:2}"
hex_b="${hex:4:2}"
rgb_r=`echo $((0x${hex_r}))`
rgb_g=`echo $((0x${hex_g}))`
rgb_b=`echo $((0x${hex_b}))`
echo -e "\033]6;1;bg;red;brightness;$rgb_r\a"$preline
echo -e "\033]6;1;bg;green;brightness;$rgb_g\a"$preline
echo -e "\033]6;1;bg;blue;brightness;$rgb_b\a"$preline
}
auto_iterm_tag_color_cwd
autoload -U add-zsh-hook
add-zsh-hook chpwd auto_iterm_tag_color_cwd
In working on this, I brought the solution into two steps:
First get the auto_iterm_tag_color_cwd to work with a hard-coded hex value.
Create a term-color-get function that would echo a hex value.
Common Canonical Source for Colors
A Ruby shell script to re-use the named color property of Emacs
#!/usr/bin/env ruby -wU
# This command is responsible for returning a hex color code, prefixed with the # sign. It will determine
# The following colors come from the modus tinted color palette. The names are common across
# modus-vivendi and modus-operandi but the hex colors vary.
COLOR_LOOKUP_LIGHT = {
"bg-red-intense" => "#ff8f88",
"bg-green-intense" => "#8adf80",
"bg-yellow-intense" => "#f3d000",
"bg-blue-intense" => "#bfc9ff",
"bg-magenta-intense" => "#dfa0f0",
"bg-cyan-intense" => "#a4d5f9",
"bg-red-subtle" => "#ffcfbf",
"bg-green-subtle" => "#b3fabf",
"bg-yellow-subtle" => "#fff576",
"bg-blue-subtle" => "#ccdfff",
"bg-magenta-subtle" => "#ffddff",
"bg-cyan-subtle" => "#bfefff",
"bg-red-nuanced" => "#ffe8f0",
"bg-green-nuanced" => "#e0f5e0",
"bg-yellow-nuanced" => "#f9ead0",
"bg-blue-nuanced" => "#ebebff",
"bg-magenta-nuanced" => "#f6e7ff",
"bg-cyan-nuanced" => "#e1f3fc",
"bg-ochre" => "#f0e0cc",
"bg-lavender" => "#dfdbfa",
"bg-sage" => "#c0e7d4"
}
COLOR_LOOKUP_DARK = {
"bg-red-intense" => "#9d1f1f",
"bg-green-intense" => "#2f822f",
"bg-yellow-intense" => "#7a6100",
"bg-blue-intense" => "#1640b0",
"bg-magenta-intense" => "#7030af",
"bg-cyan-intense" => "#2266ae",
"bg-red-subtle" => "#620f2a",
"bg-green-subtle" => "#00422a",
"bg-yellow-subtle" => "#4a4000",
"bg-blue-subtle" => "#242679",
"bg-magenta-subtle" => "#552f5f",
"bg-cyan-subtle" => "#004065",
"bg-red-nuanced" => "#350f14",
"bg-green-nuanced" => "#002718",
"bg-yellow-nuanced" => "#2c1f00",
"bg-blue-nuanced" => "#131c4d",
"bg-magenta-nuanced" => "#2f133f",
"bg-cyan-nuanced" => "#04253f",
"bg-ochre" => "#442c2f",
"bg-lavender" => "#38325c",
"bg-sage" => "#0f3d30"
}
COLOR_REGEXP = %r{\(mode-line-bg-color-name \. ([^\)]+)\)}
# When I have a "light" MacOS setting use the light colors.
table = `defaults read -g AppleInterfaceStyle 2>/dev/null`.strip.size.zero? ? COLOR_LOOKUP_LIGHT : COLOR_LOOKUP_DARK
# Set the default, which maps to my present default setting in Emacs.
color = table.fetch("bg-blue-subtle")
project_theme_colors_filename = File.join(Dir.home, "/git/dotemacs/emacs.d/jf-project-theme-colors.el")
if !File.exist?(project_theme_colors_filename)
puts color
exit! 0
end
# Recursively find the most dominant '.dir-locals.el' file in the ancestor directories
slugs = Dir.pwd.split("/")
(0...slugs.size).each do |i|
filename = File.join(*slugs[0...(slugs.size - i)], ".git")
next unless File.exist?(filename)
project_name = filename.sub(Dir.home, "~").sub(/\.git$/, "")
content = File.read(project_theme_colors_filename)
match = %r{\("#{project_name}" \. (bg-[^\)]+)\)}.match(content)
next unless match
color = table.fetch(match[1], color)
break
end
puts color
This bit of glue was the easiest to write. I chose to hard code the named color hex representation; as that decoupled me from needing an instance of Emacs
running.
Yes, sometimes I don’t have Emacs
running on my machine.
Citing My Sources
Along the way, I used the following sources for reference to help me build this out:
I built this up from reading a variety of different sources and then experimenting in an incremental fashion. And now I have a little bit of color in my life to help me visually note when my Emacs
buffer and iTerm2 path are pointing to the same project.
I only brought the Deadgrep package into my Emacs
configuration. Previously I had used a combination of the Embark and Wgrep.
Deadgrep provides an interface
Via a dedicated buffer
to see and edit the results as well as refine the parameters of interaction; thus creating more of a “work space” for the task of finding, refining my criteria, and possibly updating the found entries.
These concessions improves the collection of notes’s portability. And makes extensions on top of those conventions.
Org-Roam
and the recent Emacs Knowledge Graph📖
are interesting alternatives, but thus far, my emerging use-case appears well-served by the Denote
.
Each of my blog posts are a Denote Org-Mode
formatted note that I export to Hugo📖
via Ox-Hugo📖
. The benefit is that my public and private notes can reference each other, without needing to publish my private notes to the web.
Expand Region
I stumbled upon the expand-region package early in my Emacs
adoption. I use it frequently to expand or contract my current selection to the next semantic selection.
In text files the semantic units are:
word
sentence
paragraph
document
In programming files those units are:
word/symbol
function definition
class definition
file
This helps me quickly select for cut and paste, formatting, extraction, or whatever.
Fontaine
The Fontaine package helps me manage my fonts for different modes of work; I’m often coding and blogging in my editor, so I don’t switch fonts much. But I find it useful when switching to an extended pairing session or presenting a “slide deck” in Emacs.
It’s a narrow focused package that gets things very right.
Git Link
I use the Git Link packageall of the time: when I’m pairing, writing a blog post, writing up a commit message, reporting an issue, trying to help a team member orient to the code.
I like that git link creates a link that is for the current Secure Hash Algorithm (SHA 📖)
of my local repository; which helps create a more durable context.
I have further extended the Grab Mac Link package to quickly file the “page” away as a Denote
note. Thus allowing me to:
Annotate and comment on that page
Find back-links to that resource
All in service of helping me grow my digital garden.
Link Hint
I use the Link Hint package to quickly open links found in my text editor. When I invoke the link-hint-open-link, it finds all visible links in my editor’s view port.
Where there’s only one link, it opens that link in the registered application (e.g. an http link will open in my Operating System (OS 📖)
’s default web browser). Where there are multiple links in the view port, each link will be annotated with a letter. When I type one of the annotated letter’s, the link opens in the registered application.
Titlecase
Sometimes I’m surprised how much I use the titlecase package. Often when creating blog post titles and sub-titles, but also simply when working on local reports, estimates, and other documents that have headlines.
This package allows you to specify a title style guide from the following list:
AMA Style
AP Style
APA Style
Bluebook Style
Chicago Style
IMDB Style
MLA Style
New York Times Style
Sentence style
Wikipedia Style
I’ve chosen the Wikipedia Style for my default title case behavior. I invoke titlecase-dwim“Do What I Mean” function (DWIM 📖)
functions in Emacs
are typically a function that attempts to determine the current context and then dispatches to the function most related to the current context. There is titlecase-line, titlecase-region, and titlecase-sentence. The titlecase-dwim function determines which one to call.
and presto, I have a conformant title.
TMR
I spend a lot of time in Emacs
. And have grown to appreciate the TMR May Ring📖
(Also Known As (aka 📖)
“tmr”).
I can easily ignore my calendar application adding a notification. Yet when Emacs
alerts me to something, I pay attention.
I use the TMR May Ring
to set a timer in Emacs
, providing an optional description. And when the timer stops, Emacs
sends me a notification.
Conclusion
My Emacs configuration reflects my personal understanding and usage of Emacs
. It’s a place where I maintain, grow, and groom the functions that help me better tell my computer what to do.
I also use this configuration as a chance to explore and practice a Lisp📖
dialect.
This helped me create a Denote
note for each of the packages. Now, as I write more about those packages (or not), I’ll be able to build a list of references.
Further, if I were to move back towards a Literate ProgrammingEmacs
configuration, I could then use those notes to be the source of my configuration code.
An odd realization that I don’t plan on acting on, but I can begin to intuit how I might prefer that.
The above function, along with its siblings and cousins, helps ease my decision-making in regards to “Where do I put this thing that I want to later file away?”
Please note that planet.emacslife.com aggregates blogs, and blog authors might mention or link to nonfree things. To add a feed to this page, please e-mail the RSS or ATOM feed URL to sacha@sachachua.com . Thank you!
