Of note:
+ Multiline comments are with ~/' comment here '/~, single quote starts a one-line comment.
+ Nodes don't need to be declared, and their names may contain spaces if they are enclosed in double-quotes.
+ One forms an arrow between two nodes by writing a line with ~x ->[label here] y~
or ~y <- x~; or using ~-->~ and ~<--~ for dashed lines. The label is optional.
To enforce a particular layout, use ~-X->~ where ~X ∈ {up, down, right, left}~.
+ To declare that a node ~x~ has fields ~d, f~ we make two new lines having
~x : f~ and ~x : d~.
+ One adds a note near a node ~x~ as follows: ~note right of x: words then newline\nthen more words~.
Likewise for notes on the ~left, top, bottom~.
- A note can be on several lines. It's terminated by ~end note~.
+ Interesting sprites and many other things can be done with PlantUML. Read the docs.
This particular workflow is inspired by [[http://doc.norang.ca/org-mode.html][Bernt Hansen]] ---while quickly searching
through the PlantUML [[http://plantuml.com/guide][manual]]: The above is known as an “activity diagram” and
it's covered in §4.
Org-mode may be used with PlantUML:
+ See §11,12 for using Org-mode notation to form ‘mindmaps’ and ‘work breakdown
structures’.
+ Org-mode text formatters are also acknowledged but the delimiters must be
doubled; see §16.1.
You can quickly write and see the resulting UMLs using
https://liveuml.com/, for the most part.
** Clocking Work Time
:PROPERTIES:
:CUSTOM_ID: Clocking-Work-Time
:END:
Let's keep track of the time we spend working on tasks that we may have captured
for ourselves the previous day. Such statistics provides a good idea of how
long it actually takes me to accomplish a certain task in the future and it lets
me know where my time has gone.
+ Clock in :: on a heading with ~I~, or in the subtree with ~C-c C-x C-i~.
+ Clock out :: of a heading with ~O~, or in the subtree with ~C-c C-x C-o~.
+ Clock report :: See clocked times with ~C-c C-x C-r~.
After clocking out, the start and end times, as well as the elapsed time, are
added to a drawer to the heading. We can punch in and out of tasks as many times
as desired, say we took a break or switched to another task, and they will all
be recorded into the drawer.
#+begin_src emacs-lisp
;; Record a note on what was accomplished when clocking out of an item.
(setq org-log-note-clock-out t)
#+end_src
To get started, we could estimate how long a task will take and clock-in; then
clock-out and see how long it actually took.
# To review the day’s accomplishments, type ‘l’
# (org-agenda-log-mode) from the agenda view.
Sometimes, at the beginning at least, I would accidentally invoke the transposed
command ~C-x C-c~, which saves all buffers and quits Emacs. So here's a helpful
way to ensure I don't quit Emacs accidentally.
#+begin_src emacs-lisp
(setq confirm-kill-emacs 'yes-or-no-p)
#+end_src
A few more settings:
#+begin_src emacs-lisp
;; Resume clocking task when emacs is restarted
(org-clock-persistence-insinuate)
;; Show lot of clocking history
(setq org-clock-history-length 23)
;; Resume clocking task on clock-in if the clock is open
(setq org-clock-in-resume t)
;; Sometimes I change tasks I'm clocking quickly ---this removes clocked tasks with 0:00 duration
(setq org-clock-out-remove-zero-time-clocks t)
;; Clock out when moving task to a done state
(setq org-clock-out-when-done t)
;; Save the running clock and all clock history when exiting Emacs, load it on startup
(setq org-clock-persist t)
;; Do not prompt to resume an active clock
(setq org-clock-persist-query-resume nil)
;; Include current clocking task in clock reports
(setq org-clock-report-include-clocking-task t)
#+end_src
*** Finding tasks to clock in
:PROPERTIES:
:CUSTOM_ID: Finding-tasks-to-clock-in
:END:
Use one of the following options, with the top-most being the first to be tried.
+ From anywhere, ~C-u C-c C-x C-i~ yields a pop-up for recently clocked in tasks.
+ Pick something off today's agenda scheduled items.
+ Pick a ~Started~ task from the agenda view, work on this unfinished task.
+ Pick something from the ~TODO~ tasks list in the agenda view.
# Reporting activities
# C-c C-x i
~C-c C-x C-d~ also provides a quick summary of clocked time for the current org file.
*** Estimates versus actual time
:PROPERTIES:
:CUSTOM_ID: Estimates-versus-actual-time
:END:
Before clocking into a task, add to the properties drawer ~:Effort: 1:25~ or ~C-c
C-x C-e~, for a task that you estimate will take an hour and twenty-five minutes,
for example. Now the modeline will mention the time elapsed alongside the task
name. *Woah!*
#+begin_src emacs-lisp
(push '("Effort_ALL" . "0:15 0:30 0:45 1:00 2:00 3:00 4:00 5:00 6:00 0:00")
org-global-properties)
#+end_src
#+begin_quote org
Use speed keys ~e/E~ to insert an effort estimate, with the above being provided
options, or to increment the current effort to the next one in the above list.
#+end_quote
This is also useful when you simply want to put a time limit on a task that
wont be completed anytime soon, say writing a thesis or a long article, but
you still want to work on it for an hour a day and be warned when you exceed
such a time constraint.
:Not_working_for_me:
Even if you switch tasks then clock into this task again, the alarm will ring
again, nagging you to actual listen to yourself and work on other matters.
#+begin_src emacs-lisp
(setq org-clock-sound "~/.emacs.d/school-bell.wav")
#+end_src
:end:
When you've gone above your estimate time, the modeline colours it red.
** Habit Formation
:PROPERTIES:
:CUSTOM_ID: Habit-Formation
:END:
/The/ reason to use habits is that they come with a graph indicating consistency
by colour, and the goal of the game is to have [[https://lifehacker.com/jerry-seinfelds-productivity-secret-281626][the longest possible chain]] ---no
red days!
A ‘habit’ is a usual (recurring) task marked as a habit:
Use =C-c C-x p= to set the =STYLE= property to =habit= on a task to set it as a habit.
#+BEGIN_SRC emacs-lisp
(require 'org-habit) ;; To actually see the consistency graph in org-agenda
;; Show habits for every day in the agenda.
(setq org-habit-show-habits t)
(setq org-habit-show-habits-only-for-today nil)
;; This shows the ‘Seinfeld consistency’ graph closer to the habit heading.
(setq org-habit-graph-column 90)
;; In order to see the habit graphs, which I've placed rightwards, let's
;; always open org-agenda in ‘full screen’.
;; (setq org-agenda-window-setup 'only-window)
(setq org-habit-completed-glyph ?😊)
(setq org-habit-today-glyph 33)
;; When showing the agenda, do not collect habits together at the bottom, as is the default.
(add-to-list 'org-agenda-sorting-strategy '(agenda time-up priority-down category-keep))
#+END_SRC
| /inch by inch anything's a cinch!/ |
~!~ means today and ~⋆~ means a task has been done on that day;
intuitively green means you're on track, yellow is warning sign of overdue,
red is overdue, and blue is an acceptable break day.
# ! means today and * means a task has been done on that day. The color interpretation is intuitive: Green means on track, yellow warning sign of overdue, red overdue, and blue “still early, don’t feel bad taking a break”.
[[https://cpbotha.net/2019/11/02/forming-and-maintaining-habits-using-orgmode/org-habits-screenshot.png]]
Here's an example habit from the [[https://orgmode.org/manual/Tracking-your-habits.html][Org-mode manual]], where ~.+𝒳d/𝒴d~ reads
/perform the habit once every 𝒳 days, but never let me go 𝒴 days without doing it./
- (If you are procrastinating often, you can add a period in front of the
repeater, such as .+2d which will reschedule the completed item two days /after
it is completed/.)
#+begin_example org
,** TODO Shave
SCHEDULED: <2020-01-08 Wed .+2d/4d>
:PROPERTIES:
:STYLE: habit
:END:
#+end_example
/Shave every 2 days, but we can take a 3-day break; however, on the 4th day,
gotta shave!/ (To “ignore” a habit, just reschedule it for another day.)
Remember that in the agenda view if you alter a task, say with ~t~ to mark it
done, then you need to use ~s~ to save the underlying todo/notes files; otherwise,
any ~g~ will revert the change in the agenda buffer.
Habits are about “getting a little bit better at being alive, every day”.
- I don't mark habits with =TODO= so that they don't clutter up by Org-Agenda
Todos List, =C-c a t=. However, I still press ~t~ and set them to ~DONE~ and see a
message indicating that they're now rescheduled for a future time.
# (If you use ~t~ on a habit headline and mark it as ~Done~, you'll see that it
# briefly toggles to ~DONE~ and then automatically switches back to ~TODO~.)
- When this happens, the :LAST_REPEAT: timestamp will be automatically updated
to the current time, and, more importantly, the SCHEDULED date will be
automatically updated to the next earliest date when this habit should be
exercised.
- Habits appear grey in the agenda view, so that the non-habits stick out, and
hopefully in-time the habits become second nature and no longer need to be
in my agenda ---or at least, require little thought (which is happening with
the aid of checklists for my habits).
/People underestimate what can be done if you have a spare hour./
** Actually Doing Things ---or /Sending notifications from Emacs/
:PROPERTIES:
:CUSTOM_ID: Actually-Doing-Things
:END:
Let's setup a little audio-visual reminder to regularly check my agenda
and ensure I'm not narrowing on a single task and ignoring others.
+ More generally, we can use this snippet of code to let Emacs notify us of
other things.
+ For instance, the doc:message function shows text in the minibuffer, which
might be missed when there are multiple incoming messages or focus is on a
non-Emacs application (gasp!). Then, doc:my/notify could be used to produce
MacOS system-wide notifications.
The [[https://askubuntu.com/a/501917][text-to-speech tool]] we'll use is ~say~; which [[https://www.lifewire.com/mac-say-command-with-talking-terminal-2260772#:~:text=In%20the%20left%20pane%2C%20select,voices%20your%20Mac%20can%20use.][on a Mac can be activated]]
in a browser: Select some text, right-click, select ~Speech~, then ~Start/Stop Speaking~.
- TODO: Make the command below randomly use an English speaking voice; “tldr say” to learn more.
- TODO: Also finish reading the above mentioned links, with nice examples.
#+begin_src emacs-lisp
;; Obtain a notifications and text-to-speech utilities
(system-packages-ensure "say") ;; Built-into MacOS, but can be downloaded in Ubuntu
(system-packages-ensure "terminal-notifier") ;; MacOS specific
;; System Preferences → Notifications → Terminal Notifier → Allow “alerts”.
;; E.g.,: (shell-command "terminal-notifier -title \"Hiya\" -message \"hello\"")
#+end_src
By default, notifications are in banner style ---they go away automatically---
we can use alert style ---in which they stay until dismissed--- in MacOS as
follows: =System Preferences → Notifications → terminal-notifier → Alerts=.
#+begin_src emacs-lisp
(cl-defun my/notify (message &key (titled "") at repeat-every-hour open)
"Notify user with both an visual banner, with a beep sound, and a text-to-speech recitation.
When the user clicks on the resulting notification, unless a
given OPEN url is provided, the Emacs application is brough into
focus.
MESSAGE and TITLE are strings; AT is a time string as expected of
`run-at-time' such as \"11.23pm\" or \"5 sec\"; REPEAT-EVERY-HOUR
is a floating-point number of hours to continuously repeat the
alert. OPEN is a URL that is opened when the user clicks the
notification. This can be a web or file URL, or any custom URL
scheme.
I initially used optional arguments, but realised that in due time
it would be more informative to use named arguments instead.
Example uses:
;; In 5 minutes from now, remind me to watch this neato video!
(my/notify \"🔔 Get things done! 📎 💻 \"
:open \"https://www.youtube.com/watch?v=23tusPiiNZk&ab_channel=Motiversity\"
:at \"5 minutes\")
;; :at \"5 sec\"
;; Remind me to exercise every 1.5hours; starting at 8:00am.
(my/notify \"Take a 5min break and get your blood flowing!\"
:titled \"Exercise\"
:at \"8:00am\"
:repeat-every-hour 1.5)
;; Actually getting things done!
(my/notify \"Is what you're doing actually in alignment with your goals?
Maybe it's time to do another task?\"
:titled \"Check your agenda!\"
:at \"10:00am\"
:repeat-every-hour 2)
"
(run-at-time at ;; the time to make the alert
(when repeat-every-hour (* 60 60 repeat-every-hour))
#'async-shell-command
(format "%s" (s-replace "\n" ""
(s-join " " (--map (format "%s" it)
`(terminal-notifier
-title ,(pp-to-string titled)
-message ,(s-replace "\\n" "\n" (pp-to-string message))
;; Play a random sound when the notification appears. See sound names with: ls /System/Library/Sounds
;; Use the special NAME “default” for the default notification sound.
-sound ,(progn (require 'seq) (seq-random-elt (s-split "\n" (shell-command-to-string "ls /System/Library/Sounds"))))
;; Don't create duplicates of the notification, just one instance;
;; i.e., each notification belongs to a group and only one alert of the group may be present at any one time.
-group ,(pp-to-string titled)
;; Activate the application specified by ID when the user clicks the notification.
-activate org.gnu.Emacs
,@(when open `(-open ,(pp-to-string open)))
;; Run the shell command COMMAND when the user clicks the notification.
;; -execute COMMAND
;; & ;; … and then speak! …
;; NOTE:This was getting annyoning in the middle of work meetings.
;; say ,(s-replace "\\n" " " (pp-to-string message))
)))))))
#+end_src
#+RESULTS:
: my/notify
The following two actual uses cases are also mentioned in doc:my/notify
docstring, since I want the documentation to be self-contained.
#+begin_src emacs-lisp
;; (Emojis look terrible in Lisp; but much better when the alert is actually made!)
;; Remind me to exercise every 1.5hours; starting at 8:00am.
(my/notify "Take a 5min break and get your blood flowing!\n\t\t🚣 🏃♂️ 🧗♂️ 🧘♂️ 🏊 🏋 🚴♂️"
:titled "🤾♀️ Exercise 🚵♂️"
:at "8:00am"
:repeat-every-hour 1.5
:open "https://www.youtube.com/watch?v=23tusPiiNZk&ab_channel=Motiversity")
;; Actually getting things done!
(my/notify "Is what you're doing actually in alignment with your goals? ✔️📉
Maybe it's time to do another task? 📋"
:titled "📆 Check your agenda! 🔔"
:at "10:00am"
:repeat-every-hour 2)
#+end_src
+ [[https://emacs.stackexchange.com/questions/3844/good-methods-for-setting-up-alarms-audio-visual-triggered-by-org-mode-events][Here]] is an approach to triggering audio-visual alarms from Org-mode events
---using ~org-agenda-to-appt~.
+ Emacs's built in [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Appointments.html][appointment notification facility]] can also be used as a alarm
clock via ~M-x appt-add~.
The [[https://github.com/jcs-elpa/marquee-header][marquee-header]] package let's show messages as “horizontal moving text along
the top of the Emacs frame”, which is neat.
- Slightly related is [[https://github.com/jcs-elpa/logms][logms]], which let's us make ~message~ calls but we can also
/see/ the context/source where those calls were made; as well as a clickable
link back to the source.
** Using Gnus for Gmail :Disabled:
:PROPERTIES:
:CUSTOM_ID: Using-Gnus-for-Gmail
:header-args: :tangle no
:END:
:Alread_done_elsewhere:
Let's set the following personal Emacs-wide variables ---to be used in other
locations besides email.
#+begin_src emacs-lisp
(setq user-full-name "Musa Al-hassy"
user-mail-address "alhassy@gmail.com")
#+end_src
For some fun, run this cute method.
#+BEGIN_SRC emacs-lisp :tangle no
(animate-birthday-present user-full-name)
#+END_SRC
:End:
By default, in Emacs, we may send mail: Write it in Emacs with ~C-x m~ ---or
doc:compose-mail---, then press ~C-c C-c~ to have it sent via your OS's default
mailing system ---mine appears to be Gmail via the browser. Or cancel sending
mail with ~C-c C-k~ ---the same commands for org-capturing, discussed earlier
(•̀ᴗ•́)و
Folowing [[https://eschulte.github.io/emacs24-starter-kit/starter-kit-gnus.html][this tutorial]], to send and read email in Emacs we use [[https://en.wikipedia.org/wiki/Gnus][GNUS]], which, like
GNU itself, is a recursive acronym: GNUS Network User Service.
1. Execute, rather place in your init:
#+begin_src emacs-lisp
(setq message-send-mail-function 'smtpmail-send-it)
#+end_src
Revert to the default OS mailing method by setting this variable to
~mailclient-send-it~.
# (gnutls-available-p)
2. Follow only the [[https://www.emacswiki.org/emacs/GnusGmail#toc1][quickstart here]]; namely, make a file named ~~/.gnus~ containing:
#+begin_src emacs-lisp :tangle ~/.gnus
;; user-full-name and user-mail-address should be defined
;; Get mail using port 993/IMAP/“Internet Message Access Protocol”
(setq gnus-select-method
'(nnimap "gmail"
(nnimap-address "imap.gmail.com")
(nnimap-server-port 993)
(nnimap-stream ssl)))
;; Send mail using port 587/SMTP/“Simple Mail Transfer Protocol”
(setq message-send-mail-function 'smtpmail-send-it
smtpmail-starttls-credentials '(("smtp.gmail.com" 587 nil nil))
smtpmail-auth-credentials '(("smtp.gmail.com" 587 "alhassy@gmail.com" nil))
smtpmail-default-smtp-server "smtp.gmail.com"
smtpmail-smtp-server "smtp.gmail.com"
smtpmail-smtp-service 587)
#+end_src
# (system-packages-install "starttls")
# (setq gnus-ignored-newsgroups "^to\.\|^[0-9. ]+\( \|$\)\|^["]"[#'()]")
3. Get an email password for GNUS:
1. Go to https://myaccount.google.com/security.
2. Enable ~2-Step Verification~
3. Click on ~App passwords~, login, then generate a new password
with, say, name ~Emacs Gnus~.
4. You will then obtain a secret password, the ~x~ marks below, which you insert
in a file named ~~/.authinfo~ as follows ---using your email address.
#+begin_src shell :tangle no
machine smtp.gmail.com login alhassy@gmail.com password xxxxxxxxxxxxxxxx port 587
machine imap.gmail.com login alhassy@gmail.com password xxxxxxxxxxxxxxxx port 993
default login alhassy@gmail.com password xxxxxxxxxxxxxxxx
#+end_src
4. In Emacs, ~M-x gnus~ to see what's there.
- Or compose mail with ~C-x m~ then send it with ~C-c C-c~.
- Press ~C-h m~ to learn more about message mode for mail composition; or
read the [[https://www.gnus.org/manual/message.pdf][Message Manual]].
Only news groups with /unread mail/ are shown; to see all your groups (Gmail
‘tags’), press ~A A~ (doc:gnus-group-list-active), then press ~u~ to toggle
(un)subscription to such groups and they will show up in the main group
buffer ---if they have /unread mail/. See [[https://sachachua.com/blog/2008/05/emacs-gnus-organize-your-mail/][here]] for a tutorial on splitting
mail groups, automatically or fancily filing them away.
--------------------------------------------------------------------------------
#+BEGIN_SRC emacs-lisp
;; After startup, if Emacs is idle for 10 seconds, then start Gnus.
;; Gnus is slow upon startup since it fetches all mails upon startup.
(when my/personal-machine?
(run-with-idle-timer 10 nil #'gnus))
#+END_SRC
Learn more by reading [[https://www.gnu.org/software/emacs/manual/html_mono/gnus.html#Top][The Gnus Newsreader Manual]]; also available within Emacs by
~C-h i m gnus~ (•̀ᴗ•́)و
- Or look at the [[https://www.gnu.org/software/emacs/refcards/pdf/gnus-refcard.pdf][Gnus Reference Card]].
- Or, less comprehensively, this [[https://github.com/redguardtoo/mastering-emacs-in-one-year-guide/blob/master/gnus-guide-en.org#subscribe-groups][outline]].
- [[https://www.emacswiki.org/emacs/GnusTutorial][EmacsWiki]] has a less technical and more user friendly tutorial.
- Other possibly useful links:
+ [[http://www.cataclysmicmutation.com/2010/11/multiple-gmail-accounts-in-gnus/][Multiple Gmail accounts in Gnus]]
--------------------------------------------------------------------------------
#+begin_details Super Terse Tutorial
link-here:Super-Terse-Tutorial
⟨ See the [[https://www.gnu.org/software/emacs/refcards/pdf/gnus-refcard.pdf][GNUS Reference Card]]! ⟩
In gnus, by default items you've looked at disappear ---i.e., are archived.
They can still be viewed in, say, your online browser if you like.
In the ~Group~ view, ~R~ resets gnus, possibly retriving mail or alterations
from other mail clients. ~q~ exits gnus in ~Group~ mode, ~q~ exits the particular
view to go back to summary mode. Only after pressing ~q~ from within a group
do changes take effect on articles ---such as moves, reads, deletes, etc.
+ Expected keys: ~RET~ enter/open an item, ~q~ quit and return to previous view, ~g~
refresh view ---i.e., ‘g’et new articles.
+ =RET=: Enter a group by pressing, well, the enter key.
- Use ~SPC~ to open a group and automatically one first article there.
- Use ~C-u RET~ to see all mail in a folder instead of just unread mail.
+ Only groups/folders with unread mail will be shown, use ~L/l~ to toggle between
listing all groups.
+ ~SPC, DEL~ to scroll forward and backward; or ~C-v, M-v~ as always.
+ =G G=: Search mail at server side in the group buffer.
- Limit search to particular folders/groups by marking them with ~#~, or
unmarking them with ~M-#~.
+ ~/ /,a:~ Filter mail according to subject or author; there are many
other options, see [[https://www.gnu.org/software/emacs/manual/html_mono/gnus.html#Limiting][§3.8 Limiting]].
+ =d=: Mark an article as done, i.e., read it and it can be archived.
+ =!=: Mark an article as read, but to be kept around ---e.g., you have not
replied to it, or it requires more reading at a later time.
This lets us read mail offline; cached mail is found at =~/News/cache/=.
#+BEGIN_SRC emacs-lisp :tangle "~/.gnus"
(setq gnus-use-cache 'use-as-much-cache-as-possible)
#+END_SRC
+ =B m=: Move an article, in its current state, to another group ---i.e.,
‘label’ using Gmail parlance.
- Something to consider doing when finished with an article.
To delete an article, simply move it to ‘trash’ ---of course this will delete it
in other mail clients as well. There is no return from trash.
Emails can always be archieved ---never delete, maybe?
Anyhow, ~B m Trash~ is too verbose, let's just use ~t~ for “trash”:
#+BEGIN_SRC emacs-lisp
(with-eval-after-load 'gnus
(bind-key "t"
(lambda (N) (interactive "P") (gnus-summary-move-article N "[Gmail]/Trash"))
gnus-summary-mode-map))
;; Orginally: t ⇒ gnus-summary-toggle-header
#+END_SRC
- Select and deselect many articles before
moving them by pressing ~#~ and ~M-#~, respectively, anywhere on the entry.
- As usual, you can mark a region, =C-SPC=, then move all entries therein.
+ =R, r=: Reply with sender's quoted text in place, or without but
still visible in an adjacent buffer.
- Likewise ~S W~ or ~S w~ to reply all, ‘wide reply’, with or without quoted text.
- ~C-c C-z~ Delete everything from current position till the end.
- ~C-c C-e~ Replace selected region with ‘[...]’; when omitting parts of quoted text.
+ Press ~m~ to compose mail; or ~C-x m~ from anywhere in Emacs to do so.
- ~C-c C-c~ to send the mail.
- ~S D e~ to resend an article as new mail: Alter body, subject, etc, before
- ~C-c C-f~ to forward mail.
sending.
+ ~C-c C-a~ to attach a file; it'll be embedded in the mail body as plaintext.
- Press ~o~ on an attachment to save it locally.
#+end_details
#+begin_details GNUS Prettifications
link-here:gnus-prettifications
Let's add the icon near my mail groups ^_^
#+BEGIN_SRC emacs-lisp
;; Fancy icons for Emacs
;; Only do this once:
(use-package all-the-icons
:config (all-the-icons-install-fonts 'install-without-asking))
;; Make mail look pretty
(use-package all-the-icons-gnus
:disabled t
:config (all-the-icons-gnus-setup))
;; While we're at it: Make dired, ‘dir’ectory ‘ed’itor, look pretty
(use-package all-the-icons-dired
:disabled t
:hook (dired-mode . all-the-icons-dired-mode))
#+END_SRC
Next, let's paste in some [[http://groups.google.com/group/gnu.emacs.gnus/browse_thread/thread/a673a74356e7141f][eye-candy for Gnus]]:
#+begin_src emacs-lisp
(setq gnus-sum-thread-tree-vertical "│"
gnus-sum-thread-tree-leaf-with-other "├─► "
gnus-sum-thread-tree-single-leaf "╰─► "
gnus-summary-line-format
(concat
"%0{%U%R%z%}"
"%3{│%}" "%1{%d%}" "%3{│%}"
" "
"%4{%-20,20f%}"
" "
"%3{│%}"
" "
"%1{%B%}"
"%s\n"))
#+end_src
#+end_details
#+begin_details "Sending Mail with Lisp ---e.g., as a Bulk Mailer"
link-here:bulk-mailer
#+begin_src emacs-lisp :results replace :wrap template
(defun my/email (to subject body)
(compose-mail to subject)
(insert body)
(message-send-mail) ;; Appends info to the message buffer
; (let ((kill-buffer-query-functions nil)) (kill-this-buffer))
(ignore-errors (undo)) ;; Undo that addition
(message-kill-buffer)
(message "Send email to %s" to)) ;; Close that message buffer
#+end_src
#+begin_src emacs-lisp :results replace :wrap template :tangle no
;; Example
(my/email (format "%s <%s>" user-full-name user-mail-address) ;; To
"Test" ;; Subject
"Why hello there!") ;; Email body
#+end_src
#+end_details
#+begin_details [Disabled] Auto-completing mail addresses
# :CUSTOM_ID: Auto-completing-mail-addresses
In order to get going quickly, using [[https://github.com/redguardtoo/gmail2bbdb][gmail2bbdb]], let's convert our Gmail
contacts into a BBDB file ---the [[http://bbdb.sourceforge.net/][Insidious Big Brother Database]] is an
address-book application that we'll use for E-mail; if you want to use it as a
address-book application to keep track of contacts, notes, their organisation,
etc, then consider additionally installing [[https://github.com/emacs-helm/helm-bbdb][helm-bbdb]] which gives a nice menu
interface.
- From the [[https://www.google.com/contacts][Gmail Contacts page]], obtain a =contacts.vcf= file by clicking “More ->
Export -> vCard format -> Export”.
- Run command =M-x gmail2bbdb-import-file= and select =contacts.vcf=; a ~bbdb~ file
will be created in my Dropbox folder.
- Press ~C-x m~ then begin typing a contact's name and you'll be queried about
setting up BBDB, say yes.
#+begin_src emacs-lisp :tangle no
(use-package gmail2bbdb
:custom (gmail2bbdb-bbdb-file "~/Dropbox/bbdb"))
(use-package bbdb
:after company ;; The “com”plete “any”thig mode is set below in §Prose
:hook (message-mode . bbdb-insinuate-gnus)
(gnus-startup-hook . bbdb-insinuate-gnus)
:custom (bbdb-file gmail2bbdb-bbdb-file)
(bbdb-use-pop-up t) ;; allow popups for addresses
:config (add-to-list 'company-backends 'company-bbdb))
#+end_src
Here is an [[http://emacs-fu.blogspot.com/2009/08/managing-e-mail-addresses-with-bbdb.html][emacs-fu]] article on managing e-mail addressed with bbdb.
#+end_details
#+begin_details [Disabled] Feeds to Blogs
link-here:gnus-feeds-to-blogs
One can easily subscribe to an RSS feed in Gnus: Just press ~G R~ in the group
buffer view, then follow the prompts. However, doing so programmatically is much
harder. Below is my heartfelt attempt at doing so ---if you want a feed reader
in Emacs that “just works”, then [[https://github.com/skeeto/elfeed][elfeed]] is the way to go. When all is said and
done, the code below had me reading Gnus implementations and led me to conclude
that /Gnus has a great key-based interface but a /poor programming interface/ ---or
maybe I need to actually read the manual instead of frantically consulting
source code.
My homemade hack to getting tagged feeds programmatically into Gnus.
#+begin_src emacs-lisp :tangle no
;; Always show Gnus items organised by topic.
(add-hook 'gnus-group-mode-hook 'gnus-topic-mode)
;; From Group view, press ^, then SPC on Gwene, then look for the site you want to follow.
;; If it's not there, add it via the web interface http://gwene.org/
(add-to-list 'gnus-secondary-select-methods '(nntp "news.gwene.org"))
;;
;; E.g., http://nullprogram.com/feed/ uses an Atom feed which Gnus does not
;; support natively. But it can be found on Gwene.
(setq my/gnus-feeds
;; topic title url
'(Emacs "C‘est La 𝒵" https://cestlaz.github.io/rss.xml
Emacs "Marcin Borkowski's Blog" http://mbork.pl?action=rss
Emacs "Howardism" http://www.howardism.org/rss.xml
Islam "Shia Islam Blogspot" http://welcometoshiaislam.blogspot.com/feeds/posts/default?alt=rss
Cats "Hedonistic Learning" http://www.hedonisticlearning.com/rss.xml
Cats "Functorial Blog" https://blog.functorial.com/feed.rss
Programming "Joel on Software" http://www.joelonsoftware.com/rss.xml
Haskell "Lysxia's Blog" https://blog.poisson.chat/rss.xml))
;; If fubared, then:
;; (ignore-errors (f-delete "~/News/" 'force) (f-delete "~/.newsrc.eld"))
;; Execute this after a Gnus buffer has been opened.
(progn
(use-package with-simulated-input)
(cl-loop for (topic title url)
in (-partition 3 my/gnus-feeds)
;; url & topic are symbols, make them strings.
for url′ = (symbol-name url)
for topic′ = (symbol-name topic)
;; Avoid spacing issues by using a Unicode ghost space “ ”.
for title′ = (gnus-newsgroup-savable-name (s-replace " " " " title))
for input = (format "C-SPC C-a %s RET RET" title′)
do
; cl-letf* (((symbol-function 'insert) (lambda (x) nil))) ;; see the (undo) below.
;; Add the group
(with-simulated-input input
(gnus-group-make-rss-group url′))
;; Ensure it lives in the right topic category.
(if (equal 'no-such-topic (alist-get topic gnus-topic-alist 'no-such-topic nil #'string=))
(push (list topic′ title′) gnus-topic-alist) ;; make topic if it doesnt exist
(setf (alist-get topic′ gnus-topic-alist 'no-such-topic nil #'string=)
(cons title′ (alist-get topic gnus-topic-alist 'no-such-topic nil #'string=)))))
;; Acknowledgement
(message "Now switch into the GNUS group buffer, and refresh the topics; i.e., t t."))
;; The previous command performs an insert, since it's intended to be interactively
;; used; let's undo the insert.
; (undo-only)
;; (setq gnus-permanently-visible-groups ".*")
;;
;; Show topic alphabetically? The topics list is rendered in reverse order.
;; (reverse (cl-sort gnus-topic-alist 'string-lessp :key 'car))
#+end_src
Ironically, I've decide that “no, I do not want to see my blogs in Emacs” for
the same reasons I do not activelly use ~M-x eww~ to browse the web in Emacs: I
like seeing the colours, fonts, and math symbols that the authours have labored
over to producing quality content. Apparently, I'm shallow and I'm okay with it
---but not that shallow, since I'm constantly pushing Emacs which looks ugly by
default but it's unreasonably powerful.
#+end_details
*** Capturing Mail as Todo/Notes
:PROPERTIES:
:CUSTOM_ID: Capturing-Mail-as-Todo-Notes
:END:
Sometime mail contains useful reference material or may be a self-contained
task. Rather than using our inbox as a todo-list, we can copy the content of the
mail and store it away in our todos/notes files. [[#Capturing-ideas-notes-without-interrupting-the-current-workflow][Capturing]], above, is a way to,
well, capture ideas and notes /without/ interrupting the current workflow. Above,
in the section on capturing, we define doc:my/org-capture-buffer which quickly
captures the contents of the current buffer as notes to store away. We use that
method in the article view of mail so that [[kbd:c]] captures mail content with the
option to provide additional remarks, and [[kbd:C]] to silently do so without
additional remarks.
#+BEGIN_SRC emacs-lisp
(with-eval-after-load 'gnus
;; Orginally: c ⇒ gnus-summary-catchup-and-exit
(bind-key "c" #'my/org-capture-buffer gnus-article-mode-map)
;; Orginally: C ⇒ gnus-summary-cancel-article
(bind-key "C"
(lambda (&optional keys)
(interactive "P") (my/org-capture-buffer keys 'no-additional-remarks))
gnus-article-mode-map))
#+END_SRC
Gnus’ default =c= only enables a bad habit: Subscribing to stuff that you don't
read, since you can mark all entries as read with one key. We now replace it
with a ‘c’apturing mechanism that captures the current message as a todo or note
for further processing. Likewise, the default =C= is to cancel posting an article;
we replace it to be a /silent capture: Squirrel away informative mail content
without adding additional remarks./
*** Email contacts
:PROPERTIES:
:CUSTOM_ID: Email-contacts
:END:
I have a personal file, ~contacts.org~, with Emacs Lisp src blocks contributing to
a list variable ~my/contacts~. This list consists of entries of the shape:
#+begin_src emacs-lisp :tangle no
(:name "Jasim Jasonsama" :phone 123-455-4321 :email bobert_billiam@emacsmail.com)
#+end_src
With the following snippet, I can write ~contacts~ then kbd:TAB to select a
personal contact.
#+begin_src org :noweb-ref templates-from-other-places-in-my-init :tangle no :comments none
,** contacts: Get the email of one of my personal contacts
${1:`(and (or (featurep 'my/contacts) (org-babel-load-file "~/Dropbox/contacts.org"))
(yas-choose-value (--map (format "%s <%s>" (getf it :name) (getf it :email))
my/contacts)))`} $0
#+end_src
** [[https://github.com/sabof/stripe-buffer][Add stripes to "list" buffers]]
:PROPERTIES:
:CUSTOM_ID: https-github-com-sabof-stripe-buffer-Add-stripes-to-list-buffers
:END:
#+begin_src emacs-lisp
;; Make every other line of a buffer grey (or whatever you like).
;; Useful for buffers that list things.
;; I want it to make my Org tables look nice. Even better when org-modern is activated.
(use-package stripe-buffer
:defer 100
:config (add-hook 'org-mode-hook 'turn-on-stripe-table-mode))
#+end_src
** Basic Agenda Config
#+begin_src emacs-lisp
(setq org-agenda-files (list "~/Documents/notes.org"))
(setq org-agenda-span 'week)
;; (setq org-agenda-custom-commands '(("o" "Open Loops" tags-tree "TODO=\"STARTED\"" )))
(setq org-log-into-drawer t) ;; hide the log state change history a bit better
(setq org-fold-catch-invisible-edits 'show-and-error ;; Avoid accidental edits to folded sections
org-special-ctrl-a/e t ;; C-a/C-e know about leading “*” and ending :tags:
;; Agenda styling
org-agenda-tags-column -80
org-agenda-time-grid '((daily today require-timed)
(800 1000 1200 1400 1600 1800 2000)
" ───── " "───────────────")
org-agenda-current-time-string "◀── now ─────────────────────────────────────────────────")
;; p to “p”ush back a task to the next day.
(add-hook 'org-agenda-mode-hook
;; Note: There's also org-agenda-date-earlier to change the date by -1 day.
(lambda ()
(define-key org-agenda-mode-map "p" 'org-agenda-date-later)
;; Reschedule agenda items to today, “right 𝓃ow”, with a single command
(define-key org-agenda-mode-map "n" (defun org-agenda-reschedule-to-today ()
(interactive)
(flet ((org-read-date (&rest rest) (current-time)))
(call-interactively 'org-agenda-schedule))))))
#+end_src
** Informative [[https://arc.net/l/quote/jhczngfy][log notes]]
Let's change only two pieces, to make them more informative.
#+begin_src emacs-lisp
(setq org-log-note-headings '((done . "CLOSING NOTE %t")
(state . "State %-12s from %-12S %t")
(note . "Note taken on %t")
;; (reschedule . "Rescheduled from %S on %t") ;; Default
(reschedule . "Schedule changed on %t: %S -> %s")
(delschedule . "Not scheduled, was %S on %t")
(redeadline . "Deadline changed on %t: %S -> %s")
;; (redeadline . "New deadline from %S on %t") ;; Default
(deldeadline . "Removed deadline, was %S on %t")
(refile . "Refiled on %t")
(clock-out . "")))
#+end_src
** COMMENT See all motivational images I have, and indent things so it's clearer when something is a child of something else
TODO: Causes weird max-image-size issues?
#+begin_src emacs-lisp
(defun my/org-settings ()
(org-display-inline-images)
(org-indent-mode)
nil)
(add-hook 'org-mode-hook #'my/org-settings)
#+end_src
** COMMENT org-num-mode :SeemsTooBrokenForMe:
#+begin_src emacs-lisp
;; Please dynamically number all headlines
(setq org-startup-numerated t)
;; More options @ https://orgmode.org/manual/Dynamic-Headline-Numbering.html
;; Prefer “𝓏” instead of “𝓍.𝓎.𝓏” ---indentation ‘org-indent-mode’ resolves ambiguity
(setq org-num-format-function (defun my/org-num-format (number-path) (format "%s " (car (last number-path)))))
#+end_src
** How tasks look in org agenda
#+begin_src emacs-lisp
;; Start each agenda item with ‘○’, then show me it's %timestamp and how many
;; times it's been re-%scheduled.
(setq org-agenda-prefix-format " ○ %?-12t%-6e%s ")
;; (setq org-agenda-deadline-leaders '("DUE: " "In %3d d.: " "%2d d. ago: "))
;; Don't say “Scheduled ⟨Task⟩”, just show “⟨Task⟩”.
;; If something's overdue, say “Overdue 𝓃× ⟨Task⟩”.
(setq org-agenda-scheduled-leaders '("" "Overdue%2dx "))
#+end_src
** I use lots of “checkbox lists” in my routines: I want to think about things once, then follow the routine on auto-pilot
#+begin_src emacs-lisp
;; list items will be treated like low-level headlines; i.e., folded by default.
(setq org-cycle-include-plain-lists 'integrate)
;; clear checkbox when repeating a todo task
(add-hook 'org-todo-repeat-hook #'org-reset-checkbox-state-subtree)
;; clear sub-sub-tasks when repeating a todo task.
;; ⇒ If I have “** A [%] \n #+STYLE: habit \n SCHEDULED: <2024-04-19 Fri .+1d> \n *** DONE B”
;; then on “** A” I press ‘t’ then mark it as ‘DONE’, then the “*** B” task resets to ‘TODO’.
(add-hook 'org-todo-repeat-hook
(lambda () (org-map-entries (lambda () (when (> (length (org-get-outline-path)) 1) (org-todo "TODO"))) t 'tree)))
;; “C-c a t” ⇒ List all (non-recurring non-someday) todos sorted by state, priority, effort
(setq org-agenda-custom-commands
'(("t" "My list of all TODO entries" tags-todo "-recurring-someday"
((org-agenda-overriding-header "\nTODOs sorted by state, priority, effort")
(org-agenda-sorting-strategy '(todo-state-down priority-down effort-up))))))
#+end_src
** Work links
:PROPERTIES:
:CUSTOM_ID: my-work-links
:END:
In my private ~work.el~ file, I have declarations of the form ~(my/work-links
"REPO" "https://⟨COMPANY⟩.atlassian.net/browse/REPO-%s")~ so that I can write
things like ~REPO:1234~ to get a nice green bold link in Org-mode that will take
me to that Jira link. I also have similar links to take me to the Github
repositories, backlogs, and Kanban boards.
#+begin_src emacs-lisp
(cl-defmacro my/work-links (type url &optional (export-display '(format "%s-%s" type label)))
"Given a link of TYPE with a URL, produce the correct org-link.
EXPORT-DISPLAY is string-valued term that may mention the symbolic names ‘type’ and ‘label’.
This is how the link looks upon export."
`(org-link-set-parameters
,type
:follow (lambda (label) (browse-url (format ,url label)))
:export (lambda (label description backend)
(-let [full-url (format ,url label)]
(pcase backend
('html (format "%s" full-url (-let [type ,type] ,export-display)))
('latex (format "\\href{%s}{%s}" full-url label))
(_ full-url))))
:face '(:foreground "green" :weight bold
:underline "blue" :overline "blue")))
#+end_src
#+begin_src emacs-lisp
(defvar COMPANY (getenv "COMPANY") "Name of place I work at.")
(my/work-links "FWD" (lf-string "https://bugs.local.${(downcase COMPANY)}.com/browse/FWD-%s"))
(my/work-links "OUT" (lf-string "https://bugs.local.${(downcase COMPANY)}.com/browse/OUT-%s"))
(my/work-links "gerrit" (lf-string "https://gerrit.local.${(downcase COMPANY)}.com/c/fwd/+/%s"))
;; Open all such links in Chrome
(setq browse-url-browser-function 'browse-url-default-macosx-browser)
#+end_src
** Quick Capture
#+begin_src elisp
;; Location of my todos / captured notes file
(setq org-default-notes-file "~/Documents/notes.org")
#+end_src
#+begin_src elisp
(defmacro def-capture (name location template)
"Creates a method “my/capture-NAME”, which opens a capture buffer named NAME showing TEMPLATE.
When you press `C-c C-c`, the note is saved as an entry (ie TEMPLATE should start with “* ”.)
in `org-default-notes-file' section named LOCATION.
+ NAME, LOCATION, TEMPLATE are all strings that may contain spaces.
⇒ If you want to evaluate a function in TEMPLATE, use the syntax “%(f args)”.
See https://stackoverflow.com/a/69331239 for an example.
+ Example: (def-capture \"Friends Info\" \"Journal\" \"* %t\")
This can be used as “M-x my/capture-friends-info” or via an Org link: “[[elisp:( my/capture-friends-info)]]”.
Note: My “Journal” is nested in a section called “Workflow”, and capture finds it anyways (｡◕‿◕｡)
(More precisely, Org-Capture looks for the first (sub)headline called “Journal” /anywhere/ and uses that as the target location.)
Usage:
1. M-x my/capture-NAME ⇒ Capture something to my LOCATION; no menu used.
2. C-u M-x my/capture-NAME ⇒ Jump to my LOCATION.
3. C-u C-u M-x my/capture-NAME ⇒ Goto last note stored (by any my/capture-* method).
"
`(defun ,(intern (concat "my/capture-" (s-replace-regexp " " "-" (downcase name)))) (&optional prefix)
(interactive "p")
(-let [org-capture-templates
;; I'm using omega 𝓌 as a placeholder; i.e., a gensym-like key.
`(("𝓌" ,,name entry (file+headline ,,org-default-notes-file ,,location) ,,template))]
(org-capture (list prefix) "𝓌")
(unless (> prefix 1) (rename-buffer ,name)))))
#+end_src
*** C-c c ⇒ Capture inbox entry
#+begin_src elisp
;; I mark inbox captures as “TODO” so that they appear in my task list (C-c a t) in the event
;; I've forgotten to process my inbox.
;;
;; When I process my “* Inbox” section, I am left with an empty Org section and so delete it.
;; ⇒ “C-c c” will create the section if it does not exist.
;; ⇒ Deleting it is a nice ‘cheery on top’ when processing my inbox (✿◠‿◠)
(bind-key* "C-c c" (def-capture "Inbox Entry" "Inbox" "* TODO %?\n Captured: %U \n"))
#+end_src
*** Capture morning journal entry
#+begin_src elisp
(defalias #'my/new-journal-entry (def-capture "Journal Entry" "Journal"
(s-join "\n\n" (list
(format-time-string "* %Y-%m-%d %a %R :mood_𝒏%?:")
"My most important goal for the day is: "
(let (todays-agenda) (org-agenda-list 1) (setq todays-agenda (buffer-string)) (org-agenda-quit)
(concat "Here's what my day looks like so far:\n" todays-agenda))))))
#+end_src
*** Capture evening journal entry
#+begin_src elisp
(def-capture "Daily Retrospective" "Journal"
(concat
;; The “:mood_𝓃:” tag is so that I can easily see my moods across my entries.
;; Keeping track of mood is a simple way to monitor success; e.g., whether GTD is working for me or not.
(format-time-string "* %Y-%m-%d %a %R :mood_𝒏%?:retro:daily:\n")
"
Instructions: Read section contents and replace them with your own words.
,** Monitoring Mood For Success
- Why do I feel the way I do?
- 1 ≈ 😢 extremely negative; 5 ≈ :neutral_face: neutral; 10 ≈ 😁 extremely positive.
,** Celebrating Successes
- Acknowledge and celebrate your achievements, no matter how small.
- Recognising your progress boosts morale and motivation, inspiring you to continue striving for success.
- /Give yourself credit for your efforts!/
,** Goal Alignment
- Were today's actions directed at achieving the sprint's goals? Stay focused!
- Review your day: use my/what-did-i-do-today to review the tasks you clocked into.
[[elisp:(let ((org-clock-clocktable-default-properties (-snoc org-clock-clocktable-default-properties :block 'today :timestamp 'nil))) (beginning-of-line) (kill-line) (org-clock-report))][What Did I Work on Today?]]
- Set SMART goals for tomorrow.
,** Stress Reduction
- Any challenges or frustrations encountered today?
,** Continuous Improvement
- What went well, what didn't go as planned, and were there any unexpected challenges today?
- Learn from your experiences & brainstorm strategies better outcomes in the future.
- Consider what factors contributed to these challenges and how you responded to them.
- What thought patterns were influencing my outcomes?
,** Express Gratitude
- Conclude your retrospective by expressing gratitude for the positive aspects of your day.
- Reflect on the people, opportunities, and experiences that brought you joy or fulfilment.
"))
#+end_src
** my/see-sorted-todos
#+begin_src elisp
(defun my/see-sorted-todos ()
"See TODOs sorted by state, priority, then effort.
This view shows me all tasks, sorted, and from there I can pick & schedule & edit as desired.
Much nicer than me physically sorting tasks!
The main benefit here is I can keep /active/ tasks under their
own disjoint ‘projects’, yet still have a nice unified view of
all of my /active/ *and* non-active tasks.
⇒ You can mark DONE and archive from the sorted view.
⇒ But leave that to the Weekly Review, so that you can extract any
reference information or Lessons Learned out of the tasks to be archived.
See: https://emacs.stackexchange.com/questions/9585/org-how-to-sort-headings-by-todo-and-then-by-priority
"
(interactive)
(let ((org-agenda-custom-commands '(("𝓌" nil todo "*"
((org-agenda-overriding-header "\nTODOs sorted by state, priority, effort")
(org-agenda-sorting-strategy '(todo-state-down priority-down effort-up)))))))
(org-agenda nil "𝓌" t)
(beginning-of-buffer)))
#+end_src
** Keep agenda in view, so I don't get distracted from the day's goals
[[https://orgmode.org/worg/org-hacks.html#orgdabf067:~:text=This%20keeps%20my%20tasks%20%22always%20in%20mind%22%20whenever%20I%20come%20back%20to%20Emacs%20after%20doing%20something%20else][Source]]
#+begin_src emacs-lisp
(defun jump-to-org-agenda ()
(interactive)
(let ((buf (get-buffer "*Org Agenda*"))
wind)
(if buf
(if (setq wind (get-buffer-window buf))
(select-window wind)
(if (called-interactively-p)
(progn
(select-window (display-buffer buf t t))
(org-fit-window-to-buffer)
;; (org-agenda-redo)
)
(with-selected-window (display-buffer buf)
(org-fit-window-to-buffer)
;; (org-agenda-redo)
)))
(call-interactively 'org-agenda-list)))
;;(let ((buf (get-buffer "*Calendar*")))
;; (unless (get-buffer-window buf)
;; (org-agenda-goto-calendar)))
)
(run-with-idle-timer 300 t 'jump-to-org-agenda)
#+end_src
* Lisp Programming
:PROPERTIES:
:CUSTOM_ID: Lisp-Programming
:END:
** highlight quoted symbols
:PROPERTIES:
:CUSTOM_ID: highlight-quoted-symbols
:END:
#+begin_src emacs-lisp
(use-package highlight-quoted
:defer nil
:config (add-hook 'emacs-lisp-mode-hook 'highlight-quoted-mode))
;; If everything worked fine, then “ 'b ” below should be coloured nicely in Emacs Lisp mode.
(when nil
(-let [x 'somevar]
(list x 'b "c" :e)))
#+end_src
** Get CheatSheets and view them easily :Disabled:
:PROPERTIES:
:CUSTOM_ID: Get-CheatSheets-and-view-them-easily
:header-args: :tangle no
:END:
#+begin_src emacs-lisp
(defvar my/cheatsheet/cached-topics nil)
(cl-defun my/cheatsheet (&optional topic)
"Clone Al-hassy's ⟨TOPIC⟩CheatSheet repository when called from Lisp; visit the pretty HTML page when called interactively.
- Example usage: (my/cheatsheet \"Vue\")
- Example usage: M-x my/cheatsheet RET Vue RET."
(interactive)
(if (not topic)
(browse-url (format "https://alhassy.github.io/%sCheatSheet" (completing-read "Topic: " my/cheatsheet/cached-topics)))
(push topic my/cheatsheet/cached-topics)
(maybe-clone (format "https://github.com/alhassy/%sCheatSheet" topic))))
#+end_src
Let's actually get some repos locally, and use: ~M-x my/cheatsheet~ to view the pretty HTML (or PDF) sheets.
#+begin_src emacs-lisp
(mapcar #'my/cheatsheet '("ELisp" "GojuRyu" "Rust")) ; Python Prolog Vue Agda JavaScript
; Clojure Ruby Oz Coq Cats Haskell FSharp OCaml
#+end_src
* Prose
:PROPERTIES:
:CUSTOM_ID: Prose
:END:
Emacs can be setup with a spellchecker and other expected features of a word processing tool
---however these features apply Emacs-wide since nearly everything is
essentially text (•̀ᴗ•́)و
- Org-mode is a writer's best friend; it's large enough to deserve its own sections.
- See [[https://lucidmanager.org/tags/emacs/][Emacs Writing Studio]] for a series of articles on making/using Emacs for writing.
** Bidirectional Text
#+begin_src emacs-lisp
;; Sometimes I have Arabic in my buffers, however I am an English speaker
;; and so Left-to-Right is most natural to me. As such, even when Arabic
;; is present, or any bidirectional text, just use Left-to-Right.
(setq-default bidi-paragraph-direction 'left-to-right)
#+end_src
** Whitespace
:PROPERTIES:
:CUSTOM_ID: Whitespace
:END:
Let's start off by cleaning-up any accidental trailing whitespace and in other
places upon save.
#+begin_src emacs-lisp
(add-hook 'before-save-hook 'whitespace-cleanup)
#+end_src
See [[http://ergoemacs.org/emacs/whitespace-mode.html][here]] for making whitespace visible; including spaces, tabs, and newlines
** Formatting Text
:PROPERTIES:
:CUSTOM_ID: Formatting-Text
:END:
The following incantation, doc:my/org-mode-format, makes it so that we can
select some text then press kbd:C-c_f (to get a list of possible character
completions) then press the symbol we want our text to be surrounded with.
#+begin_details
#+begin_src emacs-lisp
(local-set-key (kbd "C-c f") #'my/org-mode-format)
(defun my/org-mode-format (&optional text)
"Surround selected region with the given Org emphasises marker.
E.g., if this command is bound to “C-c f” then the sequence
“C-c f b” would make the currenly selected text be bold.
Likewise, “C-c f *” would achieve the same goal.
When you press “C-c f”, a message is shown with a list of
useful single-character completions.
Note: “C-c f 𝓍”, for an unrecognised marker 𝓍, just inserts
the character 𝓍 before and after the selected text."
(interactive "P") ;; Works on a region
; (message "b,* ⟨Bold⟩; i,/ ⟨Italics⟩; u,_ ⟨Underline⟩; c,~ ⟨Monotype⟩")
(message "⟨Bold b,*⟩ ⟨Italics i,/⟩ ⟨Underline u,_⟩ ⟨Monotype c,~⟩")
(let ((kind (read-char)))
;; Map letters to Org formatting symbols
(setq kind (or (plist-get '(b ?\* i ?\/ u ?\_ c ?\~)
(intern (string kind)))
kind))
(insert-pair text kind kind)))
#+end_src
#+end_details
** Fill-mode ---Word Wrapping
:PROPERTIES:
:CUSTOM_ID: Fill-mode-Word-Wrapping
:END:
In fill mode, when you type past the end of a line, Emacs automatically starts a new line, cleverly formatting
paragraphs. This is a powerful form of “word wrap”.
#+BEGIN_SRC emacs-lisp
(setq-default fill-column 80 ;; Let's avoid going over 80 columns
truncate-lines nil ;; I never want to scroll horizontally
indent-tabs-mode nil) ;; Use spaces instead of tabs
#+END_SRC
Certain variables are sensibly local to a buffer, and so ~setq~ only alters their value for one buffer. Using ~setq-default~
we change a variable's default value, in every buffer.
#+BEGIN_SRC emacs-lisp
;; Wrap long lines when editing text
(add-hook 'text-mode-hook 'turn-on-auto-fill)
(add-hook 'org-mode-hook 'turn-on-auto-fill)
#+END_SRC
We may press ~M-q~ to cleverly redistribute the line breaks within any paragraph, thereby making it look better. With a
prefix argument, it justifies it as well ---i.e., pads extra white space to make the paragraph appear rectangular.
Note that ~M-o M-s~ centres a line of text ;-) Fun stuff!
Fill-mode is also known as “hard word wrapping”, which has the counterpart “soft word wrapping” …
Visual line mode is built-in and provides support for editing by visual lines: Lines off the screen are visually word
wrapped, but logically remain one line. Moreover =C-a,e,k= operate on visual lines rather than logical lines.
#+begin_src emacs-lisp
;; Bent arrows at the end and start of long lines.
(setq visual-line-fringe-indicators '(left-curly-arrow right-curly-arrow))
(global-visual-line-mode 1)
#+end_src
Visual line mode is useful when I have way too many windows open or when using smaller frames.
** Pretty Lists Markers
:PROPERTIES:
:CUSTOM_ID: Pretty-Lists-Markers
:END:
When writing, it's common to use ~+,-,*~ to enumerate unordered lists
---especially so in Org-mode wherein they denote structured text. Let's render
them visually as Unicode bullets.
#+begin_src emacs-lisp
;; (x y z) ≈ (existing-item replacement-item positivity-of-preceding-spaces)
(cl-loop for (x y z) in '(("+" "◦" *)
("-" "•" *)
("*" "⋆" +))
do (font-lock-add-keywords 'org-mode
`((,(format "^ %s\\([%s]\\) " z x)
(0 (prog1 () (compose-region (match-beginning 1) (match-end 1) ,y)))))))
#+end_src
** Fix spelling as you type ---thesaurus & dictionary too!
:PROPERTIES:
:CUSTOM_ID: Fix-spelling-as-you-type-thesaurus-dictionary-too
:END:
I would like to check spelling on the fly.
+ ~C-;~ :: Cycle through corrections for word at point.
+ ~M-$~ :: Check and correct spelling of the word at point
+ ~M-x ispell-change-dictionary RET TAB~ :: To see what dictionaries are available.
Install spell-checking application as well as a reliable English
dictionary, [[https://wordnet.princeton.edu/][WordNet]].
#+begin_src emacs-lisp
(system-packages-ensure "aspell")
(system-packages-ensure "wordnet")
#+end_src
~flyspell-prog-mode~ enables spell checking for programming by only considering
comments and strings.
#+BEGIN_SRC emacs-lisp
(use-package flyspell
:hook ((prog-mode . flyspell-prog-mode)
((org-mode text-mode) . flyspell-mode)))
#+END_SRC
Enabling fly-spell for text-mode enables it for org and latex modes since they
derive from text-mode.
Flyspell needs a spell checking tool, which is not included in Emacs. We
install ~aspell~ spell checker using, say, homebrew via ~brew install aspell~. Note
that Emacs' ~ispell~ is the interface to such a command line spelling utility.
# See available dictionary via ~aspell dicts~.
#+BEGIN_SRC emacs-lisp
(setq ispell-program-name (s-trim (shell-command-to-string "which aspell")))
(setq ispell-dictionary "en_GB") ;; set the default dictionary
#+END_SRC
[Disabled] Allow spelling support for CamlCase words like “EmacsIsCool”.
#+BEGIN_SRC emacs-lisp :tangle no
(setq ispell-extra-args '("--sug-mode=ultra"
"--run-together"
"--run-together-limit=5"
"--run-together-min=2"))
#+END_SRC
Let us select a correct spelling merely by clicking on a word
---for the rare days I have a mouse.
#+begin_src emacs-lisp
(eval-after-load "flyspell"
' (progn
(define-key flyspell-mouse-map [down-mouse-3] #'flyspell-correct-word)
(define-key flyspell-mouse-map [mouse-3] #'undefined)))
#+end_src
Colour incorrect works; default is an underline.
#+BEGIN_SRC emacs-lisp
(global-font-lock-mode t)
(custom-set-faces '(flyspell-incorrect ((t (:inverse-video t)))))
#+END_SRC
Finally, save to user dictionary without asking:
#+BEGIN_SRC emacs-lisp
(setq ispell-silently-savep t)
#+END_SRC
Let's keep track of my personal word set by having it be in my version controlled
.emacs directory. [[http://aspell.net/man-html/Format-of-the-Personal-and-Replacement-Dictionaries.html][Note]] that the default location is ~~/.[i|a]spell.DICT~ for
a specified dictionary ~DICT~.
#+BEGIN_SRC emacs-lisp
(setq ispell-personal-dictionary "~/.emacs.d/.aspell.en.pws")
#+END_SRC
Nowadays, I very rarely write non-literate programs, but if I do
I'd like to check spelling only in comments/strings. E.g.,
#+BEGIN_SRC emacs-lisp
(add-hook 'c-mode-hook 'flyspell-prog-mode)
(add-hook 'emacs-lisp-mode-hook 'flyspell-prog-mode)
#+END_SRC
Use the thesaurus Emacs frontend [[https://github.com/hpdeifel/synosaurus][Synosaurus]] to avoid unwarranted repetition.
#+begin_src emacs-lisp
(use-package synosaurus
:defer 100
:init (synosaurus-mode)
:config (setq synosaurus-choose-method 'popup) ;; 'ido is default.
(global-set-key (kbd "M-#") 'synosaurus-choose-and-replace))
#+end_src
The thesaurus is powered by the Wordnet ~wn~ tool, which can be invoked without an
internet connection!
#+begin_src emacs-lisp
;; (shell-command "brew cask install xquartz &") ;; Dependency
;; (shell-command "brew install wordnet &")
#+end_src
Let's use Wordnet as a dictionary via the [[https://github.com/gromnitsky/wordnut][wordnut]] package.
#+BEGIN_SRC emacs-lisp
(use-package wordnut
:defer 100
:bind ("M-!" . wordnut-lookup-current-word))
;; Use M-& for async shell commands.
#+END_SRC
Use ~M-↑,↓~ to navigate dictionary results, and ~wordnut-search~ for a new search.
An alternative to =wordnut= is to use the lightweight ~define-word~ package; which I
think is not ideal since it provides way less information.
:PowerthesaurusCurrentlyNotWorking:
#+BEGIN_SRC emacs-lisp :tangle no
(load "~/dotfiles/.emacs.d/powerthesaurus.el")
(global-set-key (kbd "M-#") 'powerthesaurus-lookup-word-at-point)
;; Website currently down ... https://github.com/SavchenkoValeriy/emacs-powerthesaurus/issues/6
#+END_SRC
:End:
** Touch Typing :Disabled:
:PROPERTIES:
:CUSTOM_ID: Touch-Typing
:header-args: :tangle no
:END:
Use this game to help you learn to spell words that you're having trouble with;
e.g., I have a file ~~/Dropbox/spelling.txt~ with words I have trouble spelling,
which I open then run ~M-x typing-of-emacs~ in order to improve spelling said
words.
#+BEGIN_SRC emacs-lisp :tangle no
;; The Typing Of Emacs, a game.
(use-package typing-of-emacs
:quelpa (typing :fetcher wiki :url "https://www.emacswiki.org/emacs/typing.el"))
#+END_SRC
Practice touch typing using [[https://github.com/hagleitn/speed-type][speed-type]].
#+begin_src emacs-lisp
(use-package speed-type )
#+end_src
Running ~M-x speed-type-region~ on a region of text, or ~M-x speed-type-buffer~ on a
whole buffer, or just ~M-x speed-type-text~ will produce the selected region, buffer,
or random text for practice. The timer begins when the first key is pressed
and stats are shown when the last letter is entered.
Other typing resources include:
+ [[https://www.emacswiki.org/emacs/TypingOfEmacs][Typing of Emacs]] ---an Emacs alternative to speed type, possibly more engaging.
+ [[https://alternativeto.net/software/klavaro/][Klavaro]] ---a GUI based yet language-independent typing tutor.
- I'm enjoying this tool in getting started with Arabic typing.
+ [[https://typing.io/][Typing.io]] is a tutor for coders: Lessons are based on open source code, such
some XMonad written in Haskell or Linux written in C.
+ [[https://www.gnu.org/software/gtypist/index.html#downloading][GNU Typist]] ---which is interactive in the terminal, so not ideal in Emacs--,
To assist in language learning, it may be nice to have an Emacs
[[https://github.com/atykhonov/google-translate][interface]] to Google translate ---e.g., invoke ~google-translate-at-point~.
#+BEGIN_SRC emacs-lisp
(use-package google-translate
:config
(global-set-key "\C-ct" 'google-translate-at-point))
#+END_SRC
Select the following then ~C-c t~,
#+begin_quote
Hey buddy, what're you up to?
#+end_quote
Then /detect language/ then /Arabic/ to obtain:
#+begin_quote
مرحباً يا صديقي ، ماذا تفعل؟
#+end_quote
Neato 😲
** Using a Grammar & Style Checker :Disabled:
:PROPERTIES:
:CUSTOM_ID: Using-a-Grammar-Style-Checker
:header-args: :tangle no
:END:
[ A possibly better alternative is [[https://emacstil.com/til/2022/03/05/setting-up-vale-prose-linter-on-emacs/][Vale]]. ]
Let's install [[https://github.com/mhayashi1120/Emacs-langtool][a grammar and style checker]].
We get the offline tool from the bottom of the [[https://languagetool.org/][LanguageTool]] website, then relocate it
as follows.
#+BEGIN_SRC emacs-lisp
(use-package langtool
:custom
(langtool-language-tool-jar
"~/Applications/LanguageTool-4.5/languagetool-commandline.jar"))
#+END_SRC
Now we can run ~langtool-check~ on the subsequent grammatically incorrect
text ---which is from the LanguageTool website--- which colours errors in red,
when we click on them we get the reason why; then we may invoke
~langtool-correct-buffer~ to quickly use the suggestions to fix each correction,
and finally invoke ~langtool-check-done~ to stop any remaining red colouring.
#+begin_example org
LanguageTool offers spell and grammar checking. Just paste your text here
and click the 'Check Text' button. Click the colored phrases for details
on potential errors. or use this text too see an few of of the problems
that LanguageTool can detecd. What do you thinks of grammar checkers?
Please not that they are not perfect. Style issues get a blue marker:
It's 5 P.M. in the afternoon. The weather was nice on Thursday, 27 June 2017
--uh oh, that's the wrong date ;-)
#+end_example
By looking around the source code, I can do all three stages smoothly (•̀ᴗ•́)و
#+BEGIN_SRC emacs-lisp
;; Quickly check, correct, then clean up /region/ with M-^
(eval-after-load 'langtool
(progn
(add-hook 'langtool-error-exists-hook
(lambda ()
(langtool-correct-buffer)
(langtool-check-done)))
(global-set-key "\M-^"
(lambda ()
(interactive)
(message "Grammar checking begun ...")
(langtool-check)))))
#+END_SRC
The checking command is silent, we added a bit of comforting acknowledgement to the user.
** Lightweight Prose Proofchecking
:PROPERTIES:
:CUSTOM_ID: Lightweight-Prose-Proofchecking
:END:
Let's [[https://github.com/bnbeckwith/writegood-mode][write good]]!
#+BEGIN_SRC emacs-lisp
(use-package writegood-mode
;; Load this whenver I'm composing prose.
:hook (text-mode org-mode)
;; Don't show me the “Wg” marker in the mode line
:defer 100
;; Some additional weasel words.
:config
(--map (push it writegood-weasel-words)
'("some" "simple" "simply" "easy" "often" "easily" "probably"
"clearly" ;; Is the premise undeniably true?
"experience shows" ;; Whose? What kind? How does it do so?
"may have" ;; It may also have not!
"it turns out that"))) ;; How does it turn out so?
;; ↯ What is the evidence of highighted phrase? ↯
#+END_SRC
Inspired by Matt Might's [[http://matt.might.net/articles/shell-scripts-for-passive-voice-weasel-words-duplicates/][3 shell scripts to improve your writing, or
"My Ph.D. advisor rewrote himself in bash"]], this Emacs interface
emphasises, via underline, the following weaknesses in writing ---so
that I can fix them or decide that they are appropriate for the
scenario.
Sentences that cut out the following problems may become stronger
---by being more terse or precise.
+ Weasel Words ::
Phrases that sound good without conveying information;
such as vague precision or subjective phrases.
E.g., /a number of, surprisingly, very close/.
It's okay not to have exact details, but rather than “I don't know”
explain why not and what the next steps will be.
+ Passive Voice ::
Phrases wherein interest is in the object experiencing an action,
rather than the subject that performs the action.
- Bad: The house /was built by/ my father.
- Good: My father /built/ this house.
Likewise, including relevant or explanatory information as in “X
guarantees Y” is an improvement over “Y is guaranteed”.
Sometimes the subject really is irrelevant, such as
“We did X” whereas “X happened” suffices.
👍 If the relevant subject is unclear and, also, the text reads
better in the active, then change a phrase.
+ Duplicated Words :: Occurrences of, say, “the the”.
Harder to catch manually, but easier mechanically ;-)
** Placeholder Text ---For Learning & Experimenting
:PROPERTIES:
:CUSTOM_ID: Placeholder-Text-For-Learning-Experimenting
:END:
When learning about Emacs formatting commands, such as zap-to-char ~M-z~
or transpose ~M-t~, it's best to have filler text ---even better when
it's automatically generated instead of typing it out ourselves. The
following will give us a series of commands ~lorem-ipsum-insert-⋯~ for
inserting lists, sentences, paragraphs and using a prefix argument,
with ~C-u~, we can request to generate any number of them.
#+BEGIN_SRC emacs-lisp
(use-package lorem-ipsum )
#+END_SRC
‘Lorem’ is not a word itself, but it comes from the Latin ‘Dolorem Ipsum’
which means “pain in and of itself”.
See this [[https://github.com/alhassy/emacs.d/blob/master/CheatSheet.pdf][Emacs Cheat Sheet]] to try out the textual navigation and formatting
bindings on lorem ipsum, gibberish text.
** Some text to make us smile
:PROPERTIES:
:CUSTOM_ID: Some-text-to-make-us-smile
:END:
The [[https://github.com/davep/dad-joke.el][dad-joke]] queries [[https://icanhazdadjoke.com][https://icanhazdadjoke.com]] to bring us some funny.
#+begin_src emacs-lisp
(use-package dad-joke
:config (defun dad-joke () (interactive) (insert (dad-joke-get))))
#+end_src
For example, ~M-x dad-joke~ now inserts:
#+begin_quote org
What are the strongest days of the week? Saturday and Sunday...the rest are
weekdays.
#+end_quote
** Unicode Input via Agda Input
:PROPERTIES:
:CUSTOM_ID: Unicode-Input-via-Agda-Input
:END:
:agda2-include-dirs-Issue:
#+BEGIN_SRC emacs-lisp
;; (load (shell-command-to-string "agda-mode locate"))
;;
;; Seeing: One way to avoid seeing this warning is to make sure that agda2-include-dirs is not bound.
; (makunbound 'agda2-include-dirs)
#+END_SRC
:End:
[[https://mazzo.li/posts/AgdaSort.html][Agda]] is one of my favourite languages, it's like Haskell on steroids. Let's set
it up for the main sake of its Unicode input ---you may do likewise using TeX
input. ( [[https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-every-software-developer-absolutely-positively-must-know-about-unicode-and-character-sets-no-excuses/][The Absolute Minimum Every Software Developer Absolutely, Positively
Must Know About Unicode and Character Sets (No Excuses!)]] )
/Agda input mode makes it extremely easy to use unicode in documents, something I/
/strongly prefer to do. When I can use symbols directly, instead of (for/
/instance) LaTeX commands, it makes my plaintext far more readable./ --- [[https://github.com/armkeh/dotfiles/tree/master/emacs][Armkeh
.emacs config]]
#+begin_src emacs-lisp
(system-packages-ensure "agda")
#+end_src
#+begin_details To use the Agda standard library by default
#+BEGIN_SRC shell :tangle no
mkdir -p ~/.agda
echo /usr/local/lib/agda/standard-library.agda-lib >>~/.agda/libraries
echo standard-library >>~/.agda/defaults
#+END_SRC
Invoke ~brew info agda~ to get these instructions and the version of Agda just
installed.
#+end_details
#+begin_details Get font support for subscripts, if need be
- Download and unzip the [[https://fontlibrary.org/en/font/symbola][symbola]] font
- kbd:CMD_+_SPC ⇒ =font book= ⇒ CMD+O ⇒ select the symbola directory you just
unzipped
(Note: In the before time, you could brew install this font.)
#+end_details
Executing ~agda-mode setup~ appends the following text to the ~.emacs~ file.
Let's put it here ourselves.
#+begin_src emacs-lisp
(unless noninteractive
(load-file (let ((coding-system-for-read 'utf-8))
(shell-command-to-string "agda-mode locate"))))
#+end_src
I almost always want the ~agda-mode~ input method ---it's like the TeX method, but
better.
#+BEGIN_SRC emacs-lisp
;; TODO: Maybe don't bother installing Agda, and just get agda-input.el
;; from: https://github.com/agda/agda/blob/master/src/data/emacs-mode/agda-input.el
;; then loading that!
(url-copy-file "https://raw.githubusercontent.com/agda/agda/master/src/data/emacs-mode/agda-input.el" "~/.emacs.d/elpa/agda-input.el" :ok-if-already-exists)
(load-file "~/.emacs.d/elpa/agda-input.el")
;; MA: This results in "Package cl is deprecated" !?
(unless noninteractive
(use-package agda-input
:ensure nil ;; I have it locally.
:demand t
:hook ((text-mode prog-mode) . (lambda () (set-input-method "Agda")))
:custom (default-input-method "Agda")))
;; Now C-\ or M-x toggle-input-method turn it on and offers
;; TODO add a hook that when the input method becomes Agda, just don't bother showing me in the modeline.
;; E.g., "Π" when using unicode input with Agda
;; Useful to have in the modeline, say when typing in Arabic.
;; (add-variable-watcher
;; 'current-input-method
;; (lambda (_ newvalue 'set _)
;; (setq current-input-method-title
;; (if (equal newvalue "Agda") nil newvalue))))
#+END_SRC
:agda_Command_line_arguments:
"+RTS -H4.5G -M4.5G -K256M -S/tmp/AgdaRTS.log -A1G -RTS -i ."
Wolfram Kahl has recommended the following settings.
#+begin_src emacs-lisp
;;(setq agda2-program-args (quote ("RTS" "-M4G" "-H4G" "-A128M" "-RTS")))
#+end_src
These arguments specify
| ~+RTS~, ~-RTS~ | Flags between these are arguments to the ~ghc~ runtime |
| ~-M[size]~ | Maximum heap size |
| ~-H[size]~ | Suggested heap size |
| ~-A[size]~ | Allocation area size used by the garbage collector |
Full documentation for the ~ghc~ runtime argumentscan be found [[https://downloads.haskell.org/~ghc/7.8.4/docs/html/users_guide/runtime-control.html][here]].
Additional arguments that may be useful include
| ~-S[file]~ | Produces information about “each and every garbage collection” |
| | - Outputs to ~stderr~ by default |
:end:
#+begin_quote
Unicode doesn't intend to cover things that are achievable with markup, so only
a limited subset of the alphabet is available as subscript; but all is available
as superscript, except ‘q’.
ₐₑₕᵢⱼₖₗₘₙₒₚᵣₛₜᵤᵥₓ
⁰ ¹ ² ³ ⁴ ⁵ ⁶ ⁷ ⁸ ⁹ ⁺ ⁻ ⁼ ⁽ ⁾ ₀ ₁ ₂ ₃ ₄ ₅ ₆ ₇ ₈ ₉ ₊ ₋ ₌ ₍ ₎
ᵃ ᵇ ᶜ ᵈ ᵉ ᶠ ᵍ ʰ ⁱ ʲ ᵏ ˡ ᵐ ⁿ ᵒ ᵖ ʳ ˢ ᵗ ᵘ ᵛ ʷ ˣ ʸ ᶻ
ᴬ ᴮ ᴰ ᴱ ᴳ ᴴ ᴵ ᴶ ᴷ ᴸ ᴹ ᴺ ᴼ ᴾ ᴿ ᵀ ᵁ ⱽ ᵂ
ᵅ ᵝ ᵞ ᵟ ᵋ ᶿ ᶥ ᶲ ᵠ ᵡ ᵦ ᵧ ᵨ ᵩ ᵪ
~brew cask install font-symbola~
⇒ Includes fonts for subscripts; e.g., ₐₙₑₕᵢⱼₖₗₘₙₒₚₜₛ
#+end_quote
Below are my personal Agda input symbol translations;
e.g., ~\set → 𝒮ℯ𝓉~. Note that we could give a symbol new Agda TeX binding
interactively: ~M-x customize-variable agda-input-user-translations~ then
~INS~ then for key sequence type ~set~ then ~INS~ and for string paste ~𝒮ℯ𝓉~.
#+BEGIN_SRC emacs-lisp
(unless noninteractive (add-to-list 'agda-input-user-translations '("set" "𝒮ℯ𝓉")))
#+END_SRC
Better yet, as a loop:
#+BEGIN_SRC emacs-lisp
(unless noninteractive
(cl-loop for item
in '(;; Arabic ornate parenthesis U+FD3E / U+FD3F
("(" "﴾")
(")" "﴿")
("cmd" "⌘")
;; categorial ;;
("alg" "𝒜𝓁ℊ")
("split" "▵")
("join" "▿")
("adj" "⊣")
(";;" "﹔")
(";;" "⨾")
(";;" "∘")
;; logic
("if" "⇐")
("onlyif" "⇒")
;; lattices ;;
("meet" "⊓")
("join" "⊔")
;; tortoise brackets, infix relations
("((" "〔")
("))" "〕")
;; residuals
("syq" "╳")
("over" "╱")
("under" "╲")
;; Z-quantification range notation ;;
;; e.g., “∀ x ❙ R • P” ;;
("|" "❙")
("with" "❙")
;; Z relational operators
("domainrestriction" "◁")
("domr" "◁")
("domainantirestriction" "⩤")
("doma" "⩤")
("rangerestriction" "▷")
("ranr" "▷")
("rangeantirestriction" "⩥")
("rana" "⩥")
;; adjunction isomorphism pair ;;
("floor" "⌊⌋")
("lower" "⌊⌋")
("lad" "⌊⌋")
("ceil" "⌈⌉")
("raise" "⌈⌉")
("rad" "⌈⌉")
;; Replies
("yes" "✔")
("no" "❌")
;; Arrows
("<=" "⇐")
;; more (key value) pairs here
)
do (add-to-list 'agda-input-user-translations item)))
#+END_SRC
Also some silly stuff:
#+begin_src emacs-lisp
(unless noninteractive
;; Add to the list of translations using “emot” and the given, more specfic, name.
;; Whence, \emot shows all possible emotions.
(cl-loop for emot
in `(;; angry, cry, why-you-no
("whyme" "ლ(ಠ益ಠ)ლ" "ヽ༼ಢ_ಢ༽ﾉ☂" "щ(゜ロ゜щ)" "‿︵(ಥ﹏ಥ)‿︵" "ಠ_ಠ" "(╬ ಠ益ಠ)" "･ﾟ(*❦ω❦)*･ﾟ" "(╯°□°）╯︵ ┻━┻") ;; flip the table
;; confused, disapprove, dead, shrug, awkward
("what" "「(°ヘ°)" "(ಠ_ಠ)" "(✖╭╮✖)" "¯\\_(ツ)_/¯" "(´°ω°`)" "･✧_✧･")
;; dance, csi
("cool" "┏(-_-)┓┏(-_-)┛┗(-_- )┓"
,(s-collapse-whitespace "•_•)
( •_•)>⌐■-■
(⌐■_■)"))
;; love, pleased, success, yesss, smile, excited, yay
("smile" "♥‿♥" "(─‿‿─)" "(•̀ᴗ•́)و" "ᕦ( ᴼ ڡ ᴼ )ᕤ" "(งಠ_ಠ)ง" "(｡◕‿◕｡)" "(◕‿◕)" "( ˃ ヮ˂)" "[ ⇀ ‿ ↼ ]" "٩(⁎❛ᴗ❛⁎)۶" "ᴵ’ᵐ ᵇᵉᵃᵘᵗⁱᶠᵘˡ" "(✿◠‿◠)")
;; flower high-5
("hug" "♡(✿ˇ◡ˇ)人(ˇ◡ˇ✿)♡" "(づ｡◕‿◕｡)づ" "(づ｡◕‿‿‿‿◕｡)づ"))
do
(add-to-list 'agda-input-user-translations emot)
(add-to-list 'agda-input-user-translations (cons "emot" (cdr emot)))))
#+end_src
# If you change this setting manually, without using the
# customization buffer, you need to call (agda-input-setup) in
# order for the change to take effect.
Finally let's effect such translations.
#+begin_src emacs-lisp
;; activate translations
(unless noninteractive (agda-input-setup))
#+end_src
Note that the effect of [[http://ergoemacs.org/emacs/emacs_n_unicode.html][Emacs unicode input]] could be approximated using
~abbrev-mode~.
:May_need_to_install_stix_font:
;; install STIX font from Ubuntu store!!
;; (set-fontset-font t 'unicode (font-spec :name "STIX") nil 'append)
:End:
** Increase/decrease text size
:PROPERTIES:
:CUSTOM_ID: Increase-decrease-text-size
:END:
The ‘usual’ text zoom keys ~C-±~ …
#+BEGIN_SRC emacs-lisp
(global-set-key (kbd "C-+") 'text-scale-increase)
(global-set-key (kbd "C--") 'text-scale-decrease)
;; C-x C-0 restores the default font size
#+END_SRC
If thou knowst the ELisp, forgive this shadowing of the ~negative-argument~
… we've still got ~M--~ though.
Curious, this is one of the very first things I did when
began using Emacs; yet, perhaps I would not have done
it if I was simply told the defaults:
+ ~C-x C-=,+~ increases text size
+ ~C-x C--~ decreases test size
+ ~C-x C-0~ restores it to the default size
So, the above snippet seems to save us of the prefix
~C-x~ and we lose on using ‘=’ for text increase and worse we
need the shift-key to get access to the ‘+’.
I suppose this is just a habit inherited from using other tools. Fortunately, I
did not inherit the need for the /common user access/ bindings ~C-x~ kill, ~C-c~ copy,
~C-v~ paste, nor ~C-z~ undo of other applications. If you're interested, ~M-x
cua-mode~ to enable [[https://www.gnu.org/software/emacs/manual/html_node/emacs/CUA-Bindings.html][CUA Bindings]].
** Moving Text Around
:PROPERTIES:
:CUSTOM_ID: Moving-Text-Around
:END:
This extends Org-mode's ~M-↑,↓~ to other modes, such as when coding.
#+BEGIN_SRC emacs-lisp
;; M-↑,↓ moves line, or marked region; prefix is how many lines.
(use-package move-text
:config (move-text-default-bindings))
#+END_SRC
** Enabling CamelCase Aware Editing Operations
:PROPERTIES:
:CUSTOM_ID: Enabling-CamelCase-Aware-Editing-Operations
:END:
[[https://www.gnu.org/software/emacs/manual/html_node/ccmode/Subword-Movement.html][Subword]] movement lets us treat “EmacsIsAwesome” as three words
─“Emacs”, “Is”, and “Awesome”─ which is desirable since such naming
is common among coders. Now, for example, ~M-f~ moves along each subword.
#+begin_src emacs-lisp
(global-subword-mode 1)
#+end_src
** Mouse Editing Support :Disabled:
:PROPERTIES:
:CUSTOM_ID: Mouse-Editing-Support
:header-args: :tangle no
:END:
# :Strange:This_Seems_To_Require_Deprecated_CL:Message_show_at_startup:
Text selected with the mouse is automatically copied to clipboard.
#+begin_src emacs-lisp
(setq mouse-drag-copy-region t)
#+end_src
** Delete Selection Mode
:PROPERTIES:
:CUSTOM_ID: Delete-Selection-Mode
:END:
Delete Selection mode lets you treat an Emacs region much like a typical text
selection outside of Emacs: You can replace the active region. We can delete
selected text just by hitting the backspace key.
#+BEGIN_SRC emacs-lisp
(delete-selection-mode 1)
#+END_SRC
** ~M-n,p~: Word-at-Point Navigation ╱╲ Automatic highlighting current symbol/word :Disabled:
:PROPERTIES:
:CUSTOM_ID: M-n-p-Word-at-Point-Navigation
:header-args: :tangle no
:END:
Let's mimic the ~C-n,p~ constructs from line to word, so that unoccupied ~M-n,p~ now
serve to take us to the next or previous instance of the word under the
cursor. This is less intrusive than searching ~C-s~ or listing all occurrences ~M-s
o~. Moreover, let's automaticly highlight current symbols, words under the cursour, and cycle
quickly between highlkighted locations with
doc:ahs-forward / [[kbd:M-→]] and
doc:ahs-backward / [[kbd:M-←]].
#+BEGIN_SRC emacs-lisp
;; Default: M-→/← moves to the next/previous instance of the currently highlighted word
;; These are already meaningful commands in Org-mode, so we avoid these key re-bindings in Org-mode; TODO.
(use-package auto-highlight-symbol)
;; :hook ((text-mode . auto-highlight-symbol-mode)
;; (prog-mode . auto-highlight-symbol-mode)))
;;
;; This breaks Org Exports; e.g.,
;; C-c C-e h o ⇒ Match data clobbered by buffer modification hooks
#+END_SRC
Let's also quickly replace the word at point:
#+BEGIN_SRC emacs-lisp
(defun my/symbol-replace (replacement)
"Replace all standalone symbols in the buffer matching the one at point."
(interactive (list (read-from-minibuffer "Replacement for thing at point: " nil)))
(save-excursion
(let ((symbol (or (thing-at-point 'symbol) (error "No symbol at point!"))))
(beginning-of-buffer)
;; (query-replace-regexp symbol replacement)
(replace-regexp (format "\\b%s\\b" (regexp-quote symbol)) replacement))))
#+END_SRC
(Unfortunately, as it currently is, there is no universal argument support: ~C-u
2 M-p~ does /not/ take you to the second previous instance of a word ---the prefix
is instead ignored. We can quickly form a work-around with doc:defhydra ---which
gives us temoporary modal modes.)
Finally, let's use [[kbd:M-n ╱ M-p ╱ M-']] to move to the next, previous, and
replace the word at point /but also/ to give us a meanu to repeat any of these
actions.
#+BEGIN_SRC emacs-lisp
(defmacro my/make-navigation-hydra (initial-action)
`(defhydra word-navigation
(:body-pre (,initial-action)) "Word-at-point Navigation"
("n" ahs-forward "Next instance")
("p" smartscan-symbol-go-backward "Previous instance")
("r" my/symbol-replace "Replace all occurances")
("s" ahs-display-stat "Stats")))
;; (bind-key* str func) ≈ (global-set-key (kbd str) func)
(bind-key* "M-n" (my/make-navigation-hydra ahs-forward))
(bind-key* "M-p" (my/make-navigation-hydra ahs-backward))
(bind-key* "M-'" (my/make-navigation-hydra my/symbol-replace))
#+END_SRC
An alternative is the [[https://github.com/mickeynp/smart-scan][smart-scan]] library ---which does the same thing, but does
not provide the highlighting occurances at point.
# The default symbol replacement is [[https://github.com/mickeynp/smart-scan/issues/23][over-zealous]] in that it replaces sub-terms
# occurring as parts of larger words. Let's do something about that.
** Letter-based Navigation :Disabled:
:PROPERTIES:
:CUSTOM_ID: Letter-based-Navigation
:header-args: :tangle no
:END:
At a glance of possible positions, across windows,
and a key to jump there is a feature provided to us by [[https://github.com/winterTTr/ace-jump-mode/wiki/AceJump-FAQ][ace-jump]]
---here is an [[https://www.youtube.com/watch?feature=player_embedded&v=UZkpmegySnc#!][emacs-rocks 2-minute video]].
For example, =C-c SPC m= greys our all windows and places a red
letter at the start of any word that begins with /m/, then I may
press a letter to jump to the associated position in the
associated window. Using ~C-u C-c SPC~ and ~C-u C-u C-c SPC~ let
me jump to any character or to any visible line.
➩ Super simple use case: Fix your eyes on an occurence of a word, then ~C-c SPC~
to quickly jump to it so as to edit the sentence in which it occurs.
- It's like ~C-s~ but more lightweight.
#+begin_src emacs-lisp
(use-package ace-jump-mode
:config (bind-key* "C-c SPC" 'ace-jump-mode))
;; See ace-jump issues to configure for use of home row keys.
#+end_src
There is a newer and somewhat more powerful package, [[https://github.com/abo-abo/avy][avy]], which accompishes the
same goal. It uses a tree style to jumipng: Locations are given two letter
combinations, one presses one letter to jump to a group of text, then another
letter to jump somewhere in that grouping. I prefer ace-jump since it greys
everthing out, whereas avy surrounds jump locations with a box.
Here is an [[https://www.youtube.com/watch?v=zar4GsOBU0g][emacs-doom 6-minute video]] for avy.
There is also [[https://github.com/tam17aki/ace-isearch][ace-isearch]] for bridinging different navgiational methods ---one
begins incremental search, ~s-f~, then according to a pause and length of input,
one of the navgiational methods, such as isearch or avy or helm-swoop, will be
begun. I'm okay with using ~C-s~ for helm-swoop and ~C-c SPC~ for ace-jump, and
still have ~s-f~ for incremental search, which I hardly use.
*What is bind-keys**?
Major modes provide specfic use and so their bindings always take precedence
over global bindings ---e.g., the major mode binding may do what the global does
but with extra mode-specfic behaviour, such as indentation. Other times, a major
mode's binding simply uses the same key presses with completely unrelated
behaviour. If we want to avoid having our global keybindings shadowed by a
major mode, we may use the ~bind-key*~ /macro/ of ~use-package~, or the ~bind-keys*~
/macro/ when there are multiple keys; these are macros, not clauses. ---These
essentially creates a dedicated minor mode behind the scenes, which saves us the
work of [[https://emacs.stackexchange.com/a/358/10352][doing it ourselves]].
| | ~(bind-keys* (k₁ . f₁) … (kₙ . fₙ))~ |
| ≈ | These keybindings override all minor modes that use keys =kᵢ=. |
Of course we can also use it without the asterisk; e.g.:
#+begin_src emacs-lisp
;; C-x o ⇒ Switch to the other window
;; C-x O ⇒ Switch back to the previous window
(bind-key "C-x O" (lambda () (interactive) (other-window -1)))
#+end_src
** =C-c e n,p=: Taking a tour of one's edits :Disabled:
:PROPERTIES:
:CUSTOM_ID: C-c-e-n-p-Taking-a-tour-of-one's-edits
:header-args: :tangle no
:END:
This package allows us to move around the edit points of a buffer /without/
actually undoing anything. We even obtain a brief description of what happend at
each edit point. This seems useful for when I get interrupted or lose my train
of thought: Just press [[kbd:C-c e p]] to see what I did recently and where ---the
“e” is for “e”dit.
#+BEGIN_SRC emacs-lisp
;; Give me a description of the change made at a particular stop.
(use-package goto-chg
:custom (glc-default-span 0))
(my/defhydra "C-c e" "Look at them edits!" bus
:\ ("p" goto-last-change "Goto nᵗʰ last change")
("n" goto-last-change-reverse "Goto more recent change"))
#+END_SRC
Compare this with ~C-x u~, or ~undo-tree-visualise~, wherein undos are actually performed.
Notice, as a hydra, I can use ~C-c e~ followed by any combination of ~p~ and ~n~ to
navigate my recent edits /without/ having to supply the prefix each time.
** visual-regexp
:PROPERTIES:
:CUSTOM_ID: visual-regexp
:END:
#+begin_src emacs-lisp
;; While constructing the regexp in the minibuffer, get live visual feedback for the (group) matches.
;; E.g., try: M-% use-\(.+?\) \(.+\)\b ENTER woah \1 and \2
;;
;; C-u M-% do to regexp replace, without querying.
(use-package visual-regexp
:config (define-key global-map (kbd "M-%")
(lambda (&optional prefix) (interactive "P") (call-interactively (if prefix #'vr/replace #'vr/query-replace)))))
#+end_src
** LaTeX ⇐ Org-Mode :Disabled:
:PROPERTIES:
:CUSTOM_ID: Org-Mode-PDF-HTML
:header-args: :tangle no
:END:
In this section we consider the Org-mode export for PDFs (LaTeX).
For example, we account for LaTeX citations.
# Installing LaTex
# $ brew install --cask mactex
# $ eval "$(/usr/libexec/path_helper)"
# $ type pdflatex # => pdflatex is /Library/TeX/texbin/pdflatex
#
# The ~minted~ environment can't appear as an argument to another command; a
# [[https://tex.stackexchange.com/questions/102416/error-when-compiling-a-minted-listings-inside-a-memoir-subfloat][work-around]] is to use a ‘box’. Learn more about LaTeX boxes [[https://latexref.xyz/Boxes.html][here]].
*** Get LaTeX:
:PROPERTIES:
:CUSTOM_ID: Get-LaTeX
:END:
# +begin_src shell
# time brew cask install mactex-no-gui
# +end_src
#+begin_src emacs-lisp
(system-packages-ensure "mactex")
#+end_src
- This is a redistribution of TeX Live specifically for macOS.
- We get the 4GB version since it has [[https://tex.stackexchange.com/a/1041/69371][everything]] and so
do not need to worry about missing style files.
- This took about 12 minutes on my machine.
Restart Emacs, enter =$e^{i \cdot \pi} + 1 = 0$= then press kbd:C-c_C-x_C-l to
have it rendered inline.
+ *Minted:* Get tool for colourful code snippets for LaTeX ---see “minted” in
the main article.
#+begin_src emacs-lisp
(system-packages-ensure "pygments")
#+end_src
+ *Not anymore:* Get a neato PDF presentation console: =brew install pdfpc=
- With =pdfpc myfile.pdf= you get a nice timer and multiple views
of the current slide and upcoming slides ---with support for multiple monitors.
- Install ScreenBrush, from the Apple Store, for easily drawing/annotating my
screen ---e.g., when I'm giving a virtual lecture to my students.
- An alternative is =brew install mupdf= then =mupdf-gl myfile.pdf= and press
=f= for fullscreen then =a= for adding/adorning drawings ---it was too
rough to use live.
Finally, within Emacs: =M-x pdf-tools-install=
:Possibly_breaking_toc-org:
#+BEGIN_SRC emacs-lisp :tangle no
;; Use 3 headlines of export, which is the default
;; (setq org-export-headline-levels 4)
;; no numbers by default at export
;; (setq org-export-with-section-numbers nil)
#+END_SRC
:End:
*** Working with Citations :Disabled:Not_Used:
:PROPERTIES:
:CUSTOM_ID: Working-with-Citations
:END:
# TODO Fix me, breaking Github Actions test setup
[[https://github.com/jkitchin/org-ref][An exquisite system]] for handling references.
The following entity will display useful data
when the mouse hovers over it (•̀ᴗ•́)و If you click on it, then you're
in for a lot of super neat stuff, such as searching for the pdf online!
cite:agda_overview ( In HTML export, the citation doesn't link anywhere. )
#+BEGIN_SRC emacs-lisp :tangle no
(unless noninteractive
(use-package org-ref
:custom ;; Files to look at when no “╲bibliography{⋯}” is not present in a file.
;; Most useful for non-LaTeX files.
(reftex-default-bibliography '("~/thesis-proposal/papers/References.bib"))
(bibtex-completion-bibliography (car reftex-default-bibliography))
(org-ref-default-bibliography reftex-default-bibliography))
;; Quick BibTeX references, sometimes.
(use-package helm-bibtex)
(use-package biblio) )
#+END_SRC
Execute ~M-x helm-bibtex~ or =C-c ]= and, say, enter =emacs= and you will be
presented with all the entries in the bib database that mention ‘emacs’. Super
cool stuff. Moreover, if no such entries exist, then we can look some up
using the interface!
Read the manual [[https://github.com/jkitchin/org-ref/blob/master/org-ref.org][online]] or better yet as an org-file with ~M-x org-ref-help~.
This is an Org-mode application since the citations have tooltips and export
nicely to LaTeX & HTML via the Org-mode exporter.
*** Bibliography & Coloured LaTeX using Minted
:PROPERTIES:
:CUSTOM_ID: Bibliography-Coloured-LaTeX-using-Minted
:END:
Execute the following for bibliography references as well as minted Org-mode
uses the Minted package for source code highlighting in PDF/LaTeX ---which in
turn requires the pygmentize system tool.
#+BEGIN_SRC emacs-lisp
(setq org-latex-listings 'minted
org-latex-packages-alist '(("" "minted"))
org-latex-pdf-process
'("pdflatex -shell-escape -output-directory %o %f"
"biber %b"
"pdflatex -shell-escape -output-directory %o %f"
"pdflatex -shell-escape -output-directory %o %f"))
#+END_SRC
For faster pdf generation, possibly with errors, consider invoking:
#+begin_example emacs-lisp
(setq org-latex-pdf-process
'("pdflatex -interaction nonstopmode -output-directory %o %f"))
#+end_example
By default, Org exports LaTeX using the ~nonstopmode~ option, which tries
its best to produce a PDF ---which ignores typesetting errors altogether,
which is not necessary ideal when using LaTeX.
*** COMMENT Excellent PDF Viewer
:PROPERTIES:
:CUSTOM_ID: Excellent-PDF-Viewer
:END:
Need to (re)build the epdfinfo program, do it now ? (y or n) n
--------------------------------------------------------------------------------
Let's install the [[https://github.com/politza/pdf-tools][pdf-tools]] library for viewing PDFs in Emacs.
#+BEGIN_SRC emacs-lisp
(use-package pdf-tools
; :init (system-packages-ensure "pdf-tools")
:custom (pdf-tools-handle-upgrades nil)
(pdf-info-epdfinfo-program "/usr/local/bin/epdfinfo")
:config (pdf-tools-install))
;; Now PDFs opened in Emacs are in pdfview-mode.
#+END_SRC
Besides the expected PDF viewing utilities, such as search, annotation, and continuous scrolling;
with a simple mouse right-click, we can even select a ‘midnight’ rendering mode which may be
easier on the eyes. For more, see the brief [[https://www.dailymotion.com/video/x2bc1is][pdf-tools-tourdeforce]] demo.
** HTML ⇐ Org-mode
:PROPERTIES:
:CUSTOM_ID: HTML-Org-mode
:END:
In this section we consider the Org-mode exporters for PDFs and
HTMLs. For example, we account for LaTeX citations and reliable HTML
anchors.
#+BEGIN_SRC emacs-lisp
(use-package htmlize )
;; Main use: Org produced htmls are coloured.
;; Can be used to export a file into a coloured html.
#+END_SRC
*** HTML “Folded Drawers” :Move_to_org_special_block_extras:
:PROPERTIES:
:CUSTOM_ID: HTML-Folded-Drawers
:END:
#+BEGIN_SRC emacs-lisp
(defun my/org-drawer-format (name contents)
"Export to HTML the drawers named with prefix ‘fold_’, ignoring case.
The resulting drawer is a ‘code-details’ and so appears folded;
the user clicks it to see the information therein.
Henceforth, these are called ‘fold drawers’.
Drawers without such a prefix may be nonetheless exported if their
body contains ‘:export: t’ ---this switch does not appear in the output.
Thus, we are biased to generally not exporting non-fold drawers.
One may suspend export of fold drawers by having ‘:export: nil’
in their body definition.
Fold drawers naturally come with a title.
Either it is specfied in the drawer body by ‘:title: ⋯’,
or otherwise the drawer's name is used with all underscores replaced
by spaces.
"
(let* ((contents′ (replace-regexp-in-string ":export:.*\n?" "" contents))
(fold? (s-prefix? "fold_" name 'ignore-case))
(export? (string-match ":export:\s+t" contents))
(not-export? (string-match ":export:\s+nil" contents))
(title′ (and (string-match ":title:\\(.*\\)\n" contents)
(match-string 1 contents))))
;; Ensure we have a title.
(unless title′ (setq title′ (s-join " " (cdr (s-split "_" name)))))
;; Output
(cond
((and export? (not fold?)) contents′)
(not-export? nil)
(fold?
(thread-last contents′
(replace-regexp-in-string ":title:.*\n" "")
(format "%s
%s~ and horizontal rules via ~
~. Similarly you can use other HTML tags such as ~
-->B~. *Warning*: JavaScript has some issues when working with Unicode and so, being a JavaScript utility, ~mermaid~ hangs when Unicode is used. On the upside, being a JavaScript utility, ~mermaid~ entities can have [[https://mermaid-js.github.io/mermaid/#/flowchart?id=interaction][arbitrary code attached]] to them to be executed upon clicks ---for use in browsers. - However, the Greek letters are supported; e.g., γ and Σ. See [[https://mermaid-js.github.io/mermaid/#/flowchart?id=nodes-amp-shapes][here]] for possible node shapes. #+begin_quote After forming an intricate diagram of related design patterns, I had to use a number of HTML notions, such as =, , ,
, ,
, ,
= and it was a bit more than I would have liked. In particular, the only
way to change font size was to use the deprecated HTML tag == or heading tags
like ==; even worse, the resulting PDF image did not look nice ---I had to
stretch it out.
The command line tool is *lacking functionality* and so the docs are not helpful.
E.g., I cannot produce pie charts using the command line tool.
#+end_quote
*** [[https://revealjs.com/?transition=zoom#/][Reveal.JS]] -- The HTML Presentation Framework
:PROPERTIES:
:CUSTOM_ID: https-revealjs-com-transition-zoom-Reveal-JS-The-HTML-Presentation-Framework
:END:
Org-mode documents can be transformed into beautiful slide decks
with [[https://github.com/yjwen/org-reveal/blob/master/Readme.org][org-reveal]] with the following two simple lines.
#+BEGIN_SRC emacs-lisp
(use-package ox-reveal
:custom (org-reveal-root "https://cdn.jsdelivr.net/npm/reveal.js"))
#+END_SRC
# MA: ??? It looks like ox-reveal is being abandoned in favor of org-re-reveal,
# a fork compatible with org-mode 9.2?
For example, execute, ~C-x C-e~ after the closing parenthesis of, the
following block to see an example slide-deck (─‿‿─)
#+BEGIN_SRC emacs-lisp :tangle no
(progn (shell-command "curl https://raw.githubusercontent.com/yjwen/org-reveal/696613edef0fe17a9c53146f79933fe7c4101100/Readme.org >> Trying_out_reveal.org")
(switch-to-buffer (find-file "Trying_out_reveal.org"))
(org-reveal-export-to-html-and-browse))
#+END_SRC
Org-mode exporting, ~C-c C-e~, now includes an option ~R~ for such reveal slide decks.
:Hide:
[[https://alhassy.github.io/next-700-module-systems/proposal/defence-slides.html#/sec-title-slide][Here]] ([[https://raw.githubusercontent.com/alhassy/next-700-module-systems/master/proposal/defence-slides.org][source]]) is an example of org-reveal slides where I add a number to each page,
use multiple columns, and extend the margins perhaps a bit too much.
:End:
Two dimensional slides may be a bit new to some people, so I like to
give viewers an option, in tiny font, to view the slide-deck
continuously and remind them that ~?~ provides useful shortcuts.
#+BEGIN_SRC emacs-lisp
(setq org-reveal-title-slide "%t
%a
⟪ Flattened View ; Press ? for Help ⟫
")
#+END_SRC
One should remove the ~&showNotes=true~ if they do not want to include
speaker notes in the flattened view.
Within the flatenned view, one may wish to ~CTRL/CMD+P~ then save the
resulting PDF locally.
** C-c C-l Org-mode ⇐ HTML
:PROPERTIES:
:CUSTOM_ID: Org-mode-HTML
:END:
The following let's us copy htlm into org format using eww, Emacs' built-in web browser.
#+BEGIN_SRC emacs-lisp :tangle no
;; See: https://emacs.stackexchange.com/questions/7171/paste-html-into-org-mode
(use-package org-eww
:quelpa (org-eww :fetcher git :url "https://github.com/Fuco1/org-mode.git"))
#+END_SRC
It does not work as I'd like, but may prove useful to have around.
+ Possibly useful: Open a webpage with ~M-x eww~ then toggle ~M-x read-only-mode~ to
edit the text, say for notes or deletions, as you read! No need to copy-paste.
--------------------------------------------------------------------------------
[[https://github.com/alphapapa/org-web-tools][org-web-tools]] claims to /view, capture, and archive Web pages in Org-mode/; this
may be a very useful tool.
#+begin_src emacs-lisp
(use-package org-web-tools
:config
;; Insert an Org-mode link to the URL in the clipboard or kill-ring. Downloads
;; the page to get the HTML title.
;; (bind-key* "C-c C-l" #'org-web-tools-insert-link-for-url) ;; Instead, see my/org-insert-link-dwim below.
)
#+end_src
Other useful functions, needing pandoc:
doc:org-web-tools-insert-web-page-as-entry and
doc:org-web-tools-convert-links-to-page-entries.
#+begin_src emacs-lisp
;; C-u C-c C-l ⇒ Paste URL with title, WITHOUT prompting me for anything.
;; C-c C-l ⇒ Prompt me for title.
(bind-key* "C-c C-l"
(lambda () (interactive)
(call-interactively
(if current-prefix-arg
#'org-web-tools-insert-link-for-url
#'my/org-insert-link-dwim))))
;; From:
(defun my/org-insert-link-dwim ()
"Like `org-insert-link' but with personal dwim preferences.
- When text is selected, use that as the link description --and prompt for link type
- When a URL is in the clipboard, use that as the link type
- On an existing Org link, prompt to alter the link then to alter the description
- With a ‘C-u’ prefix, prompts for a file to link to.
- It is relative to the current directory; use ‘C-u C-u’ to get an absolute path.
It fallsback to `org-insert-link' when possible.
Functin Source: https://xenodium.com/emacs-dwim-do-what-i-mean/"
(interactive)
(let* ((point-in-link (org-in-regexp org-link-any-re 1))
(clipboard-url (when (string-match-p "^http" (current-kill 0))
(current-kill 0)))
(region-content (when (region-active-p)
(buffer-substring-no-properties (region-beginning)
(region-end)))))
(cond ((and region-content clipboard-url (not point-in-link))
(delete-region (region-beginning) (region-end))
(insert (org-make-link-string clipboard-url region-content)))
((and clipboard-url (not point-in-link))
(insert (org-make-link-string
clipboard-url
(read-string "title: "
(with-current-buffer (url-retrieve-synchronously clipboard-url)
(dom-text (car
(dom-by-tag (libxml-parse-html-region
(point-min)
(point-max))
'title))))))))
(t
(call-interactively 'org-insert-link)))))
#+end_src
* TODO RDD
** get the pkg
#+begin_src emacs-lisp :tangle init.el
(use-package repl-driven-development)
(setq repl-driven-development-echo-duration 10)
#+end_src
** terminal
#+begin_src emacs-lisp :tangle init.el
;; Sometimes I see a bunch of shell incantations in a README or something and I'd like to execute them right there and then,
;; and not have to bother with copying them over to a terminal and execute there. As such, here's a quick key binding to execute
;; shell commands from anywhere.
;; (repl-driven-development [C-x C-t] "bash" :prompt "bash-3.2\\$")
(repl-driven-development [C-x C-t] terminal)
#+end_src
** jshell
#+begin_src emacs-lisp :tangle init.el
;; Set “Cx Cj” to evaluate Java code in a background REPL.
(repl-driven-development
[C-x C-j]
;; enable assertions, and add everything installed, via `mvn', in scope.
(format "jshell --class-path %s --enable-preview -R -ea --feedback silent"
(concat ".:" (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f 2>/dev/null | tr '\n' ':'")))
:prompt "jshell>"
:init "\n /set mode EmacsJavaMode normal -command
\n /set format EmacsJavaMode display \"{pre}added import {name}{post}\" import-added
\n /set format EmacsJavaMode display \"{pre}re-added import {name}{post}\" import-modified,replaced
\n /set format EmacsJavaMode result \"{type} {name} = {value}{post}\" added,modified,replaced-primary-ok
\n /set truncation EmacsJavaMode 40000
\n /set feedback EmacsJavaMode
\n System.out.println(\"Enjoy Java with Emacs (｡◕‿◕｡))\")")
;; TODO [Truncation; Low] https://github.com/xiongtx/eros/blob/master/eros.el#L202
#+end_src
** mvn
#+begin_src emacs-lisp :tangle init.el
(defun mvn (groupId artifactId)
"Quickly install a library from Maven Central."
(async-shell-command (format "mvn org.apache.maven.plugins:maven-dependency-plugin:2.8:get -Dartifact=%s:%s:LATEST:jar:sources" groupId artifactId)))
(when nil
⨾⨾ Example use of `mvn`
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; First confirm C-x C-j works as intended
IntStream.range(0, 15).mapToObj(i -> i % 15 == 0 ? "FizzBuzz" : i % 3 == 0 ? "Fizz" : i % 5 == 0 ? "Buzz" : String.valueOf(i)).toList()
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
(mvn "org.antlr" "antlr4") ;; C-x C-e
;; Now re-start the Java C-x C-j repl via a C-x C-e (lame! not ergonomic!)
;; Now check that you have access to antrl in your repl by importing it and looking at one of its classes:
;; ⦃ jshell --class-path /Users/musa/.m2/repository/org/antlr/antlr4-runtime/4.13.0/antlr4-runtime-4.13.0.jar ⦄
import org.antlr.v4.runtime.*;
CommonTokenStream.class
;; NOTE: This is the runtime, to use the actual tool:
java -jar /Users/musa/.m2/repository/org/antlr/antlr4/4.13.0/antlr4-4.13.0-complete.jar
;; Alternatively,
;; $ jshell
;; > var x = 5
;; > import org.antlr.v4.runtime.*; // CRASHES since antlr is not in scope
;; > /reset --class-path /Users/musa/.m2/repository/org/antlr/antlr4-runtime/4.13.0/antlr4-runtime-4.13.0.jar
;; > import org.antlr.v4.runtime.*; // WORKS, yay
;; > x // CRASHES, not in scope
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
import org.apache.commons.lang3.StringUtils;
StringUtils.class;
/imports // JShell command to list all imports, it now contains apache!
// Guava is the Google core libraries for Java
import com.google.common.collect.ImmutableMap;
ImmutableMap.of(1, "A", 2, "B") // ⇒ {1=A, 2=B}
;; (mvn "com.google.code.gson" "gson")
// Then C-x C-e to update the repl definition of C-x C-j to include the updated gson library.
import com.google.gson.*;
String json = new Gson().toJson(Map.of("me", List.of(1, 2,3), "you", Map.of("Love", "Lisp", "Hate", "Verbosity")))
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; TestNG is a testing framework; supporting tests configured by annotations, data-driven testing, parametric tests, etc.
(mvn "org.testng" "testng")
import org.testng.*;
/imports // Now can see org.testng at the end of the list
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; TODO[Low]: For working with Lombok annotations, use the jshell `/reset --class-path` command to include the lombok compiled file into
;; the current Jshell session.
;;
;; See: https://stackoverflow.com/questions/74084364/how-to-use-lombok-in-jshell
;;
;; (mvn "org.projectlombok" "lombok")
;; import lombok.*;
;; @lombok.Data class Test { private String name; }
;; new Test().equals(new Test())
)
#+end_src
** Adding support for “//!use” & “//!omit” top level repl commands
#+begin_src emacs-lisp
;; Adding support for “//!use” & “//!omit” top level repl commands
(setq repl/jshell/classpath (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f | tr '\n' ':'"))
(advice-add 'repl/jshell
:around (lambda (repl &rest args)
(if (equal nil current-prefix-arg)
;; No prefix supplied
(progn
(setq rdd---current-input (s-replace-regexp "\n" "" (s-trim-left
(if (region-active-p) (buffer-substring-no-properties (region-beginning) (region-end))
(substring-no-properties (thing-at-point 'line))))))
(if (s-starts-with? "//!use" rdd---current-input)
(-let [jar (s-trim (s-chop-prefix "//!use" rdd---current-input))]
(repl/top-level//!use jar))
(if (s-starts-with? "//!omit" rdd---current-input)
(-let [jar (s-trim (s-chop-prefix "//!omit" rdd---current-input))]
(repl/top-level//!omit jar))
;; otherwise business as usual
(apply repl args))))
(pcase current-prefix-arg
(-1
;; reset classpath to default, then business as usual.
(setq repl/jshell/classpath (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f | tr '\n' ':'"))
(apply repl args))
(999
(message-box "It worked"))
;; otherwise business as usual
(t (apply repl args))))))
;; remove all advice
;; (-let [sym 'repl/jshell] (advice-mapc (lambda (advice _props) (advice-remove sym advice)) sym))
(cl-defun repl/top-level//!omit (str)
(with-temp-buffer
(setq repl/jshell/classpath (s-replace-regexp (format ":[^:]*%s[^:]*:" str) ":" repl/jshell/classpath))
(insert "/env --class-path ")
(insert repl/jshell/classpath)
(repl/jshell (point-min) (point-max))))
(cl-defun repl/top-level//!use (str)
"If the given jar cannot be added successful, the existing classpath remains untouched.
Return to your default classpath by invoking the repl with the -1 prefix.
Example usage:
//!use ~/path/to/compiled/java/classes
import com.x.y.z;
Where directory hierarchy com/x/y/z denotes a Java package under the above //!use path.
"
(with-temp-buffer
(setq repl/jshell/classpath (concat (s-trim str) ":" repl/jshell/classpath))
(insert "/env --class-path ")
(insert repl/jshell/classpath)
(repl/jshell (point-min) (point-max))))
#+end_src
** Misc top level cmds
TODO: Make repl load all company class files, that way I have them upon start up.
OR: Provide a command `//!load ~/dir` which recursively loads/imports all java files? <---Probably this!
** COMMENT C-x C-e ∷ REPL-driven development for ELisp / NodeJS / Python / Etc !
:PROPERTIES:
:CUSTOM_ID: C-x-C-e-REPL-driven-development-for-NodeJS
:END:
| /Evaluate code and see the results inline ---A feedback loop that is faster than ever!/ |
Within Emacs, kbd:C-x_C-e evaluates a Lisp expression /anywhere/; e.g.,
at the end of ~(message-box "hello world")~ press ~C-x C-e~ to see a greeting.
# Likewise, evaluating a variable shows you its value: user-full-name.
- We ran some code /without/ explicitly running an interpreter/repl/compiler!
- This is known as “REPL driven development” (RDD):
There is a running REPL server for your language, implicitly in the
background, and your editor (say with ~C-x C-e~) will send it a line (or a
selected region) of code for evaluation; we then see the result as an
overlay in our current buffer.
+ You /choose/ which code gets (re)evaluated.
- A quick introduction to RDD can be viewed at [[https://purelyfunctional.tv/lesson/what-is-repl-driven-development/][PurelyFunctional.tv]].
*** ELisp
:PROPERTIES:
:CUSTOM_ID: ELisp
:END:
By default, Emacs Lisp's kbd:C-x_C-e shows results only in the minibuffer; near
the bottom of the screen. Let's also have evaluation results displayed as inline
overlays ---at the location that the user, us, is actually looking/working;
rather than forcing their eyes to shift up&down when writing&evaluating.
+ kbd:C-u_C-x_C-e inserts the evaluation result at point; kbd:C-u_0_C-x_C-e does
so /without truncating/ lengthy output.
+ Read this [[https://karthinks.com/software/an-elisp-editing-tip/][Sweet & short blog/GIFs]] on practical uses of kbd:C-x_C-e when working with Lisp.
#+begin_src emacs-lisp
;; Evaluation Result OverlayS for Emacs Lisp
(use-package eros
:defer nil
:init (eros-mode t))
#+end_src
# In particular, this gives us the Lisp function
# `eros--eval-overlay', which evaluates its argument X
# and produces an overlay of the result at position P.
# E.g., (eros--eval-overlay "hola" (point-min))
# Shows a momentary overlay at the first line.
*** JavaScript
:PROPERTIES:
:CUSTOM_ID: JavaScript
:END:
Let's setup RDD for JavaScript ---by having a NodeJS repl server running in the background.
- See [[https://github.com/anonimitoraf/skerrick][skerrick: REPL-driven development for Javascript]] for animated GIFs; it
works with modules as well.
#+begin_src emacs-lisp
(use-package skerrick
:defer nil
:init
;; Needs to be run on the very first install of skerrick. Or when you want to upgrade.
(unless (equal (shell-command-to-string "type skerrick") "skerrick not found\n")
(skerrick-install-or-upgrade-server-binary)))
;; Should be run in a JS buffer; it is buffer specific.
;; (skerrick-start-server)
;; Now main function, entry point is:
;; M-x skerrick-eval-region
#+end_src
Let's provide a quick keyboard shortcut. E.g., kbd:C-x_C-e evaluates ELisp, so let's mimic that for JS buffers:
#+begin_src emacs-lisp
(require 'js) ;; Defines js-mode-map
;; Evaluate a region, if any is selected; otherwise evaluate the current line.
(bind-key
"C-x C-e" (lambda ()
(interactive)
(if (use-region-p)
(skerrick-eval-region)
(beginning-of-line)
(set-mark-command nil)
(end-of-line)
(skerrick-eval-region)
(pop-mark)))
'js-mode-map)
#+end_src
Trying something else instead of skerrick, until
https://github.com/anonimitoraf/skerrick/issues/7 is resolved.
In any JS file, I just press ~C-x C-e~ and the JS interpreter is brought up with the evaluation results shown:
#+begin_src emacs-lisp
(use-package js-comint :defer nil)
(define-key js-mode-map (kbd "C-x C-e") (lambda () (interactive) (call-interactively #'js-comint-repl) (other-window -1) (js-comint-send-last-sexp)))
#+end_src
For instance,
#+begin_src js :tangle no
// Start the server... then
// On each line and press C-x C-e
let a = "hello"
let b = "world"
(a + ' ' + b).toUpperCase()
// The final line should show: HELLO WORLD
#+end_src
**** Preserving the context
:PROPERTIES:
:CUSTOM_ID: Preserving-the-context
:END:
When testing an application, you might notice a bug in a particular context
---i.e., a particular configuration in the app.
1. The classic approach is to kill the app; i.e., stop the server that is, well,
serving the app.
2. Solve the problem.
3. Try to get back to the configuration, context, you were in beforehand and
check that the problem has been resolved.
A better approach is to ignore the bookkeeping steps, 1&3, and just do step 2.
For that, there are numerous packages:
- [[https://github.com/mishoo/livenode/][livenode: Live-code your NodeJS applications]] ⨾⨾ [[https://vimeo.com/60636079][Video demo]] ~11min ⨾⨾ Last
updated 2013
- [[https://github.com/skeeto/skewer-mode][skewer-mode: Live web development in Emacs]] ⨾⨾ [[https://www.youtube.com/watch?v=4tyTgyzUJqM&ab_channel=Skeeto][Silent video demo]] ~5min ⨾⨾ Last
updated 2020
- [[https://github.com/swank-js/swank-js][swank-js: Swank backend for Node.JS and in-browser JavaScript]] ⨾⨾ Last updated
2015
For more RDD alternatives in Emacs, see https://github.com/anonimitoraf/skerrick/issues/8.
*** Python, etc
:PROPERTIES:
:CUSTOM_ID: Python-etc
:END:
It /seems/ to be /super easy/ to add such a support for other languages, such as Python.
See the final comment [[https://karthinks.com/software/an-elisp-editing-tip/][here]] for the tiny change required.
** COMMENT Quickly Run Code Snippets
:PROPERTIES:
:CUSTOM_ID: Quickly-Run-Code-Snippets
:END:
Sometimes we want to quickly run some code /without making a dedicated file/ or
with a file but /without remembering the terminal incantation to do so/, enter
~quickrun~. Anywhere, we can select a snippet of code and run TODO. doc.quickrun-region
to execute that snippet after selecting the associated programming language, or
TODO. doc.quickrun-replace-region if we want the results in-line. If our language of
choice does not exist, we can [[https://github.com/emacsorphanage/quickrun#user-defined-command][easily add support for it]].
#+begin_src emacs-lisp
;; In any programming buffer, “M-x quickrun” to execute that program.
;; Super useful when wanting to quickly test things out, in a playground.
;;
;; E.g., Make a new file named “hello.py” containing “print "hi"”, then “M-x quickrun”.
;;
;; Enable “quickrun-autorun-mode” to run code after every save.
(use-package quickrun
;; ⇒ “C-c C-r” to see output, “q” to close output
;; ⇒ “C-u C-c C-r” prompts for a language (Useful when testing snippets different from current programming mode)
;; ⇒ In a non-programming buffer, “C-c C-r” runs selected region.
:defer nil
:config (bind-key* "C-c C-r"
(lambda (&optional start end)
(interactive "r")
(if (use-region-p)
(quickrun-region start end)
(quickrun current-prefix-arg)))))
#+end_src
Example...
#+begin_src emacs-lisp
(system-packages-ensure "rust") ;; Rust Compiler
;; Select the following then press C-c C-r: fn main() { println!("Hello, World!"); }
#+end_src
Actually, let's get a [[https://github.com/brotzeit/rustic#intro][full Rust development environment for Emacs]] (which also
has [[https://github.com/brotzeit/rustic#org-babel][great support for Org-babel]].)
#+begin_src emacs-lisp
(use-package rustic :defer nil)
;; Open any Rust file, and run “M-x lsp” which will then prompt you to install
;; rust-analyzer, the rust LSP.
;;
;; LSP for Rust ⇒ Goto definition (M-. / ⌘-l), code completion with types and
;; docstrings, colourful documentation on hover, “Run [Test] | Debug” overlays,
;; super nice stuff! Run “M-!”/[M-x company-show-doc-buffer] if you want the doc in a colourful buffer.
;;
;; Below, hover over “Vec” and see nice, scrollable, colourful docs on vectors.
;; let v:Vec<_> = vec![1, 2, 3];
;; The offical Rust toolchain installer
(system-packages-ensure "rustup")
(shell-command "rustup update")
#+end_src
:More_on_rust:
Now, C-c C-c C-d on something to get help/description of it.
(setq rustic-racer-rust-src-path "/Users/musa/.rustup/toolchains/stable-x86_64-apple-darwin/lib/rustlib/src/rust/library/")
# Get Rustup, load it into current terminal session
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.bash_profile
source ~/.bashrc
type rustup
# Get stuff
rustup update
rustup component add rust-src
cargo +nightly install racer
rustup toolchain install nightly
rustup component add rustc-dev --toolchain=nightly
cargo +nightly install racer
:End:
* Don't show updating/installation shell buffers
#+begin_src emacs-lisp
;; By default, say, (async-shell-command "date") produces a buffer
;; with the result. In general, such commands in my init.el are for
;; updating/installing things to make sure I have the same up-to-date
;; setup where-ever I use my Emacs. As such, I don't need to see such buffers.
(add-to-list 'display-buffer-alist
'("\\*Async Shell Command\\*.*" display-buffer-no-window))
;; For an approach that does not inhibit async-shell-command this way,
;; see https://emacs.stackexchange.com/questions/299/how-can-i-run-an-async-process-in-the-background-without-popping-up-a-buffer
#+end_src
* TODO Programming
:PROPERTIES:
:CUSTOM_ID: Programming
:END:
Herein we configure utilites for version control, function and variable lookup,
and template expansion for inescapably repetitive scenarios.
TODO: Fix these docs
# TODO: + Checkout branches/PRs with doc : my/gh-checkout
# + See all company related PRs with doc : w-PRs
# + Quickly look up language/library docs /within/ Emacs with kbd:C-c_d.
#+begin_src emacs-lisp
(when my/work-machine?
(setq doom-modeline-buffer-file-name-style 'truncate-except-project))
#+end_src
** COMMENT devdocs
:PROPERTIES:
:CUSTOM_ID: devdocs
:END:
#+begin_src emacs-lisp
;; 1. Get docs of a languages: M-x devdocs-install
;; 2. Lookup docs: [C-u] M-x devdocs-lookup
;; 𝟚. Lookup docs: [C-u] C-c d
(use-package devdocs
:defer nil
:bind ("C-c d" . #'devdocs-lookup)
:config
(when nil ;; “C-x C-e” the following once.
(cl-loop for lang in '(javascript ramda typescript html css sass
vue~3 vuex~4 vue_router~4 "angularjs~1.6"
nginx webpack~5 web_extensions
;;
eslint jest jq jsdoc prettier
mocha chai jasmine
;;
bash docker~19 git homebrew elisp
;;
postgresql~14 redis sqlite
;;
rust ruby~3 minitest "rails~7.0")
do (devdocs-install (list (cons 'slug (format "%s" lang)))))))
#+end_src
** COMMENT How do I do something?
:PROPERTIES:
:CUSTOM_ID: How-do-I-do-something
:END:
When programming, sometimes you just gotta Google “how do I do ⋯”.
- The usual process is (1) open a browser, (2) make a Google query, (3) look
at StackOverflow's most upvoted answer for your query, (4) copy-paste the
code solution/example to your editor; [(5) get distracted by interesting
things you'd like to read].
- Better would be to use the [[https://github.com/gleitz/howdoi][howdoi]] tool, which gives instant coding answers
for common questions via the command line.
- Below, my /Emacs Lisp/ function doc : howdoi let's me reduce the 4-step process
to just 2 steps: Write your query /anywhere/ then call ~M-x howdoi~ on it to
replace the query with the answer. (Or ~C-u M-x howdoi~ to see the full answer
and a link to it on StackOverflow.)
| /⚡ Never open your browser to look for help again ⚡/ |
#+begin_src emacs-lisp
(system-packages-ensure "howdoi")
(cl-defun howdoi (&optional show-full-answer)
"Instantly insert coding answers.
Replace a query with a code solution; replace it with an entire
answer if a prefix is provided.
Example usage:
On a new line, write a question such as:
search and replace buffer Emacs Lisp
Then invoke ‘M-x howdoi’ anywhere on the line
to get a code snippet; or ‘C-u M-x howdoi’ to get a full answer to your query.
"
(interactive "P")
(let ((query (s-collapse-whitespace (substring-no-properties (thing-at-point 'line))))
(flag (if show-full-answer "-a" "")))
(beginning-of-line)
(kill-line)
(insert (shell-command-to-string (format "howdoi %s %s" query flag)))))
#+end_src
** Sleek Semantic Selection
:PROPERTIES:
:CUSTOM_ID: Sleek-Semantic-Selection
:END:
Super sleek way to select regions: Anywhere press kbd:⌘-r to select the current
word, press it again to select sentence, then again for the current paragraph,
then more to get the current section.
#+begin_src emacs-lisp
(use-package expand-region
:bind (("s-r" . #'er/expand-region)))
#+end_src
You can watch an introductory ~3 minute video to expand-region at [[http://emacsrocks.com/e09.html][Emacs Rocks!]].
That is, /repeated ⌘+r expands the selection to the next logical segment of text:/
In writing this means “Word, sentence, paragraph”, and in programming this means
“identifier, then incrementally larger scopes”.
** COMMENT Managing Processes/Servers from within Emacs ---Work-specific functions
:PROPERTIES:
:CUSTOM_ID: Managing-Processes-Servers-from-within-Emacs-Work-specific-functions
:END:
Let's make a few interactive Emacs Lisp functions to reduce the amount of time I
need to be in a terminal. I'll use the /prefix ~“w-”~ for work stuff/. Example
tasks:
+ Start/stop my servers
+ Interactively select an app to be opened in the browser
+ Do database migrations/rollbacks
⟨ Obfuscated with lorem ipsum text. ⟩
[[file:images/services-dashboard.png]]
--------------------------------------------------------------------------------
Not using this, a bit too verbose to setup for each service but, more
accurately, does not Just Workᵀᴹ for my needs.
#+begin_src emacs-lisp
;; “M-x prodigy”, then press “s” to start a service; “S” to stop it; “$” to see it; “r”estart
(use-package prodigy :disabled t)
;; C-h v prodigy-services ⇒ See possible properties.
#+end_src
*** my/defaliases
:PROPERTIES:
:CUSTOM_ID: my-defaliases
:END:
#+begin_src emacs-lisp
(defalias 'defaliases 'my/defaliases)
(defmacro my/defaliases (src &rest tgts)
"Provide names TGTS as synonymous aliases for SRC, for discovarability.
Often a function SRC can be construed from different perspectives, names, purposes TGTS.
Another example is when I define things with the ‘my/’ prefix, but also want to use them without.
Example use: (my/defaliases view-hello-file greet-others learn-about-the-world)
In particular: (my/defaliases OLD NEW) ≈ (defalias 'NEW 'OLD)."
`(--map (eval (quote (defalias `,it (quote ,src)))) (quote ,tgts)))
#+end_src
*** Making unkillable buffers & shells
:PROPERTIES:
:CUSTOM_ID: Making-unkillable-buffers-shells
:END:
#+begin_details "Making unkillable buffers & shells"
#+begin_src emacs-lisp
(defun my/declare-unkillable-buffer (name)
(add-hook 'kill-buffer-query-functions
`(lambda () (or (not (equal (buffer-name) ,name))
(progn (message "Not allowed to kill %s, burying instead; otherwise use “M-x force-kill”" (buffer-name))
(bury-buffer))))))
(my/defaliases my/force-kill force-kill w-force-kill)
(cl-defun my/force-kill (&optional buffer-name)
(interactive)
(-let [kill-buffer-query-functions nil]
(if buffer-name
(kill-buffer buffer-name)
(kill-current-buffer))
(ignore-errors (delete-window))))
(cl-defun my/run-unkillable-shell (command &optional (buffer-name command))
"Example use: (my/run-unkillable-shell \"cd ~/my-noejds-project; npm run dev\" \"my-nodejs-project\")"
(-let [it (get-buffer buffer-name)]
(if it
(switch-to-buffer-other-window it)
(async-shell-command command buffer-name)
(my/declare-unkillable-buffer buffer-name))))
#+end_src
#+end_details
*** w-start/stop-services
:PROPERTIES:
:CUSTOM_ID: w-start-stop-services
:END:
#+begin_src emacs-lisp
(defvar my/services nil "List of all services defined; used with `w-start-services' and `w-stop-services'.")
(defun w-start-services ()
(interactive)
(cl-loop for 𝑺 in my/services
do (funcall (intern (format "w-start-%s" 𝑺)))))
(defun w-stop-services ()
(interactive)
(cl-loop for 𝑺 in my/services
do (funcall (intern (format "w-stop-%s" 𝑺)))))
#+end_src
*** w-status-of-services
:PROPERTIES:
:CUSTOM_ID: w-status-of-services
:END:
#+begin_src emacs-lisp
;; It takes about ~3 seconds to build the Status of Services page, so let's jump to it if it's already built, and the user/me can request a refresh, if need be.
(global-set-key (kbd "M-S-SPC")
(lambda () (interactive)
(-let [buf (get-buffer "Status of Services")] (if buf (switch-to-buffer buf) (w-status-of-services)))))
;;
;; Since M-S-SPC brings up the transient menu, and most commands close the status buffer or are transient, we get the perception that the transient menu is "sticky"; i.e., stuck to the buffer, even though this is not true. I do not yet know how to make a transient menu stuck to a buffer.
;;
#+end_src
#+begin_src emacs-lisp
(defun w-status-of-services ()
"Show me status of all servers, including their current git branch, and most recent emitted output."
(interactive)
(defvar w-status-of-services/branch-name-width 12
"What is the length of the longest branch name? Let's use that to ensure there's enough whitespace.")
(-->
(-let [ shells (--filter (s-starts-with? "Shell" (process-name it)) (process-list)) ]
(cl-loop for 𝑺 in (mapcar #'pp-to-string my/services)
for associated-shell = (--find (s-contains? (format "%s" 𝑺) (cl-third (process-command it))) shells)
for status = (or (ignore-errors (process-status associated-shell)) '💥)
for branch = (-let [default-directory (format "~/%s" 𝑺)]
(magit-get-current-branch))
for _ = (setq w-status-of-services/branch-name-width (max (length branch) w-status-of-services/branch-name-width))
for 𝑺-buffer = (--find (s-starts-with? (format "*Server:%s" 𝑺) it) (mapcar 'buffer-name (buffer-list)))
for saying = (let (most-recent-shell-output (here (current-buffer)))
(if (not 𝑺-buffer)
" ─Server not started─ "
(switch-to-buffer 𝑺-buffer)
(end-of-buffer)
(beginning-of-line)
(setq most-recent-shell-output (or (thing-at-point 'line t) ""))
(switch-to-buffer here)
;; FIXME:here
(--> (s-truncate 135 (s-trim most-recent-shell-output))
(if (s-contains? "|" it)
(cl-second (s-split "|" it))
it)
(s-trim it)
(if (<= (length it) 3) (s-repeat 70 " ") it))))
for _ = (if (or (s-contains? "Error" saying) (not 𝑺-buffer)) (setq status '💥))
for keymap = (copy-keymap org-mouse-map)
do (cl-loop for (key action)
on `( ;; Checkout branch/PR
c (w-pr-checkout (format "~/%s" ,𝑺))
;; Restart service, remaining on current branch [not switching to “main”!]
r (-let [current-prefix-arg t]
(funcall (intern (format "w-stop-%s" ,𝑺)))
(funcall (intern (format "w-start-%s" ,𝑺))))
f (-let [default-directory (format "~/%s" ,𝑺)]
(call-interactively #' projectile-find-file))
t (vterm-shell-command (format "clear; cd ~/%s; git status" ,𝑺) (format "vterm/%s" ,𝑺))
;; See the repo in the web
w (--> (format "%s" ,𝑺)
(if (s-contains? "/" it) (f-parent it) it)
(format "https://github.com/%s/%s" work/gh-user it)
(browse-url it))
;; Visit service shell
(when ,𝑺-buffer
(delete-other-windows)
(split-window-below)
(switch-to-buffer ,𝑺-buffer)
(end-of-buffer)
(other-window 1))
;; See service magit buffer
(progn (magit-status (format "~/%s" ,𝑺)) (delete-other-windows)))
by #'cddr
do (define-key keymap (kbd (format "%s" key))
`(lambda () (interactive) ,action)))
collect
;; “%𝑾s” ⇒ Print a string with at least width 𝑾: If length(str) ≤ 𝑾, then pad with spaces on the left side.
;; Use “%-𝑾s” to instead pad with spaces to the right.
(list keymap (format (format "%%s %%-20s %%-%ss %%s" (+ 5 w-status-of-services/branch-name-width)) status 𝑺 branch saying))))
;; Setup buffer
(-let [buf "Status of Services"]
(ignore-errors (kill-buffer buf))
(switch-to-buffer buf)
(delete-other-windows)
it)
;; Insert out buttons
(--each it
;; https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlay-Properties.html
(-let [help (s-join "\n"
'("Keybindings:"
"[C-u] c ∷ Checkout PR [or branch] \t\t\t b ∷ Browse an app"
"tab ∷ See service magit buffer \t\t\t i ∷ Inject users"
"return ∷ Visit service shell \t\t\t s ∷ SQL buffer"
"r ∷ Restart service \t\t\t w ∷ See the repo in the web"
"f ∷ Find file in project \t\t\t t ∷ Terminal"
"g ∷ Refresh this view \t\t\t q ∷ Quit, and kill, this buffer"))]
(insert-text-button (s-replace "\"" "″" (s-replace "run" "✅" (nth 1 it)))
'face nil
;; 'mouse-face '(:box t) ;; I use the cursor more than the mouse, so don't want two distinct views.
'keymap (nth 0 it)
;; NOTE: The functions are called only when the minor mode cursor-sensor-mode is turned on.
;; When cursor enters the button, we temporarily make it a box and show shortcuts in message area.
'cursor-sensor-functions `((lambda (_ old-pos entered?)
(message ,help)
(setq entered? (equal entered? 'entered))
(-let [self (button-at (if entered? (point) old-pos))]
(read-only-mode 0) ;; Temporarily disable help-mode's read-only-mode setup.
(if entered?
(button-put self 'face '(:box "yellow" :weight bold))
(button-put self 'face nil)))))
'help-echo help)
(insert "\n")))
;; Do some highlighting, as a cautionary measure.
(highlight-regexp ".*crashed.*" 'hi-red-b)
;; Forbid editing
(help-mode) ;; This wont do the button face changes I like when cursor moves; so I disable read-only-mode temporarily when making the changes.
(cursor-sensor-mode)
(stripe-buffer-mode)
(visual-line-mode -1)
(toggle-truncate-lines)
;; Add some specific work related bindings
(local-set-key "b" #'w-browse-app)
(local-set-key "i" #'w-inject-users)
(local-set-key "s" (lambda () (interactive) (w-sql) (delete-other-windows)))
;; Add general view keys
(local-set-key "g" (lambda () "Refresh this view" (interactive) (ignore-errors (kill-buffer-and-window)) (w-status-of-services)))
(local-set-key "q" (lambda () "Quit buffer" (interactive) (ignore-errors (kill-buffer-and-window))))
;; Go to the first entry, so my “homemade echo menu” appears.
(beginning-of-buffer)))
#+end_src
**** COMMENT Old definition with colourful menu :ignore:
:PROPERTIES:
:CUSTOM_ID: COMMENT-Old-definition-with-colourful-menu
:END:
#+begin_src emacs-lisp
(defun w-status-of-services ()
"Show me status of all servers, including their current git branch, and most recent emitted output."
(interactive)
(thread-last
(-let [ shells (--filter (s-starts-with? "Shell" (process-name it)) (process-list)) ]
(cl-loop for 𝑺 in (mapcar #'pp-to-string my/services)
for associated-shell = (--find (s-contains? (format "%s" 𝑺) (cl-third (process-command it))) shells)
for status = (or (ignore-errors (process-status associated-shell)) '💥)
for branch = (-let [default-directory (format "~/%s" 𝑺)]
(magit-get-current-branch))
for saying = (let (most-recent-shell-output (here (current-buffer)))
(switch-to-buffer (--find (s-starts-with-p 𝑺 (buffer-name it)) (buffer-list)))
(end-of-buffer)
(beginning-of-line)
(setq most-recent-shell-output (or (thing-at-point 'line t) ""))
(switch-to-buffer here)
(s-truncate 135 (s-trim most-recent-shell-output)))
collect
;; “%𝑾s” ⇒ Print a string with at least width 𝑾: If length(str) ≤ 𝑾, then pad with spaces on the left side.
;; Use “%-𝑾s” to instead pad with spaces to the right.
(format "%s %-20s %-12s %s" status 𝑺 branch
(-let [it (s-trim (if (s-contains? "|" saying)
(cl-second (s-split "|" saying))
saying))]
(if (<= (length it) 3) "-" it)))))
(--map (format "%s" it))
(s-join "\n")
(s-replace "run" "✅")
(funcall (lambda (it) (-let [max-mini-window-height 0]
(ignore-errors (kill-buffer "Status of Services"))
(display-message-or-buffer it "Status of Services")
(delete-other-windows)
(switch-to-buffer "Status of Services")
(highlight-regexp ".*crashed.*" 'hi-red-b)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Start describing the keys
(end-of-buffer)
(insert "\n \n \n \n \n")
(let ((register-action (lambda (key-desc-actions)
(if (stringp key-desc-actions)
(propertize key-desc-actions 'font-lock-face '(face success))
(-let [ [key desc &rest actions] key-desc-actions ]
;; For buffer-local keys, you cannot use local-set-key, unless you want to modify the keymap of the entire major-mode in question: local-set-key is local to a major-mode, not to a buffer.
;; (use-local-map (copy-keymap text-mode-map))
(local-set-key key `(lambda () (interactive) ,@(seq-into actions 'list)))
(format "%s %s"
(propertize (format "%s" key) 'font-lock-face '(face error))
(propertize desc 'font-lock-face '(:foreground "grey")))))))
(repo-at-point (lambda () (-as-> (beginning-of-line) repo
(thing-at-point 'line t)
(s-split " " repo)
cl-second))))
(insert (s-join "\n" (seq-mapn (lambda (&rest cols) (apply #'format (s-repeat (length cols) "%-40s ")
(--map (funcall register-action it) cols)))
["This view"
["g" "Refresh this view" (ignore-errors (kill-buffer-and-window)) (w-status-of-services)]
["q" "Quit buffer" (ignore-errors (kill-buffer-and-window))]
["" "" ""]]
`["Current service"
["c" "Checkout PR" (w-pr-checkout (format "~/%s" (funcall ,repo-at-point)))]
[[return] "Visit service shell"
(delete-other-windows)
(split-window-below)
(switch-to-buffer (--find (s-starts-with? (funcall ,repo-at-point) (buffer-name it)) (buffer-list)))
(end-of-buffer)
(other-window 1)]
[[tab] "See service magit buffer"
(magit-status (format "~/%s" (funcall ,repo-at-point)))
(delete-other-windows)]]
["Misc"
["b" "Browse an app" (w-browse-app)]
["i" "Inject users" (w-inject-users)]
["s" "SQL buffer" (w-sql) (delete-other-windows)]]))))
(beginning-of-buffer)
;; (help-mode) ;; For some reason, default fundamental-mode does not regoznise proprtised strings.
;; Also, this is read-only be default and emits a nice message for undefiend single key bindings.
;; (help-mode)
)))))
#+end_src
*** my/defservice
:PROPERTIES:
:CUSTOM_ID: my-defservice
:END:
#+begin_src emacs-lisp
;; Even though I'm doing frequent prunes, it helps to give docker some leeway.
;; NOTE: Docker Icon → Preferences → Resources → 4 CPUs; 8gb Memory; 2gb Swap; 120 DiskImageSize.
(cl-defmacro my/defservice
(repo &key (main-setup "git checkout main; git pull; git status; hr; npm ci; hr; time docker system prune -af")
(cmd "npm run docker:dev")
(example ""))
"Example use:
(my/defservice 𝒟 :cmd 𝒞 :example ℰ)
⇒
(w-start-𝒟) ≈ Unkillable shell: cd 𝒟; 𝒞
(w-is-up-𝒟?) ≈ Open browser at ℰ
(w-stop-𝒟) ≈ Kill all emacs-buffers & docker-images containing 𝒟 in their name
(w-[start|stop]-services) ⇒ Starts/stops all defined services."
(add-to-list 'my/services repo)
`(list
(cl-defun ,(intern (format "w-start-%s" repo)) ()
"Start server off of ‘main’, with prefix just start server off of current branch."
(interactive)
(let ((command (format "cd ~/%s; pwd; hr; %s; hr; %s"
(quote ,repo)
(if current-prefix-arg "" ,main-setup)
,cmd))
(buf-name (format "*Server:%s/%s*" (quote ,repo)
(if current-prefix-arg "main"
(-let [default-directory ,(format "~/%s" repo)]
(magit-get-current-branch))))))
(my/run-unkillable-shell
(format "echo %s; hr; %s" (pp-to-string command) command) ;; Show command being run in output buffer, then run that command
buf-name)
(with-current-buffer buf-name (read-only-mode))))
(cl-defun ,(intern (format "w-stop-%s" repo)) ()
"Force-kill all unkillable buffers that mention REPO in their name. Also stop any docker services mentioning REPO in their name."
(interactive)
(my/docker-stop ,(pp-to-string repo))
(thread-last (buffer-list)
(mapcar 'buffer-name)
(--filter (s-contains-p ,(pp-to-string repo) it))
(mapcar #'my/force-kill)))
(if ,example
(cl-defun ,(intern (format "w-is-up-%s?" repo)) ()
(interactive)
(browse-url ,example)
(message "If the URL is busted, then the repo is not up correctly or the server has an error!")))))
#+end_src
In my private ~work.el~ I have declarations of the form ~(my/defservice ⟨directory⟩
:cmd "npm run dev" :example "Example URL to try out for this server")~.
#+begin_src emacs-lisp
(when my/work-machine?
(load-file "~/Desktop/work.el"))
#+end_src
** Project management & navigation
:PROPERTIES:
:CUSTOM_ID: Project-management-navigation
:END:
Version controlled repositories are considered “projects” ---no setup needed---,
but you can declare your own too.
Videos:
+ ~5mins: https://youtu.be/bFS0V_4YfhY
+ ~1hr: https://www.youtube.com/watch?v=INTu30BHZGk
This is so sweet at work (and possibly at home!): From anywhere,
+ [[kbd:C-x p p]] ⟨select your project⟩ RET ⟨start typing to see any file anywhere in the project⟩
+ [[kbd:C-x p b ]] ⇒ Switch to buffers only in the current “stream of thought” (project).
+ [[kbd:C-x p f ]] ⇒ Find files only in the current “stream of thought” (project).
+ [[kbd:C-x p s g ]] ⇒ Search the project using grep; TAB in the resulting buffer to
open files.
+ [[kbd:C-x p S ]] ⇒ Save all project buffers
+ [[kbd:C-x p k ]] ⇒ Kill all buffers relating to the parent project
+ [[kbd:C-x p & ]] ⇒ Runs an async-shell-command in the project's root directory
+ [[kbd:C-x p x s ]] ⇒ Start or visit a shell for the project
+ [[kbd:C-x p r ]] ⇒ Runs interactive query-replace on all files in the projects
+ [[kbd:C-x p e ]] ⇒ Show a list of recently visited files, in the current project
+ [[kbd:C-x p V ]] ⇒ Open a project that has been modified, but not pushed with version control.
#+begin_src emacs-lisp
;; More info & key bindings: https://docs.projectile.mx/projectile/usage.html
(use-package projectile
:config
(projectile-mode +1)
(define-key projectile-mode-map (kbd "C-x p") 'projectile-command-map)
;; Replace usual find-file with a project-wide version :smile:
(global-set-key (kbd "C-x f") #'projectile-find-file)
;; Makes indexing large projects much faster, after first time.
;; Since its caching, some files may be out of sync; you can delete the cache
;; with: C-u C-x f
(setq projectile-enable-caching t))
(use-package projectile
:config
(define-key projectile-mode-map (kbd "C-x p s")
;; I prefer helm-do-grep-ag since it shows me a live search
(lambda () (interactive)
(let ((default-directory (car (projectile-get-project-directories (projectile-acquire-root)))))
;; (shell-command-to-string "echo $PWD")
(helm-do-grep-ag nil))))) ;; “p”roject “s”earch
#+end_src
Let's get the file path of the current file. We bind it and make it a top-level invokable function.
#+begin_src emacs-lisp
(use-package projectile
:defer nil
:config
(define-key projectile-mode-map (kbd "C-x p c")
(defun my/copy-current-file-path ()
"Add current file path to kill ring."
(interactive)
(message (kill-new buffer-file-name)))))
#+end_src
** TODO Projectile
:PROPERTIES:
:CUSTOM_ID: Projectile
:END:
#+begin_src emacs-lisp
;; https://cestlaz.github.io/posts/using-emacs-33-projectile-jump/
;; https://github.com/bbatsov/projectile
(use-package projectile
:config (projectile-global-mode)
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map))
#+end_src
** TODO COMMENT Are there any errors in my code?
:PROPERTIES:
:CUSTOM_ID: Are-there-any-errors-in-my-code
:END:
[[https://www.flycheck.org/en/latest/][Flycheck]] gives us syntax checking and linting tools to automatically check the
contents of buffers while you type, and reports warnings and errors directly in
the buffer, or in an optional error list. Sadly, the default reporting of errors
looks like ~FlyC 3~ in the modeline, but with [[https://github.com/liblit/flycheck-status-emoji][flycheck-status-emoji]] we can see the
status using cute & compact emoji such as ~😱3~.
#+begin_src emacs-lisp
(use-package flycheck-status-emoji
:defer nil
:config
(load-library "flycheck-status-emoji")
;; (diminish-undo 'flycheck-mode)
(flycheck-status-emoji-mode))
#+end_src
Let's also have a nifty modal menu to quickly navigate between errors.
#+begin_src emacs-lisp
(use-package helm-flycheck :defer nil)
(bind-key*
"C-c !"
(defhydra my/flycheck-hydra (:color blue :hint nil)
"Move around flycheck errors and get info about them"
("n" flycheck-next-error "next" :column "Navigation")
("p" flycheck-previous-error "previous")
("f" flycheck-first-error "first")
("l" flycheck-list-errors "list")
("h" helm-flycheck "helm") ;; Jump to an error / see-errors from a nice interactive menu
("e" flycheck-explain-error-at-point "explain" :column "Current errror")
("c" flycheck-copy-errors-as-kill "copy")
("d" flycheck-describe-checker "Describe checker" :column "More")
("s" flycheck-select-checker "Select checker")
("S" flycheck-verify-setup "Suggest setup")
("m" flycheck-manual "manual")))
#+end_src
*** On the fly syntax checking
:PROPERTIES:
:CUSTOM_ID: On-the-fly-syntax-checking
:END:
[[https://www.flycheck.org/en/latest/][Flycheck]] is a on-the-fly syntax checker that relies on external programs to
check buffers; which must be installed separately.
+ E.g., ghc is required for Haskell; whereas Emacs Lisp is checked by Emacs'
own byte compiler, ~emacs-lisp~.
+ Sometimes more than one checking tool applies, use ~C-c ! s~ to select a
different checker.
+ =C-c ! n,p,l= takes you to the ‘n’ext or ‘p’revious
error, or ‘l’ist all errors in another buffer.
~C-c ! c~ to explicitly recheck the buffer.
#+begin_src emacs-lisp
(use-package flycheck
:defer nil
:init (global-flycheck-mode)
:config ;; There may be multiple tools; I have GHC not Stack, so let's avoid that.
(setq-default flycheck-disabled-checkers '(haskell-stack-ghc emacs-lisp-checkdoc))
:custom (flycheck-display-errors-delay .3))
#+end_src
In an org-src block, we press ~C-c '~ to get into the language's mode where
flycheck will provide warnings.
#+begin_src haskell :tangle no
module Main where
main :: IO ()
main = putStrLn $ "nice" ++ f 0
f :: Int -> String
f x = x -- show x
-- type error
#+end_src
In-general, flycheck is intended for self-contained raw code ---not for source
blocks in Org-mode. Whence, the above example is a complete Haskell program,
with a named module and ~main~ method.
I think the built-in [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Flymake.html][flymake]] syntax checker is better for Emacs Lisp,
so let's use that for ELisp.
#+BEGIN_SRC emacs-lisp
(use-package flymake
:defer nil
:hook ((emacs-lisp-mode . (lambda () (flycheck-mode -1)))
(emacs-lisp-mode . flymake-mode))
:bind (:map flymake-mode-map
("C-c ! n" . flymake-goto-next-error)
("C-c ! p" . flymake-goto-prev-error)))
#+END_SRC
Try it out:
#+begin_src emacs-lisp :tangle no
(setq 1 2) ;; Error: ‘1’ is not a variable.
#+end_src
** COMMENT Jumping to definitions & references
:PROPERTIES:
:CUSTOM_ID: Jumping-to-definitions-references
:END:
Out-of-the-box Emacs has ‘xref’ utilities ~M-.~ and ~C-u M-.~ to [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html#Xref][Find Identifier
References]]; however, tags to source definitions need to be generated using the
=etags= program. Nonetheless, the xref utilites are impressive and some just work:
For example, ~M-?~ cleverly finds /all/ references for an identifier in ‘near by’
files; whereas ~C-u M-. RET my/.*~, for example, uses the given regular expression
to list all identifiers with prefix ~my/~, thereby listing my personally defined
names ^_^
| =C-M-. 𝓇𝓮ℊ𝓮𝓍= | Find all identifiers whose name matches the given pattern |
Let's get [[https://github.com/jacktasia/dumb-jump][dumb-jump]], where the ‘dumb’ is possibly due to the fact
that it works by brute-force regular-expression lookup of
pre-defined ‘definitional template’ rules. It “just works” ^_^
#+BEGIN_SRC emacs-lisp
(use-package dumb-jump
:defer nil
:bind (("M-g q" . dumb-jump-quick-look) ;; Show me in a tooltip.
("M-g ." . dumb-jump-go-other-window)
("M-g b" . dumb-jump-back)
("M-g p" . dumb-jump-go-prompt)
("M-g a" . xref-find-apropos)) ;; aka C-M-.
:config
;; If source file is visible, just shift focus to it.
(setq dumb-jump-use-visible-window t))
#+END_SRC
In Lisp, for binding macros, it lists all possible mentions of the bound
variable ---the first is likely what is desired. Alternatively, one could just
add the necessary rule to the variable =dumb-jump-find-rules=. Otherwise, it
works fine even for locally bound definitions. It works depending on the
extension of a file.
** COMMENT Which function are we writing?
:PROPERTIES:
:CUSTOM_ID: Which-function-are-we-writing
:END:
In the modeline, show the name of the function we're currently writing.
#+BEGIN_SRC emacs-lisp
(add-hook 'prog-mode-hook #'which-function-mode)
(add-hook 'org-mode-hook #'which-function-mode)
#+END_SRC
In Org-mode, this places the current heading in the modeline.
In Lisp mode, ensure we always have matching parens.
#+BEGIN_SRC emacs-lisp
(add-hook 'emacs-lisp-mode-hook #'check-parens)
#+END_SRC
** COMMENT Highlight defined Lisp symbols
:PROPERTIES:
:CUSTOM_ID: Highlight-defined-Lisp-symbols
:END:
Usually Emacs only highlights macro names, the [[https://github.com/Fanael/highlight-defined][following]] incantation makes it
highlight all defined names ---as long as we're in Lisp mode, whence in org-src
blocks we use ~C-c '~.
#+BEGIN_SRC emacs-lisp
;; Emacs Lisp specific
(use-package highlight-defined
:defer nil
:hook (emacs-lisp-mode . highlight-defined-mode))
#+END_SRC
Super helpful in making my Emacs configuration: If a name is not highlighted,
then I've misspelled it or it doesn't exist! :smile:
** TODO Aggressive Indentation :Broken_Subsection:
:PROPERTIES:
:CUSTOM_ID: Aggressive-Indentation
:END:
With a single space or tab, my code should always remain indented.
[[https://github.com/Malabarba/aggressive-indent-mode][aggressive-indent-mode]] is a minor mode that keeps your code always indented. It
reindents after every change, making it more reliable than electric-indent-mode.
#+BEGIN_SRC emacs-lisp
;; Always stay indented: Automatically have blocks reindented after every change.
(use-package aggressive-indent
:defer nil
:config (global-aggressive-indent-mode t))
;; Use 4 spaces in places of tabs when indenting.
(setq-default indent-tabs-mode nil)
(setq-default tab-width 4)
#+END_SRC
This mode requires my Lisp forms to be well-balanced; e.g., having a missing
parenthesis does not indent. For instance, I have a form ~F~ and I write ~(when F~
but have not yet enclosed the final parens, I still want nice indentation. So...
*** TODO [[https://github.com/jiahaowork/el-fly-indent-mode.el][Indent Emacs Lisp on the fly]] :Disabled:Breaks_C_c_C_v_C_t:
:PROPERTIES:
:CUSTOM_ID: https-github-com-jiahaowork-el-fly-indent-mode-el-Indent-Emacs-Lisp-on-the-fly
:END:
#+begin_src emacs-lisp :tangle no
;; This minor mode toggles on along with elisp-mode and indents on the fly when
;; you edit the code. No special key strokes needed.
;; Demo: https://www.youtube.com/watch?v=zrFmfFZfj-A&ab_channel=JiahaoLi
(use-package el-fly-indent-mode
:defer nil
:config (add-hook 'emacs-lisp-mode-hook #'el-fly-indent-mode))
#+end_src
** COMMENT Being Generous with Whitespace
:PROPERTIES:
:CUSTOM_ID: Being-Generous-with-Whitespace
:END:
The following minor mode automatically adds spacing around operators.
#+begin_src emacs-lisp
(use-package electric-operator
:defer nil
:hook (c-mode . electric-operator-mode))
#+end_src
I dislike it when users write ~x=y+1~ ---whitespace is free and helpful. ⟨ Also,
languages with arbitrary identifiers, like Lisp and Agda, would accept ~x=y+1~ as
an identifier, not an expression! ⟩
** Coding with a Fruit Salad: Semantic Highlighting
:PROPERTIES:
:CUSTOM_ID: Coding-with-a-Fruit-Salad-Semantic-Highlighting
:END:
What should be highlighted when we write code? Static keywords with fixed uses,
or dynamic user-defined names?
+ /Syntax/ highlighting ⇨ Specific words are highlighted in strong colours so that
the /structure/ can be easily gleaned.
- Generally this only includes a language's keywords, such as ~if, loop, begin,
end, cond~.
- User defined names generally share one colour; usually black.
- Hence, an ~if~ block may be seen as one coloured keyword followed by
a blob of black text.
/Obvious keywords are highlighted while the rest remains in black!/
+ /Semantic/ highlighting ⇨ Identifiers obtain unique colouring.
- This makes it much easier to visually spot dependencies with a quick glance.
+ One can *see* how data flows through a function.
- In dynamic languages, this is a visual form of typing: Different colours are
for different names.
+ Especially helpful for (library) names that are almost the same.
+ This can be accomplished anywhere in Emacs by pressing ~M-s h .~ on
a selected phrase.
For Emacs, [[https://github.com/ankurdave/color-identifiers-mode][Color Identifiers Mode]] gives unique highlighting to identifiers.
- It comes with support for a bunch of languages, and one can add support for others.
- It picks colours adaptively to fit the theme; one uses ~M-x color-identifiers:regenerate-colors~ after a theme change.
#+begin_src emacs-lisp
(use-package color-identifiers-mode
:config (global-color-identifiers-mode))
;; Sometimes just invoke: M-x color-identifiers:refresh
#+END_SRC
When writing a new name, after about ~5 seconds it obtains a colour which is then
propagated immediately to any new occurrences. This timeout before recolouring
is to avoid any lag from multithreading and can be changed by altering the following
line (#64) in the source file, changing the ~5~ to a smaller number.
#+BEGIN_SRC emacs-lisp :tangle no
(run-with-idle-timer 5 t 'color-identifiers:refresh)
#+END_SRC
Here are further reads:
- [[https://medium.com/@evnbr/coding-in-color-3a6db2743a1e][Coding in color: How to make syntax highlighting more useful]] ---an excellent, terse, read
- [[https://zwabel.wordpress.com/2009/01/08/c-ide-evolution-from-syntax-highlighting-to-semantic-highlighting/][C++ IDE Evolution: From Syntax Highlighting to Semantic Highlighting]]
+ Names with a similar prefix share a colour, and class-local items share a colour.
- [[https://wordsandbuttons.online/lexical_differential_highlighting_instead_of_syntax_highlighting.html][Lexical differential highlighting instead of syntax highlighting]]
+ /Ideally, the smaller the lexical difference, the greater the color difference should be./
- [[https://github.com/jacksonrayhamilton/context-coloring][Colouring by Context]] ---an Emacs package
- [[http://www.linusakesson.net/programming/syntaxhighlighting/][A case against syntax highlighting]]
** TODO Text Folding ---Selectively displaying portions of a program :causes_HIDING_ALL_BLOCKS_issue:
:PROPERTIES:
:CUSTOM_ID: Text-Folding
:END:
⟦‼ TODO: hideshowvis shows ="*hideshowvis*"= literally in src code blocks upon
export; as such we need to hook to exports so as to temporarily disable it. ⟧
Literate programming within Org-mode is not always ideal or possible, so we use
a programming mode directly and then may want to have arbitrary ‘sections’ of
text folded up. Let's describe how to accomplish this goal. I've tried the
feature-full folding modes [[https://github.com/gregsexton/origami.el][Origami-mode]] and ~yafolding-mode~, but it seems the
/built-in/ TODO. doc.hs-minor-mode is the best: (0) It folds comments, (1) it's the
fastest, and (2) it Just Worksᵀᴹ out-of-the-box. Coupled with Vimish folding,
for arbitrary region folding; and a helpful hydra, I'm rather happy with my
setup.
On two JavaScript files, I found the following timings (using TODO. doc.elp-instrument-function
and TODO. doc.elp-results):
| Folding function | ~500 lines | ~2300 lines |
|-------------------------+------------+-------------|
| hs-hide-all | 0.00277 | 0.004358 |
| origami-close-all-nodes | 0.00304 | 0.025569 |
| yafolding-hide-all | 7.051795 | 74.252598 |
(TODO: Maybe these timings are due to my config, I should try to reproduce these
with ~emacs -Q~.)
#+begin_box "There's a built-in, less featureful, alternative based on indentation!"
Quickly fold-away code with TODO. doc.set-selective-display; e.g.,
folds away all code indented 4 spaces, whereas is for 8
spaces, and disables the folding. This is built into Emacs.
I've incorporated this into my folding hydra, below.
#+end_box
#+begin_box "Vimish fold - Fold regions based on selection, not syntax"
Sometimes we want to fold some random piece of text ---rather than fold accoding
to a programming language's syntactic constructions.
[[https://github.com/mrkkrp/vimish-fold][Vimish-fold]] gives us just that and with many fancy features, from the README:
+ folding of active regions;
+ good visual feedback: it's obvious which part of text is folded with a ‘⋮’ in the fringe.
+ create folds from regions between ~{{{~ and ~}}}~ automatically (marks are customizable; TODO. doc.vimish-fold-from-marks);
+ persistence by default: when you kill a buffer your folds don't disappear;
+ persistence scales well, you can work on hundreds of files with lots of folds without adverse effects;
+ it does not break indentation;
+ folds can be toggled from folded state to unfolded and back very easily;
+ quick navigation between existing folds;
+ you can use mouse to unfold folds (good for beginners and not only for them).
#+begin_src emacs-lisp
(use-package vimish-fold
:config (vimish-fold-global-mode 1))
#+end_src
#+end_box
*** TODO Actual Setup :ignore:
:PROPERTIES:
:CUSTOM_ID: Actual-Setup
:END:
--------------------------------------------------------------------------------
TODO: Below I setup hideshow along with [doc : hideshowvis-symbols] [hideshowvis] which gives us a nice clickable
“+/-” marker for foldable blocks as well as an overlay that indicates how many
lines are folded away. For more on hideshow-mode, see the [[https://writequit.org/denver-emacs/presentations/2017-11-02-hidden-gems.html][Hidden Gem Packages]]
presentation which contains a small self-contained introduction, or [[https://github.com/emacs-mirror/emacs/blob/master/lisp/progmodes/hideshow.el#L127][these super useful source comments]]
which discuss hooks and support for special modes ([[https://superuser.com/questions/576447/enable-hideshow-for-more-modes-e-g-ruby][like this one]]).
#+BEGIN_SRC emacs-lisp
(use-package hideshow
:defer nil
:init
;; https://github.com/emacsmirror/emacswiki.org/blob/master/hideshowvis.el
(quelpa '(hideshowvis :fetcher wiki))
;; Press “C-c TAB” to toggle a block's visibility or “C-c f” for my folding hydra.
:bind (("C-c TAB" . hs-toggle-hiding))
;; https://github.com/shanecelis/hideshow-org/tree/master
;; This extension bring Org-mode tab behaviour to folding, at the block level
;; and buffer level ---but not cycling visibility.
;; (use-package hideshow-org) ;; Disabled as commented below.
:hook ((prog-mode . (lambda () (hs-minor-mode +1)
(hideshowvis-minor-mode t)
(hideshowvis-symbols)
;; This hook along with hs-org mode breaks editing of src blocks in Org files.
;; That's OK, since my folding hydra does a better job for my needs.
;; (hs-org/minor-mode t)
(hs-hide-all)))))
#+END_SRC
Along with a hydra for super quick navigation and easily folding, unfolding
blocks! Love this one (•̀ᴗ•́)و
#+BEGIN_SRC emacs-lisp
(my/defhydra "C-c f" "Folding text" archive
:Current
("h" hs-hide-block "Hide")
("s" hs-show-block "Show")
("t" hs-toggle-hiding "Toggle")
;; "l" hs-hide-level "Hide blocks n levels below this block"; TODO: Enable folding feature
:Buffer
("H" hs-hide-all "Hide")
("S" hs-show-all "Show")
("T" my/hs-toggle-buffer "Toggle")
:Style
("i" my/clever-selective-display "Fold along current indentation" :toggle selective-display)
("e" auto-set-selective-display-mode "Explore; walk and see" :toggle t)
:Region
("f" (lambda () (interactive) (vimish-fold-toggle) (vimish-fold (region-beginning) (region-end))) "Fold/Toggle")
("d" vimish-fold-delete "Delete fold")
("U" vimish-fold-unfold-all "Unfold all")
("D" vimish-fold-delete-all "Delete all")
("n" vimish-fold-next-fold "Next fold")
("p" vimish-fold-previous-fold "Previous fold")
:...
("w" hl-todo-occur "Show WIPs/TODOs" :exit t)
("m" lsp-ui-imenu "Menu of TLIs" :exit t) ;; TLI ≈ Top Level Items
;; ("i" imenu-list "iMenu (General)") ;; It seems the above is enough for both prog and otherwise.
("r" (progn (hs-minor-mode -1) (hs-minor-mode +1)) "Reset Hideshow") ;; Remove all folds from the buffer and reset all hideshow-mode. Useful if it messes up!
("q" nil "Quit" :color blue))
;; Features from origami/yafolding that maybe I'd like to implement include:
;; narrowing to block or folding everything except block, navigating back and forth between folded blocks.
;; Finally, if we want to cycle the visibility of a block (as in Org-mode), we can use a combination of hs-show-block and hs-hide-level.
#+END_SRC
#+begin_details "Folding Hydra Helpers"
#+BEGIN_SRC emacs-lisp
(defvar my/hs-hide nil "Current state of hideshow for toggling all.")
(defun my/hs-toggle-buffer () "Toggle hideshow all."
(interactive)
(setq my/hs-hide (not my/hs-hide))
(if my/hs-hide
(hs-hide-all)
(hs-show-all)))
#+END_SRC
#+BEGIN_SRC emacs-lisp
(defun my/clever-selective-display (&optional level)
"Fold text indented same of more than the cursor.
This function toggles folding according to the level of
indentation at point. It's convenient not having to specify a
number nor move point to the desired column.
"
(interactive "P")
(if (eq selective-display (1+ (current-column)))
(set-selective-display 0)
(set-selective-display (or level (1+ (current-column))))))
#+END_SRC
#+BEGIN_SRC emacs-lisp
;; Src: https://emacs.stackexchange.com/questions/52588/dynamically-hide-lines-indented-more-than-current-line
(define-minor-mode auto-set-selective-display-mode
"Automatically apply `set-selective-display' at all times based on current indentation."
nil "$" nil
(if auto-set-selective-display-mode
(add-hook 'post-command-hook #'auto-set-selective-display nil t)
(remove-hook 'post-command-hook #'auto-set-selective-display t)
(with-temp-message ""
(set-selective-display nil))))
;;
(defun auto-set-selective-display ()
"Apply `set-selective-display' such that current and next line are visible.
Scroll events are excluded in order to prevent wild flickering while navigating."
(unless (eq last-command #'mwheel-scroll)
(let*((this-line-indent (current-indentation))
(next-line-indent (save-excursion (forward-line) (current-indentation))))
(with-temp-message "" ; Suppress messages.
(set-selective-display (1+ (max this-line-indent next-line-indent)))))))
#+END_SRC
#+end_details
With expected support for searching.
#+BEGIN_SRC emacs-lisp
;; Open folded nodes if a search stops there.
(add-hook 'helm-swoop-after-goto-line-action-hook #'my/search-hook-function)
(defun my/search-hook-function ()
(when hs-minor-mode (set-mark-command nil) (hs-show-block) (pop-to-mark-command)))
#+END_SRC
#+begin_details "What if I want my own hideshow overlays, instead of hideshowvis?"
#+BEGIN_SRC emacs-lisp :tangle no
;; Add an overlay to display the number of hidden lines 😁;; https://github.com/shanecelis/hideshow-org/tree/master
(setq hs-set-up-overlay
(defun my-display-code-line-counts (ov)
(when (eq 'code (overlay-get ov 'hs))
(overlay-put ov 'display
(propertize
(format " ... ﴾%d﴿"
(count-lines (overlay-start ov)
(overlay-end ov)))
'face 'font-lock-type-face)))))
#+END_SRC
#+end_details
#+begin_details "[Disabled / Alternative] origami"
#+BEGIN_SRC emacs-lisp :tangle no
(use-package origami
;; In Lisp languages, by default only function definitions are folded.
;; :hook ((agda2-mode lisp-mode c-mode) . origami-mode)
;; Please open any code with top level items folded away.
:hook (prog-mode . (lambda () (interactive)
(origami-close-all-nodes (current-buffer))))
;; MA: It seems that this is not ideal; it takes a bit longer than I'd like to fold the whole file.
:config
;; For any major-mode that doesn't have explicit support, origami will use the
;; indentation of the buffer to determine folds.
(global-origami-mode)
;; With basic support for one of my languages.
(push '(agda2-mode . (origami-markers-parser "{-" "-}"))
origami-parser-alist))
#+END_SRC
With expected support for searching.
#+BEGIN_SRC emacs-lisp :tangle no
(defun my/search-hook-function ()
(when origami-mode (origami-open-node-recursively (current-buffer) (point))))
;; Open folded nodes if a search stops there.
(add-hook 'helm-swoop-after-goto-line-action-hook #'my/search-hook-function)
;;
;; Likewise for incremental search, isearch, users.
;; (add-hook 'isearch-mode-end-hook #'my/search-hook-function)
#+END_SRC
And hydra...
#+BEGIN_SRC emacs-lisp :tangle no
(my/defhydra "C-c f" "Folding text" archive
:Current
("h" origami-close-node-recursively "Hide")
("s" origami-open-node-recursively "Show")
("c" origami-recursively-toggle-node "Cycle") ;; Acts like org-mode header collapsing. Cycle a fold between open, recursively open, closed.
("f" origami-show-only-node "Focus") ;; Close everything but the folds necessary to see the point. Very useful for concentrating on an area of code.
;; ("H" origami-close-all-nodes "Hide All")
;; ("S" origami-open-all-nodes "Show All")
:Navigate
("n" origami-next-fold "Next")
("p" origami-previous-fold "Previous")
:...
("t" origami-toggle-all-nodes "Toggle buffer")
("m" lsp-ui-imenu "Menu of TLIs" :exit t) ;; TLI ≈ Top Level Items
;; ("i" imenu-list "iMenu (General)") ;; It seems the above is enough for both prog and otherwise.
("r" origami-reset)) ;; Remove all folds from the buffer and reset all origami state. Useful if origami messes up!
#+END_SRC
# *Disabled:* I've looked at a few folding modes, and I like this one.
# However, I seldom need it.
#+end_details
#+begin_details "[Disabled / Alternative] yafolding"
I found using yafolding-mode to be way too slow.
#+begin_src emacs-lisp :tangle no
;; “Yet Another Folding” just works: Indented elements are folded away; no setup required.
;; (use-package discover)
(use-package yafolding
;; Please open any code with top level items folded away:
;; Open the file super quick, but when I'm inactive for 5 seconds,
;; then I'm probably doing other stuff so do the folding then.
;; :hook prog-mode . (lambda () (interactive)
;; (run-with-idle-timer 5 nil #'yafolding-hide-all))
;; MA: It seems that this is not ideal; it takes a bit longer than I'd like to fold the whole file.
)
(defhydra yafolding-hydra (:color pink :columns 3)
"Fold code based on indentation levels"
;; First row
("s" yafolding-show-element "show element")
("S" yafolding-show-all "show all")
("" (lambda () (interactive)
(let ((next (car (yafolding-get-overlays (point) (point-max)))) pos)
(if (not next) (message "No more folded regions")
(setq pos (overlay-start next))
(yafolding-hide-element)
(goto-char pos)
(yafolding-show-element))))
"forward element")
;; Second row
("h" yafolding-hide-element "hide element")
("H" yafolding-hide-all "hide all")
("" (lambda () (interactive)
(let ((previous (car (yafolding-get-overlays (point-min) (point)))) pos)
(if (not previous) (message "No more folded regions")
(setq pos (overlay-start previous))
(yafolding-hide-element)
(goto-char pos)
(yafolding-show-element))))
"backward element")
;; Third row
("SPC" yafolding-toggle-element "toggle element")
("T" yafolding-toggle-all "toggle all")
("q" nil "quit" :color red)
("p" yafolding-hide-parent-element "hide parent")
("" (lambda () (interactive) (or (ignore-errors (yafolding-go-parent-element))
(message "Already at the top level.")))
"go to parent")
("r" (lambda () (interactive) (yafolding-hide-region (region-beginning) (region-end)))
"hide region"
))
(global-set-key (kbd "s-f") 'yafolding-hydra/body)
#+end_src
#+end_details
*** E2E Test :ignore:
:PROPERTIES:
:CUSTOM_ID: E2E-Test
:END:
#+begin_details Test
#+begin_src emacs-lisp :tangle init-test.el
(ert-deftest hideshow-is-enabled-and-folds-by-default ()
:tags '(hideshow)
;; Make a temporary scratch.js file with the given contents.
(let* ((contents "function fierce(name) { \n return `${name}: ROAR` \n }")
(scratch.js (make-temp-file "scratch" nil ".js" contents)))
;; Hideshow is enabled whenever we open a code file
(find-file scratch.js)
(should hs-minor-mode)
;; Function definition is a hidden block
(end-of-line)
(backward-char 2)
(should (hs-already-hidden-p))
;; Indeed, the hidden block starts at the first line break and ends just after the second.
(-let [ov (hs-already-hidden-p)]
(-let [(first\n second\n) (-elem-indices "\n" (s-split "" contents))]
(should (equal (overlay-start ov) first\n)) ;; ≈ 25
(should (equal (overlay-end ov) (+ second\n 2))))) ;; ≈ 52
(kill-buffer)))
#+end_src
#+end_details
** COMMENT Jump between windows using Cmd+Arrow & between recent buffers with Meta-Tab :relocate:
:PROPERTIES:
:CUSTOM_ID: Jump-between-windows-using-Cmd-Arrow-between-recent-buffers-with-Meta-Tab
:END:
We can use ~C-x o~ to switch to the ‘o’ther window, and ~C-u 𝓃 C-x o~ to switch to
the 𝓃-th next clockwise window, but using ~s-↑,↓,←,→~ may be faster.
#+BEGIN_SRC emacs-lisp
(use-package windmove
:defer nil
:config ;; use command key on Mac
(windmove-default-keybindings 'super)
;; wrap around at edges
(setq windmove-wrap-around t))
#+END_SRC
The [[https://github.com/killdash9/buffer-flip.el][docs]], for the following, have usage examples.
#+BEGIN_SRC emacs-lisp
(use-package buffer-flip
:defer nil
:bind
(:map buffer-flip-map
("M-" . buffer-flip-forward)
("M-S-" . buffer-flip-backward)
("C-g" . buffer-flip-abort))
:config
(setq buffer-flip-skip-patterns
'("^\\*helm\\b")))
;; key to begin cycling buffers.
(global-set-key (kbd "M-") 'buffer-flip)
#+END_SRC
See [[https://www.emacswiki.org/emacs/buffer-move.el][buffer-move]] if you're interested in moving the buffers, and their windows,
into new configurations.
** hr: [[https://github.com/LuRsT/hr][A horizontal for your terminal]] :relocate:
:PROPERTIES:
:CUSTOM_ID: hr-https-github-com-LuRsT-hr-A-horizontal-for-your-terminal
:END:
When working in the terminal, at least in my day job, it can be helpful to
visually segregate large chunks of output. With the ~hr~ command, I can run ~hr
'output5`~, for example, to have the same the string /output5/ repeated horizontal
across one line of my terminal. We can also just run ~hr~ which is the same as ~hr
'#'~. Finally, you can also run =hr '-#-' '-' '-#-'= to have 3 horizontal lines and
more generally =hr p₁ p₂ … pₙ= will produce /n/-many horizontal lines with the
$i^{th}$-line having pattern =pᵢ=.
#+begin_src emacs-lisp
(system-packages-ensure "hr") ;; ≈ brew install hr
#+end_src
** COMMENT Browse remote files
:PROPERTIES:
:CUSTOM_ID: Browse-remote-files
:END:
Sometimes you want to see the current file in Github; e.g., you select a
region and press ~M-x browse-at-remote-kill~ to get the URL for that region in
Github then you can send that URL to your peers when referencing something.
- Or just ~M-x browse-at-remote~ to see it in Github.
- [[https://github.com/rmuslimov/browse-at-remote][browse-at-remote: Browse target page on github/bitbucket from emacs buffers]].
#+begin_src emacs-lisp
;; Usage: [Optionally select a region then] M-x browse-at-remote[-kill]
(use-package browse-at-remote :defer nil)
#+end_src
** COMMENT [[https://github.com/sshaw/copy-as-format][copy-as-format:]] Emacs function to copy buffer locations as GitHub/Slack/JIRA etc... formatted code.
:PROPERTIES:
:CUSTOM_ID: https-github-com-sshaw-copy-as-format-copy-as-format-Emacs-function-to-copy-buffer-locations-as-GitHub-Slack-JIRA-etc-formatted-code
:END:
#+begin_src emacs-lisp
;; Usage: [C-u] M-x copy-as-format ⇒ Copies selected region, or current line.
;; Also use: copy-as-format-𝒮, to format to a particular 𝒮tyle.
;; Without suffix 𝒮, format defaults to `copy-as-format-default`.
;; With a prefix argument prompt for the format style 𝒮.
;; Easy to add more formats.
(use-package copy-as-format :defer nil)
#+end_src
** w-screencapture
:PROPERTIES:
:CUSTOM_ID: w-screencapture
:END:
#+begin_src emacs-lisp
(bind-key "C-c s"
(cl-defun w-screencapture ()
"Interactively capture screen and save to clipboard; then paste in Slack, etc, with ⌘-c.
After we run this command, we can swipe up on mousepad to select different desktops, then
click & drag to select portition of screen to capture.
Captured screen is NOT saved to disk, only copied to clipboard.
In MacOs,
+ Command + Shift + 5 ⇒ Select screen record
+ Command + Shift + 4 ⇒ Selection Screenshot
+ Command + Shift + 3 ⇒ Screenshot
See: https://osxdaily.com/2011/08/11/take-screen-shots-terminal-mac-os-x"
(interactive)
(async-shell-command "screencapture -i -c")))
(cl-defun w-delete-all-screenshots ()
"Delete all “Screen Shot ⋯” files in ~/Desktop."
(interactive)
(thread-last (shell-command-to-string "cd ~/Desktop; ls")
(s-split "\n")
(--filter (s-starts-with-p "Screen Shot" it))
(--map (f-delete (format "~/Desktop/%s" it)))))
#+end_src
** COMMENT Screencapturing the Current Emacs Frame
:PROPERTIES:
:CUSTOM_ID: Screencapturing-the-Current-Emacs-Frame
:END:
Sometimes an image can be tremendously convincing, or at least sufficiently
inviting. The following incantation is written for MacOS and uses it's native
=screencapture= utility, as well as =magick=.
#+BEGIN_SRC emacs-lisp
(defun my/capture-emacs-frame (&optional prefix output)
"Insert a link to a screenshot of the current Emacs frame.
Unless the name of the OUTPUT file is provided, read it from the
user. If PREFIX is provided, let the user select a portion of the screen."
(interactive "p")
(defvar my/emacs-window-id
(s-collapse-whitespace (shell-command-to-string "osascript -e 'tell app \"Emacs\" to id of window 1'"))
"The window ID of the current Emacs frame.
Takes a second to compute, whence a defvar.")
(let* ((screen (if prefix "-i" (concat "-l" my/emacs-window-id)))
(temp (format "emacs_temp_%s.png" (random)))
(default (format-time-string "emacs-%m-%d-%Y-%H:%M:%S.png")))
;; Get output file name
(unless output
(setq output (read-string (format "Emacs screenshot filename (%s): " default)))
(when (s-blank-p output) (setq output default)))
;; Clear minibuffer before capturing screen or prompt user
(message (if prefix "Please select region for capture …" "♥‿♥"))
;; Capture current screen and resize
(thread-first
(format "screencapture -T 2 %s %s" screen temp)
(concat "; magick convert -resize 60% " temp " " output)
(shell-command))
(f-delete temp)
;; Insert a link to the image and reload inline images.
(insert (concat "[[file:" output "]]")))
(org-display-inline-images nil t))
(bind-key* "C-c M-s" #'my/capture-emacs-frame)
#+END_SRC
Why this way? On MacOS, ImageMagick's =import= doesn't seem to work ---not at all
for me! Also, I dislike how large the resulting image is. As such, I'm using
MacOS's =screencapture= utility, which in-turn requires me to somehow obtain frame
IDs. Hence, the amount of work needed to make this happen on my system was most
simple if I just wrote it out myself rather than tweaking an existing system.
+ ~C-c C-x C-v~ ⇒ Toggle inline images!
** Comment-boxes up to the fill-column ---or banner instead?
:PROPERTIES:
:CUSTOM_ID: Comment-boxes-up-to-the-fill-column
:END:
GIF: https://endlessparentheses.com/images/comment-box.gif
#+begin_src emacs-lisp
(defun my/comment-box (b e)
"Draw a box comment around the region but arrange for the region
to extend to at least the fill column. Place the point after the
comment box.
Source: http://irreal.org/blog/?p=374
To do fancy stuff like removing boxes, centering them, etc
see https://github.com/lewang/rebox2/blob/master/rebox2.el"
(interactive "r")
(let ((e (copy-marker e t)))
(goto-char b)
(end-of-line)
(insert-char ? (- fill-column (current-column)))
(comment-box b e 1)
(goto-char e)
(set-marker e nil)))
#+end_src
A comment box sometimes increases the size of a file more than I'd like, or more than others on my dev team would like.
As such, let's try [[https://github.com/WJCFerguson/banner-comment][banner comments]]:
- GIF: https://github.com/WJCFerguson/banner-comment/blob/35d3315683d3f97605207691b77e9f447af18fe2/demo.png
#+begin_src emacs-lisp
(use-package banner-comment :defer nil)
#+end_src
Pretty slick!
** TODO COMMENT Auto-format on Save :Reenabled:Should_be_Disabled:Breaks_HTML_export_of_org_files_with_unicode_or_emojis:
:PROPERTIES:
:CUSTOM_ID: Auto-format-on-Save
:END:
[[https://github.com/lassik/emacs-format-all-the-code/tree/eb2a7fa6da15d23b57921218a36ac67d523e81f1][Auto-format source code in many languages with one command]]
Let's auto-format source code in many languages using the same command for all
languages, instead of learning a different Emacs package and formatting command
for each language.
Just do ~M-x format-all-buffer~ and it will try its best to do the right thing. To
auto-format code on save, use the minor mode format-all-mode. Better yet, we ask
for it to do so “on save”.
- You will need to install external programs to do the formatting. If
~format-all-buffer~ can't find the right program, it will try to tell you how to
install it.
- An alternative Emacs tool is [[https://github.com/radian-software/apheleia][apheleia: 🌷 Run code formatter on buffer
contents without moving point, using RCS patches and dynamic programming.]]
#+begin_src emacs-lisp
(use-package format-all
:defer nil
;; To enable format on save for most programming language buffers:
:hook (prog-mode . format-all-mode)
:config
;; Please use the default formatters; I don't care too much.
(add-hook 'format-all-mode-hook 'format-all-ensure-formatter))
#+end_src
[[https://prettier.io/docs/en/index.html][Prettier]] is an opinionated code formatter for numerous web related languages,
including JS, TS, HTML, CSS, JSON, Vue, Markdown, and YAML.
#+begin_src emacs-lisp
;; For JavaScript prettification: It automatically inserts semicolons, forces newlines, inserts parens, etc.
;; Lots of redundant stuff, but stuff to make it easy to work with others.
(shell-command "npm install --global prettier")
;; Specific package to do only JS prettification: https://github.com/prettier/prettier-emacs
#+end_src
For example, in a NodeJS app make a file ~.prettierrc.json~ whose contents are
#+begin_src json :tangle no
{
"singleQuote": true,
"arrowParens": "avoid",
"printWidth": 120,
"semi": false,
"trailingComma": "none"
}
#+end_src
Unfortunately, my current team prefers ~"semi": true~ ---which is understandable
for people not familar with how JavaScript does [[https://www.freecodecamp.org/news/lets-talk-about-semicolons-in-javascript-f1fe08ab4e53/][semicolon insertion]].
( If you're having trouble getting prettier to work on save, consider using this
[[https://github.com/codesuki/add-node-modules-path][package]] which detects your node modules' path. )
Anyhow, with these rules:
- I write =const f = (x) => "x" == x= then on save it becomes =const f = x => 'x' == x;=
- I write =let xs = [1, 2, 3,]= then on save it becomes =let xs = [1, 2, 3];=
- I write =foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());=
then nothing happens on save; but if you add one more argument, =, 12=, then it gets reformatted with each arg on one line.
Notice that in the first example above, only minor syntactic changes were made;
nothing altering semantics or quality of code ---for that, we use a /linter/.
In particular, [[https://emacs-lsp.github.io/lsp-mode/page/lsp-eslint/][LSP ESLint]] when activated will show us two errors: It's almost always
better to use ~===~ instead of ~==~ and literals should be on the right side of the equality.
We can use ~M-x lsp-execute-code-action~ to get a list of actions that can be performed to fix this /quality/ problem.
** Searching Hydra
:PROPERTIES:
:CUSTOM_ID: Searching-Hydra
:END:
#+begin_src emacs-lisp
(my/defhydra "s-f" "\t\tLocate Everything" search
:Buffer
;; find all the occurrences of a string, pull out the lines containing the string to another buffer where [F2] I can edit and save,
("e" helm-swoop "Editable")
;; Implicit Regex, colourful
("c" swiper "Classic")
:Project
;; “:toggle ℰ”: ℰ is a Boolean expression that is evaluated to tell us whether the state is on-or-off
("t" (lambda () (interactive)) "Ignore specs/jsons"
:toggle (let* ((with-hole "ag %s --line-numbers -S --color --nogroup %%s %%s %%s") ;; ≈ original value of ‘helm-grep-ag-command’
(ignores "--ignore=\"*spec.js\" --ignore=\"*.json\" --ignore=\"*.json5\"")
(on (equal helm-grep-ag-command (format with-hole ignores))))
(if on (progn (setq helm-grep-ag-command (format with-hole "")) nil) ;; ≈ turn off the toggle
(setq helm-grep-ag-command (format with-hole ignores)))))
("f" (lambda () (interactive) (helm-do-grep-ag t)) "File type")
("d" (lambda () (interactive) (-let [default-directory (read-directory-name "Where do you want to search? ")] (helm-do-grep-ag nil))) "Directory")
("D" (lambda () (interactive) (-let [default-directory (read-directory-name "Where do you want to search? ")] (helm-do-grep-ag t))) "Directory & type"))
#+end_src
** TODO ⌘-e: Edit Everything in a separate buffer
:PROPERTIES:
:CUSTOM_ID: e-Edit-Everything-in-a-separate-buffer
:END:
Edit comment/string/docstring/code block in separate buffer with your favourite
mode.
+ ⌘-e to toggle “e”diting of thing at point.
+ ⌘-e will try to edit thing at point, or selection, if possible; otherwise it
will exit edit session.
- 🔥 Avoid escape nightmares by editing strings in a separate buffer.
- On a string, press ⌘-e and a new buffer pops up with unescaped content,
letting you edit raw strings directly. It then takes care of automatically
escaping strings for you when you press ⌘-e, or ~C-c C-c~ ---or discard your
changes with ~C-c C-k~.
+ ⌘-e can be used within edit session to create new edit sessions, if possible; then ⌘-e will “pop-off-the-stack” as expected.
- (I already use ⌘-e to toggle editing Org src blocks, and when editing a block ⌘-e will try to do a recursive edit if possible, or exit the edit session.)
- (The separedit package also let's me press ⌘-e to edit variable values when describing them, and to edit text when in the minibuffer.)
From [[https://github.com/twlz0ne/separedit.el][source]]:
#+begin_example org
+----------+ Edit +-----------+ Edit +-----------+
| | ---------------------> | edit | ---------------------> | edit | ...
| | point-at-comment? | buffer | point-at-comment? | buffer |
| source | point-at-string? | | point-at-string? | | ...
| buffer | point-at-codeblock? | (markdown | point-at-codeblock? | (markdown | ...
| | point-at-...? | orgmode | point-at-...? | orgmode |
| | <--------------------- | ...) | <--------------------- | ...) | ...
+----------+ Commit changes +-----------+ Commit changes +-----------+
#+end_example
[In-general, we can invoke [[https://github.com/Fanael/edit-indirect/blob/e3d86416bcf8ddca951d7d112e57ad30c5f9a081/edit-indirect.el#L124][M-x edit-indirect-region]] to edit any selected piece
of text in its own buffer, then ~C-c C-c~ (or ~⌘-e~ with my setup) to commit the
edit. Actually, I've altered by ~⌘-e~ setup to also account for a selected region
😉]
#+begin_src emacs-lisp
(use-package separedit :defer nil)
;;
;; # Example Usage
;;
;; 1. Press ⌘-e on this line, to edit this entire comment.
;; 2. Press ⌘-e to exit the edit session.
;;
;; Since my ⌘-e is context sensitive, to determine whether to continue editing or
;; exit; you can explicitly request an edit with C-c ' and an exit with C-c C-c.
;;
;; ```
;; ;; 3. Press ⌘-e on this line, to edit this source block!
;; ;; 4. Press ⌘-e on this line, to edit this inner-most comment!
;; ;; 5. At start of next line, press “⌘-r ⌘-e” to edit just the source block
;; ;;
;; (cl-defun index (&rest args)
;; "6. Press ⌘-e to edit this string, \"7. and again in these quotes\""
;; "8. Press ⌘-e to edit this HTML block, in Web-mode
")
;;
;; ;; 9. Press C-u ⌘-e to guess the language of the next string (Rust); then ⌘-r C-c C-r to quickly run the code.
;; "fn main() { println!(\"{}\", \"hello!\"); }"
;;
;; ;; 10. Select & press “C-u ⌘-e” on the following, to edit it in whatever mode you want.
;; ;; select * from table -- Or just press ⌘-e and have the mode detected.
;;
;; ```
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Setup to make the above ⌘-e behaviour happen.
;; Make “⌘-e” toggle editing string literals / select region / [Org/markdown] code block / comment block when programming.
(--map (bind-key "s-e" #'separedit it)
'(prog-mode-map minibuffer-local-map help-mode-map)) ;; TODO: helpful-mode-map
#+end_src
#+begin_src emacs-lisp
;; TODO:Merge these changes upstream
;; I'm focusing on a specific region to edit, so let's not be distracted by anything else.
;; This makes the “editing stack” feel like a stack, with ⌘-e pushing new editing session buffers,
;; and C-c C-c, or ⌘-e on non-editable lines, to pop-off the stack.
;; (advice-add #'separedit :after (lambda (&rest _) (delete-other-windows)))
;;
;; NOTE: This actually breaks the stack nature of popping with ⌘-e; we need to actually save the stack via some list of buffers than push/pop buffers on that variable.
;; I don't want to be bothered for what mode I'm in, when a region is selected using current major mode.
;; I'll use a prefix, “C-u ⌘-e”, if I want to select a mode for my current selected text.
(advice-add #'separedit--select-mode :before-until
(lambda (&rest _)
(when (and (not current-prefix-arg) (region-active-p)) (pp-to-string major-mode))))
;; Also: When on a string ∷
(advice-add #'separedit--select-mode :before-until
(lambda (&rest _)
"When on a string ∷
+ ⌘-e ⇒ Edit string at point
+ C-u ⌘-e ⇒ Auto-detect my string's major mode
+ C-u C-u ⌘-e ⇒ Let me select a major mode"
(-let [str? (ignore-errors (thing-at-point 'string))]
(case (car current-prefix-arg)
(4 (when str? (pp-to-string (my/detect-prog-mode str?))))
(_ nil)))))
;; NOTE: By default, separedit provides colouring for 'strings', "strings", and `strings'
;; This doesn't look very good when I have a single quote within double quotes:
;; In an Emacs Lisp buffer, editing the string "Bob's Work" gives unexpected highlighting.
;; ```
;; (advice-add #'separedit :after
;; (lambda (&rest _)
;; (when (s-ends-with? "string-mode" (pp-to-string major-mode))
;; (text-mode))))
;; ```
#+end_src
#+begin_src emacs-lisp
;; In the indirect buffer, make ⌘-e finish editing.
(use-package edit-indirect
:config (bind-key "s-e"
(lambda ()
(interactive)
(or (ignore-errors (call-interactively #'separedit))
(call-interactively #'edit-indirect-commit)))
#'edit-indirect-mode-map))
;; I also have “s-e” bound to `org-edit-src-exit'.
(advice-add 'org-edit-src-exit :before-until
(lambda (&rest r)
(when (ignore-errors (separedit)) t)))
#+end_src
#+begin_src emacs-lisp
;; → ⌘-e on an Org paragraph pops-up an edit session in Org mode.
;; → ⌘-e on a selection in Org mode pops-up an edit session in Org mode.
;; TODO: Consider forming an alist for special blocks to refer to their preferred
;; edit mode, defaulting to Org-mode? Perhaps something to consider /after/
;; addressing the bug below.
;; (advice-unadvice 'org-edit-special) MA: TODO: FIXME: Delete this?
(advice-add 'org-edit-special :around
(lambda (orginal-function &rest r)
(cond
((region-active-p) (call-interactively #'edit-indirect-region) (org-mode))
((equal 'paragraph (car (org-element-at-point)))
(mark-paragraph) (call-interactively #'edit-indirect-region) (org-mode))
(t (or (ignore-errors (apply orginal-function r))
;; We try to edit a special block when orginal-function fails.
;; This way src blocks are not confused with the more generic idea of special blocks.
(when
(my/org-in-any-block-p)
;; Note using org-element-at-point doesn't work well with special blocks when you're somewhere within the block.
;; It only works correctly when you're on the boundary of the special block; which is not ideal.
;; This is why I'm not using: (org-element-property :begin elem).
(-let [(start . end) (my/org-in-any-block-p)]
(set-mark-command start)
(goto-char end) (previous-line 2) (end-of-line) ;; FIXME: Still shows #+end_XXX for some reason.
(call-interactively #'edit-indirect-region) (org-mode))))))))
#+end_src
#+begin_src emacs-lisp
;; where...
(defun my/org-in-any-block-p ()
"Return non-nil if the point is in any Org block.
The Org block can be *any*: src, example, verse, etc., even any
Org Special block.
This function is heavily adapted from `org-between-regexps-p'.
Src: https://scripter.co/splitting-an-org-block-into-two/"
(save-match-data
(let ((pos (point))
(case-fold-search t)
(block-begin-re "^[[:blank:]]*#\\+begin_\\(?1:.+?\\)\\(?: .*\\)*$")
(limit-up (save-excursion (outline-previous-heading)))
(limit-down (save-excursion (outline-next-heading)))
beg end)
(save-excursion
;; Point is on a block when on BLOCK-BEGIN-RE or if
;; BLOCK-BEGIN-RE can be found before it...
(and (or (org-in-regexp block-begin-re)
(re-search-backward block-begin-re limit-up :noerror))
(setq beg (match-beginning 0))
;; ... and BLOCK-END-RE after it...
(let ((block-end-re (concat "^[[:blank:]]*#\\+end_"
(match-string-no-properties 1)
"\\( .*\\)*$")))
(goto-char (match-end 0))
(re-search-forward block-end-re limit-down :noerror))
(> (setq end (match-end 0)) pos)
;; ... without another BLOCK-BEGIN-RE in-between.
(goto-char (match-beginning 0))
(not (re-search-backward block-begin-re (1+ beg) :noerror))
;; Return value.
(cons beg end))))))
#+end_src
I'd like to [[https://github.com/andreasjansson/language-detection.el][guess the language]] I'm in, when working with strings.
#+begin_src emacs-lisp
(use-package language-detection :defer nil)
;; Usage: M-x language-detection-buffer ⇒ Get programming language of current buffer
;; Also, (language-detection-string "select * from t") ;; ⇒ sql
;; TODO: Push this upstream; https://github.com/andreasjansson/language-detection.el/issues/1
(cl-defun my/detect-prog-mode (&optional string)
"Guess programming mode of the current buffer, or STRING if it is provided.
When called interactively, it enables the mode;
from Lisp it just returns the name of the associated mode.
;; Example Lisp usage
(call-interactively #'my/detect-prog-mode)
`language-detection-buffer' returns a string which is not always the name of the
associated major mode; that's what we aim to do here."
(interactive)
(defvar my/detect-prog-mode/special-names
'((c . c-mode)
(cpp . c++-mode)
(emacslisp . emacs-lisp-mode)
(html . web-mode) ;; I intentionally want to use this alternative.
(matlab . octave-mode)
(shell . shell-script-mode)
(visualbasic . visual-basic-mode)
(xml . sgml-mode))
"Names in this alist map a language to its mode; all other languages 𝒳 have mode ‘𝒳-mode’ afaik.")
(let* ((lang (if string (language-detection-string string) (language-detection-buffer)))
(mode (or (cdr (assoc lang my/detect-prog-mode/special-names))
(intern (format "%s-mode" lang)))))
(if (called-interactively-p 'any)
(progn (call-interactively mode) (message "%s enabled!" mode))
mode)))
#+end_src
+ ⌘-e to edit an Org table cell; see [[https://orgmode.org/manual/Built_002din-Table-Editor.html][here]] for built-in table editing commands.
#+begin_src emacs-lisp
(advice-add #'org-edit-special :before-until
(lambda (&rest r)
(when (equal 'table-row (car (org-element-at-point)))
(call-interactively #'org-table-edit-field))))
#+end_src
** COMMENT Pair Programming
:PROPERTIES:
:CUSTOM_ID: Pair-Programming
:END:
# Add: Quickly toggle my Emacs for when doing pair programming
I try to make my Emacs look more predictable for my colleagues, by introducing a bunch of UI elements that I normally
have off by default but would otherwise serve as useful aids when working together or provide a sense of familiarity for
my VSCoder counterparts.
#+begin_src emacs-lisp :tangle ~/Desktop/work.el
(defun my/toggle-pair-programming ()
"Toggle enabling features that might aid communication when sharing screen, or pair programming
- Full screen mode
- Line numbers, and column numbers, and cat progress bar
- Blamer overlays
- Dark theme
- Tabs
- Folder navigator
"
(interactive)
(defvar my/sharing-screen? +1)
(setq my/sharing-screen? (- my/sharing-screen?)) ;; Toggle between +1 and -1.
;; When pair programming, exit full screen mode so others can “draw” on my screen, eg using Slack
(toggle-frame-fullscreen)
;; Line numbers in the left margin
(setq display-line-numbers-width-start t)
(global-display-line-numbers-mode my/sharing-screen?)
;; Column & line numbers in the modeline; always want these on?
(column-number-mode +1) ;; Enabled in doom-modeline by default?
(line-number-mode +1) ;; Enabled in doom-modeline by default?
;; Progress bar, graphic and percentage
(use-package nyan-mode )
(nyan-mode my/sharing-screen?)
;; Who did what and when?
(global-blamer-mode my/sharing-screen?)
;; Make things look like VSCode; reduce friction with others
;; → Dark theme, tabs, and clickable folder navigation
(if (= +1 my/sharing-screen?)
(my/toggle-theme 'doom-dracula)
(my/toggle-theme 'doom-solarized-light))
(use-package centaur-tabs)
(setq centaur-tabs-set-icons t)
(setq centaur-tabs-gray-out-icons 'buffer)
(setq centaur-tabs-set-bar 'over)
(centaur-tabs-mode my/sharing-screen?)
;; Treemacs is feature-right; e.g. highlights file associated to current buffer automatically and fully mouse-complaint.
;; press ? to summon a helpful hydra
(use-package treemacs)
(if (= +1 my/sharing-screen?) ;; Toggle showing treemacs window
(treemacs)
(ignore-errors (delete-window (treemacs-get-local-window))))
;; Press “C-e” to see the end of length file names, or use the mouse to widen treemacs
(treemacs-toggle-fixed-width)
(ignore-errors (treemacs-indent-guide-mode +1))
(treemacs-resize-icons 18)
(other-window -1)
;; Kickoff message
(if (= +1 my/sharing-screen?)
(message "Pair programming provides an excellent test of technical and social skills")))
(my/toggle-pair-programming)
#+end_src
** Eldoc for Lisp and Haskell ---documentation in the mini-buffer
:PROPERTIES:
:CUSTOM_ID: Eldoc-for-Lisp-and-Haskell
:END:
In =emacs-lisp-mode= we can enable =eldoc-mode= ---“Elisp Live Documentation”--- to
display information about a function or a variable in the echo area. Likewise
for Haskell.
#+BEGIN_SRC emacs-lisp
(use-package eldoc
:hook (emacs-lisp-mode . turn-on-eldoc-mode)
(lisp-interaction-mode . turn-on-eldoc-mode)
(haskell-mode . turn-on-haskell-doc-mode)
(haskell-mode . turn-on-haskell-indent))
;; Slightly shorten eldoc display delay.
(setq eldoc-idle-delay 0.4) ;; Default 0.5
#+END_SRC
The less casual Haskeller would likely want to use [[https://haskell-lang.org/intero][intero]] to obtain
more support; e.g., obtain suggestions from GHC about redundant imports
or type signatures.
** COMMENT Modern Browsing within Emacs :Disabled:
:PROPERTIES:
:CUSTOM_ID: Modern-Browsing-within-Emacs
:END:
#+begin_src shell :tangle no
# https://github.com/d12frosted/homebrew-emacs-plus
$ brew tap d12frosted/emacs-plus
$ brew install emacs-plus@29 --with-xwidgets
$ /usr/local/Cellar/emacs-plus@29/29.0.50/bin/emacs-29.0.50 &
# In ~/.bashrc, put the following at the end:
alias emacs="/usr/local/Cellar/emacs-plus@29/29.0.50/bin/emacs-29.0.50"
#+end_src
--------------------------------------------------------------------------------
I like using Chrome ---I like the integration of all things Google.
#+begin_src emacs-lisp
(cl-defun internet (&optional (url (concat "https://www." (read-string "https://www."))))
"Browse to URL using `xwidget-webkit-browse-url'; see also `browse-url'."
(interactive)
(delete-other-windows)
(split-window-right)
(xwidget-webkit-browse-url url))
(my/defhydra "C-c p" "Emacs Browser" gamepad
:Internet
("m" (internet "https://mail.google.com/mail/u/0/#inbox") "gMail" :exit t)
("c" (internet "https://calendar.google.com/calendar/u/0/r") "gCalendar" :exit t)
("e" (internet "https://www.reddit.com/r/emacs/") "Emacs Forum" :exit t)
("b" (internet) "Browse" :exit t))
#+end_src
** An “auto read only” detection mechanism ---when jumping to definitions :Disabled:
:PROPERTIES:
:CUSTOM_ID: An-auto-read-only-detection-mechanism-when-jumping-to-definitions
:header-args: :tangle no
:END:
Files in 3ʳᵈ-party directories should be read-only whenever I open them, when
I'm jumping to definitions (with ~M-.~).
#+begin_src emacs-lisp
;; Usage: Press “M-”. “use-package” below and you can accidentally alter the source code!
;; But in this case you likely just wanted to see the 3ʳᵈ-party definition, not alter it.
;; As such, with this advice, the source will not be alterable (unless you toggle read-only mode).
(advice-add #'xref-find-definitions :after
(lambda (&rest _)
(when (--map (s-ends-with? it (f-parent buffer-file-name))
'("lisp/emacs-lisp" "/lisp" ".emacs.d/elpa/"))
(read-only-mode))))
#+end_src
* Open PDFs in Emacs
#+begin_src emacs-lisp
;; In Org-mode, clicking on PDF should open it in Emacs
;; Example: [[~/Desktop/stuff-I'm-learning.pdf::12]] ;; Opens the pdf to page 12
;; Another Example: docview:~/Desktop/stuff-I'm-learning.pdf::12
(ignore-errors (add-to-list 'org-file-apps '("\\.pdf\\'" . emacs)))
;; Required code to make the above links work as expected.
;; Source: https://www.reddit.com/r/emacs/comments/re0dx8/how_do_you_link_a_specific_pdf_page_in_org_mode/
(defun my-org-docview-open-hack (orig-func &rest args)
(let* ((link (car args)) path page)
(string-match "\\(.*?\\)\\(?:::\\([0-9]+\\)\\)?$" link)
(setq path (match-string 1 link))
(setq page (and (match-beginning 2)
(string-to-number (match-string 2 link))))
(org-open-file path 1)
(when page
(cond
((eq major-mode 'pdf-view-mode)
(pdf-view-goto-page page))
(t
(doc-view-goto-page page))))))
(advice-add 'org-docview-open :around #'my-org-docview-open-hack)
;; Alternatively, there's a dedicated package for this
;; https://github.com/fuxialexander/org-pdftools/tree/967f48fb5038bba32915ee9da8dc4e8b10ba3376
#+end_src
* empv
#+begin_src emacs-lisp
(use-package empv )
;; Then, M-x empv-play https://invidious.fdn.fr/watch?v=hlTqCmpP5eo, to listen to Dua Ifitiah in the background
;; Or: M-x empv-play https://invidious.fdn.fr/watch?v=9m9yE7qtq5w
;; lol maybe make a hydra(ie playlist) of things I commonly listen to in the background while working.
;; Require: brew install mpv
;; See also:
;; Maybe better? https://github.com/spiderbit/ytdious/tree/941460b51e43ef6764e15e2b9c4af54c3e56115f
;; Maybe better? https://melpa.org/#/yeetube
;; https://github.com/maximus12793/helm-youtube/tree/e7272f1648c7fa836ea5ac1a61770b4931ab4709
;; https://github.com/isamert/empv.el/tree/1721a581d68f211a7f0104554858ea2afb1723ff
;;
(setq empv-invidious-instance "https://invidious.fdn.fr.com")
#+end_src
* TODO COMMENT Eglot ----Fancy IDE Features that Just Workᵀᴹ
For JavaScript:
#+begin_src emacs-lisp
;; Get the language server for JavaScript
;; $ npm install -g javascript-typescript-langserver
;; Now open an empty buffer, switch to JS mode, M-x eglot, M-x company-mode,
;; then enter “console.” and see the completion of possibilities! <3
#+end_src
For Java, install doc:eglot-java-mode and activate that in a Java file ---it automatically installs the required
language server. 🚀
* COMMENT Lost Souls :Outdated_Documentation:Not_yet_tangled:
:PROPERTIES:
:CUSTOM_ID: Lost-Souls
:END:
** Note: M-S-SPC is for my personal servers dashboard.
:PROPERTIES:
:CUSTOM_ID: Note-M-S-SPC-is-for-my-personal-servers-dashboard
:END:
#+begin_src emacs-lisp :tangle no
;; Note: M-S-SPC is for my personal servers dashboard.
(global-set-key (kbd "M-SPC") (lambda () (interactive) (setq org-agenda-files (list org-default-notes-file)) (org-agenda nil "a") (delete-other-windows) (beginning-of-buffer)))
(use-package ace-jump-mode ;; Already installed above, somewhere.
:config (bind-key* "C-c SPC" 'ace-jump-mode))
#+end_src
** Zoom
:PROPERTIES:
:CUSTOM_ID: Zoom
:END:
#+begin_src emacs-lisp :tangle no
;; An automatic window-resizing mechanism.
;; A “calmer” alternative to golden-ratio.
;; https://github.com/cyrus-and/zoom
(use-package zoom
:config (zoom-mode t))
#+end_src
** Ibuffer
:PROPERTIES:
:CUSTOM_ID: Ibuffer
:END:
#+begin_src emacs-lisp :tangle no
;; Let's use an improved buffer list.
(use-package ibuffer ;; This is built-into Emacs.
:bind ("C-x C-b" . ibuffer))
;; It uses similar commands as does dired; e.g.,
;; / . org
;; This filters (“/”) the list with extensions (“.”) being “org”.
(use-package ibuffer-vc
:hook (ibuffer . (lambda ()
(ibuffer-vc-set-filter-groups-by-vc-root)
(unless (eq ibuffer-sorting-mode 'alphabetic)
(ibuffer-do-sort-by-alphabetic))))
:custom
(ibuffer-formats '((mark modified read-only " "
(name 18 18 :left :elide) " "
(size 9 -1 :right) " "
(mode 16 16 :left :elide) " "
(vc-status 16 16 :left) " "
(vc-relative-file)))))
#+end_src
+ [[http://martinowen.net/blog/2010/02/03/tips-for-emacs-ibuffer.html][Tips for using Emacs Ibuffer]]
+ (~10 minute video) [[https://cestlaz.github.io/posts/using-emacs-34-ibuffer-emmet/][Using Emacs - 34 - ibuffer and emmet - C'est la Z]]
+ (~10 minute video) [[https://www.youtube.com/watch?v=6KN_oSLFf-k&ab_channel=ProtesilaosStavrou][Emacs: introduction to IBUFFER - YouTube]]
** find function at point
:PROPERTIES:
:CUSTOM_ID: find-function-at-point
:END:
Friendly reminder that ~M-.~ takes you to the definition, and ~M-,~ takes you back
to where you originally where.
** COMMENT centered-cursor: Keep focus in the centre of the screen :Eeek:
:PROPERTIES:
:CUSTOM_ID: COMMENT-centered-cursor-Keep-focus-in-the-centre-of-the-screen
:END:
#+begin_src emacs-lisp :tangle no
;; When scrolling, move the screen and leave the cursour in the (vertical) center of the screen
(use-package centered-cursor-mode
:config (global-centered-cursor-mode))
#+end_src
** “C-x 2” and “C-x 3” now create a new window horizontally/vertically and send cursor there
:PROPERTIES:
:CUSTOM_ID: C-x-2-and-C-x-3-now-create-a-new-window-horizontally-vertically-and-send-cursor-there
:END:
#+begin_src emacs-lisp :tangle no
;; When we split open a new window, we usually want to jump to the new window.
(advice-add #'split-window-below :after (lambda (&rest _) (other-window 1)))
(advice-add #'split-window-right :after (lambda (&rest _) (other-window 1)))
#+end_src
** Semantic Change
:PROPERTIES:
:CUSTOM_ID: Semantic-Change
:END:
Using kbd:⌘-i and kbd:⌘-o we can quickly, for example, delete a string or its
contents; or delete a {}-block or just its contents; or delete a ()-argument
list or just its contents, etc.
~change-inner~ gives you vim's ~ci~ command:
- ~change-inner {~ ⇒ Delete all text starting from the first ‘{’ delimiter to the next one; but /keep the delimiters/.
- ~change-outer {~ ⇒ As above, but also delete the delimiters.
#+begin_src emacs-lisp :tangle no
(use-package change-inner
:bind (("s-i" . #'change-inner)
("s-o" . #'change-outer)))
#+end_src
** Drag Stuff :Disabled:
:PROPERTIES:
:CUSTOM_ID: Drag-Stuff
:END:
#+begin_src emacs-lisp :tangle no :tangle no
;; Move current word ←/→, or current line ↑/↓.
;; Todo: Compare with org-metaup and org-metadown...
(use-package drag-stuff
:config (cl-loop for (key . action) in '(("" . drag-stuff-down)
("" . drag-stuff-up)
("" . drag-stuff-right)
("" . drag-stuff-left))
do (bind-key key action org-mode-map))
(drag-stuff-global-mode 1))
#+end_src
Ruins Org-mode's M-↑/↓ for moving entire sections around.
** Indentation Guide
:PROPERTIES:
:CUSTOM_ID: Indentation-Guide
:END:
The following is also “OK” in Org-mode ;-)
#+begin_src emacs-lisp :tangle no
;; Add a visual indent guide
(use-package highlight-indent-guides
:hook (prog-mode . highlight-indent-guides-mode)
:custom
(highlight-indent-guides-method 'character)
(highlight-indent-guides-character ?|)
(highlight-indent-guides-responsive 'stack))
#+end_src
** TODO COMMENT [Nope?] JavaScript
:PROPERTIES:
:CUSTOM_ID: COMMENT-Nope-JavaScript
:END:
+ ;; FIXME Error (use-package): Failed to install ob-js: Package ‘ob-js-’ is unavailable
#+begin_src emacs-lisp :tangle no
(use-package ob-js
:config
(add-to-list 'org-babel-load-languages '(js . t))
(org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages)
(add-to-list 'org-babel-tangle-lang-exts '("js" . "js"))
(system-packages-ensure "node"))
;; use “:results output” for js blocks!
#+end_src
** Commenting
:PROPERTIES:
:CUSTOM_ID: Commenting
:END:
Let's get some nifty [[https://github.com/remyferre/comment-dwim-2][commenting]] features ---the link has nice usage gifs.
+ [[kbd:][M-;]]
repeatedly does (1) comments current line, (2) inserts a comment at the end
of the current line, and (3) deletes an existing end-of-line comment.
[[kbd:][C-u_M-;]] indents the current enf-of-line comment with any above it.
For use with Org-mode, it's best to use doc:org-edit-src-code ---which I've
bound to [[kbd:][⌘ e]].
#+begin_src emacs-lisp :tangle no
(use-package comment-dwim-2
:bind ("M-;" . comment-dwim-2))
;; Not ideal: M-; comments a parent Org heading and not the current line.
;; (define-key org-mode-map (kbd "M-;") 'org-comment-dwim-2)
#+end_src
** Having a workspace manager in Emacs
:PROPERTIES:
:CUSTOM_ID: Having-a-workspace-manager-in-Emacs
:END:
I've loved using XMonad as a window tiling manager. I've enjoyed the ability to
segregate my tasks according to what ‘project’ I'm working on; such as research,
marking, Emacs play, etc. With [[https://github.com/nex3/perspective-el][perspective]], I can do the same thing :-)
That is, I can have a million buffers, but only those that belong to a workspace
will be visible when I'm switching between buffers, for example.
( The awesome-tab and centaur-tab, mentioned elsewhere here, can be used to
achieve the same thing by ‘grouping buffers together’. )
#+begin_src emacs-lisp :tangle no
(use-package perspective
:config ;; Activate it.
(persp-mode)
;; In the modeline, tell me which workspace I'm in.
(persp-turn-on-modestring))
#+END_SRC
All commands are prefixed by ~C-x x~; main commands:
+ ~s, n/→, p/←~ :: ‘S’elect a workspace to go to or create it, or go to ‘n’ext
one, or go to ‘p’revious one.
+ ~c~ :: Query a perspective to kill.
+ ~r~ :: Rename a perspective.
+ ~A~ :: Add buffer to current perspective & remove it from all others.
As always, since we've installed ~which-key~, it suffices to press ~C-x x~ then look
at the resulting menu 😃
** Editor Documentation with Contextual Information
:PROPERTIES:
:CUSTOM_ID: Editor-Documentation-with-Contextual-Information
:END:
/Emacs is an extensible self-documenting editor!/
Let's use a helpful Emacs /documentation/ system that cleanly shows a lot of
contextual information ---then let's /extend/ that to work as we want it to:
~C-h o~ to describe the symbol at point.
#+begin_src emacs-lisp :tangle no
(use-package helpful )
(defun my/describe-symbol (symbol)
"A “C-h o” replacement using “helpful”:
If there's a thing at point, offer that as default search item.
If a prefix is provided, i.e., “C-u C-h o” then the built-in
“describe-symbol” command is used.
⇨ Pretty docstrings, with links and highlighting.
⇨ Source code of symbol.
⇨ Callers of function symbol.
⇨ Key bindings for function symbol.
⇨ Aliases.
⇨ Options to enable tracing, dissable, and forget/unbind the symbol!
"
(interactive "p")
(let* ((thing (symbol-at-point))
(val (completing-read
(format "Describe symbol (default %s): " thing)
(vconcat (list thing) obarray)
(lambda (vv)
(cl-some (lambda (x) (funcall (nth 1 x) vv))
describe-symbol-backends))
t nil nil))
(it (intern val)))
(cond
(current-prefix-arg (funcall #'describe-symbol it))
((or (functionp it) (macrop it) (commandp it)) (helpful-callable it))
(t (helpful-symbol it)))))
;; Keybindings.
(global-set-key (kbd "C-h o") #'my/describe-symbol)
(global-set-key (kbd "C-h k") #'helpful-key)
#+END_SRC
I like [[https://github.com/Wilfred/helpful][helpful]] and wanted it to have the same behaviour as ~C-h o~, which
~helpful-at-point~ does not achieve. The incantation above makes ~C-h o~ use ~helpful~
in that if the cursor is on a symbol, then it is offered to the user as a
default search item for help, otherwise a plain search box for help
appears. Using a universal argument lets us drop to the built-in help command.
** =README= ---From =init.org= to =init.el=
:PROPERTIES:
:CUSTOM_ID: README-From-init-org-to-init-el
:END:
Rather than manually extracting the Lisp code from this literate document each
time we alter it, let's instead add a ‘hook’ ---a method that is invoked on a
particular event, in this case when we save the file. More precisely, in this
case, ~C-x C-s~ is a normal save whereas ~C-u C-x C-s~ is a save after forming
~init.elc~ and ~README.md~.
**** The =my/make-init-el-and-README= function
:PROPERTIES:
:CUSTOM_ID: The-my-make-init-el-and-README-function
:END:
We ‘hook on’ the following function to the usual save method
that is associated with this file only.
# +name: enable making init and readme
#+name: startup-code
#+begin_src emacs-lisp :tangle no :eval never-export
(defun my/make-init-el-and-README ()
"Tangle an el and a github README from my init.org."
(interactive "P") ;; Places value of universal argument into: current-prefix-arg
(when current-prefix-arg
(let* ((time (current-time))
(_date (format-time-string "_%Y-%m-%d"))
(.emacs "~/.emacs")
(.emacs.el "~/.emacs.el"))
;; Make README.org
(save-excursion
(org-babel-goto-named-src-block "make-readme") ;; See next subsubsection.
(org-babel-execute-src-block))
;; remove any other initialisation file candidates
(ignore-errors
(f-move .emacs (concat .emacs _date))
(f-move .emacs.el (concat .emacs.el _date)))
;; Make init.el
(org-babel-tangle)
;; (byte-compile-file "~/.emacs.d/init.el")
(load-file "~/.emacs.d/init.el")
;; Acknowledgement
(message "Tangled, compiled, and loaded init.el; and made README.md … %.06f seconds"
(float-time (time-since time))))))
(add-hook 'after-save-hook 'my/make-init-el-and-README nil 'local-to-this-file-please)
#+end_src
**** The Org-block named =make-readme=
:PROPERTIES:
:CUSTOM_ID: The-Org-block-named-make-readme
:END:
Where the following block has ~#+NAME: make-readme~ before it. This source block
generates the ~README~ for the associated Github repository.
#+NAME: make-readme
#+begin_src emacs-lisp :tangle no :tangle no :export_never t
(save-buffer)
(with-temp-buffer
(insert
"#+EXPORT_FILE_NAME: README.org
# Logos and birthday present painting
,#+HTML:" (s-collapse-whitespace (concat
"
![](\"images/emacs-logo.png\")
![](\"https://img.shields.io/badge/GNU%20Emacs-")
![](\"https://img.shields.io/badge/org--mode-")
![](\"images/emacs-birthday-present.png\")
"))
;; My Literate Setup; need the empty new lines for the export
"
I enjoy reading others' /literate/ configuration files and
incorporating what I learn into my own. The result is a
sufficiently well-documented and accessible read that yields
a stylish and functional system (•̀ᴗ•́)و
This ~README.org~ has been automatically generated from my
configuration and its contents below are accessible
in (outdated) blog format, with /colour/, or as colourful
PDF, [[https://alhassy.github.io/init/][here]]. Enjoy
:smile:
,#+INCLUDE: init.org
")
;; No code execution on export
;; ⟪ For a particular block, we use “:eval never-export”. ⟫
(let ((org-export-use-babel nil))
(org-mode)
(org-org-export-to-org)))
#+end_src
Alternatively, evaluate the above source block with ~C-c C-c~ to produce a ~README~
file.
For the ‘badges’, see https://shields.io/. The syntax above is structured:
#+begin_example org
https://img.shields.io/badge/
=; even worse, the resulting PDF image did not look nice ---I had to
stretch it out.
The command line tool is *lacking functionality* and so the docs are not helpful.
E.g., I cannot produce pie charts using the command line tool.
#+end_quote
*** [[https://revealjs.com/?transition=zoom#/][Reveal.JS]] -- The HTML Presentation Framework
:PROPERTIES:
:CUSTOM_ID: https-revealjs-com-transition-zoom-Reveal-JS-The-HTML-Presentation-Framework
:END:
Org-mode documents can be transformed into beautiful slide decks
with [[https://github.com/yjwen/org-reveal/blob/master/Readme.org][org-reveal]] with the following two simple lines.
#+BEGIN_SRC emacs-lisp
(use-package ox-reveal
:custom (org-reveal-root "https://cdn.jsdelivr.net/npm/reveal.js"))
#+END_SRC
# MA: ??? It looks like ox-reveal is being abandoned in favor of org-re-reveal,
# a fork compatible with org-mode 9.2?
For example, execute, ~C-x C-e~ after the closing parenthesis of, the
following block to see an example slide-deck (─‿‿─)
#+BEGIN_SRC emacs-lisp :tangle no
(progn (shell-command "curl https://raw.githubusercontent.com/yjwen/org-reveal/696613edef0fe17a9c53146f79933fe7c4101100/Readme.org >> Trying_out_reveal.org")
(switch-to-buffer (find-file "Trying_out_reveal.org"))
(org-reveal-export-to-html-and-browse))
#+END_SRC
Org-mode exporting, ~C-c C-e~, now includes an option ~R~ for such reveal slide decks.
:Hide:
[[https://alhassy.github.io/next-700-module-systems/proposal/defence-slides.html#/sec-title-slide][Here]] ([[https://raw.githubusercontent.com/alhassy/next-700-module-systems/master/proposal/defence-slides.org][source]]) is an example of org-reveal slides where I add a number to each page,
use multiple columns, and extend the margins perhaps a bit too much.
:End:
Two dimensional slides may be a bit new to some people, so I like to
give viewers an option, in tiny font, to view the slide-deck
continuously and remind them that ~?~ provides useful shortcuts.
#+BEGIN_SRC emacs-lisp
(setq org-reveal-title-slide "%t
%a
⟪ Flattened View ; Press ? for Help ⟫
")
#+END_SRC
One should remove the ~&showNotes=true~ if they do not want to include
speaker notes in the flattened view.
Within the flatenned view, one may wish to ~CTRL/CMD+P~ then save the
resulting PDF locally.
** C-c C-l Org-mode ⇐ HTML
:PROPERTIES:
:CUSTOM_ID: Org-mode-HTML
:END:
The following let's us copy htlm into org format using eww, Emacs' built-in web browser.
#+BEGIN_SRC emacs-lisp :tangle no
;; See: https://emacs.stackexchange.com/questions/7171/paste-html-into-org-mode
(use-package org-eww
:quelpa (org-eww :fetcher git :url "https://github.com/Fuco1/org-mode.git"))
#+END_SRC
It does not work as I'd like, but may prove useful to have around.
+ Possibly useful: Open a webpage with ~M-x eww~ then toggle ~M-x read-only-mode~ to
edit the text, say for notes or deletions, as you read! No need to copy-paste.
--------------------------------------------------------------------------------
[[https://github.com/alphapapa/org-web-tools][org-web-tools]] claims to /view, capture, and archive Web pages in Org-mode/; this
may be a very useful tool.
#+begin_src emacs-lisp
(use-package org-web-tools
:config
;; Insert an Org-mode link to the URL in the clipboard or kill-ring. Downloads
;; the page to get the HTML title.
;; (bind-key* "C-c C-l" #'org-web-tools-insert-link-for-url) ;; Instead, see my/org-insert-link-dwim below.
)
#+end_src
Other useful functions, needing pandoc:
doc:org-web-tools-insert-web-page-as-entry and
doc:org-web-tools-convert-links-to-page-entries.
#+begin_src emacs-lisp
;; C-u C-c C-l ⇒ Paste URL with title, WITHOUT prompting me for anything.
;; C-c C-l ⇒ Prompt me for title.
(bind-key* "C-c C-l"
(lambda () (interactive)
(call-interactively
(if current-prefix-arg
#'org-web-tools-insert-link-for-url
#'my/org-insert-link-dwim))))
;; From:
(defun my/org-insert-link-dwim ()
"Like `org-insert-link' but with personal dwim preferences.
- When text is selected, use that as the link description --and prompt for link type
- When a URL is in the clipboard, use that as the link type
- On an existing Org link, prompt to alter the link then to alter the description
- With a ‘C-u’ prefix, prompts for a file to link to.
- It is relative to the current directory; use ‘C-u C-u’ to get an absolute path.
It fallsback to `org-insert-link' when possible.
Functin Source: https://xenodium.com/emacs-dwim-do-what-i-mean/"
(interactive)
(let* ((point-in-link (org-in-regexp org-link-any-re 1))
(clipboard-url (when (string-match-p "^http" (current-kill 0))
(current-kill 0)))
(region-content (when (region-active-p)
(buffer-substring-no-properties (region-beginning)
(region-end)))))
(cond ((and region-content clipboard-url (not point-in-link))
(delete-region (region-beginning) (region-end))
(insert (org-make-link-string clipboard-url region-content)))
((and clipboard-url (not point-in-link))
(insert (org-make-link-string
clipboard-url
(read-string "title: "
(with-current-buffer (url-retrieve-synchronously clipboard-url)
(dom-text (car
(dom-by-tag (libxml-parse-html-region
(point-min)
(point-max))
'title))))))))
(t
(call-interactively 'org-insert-link)))))
#+end_src
* TODO RDD
** get the pkg
#+begin_src emacs-lisp :tangle init.el
(use-package repl-driven-development)
(setq repl-driven-development-echo-duration 10)
#+end_src
** terminal
#+begin_src emacs-lisp :tangle init.el
;; Sometimes I see a bunch of shell incantations in a README or something and I'd like to execute them right there and then,
;; and not have to bother with copying them over to a terminal and execute there. As such, here's a quick key binding to execute
;; shell commands from anywhere.
;; (repl-driven-development [C-x C-t] "bash" :prompt "bash-3.2\\$")
(repl-driven-development [C-x C-t] terminal)
#+end_src
** jshell
#+begin_src emacs-lisp :tangle init.el
;; Set “Cx Cj” to evaluate Java code in a background REPL.
(repl-driven-development
[C-x C-j]
;; enable assertions, and add everything installed, via `mvn', in scope.
(format "jshell --class-path %s --enable-preview -R -ea --feedback silent"
(concat ".:" (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f 2>/dev/null | tr '\n' ':'")))
:prompt "jshell>"
:init "\n /set mode EmacsJavaMode normal -command
\n /set format EmacsJavaMode display \"{pre}added import {name}{post}\" import-added
\n /set format EmacsJavaMode display \"{pre}re-added import {name}{post}\" import-modified,replaced
\n /set format EmacsJavaMode result \"{type} {name} = {value}{post}\" added,modified,replaced-primary-ok
\n /set truncation EmacsJavaMode 40000
\n /set feedback EmacsJavaMode
\n System.out.println(\"Enjoy Java with Emacs (｡◕‿◕｡))\")")
;; TODO [Truncation; Low] https://github.com/xiongtx/eros/blob/master/eros.el#L202
#+end_src
** mvn
#+begin_src emacs-lisp :tangle init.el
(defun mvn (groupId artifactId)
"Quickly install a library from Maven Central."
(async-shell-command (format "mvn org.apache.maven.plugins:maven-dependency-plugin:2.8:get -Dartifact=%s:%s:LATEST:jar:sources" groupId artifactId)))
(when nil
⨾⨾ Example use of `mvn`
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; First confirm C-x C-j works as intended
IntStream.range(0, 15).mapToObj(i -> i % 15 == 0 ? "FizzBuzz" : i % 3 == 0 ? "Fizz" : i % 5 == 0 ? "Buzz" : String.valueOf(i)).toList()
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
(mvn "org.antlr" "antlr4") ;; C-x C-e
;; Now re-start the Java C-x C-j repl via a C-x C-e (lame! not ergonomic!)
;; Now check that you have access to antrl in your repl by importing it and looking at one of its classes:
;; ⦃ jshell --class-path /Users/musa/.m2/repository/org/antlr/antlr4-runtime/4.13.0/antlr4-runtime-4.13.0.jar ⦄
import org.antlr.v4.runtime.*;
CommonTokenStream.class
;; NOTE: This is the runtime, to use the actual tool:
java -jar /Users/musa/.m2/repository/org/antlr/antlr4/4.13.0/antlr4-4.13.0-complete.jar
;; Alternatively,
;; $ jshell
;; > var x = 5
;; > import org.antlr.v4.runtime.*; // CRASHES since antlr is not in scope
;; > /reset --class-path /Users/musa/.m2/repository/org/antlr/antlr4-runtime/4.13.0/antlr4-runtime-4.13.0.jar
;; > import org.antlr.v4.runtime.*; // WORKS, yay
;; > x // CRASHES, not in scope
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
import org.apache.commons.lang3.StringUtils;
StringUtils.class;
/imports // JShell command to list all imports, it now contains apache!
// Guava is the Google core libraries for Java
import com.google.common.collect.ImmutableMap;
ImmutableMap.of(1, "A", 2, "B") // ⇒ {1=A, 2=B}
;; (mvn "com.google.code.gson" "gson")
// Then C-x C-e to update the repl definition of C-x C-j to include the updated gson library.
import com.google.gson.*;
String json = new Gson().toJson(Map.of("me", List.of(1, 2,3), "you", Map.of("Love", "Lisp", "Hate", "Verbosity")))
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; TestNG is a testing framework; supporting tests configured by annotations, data-driven testing, parametric tests, etc.
(mvn "org.testng" "testng")
import org.testng.*;
/imports // Now can see org.testng at the end of the list
;; ⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾⨾
;; TODO[Low]: For working with Lombok annotations, use the jshell `/reset --class-path` command to include the lombok compiled file into
;; the current Jshell session.
;;
;; See: https://stackoverflow.com/questions/74084364/how-to-use-lombok-in-jshell
;;
;; (mvn "org.projectlombok" "lombok")
;; import lombok.*;
;; @lombok.Data class Test { private String name; }
;; new Test().equals(new Test())
)
#+end_src
** Adding support for “//!use” & “//!omit” top level repl commands
#+begin_src emacs-lisp
;; Adding support for “//!use” & “//!omit” top level repl commands
(setq repl/jshell/classpath (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f | tr '\n' ':'"))
(advice-add 'repl/jshell
:around (lambda (repl &rest args)
(if (equal nil current-prefix-arg)
;; No prefix supplied
(progn
(setq rdd---current-input (s-replace-regexp "\n" "" (s-trim-left
(if (region-active-p) (buffer-substring-no-properties (region-beginning) (region-end))
(substring-no-properties (thing-at-point 'line))))))
(if (s-starts-with? "//!use" rdd---current-input)
(-let [jar (s-trim (s-chop-prefix "//!use" rdd---current-input))]
(repl/top-level//!use jar))
(if (s-starts-with? "//!omit" rdd---current-input)
(-let [jar (s-trim (s-chop-prefix "//!omit" rdd---current-input))]
(repl/top-level//!omit jar))
;; otherwise business as usual
(apply repl args))))
(pcase current-prefix-arg
(-1
;; reset classpath to default, then business as usual.
(setq repl/jshell/classpath (shell-command-to-string "find ~/.m2/repository -name \"*.jar\" -type f | tr '\n' ':'"))
(apply repl args))
(999
(message-box "It worked"))
;; otherwise business as usual
(t (apply repl args))))))
;; remove all advice
;; (-let [sym 'repl/jshell] (advice-mapc (lambda (advice _props) (advice-remove sym advice)) sym))
(cl-defun repl/top-level//!omit (str)
(with-temp-buffer
(setq repl/jshell/classpath (s-replace-regexp (format ":[^:]*%s[^:]*:" str) ":" repl/jshell/classpath))
(insert "/env --class-path ")
(insert repl/jshell/classpath)
(repl/jshell (point-min) (point-max))))
(cl-defun repl/top-level//!use (str)
"If the given jar cannot be added successful, the existing classpath remains untouched.
Return to your default classpath by invoking the repl with the -1 prefix.
Example usage:
//!use ~/path/to/compiled/java/classes
import com.x.y.z;
Where directory hierarchy com/x/y/z denotes a Java package under the above //!use path.
"
(with-temp-buffer
(setq repl/jshell/classpath (concat (s-trim str) ":" repl/jshell/classpath))
(insert "/env --class-path ")
(insert repl/jshell/classpath)
(repl/jshell (point-min) (point-max))))
#+end_src
** Misc top level cmds
TODO: Make repl load all company class files, that way I have them upon start up.
OR: Provide a command `//!load ~/dir` which recursively loads/imports all java files? <---Probably this!
** COMMENT C-x C-e ∷ REPL-driven development for ELisp / NodeJS / Python / Etc !
:PROPERTIES:
:CUSTOM_ID: C-x-C-e-REPL-driven-development-for-NodeJS
:END:
| /Evaluate code and see the results inline ---A feedback loop that is faster than ever!/ |
Within Emacs, kbd:C-x_C-e evaluates a Lisp expression /anywhere/; e.g.,
at the end of ~(message-box "hello world")~ press ~C-x C-e~ to see a greeting.
# Likewise, evaluating a variable shows you its value: user-full-name.
- We ran some code /without/ explicitly running an interpreter/repl/compiler!
- This is known as “REPL driven development” (RDD):
There is a running REPL server for your language, implicitly in the
background, and your editor (say with ~C-x C-e~) will send it a line (or a
selected region) of code for evaluation; we then see the result as an
overlay in our current buffer.
+ You /choose/ which code gets (re)evaluated.
- A quick introduction to RDD can be viewed at [[https://purelyfunctional.tv/lesson/what-is-repl-driven-development/][PurelyFunctional.tv]].
*** ELisp
:PROPERTIES:
:CUSTOM_ID: ELisp
:END:
By default, Emacs Lisp's kbd:C-x_C-e shows results only in the minibuffer; near
the bottom of the screen. Let's also have evaluation results displayed as inline
overlays ---at the location that the user, us, is actually looking/working;
rather than forcing their eyes to shift up&down when writing&evaluating.
+ kbd:C-u_C-x_C-e inserts the evaluation result at point; kbd:C-u_0_C-x_C-e does
so /without truncating/ lengthy output.
+ Read this [[https://karthinks.com/software/an-elisp-editing-tip/][Sweet & short blog/GIFs]] on practical uses of kbd:C-x_C-e when working with Lisp.
#+begin_src emacs-lisp
;; Evaluation Result OverlayS for Emacs Lisp
(use-package eros
:defer nil
:init (eros-mode t))
#+end_src
# In particular, this gives us the Lisp function
# `eros--eval-overlay', which evaluates its argument X
# and produces an overlay of the result at position P.
# E.g., (eros--eval-overlay "hola" (point-min))
# Shows a momentary overlay at the first line.
*** JavaScript
:PROPERTIES:
:CUSTOM_ID: JavaScript
:END:
Let's setup RDD for JavaScript ---by having a NodeJS repl server running in the background.
- See [[https://github.com/anonimitoraf/skerrick][skerrick: REPL-driven development for Javascript]] for animated GIFs; it
works with modules as well.
#+begin_src emacs-lisp
(use-package skerrick
:defer nil
:init
;; Needs to be run on the very first install of skerrick. Or when you want to upgrade.
(unless (equal (shell-command-to-string "type skerrick") "skerrick not found\n")
(skerrick-install-or-upgrade-server-binary)))
;; Should be run in a JS buffer; it is buffer specific.
;; (skerrick-start-server)
;; Now main function, entry point is:
;; M-x skerrick-eval-region
#+end_src
Let's provide a quick keyboard shortcut. E.g., kbd:C-x_C-e evaluates ELisp, so let's mimic that for JS buffers:
#+begin_src emacs-lisp
(require 'js) ;; Defines js-mode-map
;; Evaluate a region, if any is selected; otherwise evaluate the current line.
(bind-key
"C-x C-e" (lambda ()
(interactive)
(if (use-region-p)
(skerrick-eval-region)
(beginning-of-line)
(set-mark-command nil)
(end-of-line)
(skerrick-eval-region)
(pop-mark)))
'js-mode-map)
#+end_src
Trying something else instead of skerrick, until
https://github.com/anonimitoraf/skerrick/issues/7 is resolved.
In any JS file, I just press ~C-x C-e~ and the JS interpreter is brought up with the evaluation results shown:
#+begin_src emacs-lisp
(use-package js-comint :defer nil)
(define-key js-mode-map (kbd "C-x C-e") (lambda () (interactive) (call-interactively #'js-comint-repl) (other-window -1) (js-comint-send-last-sexp)))
#+end_src
For instance,
#+begin_src js :tangle no
// Start the server... then
// On each line and press C-x C-e
let a = "hello"
let b = "world"
(a + ' ' + b).toUpperCase()
// The final line should show: HELLO WORLD
#+end_src
**** Preserving the context
:PROPERTIES:
:CUSTOM_ID: Preserving-the-context
:END:
When testing an application, you might notice a bug in a particular context
---i.e., a particular configuration in the app.
1. The classic approach is to kill the app; i.e., stop the server that is, well,
serving the app.
2. Solve the problem.
3. Try to get back to the configuration, context, you were in beforehand and
check that the problem has been resolved.
A better approach is to ignore the bookkeeping steps, 1&3, and just do step 2.
For that, there are numerous packages:
- [[https://github.com/mishoo/livenode/][livenode: Live-code your NodeJS applications]] ⨾⨾ [[https://vimeo.com/60636079][Video demo]] ~11min ⨾⨾ Last
updated 2013
- [[https://github.com/skeeto/skewer-mode][skewer-mode: Live web development in Emacs]] ⨾⨾ [[https://www.youtube.com/watch?v=4tyTgyzUJqM&ab_channel=Skeeto][Silent video demo]] ~5min ⨾⨾ Last
updated 2020
- [[https://github.com/swank-js/swank-js][swank-js: Swank backend for Node.JS and in-browser JavaScript]] ⨾⨾ Last updated
2015
For more RDD alternatives in Emacs, see https://github.com/anonimitoraf/skerrick/issues/8.
*** Python, etc
:PROPERTIES:
:CUSTOM_ID: Python-etc
:END:
It /seems/ to be /super easy/ to add such a support for other languages, such as Python.
See the final comment [[https://karthinks.com/software/an-elisp-editing-tip/][here]] for the tiny change required.
** COMMENT Quickly Run Code Snippets
:PROPERTIES:
:CUSTOM_ID: Quickly-Run-Code-Snippets
:END:
Sometimes we want to quickly run some code /without making a dedicated file/ or
with a file but /without remembering the terminal incantation to do so/, enter
~quickrun~. Anywhere, we can select a snippet of code and run TODO. doc.quickrun-region
to execute that snippet after selecting the associated programming language, or
TODO. doc.quickrun-replace-region if we want the results in-line. If our language of
choice does not exist, we can [[https://github.com/emacsorphanage/quickrun#user-defined-command][easily add support for it]].
#+begin_src emacs-lisp
;; In any programming buffer, “M-x quickrun” to execute that program.
;; Super useful when wanting to quickly test things out, in a playground.
;;
;; E.g., Make a new file named “hello.py” containing “print "hi"”, then “M-x quickrun”.
;;
;; Enable “quickrun-autorun-mode” to run code after every save.
(use-package quickrun
;; ⇒ “C-c C-r” to see output, “q” to close output
;; ⇒ “C-u C-c C-r” prompts for a language (Useful when testing snippets different from current programming mode)
;; ⇒ In a non-programming buffer, “C-c C-r” runs selected region.
:defer nil
:config (bind-key* "C-c C-r"
(lambda (&optional start end)
(interactive "r")
(if (use-region-p)
(quickrun-region start end)
(quickrun current-prefix-arg)))))
#+end_src
Example...
#+begin_src emacs-lisp
(system-packages-ensure "rust") ;; Rust Compiler
;; Select the following then press C-c C-r: fn main() { println!("Hello, World!"); }
#+end_src
Actually, let's get a [[https://github.com/brotzeit/rustic#intro][full Rust development environment for Emacs]] (which also
has [[https://github.com/brotzeit/rustic#org-babel][great support for Org-babel]].)
#+begin_src emacs-lisp
(use-package rustic :defer nil)
;; Open any Rust file, and run “M-x lsp” which will then prompt you to install
;; rust-analyzer, the rust LSP.
;;
;; LSP for Rust ⇒ Goto definition (M-. / ⌘-l), code completion with types and
;; docstrings, colourful documentation on hover, “Run [Test] | Debug” overlays,
;; super nice stuff! Run “M-!”/[M-x company-show-doc-buffer] if you want the doc in a colourful buffer.
;;
;; Below, hover over “Vec” and see nice, scrollable, colourful docs on vectors.
;; let v:Vec<_> = vec![1, 2, 3];
;; The offical Rust toolchain installer
(system-packages-ensure "rustup")
(shell-command "rustup update")
#+end_src
:More_on_rust:
Now, C-c C-c C-d on something to get help/description of it.
(setq rustic-racer-rust-src-path "/Users/musa/.rustup/toolchains/stable-x86_64-apple-darwin/lib/rustlib/src/rust/library/")
# Get Rustup, load it into current terminal session
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.bash_profile
source ~/.bashrc
type rustup
# Get stuff
rustup update
rustup component add rust-src
cargo +nightly install racer
rustup toolchain install nightly
rustup component add rustc-dev --toolchain=nightly
cargo +nightly install racer
:End:
* Don't show updating/installation shell buffers
#+begin_src emacs-lisp
;; By default, say, (async-shell-command "date") produces a buffer
;; with the result. In general, such commands in my init.el are for
;; updating/installing things to make sure I have the same up-to-date
;; setup where-ever I use my Emacs. As such, I don't need to see such buffers.
(add-to-list 'display-buffer-alist
'("\\*Async Shell Command\\*.*" display-buffer-no-window))
;; For an approach that does not inhibit async-shell-command this way,
;; see https://emacs.stackexchange.com/questions/299/how-can-i-run-an-async-process-in-the-background-without-popping-up-a-buffer
#+end_src
* TODO Programming
:PROPERTIES:
:CUSTOM_ID: Programming
:END:
Herein we configure utilites for version control, function and variable lookup,
and template expansion for inescapably repetitive scenarios.
TODO: Fix these docs
# TODO: + Checkout branches/PRs with doc : my/gh-checkout
# + See all company related PRs with doc : w-PRs
# + Quickly look up language/library docs /within/ Emacs with kbd:C-c_d.
#+begin_src emacs-lisp
(when my/work-machine?
(setq doom-modeline-buffer-file-name-style 'truncate-except-project))
#+end_src
** COMMENT devdocs
:PROPERTIES:
:CUSTOM_ID: devdocs
:END:
#+begin_src emacs-lisp
;; 1. Get docs of a languages: M-x devdocs-install
;; 2. Lookup docs: [C-u] M-x devdocs-lookup
;; 𝟚. Lookup docs: [C-u] C-c d
(use-package devdocs
:defer nil
:bind ("C-c d" . #'devdocs-lookup)
:config
(when nil ;; “C-x C-e” the following once.
(cl-loop for lang in '(javascript ramda typescript html css sass
vue~3 vuex~4 vue_router~4 "angularjs~1.6"
nginx webpack~5 web_extensions
;;
eslint jest jq jsdoc prettier
mocha chai jasmine
;;
bash docker~19 git homebrew elisp
;;
postgresql~14 redis sqlite
;;
rust ruby~3 minitest "rails~7.0")
do (devdocs-install (list (cons 'slug (format "%s" lang)))))))
#+end_src
** COMMENT How do I do something?
:PROPERTIES:
:CUSTOM_ID: How-do-I-do-something
:END:
When programming, sometimes you just gotta Google “how do I do ⋯”.
- The usual process is (1) open a browser, (2) make a Google query, (3) look
at StackOverflow's most upvoted answer for your query, (4) copy-paste the
code solution/example to your editor; [(5) get distracted by interesting
things you'd like to read].
- Better would be to use the [[https://github.com/gleitz/howdoi][howdoi]] tool, which gives instant coding answers
for common questions via the command line.
- Below, my /Emacs Lisp/ function doc : howdoi let's me reduce the 4-step process
to just 2 steps: Write your query /anywhere/ then call ~M-x howdoi~ on it to
replace the query with the answer. (Or ~C-u M-x howdoi~ to see the full answer
and a link to it on StackOverflow.)
| /⚡ Never open your browser to look for help again ⚡/ |
#+begin_src emacs-lisp
(system-packages-ensure "howdoi")
(cl-defun howdoi (&optional show-full-answer)
"Instantly insert coding answers.
Replace a query with a code solution; replace it with an entire
answer if a prefix is provided.
Example usage:
On a new line, write a question such as:
search and replace buffer Emacs Lisp
Then invoke ‘M-x howdoi’ anywhere on the line
to get a code snippet; or ‘C-u M-x howdoi’ to get a full answer to your query.
"
(interactive "P")
(let ((query (s-collapse-whitespace (substring-no-properties (thing-at-point 'line))))
(flag (if show-full-answer "-a" "")))
(beginning-of-line)
(kill-line)
(insert (shell-command-to-string (format "howdoi %s %s" query flag)))))
#+end_src
** Sleek Semantic Selection
:PROPERTIES:
:CUSTOM_ID: Sleek-Semantic-Selection
:END:
Super sleek way to select regions: Anywhere press kbd:⌘-r to select the current
word, press it again to select sentence, then again for the current paragraph,
then more to get the current section.
#+begin_src emacs-lisp
(use-package expand-region
:bind (("s-r" . #'er/expand-region)))
#+end_src
You can watch an introductory ~3 minute video to expand-region at [[http://emacsrocks.com/e09.html][Emacs Rocks!]].
That is, /repeated ⌘+r expands the selection to the next logical segment of text:/
In writing this means “Word, sentence, paragraph”, and in programming this means
“identifier, then incrementally larger scopes”.
** COMMENT Managing Processes/Servers from within Emacs ---Work-specific functions
:PROPERTIES:
:CUSTOM_ID: Managing-Processes-Servers-from-within-Emacs-Work-specific-functions
:END:
Let's make a few interactive Emacs Lisp functions to reduce the amount of time I
need to be in a terminal. I'll use the /prefix ~“w-”~ for work stuff/. Example
tasks:
+ Start/stop my servers
+ Interactively select an app to be opened in the browser
+ Do database migrations/rollbacks
⟨ Obfuscated with lorem ipsum text. ⟩
[[file:images/services-dashboard.png]]
--------------------------------------------------------------------------------
Not using this, a bit too verbose to setup for each service but, more
accurately, does not Just Workᵀᴹ for my needs.
#+begin_src emacs-lisp
;; “M-x prodigy”, then press “s” to start a service; “S” to stop it; “$” to see it; “r”estart
(use-package prodigy :disabled t)
;; C-h v prodigy-services ⇒ See possible properties.
#+end_src
*** my/defaliases
:PROPERTIES:
:CUSTOM_ID: my-defaliases
:END:
#+begin_src emacs-lisp
(defalias 'defaliases 'my/defaliases)
(defmacro my/defaliases (src &rest tgts)
"Provide names TGTS as synonymous aliases for SRC, for discovarability.
Often a function SRC can be construed from different perspectives, names, purposes TGTS.
Another example is when I define things with the ‘my/’ prefix, but also want to use them without.
Example use: (my/defaliases view-hello-file greet-others learn-about-the-world)
In particular: (my/defaliases OLD NEW) ≈ (defalias 'NEW 'OLD)."
`(--map (eval (quote (defalias `,it (quote ,src)))) (quote ,tgts)))
#+end_src
*** Making unkillable buffers & shells
:PROPERTIES:
:CUSTOM_ID: Making-unkillable-buffers-shells
:END:
#+begin_details "Making unkillable buffers & shells"
#+begin_src emacs-lisp
(defun my/declare-unkillable-buffer (name)
(add-hook 'kill-buffer-query-functions
`(lambda () (or (not (equal (buffer-name) ,name))
(progn (message "Not allowed to kill %s, burying instead; otherwise use “M-x force-kill”" (buffer-name))
(bury-buffer))))))
(my/defaliases my/force-kill force-kill w-force-kill)
(cl-defun my/force-kill (&optional buffer-name)
(interactive)
(-let [kill-buffer-query-functions nil]
(if buffer-name
(kill-buffer buffer-name)
(kill-current-buffer))
(ignore-errors (delete-window))))
(cl-defun my/run-unkillable-shell (command &optional (buffer-name command))
"Example use: (my/run-unkillable-shell \"cd ~/my-noejds-project; npm run dev\" \"my-nodejs-project\")"
(-let [it (get-buffer buffer-name)]
(if it
(switch-to-buffer-other-window it)
(async-shell-command command buffer-name)
(my/declare-unkillable-buffer buffer-name))))
#+end_src
#+end_details
*** w-start/stop-services
:PROPERTIES:
:CUSTOM_ID: w-start-stop-services
:END:
#+begin_src emacs-lisp
(defvar my/services nil "List of all services defined; used with `w-start-services' and `w-stop-services'.")
(defun w-start-services ()
(interactive)
(cl-loop for 𝑺 in my/services
do (funcall (intern (format "w-start-%s" 𝑺)))))
(defun w-stop-services ()
(interactive)
(cl-loop for 𝑺 in my/services
do (funcall (intern (format "w-stop-%s" 𝑺)))))
#+end_src
*** w-status-of-services
:PROPERTIES:
:CUSTOM_ID: w-status-of-services
:END:
#+begin_src emacs-lisp
;; It takes about ~3 seconds to build the Status of Services page, so let's jump to it if it's already built, and the user/me can request a refresh, if need be.
(global-set-key (kbd "M-S-SPC")
(lambda () (interactive)
(-let [buf (get-buffer "Status of Services")] (if buf (switch-to-buffer buf) (w-status-of-services)))))
;;
;; Since M-S-SPC brings up the transient menu, and most commands close the status buffer or are transient, we get the perception that the transient menu is "sticky"; i.e., stuck to the buffer, even though this is not true. I do not yet know how to make a transient menu stuck to a buffer.
;;
#+end_src
#+begin_src emacs-lisp
(defun w-status-of-services ()
"Show me status of all servers, including their current git branch, and most recent emitted output."
(interactive)
(defvar w-status-of-services/branch-name-width 12
"What is the length of the longest branch name? Let's use that to ensure there's enough whitespace.")
(-->
(-let [ shells (--filter (s-starts-with? "Shell" (process-name it)) (process-list)) ]
(cl-loop for 𝑺 in (mapcar #'pp-to-string my/services)
for associated-shell = (--find (s-contains? (format "%s" 𝑺) (cl-third (process-command it))) shells)
for status = (or (ignore-errors (process-status associated-shell)) '💥)
for branch = (-let [default-directory (format "~/%s" 𝑺)]
(magit-get-current-branch))
for _ = (setq w-status-of-services/branch-name-width (max (length branch) w-status-of-services/branch-name-width))
for 𝑺-buffer = (--find (s-starts-with? (format "*Server:%s" 𝑺) it) (mapcar 'buffer-name (buffer-list)))
for saying = (let (most-recent-shell-output (here (current-buffer)))
(if (not 𝑺-buffer)
" ─Server not started─ "
(switch-to-buffer 𝑺-buffer)
(end-of-buffer)
(beginning-of-line)
(setq most-recent-shell-output (or (thing-at-point 'line t) ""))
(switch-to-buffer here)
;; FIXME:here
(--> (s-truncate 135 (s-trim most-recent-shell-output))
(if (s-contains? "|" it)
(cl-second (s-split "|" it))
it)
(s-trim it)
(if (<= (length it) 3) (s-repeat 70 " ") it))))
for _ = (if (or (s-contains? "Error" saying) (not 𝑺-buffer)) (setq status '💥))
for keymap = (copy-keymap org-mouse-map)
do (cl-loop for (key action)
on `( ;; Checkout branch/PR
c (w-pr-checkout (format "~/%s" ,𝑺))
;; Restart service, remaining on current branch [not switching to “main”!]
r (-let [current-prefix-arg t]
(funcall (intern (format "w-stop-%s" ,𝑺)))
(funcall (intern (format "w-start-%s" ,𝑺))))
f (-let [default-directory (format "~/%s" ,𝑺)]
(call-interactively #' projectile-find-file))
t (vterm-shell-command (format "clear; cd ~/%s; git status" ,𝑺) (format "vterm/%s" ,𝑺))
;; See the repo in the web
w (--> (format "%s" ,𝑺)
(if (s-contains? "/" it) (f-parent it) it)
(format "https://github.com/%s/%s" work/gh-user it)
(browse-url it))
;; Visit service shell
(when ,𝑺-buffer
(delete-other-windows)
(split-window-below)
(switch-to-buffer ,𝑺-buffer)
(end-of-buffer)
(other-window 1))
;; See service magit buffer
(progn (magit-status (format "~/%s" ,𝑺)) (delete-other-windows)))
by #'cddr
do (define-key keymap (kbd (format "%s" key))
`(lambda () (interactive) ,action)))
collect
;; “%𝑾s” ⇒ Print a string with at least width 𝑾: If length(str) ≤ 𝑾, then pad with spaces on the left side.
;; Use “%-𝑾s” to instead pad with spaces to the right.
(list keymap (format (format "%%s %%-20s %%-%ss %%s" (+ 5 w-status-of-services/branch-name-width)) status 𝑺 branch saying))))
;; Setup buffer
(-let [buf "Status of Services"]
(ignore-errors (kill-buffer buf))
(switch-to-buffer buf)
(delete-other-windows)
it)
;; Insert out buttons
(--each it
;; https://www.gnu.org/software/emacs/manual/html_node/elisp/Overlay-Properties.html
(-let [help (s-join "\n"
'("Keybindings:"
"[C-u] c ∷ Checkout PR [or branch] \t\t\t b ∷ Browse an app"
"tab ∷ See service magit buffer \t\t\t i ∷ Inject users"
"return ∷ Visit service shell \t\t\t s ∷ SQL buffer"
"r ∷ Restart service \t\t\t w ∷ See the repo in the web"
"f ∷ Find file in project \t\t\t t ∷ Terminal"
"g ∷ Refresh this view \t\t\t q ∷ Quit, and kill, this buffer"))]
(insert-text-button (s-replace "\"" "″" (s-replace "run" "✅" (nth 1 it)))
'face nil
;; 'mouse-face '(:box t) ;; I use the cursor more than the mouse, so don't want two distinct views.
'keymap (nth 0 it)
;; NOTE: The functions are called only when the minor mode cursor-sensor-mode is turned on.
;; When cursor enters the button, we temporarily make it a box and show shortcuts in message area.
'cursor-sensor-functions `((lambda (_ old-pos entered?)
(message ,help)
(setq entered? (equal entered? 'entered))
(-let [self (button-at (if entered? (point) old-pos))]
(read-only-mode 0) ;; Temporarily disable help-mode's read-only-mode setup.
(if entered?
(button-put self 'face '(:box "yellow" :weight bold))
(button-put self 'face nil)))))
'help-echo help)
(insert "\n")))
;; Do some highlighting, as a cautionary measure.
(highlight-regexp ".*crashed.*" 'hi-red-b)
;; Forbid editing
(help-mode) ;; This wont do the button face changes I like when cursor moves; so I disable read-only-mode temporarily when making the changes.
(cursor-sensor-mode)
(stripe-buffer-mode)
(visual-line-mode -1)
(toggle-truncate-lines)
;; Add some specific work related bindings
(local-set-key "b" #'w-browse-app)
(local-set-key "i" #'w-inject-users)
(local-set-key "s" (lambda () (interactive) (w-sql) (delete-other-windows)))
;; Add general view keys
(local-set-key "g" (lambda () "Refresh this view" (interactive) (ignore-errors (kill-buffer-and-window)) (w-status-of-services)))
(local-set-key "q" (lambda () "Quit buffer" (interactive) (ignore-errors (kill-buffer-and-window))))
;; Go to the first entry, so my “homemade echo menu” appears.
(beginning-of-buffer)))
#+end_src
**** COMMENT Old definition with colourful menu :ignore:
:PROPERTIES:
:CUSTOM_ID: COMMENT-Old-definition-with-colourful-menu
:END:
#+begin_src emacs-lisp
(defun w-status-of-services ()
"Show me status of all servers, including their current git branch, and most recent emitted output."
(interactive)
(thread-last
(-let [ shells (--filter (s-starts-with? "Shell" (process-name it)) (process-list)) ]
(cl-loop for 𝑺 in (mapcar #'pp-to-string my/services)
for associated-shell = (--find (s-contains? (format "%s" 𝑺) (cl-third (process-command it))) shells)
for status = (or (ignore-errors (process-status associated-shell)) '💥)
for branch = (-let [default-directory (format "~/%s" 𝑺)]
(magit-get-current-branch))
for saying = (let (most-recent-shell-output (here (current-buffer)))
(switch-to-buffer (--find (s-starts-with-p 𝑺 (buffer-name it)) (buffer-list)))
(end-of-buffer)
(beginning-of-line)
(setq most-recent-shell-output (or (thing-at-point 'line t) ""))
(switch-to-buffer here)
(s-truncate 135 (s-trim most-recent-shell-output)))
collect
;; “%𝑾s” ⇒ Print a string with at least width 𝑾: If length(str) ≤ 𝑾, then pad with spaces on the left side.
;; Use “%-𝑾s” to instead pad with spaces to the right.
(format "%s %-20s %-12s %s" status 𝑺 branch
(-let [it (s-trim (if (s-contains? "|" saying)
(cl-second (s-split "|" saying))
saying))]
(if (<= (length it) 3) "-" it)))))
(--map (format "%s" it))
(s-join "\n")
(s-replace "run" "✅")
(funcall (lambda (it) (-let [max-mini-window-height 0]
(ignore-errors (kill-buffer "Status of Services"))
(display-message-or-buffer it "Status of Services")
(delete-other-windows)
(switch-to-buffer "Status of Services")
(highlight-regexp ".*crashed.*" 'hi-red-b)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Start describing the keys
(end-of-buffer)
(insert "\n \n \n \n \n")
(let ((register-action (lambda (key-desc-actions)
(if (stringp key-desc-actions)
(propertize key-desc-actions 'font-lock-face '(face success))
(-let [ [key desc &rest actions] key-desc-actions ]
;; For buffer-local keys, you cannot use local-set-key, unless you want to modify the keymap of the entire major-mode in question: local-set-key is local to a major-mode, not to a buffer.
;; (use-local-map (copy-keymap text-mode-map))
(local-set-key key `(lambda () (interactive) ,@(seq-into actions 'list)))
(format "%s %s"
(propertize (format "%s" key) 'font-lock-face '(face error))
(propertize desc 'font-lock-face '(:foreground "grey")))))))
(repo-at-point (lambda () (-as-> (beginning-of-line) repo
(thing-at-point 'line t)
(s-split " " repo)
cl-second))))
(insert (s-join "\n" (seq-mapn (lambda (&rest cols) (apply #'format (s-repeat (length cols) "%-40s ")
(--map (funcall register-action it) cols)))
["This view"
["g" "Refresh this view" (ignore-errors (kill-buffer-and-window)) (w-status-of-services)]
["q" "Quit buffer" (ignore-errors (kill-buffer-and-window))]
["" "" ""]]
`["Current service"
["c" "Checkout PR" (w-pr-checkout (format "~/%s" (funcall ,repo-at-point)))]
[[return] "Visit service shell"
(delete-other-windows)
(split-window-below)
(switch-to-buffer (--find (s-starts-with? (funcall ,repo-at-point) (buffer-name it)) (buffer-list)))
(end-of-buffer)
(other-window 1)]
[[tab] "See service magit buffer"
(magit-status (format "~/%s" (funcall ,repo-at-point)))
(delete-other-windows)]]
["Misc"
["b" "Browse an app" (w-browse-app)]
["i" "Inject users" (w-inject-users)]
["s" "SQL buffer" (w-sql) (delete-other-windows)]]))))
(beginning-of-buffer)
;; (help-mode) ;; For some reason, default fundamental-mode does not regoznise proprtised strings.
;; Also, this is read-only be default and emits a nice message for undefiend single key bindings.
;; (help-mode)
)))))
#+end_src
*** my/defservice
:PROPERTIES:
:CUSTOM_ID: my-defservice
:END:
#+begin_src emacs-lisp
;; Even though I'm doing frequent prunes, it helps to give docker some leeway.
;; NOTE: Docker Icon → Preferences → Resources → 4 CPUs; 8gb Memory; 2gb Swap; 120 DiskImageSize.
(cl-defmacro my/defservice
(repo &key (main-setup "git checkout main; git pull; git status; hr; npm ci; hr; time docker system prune -af")
(cmd "npm run docker:dev")
(example ""))
"Example use:
(my/defservice 𝒟 :cmd 𝒞 :example ℰ)
⇒
(w-start-𝒟) ≈ Unkillable shell: cd 𝒟; 𝒞
(w-is-up-𝒟?) ≈ Open browser at ℰ
(w-stop-𝒟) ≈ Kill all emacs-buffers & docker-images containing 𝒟 in their name
(w-[start|stop]-services) ⇒ Starts/stops all defined services."
(add-to-list 'my/services repo)
`(list
(cl-defun ,(intern (format "w-start-%s" repo)) ()
"Start server off of ‘main’, with prefix just start server off of current branch."
(interactive)
(let ((command (format "cd ~/%s; pwd; hr; %s; hr; %s"
(quote ,repo)
(if current-prefix-arg "" ,main-setup)
,cmd))
(buf-name (format "*Server:%s/%s*" (quote ,repo)
(if current-prefix-arg "main"
(-let [default-directory ,(format "~/%s" repo)]
(magit-get-current-branch))))))
(my/run-unkillable-shell
(format "echo %s; hr; %s" (pp-to-string command) command) ;; Show command being run in output buffer, then run that command
buf-name)
(with-current-buffer buf-name (read-only-mode))))
(cl-defun ,(intern (format "w-stop-%s" repo)) ()
"Force-kill all unkillable buffers that mention REPO in their name. Also stop any docker services mentioning REPO in their name."
(interactive)
(my/docker-stop ,(pp-to-string repo))
(thread-last (buffer-list)
(mapcar 'buffer-name)
(--filter (s-contains-p ,(pp-to-string repo) it))
(mapcar #'my/force-kill)))
(if ,example
(cl-defun ,(intern (format "w-is-up-%s?" repo)) ()
(interactive)
(browse-url ,example)
(message "If the URL is busted, then the repo is not up correctly or the server has an error!")))))
#+end_src
In my private ~work.el~ I have declarations of the form ~(my/defservice ⟨directory⟩
:cmd "npm run dev" :example "Example URL to try out for this server")~.
#+begin_src emacs-lisp
(when my/work-machine?
(load-file "~/Desktop/work.el"))
#+end_src
** Project management & navigation
:PROPERTIES:
:CUSTOM_ID: Project-management-navigation
:END:
Version controlled repositories are considered “projects” ---no setup needed---,
but you can declare your own too.
Videos:
+ ~5mins: https://youtu.be/bFS0V_4YfhY
+ ~1hr: https://www.youtube.com/watch?v=INTu30BHZGk
This is so sweet at work (and possibly at home!): From anywhere,
+ [[kbd:C-x p p]] ⟨select your project⟩ RET ⟨start typing to see any file anywhere in the project⟩
+ [[kbd:C-x p b ]] ⇒ Switch to buffers only in the current “stream of thought” (project).
+ [[kbd:C-x p f ]] ⇒ Find files only in the current “stream of thought” (project).
+ [[kbd:C-x p s g ]] ⇒ Search the project using grep; TAB in the resulting buffer to
open files.
+ [[kbd:C-x p S ]] ⇒ Save all project buffers
+ [[kbd:C-x p k ]] ⇒ Kill all buffers relating to the parent project
+ [[kbd:C-x p & ]] ⇒ Runs an async-shell-command in the project's root directory
+ [[kbd:C-x p x s ]] ⇒ Start or visit a shell for the project
+ [[kbd:C-x p r ]] ⇒ Runs interactive query-replace on all files in the projects
+ [[kbd:C-x p e ]] ⇒ Show a list of recently visited files, in the current project
+ [[kbd:C-x p V ]] ⇒ Open a project that has been modified, but not pushed with version control.
#+begin_src emacs-lisp
;; More info & key bindings: https://docs.projectile.mx/projectile/usage.html
(use-package projectile
:config
(projectile-mode +1)
(define-key projectile-mode-map (kbd "C-x p") 'projectile-command-map)
;; Replace usual find-file with a project-wide version :smile:
(global-set-key (kbd "C-x f") #'projectile-find-file)
;; Makes indexing large projects much faster, after first time.
;; Since its caching, some files may be out of sync; you can delete the cache
;; with: C-u C-x f
(setq projectile-enable-caching t))
(use-package projectile
:config
(define-key projectile-mode-map (kbd "C-x p s")
;; I prefer helm-do-grep-ag since it shows me a live search
(lambda () (interactive)
(let ((default-directory (car (projectile-get-project-directories (projectile-acquire-root)))))
;; (shell-command-to-string "echo $PWD")
(helm-do-grep-ag nil))))) ;; “p”roject “s”earch
#+end_src
Let's get the file path of the current file. We bind it and make it a top-level invokable function.
#+begin_src emacs-lisp
(use-package projectile
:defer nil
:config
(define-key projectile-mode-map (kbd "C-x p c")
(defun my/copy-current-file-path ()
"Add current file path to kill ring."
(interactive)
(message (kill-new buffer-file-name)))))
#+end_src
** TODO Projectile
:PROPERTIES:
:CUSTOM_ID: Projectile
:END:
#+begin_src emacs-lisp
;; https://cestlaz.github.io/posts/using-emacs-33-projectile-jump/
;; https://github.com/bbatsov/projectile
(use-package projectile
:config (projectile-global-mode)
(define-key projectile-mode-map (kbd "s-p") 'projectile-command-map))
#+end_src
** TODO COMMENT Are there any errors in my code?
:PROPERTIES:
:CUSTOM_ID: Are-there-any-errors-in-my-code
:END:
[[https://www.flycheck.org/en/latest/][Flycheck]] gives us syntax checking and linting tools to automatically check the
contents of buffers while you type, and reports warnings and errors directly in
the buffer, or in an optional error list. Sadly, the default reporting of errors
looks like ~FlyC 3~ in the modeline, but with [[https://github.com/liblit/flycheck-status-emoji][flycheck-status-emoji]] we can see the
status using cute & compact emoji such as ~😱3~.
#+begin_src emacs-lisp
(use-package flycheck-status-emoji
:defer nil
:config
(load-library "flycheck-status-emoji")
;; (diminish-undo 'flycheck-mode)
(flycheck-status-emoji-mode))
#+end_src
Let's also have a nifty modal menu to quickly navigate between errors.
#+begin_src emacs-lisp
(use-package helm-flycheck :defer nil)
(bind-key*
"C-c !"
(defhydra my/flycheck-hydra (:color blue :hint nil)
"Move around flycheck errors and get info about them"
("n" flycheck-next-error "next" :column "Navigation")
("p" flycheck-previous-error "previous")
("f" flycheck-first-error "first")
("l" flycheck-list-errors "list")
("h" helm-flycheck "helm") ;; Jump to an error / see-errors from a nice interactive menu
("e" flycheck-explain-error-at-point "explain" :column "Current errror")
("c" flycheck-copy-errors-as-kill "copy")
("d" flycheck-describe-checker "Describe checker" :column "More")
("s" flycheck-select-checker "Select checker")
("S" flycheck-verify-setup "Suggest setup")
("m" flycheck-manual "manual")))
#+end_src
*** On the fly syntax checking
:PROPERTIES:
:CUSTOM_ID: On-the-fly-syntax-checking
:END:
[[https://www.flycheck.org/en/latest/][Flycheck]] is a on-the-fly syntax checker that relies on external programs to
check buffers; which must be installed separately.
+ E.g., ghc is required for Haskell; whereas Emacs Lisp is checked by Emacs'
own byte compiler, ~emacs-lisp~.
+ Sometimes more than one checking tool applies, use ~C-c ! s~ to select a
different checker.
+ =C-c ! n,p,l= takes you to the ‘n’ext or ‘p’revious
error, or ‘l’ist all errors in another buffer.
~C-c ! c~ to explicitly recheck the buffer.
#+begin_src emacs-lisp
(use-package flycheck
:defer nil
:init (global-flycheck-mode)
:config ;; There may be multiple tools; I have GHC not Stack, so let's avoid that.
(setq-default flycheck-disabled-checkers '(haskell-stack-ghc emacs-lisp-checkdoc))
:custom (flycheck-display-errors-delay .3))
#+end_src
In an org-src block, we press ~C-c '~ to get into the language's mode where
flycheck will provide warnings.
#+begin_src haskell :tangle no
module Main where
main :: IO ()
main = putStrLn $ "nice" ++ f 0
f :: Int -> String
f x = x -- show x
-- type error
#+end_src
In-general, flycheck is intended for self-contained raw code ---not for source
blocks in Org-mode. Whence, the above example is a complete Haskell program,
with a named module and ~main~ method.
I think the built-in [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Flymake.html][flymake]] syntax checker is better for Emacs Lisp,
so let's use that for ELisp.
#+BEGIN_SRC emacs-lisp
(use-package flymake
:defer nil
:hook ((emacs-lisp-mode . (lambda () (flycheck-mode -1)))
(emacs-lisp-mode . flymake-mode))
:bind (:map flymake-mode-map
("C-c ! n" . flymake-goto-next-error)
("C-c ! p" . flymake-goto-prev-error)))
#+END_SRC
Try it out:
#+begin_src emacs-lisp :tangle no
(setq 1 2) ;; Error: ‘1’ is not a variable.
#+end_src
** COMMENT Jumping to definitions & references
:PROPERTIES:
:CUSTOM_ID: Jumping-to-definitions-references
:END:
Out-of-the-box Emacs has ‘xref’ utilities ~M-.~ and ~C-u M-.~ to [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html#Xref][Find Identifier
References]]; however, tags to source definitions need to be generated using the
=etags= program. Nonetheless, the xref utilites are impressive and some just work:
For example, ~M-?~ cleverly finds /all/ references for an identifier in ‘near by’
files; whereas ~C-u M-. RET my/.*~, for example, uses the given regular expression
to list all identifiers with prefix ~my/~, thereby listing my personally defined
names ^_^
| =C-M-. 𝓇𝓮ℊ𝓮𝓍= | Find all identifiers whose name matches the given pattern |
Let's get [[https://github.com/jacktasia/dumb-jump][dumb-jump]], where the ‘dumb’ is possibly due to the fact
that it works by brute-force regular-expression lookup of
pre-defined ‘definitional template’ rules. It “just works” ^_^
#+BEGIN_SRC emacs-lisp
(use-package dumb-jump
:defer nil
:bind (("M-g q" . dumb-jump-quick-look) ;; Show me in a tooltip.
("M-g ." . dumb-jump-go-other-window)
("M-g b" . dumb-jump-back)
("M-g p" . dumb-jump-go-prompt)
("M-g a" . xref-find-apropos)) ;; aka C-M-.
:config
;; If source file is visible, just shift focus to it.
(setq dumb-jump-use-visible-window t))
#+END_SRC
In Lisp, for binding macros, it lists all possible mentions of the bound
variable ---the first is likely what is desired. Alternatively, one could just
add the necessary rule to the variable =dumb-jump-find-rules=. Otherwise, it
works fine even for locally bound definitions. It works depending on the
extension of a file.
** COMMENT Which function are we writing?
:PROPERTIES:
:CUSTOM_ID: Which-function-are-we-writing
:END:
In the modeline, show the name of the function we're currently writing.
#+BEGIN_SRC emacs-lisp
(add-hook 'prog-mode-hook #'which-function-mode)
(add-hook 'org-mode-hook #'which-function-mode)
#+END_SRC
In Org-mode, this places the current heading in the modeline.
In Lisp mode, ensure we always have matching parens.
#+BEGIN_SRC emacs-lisp
(add-hook 'emacs-lisp-mode-hook #'check-parens)
#+END_SRC
** COMMENT Highlight defined Lisp symbols
:PROPERTIES:
:CUSTOM_ID: Highlight-defined-Lisp-symbols
:END:
Usually Emacs only highlights macro names, the [[https://github.com/Fanael/highlight-defined][following]] incantation makes it
highlight all defined names ---as long as we're in Lisp mode, whence in org-src
blocks we use ~C-c '~.
#+BEGIN_SRC emacs-lisp
;; Emacs Lisp specific
(use-package highlight-defined
:defer nil
:hook (emacs-lisp-mode . highlight-defined-mode))
#+END_SRC
Super helpful in making my Emacs configuration: If a name is not highlighted,
then I've misspelled it or it doesn't exist! :smile:
** TODO Aggressive Indentation :Broken_Subsection:
:PROPERTIES:
:CUSTOM_ID: Aggressive-Indentation
:END:
With a single space or tab, my code should always remain indented.
[[https://github.com/Malabarba/aggressive-indent-mode][aggressive-indent-mode]] is a minor mode that keeps your code always indented. It
reindents after every change, making it more reliable than electric-indent-mode.
#+BEGIN_SRC emacs-lisp
;; Always stay indented: Automatically have blocks reindented after every change.
(use-package aggressive-indent
:defer nil
:config (global-aggressive-indent-mode t))
;; Use 4 spaces in places of tabs when indenting.
(setq-default indent-tabs-mode nil)
(setq-default tab-width 4)
#+END_SRC
This mode requires my Lisp forms to be well-balanced; e.g., having a missing
parenthesis does not indent. For instance, I have a form ~F~ and I write ~(when F~
but have not yet enclosed the final parens, I still want nice indentation. So...
*** TODO [[https://github.com/jiahaowork/el-fly-indent-mode.el][Indent Emacs Lisp on the fly]] :Disabled:Breaks_C_c_C_v_C_t:
:PROPERTIES:
:CUSTOM_ID: https-github-com-jiahaowork-el-fly-indent-mode-el-Indent-Emacs-Lisp-on-the-fly
:END:
#+begin_src emacs-lisp :tangle no
;; This minor mode toggles on along with elisp-mode and indents on the fly when
;; you edit the code. No special key strokes needed.
;; Demo: https://www.youtube.com/watch?v=zrFmfFZfj-A&ab_channel=JiahaoLi
(use-package el-fly-indent-mode
:defer nil
:config (add-hook 'emacs-lisp-mode-hook #'el-fly-indent-mode))
#+end_src
** COMMENT Being Generous with Whitespace
:PROPERTIES:
:CUSTOM_ID: Being-Generous-with-Whitespace
:END:
The following minor mode automatically adds spacing around operators.
#+begin_src emacs-lisp
(use-package electric-operator
:defer nil
:hook (c-mode . electric-operator-mode))
#+end_src
I dislike it when users write ~x=y+1~ ---whitespace is free and helpful. ⟨ Also,
languages with arbitrary identifiers, like Lisp and Agda, would accept ~x=y+1~ as
an identifier, not an expression! ⟩
** Coding with a Fruit Salad: Semantic Highlighting
:PROPERTIES:
:CUSTOM_ID: Coding-with-a-Fruit-Salad-Semantic-Highlighting
:END:
What should be highlighted when we write code? Static keywords with fixed uses,
or dynamic user-defined names?
+ /Syntax/ highlighting ⇨ Specific words are highlighted in strong colours so that
the /structure/ can be easily gleaned.
- Generally this only includes a language's keywords, such as ~if, loop, begin,
end, cond~.
- User defined names generally share one colour; usually black.
- Hence, an ~if~ block may be seen as one coloured keyword followed by
a blob of black text.
/Obvious keywords are highlighted while the rest remains in black!/
+ /Semantic/ highlighting ⇨ Identifiers obtain unique colouring.
- This makes it much easier to visually spot dependencies with a quick glance.
+ One can *see* how data flows through a function.
- In dynamic languages, this is a visual form of typing: Different colours are
for different names.
+ Especially helpful for (library) names that are almost the same.
+ This can be accomplished anywhere in Emacs by pressing ~M-s h .~ on
a selected phrase.
For Emacs, [[https://github.com/ankurdave/color-identifiers-mode][Color Identifiers Mode]] gives unique highlighting to identifiers.
- It comes with support for a bunch of languages, and one can add support for others.
- It picks colours adaptively to fit the theme; one uses ~M-x color-identifiers:regenerate-colors~ after a theme change.
#+begin_src emacs-lisp
(use-package color-identifiers-mode
:config (global-color-identifiers-mode))
;; Sometimes just invoke: M-x color-identifiers:refresh
#+END_SRC
When writing a new name, after about ~5 seconds it obtains a colour which is then
propagated immediately to any new occurrences. This timeout before recolouring
is to avoid any lag from multithreading and can be changed by altering the following
line (#64) in the source file, changing the ~5~ to a smaller number.
#+BEGIN_SRC emacs-lisp :tangle no
(run-with-idle-timer 5 t 'color-identifiers:refresh)
#+END_SRC
Here are further reads:
- [[https://medium.com/@evnbr/coding-in-color-3a6db2743a1e][Coding in color: How to make syntax highlighting more useful]] ---an excellent, terse, read
- [[https://zwabel.wordpress.com/2009/01/08/c-ide-evolution-from-syntax-highlighting-to-semantic-highlighting/][C++ IDE Evolution: From Syntax Highlighting to Semantic Highlighting]]
+ Names with a similar prefix share a colour, and class-local items share a colour.
- [[https://wordsandbuttons.online/lexical_differential_highlighting_instead_of_syntax_highlighting.html][Lexical differential highlighting instead of syntax highlighting]]
+ /Ideally, the smaller the lexical difference, the greater the color difference should be./
- [[https://github.com/jacksonrayhamilton/context-coloring][Colouring by Context]] ---an Emacs package
- [[http://www.linusakesson.net/programming/syntaxhighlighting/][A case against syntax highlighting]]
** TODO Text Folding ---Selectively displaying portions of a program :causes_HIDING_ALL_BLOCKS_issue:
:PROPERTIES:
:CUSTOM_ID: Text-Folding
:END:
⟦‼ TODO: hideshowvis shows ="*hideshowvis*"= literally in src code blocks upon
export; as such we need to hook to exports so as to temporarily disable it. ⟧
Literate programming within Org-mode is not always ideal or possible, so we use
a programming mode directly and then may want to have arbitrary ‘sections’ of
text folded up. Let's describe how to accomplish this goal. I've tried the
feature-full folding modes [[https://github.com/gregsexton/origami.el][Origami-mode]] and ~yafolding-mode~, but it seems the
/built-in/ TODO. doc.hs-minor-mode is the best: (0) It folds comments, (1) it's the
fastest, and (2) it Just Worksᵀᴹ out-of-the-box. Coupled with Vimish folding,
for arbitrary region folding; and a helpful hydra, I'm rather happy with my
setup.
On two JavaScript files, I found the following timings (using TODO. doc.elp-instrument-function
and TODO. doc.elp-results):
| Folding function | ~500 lines | ~2300 lines |
|-------------------------+------------+-------------|
| hs-hide-all | 0.00277 | 0.004358 |
| origami-close-all-nodes | 0.00304 | 0.025569 |
| yafolding-hide-all | 7.051795 | 74.252598 |
(TODO: Maybe these timings are due to my config, I should try to reproduce these
with ~emacs -Q~.)
#+begin_box "There's a built-in, less featureful, alternative based on indentation!"
Quickly fold-away code with TODO. doc.set-selective-display; e.g.,
folds away all code indented 4 spaces, whereas is for 8
spaces, and disables the folding. This is built into Emacs.
I've incorporated this into my folding hydra, below.
#+end_box
#+begin_box "Vimish fold - Fold regions based on selection, not syntax"
Sometimes we want to fold some random piece of text ---rather than fold accoding
to a programming language's syntactic constructions.
[[https://github.com/mrkkrp/vimish-fold][Vimish-fold]] gives us just that and with many fancy features, from the README:
+ folding of active regions;
+ good visual feedback: it's obvious which part of text is folded with a ‘⋮’ in the fringe.
+ create folds from regions between ~{{{~ and ~}}}~ automatically (marks are customizable; TODO. doc.vimish-fold-from-marks);
+ persistence by default: when you kill a buffer your folds don't disappear;
+ persistence scales well, you can work on hundreds of files with lots of folds without adverse effects;
+ it does not break indentation;
+ folds can be toggled from folded state to unfolded and back very easily;
+ quick navigation between existing folds;
+ you can use mouse to unfold folds (good for beginners and not only for them).
#+begin_src emacs-lisp
(use-package vimish-fold
:config (vimish-fold-global-mode 1))
#+end_src
#+end_box
*** TODO Actual Setup :ignore:
:PROPERTIES:
:CUSTOM_ID: Actual-Setup
:END:
--------------------------------------------------------------------------------
TODO: Below I setup hideshow along with [doc : hideshowvis-symbols] [hideshowvis] which gives us a nice clickable
“+/-” marker for foldable blocks as well as an overlay that indicates how many
lines are folded away. For more on hideshow-mode, see the [[https://writequit.org/denver-emacs/presentations/2017-11-02-hidden-gems.html][Hidden Gem Packages]]
presentation which contains a small self-contained introduction, or [[https://github.com/emacs-mirror/emacs/blob/master/lisp/progmodes/hideshow.el#L127][these super useful source comments]]
which discuss hooks and support for special modes ([[https://superuser.com/questions/576447/enable-hideshow-for-more-modes-e-g-ruby][like this one]]).
#+BEGIN_SRC emacs-lisp
(use-package hideshow
:defer nil
:init
;; https://github.com/emacsmirror/emacswiki.org/blob/master/hideshowvis.el
(quelpa '(hideshowvis :fetcher wiki))
;; Press “C-c TAB” to toggle a block's visibility or “C-c f” for my folding hydra.
:bind (("C-c TAB" . hs-toggle-hiding))
;; https://github.com/shanecelis/hideshow-org/tree/master
;; This extension bring Org-mode tab behaviour to folding, at the block level
;; and buffer level ---but not cycling visibility.
;; (use-package hideshow-org) ;; Disabled as commented below.
:hook ((prog-mode . (lambda () (hs-minor-mode +1)
(hideshowvis-minor-mode t)
(hideshowvis-symbols)
;; This hook along with hs-org mode breaks editing of src blocks in Org files.
;; That's OK, since my folding hydra does a better job for my needs.
;; (hs-org/minor-mode t)
(hs-hide-all)))))
#+END_SRC
Along with a hydra for super quick navigation and easily folding, unfolding
blocks! Love this one (•̀ᴗ•́)و
#+BEGIN_SRC emacs-lisp
(my/defhydra "C-c f" "Folding text" archive
:Current
("h" hs-hide-block "Hide")
("s" hs-show-block "Show")
("t" hs-toggle-hiding "Toggle")
;; "l" hs-hide-level "Hide blocks n levels below this block"; TODO: Enable folding feature
:Buffer
("H" hs-hide-all "Hide")
("S" hs-show-all "Show")
("T" my/hs-toggle-buffer "Toggle")
:Style
("i" my/clever-selective-display "Fold along current indentation" :toggle selective-display)
("e" auto-set-selective-display-mode "Explore; walk and see" :toggle t)
:Region
("f" (lambda () (interactive) (vimish-fold-toggle) (vimish-fold (region-beginning) (region-end))) "Fold/Toggle")
("d" vimish-fold-delete "Delete fold")
("U" vimish-fold-unfold-all "Unfold all")
("D" vimish-fold-delete-all "Delete all")
("n" vimish-fold-next-fold "Next fold")
("p" vimish-fold-previous-fold "Previous fold")
:...
("w" hl-todo-occur "Show WIPs/TODOs" :exit t)
("m" lsp-ui-imenu "Menu of TLIs" :exit t) ;; TLI ≈ Top Level Items
;; ("i" imenu-list "iMenu (General)") ;; It seems the above is enough for both prog and otherwise.
("r" (progn (hs-minor-mode -1) (hs-minor-mode +1)) "Reset Hideshow") ;; Remove all folds from the buffer and reset all hideshow-mode. Useful if it messes up!
("q" nil "Quit" :color blue))
;; Features from origami/yafolding that maybe I'd like to implement include:
;; narrowing to block or folding everything except block, navigating back and forth between folded blocks.
;; Finally, if we want to cycle the visibility of a block (as in Org-mode), we can use a combination of hs-show-block and hs-hide-level.
#+END_SRC
#+begin_details "Folding Hydra Helpers"
#+BEGIN_SRC emacs-lisp
(defvar my/hs-hide nil "Current state of hideshow for toggling all.")
(defun my/hs-toggle-buffer () "Toggle hideshow all."
(interactive)
(setq my/hs-hide (not my/hs-hide))
(if my/hs-hide
(hs-hide-all)
(hs-show-all)))
#+END_SRC
#+BEGIN_SRC emacs-lisp
(defun my/clever-selective-display (&optional level)
"Fold text indented same of more than the cursor.
This function toggles folding according to the level of
indentation at point. It's convenient not having to specify a
number nor move point to the desired column.
"
(interactive "P")
(if (eq selective-display (1+ (current-column)))
(set-selective-display 0)
(set-selective-display (or level (1+ (current-column))))))
#+END_SRC
#+BEGIN_SRC emacs-lisp
;; Src: https://emacs.stackexchange.com/questions/52588/dynamically-hide-lines-indented-more-than-current-line
(define-minor-mode auto-set-selective-display-mode
"Automatically apply `set-selective-display' at all times based on current indentation."
nil "$" nil
(if auto-set-selective-display-mode
(add-hook 'post-command-hook #'auto-set-selective-display nil t)
(remove-hook 'post-command-hook #'auto-set-selective-display t)
(with-temp-message ""
(set-selective-display nil))))
;;
(defun auto-set-selective-display ()
"Apply `set-selective-display' such that current and next line are visible.
Scroll events are excluded in order to prevent wild flickering while navigating."
(unless (eq last-command #'mwheel-scroll)
(let*((this-line-indent (current-indentation))
(next-line-indent (save-excursion (forward-line) (current-indentation))))
(with-temp-message "" ; Suppress messages.
(set-selective-display (1+ (max this-line-indent next-line-indent)))))))
#+END_SRC
#+end_details
With expected support for searching.
#+BEGIN_SRC emacs-lisp
;; Open folded nodes if a search stops there.
(add-hook 'helm-swoop-after-goto-line-action-hook #'my/search-hook-function)
(defun my/search-hook-function ()
(when hs-minor-mode (set-mark-command nil) (hs-show-block) (pop-to-mark-command)))
#+END_SRC
#+begin_details "What if I want my own hideshow overlays, instead of hideshowvis?"
#+BEGIN_SRC emacs-lisp :tangle no
;; Add an overlay to display the number of hidden lines 😁;; https://github.com/shanecelis/hideshow-org/tree/master
(setq hs-set-up-overlay
(defun my-display-code-line-counts (ov)
(when (eq 'code (overlay-get ov 'hs))
(overlay-put ov 'display
(propertize
(format " ... ﴾%d﴿"
(count-lines (overlay-start ov)
(overlay-end ov)))
'face 'font-lock-type-face)))))
#+END_SRC
#+end_details
#+begin_details "[Disabled / Alternative] origami"
#+BEGIN_SRC emacs-lisp :tangle no
(use-package origami
;; In Lisp languages, by default only function definitions are folded.
;; :hook ((agda2-mode lisp-mode c-mode) . origami-mode)
;; Please open any code with top level items folded away.
:hook (prog-mode . (lambda () (interactive)
(origami-close-all-nodes (current-buffer))))
;; MA: It seems that this is not ideal; it takes a bit longer than I'd like to fold the whole file.
:config
;; For any major-mode that doesn't have explicit support, origami will use the
;; indentation of the buffer to determine folds.
(global-origami-mode)
;; With basic support for one of my languages.
(push '(agda2-mode . (origami-markers-parser "{-" "-}"))
origami-parser-alist))
#+END_SRC
With expected support for searching.
#+BEGIN_SRC emacs-lisp :tangle no
(defun my/search-hook-function ()
(when origami-mode (origami-open-node-recursively (current-buffer) (point))))
;; Open folded nodes if a search stops there.
(add-hook 'helm-swoop-after-goto-line-action-hook #'my/search-hook-function)
;;
;; Likewise for incremental search, isearch, users.
;; (add-hook 'isearch-mode-end-hook #'my/search-hook-function)
#+END_SRC
And hydra...
#+BEGIN_SRC emacs-lisp :tangle no
(my/defhydra "C-c f" "Folding text" archive
:Current
("h" origami-close-node-recursively "Hide")
("s" origami-open-node-recursively "Show")
("c" origami-recursively-toggle-node "Cycle") ;; Acts like org-mode header collapsing. Cycle a fold between open, recursively open, closed.
("f" origami-show-only-node "Focus") ;; Close everything but the folds necessary to see the point. Very useful for concentrating on an area of code.
;; ("H" origami-close-all-nodes "Hide All")
;; ("S" origami-open-all-nodes "Show All")
:Navigate
("n" origami-next-fold "Next")
("p" origami-previous-fold "Previous")
:...
("t" origami-toggle-all-nodes "Toggle buffer")
("m" lsp-ui-imenu "Menu of TLIs" :exit t) ;; TLI ≈ Top Level Items
;; ("i" imenu-list "iMenu (General)") ;; It seems the above is enough for both prog and otherwise.
("r" origami-reset)) ;; Remove all folds from the buffer and reset all origami state. Useful if origami messes up!
#+END_SRC
# *Disabled:* I've looked at a few folding modes, and I like this one.
# However, I seldom need it.
#+end_details
#+begin_details "[Disabled / Alternative] yafolding"
I found using yafolding-mode to be way too slow.
#+begin_src emacs-lisp :tangle no
;; “Yet Another Folding” just works: Indented elements are folded away; no setup required.
;; (use-package discover)
(use-package yafolding
;; Please open any code with top level items folded away:
;; Open the file super quick, but when I'm inactive for 5 seconds,
;; then I'm probably doing other stuff so do the folding then.
;; :hook prog-mode . (lambda () (interactive)
;; (run-with-idle-timer 5 nil #'yafolding-hide-all))
;; MA: It seems that this is not ideal; it takes a bit longer than I'd like to fold the whole file.
)
(defhydra yafolding-hydra (:color pink :columns 3)
"Fold code based on indentation levels"
;; First row
("s" yafolding-show-element "show element")
("S" yafolding-show-all "show all")
("" (lambda () (interactive)
(let ((next (car (yafolding-get-overlays (point) (point-max)))) pos)
(if (not next) (message "No more folded regions")
(setq pos (overlay-start next))
(yafolding-hide-element)
(goto-char pos)
(yafolding-show-element))))
"forward element")
;; Second row
("h" yafolding-hide-element "hide element")
("H" yafolding-hide-all "hide all")
("" (lambda () (interactive)
(let ((previous (car (yafolding-get-overlays (point-min) (point)))) pos)
(if (not previous) (message "No more folded regions")
(setq pos (overlay-start previous))
(yafolding-hide-element)
(goto-char pos)
(yafolding-show-element))))
"backward element")
;; Third row
("SPC" yafolding-toggle-element "toggle element")
("T" yafolding-toggle-all "toggle all")
("q" nil "quit" :color red)
("p" yafolding-hide-parent-element "hide parent")
("" (lambda () (interactive) (or (ignore-errors (yafolding-go-parent-element))
(message "Already at the top level.")))
"go to parent")
("r" (lambda () (interactive) (yafolding-hide-region (region-beginning) (region-end)))
"hide region"
))
(global-set-key (kbd "s-f") 'yafolding-hydra/body)
#+end_src
#+end_details
*** E2E Test :ignore:
:PROPERTIES:
:CUSTOM_ID: E2E-Test
:END:
#+begin_details Test
#+begin_src emacs-lisp :tangle init-test.el
(ert-deftest hideshow-is-enabled-and-folds-by-default ()
:tags '(hideshow)
;; Make a temporary scratch.js file with the given contents.
(let* ((contents "function fierce(name) { \n return `${name}: ROAR` \n }")
(scratch.js (make-temp-file "scratch" nil ".js" contents)))
;; Hideshow is enabled whenever we open a code file
(find-file scratch.js)
(should hs-minor-mode)
;; Function definition is a hidden block
(end-of-line)
(backward-char 2)
(should (hs-already-hidden-p))
;; Indeed, the hidden block starts at the first line break and ends just after the second.
(-let [ov (hs-already-hidden-p)]
(-let [(first\n second\n) (-elem-indices "\n" (s-split "" contents))]
(should (equal (overlay-start ov) first\n)) ;; ≈ 25
(should (equal (overlay-end ov) (+ second\n 2))))) ;; ≈ 52
(kill-buffer)))
#+end_src
#+end_details
** COMMENT Jump between windows using Cmd+Arrow & between recent buffers with Meta-Tab :relocate:
:PROPERTIES:
:CUSTOM_ID: Jump-between-windows-using-Cmd-Arrow-between-recent-buffers-with-Meta-Tab
:END:
We can use ~C-x o~ to switch to the ‘o’ther window, and ~C-u 𝓃 C-x o~ to switch to
the 𝓃-th next clockwise window, but using ~s-↑,↓,←,→~ may be faster.
#+BEGIN_SRC emacs-lisp
(use-package windmove
:defer nil
:config ;; use command key on Mac
(windmove-default-keybindings 'super)
;; wrap around at edges
(setq windmove-wrap-around t))
#+END_SRC
The [[https://github.com/killdash9/buffer-flip.el][docs]], for the following, have usage examples.
#+BEGIN_SRC emacs-lisp
(use-package buffer-flip
:defer nil
:bind
(:map buffer-flip-map
("M-" . buffer-flip-forward)
("M-S-" . buffer-flip-backward)
("C-g" . buffer-flip-abort))
:config
(setq buffer-flip-skip-patterns
'("^\\*helm\\b")))
;; key to begin cycling buffers.
(global-set-key (kbd "M-") 'buffer-flip)
#+END_SRC
See [[https://www.emacswiki.org/emacs/buffer-move.el][buffer-move]] if you're interested in moving the buffers, and their windows,
into new configurations.
** hr: [[https://github.com/LuRsT/hr][A horizontal for your terminal]] :relocate:
:PROPERTIES:
:CUSTOM_ID: hr-https-github-com-LuRsT-hr-A-horizontal-for-your-terminal
:END:
When working in the terminal, at least in my day job, it can be helpful to
visually segregate large chunks of output. With the ~hr~ command, I can run ~hr
'output5`~, for example, to have the same the string /output5/ repeated horizontal
across one line of my terminal. We can also just run ~hr~ which is the same as ~hr
'#'~. Finally, you can also run =hr '-#-' '-' '-#-'= to have 3 horizontal lines and
more generally =hr p₁ p₂ … pₙ= will produce /n/-many horizontal lines with the
$i^{th}$-line having pattern =pᵢ=.
#+begin_src emacs-lisp
(system-packages-ensure "hr") ;; ≈ brew install hr
#+end_src
** COMMENT Browse remote files
:PROPERTIES:
:CUSTOM_ID: Browse-remote-files
:END:
Sometimes you want to see the current file in Github; e.g., you select a
region and press ~M-x browse-at-remote-kill~ to get the URL for that region in
Github then you can send that URL to your peers when referencing something.
- Or just ~M-x browse-at-remote~ to see it in Github.
- [[https://github.com/rmuslimov/browse-at-remote][browse-at-remote: Browse target page on github/bitbucket from emacs buffers]].
#+begin_src emacs-lisp
;; Usage: [Optionally select a region then] M-x browse-at-remote[-kill]
(use-package browse-at-remote :defer nil)
#+end_src
** COMMENT [[https://github.com/sshaw/copy-as-format][copy-as-format:]] Emacs function to copy buffer locations as GitHub/Slack/JIRA etc... formatted code.
:PROPERTIES:
:CUSTOM_ID: https-github-com-sshaw-copy-as-format-copy-as-format-Emacs-function-to-copy-buffer-locations-as-GitHub-Slack-JIRA-etc-formatted-code
:END:
#+begin_src emacs-lisp
;; Usage: [C-u] M-x copy-as-format ⇒ Copies selected region, or current line.
;; Also use: copy-as-format-𝒮, to format to a particular 𝒮tyle.
;; Without suffix 𝒮, format defaults to `copy-as-format-default`.
;; With a prefix argument prompt for the format style 𝒮.
;; Easy to add more formats.
(use-package copy-as-format :defer nil)
#+end_src
** w-screencapture
:PROPERTIES:
:CUSTOM_ID: w-screencapture
:END:
#+begin_src emacs-lisp
(bind-key "C-c s"
(cl-defun w-screencapture ()
"Interactively capture screen and save to clipboard; then paste in Slack, etc, with ⌘-c.
After we run this command, we can swipe up on mousepad to select different desktops, then
click & drag to select portition of screen to capture.
Captured screen is NOT saved to disk, only copied to clipboard.
In MacOs,
+ Command + Shift + 5 ⇒ Select screen record
+ Command + Shift + 4 ⇒ Selection Screenshot
+ Command + Shift + 3 ⇒ Screenshot
See: https://osxdaily.com/2011/08/11/take-screen-shots-terminal-mac-os-x"
(interactive)
(async-shell-command "screencapture -i -c")))
(cl-defun w-delete-all-screenshots ()
"Delete all “Screen Shot ⋯” files in ~/Desktop."
(interactive)
(thread-last (shell-command-to-string "cd ~/Desktop; ls")
(s-split "\n")
(--filter (s-starts-with-p "Screen Shot" it))
(--map (f-delete (format "~/Desktop/%s" it)))))
#+end_src
** COMMENT Screencapturing the Current Emacs Frame
:PROPERTIES:
:CUSTOM_ID: Screencapturing-the-Current-Emacs-Frame
:END:
Sometimes an image can be tremendously convincing, or at least sufficiently
inviting. The following incantation is written for MacOS and uses it's native
=screencapture= utility, as well as =magick=.
#+BEGIN_SRC emacs-lisp
(defun my/capture-emacs-frame (&optional prefix output)
"Insert a link to a screenshot of the current Emacs frame.
Unless the name of the OUTPUT file is provided, read it from the
user. If PREFIX is provided, let the user select a portion of the screen."
(interactive "p")
(defvar my/emacs-window-id
(s-collapse-whitespace (shell-command-to-string "osascript -e 'tell app \"Emacs\" to id of window 1'"))
"The window ID of the current Emacs frame.
Takes a second to compute, whence a defvar.")
(let* ((screen (if prefix "-i" (concat "-l" my/emacs-window-id)))
(temp (format "emacs_temp_%s.png" (random)))
(default (format-time-string "emacs-%m-%d-%Y-%H:%M:%S.png")))
;; Get output file name
(unless output
(setq output (read-string (format "Emacs screenshot filename (%s): " default)))
(when (s-blank-p output) (setq output default)))
;; Clear minibuffer before capturing screen or prompt user
(message (if prefix "Please select region for capture …" "♥‿♥"))
;; Capture current screen and resize
(thread-first
(format "screencapture -T 2 %s %s" screen temp)
(concat "; magick convert -resize 60% " temp " " output)
(shell-command))
(f-delete temp)
;; Insert a link to the image and reload inline images.
(insert (concat "[[file:" output "]]")))
(org-display-inline-images nil t))
(bind-key* "C-c M-s" #'my/capture-emacs-frame)
#+END_SRC
Why this way? On MacOS, ImageMagick's =import= doesn't seem to work ---not at all
for me! Also, I dislike how large the resulting image is. As such, I'm using
MacOS's =screencapture= utility, which in-turn requires me to somehow obtain frame
IDs. Hence, the amount of work needed to make this happen on my system was most
simple if I just wrote it out myself rather than tweaking an existing system.
+ ~C-c C-x C-v~ ⇒ Toggle inline images!
** Comment-boxes up to the fill-column ---or banner instead?
:PROPERTIES:
:CUSTOM_ID: Comment-boxes-up-to-the-fill-column
:END:
GIF: https://endlessparentheses.com/images/comment-box.gif
#+begin_src emacs-lisp
(defun my/comment-box (b e)
"Draw a box comment around the region but arrange for the region
to extend to at least the fill column. Place the point after the
comment box.
Source: http://irreal.org/blog/?p=374
To do fancy stuff like removing boxes, centering them, etc
see https://github.com/lewang/rebox2/blob/master/rebox2.el"
(interactive "r")
(let ((e (copy-marker e t)))
(goto-char b)
(end-of-line)
(insert-char ? (- fill-column (current-column)))
(comment-box b e 1)
(goto-char e)
(set-marker e nil)))
#+end_src
A comment box sometimes increases the size of a file more than I'd like, or more than others on my dev team would like.
As such, let's try [[https://github.com/WJCFerguson/banner-comment][banner comments]]:
- GIF: https://github.com/WJCFerguson/banner-comment/blob/35d3315683d3f97605207691b77e9f447af18fe2/demo.png
#+begin_src emacs-lisp
(use-package banner-comment :defer nil)
#+end_src
Pretty slick!
** TODO COMMENT Auto-format on Save :Reenabled:Should_be_Disabled:Breaks_HTML_export_of_org_files_with_unicode_or_emojis:
:PROPERTIES:
:CUSTOM_ID: Auto-format-on-Save
:END:
[[https://github.com/lassik/emacs-format-all-the-code/tree/eb2a7fa6da15d23b57921218a36ac67d523e81f1][Auto-format source code in many languages with one command]]
Let's auto-format source code in many languages using the same command for all
languages, instead of learning a different Emacs package and formatting command
for each language.
Just do ~M-x format-all-buffer~ and it will try its best to do the right thing. To
auto-format code on save, use the minor mode format-all-mode. Better yet, we ask
for it to do so “on save”.
- You will need to install external programs to do the formatting. If
~format-all-buffer~ can't find the right program, it will try to tell you how to
install it.
- An alternative Emacs tool is [[https://github.com/radian-software/apheleia][apheleia: 🌷 Run code formatter on buffer
contents without moving point, using RCS patches and dynamic programming.]]
#+begin_src emacs-lisp
(use-package format-all
:defer nil
;; To enable format on save for most programming language buffers:
:hook (prog-mode . format-all-mode)
:config
;; Please use the default formatters; I don't care too much.
(add-hook 'format-all-mode-hook 'format-all-ensure-formatter))
#+end_src
[[https://prettier.io/docs/en/index.html][Prettier]] is an opinionated code formatter for numerous web related languages,
including JS, TS, HTML, CSS, JSON, Vue, Markdown, and YAML.
#+begin_src emacs-lisp
;; For JavaScript prettification: It automatically inserts semicolons, forces newlines, inserts parens, etc.
;; Lots of redundant stuff, but stuff to make it easy to work with others.
(shell-command "npm install --global prettier")
;; Specific package to do only JS prettification: https://github.com/prettier/prettier-emacs
#+end_src
For example, in a NodeJS app make a file ~.prettierrc.json~ whose contents are
#+begin_src json :tangle no
{
"singleQuote": true,
"arrowParens": "avoid",
"printWidth": 120,
"semi": false,
"trailingComma": "none"
}
#+end_src
Unfortunately, my current team prefers ~"semi": true~ ---which is understandable
for people not familar with how JavaScript does [[https://www.freecodecamp.org/news/lets-talk-about-semicolons-in-javascript-f1fe08ab4e53/][semicolon insertion]].
( If you're having trouble getting prettier to work on save, consider using this
[[https://github.com/codesuki/add-node-modules-path][package]] which detects your node modules' path. )
Anyhow, with these rules:
- I write =const f = (x) => "x" == x= then on save it becomes =const f = x => 'x' == x;=
- I write =let xs = [1, 2, 3,]= then on save it becomes =let xs = [1, 2, 3];=
- I write =foo(reallyLongArg(), omgSoManyParameters(), IShouldRefactorThis(), isThereSeriouslyAnotherOne());=
then nothing happens on save; but if you add one more argument, =, 12=, then it gets reformatted with each arg on one line.
Notice that in the first example above, only minor syntactic changes were made;
nothing altering semantics or quality of code ---for that, we use a /linter/.
In particular, [[https://emacs-lsp.github.io/lsp-mode/page/lsp-eslint/][LSP ESLint]] when activated will show us two errors: It's almost always
better to use ~===~ instead of ~==~ and literals should be on the right side of the equality.
We can use ~M-x lsp-execute-code-action~ to get a list of actions that can be performed to fix this /quality/ problem.
** Searching Hydra
:PROPERTIES:
:CUSTOM_ID: Searching-Hydra
:END:
#+begin_src emacs-lisp
(my/defhydra "s-f" "\t\tLocate Everything" search
:Buffer
;; find all the occurrences of a string, pull out the lines containing the string to another buffer where [F2] I can edit and save,
("e" helm-swoop "Editable")
;; Implicit Regex, colourful
("c" swiper "Classic")
:Project
;; “:toggle ℰ”: ℰ is a Boolean expression that is evaluated to tell us whether the state is on-or-off
("t" (lambda () (interactive)) "Ignore specs/jsons"
:toggle (let* ((with-hole "ag %s --line-numbers -S --color --nogroup %%s %%s %%s") ;; ≈ original value of ‘helm-grep-ag-command’
(ignores "--ignore=\"*spec.js\" --ignore=\"*.json\" --ignore=\"*.json5\"")
(on (equal helm-grep-ag-command (format with-hole ignores))))
(if on (progn (setq helm-grep-ag-command (format with-hole "")) nil) ;; ≈ turn off the toggle
(setq helm-grep-ag-command (format with-hole ignores)))))
("f" (lambda () (interactive) (helm-do-grep-ag t)) "File type")
("d" (lambda () (interactive) (-let [default-directory (read-directory-name "Where do you want to search? ")] (helm-do-grep-ag nil))) "Directory")
("D" (lambda () (interactive) (-let [default-directory (read-directory-name "Where do you want to search? ")] (helm-do-grep-ag t))) "Directory & type"))
#+end_src
** TODO ⌘-e: Edit Everything in a separate buffer
:PROPERTIES:
:CUSTOM_ID: e-Edit-Everything-in-a-separate-buffer
:END:
Edit comment/string/docstring/code block in separate buffer with your favourite
mode.
+ ⌘-e to toggle “e”diting of thing at point.
+ ⌘-e will try to edit thing at point, or selection, if possible; otherwise it
will exit edit session.
- 🔥 Avoid escape nightmares by editing strings in a separate buffer.
- On a string, press ⌘-e and a new buffer pops up with unescaped content,
letting you edit raw strings directly. It then takes care of automatically
escaping strings for you when you press ⌘-e, or ~C-c C-c~ ---or discard your
changes with ~C-c C-k~.
+ ⌘-e can be used within edit session to create new edit sessions, if possible; then ⌘-e will “pop-off-the-stack” as expected.
- (I already use ⌘-e to toggle editing Org src blocks, and when editing a block ⌘-e will try to do a recursive edit if possible, or exit the edit session.)
- (The separedit package also let's me press ⌘-e to edit variable values when describing them, and to edit text when in the minibuffer.)
From [[https://github.com/twlz0ne/separedit.el][source]]:
#+begin_example org
+----------+ Edit +-----------+ Edit +-----------+
| | ---------------------> | edit | ---------------------> | edit | ...
| | point-at-comment? | buffer | point-at-comment? | buffer |
| source | point-at-string? | | point-at-string? | | ...
| buffer | point-at-codeblock? | (markdown | point-at-codeblock? | (markdown | ...
| | point-at-...? | orgmode | point-at-...? | orgmode |
| | <--------------------- | ...) | <--------------------- | ...) | ...
+----------+ Commit changes +-----------+ Commit changes +-----------+
#+end_example
[In-general, we can invoke [[https://github.com/Fanael/edit-indirect/blob/e3d86416bcf8ddca951d7d112e57ad30c5f9a081/edit-indirect.el#L124][M-x edit-indirect-region]] to edit any selected piece
of text in its own buffer, then ~C-c C-c~ (or ~⌘-e~ with my setup) to commit the
edit. Actually, I've altered by ~⌘-e~ setup to also account for a selected region
😉]
#+begin_src emacs-lisp
(use-package separedit :defer nil)
;;
;; # Example Usage
;;
;; 1. Press ⌘-e on this line, to edit this entire comment.
;; 2. Press ⌘-e to exit the edit session.
;;
;; Since my ⌘-e is context sensitive, to determine whether to continue editing or
;; exit; you can explicitly request an edit with C-c ' and an exit with C-c C-c.
;;
;; ```
;; ;; 3. Press ⌘-e on this line, to edit this source block!
;; ;; 4. Press ⌘-e on this line, to edit this inner-most comment!
;; ;; 5. At start of next line, press “⌘-r ⌘-e” to edit just the source block
;; ;;
;; (cl-defun index (&rest args)
;; "6. Press ⌘-e to edit this string, \"7. and again in these quotes\""
;; "8. Press ⌘-e to edit this HTML block, in Web-mode
")
;;
;; ;; 9. Press C-u ⌘-e to guess the language of the next string (Rust); then ⌘-r C-c C-r to quickly run the code.
;; "fn main() { println!(\"{}\", \"hello!\"); }"
;;
;; ;; 10. Select & press “C-u ⌘-e” on the following, to edit it in whatever mode you want.
;; ;; select * from table -- Or just press ⌘-e and have the mode detected.
;;
;; ```
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;; Setup to make the above ⌘-e behaviour happen.
;; Make “⌘-e” toggle editing string literals / select region / [Org/markdown] code block / comment block when programming.
(--map (bind-key "s-e" #'separedit it)
'(prog-mode-map minibuffer-local-map help-mode-map)) ;; TODO: helpful-mode-map
#+end_src
#+begin_src emacs-lisp
;; TODO:Merge these changes upstream
;; I'm focusing on a specific region to edit, so let's not be distracted by anything else.
;; This makes the “editing stack” feel like a stack, with ⌘-e pushing new editing session buffers,
;; and C-c C-c, or ⌘-e on non-editable lines, to pop-off the stack.
;; (advice-add #'separedit :after (lambda (&rest _) (delete-other-windows)))
;;
;; NOTE: This actually breaks the stack nature of popping with ⌘-e; we need to actually save the stack via some list of buffers than push/pop buffers on that variable.
;; I don't want to be bothered for what mode I'm in, when a region is selected using current major mode.
;; I'll use a prefix, “C-u ⌘-e”, if I want to select a mode for my current selected text.
(advice-add #'separedit--select-mode :before-until
(lambda (&rest _)
(when (and (not current-prefix-arg) (region-active-p)) (pp-to-string major-mode))))
;; Also: When on a string ∷
(advice-add #'separedit--select-mode :before-until
(lambda (&rest _)
"When on a string ∷
+ ⌘-e ⇒ Edit string at point
+ C-u ⌘-e ⇒ Auto-detect my string's major mode
+ C-u C-u ⌘-e ⇒ Let me select a major mode"
(-let [str? (ignore-errors (thing-at-point 'string))]
(case (car current-prefix-arg)
(4 (when str? (pp-to-string (my/detect-prog-mode str?))))
(_ nil)))))
;; NOTE: By default, separedit provides colouring for 'strings', "strings", and `strings'
;; This doesn't look very good when I have a single quote within double quotes:
;; In an Emacs Lisp buffer, editing the string "Bob's Work" gives unexpected highlighting.
;; ```
;; (advice-add #'separedit :after
;; (lambda (&rest _)
;; (when (s-ends-with? "string-mode" (pp-to-string major-mode))
;; (text-mode))))
;; ```
#+end_src
#+begin_src emacs-lisp
;; In the indirect buffer, make ⌘-e finish editing.
(use-package edit-indirect
:config (bind-key "s-e"
(lambda ()
(interactive)
(or (ignore-errors (call-interactively #'separedit))
(call-interactively #'edit-indirect-commit)))
#'edit-indirect-mode-map))
;; I also have “s-e” bound to `org-edit-src-exit'.
(advice-add 'org-edit-src-exit :before-until
(lambda (&rest r)
(when (ignore-errors (separedit)) t)))
#+end_src
#+begin_src emacs-lisp
;; → ⌘-e on an Org paragraph pops-up an edit session in Org mode.
;; → ⌘-e on a selection in Org mode pops-up an edit session in Org mode.
;; TODO: Consider forming an alist for special blocks to refer to their preferred
;; edit mode, defaulting to Org-mode? Perhaps something to consider /after/
;; addressing the bug below.
;; (advice-unadvice 'org-edit-special) MA: TODO: FIXME: Delete this?
(advice-add 'org-edit-special :around
(lambda (orginal-function &rest r)
(cond
((region-active-p) (call-interactively #'edit-indirect-region) (org-mode))
((equal 'paragraph (car (org-element-at-point)))
(mark-paragraph) (call-interactively #'edit-indirect-region) (org-mode))
(t (or (ignore-errors (apply orginal-function r))
;; We try to edit a special block when orginal-function fails.
;; This way src blocks are not confused with the more generic idea of special blocks.
(when
(my/org-in-any-block-p)
;; Note using org-element-at-point doesn't work well with special blocks when you're somewhere within the block.
;; It only works correctly when you're on the boundary of the special block; which is not ideal.
;; This is why I'm not using: (org-element-property :begin elem).
(-let [(start . end) (my/org-in-any-block-p)]
(set-mark-command start)
(goto-char end) (previous-line 2) (end-of-line) ;; FIXME: Still shows #+end_XXX for some reason.
(call-interactively #'edit-indirect-region) (org-mode))))))))
#+end_src
#+begin_src emacs-lisp
;; where...
(defun my/org-in-any-block-p ()
"Return non-nil if the point is in any Org block.
The Org block can be *any*: src, example, verse, etc., even any
Org Special block.
This function is heavily adapted from `org-between-regexps-p'.
Src: https://scripter.co/splitting-an-org-block-into-two/"
(save-match-data
(let ((pos (point))
(case-fold-search t)
(block-begin-re "^[[:blank:]]*#\\+begin_\\(?1:.+?\\)\\(?: .*\\)*$")
(limit-up (save-excursion (outline-previous-heading)))
(limit-down (save-excursion (outline-next-heading)))
beg end)
(save-excursion
;; Point is on a block when on BLOCK-BEGIN-RE or if
;; BLOCK-BEGIN-RE can be found before it...
(and (or (org-in-regexp block-begin-re)
(re-search-backward block-begin-re limit-up :noerror))
(setq beg (match-beginning 0))
;; ... and BLOCK-END-RE after it...
(let ((block-end-re (concat "^[[:blank:]]*#\\+end_"
(match-string-no-properties 1)
"\\( .*\\)*$")))
(goto-char (match-end 0))
(re-search-forward block-end-re limit-down :noerror))
(> (setq end (match-end 0)) pos)
;; ... without another BLOCK-BEGIN-RE in-between.
(goto-char (match-beginning 0))
(not (re-search-backward block-begin-re (1+ beg) :noerror))
;; Return value.
(cons beg end))))))
#+end_src
I'd like to [[https://github.com/andreasjansson/language-detection.el][guess the language]] I'm in, when working with strings.
#+begin_src emacs-lisp
(use-package language-detection :defer nil)
;; Usage: M-x language-detection-buffer ⇒ Get programming language of current buffer
;; Also, (language-detection-string "select * from t") ;; ⇒ sql
;; TODO: Push this upstream; https://github.com/andreasjansson/language-detection.el/issues/1
(cl-defun my/detect-prog-mode (&optional string)
"Guess programming mode of the current buffer, or STRING if it is provided.
When called interactively, it enables the mode;
from Lisp it just returns the name of the associated mode.
;; Example Lisp usage
(call-interactively #'my/detect-prog-mode)
`language-detection-buffer' returns a string which is not always the name of the
associated major mode; that's what we aim to do here."
(interactive)
(defvar my/detect-prog-mode/special-names
'((c . c-mode)
(cpp . c++-mode)
(emacslisp . emacs-lisp-mode)
(html . web-mode) ;; I intentionally want to use this alternative.
(matlab . octave-mode)
(shell . shell-script-mode)
(visualbasic . visual-basic-mode)
(xml . sgml-mode))
"Names in this alist map a language to its mode; all other languages 𝒳 have mode ‘𝒳-mode’ afaik.")
(let* ((lang (if string (language-detection-string string) (language-detection-buffer)))
(mode (or (cdr (assoc lang my/detect-prog-mode/special-names))
(intern (format "%s-mode" lang)))))
(if (called-interactively-p 'any)
(progn (call-interactively mode) (message "%s enabled!" mode))
mode)))
#+end_src
+ ⌘-e to edit an Org table cell; see [[https://orgmode.org/manual/Built_002din-Table-Editor.html][here]] for built-in table editing commands.
#+begin_src emacs-lisp
(advice-add #'org-edit-special :before-until
(lambda (&rest r)
(when (equal 'table-row (car (org-element-at-point)))
(call-interactively #'org-table-edit-field))))
#+end_src
** COMMENT Pair Programming
:PROPERTIES:
:CUSTOM_ID: Pair-Programming
:END:
# Add: Quickly toggle my Emacs for when doing pair programming
I try to make my Emacs look more predictable for my colleagues, by introducing a bunch of UI elements that I normally
have off by default but would otherwise serve as useful aids when working together or provide a sense of familiarity for
my VSCoder counterparts.
#+begin_src emacs-lisp :tangle ~/Desktop/work.el
(defun my/toggle-pair-programming ()
"Toggle enabling features that might aid communication when sharing screen, or pair programming
- Full screen mode
- Line numbers, and column numbers, and cat progress bar
- Blamer overlays
- Dark theme
- Tabs
- Folder navigator
"
(interactive)
(defvar my/sharing-screen? +1)
(setq my/sharing-screen? (- my/sharing-screen?)) ;; Toggle between +1 and -1.
;; When pair programming, exit full screen mode so others can “draw” on my screen, eg using Slack
(toggle-frame-fullscreen)
;; Line numbers in the left margin
(setq display-line-numbers-width-start t)
(global-display-line-numbers-mode my/sharing-screen?)
;; Column & line numbers in the modeline; always want these on?
(column-number-mode +1) ;; Enabled in doom-modeline by default?
(line-number-mode +1) ;; Enabled in doom-modeline by default?
;; Progress bar, graphic and percentage
(use-package nyan-mode )
(nyan-mode my/sharing-screen?)
;; Who did what and when?
(global-blamer-mode my/sharing-screen?)
;; Make things look like VSCode; reduce friction with others
;; → Dark theme, tabs, and clickable folder navigation
(if (= +1 my/sharing-screen?)
(my/toggle-theme 'doom-dracula)
(my/toggle-theme 'doom-solarized-light))
(use-package centaur-tabs)
(setq centaur-tabs-set-icons t)
(setq centaur-tabs-gray-out-icons 'buffer)
(setq centaur-tabs-set-bar 'over)
(centaur-tabs-mode my/sharing-screen?)
;; Treemacs is feature-right; e.g. highlights file associated to current buffer automatically and fully mouse-complaint.
;; press ? to summon a helpful hydra
(use-package treemacs)
(if (= +1 my/sharing-screen?) ;; Toggle showing treemacs window
(treemacs)
(ignore-errors (delete-window (treemacs-get-local-window))))
;; Press “C-e” to see the end of length file names, or use the mouse to widen treemacs
(treemacs-toggle-fixed-width)
(ignore-errors (treemacs-indent-guide-mode +1))
(treemacs-resize-icons 18)
(other-window -1)
;; Kickoff message
(if (= +1 my/sharing-screen?)
(message "Pair programming provides an excellent test of technical and social skills")))
(my/toggle-pair-programming)
#+end_src
** Eldoc for Lisp and Haskell ---documentation in the mini-buffer
:PROPERTIES:
:CUSTOM_ID: Eldoc-for-Lisp-and-Haskell
:END:
In =emacs-lisp-mode= we can enable =eldoc-mode= ---“Elisp Live Documentation”--- to
display information about a function or a variable in the echo area. Likewise
for Haskell.
#+BEGIN_SRC emacs-lisp
(use-package eldoc
:hook (emacs-lisp-mode . turn-on-eldoc-mode)
(lisp-interaction-mode . turn-on-eldoc-mode)
(haskell-mode . turn-on-haskell-doc-mode)
(haskell-mode . turn-on-haskell-indent))
;; Slightly shorten eldoc display delay.
(setq eldoc-idle-delay 0.4) ;; Default 0.5
#+END_SRC
The less casual Haskeller would likely want to use [[https://haskell-lang.org/intero][intero]] to obtain
more support; e.g., obtain suggestions from GHC about redundant imports
or type signatures.
** COMMENT Modern Browsing within Emacs :Disabled:
:PROPERTIES:
:CUSTOM_ID: Modern-Browsing-within-Emacs
:END:
#+begin_src shell :tangle no
# https://github.com/d12frosted/homebrew-emacs-plus
$ brew tap d12frosted/emacs-plus
$ brew install emacs-plus@29 --with-xwidgets
$ /usr/local/Cellar/emacs-plus@29/29.0.50/bin/emacs-29.0.50 &
# In ~/.bashrc, put the following at the end:
alias emacs="/usr/local/Cellar/emacs-plus@29/29.0.50/bin/emacs-29.0.50"
#+end_src
--------------------------------------------------------------------------------
I like using Chrome ---I like the integration of all things Google.
#+begin_src emacs-lisp
(cl-defun internet (&optional (url (concat "https://www." (read-string "https://www."))))
"Browse to URL using `xwidget-webkit-browse-url'; see also `browse-url'."
(interactive)
(delete-other-windows)
(split-window-right)
(xwidget-webkit-browse-url url))
(my/defhydra "C-c p" "Emacs Browser" gamepad
:Internet
("m" (internet "https://mail.google.com/mail/u/0/#inbox") "gMail" :exit t)
("c" (internet "https://calendar.google.com/calendar/u/0/r") "gCalendar" :exit t)
("e" (internet "https://www.reddit.com/r/emacs/") "Emacs Forum" :exit t)
("b" (internet) "Browse" :exit t))
#+end_src
** An “auto read only” detection mechanism ---when jumping to definitions :Disabled:
:PROPERTIES:
:CUSTOM_ID: An-auto-read-only-detection-mechanism-when-jumping-to-definitions
:header-args: :tangle no
:END:
Files in 3ʳᵈ-party directories should be read-only whenever I open them, when
I'm jumping to definitions (with ~M-.~).
#+begin_src emacs-lisp
;; Usage: Press “M-”. “use-package” below and you can accidentally alter the source code!
;; But in this case you likely just wanted to see the 3ʳᵈ-party definition, not alter it.
;; As such, with this advice, the source will not be alterable (unless you toggle read-only mode).
(advice-add #'xref-find-definitions :after
(lambda (&rest _)
(when (--map (s-ends-with? it (f-parent buffer-file-name))
'("lisp/emacs-lisp" "/lisp" ".emacs.d/elpa/"))
(read-only-mode))))
#+end_src
* Open PDFs in Emacs
#+begin_src emacs-lisp
;; In Org-mode, clicking on PDF should open it in Emacs
;; Example: [[~/Desktop/stuff-I'm-learning.pdf::12]] ;; Opens the pdf to page 12
;; Another Example: docview:~/Desktop/stuff-I'm-learning.pdf::12
(ignore-errors (add-to-list 'org-file-apps '("\\.pdf\\'" . emacs)))
;; Required code to make the above links work as expected.
;; Source: https://www.reddit.com/r/emacs/comments/re0dx8/how_do_you_link_a_specific_pdf_page_in_org_mode/
(defun my-org-docview-open-hack (orig-func &rest args)
(let* ((link (car args)) path page)
(string-match "\\(.*?\\)\\(?:::\\([0-9]+\\)\\)?$" link)
(setq path (match-string 1 link))
(setq page (and (match-beginning 2)
(string-to-number (match-string 2 link))))
(org-open-file path 1)
(when page
(cond
((eq major-mode 'pdf-view-mode)
(pdf-view-goto-page page))
(t
(doc-view-goto-page page))))))
(advice-add 'org-docview-open :around #'my-org-docview-open-hack)
;; Alternatively, there's a dedicated package for this
;; https://github.com/fuxialexander/org-pdftools/tree/967f48fb5038bba32915ee9da8dc4e8b10ba3376
#+end_src
* empv
#+begin_src emacs-lisp
(use-package empv )
;; Then, M-x empv-play https://invidious.fdn.fr/watch?v=hlTqCmpP5eo, to listen to Dua Ifitiah in the background
;; Or: M-x empv-play https://invidious.fdn.fr/watch?v=9m9yE7qtq5w
;; lol maybe make a hydra(ie playlist) of things I commonly listen to in the background while working.
;; Require: brew install mpv
;; See also:
;; Maybe better? https://github.com/spiderbit/ytdious/tree/941460b51e43ef6764e15e2b9c4af54c3e56115f
;; Maybe better? https://melpa.org/#/yeetube
;; https://github.com/maximus12793/helm-youtube/tree/e7272f1648c7fa836ea5ac1a61770b4931ab4709
;; https://github.com/isamert/empv.el/tree/1721a581d68f211a7f0104554858ea2afb1723ff
;;
(setq empv-invidious-instance "https://invidious.fdn.fr.com")
#+end_src
* TODO COMMENT Eglot ----Fancy IDE Features that Just Workᵀᴹ
For JavaScript:
#+begin_src emacs-lisp
;; Get the language server for JavaScript
;; $ npm install -g javascript-typescript-langserver
;; Now open an empty buffer, switch to JS mode, M-x eglot, M-x company-mode,
;; then enter “console.” and see the completion of possibilities! <3
#+end_src
For Java, install doc:eglot-java-mode and activate that in a Java file ---it automatically installs the required
language server. 🚀
* COMMENT Lost Souls :Outdated_Documentation:Not_yet_tangled:
:PROPERTIES:
:CUSTOM_ID: Lost-Souls
:END:
** Note: M-S-SPC is for my personal servers dashboard.
:PROPERTIES:
:CUSTOM_ID: Note-M-S-SPC-is-for-my-personal-servers-dashboard
:END:
#+begin_src emacs-lisp :tangle no
;; Note: M-S-SPC is for my personal servers dashboard.
(global-set-key (kbd "M-SPC") (lambda () (interactive) (setq org-agenda-files (list org-default-notes-file)) (org-agenda nil "a") (delete-other-windows) (beginning-of-buffer)))
(use-package ace-jump-mode ;; Already installed above, somewhere.
:config (bind-key* "C-c SPC" 'ace-jump-mode))
#+end_src
** Zoom
:PROPERTIES:
:CUSTOM_ID: Zoom
:END:
#+begin_src emacs-lisp :tangle no
;; An automatic window-resizing mechanism.
;; A “calmer” alternative to golden-ratio.
;; https://github.com/cyrus-and/zoom
(use-package zoom
:config (zoom-mode t))
#+end_src
** Ibuffer
:PROPERTIES:
:CUSTOM_ID: Ibuffer
:END:
#+begin_src emacs-lisp :tangle no
;; Let's use an improved buffer list.
(use-package ibuffer ;; This is built-into Emacs.
:bind ("C-x C-b" . ibuffer))
;; It uses similar commands as does dired; e.g.,
;; / . org
;; This filters (“/”) the list with extensions (“.”) being “org”.
(use-package ibuffer-vc
:hook (ibuffer . (lambda ()
(ibuffer-vc-set-filter-groups-by-vc-root)
(unless (eq ibuffer-sorting-mode 'alphabetic)
(ibuffer-do-sort-by-alphabetic))))
:custom
(ibuffer-formats '((mark modified read-only " "
(name 18 18 :left :elide) " "
(size 9 -1 :right) " "
(mode 16 16 :left :elide) " "
(vc-status 16 16 :left) " "
(vc-relative-file)))))
#+end_src
+ [[http://martinowen.net/blog/2010/02/03/tips-for-emacs-ibuffer.html][Tips for using Emacs Ibuffer]]
+ (~10 minute video) [[https://cestlaz.github.io/posts/using-emacs-34-ibuffer-emmet/][Using Emacs - 34 - ibuffer and emmet - C'est la Z]]
+ (~10 minute video) [[https://www.youtube.com/watch?v=6KN_oSLFf-k&ab_channel=ProtesilaosStavrou][Emacs: introduction to IBUFFER - YouTube]]
** find function at point
:PROPERTIES:
:CUSTOM_ID: find-function-at-point
:END:
Friendly reminder that ~M-.~ takes you to the definition, and ~M-,~ takes you back
to where you originally where.
** COMMENT centered-cursor: Keep focus in the centre of the screen :Eeek:
:PROPERTIES:
:CUSTOM_ID: COMMENT-centered-cursor-Keep-focus-in-the-centre-of-the-screen
:END:
#+begin_src emacs-lisp :tangle no
;; When scrolling, move the screen and leave the cursour in the (vertical) center of the screen
(use-package centered-cursor-mode
:config (global-centered-cursor-mode))
#+end_src
** “C-x 2” and “C-x 3” now create a new window horizontally/vertically and send cursor there
:PROPERTIES:
:CUSTOM_ID: C-x-2-and-C-x-3-now-create-a-new-window-horizontally-vertically-and-send-cursor-there
:END:
#+begin_src emacs-lisp :tangle no
;; When we split open a new window, we usually want to jump to the new window.
(advice-add #'split-window-below :after (lambda (&rest _) (other-window 1)))
(advice-add #'split-window-right :after (lambda (&rest _) (other-window 1)))
#+end_src
** Semantic Change
:PROPERTIES:
:CUSTOM_ID: Semantic-Change
:END:
Using kbd:⌘-i and kbd:⌘-o we can quickly, for example, delete a string or its
contents; or delete a {}-block or just its contents; or delete a ()-argument
list or just its contents, etc.
~change-inner~ gives you vim's ~ci~ command:
- ~change-inner {~ ⇒ Delete all text starting from the first ‘{’ delimiter to the next one; but /keep the delimiters/.
- ~change-outer {~ ⇒ As above, but also delete the delimiters.
#+begin_src emacs-lisp :tangle no
(use-package change-inner
:bind (("s-i" . #'change-inner)
("s-o" . #'change-outer)))
#+end_src
** Drag Stuff :Disabled:
:PROPERTIES:
:CUSTOM_ID: Drag-Stuff
:END:
#+begin_src emacs-lisp :tangle no :tangle no
;; Move current word ←/→, or current line ↑/↓.
;; Todo: Compare with org-metaup and org-metadown...
(use-package drag-stuff
:config (cl-loop for (key . action) in '(("" . drag-stuff-down)
("" . drag-stuff-up)
("" . drag-stuff-right)
("" . drag-stuff-left))
do (bind-key key action org-mode-map))
(drag-stuff-global-mode 1))
#+end_src
Ruins Org-mode's M-↑/↓ for moving entire sections around.
** Indentation Guide
:PROPERTIES:
:CUSTOM_ID: Indentation-Guide
:END:
The following is also “OK” in Org-mode ;-)
#+begin_src emacs-lisp :tangle no
;; Add a visual indent guide
(use-package highlight-indent-guides
:hook (prog-mode . highlight-indent-guides-mode)
:custom
(highlight-indent-guides-method 'character)
(highlight-indent-guides-character ?|)
(highlight-indent-guides-responsive 'stack))
#+end_src
** TODO COMMENT [Nope?] JavaScript
:PROPERTIES:
:CUSTOM_ID: COMMENT-Nope-JavaScript
:END:
+ ;; FIXME Error (use-package): Failed to install ob-js: Package ‘ob-js-’ is unavailable
#+begin_src emacs-lisp :tangle no
(use-package ob-js
:config
(add-to-list 'org-babel-load-languages '(js . t))
(org-babel-do-load-languages 'org-babel-load-languages org-babel-load-languages)
(add-to-list 'org-babel-tangle-lang-exts '("js" . "js"))
(system-packages-ensure "node"))
;; use “:results output” for js blocks!
#+end_src
** Commenting
:PROPERTIES:
:CUSTOM_ID: Commenting
:END:
Let's get some nifty [[https://github.com/remyferre/comment-dwim-2][commenting]] features ---the link has nice usage gifs.
+ [[kbd:][M-;]]
repeatedly does (1) comments current line, (2) inserts a comment at the end
of the current line, and (3) deletes an existing end-of-line comment.
[[kbd:][C-u_M-;]] indents the current enf-of-line comment with any above it.
For use with Org-mode, it's best to use doc:org-edit-src-code ---which I've
bound to [[kbd:][⌘ e]].
#+begin_src emacs-lisp :tangle no
(use-package comment-dwim-2
:bind ("M-;" . comment-dwim-2))
;; Not ideal: M-; comments a parent Org heading and not the current line.
;; (define-key org-mode-map (kbd "M-;") 'org-comment-dwim-2)
#+end_src
** Having a workspace manager in Emacs
:PROPERTIES:
:CUSTOM_ID: Having-a-workspace-manager-in-Emacs
:END:
I've loved using XMonad as a window tiling manager. I've enjoyed the ability to
segregate my tasks according to what ‘project’ I'm working on; such as research,
marking, Emacs play, etc. With [[https://github.com/nex3/perspective-el][perspective]], I can do the same thing :-)
That is, I can have a million buffers, but only those that belong to a workspace
will be visible when I'm switching between buffers, for example.
( The awesome-tab and centaur-tab, mentioned elsewhere here, can be used to
achieve the same thing by ‘grouping buffers together’. )
#+begin_src emacs-lisp :tangle no
(use-package perspective
:config ;; Activate it.
(persp-mode)
;; In the modeline, tell me which workspace I'm in.
(persp-turn-on-modestring))
#+END_SRC
All commands are prefixed by ~C-x x~; main commands:
+ ~s, n/→, p/←~ :: ‘S’elect a workspace to go to or create it, or go to ‘n’ext
one, or go to ‘p’revious one.
+ ~c~ :: Query a perspective to kill.
+ ~r~ :: Rename a perspective.
+ ~A~ :: Add buffer to current perspective & remove it from all others.
As always, since we've installed ~which-key~, it suffices to press ~C-x x~ then look
at the resulting menu 😃
** Editor Documentation with Contextual Information
:PROPERTIES:
:CUSTOM_ID: Editor-Documentation-with-Contextual-Information
:END:
/Emacs is an extensible self-documenting editor!/
Let's use a helpful Emacs /documentation/ system that cleanly shows a lot of
contextual information ---then let's /extend/ that to work as we want it to:
~C-h o~ to describe the symbol at point.
#+begin_src emacs-lisp :tangle no
(use-package helpful )
(defun my/describe-symbol (symbol)
"A “C-h o” replacement using “helpful”:
If there's a thing at point, offer that as default search item.
If a prefix is provided, i.e., “C-u C-h o” then the built-in
“describe-symbol” command is used.
⇨ Pretty docstrings, with links and highlighting.
⇨ Source code of symbol.
⇨ Callers of function symbol.
⇨ Key bindings for function symbol.
⇨ Aliases.
⇨ Options to enable tracing, dissable, and forget/unbind the symbol!
"
(interactive "p")
(let* ((thing (symbol-at-point))
(val (completing-read
(format "Describe symbol (default %s): " thing)
(vconcat (list thing) obarray)
(lambda (vv)
(cl-some (lambda (x) (funcall (nth 1 x) vv))
describe-symbol-backends))
t nil nil))
(it (intern val)))
(cond
(current-prefix-arg (funcall #'describe-symbol it))
((or (functionp it) (macrop it) (commandp it)) (helpful-callable it))
(t (helpful-symbol it)))))
;; Keybindings.
(global-set-key (kbd "C-h o") #'my/describe-symbol)
(global-set-key (kbd "C-h k") #'helpful-key)
#+END_SRC
I like [[https://github.com/Wilfred/helpful][helpful]] and wanted it to have the same behaviour as ~C-h o~, which
~helpful-at-point~ does not achieve. The incantation above makes ~C-h o~ use ~helpful~
in that if the cursor is on a symbol, then it is offered to the user as a
default search item for help, otherwise a plain search box for help
appears. Using a universal argument lets us drop to the built-in help command.
** =README= ---From =init.org= to =init.el=
:PROPERTIES:
:CUSTOM_ID: README-From-init-org-to-init-el
:END:
Rather than manually extracting the Lisp code from this literate document each
time we alter it, let's instead add a ‘hook’ ---a method that is invoked on a
particular event, in this case when we save the file. More precisely, in this
case, ~C-x C-s~ is a normal save whereas ~C-u C-x C-s~ is a save after forming
~init.elc~ and ~README.md~.
**** The =my/make-init-el-and-README= function
:PROPERTIES:
:CUSTOM_ID: The-my-make-init-el-and-README-function
:END:
We ‘hook on’ the following function to the usual save method
that is associated with this file only.
# +name: enable making init and readme
#+name: startup-code
#+begin_src emacs-lisp :tangle no :eval never-export
(defun my/make-init-el-and-README ()
"Tangle an el and a github README from my init.org."
(interactive "P") ;; Places value of universal argument into: current-prefix-arg
(when current-prefix-arg
(let* ((time (current-time))
(_date (format-time-string "_%Y-%m-%d"))
(.emacs "~/.emacs")
(.emacs.el "~/.emacs.el"))
;; Make README.org
(save-excursion
(org-babel-goto-named-src-block "make-readme") ;; See next subsubsection.
(org-babel-execute-src-block))
;; remove any other initialisation file candidates
(ignore-errors
(f-move .emacs (concat .emacs _date))
(f-move .emacs.el (concat .emacs.el _date)))
;; Make init.el
(org-babel-tangle)
;; (byte-compile-file "~/.emacs.d/init.el")
(load-file "~/.emacs.d/init.el")
;; Acknowledgement
(message "Tangled, compiled, and loaded init.el; and made README.md … %.06f seconds"
(float-time (time-since time))))))
(add-hook 'after-save-hook 'my/make-init-el-and-README nil 'local-to-this-file-please)
#+end_src
**** The Org-block named =make-readme=
:PROPERTIES:
:CUSTOM_ID: The-Org-block-named-make-readme
:END:
Where the following block has ~#+NAME: make-readme~ before it. This source block
generates the ~README~ for the associated Github repository.
#+NAME: make-readme
#+begin_src emacs-lisp :tangle no :tangle no :export_never t
(save-buffer)
(with-temp-buffer
(insert
"#+EXPORT_FILE_NAME: README.org
# Logos and birthday present painting
,#+HTML:" (s-collapse-whitespace (concat
"
"))
;; My Literate Setup; need the empty new lines for the export
"
I enjoy reading others' /literate/ configuration files and
incorporating what I learn into my own. The result is a
sufficiently well-documented and accessible read that yields
a stylish and functional system (•̀ᴗ•́)و
This ~README.org~ has been automatically generated from my
configuration and its contents below are accessible
in (outdated) blog format, with /colour/, or as colourful
PDF, [[https://alhassy.github.io/init/][here]]. Enjoy
:smile:
,#+INCLUDE: init.org
")
;; No code execution on export
;; ⟪ For a particular block, we use “:eval never-export”. ⟫
(let ((org-export-use-babel nil))
(org-mode)
(org-org-export-to-org)))
#+end_src
Alternatively, evaluate the above source block with ~C-c C-c~ to produce a ~README~
file.
For the ‘badges’, see https://shields.io/. The syntax above is structured:
#+begin_example org
https://img.shields.io/badge/
8. Press ⌘-e to edit this HTML block, in Web-mode
") ;; ;; ;; 9. Press C-u ⌘-e to guess the language of the next string (Rust); then ⌘-r C-c C-r to quickly run the code. ;; "fn main() { println!(\"{}\", \"hello!\"); }" ;; ;; ;; 10. Select & press “C-u ⌘-e” on the following, to edit it in whatever mode you want. ;; ;; select * from table -- Or just press ⌘-e and have the mode detected. ;; ;; ``` ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;; Setup to make the above ⌘-e behaviour happen. ;; Make “⌘-e” toggle editing string literals / select region / [Org/markdown] code block / comment block when programming. (--map (bind-key "s-e" #'separedit it) '(prog-mode-map minibuffer-local-map help-mode-map)) ;; TODO: helpful-mode-map #+end_src #+begin_src emacs-lisp ;; TODO:Merge these changes upstream ;; I'm focusing on a specific region to edit, so let's not be distracted by anything else. ;; This makes the “editing stack” feel like a stack, with ⌘-e pushing new editing session buffers, ;; and C-c C-c, or ⌘-e on non-editable lines, to pop-off the stack. ;; (advice-add #'separedit :after (lambda (&rest _) (delete-other-windows))) ;; ;; NOTE: This actually breaks the stack nature of popping with ⌘-e; we need to actually save the stack via some list of buffers than push/pop buffers on that variable. ;; I don't want to be bothered for what mode I'm in, when a region is selected using current major mode. ;; I'll use a prefix, “C-u ⌘-e”, if I want to select a mode for my current selected text. (advice-add #'separedit--select-mode :before-until (lambda (&rest _) (when (and (not current-prefix-arg) (region-active-p)) (pp-to-string major-mode)))) ;; Also: When on a string ∷ (advice-add #'separedit--select-mode :before-until (lambda (&rest _) "When on a string ∷ + ⌘-e ⇒ Edit string at point + C-u ⌘-e ⇒ Auto-detect my string's major mode + C-u C-u ⌘-e ⇒ Let me select a major mode" (-let [str? (ignore-errors (thing-at-point 'string))] (case (car current-prefix-arg) (4 (when str? (pp-to-string (my/detect-prog-mode str?)))) (_ nil))))) ;; NOTE: By default, separedit provides colouring for 'strings', "strings", and `strings' ;; This doesn't look very good when I have a single quote within double quotes: ;; In an Emacs Lisp buffer, editing the string "Bob's Work" gives unexpected highlighting. ;; ``` ;; (advice-add #'separedit :after ;; (lambda (&rest _) ;; (when (s-ends-with? "string-mode" (pp-to-string major-mode)) ;; (text-mode)))) ;; ``` #+end_src #+begin_src emacs-lisp ;; In the indirect buffer, make ⌘-e finish editing. (use-package edit-indirect :config (bind-key "s-e" (lambda () (interactive) (or (ignore-errors (call-interactively #'separedit)) (call-interactively #'edit-indirect-commit))) #'edit-indirect-mode-map)) ;; I also have “s-e” bound to `org-edit-src-exit'. (advice-add 'org-edit-src-exit :before-until (lambda (&rest r) (when (ignore-errors (separedit)) t))) #+end_src #+begin_src emacs-lisp ;; → ⌘-e on an Org paragraph pops-up an edit session in Org mode. ;; → ⌘-e on a selection in Org mode pops-up an edit session in Org mode. ;; TODO: Consider forming an alist for special blocks to refer to their preferred ;; edit mode, defaulting to Org-mode? Perhaps something to consider /after/ ;; addressing the bug below. ;; (advice-unadvice 'org-edit-special) MA: TODO: FIXME: Delete this? (advice-add 'org-edit-special :around (lambda (orginal-function &rest r) (cond ((region-active-p) (call-interactively #'edit-indirect-region) (org-mode)) ((equal 'paragraph (car (org-element-at-point))) (mark-paragraph) (call-interactively #'edit-indirect-region) (org-mode)) (t (or (ignore-errors (apply orginal-function r)) ;; We try to edit a special block when orginal-function fails. ;; This way src blocks are not confused with the more generic idea of special blocks. (when (my/org-in-any-block-p) ;; Note using org-element-at-point doesn't work well with special blocks when you're somewhere within the block. ;; It only works correctly when you're on the boundary of the special block; which is not ideal. ;; This is why I'm not using: (org-element-property :begin elem). (-let [(start . end) (my/org-in-any-block-p)] (set-mark-command start) (goto-char end) (previous-line 2) (end-of-line) ;; FIXME: Still shows #+end_XXX for some reason. (call-interactively #'edit-indirect-region) (org-mode)))))))) #+end_src #+begin_src emacs-lisp ;; where... (defun my/org-in-any-block-p () "Return non-nil if the point is in any Org block. The Org block can be *any*: src, example, verse, etc., even any Org Special block. This function is heavily adapted from `org-between-regexps-p'. Src: https://scripter.co/splitting-an-org-block-into-two/" (save-match-data (let ((pos (point)) (case-fold-search t) (block-begin-re "^[[:blank:]]*#\\+begin_\\(?1:.+?\\)\\(?: .*\\)*$") (limit-up (save-excursion (outline-previous-heading))) (limit-down (save-excursion (outline-next-heading))) beg end) (save-excursion ;; Point is on a block when on BLOCK-BEGIN-RE or if ;; BLOCK-BEGIN-RE can be found before it... (and (or (org-in-regexp block-begin-re) (re-search-backward block-begin-re limit-up :noerror)) (setq beg (match-beginning 0)) ;; ... and BLOCK-END-RE after it... (let ((block-end-re (concat "^[[:blank:]]*#\\+end_" (match-string-no-properties 1) "\\( .*\\)*$"))) (goto-char (match-end 0)) (re-search-forward block-end-re limit-down :noerror)) (> (setq end (match-end 0)) pos) ;; ... without another BLOCK-BEGIN-RE in-between. (goto-char (match-beginning 0)) (not (re-search-backward block-begin-re (1+ beg) :noerror)) ;; Return value. (cons beg end)))))) #+end_src I'd like to [[https://github.com/andreasjansson/language-detection.el][guess the language]] I'm in, when working with strings. #+begin_src emacs-lisp (use-package language-detection :defer nil) ;; Usage: M-x language-detection-buffer ⇒ Get programming language of current buffer ;; Also, (language-detection-string "select * from t") ;; ⇒ sql ;; TODO: Push this upstream; https://github.com/andreasjansson/language-detection.el/issues/1 (cl-defun my/detect-prog-mode (&optional string) "Guess programming mode of the current buffer, or STRING if it is provided. When called interactively, it enables the mode; from Lisp it just returns the name of the associated mode. ;; Example Lisp usage (call-interactively #'my/detect-prog-mode) `language-detection-buffer' returns a string which is not always the name of the associated major mode; that's what we aim to do here." (interactive) (defvar my/detect-prog-mode/special-names '((c . c-mode) (cpp . c++-mode) (emacslisp . emacs-lisp-mode) (html . web-mode) ;; I intentionally want to use this alternative. (matlab . octave-mode) (shell . shell-script-mode) (visualbasic . visual-basic-mode) (xml . sgml-mode)) "Names in this alist map a language to its mode; all other languages 𝒳 have mode ‘𝒳-mode’ afaik.") (let* ((lang (if string (language-detection-string string) (language-detection-buffer))) (mode (or (cdr (assoc lang my/detect-prog-mode/special-names)) (intern (format "%s-mode" lang))))) (if (called-interactively-p 'any) (progn (call-interactively mode) (message "%s enabled!" mode)) mode))) #+end_src + ⌘-e to edit an Org table cell; see [[https://orgmode.org/manual/Built_002din-Table-Editor.html][here]] for built-in table editing commands. #+begin_src emacs-lisp (advice-add #'org-edit-special :before-until (lambda (&rest r) (when (equal 'table-row (car (org-element-at-point))) (call-interactively #'org-table-edit-field)))) #+end_src ** COMMENT Pair Programming :PROPERTIES: :CUSTOM_ID: Pair-Programming :END: # Add: Quickly toggle my Emacs for when doing pair programming I try to make my Emacs look more predictable for my colleagues, by introducing a bunch of UI elements that I normally have off by default but would otherwise serve as useful aids when working together or provide a sense of familiarity for my VSCoder counterparts. #+begin_src emacs-lisp :tangle ~/Desktop/work.el (defun my/toggle-pair-programming () "Toggle enabling features that might aid communication when sharing screen, or pair programming - Full screen mode - Line numbers, and column numbers, and cat progress bar - Blamer overlays - Dark theme - Tabs - Folder navigator " (interactive) (defvar my/sharing-screen? +1) (setq my/sharing-screen? (- my/sharing-screen?)) ;; Toggle between +1 and -1. ;; When pair programming, exit full screen mode so others can “draw” on my screen, eg using Slack (toggle-frame-fullscreen) ;; Line numbers in the left margin (setq display-line-numbers-width-start t) (global-display-line-numbers-mode my/sharing-screen?) ;; Column & line numbers in the modeline; always want these on? (column-number-mode +1) ;; Enabled in doom-modeline by default? (line-number-mode +1) ;; Enabled in doom-modeline by default? ;; Progress bar, graphic and percentage (use-package nyan-mode ) (nyan-mode my/sharing-screen?) ;; Who did what and when? (global-blamer-mode my/sharing-screen?) ;; Make things look like VSCode; reduce friction with others ;; → Dark theme, tabs, and clickable folder navigation (if (= +1 my/sharing-screen?) (my/toggle-theme 'doom-dracula) (my/toggle-theme 'doom-solarized-light)) (use-package centaur-tabs) (setq centaur-tabs-set-icons t) (setq centaur-tabs-gray-out-icons 'buffer) (setq centaur-tabs-set-bar 'over) (centaur-tabs-mode my/sharing-screen?) ;; Treemacs is feature-right; e.g. highlights file associated to current buffer automatically and fully mouse-complaint. ;; press ? to summon a helpful hydra (use-package treemacs) (if (= +1 my/sharing-screen?) ;; Toggle showing treemacs window (treemacs) (ignore-errors (delete-window (treemacs-get-local-window)))) ;; Press “C-e” to see the end of length file names, or use the mouse to widen treemacs (treemacs-toggle-fixed-width) (ignore-errors (treemacs-indent-guide-mode +1)) (treemacs-resize-icons 18) (other-window -1) ;; Kickoff message (if (= +1 my/sharing-screen?) (message "Pair programming provides an excellent test of technical and social skills"))) (my/toggle-pair-programming) #+end_src ** Eldoc for Lisp and Haskell ---documentation in the mini-buffer :PROPERTIES: :CUSTOM_ID: Eldoc-for-Lisp-and-Haskell :END: In =emacs-lisp-mode= we can enable =eldoc-mode= ---“Elisp Live Documentation”--- to display information about a function or a variable in the echo area. Likewise for Haskell. #+BEGIN_SRC emacs-lisp (use-package eldoc :hook (emacs-lisp-mode . turn-on-eldoc-mode) (lisp-interaction-mode . turn-on-eldoc-mode) (haskell-mode . turn-on-haskell-doc-mode) (haskell-mode . turn-on-haskell-indent)) ;; Slightly shorten eldoc display delay. (setq eldoc-idle-delay 0.4) ;; Default 0.5 #+END_SRC The less casual Haskeller would likely want to use [[https://haskell-lang.org/intero][intero]] to obtain more support; e.g., obtain suggestions from GHC about redundant imports or type signatures. ** COMMENT Modern Browsing within Emacs :Disabled: :PROPERTIES: :CUSTOM_ID: Modern-Browsing-within-Emacs :END: #+begin_src shell :tangle no # https://github.com/d12frosted/homebrew-emacs-plus $ brew tap d12frosted/emacs-plus $ brew install emacs-plus@29 --with-xwidgets $ /usr/local/Cellar/emacs-plus@29/29.0.50/bin/emacs-29.0.50 & # In ~/.bashrc, put the following at the end: alias emacs="/usr/local/Cellar/emacs-plus@29/29.0.50/bin/emacs-29.0.50" #+end_src -------------------------------------------------------------------------------- I like using Chrome ---I like the integration of all things Google. #+begin_src emacs-lisp (cl-defun internet (&optional (url (concat "https://www." (read-string "https://www.")))) "Browse to URL using `xwidget-webkit-browse-url'; see also `browse-url'." (interactive) (delete-other-windows) (split-window-right) (xwidget-webkit-browse-url url)) (my/defhydra "C-c p" "Emacs Browser" gamepad :Internet ("m" (internet "https://mail.google.com/mail/u/0/#inbox") "gMail" :exit t) ("c" (internet "https://calendar.google.com/calendar/u/0/r") "gCalendar" :exit t) ("e" (internet "https://www.reddit.com/r/emacs/") "Emacs Forum" :exit t) ("b" (internet) "Browse" :exit t)) #+end_src ** An “auto read only” detection mechanism ---when jumping to definitions :Disabled: :PROPERTIES: :CUSTOM_ID: An-auto-read-only-detection-mechanism-when-jumping-to-definitions :header-args: :tangle no :END: Files in 3ʳᵈ-party directories should be read-only whenever I open them, when I'm jumping to definitions (with ~M-.~). #+begin_src emacs-lisp ;; Usage: Press “M-”. “use-package” below and you can accidentally alter the source code! ;; But in this case you likely just wanted to see the 3ʳᵈ-party definition, not alter it. ;; As such, with this advice, the source will not be alterable (unless you toggle read-only mode). (advice-add #'xref-find-definitions :after (lambda (&rest _) (when (--map (s-ends-with? it (f-parent buffer-file-name)) '("lisp/emacs-lisp" "/lisp" ".emacs.d/elpa/")) (read-only-mode)))) #+end_src * Open PDFs in Emacs #+begin_src emacs-lisp ;; In Org-mode, clicking on PDF should open it in Emacs ;; Example: [[~/Desktop/stuff-I'm-learning.pdf::12]] ;; Opens the pdf to page 12 ;; Another Example: docview:~/Desktop/stuff-I'm-learning.pdf::12 (ignore-errors (add-to-list 'org-file-apps '("\\.pdf\\'" . emacs))) ;; Required code to make the above links work as expected. ;; Source: https://www.reddit.com/r/emacs/comments/re0dx8/how_do_you_link_a_specific_pdf_page_in_org_mode/ (defun my-org-docview-open-hack (orig-func &rest args) (let* ((link (car args)) path page) (string-match "\\(.*?\\)\\(?:::\\([0-9]+\\)\\)?$" link) (setq path (match-string 1 link)) (setq page (and (match-beginning 2) (string-to-number (match-string 2 link)))) (org-open-file path 1) (when page (cond ((eq major-mode 'pdf-view-mode) (pdf-view-goto-page page)) (t (doc-view-goto-page page)))))) (advice-add 'org-docview-open :around #'my-org-docview-open-hack) ;; Alternatively, there's a dedicated package for this ;; https://github.com/fuxialexander/org-pdftools/tree/967f48fb5038bba32915ee9da8dc4e8b10ba3376 #+end_src * empv #+begin_src emacs-lisp (use-package empv ) ;; Then, M-x empv-play https://invidious.fdn.fr/watch?v=hlTqCmpP5eo, to listen to Dua Ifitiah in the background ;; Or: M-x empv-play https://invidious.fdn.fr/watch?v=9m9yE7qtq5w ;; lol maybe make a hydra(ie playlist) of things I commonly listen to in the background while working. ;; Require: brew install mpv ;; See also: ;; Maybe better? https://github.com/spiderbit/ytdious/tree/941460b51e43ef6764e15e2b9c4af54c3e56115f ;; Maybe better? https://melpa.org/#/yeetube ;; https://github.com/maximus12793/helm-youtube/tree/e7272f1648c7fa836ea5ac1a61770b4931ab4709 ;; https://github.com/isamert/empv.el/tree/1721a581d68f211a7f0104554858ea2afb1723ff ;; (setq empv-invidious-instance "https://invidious.fdn.fr.com") #+end_src * TODO COMMENT Eglot ----Fancy IDE Features that Just Workᵀᴹ For JavaScript: #+begin_src emacs-lisp ;; Get the language server for JavaScript ;; $ npm install -g javascript-typescript-langserver ;; Now open an empty buffer, switch to JS mode, M-x eglot, M-x company-mode, ;; then enter “console.” and see the completion of possibilities! <3 #+end_src For Java, install doc:eglot-java-mode and activate that in a Java file ---it automatically installs the required language server. 🚀 * COMMENT Lost Souls :Outdated_Documentation:Not_yet_tangled: :PROPERTIES: :CUSTOM_ID: Lost-Souls :END: ** Note: M-S-SPC is for my personal servers dashboard. :PROPERTIES: :CUSTOM_ID: Note-M-S-SPC-is-for-my-personal-servers-dashboard :END: #+begin_src emacs-lisp :tangle no ;; Note: M-S-SPC is for my personal servers dashboard. (global-set-key (kbd "M-SPC") (lambda () (interactive) (setq org-agenda-files (list org-default-notes-file)) (org-agenda nil "a") (delete-other-windows) (beginning-of-buffer))) (use-package ace-jump-mode ;; Already installed above, somewhere. :config (bind-key* "C-c SPC" 'ace-jump-mode)) #+end_src ** Zoom :PROPERTIES: :CUSTOM_ID: Zoom :END: #+begin_src emacs-lisp :tangle no ;; An automatic window-resizing mechanism. ;; A “calmer” alternative to golden-ratio. ;; https://github.com/cyrus-and/zoom (use-package zoom :config (zoom-mode t)) #+end_src ** Ibuffer :PROPERTIES: :CUSTOM_ID: Ibuffer :END: #+begin_src emacs-lisp :tangle no ;; Let's use an improved buffer list. (use-package ibuffer ;; This is built-into Emacs. :bind ("C-x C-b" . ibuffer)) ;; It uses similar commands as does dired; e.g., ;; / . org ;; This filters (“/”) the list with extensions (“.”) being “org”. (use-package ibuffer-vc :hook (ibuffer . (lambda () (ibuffer-vc-set-filter-groups-by-vc-root) (unless (eq ibuffer-sorting-mode 'alphabetic) (ibuffer-do-sort-by-alphabetic)))) :custom (ibuffer-formats '((mark modified read-only " " (name 18 18 :left :elide) " " (size 9 -1 :right) " " (mode 16 16 :left :elide) " " (vc-status 16 16 :left) " " (vc-relative-file))))) #+end_src + [[http://martinowen.net/blog/2010/02/03/tips-for-emacs-ibuffer.html][Tips for using Emacs Ibuffer]] + (~10 minute video) [[https://cestlaz.github.io/posts/using-emacs-34-ibuffer-emmet/][Using Emacs - 34 - ibuffer and emmet - C'est la Z]] + (~10 minute video) [[https://www.youtube.com/watch?v=6KN_oSLFf-k&ab_channel=ProtesilaosStavrou][Emacs: introduction to IBUFFER - YouTube]] ** find function at point :PROPERTIES: :CUSTOM_ID: find-function-at-point :END: Friendly reminder that ~M-.~ takes you to the definition, and ~M-,~ takes you back to where you originally where. ** COMMENT centered-cursor: Keep focus in the centre of the screen :Eeek: :PROPERTIES: :CUSTOM_ID: COMMENT-centered-cursor-Keep-focus-in-the-centre-of-the-screen :END: #+begin_src emacs-lisp :tangle no ;; When scrolling, move the screen and leave the cursour in the (vertical) center of the screen (use-package centered-cursor-mode :config (global-centered-cursor-mode)) #+end_src ** “C-x 2” and “C-x 3” now create a new window horizontally/vertically and send cursor there :PROPERTIES: :CUSTOM_ID: C-x-2-and-C-x-3-now-create-a-new-window-horizontally-vertically-and-send-cursor-there :END: #+begin_src emacs-lisp :tangle no ;; When we split open a new window, we usually want to jump to the new window. (advice-add #'split-window-below :after (lambda (&rest _) (other-window 1))) (advice-add #'split-window-right :after (lambda (&rest _) (other-window 1))) #+end_src ** Semantic Change :PROPERTIES: :CUSTOM_ID: Semantic-Change :END: Using kbd:⌘-i and kbd:⌘-o we can quickly, for example, delete a string or its contents; or delete a {}-block or just its contents; or delete a ()-argument list or just its contents, etc. ~change-inner~ gives you vim's ~ci~ command: - ~change-inner {~ ⇒ Delete all text starting from the first ‘{’ delimiter to the next one; but /keep the delimiters/. - ~change-outer {~ ⇒ As above, but also delete the delimiters. #+begin_src emacs-lisp :tangle no (use-package change-inner :bind (("s-i" . #'change-inner) ("s-o" . #'change-outer))) #+end_src ** Drag Stuff :Disabled: :PROPERTIES: :CUSTOM_ID: Drag-Stuff :END: #+begin_src emacs-lisp :tangle no :tangle no ;; Move current word ←/→, or current line ↑/↓. ;; Todo: Compare with org-metaup and org-metadown... (use-package drag-stuff :config (cl-loop for (key . action) in '(("