Core

Init

gc cons threshold

A big contributor to long startup times is the garbage collector. When performing a large number of calculations, it can make a big difference to increase the gc-cons-threshold, or the number of bytes of consing between garbage collections. The default value is usually too low for modern machines.

gc cons threshold

(defconst VOID:GC-CONS-THRESHOLD-MAX (eval-when-compile (* 256 1024 1024))
  "The upper limit for `gc-cons-threshold'.
When VOID is performing computationally intensive operations,
`gc-cons-threshold' is set to this value.")

(defconst VOID:GC-CONS-THRESHOLD (eval-when-compile (* 16 1024 1024))
  "The default value for `gc-cons-threshold'.
If you experience freezing, decrease this. If you experience stuttering,
increase this.")

(defconst VOID:GC-CONS-PERCENTAGE-MAX 0.6
  "The upper limit for `gc-cons-percentage'.
When VOID is performing computationally intensive operations,
`gc-cons-percentage' is set to this value.")

(defconst VOID:GC-CONS-PERCENTAGE 0.1
  "The default value for `gc-cons-percentage'.")

boost gc threshold

Here I boost the gc-cons-threshold for my current emacs session. It will be restored after package loading slows down.

(setq gc-cons-threshold VOID:GC-CONS-THRESHOLD-MAX)
(setq gc-cons-percentage VOID:GC-CONS-PERCENTAGE-MAX)

restore threshold after delay

Restore gc-cons-threshold (after a 7 second delay). I got this from doom. We don’t do it immediately because packages are still being lazy loaded at this time.

(defun void:restore-gc-cons-threshold ()
  "Restore `gc-cons-threshold' to `VOID:GC-CONS-PERCENTAGE' after 7 idle seconds."
  (void:log "Restoring...gc-cons-threshold: %d -> %d | gc-cons-percentage %.2f -> %.2f"
            gc-cons-threshold
            VOID:GC-CONS-THRESHOLD
            gc-cons-percentage
            VOID:GC-CONS-PERCENTAGE)
  (setq gc-cons-threshold VOID:GC-CONS-THRESHOLD)
  (setq gc-cons-percentage VOID:GC-CONS-PERCENTAGE))

(run-with-idle-timer 7 nil #'void:restore-gc-cons-threshold)

directories

core directories and files

top level

These are important files and directories that I end up referring to often in my code. Well, not so much VOID:README-FILE and VOID:TODO-FILE but the others are referenced alot.

(defconst VOID:EMACS-DIR (file-truename user-emacs-directory)
  "Path to `user-emacs-directory'.")

(defconst VOID:INIT-FILE (concat VOID:EMACS-DIR "init.el")
  "Path to the elisp file that bootstraps Void startup.")

(defconst VOID:README-FILE (concat VOID:EMACS-DIR "README.org")
  "Path to the Org file that when that Void.")

(defconst VOID:ORG-DIR (expand-file-name "~/Documents/org/")
  "Path where Void's org files go.")

(defconst VOID:SCREENSHOT-DIR (concat VOID:EMACS-DIR "screenshots/")
  "Path where any screenshots I take with Void go.")

(defconst VOID:TEST-FILE (concat VOID:EMACS-DIR "test.org")
  "Path to the file that contains all of Void's tests.")

(defconst VOID:TODO-FILE (concat VOID:ORG-DIR "emacs.org")
  "Path where all of Void's emacs related todos go.")

hidden

(defconst VOID:LOCAL-DIR (concat VOID:EMACS-DIR ".local/")
  "Path to the directory for local Emacs files.
Files that need to exist, but I don't typically want to see go here.")

(defconst VOID:DATA-DIR (concat VOID:LOCAL-DIR "data/")
  "Path to the directory where Void data files are stored.")

(defconst VOID:PACKAGES-DIR (concat VOID:LOCAL-DIR "packages/")
  "Path to the directory where packages are stored.")

system directories

(defconst VOID:DOWNLOAD-DIR (expand-file-name "~/Downloads/")
  "Directory where downloads should go.")

(defconst VOID:MULTIMEDIA-DIR (expand-file-name "~/Multimedia/")
  "Directory where multimedia should go.")

(defconst VOID:VIDEO-DIR (concat VOID:MULTIMEDIA-DIR "Videos/")
  "Directory where videos should go.")

(defconst VOID:MUSIC-DIR (concat VOID:MULTIMEDIA-DIR "Music/")
  "Directory where music should go.")

(defconst VOID:ALERT-SOUNDS (concat VOID:MULTIMEDIA-DIR "Alert Sounds/")
  "Directory where alert sounds should go.")

(defconst VOID:EMAIL-DIR (expand-file-name "~/.mail/")
  "Directories where emails are stored.")

ensure directories exist

I create the directories that don’t exist. But I assume they already exist if Void is compiled.

(dolist (dir (list VOID:LOCAL-DIR VOID:DATA-DIR VOID:ORG-DIR))
  (make-directory dir t))

message logging

Its not uncommon for the Messages buffer to become full of messages.

debug-p

void:debug is snatched from Doom’s doom-debug-mode. The point of this variable is to serve as an indicator of whether the current Void instance is run for debugging. When Void is set up for debugging it prints out many messages about what its doing via void:log.

(defvar void:debug-p (or (getenv "DEBUG") init-file-debug)
  "When non-nil print debug messages.
The --debug-init flag and setting the DEBUG envar will enable this at startup.")

logging

The purpose of void:log is to distinguish regular messages from messages that pertain specifically to Void, and to help debug Void functionality. When Void is void:debug is non-nil, void:specific messages are logged in the *messages* buffer.

(defun void:log (format-string &rest args)
  "Log to *Messages* if `void:debug-p' is on.
Does not interrupt the minibuffer if it is in use, but still log to *Messages*.
Accept the same arguments as `message'."
  (when void:debug-p
    (let ((inhibit-message (active-minibuffer-window)))
      (when void:debug-p
        (apply #'message (concat (propertize "VOID " 'face 'font-lock-comment-face)
                                 format-string)
               args)))))

default coding system

(defconst VOID:DEFAULT-CODING-SYSTEM 'utf-8
  "Default text encoding.")

UTF-8

I set utf-8 as the default encoding for everything except the clipboard on windows. Window clipboard encoding could be wider than utf-8, so we let Emacs/the OS decide what encoding to use.

(when (fboundp 'set-charset-priority)
  (set-charset-priority 'unicode))

Package Manager Bootstrap

straight.el

straight.el is a package manager that strives to make emacs configurations completely reproducable.

customize straight directory

The path of the straight directory within emacs is hardcoded into straight so we need to trick it into thinking VOID:PACKAGES-DIR is the our emacs directory. This needs to be done before bootstraping straight, else the straight directory will be created anyway. I got this from Doom’s straight branch.

(defun straight:use-packages-dir-a (orig-fn &rest args)
  "Use `VOID:PACKAGES-DIR' for straight directory."
  (let ((user-emacs-directory VOID:PACKAGES-DIR))
    (apply orig-fn args)))

(advice-add #'straight--emacs-dir :around #'straight:use-packages-dir-a)

bootstrap code

This code initializes straight if it’s not already installed.

(defun straight:init-fn ()
  "Initialize `straight.el'."
  (defvar bootstrap-version)
  (let* ((user-emacs-directory VOID:PACKAGES-DIR)
         (bootstrap-file
          (expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory))
         (bootstrap-version 5))
    (unless (file-exists-p bootstrap-file)
      (with-current-buffer
          (url-retrieve-synchronously
           "https://raw.githubusercontent.com/raxod502/straight.el/develop/install.el"
           'silent 'inhibit-cookies)
        (goto-char (point-max))
        (eval-print-last-sexp)))
    (load bootstrap-file nil 'nomessage)))

straight-installer

(defun straight:install-package (package-or-recipe)
  "Install PACKAGE with optional RECIPE."
  (unless (featurep 'straight) (straight:init-fn))
  (let ((package (or (car-safe package-or-recipe) package-or-recipe)))
    (condition-case err
        (progn (straight-use-package package-or-recipe)
               (void:log "✓ installed %s" package))
      (error
       (void:log "✕ failed to install %s because of %s" package err)))))

required packages

(dolist (package '(leaf-keywords leaf dash anaphora))
  (funcall #'straight:install-package package)
  (require package))

leaf aliases

The name leaf is not very indicative of what the leaf macro does. Therefore, I alias it to use-package! for external packages, and use-feature! for built-in packages.

(defalias 'use-package! 'leaf)

(defmacro use-feature! (feature &rest args)
  (declare (indent defun))
  `(leaf ,feature :ensure nil ,@args))

Library

This headline contains all the the helper functions and macros I defined for customizing emacs.

macro writing tools

symbols

Conversion between symbols, keywords, and strings are prevalent in macro-writing.

symbol intern

(defun void:symbol-intern (&rest args)
  "Return ARGS as a symbol."
  (declare (pure t) (side-effect-free t))
  (intern (apply #'void:to-string args)))

keyword intern

(defun void:keyword-intern (&rest args)
  "Return ARGS as a keyword."
  (declare (pure t) (side-effect-free t))
  (apply #'void:symbol-intern ":" args))

keyword name

(defun void:keyword-name (keyword)
  "Return the name of the KEYWORD without the prepended `:'."
  (declare (pure t) (side-effect-free t))
  (substring-no-properties (void:to-string keyword) 1))

convert to string

(defun void:to-string (&rest args)
  "Return ARGS as a string."
  (declare (pure t) (side-effect-free t))
  (with-output-to-string
    (dolist (a args) (princ a))))

wrap-form

When writing macros in lisp it is not uncommon to need to write a macro that can nest a form within some number of other forms (for an example, see after!). This macro makes this problem much easier.

(defun void:wrap-form (wrappers form)
  "Wrap FORM with each wrapper in WRAPPERS.
WRAPPERS are a list of forms to wrap around FORM."
  (declare (pure t) (side-effect-free t))
  (setq wrappers (reverse wrappers))
  (if (consp wrappers)
      (void:wrap-form (cdr wrappers)
                      (append (car wrappers)
                              (list form)))
    form))

anaphora

Anaphora refers to the ability to refer to. I have decided it is best to use <> to denote the symbol referred to by anaphoric macros because it is easy to type (assuming parentheses completion), because such a symbol uncommon in lisp. A key advantage to this is that there is a consistent “syntax” for anaphoric variables as opposed to using it. A consequence of this is that you have more flexibility to name variables. Additionally, I like that it looks like a slot or placeholder.

https://en.wikipedia.org/wiki/Anaphoric_macro

anaphoric symbol regexp

(defconst VOID:ANAPHORIC-SYMBOL-REGEXP
  (eval-when-compile (rx "<" (group (1+ (not (any white ">" "<")))) ">"))
  "Regular expression that matches an anaphoric symbol.")

anaphoric symbol

(defun void:anaphoric-symbol-p (obj)
  "Return non-nil if OBJ is an anaphoric symbol."
  (and (symbolp obj)
       (string-match-p VOID:ANAPHORIC-SYMBOL-REGEXP (symbol-name obj))))

true anaphora name

(defun void:anaphoric-true-symbol (symbol)
  "Return the symbol that corresponds to the anaphoric symbol."
  (save-match-data
    (string-match VOID:ANAPHORIC-SYMBOL-REGEXP (symbol-name symbol))
    (intern (match-string 1 (symbol-name symbol)))))

body symbols

(defun void:anaphoric-symbols (body)
  "Return all the anaphoric symbols in body."
  (->> (-flatten body)
    (-filter #'void:anaphoric-symbol-p)
    (-uniq)))

all anaphoric symbols in obj

(defun void:anaphoric-symbols-in-obj (obj)
  "Return a list of anaphoric symbols in OBJ."
  (s-match-strings-all VOID:ANAPHORIC-SYMBOL-REGEXP (void:to-string obj)))

with-symbols!

(defmacro with-symbols! (names &rest body)
  "Bind each variable in NAMES to a unique symbol and evaluate BODY."
  (declare (indent defun))
  `(let ,(-map (lambda (symbol) `(,symbol (make-symbol ,(symbol-name symbol)))) names)
     ,@body))

once-only!

(defmacro once-only! (bindings &rest body)
  "Rebind symbols according to BINDINGS and evaluate BODY.

Each of BINDINGS must be either a symbol naming the variable to be
rebound or of the form:

  (SYMBOL INITFORM)

where INITFORM is guaranteed to be evaluated only once.

Bare symbols in BINDINGS are equivalent to:

  (SYMBOL SYMBOL)"
  (declare (indent defun))
  (let* ((bind-fn (lambda (bind)
                    (if (consp bind)
                        (cons (car bind) (cadr bind))
                      (cons bind bind))))
         (names-and-forms (-map bind-fn bindings))
         (names (-map #'car names-and-forms))
         (forms (-map #'cdr names-and-forms))
         (symbols (--map (make-symbol (symbol-name it)) names)))
    `(with-symbols! ,symbols
       (list 'let
             (-zip-with #'list (list ,@symbols) (list ,@forms))
             ,(cl-list* 'let
                        (-zip-with #'list names symbols)
                        body)))))

deferred loading

with-os!

Emacs is for the most part operating system agnostic. Packages written in elisp should work across operating systems. Nevertheless, there are a handful of settings that should favors particular operating systems over others.

(defmacro with-os! (os &rest body)
  "If OS is current system's operating system, execute body.
OS can be either `mac', `linux' or `windows'(unquoted)."
  (declare (indent defun))
  (setq os (if (listp os) os (list os)))
  (when (funcall (cond ((eq :not (car-safe os)) (lambda (a b) (not (member a b))))
                       (t #'member))
                 (pcase system-type
                   (`darwin 'mac)
                   (`gnu/linux 'linux)
                   (`(cygwin windows-nt ms-dos) 'windows)
                   (_ nil))
                 os)
    `(progn ,@body)))

defhook!

(defmacro defhook! (name args &rest body)
  "Define a hook function."
  (-let* ((docstring (when (stringp (car body)) (pop body)))
          ((key hooks . body) body)
          (append (eq key :append))
          (local (eq key :local)))
    `(prog1 (defun ,name ,args ,docstring ,@body)
       ,@(-map (lambda (hook) `(add-hook ',hook #',name ,append ,local))
               (-list hooks)))))

defadvice!

(defmacro defadvice! (name args &rest body)
  "Add advice."
  (-let ((docstring (when (stringp (car body)) (pop body)))
         ((key advices . body) body))
    `(prog1 (defun ,name ,args ,docstring ,@body)
       ,@(--map `(advice-add #',it ,key #',name)
                (-list advices)))))

eval-after-load!

If an eval-after-load block contains an error and it is triggered by a feature, the error will keep raised everytime you load that feature.

(defmacro eval-after-load! (feature &rest body)
  ""
  (declare (indent defun))
  `(eval-after-load ',feature
     '(with-no-warnings
        (condition-case error
            (progn ,@body)
          (error
           (message "Error: %S" error)
           (message "BODY: %S" ',body))))))

after!

The reason that we check for the feature is to prevent eval-after-load from polluting the after-load-list. eval-after-load adds an entry to after-load-list whether or not it has been loaded.

We intentionally avoid with-eval-after-load to prevent eager macro expansion from pulling (or failing to pull) in autoloaded macros/features.

(defmacro after! (features &rest body)
  "Same as `with-eval-after-load' but."
  (declare (indent defun) (debug t))
  (pcase (car-safe features)
    ('or
     (macroexp-progn
      (--map `(after! ,it ,@body) (cdr features))))
    ('and
     (void:wrap-form (--map `(after! ,it) (cdr features))
                     (macroexp-progn body)))
    ((guard (listp features))
     `(after! ,(cons 'and features) ,@body))
    ((pred symbolp)
     `(if (featurep ',features)
          ,(macroexp-progn body)
        (eval-after-load! ,features ,@body)))
    (_ (error "Invalid argument."))))

macros

ignore!

(defmacro ignore! (&rest _)
  "Do nothing and return nil."
  nil)

anaphoric macros

pair value extraction

When extracting one value from a plist, alist or another lisp data structure at a time, it often suffices to use plist-get, alist-get or whatever function is used to get a particular value based on the structure. Sometimes, however, we need to get and use many values from the data structure. And in these cases it becomes repetative to have to do (plist-get plist key) all the time.

with-structure!

(defmacro with-structure! (structure fn &rest body)
  "Access items from STRUCTURE.
FN is a function that accepts two arguments, the structure and a symbol name. FN
should return the value of structure for that symbol.
BODY contains any number of `<NAME>' where NAME refers to the name of the symbol."
  (declare (indent 2))
  (let* ((symbols (->> (flatten-list body)
                       (-filter #'void:anaphoric-symbol-p)
                       (-uniq)))
         (names (-map #'void:anaphoric-true-symbol symbols))
         (structure-sym (make-symbol "structure")))
    `(let* ((,structure-sym ,structure)
            ,@(--map `(,it (funcall ,fn ,structure-sym ',it))
                     (-zip #'list symbols names)))
       ,@body)))

with-plist!

(defmacro with-plist! (plist &rest body)
  (declare (indent 1))
  `(with-structure! ,plist #'plist-get ,@body))

with-alist!

(defmacro with-alist! (alist &rest body)
  (declare (indent 1))
  `(with-structure! ,alist (lambda (key) (alist-get key alist)) ,@body))

list mutation

append!

(defmacro append! (sym &rest lists)
  "Append LISTS to SYM.
SYM is a symbol that stores a list."
  (declare (indent 1))
  `(setq ,sym (append ,sym ,@lists)))

prepend!

(defmacro prepend! (sym &rest lists)
  (declare (indent defun))
  `(setq ,sym (append ,@lists ,sym)))

nconc!

(defmacro nconc! (sym &rest lists)
  "Append LISTS to SYM by altering them in place."
  (declare (indent 1))
  `(setq ,sym (nconc ,sym ,@lists)))

Leaf

Like use-package, leaf is a macro that fascilitates package configuration.

leaf

(use-package! leaf
  :setq
  (leaf-defaults . '(:ensure t))
  (leaf-expand-minimally . t))

leaf-keywords

(use-package! leaf-keywords
  :ensure nil
  :init (leaf-keywords-init))

defining leaf keywords

Leaf is very low level. It does not provide a function or macro for fast new keyword creation. Whenever you want to create a new keyword you have to recall the underlying leaf data structure.

leaf variables

(defvar leaf:process-variables
  '(leaf--raw leaf--name leaf--key leaf--keyname leaf--value leaf--body)
  "List of variables that leaf binds when processing a keyword.")

leaf insert keyword

(defun leaf:insert-keyword (keyword where place form)
  "Insert KEYWORD at PLACE.
WHERE can be the symbol `before' or `after'."
  (alet (pcase where
          ('after #'leaf-insert-list-after)
          ('before #'leaf-insert-list-before)
          (_ (error "where is %S but expected `before' or `after'" where)))
    (setq leaf-keywords
          (funcall it leaf-keywords place (list keyword form)))))

defer

(defun leaf:make-defer (keyword)
  "Add KEYWORD to `leaf-defer-keywords'."
  (add-to-list 'leaf-defer-keywords keyword))

alias

(defun leaf:set-alias (alias name)
  "Set ALIAS to NAME."
  (push (cons alias name) leaf-alias-keyword-alist))

define-leaf-keyword!

(defmacro define-leaf-keyword! (name args &rest body)
  "Define a leaf keyword."
  (declare (indent defun))
  (-let* ((keyword (intern (concat ":" (symbol-name name))))
          ((where place) args)
          (docstring (when (stringp body) (pop body)))
          (actions (--unfold (when (keywordp (car it))
                               (cons (-take 2 it)
                                     (setq body (-drop 2 it))))
                             body))
          (apply-fn (intern (concat "leaf::apply-" (symbol-name name))))
          (form `(,apply-fn ,@leaf:process-variables)))
    `(progn
       (leaf:insert-keyword ,keyword ',where ,place ',form)
       (defun ,apply-fn ,leaf:process-variables
         ,docstring
         (ignore ,@leaf:process-variables)
         ,@body))))

normalizer

add normalizer

(defun leaf:set-normalizer (keyword normalizer)
  "Add KEYWORD."
  (push `((or (memq leaf--key '(,keyword))
              (eq (alist-get leaf--key leaf-alias-keyword-alist) ,keyword))
          (funcall #',normalizer leaf--value))
        leaf-normalize))

normalizers

normalizers

leaf’s setq does not correctly handle setting variables to forms that need to be evaluated.

(defun leaf:normalize-setq (leaf--value)
  (-map (-lambda ((var . value)) (cons var value))
        leaf--value))

(defun leaf:normalize-commands (leaf--value)
  (-map (lambda (elm)
          (cond ((memq leaf--key '(:after))
                 (if (eq elm t) leaf--name elm))
                (t elm)))
        (-uniq (delq nil (leaf-flatten leaf--value)))))

use `after!` in leaf-defer

(leaf:set-alias :leaf-defer :void-leaf-defer)

(define-leaf-keyword! void-leaf-defer (before :leaf-defer)
  (if (and leaf--body (eval (car leaf--value))
           (leaf-list-memq leaf-defer-keywords (leaf-plist-keys leaf--raw)))
      `((after! ,leaf--name ,@leaf--body))
    `(,@leaf--body)))

custom leaf keywords

set keywords

Leaf keywords do not.

setq

(leaf:set-normalizer :setq #'leaf:normalize-setq)

pre-setq

(leaf:set-normalizer :pre-setq #'leaf:normalize-setq)

custom

(leaf:set-normalizer :custom #'leaf:normalize-setq)

setq-default

(leaf:set-normalizer :setq-default #'leaf:normalize-setq)

defer keywords

These keywords are meant to improve on the deferred loading options already provided by leaf. They are inspired from DOOM emacs.

leaf-generate-load-fn

(defun leaf:generate-load-form (package &optional hooks advice-place advices)
  "Return form that evals into function that loads the package."
  (let ((load-fn (intern (concat "leaf:load-" (symbol-name package)))))
    `(progn
       (defun ,load-fn (&rest _)
         (void:log "Loading %S..." ',package)
         (unless (require ',package nil t)
           (message "Error loading %S" ',package))
         ,@(mapcar (lambda (hook) `(remove-hook ',hook #',load-fn)) hooks)
         ,@(mapcar (lambda (advice) `(advice-remove #',advice #',load-fn)) advices)
         (fmakunbound #',load-fn))
       ,@(mapcar (lambda (hook) `(add-hook ',hook #',load-fn)) hooks)
       ,@(mapcar (lambda (advice) `(advice-add #',advice ,advice-place #',load-fn)) advices))))

before-call

(leaf:make-defer :before-call)

(leaf:set-normalizer :before-call #'leaf:normalize-commands)

(define-leaf-keyword! before-call (before :hook)
  `(,(leaf:generate-load-form leaf--name nil :before leaf--value)
    ,@leaf--body))

after-call

(leaf:make-defer :after-call)

(leaf:set-normalizer :after-call #'leaf:normalize-commands)

(define-leaf-keyword! after-call (before :hook)
  `(,(leaf:generate-load-form leaf--name nil :after leaf--value)
    ,@leaf--body))

defer-incrementally

(define-leaf-keyword! idle-require (before :before-call)
  `((-each ',leaf--value #'idle-require)
    ,@leaf--body))

straight keyword

This keyword is designed to be compiled away, leaving only forms adding package paths to the load-path. This is so that package installation isn’t done after VOID is compiled.

(leaf:set-alias :straight :void-straight)
(leaf:set-alias :ensure :void-straight)

(leaf:set-normalizer :void-straight #'leaf:void-straight-normalizer)

(define-leaf-keyword! void-straight (before :straight)
  `(,@(when (and leaf--value (car-safe leaf--value))
        `((straight:install-package ',(car leaf--value))))
    ,@leaf--body))

(defun leaf:void-straight-normalizer (leaf--value)
  (cond ((eq t (car leaf--value))
         (list leaf--name))
        ((eq nil (car leaf--value))
         nil)
        ((listp (car-safe leaf--value))
         (list (cons leaf--name (car leaf--value))))))

popup

The point of this keyword is to let me configure the display of buffers for specific packages.

(define-leaf-keyword! popup (before :mode)
  `(,@(--map `(push ',it display-buffer-alist) leaf--value)
    ,@leaf--body))

os

(define-leaf-keyword! os (before :when)
  (when leaf--body `((with-os! ,leaf--value ,@leaf--body))))

straight

(use-package! straight
  :require t
  :setq
  (straight-disable-autoloads . nil)
  (straight-cache-autoloads . t)
  (straight-check-for-modifications . nil)
  (straight-enable-package-integration . nil)
  (straight-recipes-emacsmirror-use-mirror . t))

alias

(leaf:set-normalizer :alias #'leaf:normalize-setq)

(define-leaf-keyword! alias (before :init)
  `((eval-and-compile
      ,@(-map (-lambda ((alias . def)) `(defalias ',alias ',def))
              leaf--value))
    ,@leaf--body))

ignore-buffers

(leaf:set-normalizer :ignore-buffers #'leaf:normalize-commands)

(define-leaf-keyword! ignore-buffers (before :init)
  `((after! midnight
      (--each ',leaf--value
        (push it clean-buffer-list-kill-regexps)))
    ,@leaf--body))

Packages

built-in

vc-hook

(use-feature! vc-hooks
  :setq
  (vc-follow-link . t)
  (vc-follow-symlinks . t))

subr-x

(use-feature! subr-x :require t)

startup

Emacs starts up with a default screen setup. No, thanks.

(use-feature! startup
  :setq
  (inhibit-startup-screen . t)
  (inhibit-default-init . t)
  (inhibit-startup-buffer-menu . t)
  (initial-major-mode . 'fundamental-mode)
  (initial-scratch-message . nil)
  (initial-buffer-choice . (if void:debug-p (lambda () (get-buffer "*Messages*")) t))
  (inhibit-startup-echo-area-message . user-login-name))

paren

(use-feature! paren
  :hook (prog-mode-hook . show-paren-mode)
  :setq-default
  (show-paren-delay . 0))

clipboard

;; Not windows.
(use-feature! select
  :setq
  (selection-coding-system . 'utf-8)
  (select-enable-clipboard . t)
  (select-enable-primary . t)
  (x-select-request-type . '(UTF8_STRING COMPOUND_TEXT TEXT STRING)))

simple

(use-feature! simple
  :popup ("\\*Messages"
          (display-buffer-at-bottom)
          (window-height . 0.5))
  :setq-default
  (idle-update-delay . 1)
  (blink-matching-paren . t)
  (delete-trailing-lines . nil)
  :setq
  (mail-user-agent . 'mu4e-user-agent))

loaddefs

These are extremely important lines if you use an external program as I do (msmtp) to send your email. If you don’t set these variables, emacs will think you want to use smtp.

(use-feature! loaddefs
  :setq-default
  (disabled-command-function . nil)
  ;; very important if you're using msmtp
  )

files

(use-feature! files
  :setq-default
  ;; Disable second, case-insensitive pass over `auto-mode-alist'.
  (auto-mode-case-fold . nil)
  ;; Whether to add a newline automatically at the end of the file.
  ;; Whether confirmation is requested before visiting a new file or buffer.
  (confirm-nonexistent-file-or-buffer . nil)
  ;; How to ask for confirmation when leaving Emacs.
  (confirm-kill-emacs . #'y-or-n-p)
  (require-final-newline . nil)
  (trash-directory . (expand-file-name "Trash" "~"))
  (auto-save-default . nil)
  (auto-save-interval . 300)
  (auto-save-timeout . 30)
  (backup-directory-alist . (list (cons ".*" (concat VOID:DATA-DIR "backup/"))))
  (make-backup-files . nil)
  (version-control . nil)
  (kept-old-versions . 2)
  (kept-new-versions . 2)
  (delete-old-versions . t)
  (backup-by-copying . t)
  (backup-by-copying-when-linked . t))

subr

(use-feature! subr
  :init
  (fset #'yes-or-no-p #'y-or-n-p)
  (fset #'display-startup-echo-area-message #'ignore))

subr-x

;; This is where `->>' and `thread-first' come from.
(use-feature! subr-x
  :require t)

ffap

Don’t ping things that look like domain names.

(use-feature! ffap
  :setq
  (ffap-machine-p-known . 'reject))

server

(use-feature! server
  :setq
  (server-auth-dir . (concat VOID:DATA-DIR "server/")))

tramp

(use-feature! tramp
  :setq
  (tramp-backup-directory-alist . backup-directory-alist)
  (tramp-auto-save-directory . (concat VOID:DATA-DIR "tramp-auto-save/"))
  (tramp-persistency-file-name . (concat VOID:DATA-DIR "tramp-persistency.el")))

desktop

(use-feature! desktop
  :setq
  (desktop-dirname . (concat VOID:DATA-DIR "desktop"))
  (desktop-base-file-name . "autosave")
  (desktop-base-lock-name . "autosave-lock"))

cus-edit

(use-feature! cus-edit
  :setq
  (custom-file . (concat VOID:DATA-DIR "custom.el"))
  (custom-theme-directory . (concat VOID:LOCAL-DIR "themes/")))

url cache

(use-feature! url
  :setq
  (url-cache-directory . (concat VOID:DATA-DIR "url/cache/"))
  (url-configuration-directory . (concat VOID:DATA-DIR "url/configuration/")))

bytecomp

(use-feature! bytecomp
  :setq
  (byte-compile-verbose . void:debug-p)
  (byte-compile-warnings . '(not free-vars unresolved noruntime lexical make-local)))

compile

(use-feature! compile
  :setq-default
  (compilation-always-kill . t)
  (compilation-ask-about-save . nil)
  (compilation-scroll-output . 'first-error))

uniquify

(use-feature! uniquify
  :setq-default
  (uniquify-buffer-name-style . 'forward))

ansi-color

(use-feature! ansi-color
  :setq-default
  (ansi-color-for-comint-mode . t))

image mode

(use-feature! image-mode
  :setq
  ;; Non-nil means animated images loop forever, rather than playing once.
  (image-animate-loop . t))

window

(use-feature! window
  :setq-default
  (split-width-threshold . 160))

paragraphs

(use-feature! paragraphs)

indent

(use-feature! indent
  :setq-default
  (tab-always-indent . t))

mouse

(use-feature! mouse
  :setq-default
  (mouse-yank-at-point . t))

calendar

(use-feature! calendar
  :setq (diary-file . (concat VOID:DATA-DIR "diary")))

mule-cmds

(use-feature! mule-cmds
  :init (prefer-coding-system VOID:DEFAULT-CODING-SYSTEM))

gv

gv is what contains the code for the setf macro. https://emacs.stackexchange.com/questions/59314/how-can-i-make-setf-work-with-plist-get

(use-feature! gv
  :defer-config
  (gv-define-simple-setter plist-get plist-put))

nsm

(use-feature! nsm
  :setq (nsm-settings-file . (concat VOID:DATA-DIR "network-settings.data")))

external libraries

dash-functional

(use-package! dash-functional :require t)

dash

Dash is an excellent functional list manipulation library. If I did not use it as a dependency, I’d end up rewriting many of its functions.

(use-package! dash :require t)

general

Keybindings are a key part of emacs (pun intended).

general

There are numerous keybinding functions in Emacs; and they all look a little different: there’s global-set-key, local-set-key, define-key and the list goes on. And with [[][evil]] which I use , there’s also evil-global-set-key and evil-define-key. It would be nice to have one keybinding function that can handle all bindings. [[][general]] provides such a function (general-define-key).

(use-package! general
  :require t
  :config
  (general-auto-unbind-keys))

prefix bindings

A popular strategy to mitigate the mental load of remembering many keybindings is to bind them in a tree-like fashion. [[][spacemacs]].

leader Keys

(defvar void:leader-key "SPC"
  "The evil leader prefix key.")

(defvar void:leader-alt-key "M-SPC"
  "The leader prefix key used for Insert and Emacs states.")

localleader keys

(defvar void:localleader-key "SPC m"
  "The localleader prefix key for major-mode specific commands.")

(defvar void:localleader-alt-key "C-SPC m"
  "The localleader prefix key for major-mode specific commands.")

(defvar void:localleader-short-key ","
  "A shorter alternative `void:localleader-key'.")

(defvar void:localleader-short-alt-key "M-,"
  "A short non-normal  `void:localleader-key'.")

definers

As I’ve mentioned general uses the function general-define-key as a generic do-all key binder. Sometimes though we have keys that we want to bind with specific arguments to general-define-key pretty often. A typical example of this is binding leader or localleader keys like spacemacs.

(general-create-definer define-leader-key!
  :prefix void:leader-key
  :non-normal-prefix void:leader-alt-key
  :keymaps 'override
  :states '(normal motion insert emacs))

localleader

There’s pros and cons to the SPC m binding. The main pro is that it’s consistent with SPC. With the leader and the localleader, this means that you can reach any binding from just SPC. This means that you can discover all bindings from just one root binding. This is a nice property to have. On the other hand, bindings can get a bit long. That one extra character can really make a difference. That’s why.

(defmacro define-localleader-key! (&rest args)
  (declare (indent defun))
  (let ((shared-args '(:keymaps 'override :states '(normal motion insert emacs))))
    `(progn (general-def
              ,@args
              ,@shared-args
              :prefix void:localleader-key
              :non-normal-prefix void:localleader-alt-key)
            (general-def
              ,@args
              ,@shared-args
              :prefix void:localleader-short-key
              :non-normal-prefix void:localleader-short-alt-key))))

s

(use-package! s :require t)

gc

Wait until idle time to garbage collect while staving off garbage collector while the user is working.

(use-package! gcmh
  :hook emacs-startup-hook
  :setq
  (gcmh-idle-delay . 10)
  (gcmh-verbose . void:debug-p)
  (gcmh-high-cons-threshold . (* 16 1024 1024)))

shut-up

(use-package! shut-up
  :commands shut-up
  :init
  (defalias 'shut-up! 'shut-up)
  (defalias 'quiet! 'shut-up))

keyfreq

(use-package! keyfreq :hook emacs-startup-hook)

Initialize

defined in c source code

default settings

(setq-default fringe-indicator-alist
              (delq (assq 'continuation fringe-indicator-alist)
                    fringe-indicator-alist))
(setq-default highlight-nonselected-windows nil)
(setq-default indicate-buffer-boundaries nil)
(setq-default inhibit-compacting-font-caches t)
(setq-default max-mini-window-height 0.3)
(setq-default mode-line-default-help-echo nil)
(setq-default mouse-yank-at-point t)
(setq-default resize-mini-windows 'grow-only)
(setq-default show-help-function nil)
(setq-default use-dialog-box nil)
(setq-default visible-cursor t)
(setq-default x-stretch-cursor nil)
(setq-default ring-bell-function #'ignore)
(setq-default visible-bell nil)
(setq-default window-resize-pixelwise t)
(setq-default frame-resize-pixelwise t)

compilation

;; Non-nil means load prefers the newest version of a file.
(setq-default load-prefer-newer t)

all

;; File name in which to write a list of all auto save file names.
(setq auto-save-list-file-name (concat VOID:DATA-DIR "autosave"))
;; Directory of score files for games which come with GNU Emacs.
(setq shared-game-score-directory (concat VOID:DATA-DIR "shared-game-score/"))

(setq-default cursor-in-non-selected-windows nil)

(setq highlight-nonselected-windows nil)

;; When non-nil, accelerate scrolling operations.
(setq fast-but-imprecise-scrolling t)

(setq-default frame-inhibit-implied-resize t)

;; Non-nil means use lockfiles to avoid editing collisions.
(setq-default create-lockfiles nil)
;; Non-nil says by default do auto-saving of every file-visiting buffer.
(setq-default history-length 500)
;; Specifies whether to use the system's trash can.
(setq-default delete-by-moving-to-trash t)

;; Disabling bidirectional text provides a small performance boost. Bidirectional
;; text is useful for languages that read right to left.
(setq-default bidi-display-reordering 'left-to-right)
(setq-default bidi-paragraph-direction 'left-to-right)

;; Non-nil means echo keystrokes after this many seconds. A value of zero means
;; don't echo at all.
(setq-default echo-keystrokes 0)

;; Template for displaying mode line for current buffer.
(setq-default mode-line-format nil)

(setq-default locale-coding-system VOID:DEFAULT-CODING-SYSTEM)
(setq-default buffer-file-coding-system VOID:DEFAULT-CODING-SYSTEM)

scrolling

(setq-default hscroll-margin 2)
(setq-default hscroll-step 1)
(setq-default scroll-conservatively 1001)
(setq-default scroll-margin 0)
(setq-default scroll-preserve-screen-position t)

spacing

(setq-default fill-column 80)
(setq-default sentence-end-double-space nil)
(setq-default tab-width 4)

line wrapping

(setq-default word-wrap t)
(setq-default indicate-empty-lines nil)
(setq-default indent-tabs-mode nil)
(setq-default truncate-lines t)
(setq-default truncate-partial-width-windows 50)

other

;; Non-nil means reorder bidirectional text for display in the visual order.
;; Disabling this gives Emacs a tiny performance boost.
(setq-default bidi-display-reordering nil)
(setq-default cursor-in-non-selected-windows nil)
(setq-default display-line-numbers-width 3)
(setq-default enable-recursive-minibuffers t)
(setq-default frame-inhibit-implied-resize t)

printing

When eval and replacing expressions, I want the printed result to express all newlines in strings as \n as opposed to an actual newline. In fact, in general I want any character to be expressed in backslash + number or character form. It makes the strings more readable and easier to deal with.

Furthermore, I’d like printed lisp expressions to express quoted forms the way I write them, with a ' as opposed to the literal (quote ...).

There comes a point when output is too long, or too nested to be usable. It’s ok to abbreviate it at this point.

(setq-default print-escape-newlines t)
(setq-default print-escape-multibyte t)
(setq-default print-escape-control-characters t)
(setq-default print-escape-nonascii t)
(setq-default print-length nil)
(setq-default print-level nil)
(setq-default print-quoted t)
(setq-default print-escape-newlines t)

OS

`abbreviated-home-dir`

Emacs on windows often confuses HOME (C:\Users\<NAME>) and APPDATA, causing abbreviate-home-dir to produce incorrect paths.

(with-os! windows
  (setq abbreviated-home-dir "\\`'"))

font caches

Font compacting can be terribly expensive, especially for rendering icon fonts on Windows. Whether it has a noteable affect on Linux and Mac hasn’t been determined.

(with-os! windows
  (setq inhibit-compacting-font-caches t))

windows performance

Reduce the workload when doing file IO.

(with-os! windows
  (setq w32-get-true-file-attributes nil))

unnecessary command line options

Some command line options aren’t necessary.

(with-os! (not linux)
  (setq command-line-x-option-alist nil))

(with-os! (not mac)
  (setq command-line-ns-option-alist nil))

windows

(with-os! windows
  (setq w32-get-true-file-attributes nil)
  (when (display-graphic-p)
    (setenv "GIT_ASKPASS" "git-gui--askpass")))

mac

defaults

(with-os! mac
  (setq mac-command-modifier 'meta)
  (setq mac-option-modifier  'alt)
  ;; sane trackpad/mouse scroll settings
  (setq mac-redisplay-dont-reset-vscroll t)
  (setq mac-mouse-wheel-smooth-scroll nil)
  ;;  one line at a time
  (setq mouse-wheel-scroll-amount '(5 ((shift) . 2)))
  ;; don't accelerate scrolling
  (setq mouse-wheel-progressive-speed nil)
  (setq ns-use-native-fullscreen nil)
  ;; Don't open files from the workspace in a new frame
  (setq ns-pop-up-frames nil))

exec path from shell

A known problem with GUI Emacs on MacOS (or daemons started via launchctl or brew services): it runs in an isolated environment, so envvars will be wrong. That includes the path Emacs picks up. exec-path-from-shell fixes this.

(leaf exec-path-from-shell
  :os mac
  :when (or (daemonp) (display-graphic-p))
  :require t
  :setq
  (exec-path-from-shell-check-startup-files . nil)
  (exec-path-from-shell-arguments . (delete "-i" exec-path-from-shell-arguments))
  (exec-path-from-shell-debug . void:debug-p)
  :init
  (nconc! exec-path-from-shell-variables
    '("LC_CTYPE" "LC_ALL" "LANG"))
  (exec-path-from-shell-initialize))

ns-auto-titlebar

ns-auto-titlebar syncs ns frame parameters with theme and fixes mismatching text color in the frame title.

(use-package! ns-auto-titlebar
  :os mac
  :when (or (daemonp) (display-graphic-p))
  :require t)

osx-clipboard

(use-package! osx-clipboard
  :os mac
  :when (or (daemonp) (not (display-graphic-p)))
  :hook emacs-startup-hook)

linux

(with-os! linux
  (setq x-underline-at-descent-line t)
  (setq x-gtk-use-system-tooltips nil))

void specific funtions

windows

split-right-and-focus

(defun void/window-split-right-and-focus ()
  "Split window right and select the window created with the split."
  (interactive)
  (select-window (split-window-right)))

split-below-and-focus

(defun void/window-split-below-and-focus ()
  "Split window below and select the window created with the split."
  (interactive)
  (select-window (split-window-below)))

all

quit emacs without hook

Sometimes something goes wrong with kill-emacs-hook and because of that I can’t close emacs. For that reason, I have this function.

(defun void/kill-emacs-no-hook ()
  "Kill emacs, ignoring `kill-emacs-hook'."
  (interactive)
  (when (yes-or-no-p "Quit without `kill-emacs-hook'?")
    (let (kill-emacs-hook) (kill-emacs))))

quit emacs brutally

I’ve never had to use this. But better be safe than sorry.

(defun void/kill-emacs-brutally ()
  "Tell an external process to kill emacs."
  (interactive)
  (when (yes-or-no-p "Do you want to BRUTALLY kill emacs?")
    (call-process "kill" nil nil nil "-9" (number-to-string (emacs-pid)))))

new emacs instance

(defun void/open-emacs-instance ()
  "Open a new emacs instance in debug-mode."
  (interactive)
  (cond ((eq system-type 'darwin)
         (start-process-shell-command
          "emacs"
          nil "open -n /Applications/Emacs.app --args --debug-init"))
        ((eq system-type 'gnu/linux)
         (start-process "emacs" nil "emacs" "--debug-init"))))

kill all process of program

(defun void/kill-emacs-processes ()
  (interactive)
  (let ((count 1) (process "emacs"))
    (kill-process process)
    (while (ignore-errors (kill-process process))
      (setq process (format "emacs<%d>" count))
      (cl-incf count))
    (message "killed %d processes" count)))

qutebrowser

(defun void/open-qutebrowser ()
  "Open qutebrowser."
  (interactive)
  (start-process "qutebrowser" nil "qutebrowser"))

messages buffer

In Emacs, messages. The messages buffer is where messages displayed at the bottom of the Emacs frame are recorded after they expire.

(defun void/switch-to-messages ()
  (interactive)
  (select-window (display-buffer (get-buffer "*Messages*"))))

main org file

(defun void/switch-to-main-org-file ()
  (interactive)
  (find-file (concat VOID:EMACS-DIR "README.org")))

main todo file

(defun void/switch-to-todo-file ()
  (interactive)
  (switch-to-buffer (find-file VOID:TODO-FILE)))

turn on debug-mode

(defun void/enable-debug-mode ()
  (interactive)
  (setq void:debug-p t))

switch to init file

(defun void/switch-to-init-org-file ()
  "Switch to Void's init.el file."
  (interactive)
  (switch-to-buffer VOID:INIT-FILE))

quit emacs no prompt

(defun void/quit-emacs-no-prompt ()
  "Quit emacs without prompting."
  (interactive)
  (let (confirm-kill-emacs)
    (kill-emacs)))

post init

idle require

This package.

(use-package! idle-require
  :require t
  :hook emacs-startup-hook
  :setq
  (idle-require-idle-delay . 7)
  (idle-require-load-break . 2))

`tty`

When running emacs in terminal tty is tremendously slow.

(unless (display-graphic-p)
  (advice-add #'tty-run-terminal-initialization :override #'ignore)
  (defhook! void:init-tty-h ()
    :hook window-setup-hook
    (advice-remove #'tty-run-terminal-initialization #'ignore)
    (tty-run-terminal-initialization (selected-frame) nil t)))

minibuffer

minibuffer-setup-hook and minibuffer-exit-hook are the hooks run just before entering and exiting the minibuffer (respectively). In the minibuffer I’ll be primarily doing searches for variables and functions. There are alot of variables and functions so this can certainly get computationally expensive. To keep things snappy I increase boost the gc-cons-threshold just before I enter the minibuffer, and restore it to it’s original value a few seconds after it’s closed.

It would take me forever to guess the name minibuffer-setup-hook from the variable minibuffer-exit-hook. If I knew the name minibuffer-exit-hook but did not know what the hook to enter the minibuffer was, I’d probably minibuffer-enter-hook because “enter” is one of the main antonyms of “exit”. It’d take me forever to guess startup. Note that the only tricky thing about this example.

At first I thought of entry but after more thought I realized hook variables use action verbs in their names not nouns. So the exit in minibuffer-exit-hook is actually the verb exit not the noun.

(defvaralias 'minibuffer-enter-hook 'minibuffer-setup-hook)

(defhook! void:boost-garbage-collection-h ()
  "Boost garbage collection settings to `VOID:GC-CONS-THRESHOLD-MAX'."
  :hook minibuffer-enter-hook
  (setq gc-cons-threshold VOID:GC-CONS-THRESHOLD-MAX))

(defhook! void:defer-garbage-collection-h ()
  "Reset garbage collection settings to `void:gc-cons-threshold' after delay."
  :append minibuffer-exit-hook
  (run-with-idle-timer 3 nil (lambda () (setq gc-cons-threshold VOID:GC-CONS-THRESHOLD))))

tangling

tangle hook

Void tangles itself just before quitting if void:needs-tangling-p returns true. I tangle before quitting so I don’t have to do it before startup. It’s preferable for quitting emacs to be slightly slower than for emacs startup to be.

(defhook! void:tangle-on-quit-maybe-h ()
  "Tangle if `void:needs-tangling-p' returns t."
  :append kill-emacs-hook
  (when (void:needs-tangling-p)
    (void/tangle-org-file)))

tangle asynchronously upon saving

This is another attempt to keep my main.el file in sync as much as possible with void:main-org-file. void:tangle-on-save-h is called whenever a buffer is being saved to a file. The reason why I use cl-letf to temporarily override load is because VOID:INIT-FILE already contains all the code I need so I don’t want it to waste time loading void:main-elisp-file.

(defhook! void:tangle-on-save-h ()
  "Tangle `VOID:README-FILE' asynchronously when it is saved."
  :hook after-save-hook
  (when (and (require 'async nil t)
             (string= (file-truename VOID:README-FILE)
                      (or (buffer-file-name (current-buffer)) ""))
             (void:needs-tangling-p))
    (async-start
     (lambda ()
       (let ((old-fn (symbol-function 'load))
             (user-init-file (concat user-emacs-directory "init.el")))
         (require 'cl)
         (cl-letf (((symbol-function 'load)
                    (lambda (file &rest args)
                      (when (string= user-init-file file)
                        (apply old-fn file args)))))
           (load user-init-file))))
     (lambda (_)
       (void:log
        (concat (if (void:needs-tangling-p) "✕ failed" "✓ succeeded")
                " tangling `VOID:README-FILE'."))))))

UI

maybe get rid of UI elements

Emacs 27 and above allows the user to customize the UI in early-init.el. For easy backwards usage previous version of emacs (25 and 26) I include.

(when (version< emacs-version "27")
  (ignore-errors
    (tool-bar-mode -1)
    (scroll-bar-mode -1)
    (menu-bar-mode -1)))

fullscreen

By default start emacs as fullscreen.

(add-to-list 'default-frame-alist '(fullscreen . maximized))

hooks

switching buffers

switch buffer hook

(defvar void:after-switch-buffer-hook nil
  "A list of hooks run after changing the current buffer.")

inhibit switch buffer hook

(defvar void:inhibit-switch-buffer-hooks nil
  "When non-nil, switch buffer hooks are inhibited.")

switching

(defadvice! void:run-switch-buffer-hooks-a (orig-fn buffer-or-name &rest args)
  "Run `void:after-switch-buffer-hook'."
  :around (switch-to-buffer display-buffer)
  (let ((gc-cons-threshold most-positive-fixnum))
    (if (or void:inhibit-switch-buffer-hooks
            (eq (current-buffer) (get-buffer buffer-or-name))
            (and (eq orig-fn #'switch-to-buffer) (car args)))
        (apply orig-fn buffer-or-name args)
      (let ((void:inhibit-switch-buffer-hooks t))
        (when-let (buffer (apply orig-fn buffer-or-name args))
          (with-current-buffer (if (windowp buffer)
                                   (window-buffer buffer)
                                 buffer)
            (run-hooks 'void:after-switch-buffer-hook))
          buffer)))))

next previous

(defadvice! void:run-prev-or-next-buffer-hooks-a (orig-fn &rest args)
  :around (switch-to-next-buffer switch-to-previous-buffer)
  (let ((gc-cons-threshold most-positive-fixnum))
    (if void:inhibit-switch-buffer-hooks
        (apply orig-fn args)
      (let ((void:inhibit-switch-buffer-hooks t))
        (when-let (buffer (apply orig-fn args))
          (with-current-buffer buffer
            (run-hooks 'void:after-switch-buffer-hook)))))))

font

determine which font to use

I want Void to be flexible when choosing a font. I create a list of my preferred fonts in void:backup-fonts. They are in order of most preferred to least preferred. To compute the value of void:font, Void checks each of these fonts in turn for the first available font. If none is availabe it just uses the system font.

This process is time consuming (at least relative to the total emacs startup time). But it benefits from byte-compilation.

(defvar void:backup-fonts
  '("Inconsolata-18" "Fira Code-18" "DejaVu Sans Mono-18"))

(defvar void:font "Courier 10 Pitch-18"
  "Default font for Void Emacs.
The font for Void is the first font in `void:backup-fonts' that's found in the
computer. If no font in `void:backup-fonts' is found then it uses the default
system font.")

specify `void:font` as default

The default-frame-alist is an alist of the default values for creating a frame. So here I’m making the default font for all Emacs frames void:font.

(add-to-list 'default-frame-alist (cons 'font void:font))

catch undefined fonts

(defadvice! void:frame-notice-user-settings-a (orig-fn &rest args)
  "Try `void:font' followed each of `void:backup-fonts' until success.
If none of the fonts work, just use the default system font."
  :around frame-notice-user-settings
  (condition-case nil
      (progn (apply orig-fn args)
             (void:log "Font is: %s" (face-attribute 'default :font)))
    (error
     (if void:backup-fonts
         (progn
           ;; (push (cons err nil) void:init-errors)
           (void:log "Setting %s failed. Trying %s..." void:font (car void:backup-fonts))
           (setq void:font (pop void:backup-fonts))
           (add-to-list 'default-frame-alist (cons 'font void:font))
           ;; I want to call the function with advice in it.
           (apply #'frame-notice-user-settings args))
       (setq void:font (face-attribute 'default :font))
       (void:log "None of the backup-fonts worked, defaulting to: %s"
                 void:font)
       (add-to-list 'default-frame-alist (cons 'font void:font))
       (apply #'frame-notice-user-settings args)))))

size

Face attribute height is a magnitude of 10 greater than what we typically use as font sizes (eg. font-size 14 corresponds to a face-height of 140). I want to make sure I don’t input 14 thinking about font size (it’s happened before and it’s a huge pain resetting the font-size when the font is super small). Therefore, I check the code.

(defun void/set-font-size ()
  "Set the font size interactively."
  (interactive)
  (let* ((old-font-size (face-attribute 'default :height))
         (prompt "The font size is %d. What do you want to change it to? ")
         (font-size (string-to-number (read-string (format prompt old-font-size))))
         (digits (+ 1 (floor (log font-size 10)))))

    ;; Make the font-size be 3 digits (Do what I mean not what I say).
    (when (< digits 3)
      (setq font-size (* font-size (expt 10 (- 3 digits)))))
    (when (> digits 3)
      (setq font-size (/ font-size (expt 10 (- digits 3)))))

    ;; If font size is still doesn't make sense, ask me to make sure it's what I want.
    (if (or (< font-size 280)
            (y-or-n-p
             (format "You're choosing a pretty large font size: %d. Is this what you intended?)"
                     font-size)))
        (progn
          (set-face-attribute 'default nil :height font-size)
          (message "Your Font Size was %s. Font size is now: %s"
                   old-font-size
                   font-size))
      (message "Font Size has been cancelled."))))

theme

theme to load

(defvar void:theme 'one-light
  "The theme to load on startup.
The value of this variable is updated to the current theme whenever `load-theme'
is called.")

(setq custom-safe-themes t)

initialize at startup

(defhook! void:init-theme-h ()
  "Set the theme and load the font, in that order."
  :hook window-setup-hook
  (when (and void:theme (not (memq void:theme custom-enabled-themes)))
    (condition-case nil
        (load-theme void:theme t)
      (error (void:log "Could not load %s" void:theme)))))

loading theme

Sometimes there are things that need tidying up after loading a theme. For example, if I’m using evil I need to update the cursor color.

(defvar void:after-load-theme-hook nil
  "Hook run after the theme is loaded with `load-theme'.")

(defadvice! void:run-after-load-theme-hook-a (theme &rest _)
  "Set up `void:load-theme-hook' to run after `load-theme' is called."
  :after load-theme
  (setq void:theme theme)
  (run-hooks 'void:after-load-theme-hook))

disable old themes first

Sometimes we end up with remants of the faces of old themes when we load a new one. For this reason, I make sure to disable any enabled themes before applying a new theme.

(defadvice! void:disable-old-themes-first-a (orig-fn &rest args)
  "Disable old themes before loading new ones."
  :around load-theme
  (mapc #'disable-theme custom-enabled-themes)
  (apply orig-fn args))

Window Management

Window management is one of the most important things to get right if you’re going to be efficient in emacs (that is unless you’re using primarily frames instead of windows).

ace-window

ace-window uses avy to navigate windows in cases when there are many. There is an alternative package for this, switch-window. The advantage of switch-window is that the characters used for switching to a window are really easy to see, but you can’t see the buffer contents. That’s a no-go for me I need to see them.

(use-package! ace-window
  :commands ace-window ace-swap-window
  :bind ([remap other-window] . ace-window)
  :setq
  (aw-keys . '(?a ?s ?d ?f ?g ?h ?j ?k ?l))
  (aw-background . t))

eyebrowse

eyebrowse is for managing workspaces. A workspace in Emacs a specific window setup. It’s for when you are doing some task let’s say researching some eyebrowse code and then you want to take a break and do something else but you don’t want to close all the nice windows you have up (and have to set them up again later). You can create a new workspace with eyebrowse-create-window-config and switch to it with eyebrowse-next-window-config. You can always go back to your previous workspace now with eyebrowse-prev-window-config or eyebrowse-switch-to-window-config.

(use-package! eyebrowse
  :commands eyebrowse-create-window-config
  :setq (eyebrowse-wrap-around . t))

window divider

Emacs can add border to windows using a mode called window-divider-mode. Often in emacs you have multiple windows displaying different buffers on the screen. By default the border between these windows is very thin, so it can be hard to distinguish windows sometimes. The point of adding borders to windows is to distinguish them easily from one another.

window dividers

Window dividers are useful in general so I don’t get confused about when one window ends and another begins (see window-divider-mode). When using exwm it makes emacs feel like a window manager with gaps.

(use-feature! frame
  :hook (window-setup-hook . window-divider-mode)
  :custom
  (window-divider-default-places       . t)
  (window-divider-default-bottom-width . 10)
  (window-divider-default-right-width  . 10)
  :config
  (set-face-foreground 'window-divider "black")
  (blink-cursor-mode -1))

update on theme change

(defhook! frame:update-window-divider-hook ()
  "Ensure window divider persists after theme change."
  :hook void:after-load-theme-hook
  (unless (bound-and-true-p window-divider-mode)
    (window-divider-mode 1)))

adjust window divider gap size

increase gap size

Somtimes I might want to adjust this.

(defun frame:adjust-window-divider-size (amount)
  "Adjust the gap size of window-divider by AMOUNT."
  (general-setq window-divider-default-bottom-width
                (+ amount window-divider-default-bottom-width))
  (general-setq window-divider-default-right-width
                (+ amount window-divider-default-right-width)))

increase

(defun frame/increment-window-divider-size ()
  "Increase window divider size."
  (interactive)
  (frame:adjust-window-divider-size 1))

decrease

(defun frame/decrement-window-divider-size ()
  "Decrease window divider size."
  (interactive)
  (frame:adjust-window-divider-size -1))

transpose-frame

https://www.emacswiki.org/emacs/TransposeFrame

(use-package! transpose-frame
  :commands (transpose-frame
             flip-frame
             flop-frame
             rotate-frame
             rotate-frame-clockwise))

exwm

EXWM (Emacs X-Window Manager) is a full-featured window manager in Emacs. There are benefits and drawbacks to making emacs your window manager. One benefit is that you get a super consistent window management experience. If you use a typical window manager, you have to.

exwm

In fact, EXWM does not need to be loaded on startup. It is only needed when you actually want to open another application such as a separate Emacs instance or the web browser. This is great because EXWM actually does consume significant startup time. Instead of loading EXWM immediately, I add advises to the functions which open external linux applications.

(use-package! exwm
  :hook (exwm-mode-hook . hide-mode-line-mode)
  :before-call (void/open-qutebrowser counsel-linux-app void/open-emacs-instance)
  :setq (exwm-replace . nil)
  :defer-config
  (exwm-init)
  ;; Enable the clipboard.
  (require 'exwm-systemtray)
  (exwm-systemtray-enable))

(defhook! exwm:setup-hide-mode-line-h ()
  :hook exwm-mode-hook
  (add-hook 'exwm-floating-setup-hook #'exwm-layout-hide-mode-line)
  (add-hook 'exwm-floating-exit-hook #'exwm-layout-show-mode-line))

appropriate name for exwm buffers

(defhook! exwm:rename-buffer-to-title-h ()
  "Rename buffer to title."
  :hook exwm-update-title-hook
  (exwm-workspace-rename-buffer exwm-title))

to start in char mode

EXWM has two modes, line-mode and char-mode. It’s best for Emacs and Next to start with char-mode because they both have keys that are important for their use (like M-x) which conflict with Emacs (the instance that’s managing the windows).

list of applications

(defvar exwm:char-mode-apps (list "emacs" "next" "nyxt")
  "List of applications to exwm should start in char-mode.")

to start in char mode

(defhook! exwm:start-in-char-mode-h ()
  "Start a program in char-mode if it's in `exwm:char-mode-apps'."
  :hook exwm-manage-finish-hook
  (when (--any-p (string-prefix-p it exwm-instance-name) exwm:char-mode-apps)
    (exwm-input-release-keyboard (exwm--buffer->id (window-buffer)))))

keybindings

(after! exwm
  (funcall (get 'exwm-input-global-keys 'custom-set)
           'exwm-input-global-keys
           `((,(kbd "s-R") . exwm-reset)
             (,(kbd "s-x") . exwm-input-toggle-keyboard)
             (,(kbd "s-h") . windmove-left)
             (,(kbd "s-j") . windmove-down)
             (,(kbd "s-k") . windmove-up)
             (,(kbd "s-l") . windmove-right)
             (,(kbd "s-t") . transpose-frame)
             (,(kbd "s-D") . kill-this-buffer)
             (,(kbd "s-b") . switch-to-buffer)
             (,(kbd "s-f") . find-file)
             (,(kbd "s-O") . exwm-layout-toggle-fullscreen)
             (,(kbd "s-p") . previous-buffer)
             (,(kbd "s-n") . next-buffer)
             (,(kbd "s-q") . void/open-qutebrowser)
             (,(kbd "s-e") . void/open-emacs-instance))))

(general-def
  "s-R" #'exwm-reset
  "s-x" #'exwm-input-toggle-keyboard
  "s-h" #'windmove-left
  "s-j" #'windmove-down
  "s-k" #'windmove-up
  "s-l" #'windmove-right
  "s-t" #'transpose-frame
  "s-D" #'kill-this-buffer
  "s-b" #'switch-to-buffer
  "s-f" #'find-file
  "s-O" #'exwm-layout-toggle-fullscreen
  "s-p" #'previous-buffer
  "s-n" #'next-buffer
  "s-q" #'void/open-qutebrowser
  "s-e" #'void/open-emacs-instance)

exwm-edit

The dream is to do all text editing in Emacs. This package is a big step towards achieving that dream. exwm-edit allows the user to edit text fields in external packages with an emacs buffer. It acts a lot like org-edit-src-code: it copies any text in the text field to a buffer, you edit the buffer, then press a binding to insert the buffer text into the text field. It goes without saying that when the text is in an emacs buffer, you can use the full-force of Emacs’s text editing capabilities on it.

(use-package! exwm-edit :after exwm)

exwm firefox

(use-package! exwm-firefox-evil
  :disabled t
  :after exwm
  :hook (exwm-manage-finish-hook . exwm-firefox-evil-activate-if-firefox)
  :config
  (dolist (k `(escape))
    (cl-pushnew k exwm-input-prefix-keys)))

buffer expose

(use-package! buffer-expose
  :commands (buffer-expose
             buffer-expose-no-stars
             buffer-expose-major-mode
             buffer-expose-dired-buffers
             buffer-expose-stars
             buffer-expose-current-mode)
  :setq
  (buffer-expose-show-current-buffer . t)
  (buffer-expose-rescale-factor      . 0.5)
  (buffer-expose-highlight-selected  . nil)
  (buffer-expose-max-num-windows     . 8)
  (buffer-expose-auto-init-aw        . t)
  (buffer-expose-hide-modelines      . nil)
  (buffer-expose-key-hint            . "")
  :bind
  (:buffer-expose-grid-map
   ("l" . buffer-expose-next-window)
   ("h" . buffer-expose-prev-window)
   ("L" . buffer-expose-next-page)
   ("H" . buffer-expose-prev-page)
   ("j" . buffer-expose-down-window)
   ("k" . buffer-expose-up-window)))

Completion

Completion has certainly become an integral part of any efficient workflow. One commonality among things like searching emails, code-completing a word, surfing the web is that in one way or another all of these things involve the suggestion of likely candidates from a population that is too time consuming to look through on our own. It’s not much different in Emacs. We’re constantly sifting though files, buffers, commands, words–all to try to get through to the subset of things that we actually want at this moment.

snippets

defsnippet

I find it painful to write and edit long one-liner snippets with lots of inner elisp code. Additionally, I dislike having many different files for snippets. To me it’s a potential source of errors and it makes it so I have to go looking for a snippet whenever I want to edit it.

These grievances have inspired me to write an API for writing snippet templates in a declarative syntax as opposed to via a snippet file.

defsnippet

This is the user-facing function to define yasnippets.

(defun defsnippet:new-snippet (&rest plist)
  "Define a snippet."
  (-let (((&plist :name :mode :body :placeholders) plist)
         (keys '(:key :name :contributor :group :expand-env :binding :type :uuid)))
    (cl-assert (-none-p #'null (list name mode body)))

    (alet (append
           (list "# -*- mode: snippet -*-\n")
           (->> keys
                (--filter (plist-get plist it))
                (--map (format "# %s: %s\n" (void:keyword-name it) (plist-get plist it))))
           (list "# --\n")
           (list (defsnippet:compute-body body placeholders)))
      (with-temp-buffer
        (insert (string-join it "\n"))
        (yas-load-snippet-buffer mode)))))

compute body

(defun defsnippet:compute-body (body placeholders)
  "Return the result of PLACEHOLDERS applied to BODY."
  (alet (-map (-lambda ((number name form))
                (if (eq '_  name)
                    (format "${%d:$$%S}" number form)
                  (format "${%d:%s$%S}" number name form)))
              placeholders)
    (apply #'format body it)))

list symbols

(defun defsnippet:list-symbols (&optional pred)
  "List interned symbols."
  (setq pred (or pred #'identity))
  (let (acc)
    (mapatoms (lambda (it)
                (when (and (symbolp it)
                           (not (eq 'nil it))
                           (funcall pred it))
                  (push it acc))))
    (nreverse acc)))

defsnippet!

This macro helps me define snippets declaratively without worrying about whether yasnippet is loaded or not.

(defmacro defsnippet! (snippet &rest properties)
  "Syntactic sugar for defining a snippet on time."
  (declare (indent defun))
  `(after! yasnippet
     (defsnippet:new-snippet
       :name ,(void:to-string snippet)
       ,@properties)))

snippets

It’s really nice being able to re-evaluate a snippet with an elisp form as opposed to going to the snippet buffer, editing it and reloading it.

org links

helpfn

For extremely good documentation.

(defsnippet! help-function
  :key "hfn"
  :mode 'org-mode
  :body "[[helpfn:%s][$1]%s"
  :placeholders '((1 function (yas-auto-next (yas-choose-value (defsnippet:list-symbols))))
                  (0 _ (insert "]"))))

helpvar

(defsnippet! help-variable
  :mode 'org-mode
  :key "hvar"
  :body "[[helpvar:$1][%s]%s"
  :placeholders '((1 variable (->> (defsnippet:list-symbols #'helpful--variable-p)
                               (yas-choose-value)
                               (yas-auto-next)))
                  (0 _ (insert "]"))))

id

(defsnippet! org-id
  :mode 'org-mode
  :key "oid"
  :body "[[id:%s][#%s]$0"
  :placeholders '((1 _ (->> (hash-table-keys org-id-locations)
                        (yas-choose-value)
                        (yas-auto-next)))
                  (2 _ (substring (yas-field-value 1) 0 5))
                  (0 _ (insert "]"))))

elisp

defun

(defsnippet! defun
  :mode 'emacs-lisp-mode
  :key "dfn"
  :body "(defun %s (%s)\n  \"%s\"\n  %s)"
  :placeholders '((1 name)
                  (2 args)
                  (3 docstring (thread-first (rx-to-string `(or ,@(s-split "\s" (yas-field-value 2) t)))
                                (replace-regexp-in-string #'upcase yas-text)
                                (ignore-errors)))
                  (4 body)))

yasnippet

yasnippet is a template completion package. You can define templates which can be inserted and interactively completed.

(use-package! yasnippet
  :hook (prog-mode-hook . yas-minor-mode-on)
  :setq
  (yas-snippet-dirs . (list (concat VOID:DATA-DIR "snippets/")))
  (yas-verbosity . (if void:debug-p 3 0))
  (yas-indent-line . 'auto)
  (yas-prompt-functions . '(yas-completing-prompt yas-ido-prompt))
  (yas-use-menu . nil)
  (yas-triggers-in-field . t)
  :defer-config
  (--each yas-snippet-dirs (mkdir it t))
  (delq #'yas-dropdown-prompt yas-prompt-functions)
  (after! smartparens
    ;; tell smartparens overlays not to interfere with yasnippet keybinds
    (advice-add #'yas-expand :before #'sp-remove-active-pair-overlay)))

snippet collection

yasnippet-snippets is a collection of snippets.

(use-package! yasnippet-snippets
  :after yasnippet
  :init
  (awhen (-first (-partial #'s-contains-p "yasnippet-snippets") load-path)
    (push it yas-snippet-dirs)))

selectrum

Selectrum is an investement. It doesn’t have the support that completing frameworks like ivy and helm has. However, it is coded more sanely and it is more predictable. Additionally, it is minimal and lightweight meaning that you won’t have to worry about snappiness and performance.

selectrum

(use-package! selectrum
  :hook emacs-startup-hook
  :setq
  (selectrum-fix-minibuffer-height . t)
  (selectrum-should-sort-p . t)
  (selectrum-count-style . nil)
  (selectrum-num-candidates-displayed . 15))

(general-def '(insert emacs) selectrum-minibuffer-map
  "TAB" #'selectrum-next-candidate
  "C-k" #'selectrum-previous-candidate
  "C-j" #'selectrum-next-candidate
  "C-l" #'selectrum/mark-candidate
  [backtab] #'selectrum-previous-candidate)

selectrum prescient

This package manages remembering recently selected candidates.

(use-package! prescient
  :hook (selectrum-mode-hook . prescient-persist-mode)
  :setq
  (prescient-save-file . (concat VOID:DATA-DIR "prescient-save-file")))

(use-package! selectrum-prescient
  :hook selectrum-mode-hook
  :setq
  (selectrum-preprocess-candidates-function . #'selectrum-prescient--preprocess))

orderless

This package provides an “orderless” completion style.

(use-package! orderless
  :init
  (defadvice! orderless:inhibit-filtering-and-highlighting (orig-fn &rest args)
    "Don't let `selectrum-prescient' filter or highlight.
Orderless will do this."
    :around selectrum-prescient-mode
    (let ((selectrum-refine-candidates-function selectrum-refine-candidates-function)
          (selectrum-highlight-candidates-function selectrum-highlight-candidates-function))
      (apply orig-fn args)))
  :setq
  (selectrum-refine-candidates-function . #'orderless-filter)
  (selectrum-highlight-candidates-function . #'orderless-highlight-matches))

utilities

Many of these utilities come from the selectrum wiki.

select x-font function for ivy and selectrum

This version lets you choose different variants.

(defun void/set-font ()
  "Select xfont."
  (interactive)
  (set-frame-font (completing-read "Choose font: " (x-list-fonts "*"))))

swiper

(defvar selectrum:swiper-history nil "Submission history for `selectrum-swiper'.")

(defun selectrum/swiper ()
  "Search for a matching line and jump to the beginning of its text.  Obeys narrowing."
  (interactive)
  (let* ((selectrum-should-sort-p nil)
         (gc-cons-threshold VOID:GC-CONS-THRESHOLD-MAX)
         (minimum-line-number (line-number-at-pos (point-min) t))
         (current-line-number (line-number-at-pos (point) t))
         (line-choices (->> (split-string (buffer-string) "\n")
                            (--map-indexed (unless (string-empty-p it)
                                             (format "L%d: %s" (+ it-index minimum-line-number) it)))
                            (-non-nil)))
         (chosen-line (completing-read "Jump to matching line: " line-choices
                                       nil t nil 'selectrum:swiper-history))
         (chosen-line-num (--> chosen-line
                               (s-match (rx "L" (group (+ digit)) ":") it)
                               (elt it 1)
                               (string-to-number it))))
    (push-mark (point) t)
    (forward-line (- chosen-line-num current-line-number))
    (beginning-of-line-text 1)))

switch to buffer and recentf

(defun selectrum/switch-buffer ()
  (interactive)
  (require 'f)
  (let* ((selectrum-should-sort-p nil)
         (other-buffers (->> (buffer-list)
                             (-remove-item (current-buffer))
                             (-map #'buffer-name)
                             (--remove (s-prefix-p " " it))))
         (buffer-file-paths (->> other-buffers
                                 (--map (buffer-file-name (get-buffer it)))
                                 (-non-nil)))
         (recentf-paths (--remove (-any-p (-partial #'string= (f-full it))
                                          buffer-file-paths)
                                  recentf-list)))
    (alet (completing-read "Select buffer: " (append other-buffers recentf-paths))
      (funcall (if (-contains-p recentf-list it)
                   #'find-file
                 #'switch-to-buffer)
               it))))

(general-def [remap switch-to-buffer] #'selectrum/switch-buffer)

mark candidate for completing-read-mutiple

This saves us some time over tab completing and then adding the separator ourselves.

(defun selectrum/mark-candidate ()
  "Mark candidate for completing-read-multiple."
  (interactive)
  (selectrum-insert-current-candidate)
  (insert crm-default-separator))

open app

(defun selectrum/open-app ()
  "Open an application I have installed."
  (interactive)
  (alet (completing-read-multiple "Open app: " ())
    (start-process)))

org

outline headlines

(defun selectrum/org-outline-headings ()
  "Jump to an org heading using selectrum."
  (interactive)
  (let ((selectrum-should-sort-p nil)
        (org-outline-path-complete-in-steps)
        (org-goto-interface 'outline-path-completion))
    (org-goto)))

org select tags

(defun selectrum/org-select-tags ()
  "Select tags to add to headline."
  (interactive)
  (let* ((current (org-get-tags (point)))
         (selected (completing-read-multiple "Select org tag(s): " (org-get-buffer-tags))))
    (alet (-uniq (append (-difference current selected)
                         (-difference selected current)))
      (org-set-tags it))))

(general-def [remap org-set-tags-command] #'selectrum/org-select-tags)

select capture templates

This is based on [[][counsel-org-capture]].

(defun selectrum/select-capture-template ()
  "Select capture template."
  (interactive)
  (let (prefixes)
    (alet (mapcan (lambda (x)
                    (let ((x-keys (car x)))
                      ;; Remove prefixed keys until we get one that matches the current item.
                      (while (and prefixes
                                  (let ((p1-keys (caar prefixes)))
                                    (or
                                     (<= (length x-keys) (length p1-keys))
                                     (not (string-prefix-p p1-keys x-keys)))))
                        (pop prefixes))
                      (if (> (length x) 2)
                          (let ((desc (mapconcat #'cadr (reverse (cons x prefixes)) " | ")))
                            (list (format "%-5s %s" x-keys desc)))
                        (push x prefixes)
                        nil)))
                  (-> org-capture-templates
                      (org-capture-upgrade-templates)
                      (org-contextualize-keys org-capture-templates-contexts)))
      (funcall #'org-capture nil (car (split-string (completing-read "Capture template: " it nil t)))) )))

(general-def org-mode-map [remap org-capture] #'selectrum/select-capture-template)

embark

Embark allows for using actions on candidates.

(use-package! embark
  :ensure (:host github :repo "oantolin/embark"))

(general-def '(insert emacs) selectrum-minibuffer-map "C-a" #'embark-act)

(defun refresh-selectrum ()
  (setq selectrum--previous-input-string nil))

(add-hook 'embark-pre-action-hook #'refresh-selectrum)

(setq embark-action-indicator
      (defun embark-which-key-setup ()
        (let ((help-char nil)
              (which-key-show-transient-maps t)
              (which-key-replacement-alist
               (cons '(("^[0-9-]\\|kp-[0-9]\\|kp-subtract\\|C-u$" . nil) . ignore)
                     which-key-replacement-alist)))
          (setq-local which-key-show-prefix nil)
          (setq-local which-key-persistent-popup t)
          (which-key--update)))
      embark-become-indicator embark-action-indicator)

(add-hook 'embark-pre-action-hook
          (defun embark-which-key-tear-down ()
            (kill-local-variable 'which-key-persistent-popup)
            (kill-local-variable 'which-key-show-prefix)
            (unless which-key-persistent-popup
              (which-key--hide-popup-ignore-command))))

company

company

company offers code completion.

(use-package! company
  :hook prog-mode-hook
  :bind (:company-active-map
         ([tab] . company-select-next)
         ([backtab] . company-select-previous)
         ("C-k"     . company-select-previous)
         ("C-j"     . company-select-next))
  :setq
  (company-frontends . '(company-pseudo-tooltip-frontend))
  (company-tooltip-align-annotations . t)
  (company-show-numbers . t)
  (company-dabbrev-downcase . nil)
  (company-idle-delay . 0.15)
  (company-tooltip-limit . 14)
  (company-minimum-prefix-length . 1)
  (company-minimum-prefix-length . 1)
  (company-require-match . 'never))

backends

company-backends is what you have to keep in mind when you’re using company. According to its documentation, company-backends contain individual backends or groups of backends. This is important so it’s worth quoting here:

backends-alist

(defvar company:backend-alist
  '((text-mode :derived (company-dabbrev company-yasnippet company-ispell))
    (prog-mode :derived ((:separate company-capf company-yasnippet)))
    (conf-mode :derived (company-capf company-dabbrev-code company-yasnippet))
    (org-mode  :only (company-yasnippet)))
  "An alist matching modes to company backends.")

initialize a backend

(defhook! company:init-backends-h ()
  "Set `company-backends' for the current buffer."
  :hook company-mode-hook
  (require 'company)
  (unless (eq major-mode 'fundamental-mode)
    (set (make-local-variable 'company-backends) (company--backends+)))
  (add-hook 'after-change-major-mode-hook #'company:init-backends-h nil 'local))

get backends

(defun company--backends+ ()
  "Compute company backends."
  (or
   (-when-let (((mode type backends) (assoc major-mode company:backend-alist)))
     (when (eq type :only) backends))
   (-mapcat (-lambda ((mode type backends))
              (when (or (and (eq type :derived) (derived-mode-p mode))
                        (and (eq type :exact)
                             (or (eq major-mode mode)
                                 (and (boundp mode) (symbol-value mode)))))
                backends))
            company:backend-alist)))

local hook

(after! company
  (put 'company:init-backends-h 'permanent-local-hook t))

close company on escape

(defhook! company:close-tooltip-h ()
  "Close company tooltip."
  :hook void:escape-hook
  (when (and (boundp 'company-mode)
             (eq company-mode t))
    (company-abort)
    t))

company prescient

company-prescient is the same as prescient but for company instead of ivy.

(use-package! company-prescient :hook company-mode-hook)

Email

In today’s world communication is largely done via emails. Whether at work or at school it’s common to receive emails every day. In fact, you hear of people that have 20,000+ emails in a particular account. Unsurprisingly, when we’re getting so many emails, it’s easy to become overwhelmed. Fortunately, there are numerous ways to read and send emails in Emacs.

sendmail

(use-feature! sendmail
  :setq
  (send-mail-function . #'sendmail-send-it)
  (sendmail-program . (executable-find "msmtp"))
  (mail-specify-envelope-from . t))

smtpmail

(use-feature! smtpmail
  :disabled t
  :setq
  (smtp-default-mail-server . "mail.example.com")
  (smtp-smtp-server . "mail.example.com")
  (smtpmail-smtp-service . 587)
  (smtpmail-debug-info . t))

message

(use-feature! message
  :setq
  (message-signature . user-full-name)
  (message-sendmail-envelope-from . 'header)
  (message-send-mail-function . #'sendmail-send-it)
  (message-kill-buffer-on-exit . t))

mu4e

The most popular emacs mail client is mu4e. And, there is good reason why. mu4e has many juicy features. Overall, mu4e is definitely a great mail client. However, it’s not all roses and rainbows; it does have a few annoying quicks. One is that unlike virtually all other emacs packages it does not come decoupled from mu. Another is that it is hard to set up multiple accounts properly despite it’s explicit support for multiple accounts. mu4e comes bundled with mu. A significant advantage of using it is it’s the most popular option and, therefore, has the most support (in the form of setup blogs and packages).

mu4e

(use-package! mu4e
  :ensure nil
  :load-path "/usr/share/emacs/site-lisp/mu4e/"
  :commands mu4e
  :setq
  (mu4e-completing-read-function . #'completing-read)
  (mu4e-view-show-addresses . t)
  (mu4e-view-show-images . t)
  (mu4e-view-image-max-width . 800)
  (mu4e-compose-signature-auto-include . t)
  (mu4e-compose-format-flowed . t)
  (mu4e-get-mail-command . "mbsync -a")
  (mu4e-index-cleanup . t)
  (mu4e-index-lazy-check . nil)
  (mu4e-update-interval . 180)
  (mu4e-headers-auto-update . t)
  (mu4e-context-policy . 'pick-first)
  (mu4e-compose-context-policy . 'ask-if-none)
  (mu4e-confirm-quit . nil)
  (mu4e-header-fields . '((:human-date . 12)
                          (:flags . 4)
                          (:from . 25)
                          (:subject)))
  (mu4e-html2text-command . (if (executable-find "w3m") "w3m -dump -T text/html" #'mu4e-shr2text)))

setup mu4e

(defun mu4e/init ()
  "Initialize mu4e."
  (interactive)
  (require 'password-store)
  (let ((email-dirs (--map (concat VOID:EMAIL-DIR it) (pass:email-list))))
    (when (or (not (-all-p #'f-exists-p email-dirs))
              (-some-p #'f-empty-p email-dirs))
      (message "creating directories that don't exist.")
      (--each email-dirs (mkdir it t))
      (shell-command (format "mu init -m %s" VOID:EMAIL-DIR))
      (message "Updating mail...")
      (mu4e-update-mail-and-index t))))

mu4e headers

(use-package! mu4e-headers
  :ensure nil
  :after mu4e
  :setq
  (mu4e-use-fancy-chars . t)
  (mu4e-headers-draft-mark     . (cons "D" (all-the-icons-faicon "pencil")))
  (mu4e-headers-flagged-mark   . (cons "F" (all-the-icons-faicon "flag")))
  (mu4e-headers-new-mark       . (cons "N" (all-the-icons-material "fiber_new")))
  (mu4e-headers-passed-mark    . (cons "P" (all-the-icons-faicon "arrow-right")))
  (mu4e-headers-seen-mark      . (cons "S" (all-the-icons-faicon "eye")))
  (mu4e-headers-attach-mark    . (cons "a" (all-the-icons-material "attach_file")))
  (mu4e-headers-replied-mark   . (cons "R" (all-the-icons-faicon "reply")))
  (mu4e-headers-unread-mark    . (cons "u" (all-the-icons-faicon "eye-slash")))
  (mu4e-headers-encrypted-mark . (cons "x" (all-the-icons-octicon "lock")))
  (mu4e-headers-signed-mark    . (cons "s" (all-the-icons-faicon "certificate")))
  (mu4e-headers-trash-mark     . (cons "T" (all-the-icons-faicon "trash"))))

org mu4e

Mu4e’s org integration lets you write emails in org mode and convert it to html before sending–very interesting indeed. I have yet to explore this feature but it is definitely on my list of things to try out.

(use-package! org-mu4e
  :disabled t
  :hook (mu4e-compose-mode-hook . org-mu4e-compose-org-mode)
  :setq
  (org-mu4e-link-query-in-headers-mode . nil)
  (org-mu4e-convert-to-html . t)
  :defer-config
  ;; Only render to html once. If the first send fails for whatever reason,
  ;; org-mu4e would do so each time you try again.
  (defhook! org-mu4e-render-html-only-once-h ()
    :hook message-send-hook
    (setq-local org-mu4e-convert-to-html nil)))

multiple accounts

Mu4e certainly gave me some trouble setting up multiple accounts despite [its attempt] to make this easy. I have one directory ~/.mail where which stores all my mail. The subdirectories of ~/.mail correspond to my individual email accounts. Until I set multiple accounts correctly it keeps prompting me to create folders (such as sent/) in the ~/.mail directory. I think part of the reason I spent so much time setting this up is because.

return the list of emails with credentials

(defun pass:email-list ()
  "Return a list of emails."
  (->> (password-store-list)
       (--map (elt (s-match "email/\\(.*\\)" it) 1))
       (-non-nil)))

return the stuff as a plist

(defun pass:email-account-plist (email)
  "Return a plist of the relevant values of an email."
  (shut-up!
    (->> (cdr (password-store-parse-entry email))
         (mapcar #'car)
         (--mapcat (list (intern it)
                         (password-store-get-field (concat "email/" email) it))))))

mu4e folder name alist

Mu4e keeps prompting you for the sent, trash, and drafts directory if you do not assign the corresponding mu4e variables. The way certain email servers name their directories varies. For example, outlook names its sent directory as Sent Items.

(defun mu4e:guess-folder (base-dir possible-name &rest other-possible-names)
  "Return the first file in BASE-DIR that matches POSSIBLE-NAME or any POSSIBLE-NAMES.
If there is no match, return POSSIBLE-NAME."
  (alet (or (--first (-some-p (-cut s-contains-p <> it t)
                              (cons possible-name other-possible-names))
                     (cddr (directory-files base-dir)))
            possible-name)
    (format "/%s/%s" (f-filename base-dir) it)))

set up contexts for single account

(defun mu4e::account-context (email)
  "Return an mu4e account context for specified EMAIL."
  (let* ((base-dir (concat VOID:EMAIL-DIR email "/"))
         (name (cl-second (s-match ".*@\\([^.]*\\)" email)))
         (account (pass:email-account-plist email))
         (out-host (plist-get 'out-host account))
         (out-port (plist-get 'out-port account)))
    (alet `((mu4e-sent-folder      . ,(mu4e:guess-folder base-dir "sent"))
            (mu4e-drafts-folder    . ,(mu4e:guess-folder base-dir "draft"))
            (mu4e-trash-folder     . ,(mu4e:guess-folder base-dir "trash" "delete" "junk"))
            (user-email-address    . ,email)
            (smtpmail-smtp-server  . ,out-host)
            (smtpmail-smtp-user    . ,base-dir)
            (smtpmail-smtp-service . ,out-port))
      (make-mu4e-context :name name :vars it))))

multiple contexts

(defadvice! mu4e:initialize-all-contexts (&rest _)
  "Initiaize context for each email account."
  :before mu4e
  (require 'password-store)
  (--each (-map #'mu4e::account-context (pass:email-list))
    (cl-pushnew it mu4e-contexts)))

shortcuts

(defun mu4e/view-today-emails ()
  (interactive)
  (mu4e t)
  (mu4e-headers-search "date:today..now"))

(defun mu4e/view-shnu-account ()
  (interactive)
  (mu4e t)
  (mu4e-headers-search "to:luis.henriquez@snhu.edu"))

(defun mu4e/view-luishp-account ()
  (interactive)
  (mu4e t)
  (mu4e-headers-search "to:luis@luishp.xyz"))

(defun mu4e/view-gmail-account ()
  (interactive)
  (mu4e-headers-search "to:luishenriquezperez@gmail.com"))

bindings

(general-def 'normal mu4e-headers-mode-map
  "q" #'kill-buffer-and-window
  "i" #'ignore
  "I" #'ignore
  "D" #'mu4e-headers-mark-for-delete
  "F" #'mu4e-headers-mark-for-flag
  "u" #'mu4e-headers-mark-for-unmark
  "x" #'mu4e-mark-execute-all
  "t" #'mu4e-headers-mark-for-trash
  "c" #'mu4e-compose
  "o" #'org-mu4e-compose-org-mode
  "s" #'mu4e-headers-search
  "r" #'mu4e-compose-reply
  "RET" #'mu4e-headers-view-message)

(general-def 'normal mu4e-view-mode-map
  "q" #'kill-buffer-and-window)

(define-localleader-key! mu4e-compose-mode-map
  "s" (list :def #'message-send-and-exit :which-key "send and exit")
  "d" (list :def #'message-kill-buffer :which-key "kill buffer")
  "S" (list :def #'message-dont-send :which-key "save draft")
  "a" (list #'mail-add-attachment :which-key "attach"))

truncate lines in messages

(defhook! mu4e:wrap-text-in-message ()
  :hook mu4e-view-mode-hook
  (setq-local truncate-lines nil))

notmuch

Notmuch is probably the most elegant email solution of the three. It operates purely on tags. Mu4e uses tags in the background but notmuch goes all out. There’s no concept of folders. A great thing about this is you avoid the headache of Mu4e contexts because there is no such thing as a context to notmuch. notmuch couldn’t care less about how your emails are organized. Also, notmuch is even faster than Mu4e when it comes to indexing email. Though this probably won’t be a significant practical difference unless you have many emails.

bootstrap

(use-package! notmuch
  :commands notmuch
  :setq
  (notmuch-search-oldest-first . nil)
  ;; Don't show notmuch logo.
  (notmuch-show-logo . nil)
  (notmuch-show-mark-read-tags . '("-unread")))

accounts

I want this command to be a replacement to `notmuch’. Calling `notmuch’ displays an (ugly) intro screen. I find that most of the time I just want to see my inbox, no questions asked.

(defun notmuch/display-inbox ()
  "Display the inbox."
  (interactive)
  (notmuch-search "tag:inbox" notmuch-search-oldest-first))

(defun notmuch/luishp-account ()
  (interactive)
  (notmuch-search "to:luis@luishp.xyz" notmuch-search-oldest-first))

(defun notmuch/luishenriquezperez-account ()
  (interactive)
  (notmuch-search "to:luishenriquezperez@gmail.com NOT tag:spam" notmuch-search-oldest-first))

(defun notmuch/snhu-account ()
  (interactive)
  (notmuch-search "to:luis.henriquez@snhu.edu"))

update mail

(defun notmuch/update ()
  (interactive)
  (start-process-shell-command
   "notmuch update" nil
   "mbsync -a && notmuch new")
  ;; (notmuch-tag "tag:new and folder:luishenriquezperez@gmail.com/spam" '("+spam" "-new" "-unread"))
  ;; tag new spam email as spam.
  ;; mark new email as new.
  )

gnus

Perhaps the least popular way of using emails is using gnus. It is actually how [[][John Wiegley]], one of Emacs’s maintainers, has managed his email for over 20 years. Gnus is really a mixed bag. One the one hand, I absolutely love the fact that it’s written in pure elisp (making it extremely customizable) and that it’s built-in to emacs. You can be on a completely different computer and set up have a working client with just Emacs–that’s pretty incredible. On the other hand, the abstraction it is based on is extremely outdated making many of it’s variables and functions more difficult to understand (just by reading their name) than normal; and it’s pretty slow when dealing with many emails (by many I mean 2000 which is not a lot by today’s standard).

bootstrap

(use-feature! gnus
  :commands gnus
  :setq
  (gnus-summary-line-format "%U%R%z %-16,16&user-date; %-30,30f  %B%S\n")
  (gnus-select-method . '(nnnil))
  (gnus-agent . t)
  (gnus-agent-article-alist-save-format . 1)
  (gnus-agent-cache . t)
  (gnus-agent-confirmation-function . 'y-or-n-p)
  (gnus-agent-consider-all-articles .  nil)
  (gnus-agent-directory . "~/News/agent/")
  (gnus-agent-enable-expiration . 'ENABLE)
  (gnus-agent-expire-all . nil)
  (gnus-agent-expire-days . 30)
  (gnus-agent-mark-unread-after-downloaded . t)
  (gnus-agent-queue-mail . t)
  (gnus-agent-synchronize-flags . nil))

gnus start

(use-feature! gnus-start
  :after gnus
  :setq
  (gnus-use-dribble-file . nil)
  (gnus-always-read-dribble-file . nil))

gnus sum

(use-package! gnus-sum
  :setq
  (gnus-user-date-format-alist . '(((gnus-seconds-today) . "Today at %R")
                                   ((+ 86400 (gnus-seconds-today)) . "Yest. at %R")
                                   (t . "%m-%d %R")))
  (gnus-sum-thread-tree-false-root . "")
  (gnus-sum-thread-tree-indent . " ")
  (gnus-sum-thread-tree-leaf-with-other . "├─➤ ")
  (gnus-sum-thread-tree-root . "")
  (gnus-sum-thread-tree-single-leaf . "└─➤ ")
  (gnus-sum-thread-tree-vertical . "│"))

accounts

luis

(ignore!
 (append! gnus-secondary-select-methods
   '(nnimap "luis"
     (nnimap-address "mail.luishp.xyz")
     (nnimap-stream ssl)
     (nnimap-authenticator 'login)
     (nnimap-log-command "pass"))))

(append! gnus-secondary-select-methods
  '(nnmaildir "luis"
    (directory "~/.mail/luis@luishp.xyz")))

snhu

(ignore!
 (append! gnus-secondary-select-methods
   '(nnimap "school"
     (nnimap-address "outlook.office365.com")
     (nnimap-stream ssl)
     (nnimap-log-command "pass"))))

(append! gnus-secondary-select-methods
  '((nnmaildir "snhu"
     (directory "~/.mail/luis.henriquez@snhu.edu/"))))

gmail

(append! gnus-secondary-select-methods
  '(nnimap "gmail"
    (nnimap-address "imap.gmail.com")
    (nnimap-stream ssl)
    (nnimap-log-command "pass")))

gnus group

(use-feature! gnus-group
  :setq
  (gnus-group-line-format . "%M\ %S\ %p\ %P\ %5y:%B%(%g%)\n"))

gnus art

(use-package! gnus-art
  :after gnus
  :setq
  (gnus-article-browse-delete-temp . 'ask)
  (gnus-article-over-scroll . nil)
  (gnus-article-show-cursor . t)
  (gnus-article-sort-functions
   '(gnus-article-sort-by-most-recent-number
     gnus-article-sort-by-most-recent-date))
  (gnus-article-truncate-lines . nil)
  ;; (gnus-html-frame-width 80)
  ;; (gnus-html-image-automatic-caching t)
  (gnus-inhibit-images . t)
  (gnus-max-image-proportion . 0.3)
  (gnus-treat-display-smileys . nil)
  ;; (gnus-article-mode-line-format "%G %S %m")
  (gnus-visible-headers
   '("^From:" "^To:" "^Cc:" "^Newsgroups:" "^Subject:" "^Date:"
     "Followup-To:" "Reply-To:" "^Organization:" "^X-Newsreader:"
     "^X-Mailer:"))
  (gnus-sorted-header-list . gnus-visible-headers))

Web Browsing

In current times we are fortunate enough to have a wealth of information available to us only a web search away.

w3m

w3m is a text-based web browser. There are many other text-based browsers out there, but w3m has the benefit of having comprehensive emacs interface. Why use this when you can use the GUI browser? Well, using the Emacs interface I can view an Emacs webpage as plain text, which means I can perform searches on it with [[][swiper]], or any other Emacs operation on it. Another advantage is that because the w3m interface’s backend is a terminal application, it will (I’m guessing; no benchmarks made) typically be faster than browsers at rendering plain text webpages. Of course, the main limitation is that w3m will typically only display text based web pages well–not ones with lots of interactive javascript code.

w3m

(use-package! w3m
  :commands w3m
  :setq (w3m-search-default-engine . "google"))

traversing

(general-def 'normal w3m-mode-map
  "o" #'w3m-search
  "O" #'w3m-search-new-session
  ;; Jump to a link with avy in the current session.
  "f" #'ace-link-w3m
  "F" #'ace-link-open-new-session
  ;; Delete the current emacs-w3m buffer and switch to the previous one.
  "D" #'w3m-delete-buffer
  ;; Move through tabs.
  "J" #'w3m-tab-move-right
  "K" #'w3m-tab-move-left
  ;; Move back COUNT pages in the history.
  "H" #'w3m-view-previous-page
  ;; Move forward COUNT pages in history.
  "L" #'w3m-view-next-page)

browse-url

Emacs’s go-to function for browsing the web is stored in the variable browse-url-browser-function.

(setq browse-url-browser-function #'browse-url-firefox)

(defun browse-url-firefox (url &optional _new-window)
  "Ask the Qutebrowser WWW browser to load URL.
Default to the URL around or before point.  The strings in
variable `browse-url-qutebrowser-arguments' are also passed to
Qutebrowser.
The optional argument NEW-WINDOW is not used."
  (interactive (browse-url-interactive-arg "URL: "))
  (setq url (browse-url-encode-url url))
  (let* ((process-environment (browse-url-process-environment)))
    (apply 'start-process
           (concat "firefox " url) nil
           (executable-find "qutebrowser")
           (append nil (list url)))))

xwebkit

going to url

(use-package! xwwp-follow-link
  :straight (:host github :repo "canatella/xwwp")
  :bind (:xwidget-webkit-mode-map
         ("v" . #'xwwp-follow-link))
  :setq (xwwp-follow-link-completion-system . 'ivy))

Multimedia

I’m using “multimedia” here as an umbrella term for non-text sources of information such as music, videos, images, and gifs.

youtube

Youtube contains a huge library of videos.

ytdl

ytdl is an emacs interface to youtube-dl.

(use-package! ytdl
  :setq
  (ytdl-downloads-folder . VOID:DOWNLOAD-DIR)
  (ytdl-music-folder . VOID:MUSIC-DIR)
  (ytdl-video-folder . (expand-file-name VOID:VIDEO-DIR))
  (ytdl-always-query-default-filename . nil)
  (ytdl-always-ask-delete-confirmation . t)
  (ytdl-always-query-default-filename . nil)  ;; :defer-config
  (ytdl-media-player . "mpv")
  (ytdl-max-mini-buffer-download-type-entries . 0)
  ;; (ytdl-add-field-in-download-type-list "Music" "p" (expand-file-name "~/podcasts") nil)
  )

ytel

ytel is a YouTube search front-end. It is designed to let the user collect YouTube search results into a buffer and manipulate them with emacs lisp.

(use-package! ytel
  ;; depends on curl (executable-find "curl")
  :commands ytel
  :defer-config
  (defun ytel/watch ()
    "Stream video at point in mpv."
    (interactive)
    (let* ((video (ytel-get-current-video))
     	   (id    (ytel-video-id video)))
      (start-process "ytel mpv" nil
		             "mpv"
		             (concat "https://www.youtube.com/watch?v=" id))
	  "--ytdl-format=bestvideo[height<=?720]+bestaudio/best")
    (message "Starting streaming...")))

emms

emms is a very complete music player. https://github.com/daedreth/UncleDavesEmacs

emms

(use-package! emms
  :setq
  (emms-directory . (concat VOID:DATA-DIR "emms/"))
  (emms-seek-seconds . 5)
  (emms-player-list . '(emms-player-mpv))
  (emms-source-file-default-directory . VOID:MUSIC-DIR)
  (emms-source-file-directory-tree-function . 'emms-source-file-directory-tree-find)
  (emms-playlist-buffer-name . "*EMMS-PLAYLIST*")
  (mpc-host . "127.0.0.1:6600"))

quitting

(defhook! emms:quit-h ()
  "Shut down EMMS."
  :hook kill-emacs-hook
  (when emms-player-playing-p (emms-pause))
  (emms-stop)
  ;; kill any existing mpd processes
  (when (member 'emms-player-mpd emms-player-list)
    (call-process "killall" nil nil nil "mpd")))

screenshot

Pictures or GIFs of behaviors can relate emacs behaviors in away descriptions cannot. From my experience looking at posts on emacs stackexchange or emacs-reddit or even other emacs configs, screenshots are underutilized (or often not utilized at all). In Void, where documentation is very important, I supplement my description of problems with pictures.

screenshot

[[][]] is another emacs screenshot package that.

(use-package! screenshot :commands screenshot)

escr

(use-package! escr :disabled t)

scrot

Like [[][screenshot]], scrot is screenshot taking utility. Interestingly, scrot has a function that can capture a screenshot of a particular emacs window.

(use-package! scrot :ensure (:host github :repo "dakra/scrot.el"))

gifs

This package allows for the creation of gifs from within emacs.

(use-package! gif-screencast)

keypression

keypression is displays keypresses from within Emacs–no external tools necessary! It looks pretty professional!

(use-package! keypression
  :ensure (:host github :repo "chuntaro/emacs-keypression")
  :setq (keypression-frame-justify . 'keypression-right-justified))

Text Editing

highlight-numbers

What highlight-numbers does is pretty self explanatory: it highlights numbers.

(use-package! highlight-numbers
  :hook (prog-mode-hook conf-mode-hook)
  :setq (highlight-numbers-generic-regexp . "\\_<[[:digit:]]+\\(?:\\.[0-9]*\\)?\\_>"))

highlight-escape-sequences

Also pretty self explanatory is highlight-escape-sequences.

(use-package! highlight-escape-sequences
  :ensure (:host github :repo "hlissner/highlight-escape-sequences")
  :hook (prog-mode-hook conf-mode-hook))

hideshow

Hiding text can be extremely useful. It is something that’s used extensively in Org Mode. The feature responsible for doing this is [[][hideshow]].

(use-package! hideshow
  :hook (prog-mode-hook . hs-minor-mode)
  :commands hs-minor-mode hs-toggle-hiding hs-already-hidden-p
  :setq (hs-hide-comments-when-hiding-all . nil))

rainbow-delimiters

rainbow-delimiters colors parentheses different colors based on level. This is a great idea! It makes it really easy to see which parentheses go together.

(use-package! rainbow-delimiters
  :hook (prog-mode-hook reb-mode-hook)
  :setq (rainbow-delimiters-max-face-count . 9))

edit-indirect

Edit indirect is a package that allows me to edit a region from one buffer in a different buffer. If know about org-mode and source blocks, this should sound familiar. There are two major reasons for me why doing this kind of editing has advantages over just editing the original buffer as is. One is that it eases cognitive effort by allowing you to focus on one bite-sized region of a buffer instead the whole thing. The second is that it allows you apply specialized modes to a region that may not be appropriate for the buffer as a whole. I use this package for editing source blocks instead of org-edit-src-code mainly for consistency.

edit-indirect

(use-package! edit-indirect
  :before-call (org/edit:description-at-point org/dwim-edit-source-block)
  :popup ("\\*edit-indirect"
          (display-buffer-at-bottom)
          (window-height . 0.5)
          (slot . 10)))

list of headline elements

Striving to edit org buffers as functionally as possible as opposed to using side-effects is very important. It makes code easier and less error prone to write because you deal with actual lisp object as opposed to less tangible buffer text. It also makes code easier to debug because you can test for the correctness of values returned as opposed to the state change of the buffer.

(cl-defun org:element-headline-elements ()
  "Return the list of org elements from the current headline to the next."
  (save-excursion
    (unless (org-at-heading-p) (org-back-to-heading))
    (unless (org-at-heading-p) (cl-return))
    (cons (org-element-at-point)
          (ignore-errors
            (org-down-element)
            (--unfold (when (ignore-errors (org-forward-element))
                        (cons it (org-element-at-point)))
                      (org-element-at-point))))))

editing headline descriptions

As I’ve [[][mentioned]], Org mode provides syntax to systematically delineate different languages from one another. Editing the contents of these languages is typically done through the use of org-edit-src-code (although I do it via edit-indirect-region). org-edit-src-code provides a convenient and elegant way to edit these languages. It pop open a buffer with the contents of the source block.

However, as I will argue there’s one “language” which does not require source block syntax separation in org mode and that is plain text. In org mode, plain prose is typically utilized to describe the contents of a headline just as I’m doing right now. While (I think at least) it is technically not differentiated from org mode syntax.

However, org mode does not go far enough. If you think about it descriptions under headlines are also in a “different language”–they’re in plain prose. And this is different from org-mode syntax. They utilize a different editing style and require different modes from org-mode.

whether an element is a paragraph

This function isn’t necessary. However, it’s very convenient to abbreviate (eq (org-element-type elt) 'paragraph)–more so because it’s a check I perform all the time.

(defun org:element-paragraph-p (element)
  "Return non-nil if the current element is a paragraph."
  (eq (org-element-type element) 'paragraph))

point in org element

(defun org:element-contains-point-p (point element)
  "Return t if POINT is inside ELEMENT."
  (and (>= point (org-element-property :begin element))
       (>= (org-element-property :end element) point)))

paragraph bounds

(defun org:edit-desc-bounds (point elements)
  "Return the bounds of the description at point.
ELEMENTS is a list of headline elements (see `org:element-headline-elements')."
  (awhen (-find (-some-p (-partial #'org:element-contains-point-p point) it)
                (->> (cdr elements)
                     (-group-by #'org:element-paragraph-p)
                     (-filter (-compose #'org:element-paragraph-p #'car))))
    (cons (org-element-property :contents-begin (-first-item it))
          (org-element-property :contents-end (-last-item it)))))

org edit description at point

(defun org/edit:description-at-point ()
  "Edit the description at point."
  (interactive)
  (-when-let ((beg . end) (org:edit-desc-bounds (point) (org:element-headline-elements)))
    (edit-indirect-region beg end t)))

dwim paragraph bounds

I don’t want to have to travel to a description to edit it. Ideally, I’d like to travel to anywhere I need within a heading from the headline itself.

(defun org:dwim-description-bounds (point elements)
  "Return bounds description under headline as a cons cell.
If there is no description element, return a cons cell containing the the point
where the point should go."
  ;; There are no paragraph elements.
  (acond ((-any-p #'org:element-paragraph-p elements)
          (alet (->> elements
                     (-partition-by #'org:element-paragraph-p)
                     (-filter (-compose #'org:element-paragraph-p #'-first-item))
                     (-first-item))
            (cons (org-element-property :contents-begin (-first-item it))
                  (org-element-property :contents-end (-last-item it)))))
         ;; Is there a source block?
         ((--first (eq (org-element-type it) 'src-block) elements)
          (cons (org-element-property :begin it)
                (org-element-property :begin it)))
         ;; Insert it after the last headline element.
         ((org-element-property :end (-last-item elements))
          (cons it it))))

maybe add newlines

Edit indirect has two hooks (four if you include == ==). This is great! The problem is that you will likely use edit-indirect for various different things. And for these different things, you might want to use different hooks (i.e. a hook for editing a comment in an edit-indirect buffer might not be appropriate for editing a source block.) You don’t want the hooks stepping over eachother.

The best way I could think of achieving this is through temporary or transient hooks.

(defun edit:indirect-add-newlines-maybe-h ()
  "Add newlines to edit-indirect buffer before commiting."
  (when (aand edit-indirect--overlay
              (= (overlay-start it) (overlay-end it)))
    (add-hook 'edit-indirect-before-commit-hook
              (lambda ()
                ;; (not (string-match-p "\\(?:[[:space:]]\\|\n\\)+" (buffer-string)))
                (goto-char (point-max)) (insert "\n\n"))
              0
              :local)))

dwim edit description

(defun org/dwim-edit-description ()
  "Edit a description the way I want to."
  (interactive)
  (-let* ((elements (org:element-headline-elements))
          ((beg . end) (org:dwim-description-bounds (point) elements))
          (edit-indirect-guess-mode-function (lambda (&rest _) (text-mode)))
          (edit-indirect-after-creation-hook edit-indirect-after-creation-hook))
    (edit-indirect:add-before-commit-hook #'edit-indirect:ensure-newline)
    (general-add-hook 'edit-indirect-after-creation-hook
                      ;; Move point to last non-whitespace character.
                      (list (lambda ()
                              (end-of-buffer)
                              (ignore-errors (re-search-backward (rx (or white "\n")))))
                            #'evil-insert-state))
    (edit-indirect-region beg end t)))

org link minor mode

(use-package! org-link-minor-mode
  :commands org-link-minor-mode)

editing source blocks

Why use this package to edit source blocks when there’s already an org function which does it? One reason is consistently. Eventually, I want all separate editing buffers to be from edit-indirect. That why I don’t have to configure both edit-indirect and org source block function to work the way I want; I can deal with just one source.

add before commit hook

(defun edit-indirect:add-before-commit-hook (fn)
  "Add FN."
  (add-hook 'edit-indirect-after-creation-hook
            `(lambda ()
               (add-hook 'edit-indirect-before-commit-hook #',fn nil t))))

prevent ending with no newline

edit-indirect buffers with source block contents must end in a newline otherwise the #+end_src code block delimiter will not end up in its own line (see this for example).

(defun edit-indirect:ensure-newline (&optional block-was-empty-p)
  "Ensure that source block ends with a newline.
If the source block was initially empty and no content was added, don't add a newline.
Otherwise, add a newline if there isn't one."
  (save-excursion
    (when (and (not (string-match-p (rx (* anything) "\n" eos) (buffer-string)))
               (not block-was-empty-p))
      (goto-char (point-max))
      (insert "\n"))))

edit source block at point

(defun org/edit-source-block-at-point ()
  "Edit the source block at point."
  (interactive)
  (alet (org-element-context)
    (when (or (null it) (not (eq 'src-block (org-element-type it))))
      (user-error "No element at point."))
    (-let* (((beg end) (org-src--contents-area it))
            (lang (plist-get (-second-item it) :language))
            (edit-indirect-guess-mode-function `(lambda (&rest _) (funcall (org-src-get-lang-mode ,lang))))
            (edit-indirect-after-creation-hook edit-indirect-after-creation-hook))
      (add-hook 'edit-indirect-after-creation-hook #'edit-indirect:ensure-newline)
      (add-hook 'edit-indirect-after-creation-hook #'beginning-of-buffer)
      (edit-indirect-region beg end t))))

dwim edit source block

I want to be able to edit a source block without actually going to the source block.

(defun org/dwim-edit-source-block ()
  "Edit the source block."
  (interactive)
  (unless (org-in-src-block-p)
    (aif (--first (eq (org-element-type it) 'src-block)
                  (org:element-headline-elements))
        (goto-char (org-element-property :begin it))
      (user-error "No source at headline.")))
  (org/edit-source-block-at-point))

bindings inside edit-indirect

I want quick, convenient bindings I can use to abort or commit (which is edit-indirect lingo for writing the contents of the buffer back into its source file, see edit-indirect-commit.

(define-localleader-key! edit-indirect-mode-map
  "," #'edit-indirect-commit
  "c" #'edit-indirect-commit
  "a" #'edit-indirect-abort)

org bindings

(after! (evil edit-indirect)
  (evil-make-overriding-map edit-indirect-mode-map 'normal))

(define-localleader-key! org-mode-map
  "d" #'org/dwim-edit-description
  "e" #'org/dwim-edit-source-block)

spacing and indentation

aggressive-indent

aggressive-indent indents portions of the text your working on as your typing it. It’s pretty smart and very convenient.

(use-package! aggressive-indent :hook emacs-lisp-mode-hook)

electric indent

(use-package! electric
  :config
  (electric-indent-mode -1))

ws-bulter

ws-butler cleans up whitespace.

(use-package! ws-butler
  :hook (prog-mode-hook org-mode-hook)
  :defer-config
  (append! ws-butler-global-exempt-modes
    '(special-mode comint-mode term-mode eshell-mode)))

ialign

Package ialign lets me use regular expressions to align text.

(use-package! ialign :commands ialign)

lisp editing

smartparens

bootstrap

(use-package! smartparens
  :hook (prog-mode-hook eshell-mode-hook ielm-mode-hook)
  :setq
  (sp-highlight-pair-overlay . nil)
  (sp-highlight-wrap-overlay . nil)
  (sp-highlight-wrap-tag-overlay . nil)
  (sp-show-pair-from-inside . t)
  (sp-cancel-autoskip-on-backward-movement . nil)
  (sp-show-pair-delay . 0.1)
  (sp-max-pair-length . 4)
  (sp-max-prefix-length . 50)
  (sp-escape-quotes-after-insert . nil)
  :defer-config
  (sp-local-pair 'emacs-lisp-mode "<" ">")
  (require 'smartparens-config)
  (sp-local-pair 'minibuffer-inactive-mode "'" nil :actions nil))

disable `smartparens-navigate-skip-match`

(defhook! smartparens:disable-smartparens-navigate-skip-match-h ()
  "Disable smartparents skip match feature."
  :hook after-change-major-mode-hook
  (setq sp-navigate-skip-match nil)
  (setq sp-navigate-consider-sgml-tags nil))

autopairing

(defhook! smartparens:init-in-eval-expression-h ()
  "Enable `smartparens-mode' in the minibuffer, during `eval-expression' or
`evil-ex'."
  :hook minibuffer-setup-hook
  (when (memq this-command '(eval-expression evil-ex))
    (smartparens-mode)))

enable smartparens in eval-expression

(defhook! smartparens:init-in-minibuffer-h ()
  "Enable smartparens for `eval-expression' and `evil-ex'."
  :hook minibuffer-setup-hook
  (when (memq this-command '(eval-expression evil-ex))
    (smartparens-mode 1)))

lispyville

lispyville helps vim commands work better with lisp by providing commands (like lispyville-delete) which preserve parentheses.

initialize

(use-package! lispyville
  :commands lispyville-comment-or-uncomment-line
  :hook emacs-lisp-mode-hook
  :bind
  (:emacs-lisp-mode-map
   ([remap evil-yank]                 . lispyville-yank)
   ([remap evil-delete]               . lispyville-delete)
   ([remap evil-change]               . lispyville-change)
   ([remap evil-yank-line]            . lispyville-yank-line)
   ([remap evil-delete-line]          . lispyville-delete-line)
   ([remap evil-change-line]          . lispyville-change-line)
   ([remap evil-delete-char]          . lispyville-delete-char-or-splice)
   ([remap evil-delete-backward-char] . lispyville-delete-char-or-splice-backwards)
   ([remap evil-substitute]           . lispyville-substitute)
   ([remap evil-change-whole-line]    . lispyville-change-whole-line)
   ([remap evil-join]                 . lispyville-join)))

text objects

(general-def evil-inner-text-objects-map
  "a" #'lispyville-inner-atom
  "l" #'lispyville-inner-list
  "x" #'lispyville-inner-sexp
  "c" #'lispyville-inner-comment
  ;; "f" #'lispyville-inner-function
  ;; "c" #'evilnc-inner-comment
  ;; overriding inner-sentence.
  "s" #'lispyville-inner-string)

(general-def evil-outer-text-objects-map
  "a" #'lispyville-a-atom
  "l" #'lispyville-a-list
  "x" #'lispyville-a-sexp
  "c" #'lispyville-a-comment
  ;; "f" #'lispyville-a-function
  ;; "c" #'evilnc-outer-commenter
  ;; "c" #'evilnc-outer-commenter
  "s" #'lispyville-a-string)

slurp/barf

(general-def 'normal lispyville-mode-map
  ">" #'lispyville-slurp
  "<" #'lispyville-barf)

escape

lispyville binds escape to lispyville-normal-state. So for void:escape-hook to still happen on escape, I need to add evil:escape-a as advice to lispyville-normal-state.

Sometimes evil-normal-state enters visual state.

(general-def '(emacs insert) lispyville-mode-map [escape] #'lispyville-normal-state)
(advice-add #'lispyville-normal-state :after #'evil:dwim-abort-after-escape-a)

additional

(general-def '(emacs insert) lispyville-mode-map
  "SPC" #'lispy-space
  ";"   #'lispy-comment)

(general-def '(normal visual) lispyville-mode-map
  "M-j" #'lispyville-drag-forward
  "M-k" #'lispyville-drag-backward
  "M-R" #'lispyville-raise-list
  "M-v" #'lispy-convolute-sexp)

lispy

For learning how to use lispy. the README and the lispy function reference were very useful to me.

(use-package! lispy
  :hook emacs-lisp-mode-hook
  :setq
  (lispy-avy-style-paren . 'at-full)
  (lispy-eval-display-style . 'overlay)
  (lispy-safe-delete . t)
  (lispy-safe-copy . t)
  (lispy-safe-paste . t)
  (lispy-safe-actions-no-pull-delimiters-into-comments . t)
  (lispy-delete-sexp-from-within . t)
  (lispy-parens-only-left-in-string-or-comment . nil)
  ;; TODO see how performant is at larger thresholds and optimize
  (lispy-safe-threshold . 5000)
  (lispy-use-sly . t)
  ;; allow space before asterisk for headings (e.g. ";; *")
  (lispy-outline . "^;;\\(?:;[^#]\\|[[:space:]]*\\*+\\)")
  (lispy-key-theme . nil)
  :defer-config
  ;; You'll get void variable if you don't do this.
  (after! avy (setq lispy-avy-keys avy-keys)))

writing

spell-number

(use-package! spell-number
  :setq
  (spelln-language . 'english-us)
  (spelln-country . 'united-states)
  (spelln-period-character . ?,)
  (spelln-decimal-character . ?.))

fill paragraph

(use-package! aggressive-fill-paragraph)

spell check

(use-package! spell-fu
  :ensure (:host gitlab :repo "ideasman42/emacs-spell-fu")
  :commands spell-fu-mode
  :setq (spell-fu-directory . (concat VOID:DATA-DIR "spell-fu/")))

autocapitalize

auto-capitalize automatically capitalizes the first word of a sentence for me. It will also upcase any word I add to auto-capitalize-words.

(use-package! auto-capitalize
  :setq (auto-capitalize-words . '("I" "English")))

thesaurus

(use-package! powerthesaurus
  :commands (powerthesaurus-lookup-word-at-point power-thesaurus-lookup-word-dwim))

dictionary

(use-package! define-it
  :commands define-it define-it-at-point
  :setq
  (define-it-output-choice . 'view)
  (define-it-show-google-translate . nil))

evil

evil

evil is an extensible vi layer for Emacs. It emulates the main features of Vim, and provides facilities for writing custom extensions. Also see our page on EmacsWiki. See a brief manual. See the evil-guide by noctuid.

evil

(use-package! evil
  :require t
  :hook window-setup-hook
  :custom
  (evil-want-C-u-scroll    . t)
  (evil-want-C-d-scroll    . t)
  (evil-want-C-w-delete    . t)
  (evil-want-Y-yank-to-eol . t)
  (evil-overriding-maps    . nil)
  (evil-want-minibuffer    . t)
  :pre-setq
  (evil-want-keybinding                 . nil)
  :setq
  (evil-want-C-w-in-emacs-state         . nil)
  (evil-want-visual-char-semi-exclusive . t)
  ;; Whether the cursor can move past the end of the line.
  (evil-move-beyond-eol                 . nil)
  (evil-magic                           . t)
  (evil-echo-state                      . nil)
  (evil-indent-convert-tabs             . t)
  (evil-ex-search-vim-style-regexp      . t)
  (evil-ex-substitute-global            . t)
  (evil-ex-visual-char-range            . t)
  (evil-insert-skip-empty-lines         . t)
  (evil-mode-line-format                . nil)
  (evil-respect-visual-line-mode        . t)
  (evil-symbol-word-search              . t)
  (shift-select-mode                    . nil))

cursors

It’s nice to have cursors change colors (and sometimes shape) depending on the current evil state. It makes it easy to tell which state you’re in. I define some colors here. Evil has a cursor variable for each state. The cursor variable for insert state, for example, is evil-insert-state-cursor. Its value is of the form: ((CURSOR-SHAPE . CURSOR-WIDTH) COLOR).

colors and shapes

Evil differentiates what state you’re in based on the cursor color.

(defhook! evil:init-cursors-h ()
  "Initialize the default cursor shape and size."
  :hook evil-mode-hook
  (setq evil-insert-state-cursor   '((bar . 3)   "chartreuse3"))
  (setq evil-emacs-state-cursor    '((bar . 3)   "SkyBlue2"))
  (setq evil-normal-state-cursor   '( box        "DarkGoldenrod2"))
  (setq evil-visual-state-cursor   '((hollow)    "dark gray"))
  (setq evil-operator-state-cursor '((hbar . 10) "hot pink"))
  (setq evil-replace-state-cursor  '( box        "chocolate"))
  (setq evil-motion-state-cursor   '( box        "plum3")))

updating cursors

After a theme is loaded, the cursor color won’t automatically update. Therefore, I add a hook in void:after-load-theme-hook. Now after a new theme is loaded, the cursor color will update.

(defhook! evil:enable-cursor-refresh-h ()
  "Enable cursor refreshing after theme change."
  :hook evil-mode-hook
  (if (bound-and-true-p evil-mode)
      (add-hook 'void:after-load-theme-hook #'evil-refresh-cursor 100)
    (remove-hook 'void:after-load-theme-hook #'evil-refresh-cursor)))

normal state everywhere

(defhook! evil:make-normal-state-default-state-h ()
  :hook evil-mode-hook
  (setq evil-normal-state-modes (append evil-emacs-state-modes evil-normal-state-modes))
  (setq evil-emacs-state-modes nil)
  (setq evil-motion-state-modes nil))

(defadvice! evil:treat-motion-as-normal-state (orig-fn &rest args)
  "Advice for `evil-make-overriding-map' that inhibits motion state."
  :around evil-make-overriding-map
  (-let (((keymap state copy) args))
    (funcall orig-fn keymap (if (eq state 'motion) 'normal state) copy)))

(defadvice! evil:set-initial-state (orig-fn &rest args)
  :around evil-set-initial-state
  (-let (((mode state) args))
    (funcall orig-fn mode (if (eq state 'motion) 'normal state))))

(advice-add #'evil-motion-state :override #'evil-normal-state)

insert state in minibuffer

Before I just used (evil-change-state evil-previous-state) to revert the state back to what it last was. But this fails with evil-force-normal-state which is what I’m currently using to exit the minibuffer because then the last state is normal state if the minibuffer is aborted. Using a evil:state-before-minibuffer ensures that the state will be reverted to the correct one.

(defvar evil:state-before-minibuffer nil
  "Evil state before entering in the minibuffer.
This variable will be nil when the minibuffer is closed.")

(defhook! evil:enable-insert-state-in-minibuffer ()
  :hook evil-mode-hook
  (let ((fn (if (bound-and-true-p evil-mode) #'add-hook #'remove-hook)))
    (funcall fn 'minibuffer-enter-hook #'evil:save-state-before-minibuffer-h)
    (funcall fn 'minibuffer-exit-hook #'evil:restore-state-after-minibuffer-h)))

(defun evil:save-state-before-minibuffer-h ()
  "Save state before minibuffer."
  (setq evil:state-before-minibuffer evil-state)
  (evil-insert-state))

(defun evil:restore-state-after-minibuffer-h ()
  "Restore state after minibuffer."
  (evil-change-state evil:state-before-minibuffer)
  (setq evil:state-before-minibuffer nil))

escape

escape

We want escape to be a general “quit everything”.

(general-def :states '(emacs insert) [escape] #'evil-force-normal-state)

(defadvice! evil:dwim-abort-after-escape-a ()
  "Exits out of whatever is happening after escape."
  :after evil-force-normal-state
  (cond ((minibuffer-window-active-p (minibuffer-window))
         (abort-recursive-edit))
        ((run-hook-with-args-until-success 'void:escape-hook))
        ((or defining-kbd-macro executing-kbd-macro) nil)
        (t (keyboard-quit))))

keychord integration

Sometimes we don’t have access to a convenient escape key–I mean that caps-lock is not bound to escape. Or, perhaps, we might find it faster or preferable to press jk really quickly to invoke escape.

This is better than evil escape as it only binds in insert.

(use-package! key-chord
  :after-call (evil-insert-state evil-emacs-state)
  :defer-config
  (quiet! (key-chord-mode 1))
  (general-def :states '(visual insert)
    (general-chord "jk") 'evil-force-normal-state
    (general-chord "kj") 'evil-force-normal-state))

saving

(setq save-silently t)

(defun evil:save-message ()
  (message "\"%s\" %dL, %dC written"
           (buffer-name)
           (count-lines (point-min) (point-max))
           (buffer-size)))

text objects

To edit text efficiently Vim has the concept of text objects. Text objects are structures that are seen in text. For example, a set of words followed by a period is a sentence. A words between two closing parentheses is a sexp.

general delimiter text object

I discovered this the form text object from using evil-cleverparens in the past. The package evil-cleverparens was too slow for my taste; noctuid’s evil-lispy is much faster and gave me the functionality that I needed most from evil-cleverparens: deleting and copying text with parentheses intelligently. However, many of the ideas of evil-cleverparens were excellent. One particular idea was to have a general form text object. Instead of specifying the particular surrounding bounds when doing an evil operator command you just use a single key for them. It’s kind of like a Do-What-I-Mean surround operator. This is suprisingly useful because it takes significant time to specify whether you want [] or {}= or () or "". The main drawback you cannot distinguish between surround characters at multiple levels–it just takes the closest one. In practice, this is rarely an issue.

(after! evil
  (evil-define-text-object evil:textobj-inner-form (count &rest _)
    "Inner sexp object."
    (-if-let ((beg . end)
              (->> (list (lispy--bounds-list) (lispy--bounds-string))
                   (-non-nil)
                   (--sort (< (- (cdr it) (car it)) (- (cdr other) (car other))))
                   (car)))
        (evil-range (1+ beg) (1- end) 'inclusive :expanded t)
      (error "No surrounding form found.")))

  (evil-define-text-object evil:textobj-outer-form (count &rest _)
    "Smartparens inner sexp object."
    (-if-let ((beg . end)
              (->> (list (lispy--bounds-list) (lispy--bounds-string))
                   (-non-nil)
                   (--sort (< (- (cdr it) (car it)) (- (cdr other) (car other))))
                   (car)))
        (evil-range beg end 'inclusive :expanded t)
      (error "No surrounding form found.")))

  (general-def evil-inner-text-objects-map
    "f" #'evil:textobj-inner-form)
  (general-def evil-outer-text-objects-map
    "f" #'evil:textobj-outer-form))

fix vim/evil around `""`

Vim and Evil both have the interesting (inconsistent?) behavior that doing an outer text object operator on a comment grabs some whitespace on the left side. Try doing va" to (progn "hello world") and you’ll see that \s"hello world" is selected instead of just “hello world”.

Why not just go to the end of the " like any other around operator?

(after! evil
  (evil-define-text-object evil:textobj-a-string (count &rest _)
    "An outer comment text object as defined by `lispy--bounds-string'."
    (-if-let ((beg . end) (lispy--bounds-string))
        (evil-range beg end 'exclusive :expanded t)
      (error "Not inside a comment.")))

  (general-def evil-outer-text-objects-map
    "\"" #'evil:textobj-a-string))

package specific setup

helpful

(after! (evil helpful)
  (evil-set-initial-state 'helpful-mode 'normal))

magit

(after! (evil magit)
  (add-hook 'git-commit-mode-hook #'evil-insert-state))

org

insert state

(after! (evil org)
  (add-hook 'org-insert-heading-hook #'evil-insert-state)
  (after! org-capture
    (add-hook 'org-capture-mode-hook #'evil-insert-state)))

Info

(general-def
  (:map Info-mode-map)
  (:m "h"   #'Info-backward-node)
  (:m "l"   #'Info-forward-node)
  (:m "H"   #'Info-history-back)
  (:m "L"   #'Info-history-forward)
  (:m "r"   #'Info-history)
  (:m "J"   #'evil-scroll-page-down)
  (:m "K"   #'evil-scroll-page-up)
  (:m "f"   #'ace-link-info)
  (:m "u"   #'Info-up)
  (:m "U"   #'Info-top-node)
  (:m "m"   #'Info-menu)
  (:m "s"   #'Info-search)
  (:m "RET" #'Info-follow-nearest-node)
  (:m "q"   #'quit-window))

eshell

evil operators

evil-change

(after! eshell
  (evil-define-operator eshell/evil-change (beg end type register yank-handler delete-func)
    "Like `evil-change' but will not delete/copy the prompt."
    (interactive "<R><x><y>")
    (save-restriction
      (narrow-to-region eshell-last-output-end (point-max))
      (evil-change (max beg (point-min))
                   (if (eq type 'line) (point-max) (min (or end (point-max)) (point-max)))
                   type register yank-handler delete-func))))

evil-change-line

(after! eshell
  (evil-define-operator eshell/evil-change-line (beg end type register yank-handler)
    "Change to end of line."
    :motion evil-end-of-line
    (interactive "<R><x><y>")
    (eshell/evil-change beg end type register yank-handler #'evil-delete-line)))

evil-delete

(after! eshell
  (evil-define-operator eshell/evil-delete (beg end type register yank-handler)
    "Like `evil-delete' but will not delete/copy the prompt."
    (interactive "<R><x><y>")
    (save-restriction
      (narrow-to-region eshell-last-output-end (point-max))
      (evil-delete (if beg (max beg (point-min)) (point-min))
                   (if (eq type 'line) (point-max) (min (or end (point-max)) (point-max)))
                   type register yank-handler))))

evil-delete-line

(after! eshell
  (evil-define-operator eshell/evil-delete-line (_beg end type register yank-handler)
    "Change to end of line."
    :motion nil
    :keep-visual t
    (interactive "<R><x>")
    (eshell/evil-delete (point) end type register yank-handler)))

update cursors after entering eshell

(after! evil
  (evil-set-initial-state 'eshell-mode 'insert))

smartparens

;; smartparens breaks evil-mode's replace state
(after! (evil smartparens)
  (add-hook 'evil-replace-state-entry-hook #'turn-off-smartparens-mode)
  (add-hook 'evil-replace-state-exit-hook  #'turn-on-smartparens-mode))

debugger-mode

(after! evil (evil-set-initial-state 'debugger-mode 'emacs))

autoyasnippet

(use-package! auto-yasnippet
  :defer-config (advice-add #'aya-expand :after #'evil-insert-state)
  :setq (aya-persist-snippets-dir . (concat VOID:LOCAL-DIR "auto-snippets/")))

yasnippet

(after! (evil lispy)
  (general-def
    (:map evil-lispy-state-map)
    ("l" #'lispy-right)
    ("h" #'lispy-left)
    ("f" #'lispy-flow)
    ("j" #'lispy-down)
    ("k" #'lispy-up)
    ("d" #'lispy-different)
    ("o" #'lispy-other-mode)
    ("p" #'lispy-eval-other-window)
    ("P" #'lispy-paste)
    ("y" #'lispy-occur)
    ("z" #'lh-knight/body)))

evil-surround

(use-package! evil-surround :hook prog-mode-hook text-mode-hook)

evil-matchit

(use-package! evil-matchit :hook prog-mode)

evil-exchange

Package evil-exchange lets me swap two regions of text.

(use-package! evil-exchange
  :commands evil-exchange
  :init
  (general-def 'normal
    :prefix "g"
    "X" (list :def #'evil-exchange-cancel :wk "cancel")
    "x" (list :def #'evil-exchange :wk "exchange")))

evil-visualstar

evil-visualstar

(use-package! evil-visualstar
  :commands (evil-visualstar/begin-search-backward evil-visualstar/begin-search-forward)
  :bind (:evil-visual-state-map
         ("#" . evil-visualstar/begin-search-backward)
         ("*" . evil-visualstar/begin-search-forward)))

expand-region

expand-region allows me to toggle a key (“v” in my case) to select progressively larger text objects. It’s saves me keystrokes.

(use-package! expand-region
  :commands (er/expand-region er/contract-region er/mark-symbol er/mark-word)
  :init
  (general-def 'visual
    "V" #'er/contract-region
    "v" #'er/expand-region)
  :defer-config
  (defadvice! void:quit-expand-region-a ()
    "Properly abort an expand-region region."
    :before evil-escape evil:escape-a
    (when (memq last-command '(er/expand-region er/contract-region))
      (er/contract-region 0))))

avy

Avy

bootstrap

(use-package! avy
  :commands avy-jump
  :setq
  (avy-background . t)
  ;; Jump only on current window.
  (avy-all-windows . nil)
  ;; Use avy keys.
  (avy-keys-alist . nil)
  (avy-keys . (list
               ;; homerow keys in alternating order.
               ?a ?j ?s ?k ?d ?l ?f ?\;
               ;; middle homerow keys
               ?g ?h
               ;; keys above homerow in alternating order
               ?t ?y ?r ?u ?e ?i ?w ?o ?q ?p
               ;; keys below homerow
               ?b ?n ?v ?m ?c ?, ?x ?. ?z ?/))
  (avy-style . 'at))

avy-command-helper

(defun avy:jump-to-regexp (regexp)
  (avy-jump regexp
            :beg (window-start)
            :end (window-end)
            :pred `(lambda () (/= (1+ ,(point)) (point)))))

avy commands

(defun void/evil-beginning-of-word ()
  (interactive)
  (avy:jump-to-regexp (rx word-start nonl)))

(defun void/evil-beginning-of-WORD ()
  (interactive)
  (avy:jump-to-regexp (rx symbol-start nonl)))

(defun void/evil-end-of-word ()
  (interactive)
  (avy:jump-to-regexp (rx nonl word-end)))

(defun void/evil-end-of-WORD ()
  (interactive)
  (avy:jump-to-regexp (rx nonl symbol-end)))

bindings

(general-def 'normal
  "f" #'avy-goto-char
  "w" #'void/evil-beginning-of-word
  "W" #'void/evil-beginning-of-WORD
  "e" #'void/evil-end-of-word
  "E" #'void/evil-end-of-WORD)

undo

undo-fu

(use-package! undo-fu
  :after-hook void:after-switch-buffer-hook
  :before-call after-find-file
  :setq
  (undo-limit . 400000)
  (undo-strong-limit . 3000000)
  (undo-outer-limit . 3000000)
  :bind
  ([remap undo] . undo-fu-only-undo)
  ([remap redo] . undo-fu-only-redo)
  :defer-config
  (global-undo-tree-mode -1))

Utility

eshell

eshell is a built-in shell written entirely in elisp. This means that it’s as portable and customizable as emacs itself. It can run elisp functions as commands. There’s a good article about it in mastering-emacs. Other articles I have like about eshell: ambrevar’s eshell post, Howard Abram’s Post.

bootstrap

(use-feature! eshell
  :commands eshell
  :idle-require
  em-alias em-banner em-basic em-cmpl
  em-dirs em-glob em-hist em-ls em-prompt
  em-script em-term em-unix
  :popup ("\\*eshell"
          (display-buffer-at-bottom)
          (window-height . 0.5)
          (side . bottom)
          (slot . 2))
  :setq
  (eshell-directory-name . (concat VOID:DATA-DIR "eshell/"))
  (eshell-history-file-name . (concat eshell-directory-name "history"))
  (eshell-prefer-lisp-functions . nil)
  (eshell-scroll-to-bottom-on-input . 'all)
  (eshell-scroll-to-bottom-on-output . 'all)
  (eshell-buffer-shorthand . t)
  (eshell-kill-processes-on-exit . t)
  (eshell-hist-ignoredups . t)
  (eshell-input-filter . #'eshell-input-filter-initial-space)
  (eshell-glob-case-insensitive . t)
  (eshell-error-if-no-glob . t)
  (eshell-banner-message . '(format "%s %s\n\n"
                             (propertize (format " %s " (string-trim (buffer-name)))
                              'face 'mode-line-highlight)
                             (propertize (current-time-string)
                              'face 'font-lock-keyword-face)))
  :defer-config
  (remove-hook 'eshell-output-filter-functions
               'eshell-postoutput-scroll-to-bottom))

visual commands

(after! em-term
  (--each '("tmux" "htop" "bash" "zsh" "fish" "vim" "nvim" "ncmpcpp")
    (add-to-list 'eshell-visual-commands it)))

improvements

Eshell uses pcomplete as its completion engine.

pcomplete

This replaces the default popup window at the bottom of eshell. By using the completion-in-region backend, it triggers ivy/helm for completion.

(defun eshell/pcomplete ()
  "Use pcomplete with completion-in-region backend."
  (interactive)
  (require 'pcomplete)
  (ignore-errors (pcomplete-std-complete)))

go to prompt on insert

(defun eshell:goto-prompt-on-insert-h ()
  "Move cursor to the prompt when switching to insert mode."
  (when (< (point) eshell-last-output-end)
    (goto-char
     (if (memq this-command '(evil-append evil-append-line))
         (point-max)
       eshell-last-output-end))))

eshell commands

eshell-z

(use-package! eshell-z
  :after eshell
  :commands eshell/z
  :setq (eshell:z-file . (expand-file-name "z" eshell-directory-name))
  :defer-config
  (defalias 'eshell:z-file 'eshell-z-freq-dir-hash-table-file-name))

eshell-up

This is an Emacs package for quickly navigating to a specific parent directory in eshell without having to repeatedly typing cd ...

(use-package! eshell-up
  :after eshell
  :commands eshell-up eshell-up-peek
  :init
  (defalias 'eshell/up 'eshell-up)
  (defalias 'eshell/pk 'eshell-up-peek)
  (defalias 'eshell/peek 'eshell-up-peek))

eshell-clear

The shell often gets cluttered with many commands. It’s often useful to clear it and indeed there are many suggestions on how to do so online. However, many of them involve erasing the eshell buffer or making it’s previous contents inaccessable. I don’t like getting rid of information that could be important. All I really wanted is to just scroll up to the top of the window so that the previous contents weren’t visible. Note that it is important that this command returns nil. Eshell shell ignores output returns nil. However, when it returns non-nil it prints it to the eshell buffer, which results in a residue line–that’s not what we want.

https://emacs.stackexchange.com/questions/28819/eshell-goes-to-the-bottom-of-the-page-after-executing-a-command

(defadvice! eshell:scroll-buffer-to-top (&rest _)
  "Scroll eshell buffer to top.
The effect of this is to clear the contents of the eshell buffer."
  :override eshell/clear
  (progn (call-interactively #'evil-scroll-line-to-top) nil))

display

prompt

I got a lot of inspiration from the modern emacs blog. I think the author’s code is in general a good example of how to use macros to abstract a task and make it much simpler than it would be otherwise.

with-face

(defmacro with-face! (string &rest props)
  "Return STR propertized with PROPS."
  `(propertize ,string 'face '(,@props)))

helpers

Eshell prompt function finds eshell section functions specified by +eshell-enabled-sections and concatenates their results in order to generate the body of the eshell prompt.

(defun eshell:acc (acc x)
  "Accumulator for evaluating and concatenating `eshell:enabled-sections'."
  (--if-let (funcall x)
      (if (s-blank? acc)
          it
        (concat acc eshell:sep it))
    acc))

(defun eshell:prompt-func ()
  "Generate the eshell prompt.
This function generates the eshell prompt by concatenating `eshell:header' with
valid `eshell:enabled-sections' and the `eshell-prompt-string'."
  (concat eshell:header
          (->> eshell:enabled-sections
               (mapcar (lambda (it) (void:symbol-intern 'eshell-prompt-- it)))
               (-filter #'fboundp)
               (-reduce-from #'eshell:acc ""))
          eshell-prompt-string))

eshell components

This heading contains the parts that make up the eshell prompt. They are the header, the separator, the section delimiter and, the meat of the prompt, the actual eshell sections.

(defvar eshell:sep "\s|\s"
  "Separator between eshell sections.")

(defvar eshell:section-delim "\s"
  "Separator between an eshell section icon and form.")

(defvar eshell:header "\s"
  "Eshell prompt header.")

(defvar eshell:enabled-sections '(dir git)
  "List of enabled eshell sections.
Each element of the list is an abbreviated.")

;; This is a regex that matches your eshell prompt so that eshell knows what to
;; keep readonly and what not to.
(setq eshell-prompt-regexp (rx (*? anything) "-> "))
(setq eshell-prompt-string " -> ")

(setq eshell-prompt-function #'eshell:prompt-func)

text wrapping

(defhook! eshell:enable-text-wrapping-h ()
  "Enable text wrapping."
  :hook eshell-mode-hook
  (visual-line-mode +1)
  (set-display-table-slot standard-display-table 0 ?\ ))

fringes

(defhook! eshell:remove-fringes-h ()
  "Remove fringes for eshell."
  :hook eshell-mode-hook
  (set-window-fringes nil 0 0)
  (set-window-margins nil 1 nil))

hide modeline

(add-hook 'eshell-mode-hook #'hide-mode-line-mode)

hooks

aliases

setup

They are meant to emulate useful shell utilities, like fasd and bd. Note that you may overwrite these in your eshell-aliases-file. This is here to provide an alternative, elisp-centric way to define your aliases.

(defvar eshell:aliases
  '(("q"  "exit")
    ("ff"  "find-file $1")
    ("rg" "rg --color=always $*")
    ("ag" "ag --color=always $*")
    ("l"  "ls -lh")
    ("ll" "ls -lah"))
  "An alist of default eshell aliases. ")

initialize

(defvar eshell--default:aliases nil)

(defhook! eshell:init-aliases-h ()
  "Initialize eshell aliases."
  :hook eshell-alias-load-hook
  (setq eshell--default:aliases eshell-command-aliases-list
        eshell-command-aliases-list
        (append eshell-command-aliases-list
                eshell:aliases)))

(advice-add #'eshell-write-aliases-list :override #'ignore)

shrink-path

(use-package! shrink-path
  :commands shrink-path-file)

command-log-mode

command-log-mode keeps track of all the commands you run and displays them to you on a side window.

(use-package! command-log-mode
  :commands command-log-mode global-command-log-mode
  :setq
  (command-log-mode-auto-show . t)
  (command-log-mode-open-log-turns-on-mode . nil)
  (command-log-mode-is-global . t))

recentf

recentf is a built-in program that tracks the files you’ve opened recently persistently. This is a great idea because these are the files you’ll likely revisit. In practice, I look at this list of files in addition to the buffers I already have open using a [[][completion-framework]]. Because of this I rarely have to set out to look for a file with dired.

recentf

(use-feature! recentf
  :before-call find-file
  :idle-require easymenu tree-widget timer
  :commands recentf-open-files
  :defer-config
  (advice-add #'recentf-save-list :before #'recentf-cleanup)
  (recentf-mode 1)
  :setq
  (recentf-exclude . (list #'file-remote-p
                           "\\.\\(?:gz\\|gif\\|svg\\|png\\|jpe?g\\)$"
                           ;; ignore private Void temp files (but not all of them)
                           #'(lambda (file)
                               (-some-p (apply-partially #'file-in-directory-p file)
                                (list VOID:DATA-DIR)))))
  (recentf-max-menu-items . 0)
  (recentf-max-saved-items . 700)
  :custom
  (recentf-save-file . (concat VOID:DATA-DIR "recentf"))
  (recentf-auto-cleanup . 'never)
  (recentf-filename-handlers . '(file-truename abbreviate-file-name)))

silence recentf

(defadvice! recentf:shut-up-a (orig-fn &rest args)
  "Shut up recentf."
  :around recentf-mode
  (shut-up! (apply orig-fn args)))

saveplace

As its name suggests, save-place is a built-in package that stores the buffer location you left off at in a particular buffer. When you visit that buffer again, you are taken to the location you left off. This is very convenient.

(use-feature! saveplace
  :after-call after-find-file
  :setq
  (save-place-file . (concat VOID:DATA-DIR "saveplace"))
  (save-place-limit . nil)
  :config
  (save-place-mode)
  (defadvice! save-place-recenter-on-load-saveplace-a (&rest _)
    "Recenter on cursor when loading a saved place."
    :after-while save-place-find-file-hook
    (when buffer-file-name (ignore-errors (recenter)))))

savehist

(use-feature! savehist
  :idle-require custom
  :hook emacs-startup-hook
  :setq
  (savehist-save-minibuffer-history . t)
  (savehist-autosave-interval . nil)
  (savehist-additional-variables . '(kill-ring search-ring regexp-search-ring))
  (savehist-file . (concat VOID:DATA-DIR "savehist")))

(defhook! void:unpropertize-kill-ring-h ()
  "Remove text properties from `kill-ring'."
  :append kill-emacs-hook
  (setq kill-ring
        (mapcar (lambda (it) (when (stringp it) (substring-no-properties it)))
                 (-non-nil kill-ring))))

bookmarks

Bookmarks persistently store file locations. I use bookmark-plus an increadibly featureful bookmark extension package. Usually xah lee has good basic overviews of topics on his site, check out the one on bookmarks. I had already known about bookmark-plus, however I hadn’t really done anything with it. It was after I read this question.

(use-feature! bookmark
  :pre-setq
  (bookmark-default-file . (concat VOID:DATA-DIR "bookmarks"))
  (bookmark-save-flag . t))

elfeed

elfeed

elfeed is a news feed reader. I can give it a set of rss-feeds to blogs I like to read and then read the articles in emacs! Typically, you’d set the feeds via elfeed-feeds, but with elfeed-org I can do it by specifying a set of org files from which to read my feeds. The org file I use is elfeed.org. The rmh-elfeed-org-tree-id is the tags that elfeed-org will consider when checking for feeds. Note that it’s case-sensitive so consider this if your tags (like me) capitalized. The elfeed-search-filter specifies how far back to go when looking for newsfeed posts. So if you have some infrequent blogs, you might have to go further back in time to see older posts.

(use-package! elfeed
  :ignore-buffers ("\\*elfeed")
  :commands elfeed
  :setq
  (elfeed-search-filter         . "@1-year-old")
  (elfeed-db-directory          . (concat VOID:DATA-DIR "elfeed/db/"))
  (elfeed-enclosure-default-dir . (concat VOID:DATA-DIR "elfeed/enclosures/"))
  (elfeed-show-entry-switch     . #'pop-to-buffer)
  (elfeed-show-entry-delete     . #'elfeed-kill-buffer)
  (shr-max-image-proportion     . 0.8))

elfeed org

(use-package! elfeed-org
  :after elfeed
  :require t
  :setq
  (rmh-elfeed-org-files      . (list (concat VOID:ORG-DIR "elfeed.org")))
  (rmh-elfeed-org-tree-id    . "ELFEED")
  (rmh-elfeed-org-ignore-tag . "IGNORE")
  :config
  (let ((default-directory org-directory))
    (elfeed-org)))

pomodoro

pomodoro is meant to provide functions to follow the pomodoro style of working. There is a slight lag in emacs when I play a sound with (play-sound-file sound). I might consider doing this asynchronously.

(use-package! pomodoro
  :commands pomodoro-start
  :setq
  (pomodoro-play-sounds       . t)
  (pomodoro-work-start-sound  . (concat VOID:ALERT-SOUNDS "A-Tone-His_Self-1266414414.wav"))
  (pomodoro-break-start-sound . (concat VOID:ALERT-SOUNDS "A-Tone-His_Self-1266414414.wav"))
  (pomodoro-work-time         . 25)
  (pomodoro-break-time        . 5)
  (pomodoro-long-break-time   . 15))

(defadvice! pomodoro:play-sound-a (sound)
  "Play sound without using the call-process."
  :override play-pomodoro-sound
  (play-sound-file sound))

file browsing

dired

dired

(use-feature! dired
  :setq
  (dired-recursive-copies . 'always)
  (dired-recursive-deletes . 'top)
  (dired-hide-details-hide-symlink-targets . nil))

sort directories first

(defhook! dired:sort-directories-first-h ()
  "List directories first in dired buffers."
  :hook dired-after-readin-hook
  (save-excursion
    (let (buffer-read-only)
      (forward-line 2) ;; beyond dir. header
      (sort-regexp-fields t "^.*$" "[ ]*." (point) (point-max))))
  (and (featurep 'xemacs)
       (fboundp 'dired-insert-set-properties)
       (dired-insert-set-properties (point-min) (point-max)))
  (set-buffer-modified-p nil))

Create non-existent directory

(defun dired:create-non-existent-directory-h ()
  "Automatically create missing directories when creating new file."
  (let ((parent-directory (file-name-directory buffer-file-name)))
    (when (and (not (file-exists-p parent-directory))
               (y-or-n-p (format "Directory `%s' does not exist! Create it?" parent-directory)))
      (make-directory parent-directory t))))

(after! dired
  (add-to-list 'find-file-not-found-functions 'dired:create-non-existent-directory-h nil #'eq))

ranger

ranger is a file browser built on top of dired that seeks to emulate a VIM inspired file manager of also called ranger.

bindings

important

(general-def 'normal ranger-mode-map
  "m" #'dired-mark
  "d" #'dired-do-delete
  "s" #'dired-do-symlink
  "e" #'eshell
  "c" #'dired-do-copy
  "M" #'dired-mark-files-containing-regexp
  "r" #'dired-do-rename
  "U" #'dired-unmark-all-marks
  "x" #'dired-do-shell-command
  "a" #'avy-goto-line
  "C-r" #'ranger-refresh
  "f" #'find-file
  "q" #'ranger-close)

generic

(general-def 'normal ranger-mode-map
  "A" #'dired-do-find-regexp
  "C" #'dired-do-copy
  "B" #'dired-do-byte-compile
  "D" #'dired-do-delete
  "H" #'dired-do-hardlink
  "L" #'dired-do-load
  "M" #'dired-do-chmod
  "O" #'dired-do-chown
  "P" #'dired-do-print
  "Q" #'dired-do-find-regexp-and-replace
  "R" #'dired-do-rename
  "S" #'dired-do-symlink
  "T" #'dired-do-touch
  "X" #'dired-do-shell-command
  "Z" #'dired-do-compress
  "c" #'dired-do-compress-to
  "!" #'dired-do-shell-command
  "&" #'dired-do-async-shell-command)

other

(general-def 'normal ranger-mode-map
  "["                   #'dired-prev-dirline
  "]"                   #'dired-next-dirline
  "<"                   #'dired-prev-dirline
  ">"                   #'dired-next-dirline
  "^"                   #'dired-up-directory
  "k"                   #'dired-previous-line
  "j"                   #'dired-next-line
  "h"                   #'dired-up-directory
  "l"                   #'dired-find-file
  "RET"                 #'dired-find-file
  [remap next-line]     #'dired-next-line
  [remap previous-line] #'dired-previous-line)

other

(general-def 'normal ranger-mode-map
  :prefix "%"
  "u" #'dired-upcase
  "l" #'dired-downcase
  "d" #'dired-flag-files-regexp
  "r" #'dired-do-rename-regexp
  "C" #'dired-do-copy-regexp
  "H" #'dired-do-hardlink-regexp
  "R" #'dired-do-rename-regexp
  "S" #'dired-do-symlink-regexp
  "&" #'dired-flag-garbage-files)

marking

(general-def 'normal ranger-mode-map
  :prefix "*"
  "*"         #'dired-mark-executables
  "/"         #'dired-mark-directories
  "@"         #'dired-mark-symlinks
  "%"         #'dired-mark-files-regexp
  "("         #'dired-mark-sexp
  "."         #'dired-mark-extension
  "O"         #'dired-mark-omitted
  "c"         #'dired-change-marks
  "s"         #'dired-mark-subdir-files
  "m"         #'dired-mark
  "u"         #'dired-unmark
  "?"         #'dired-unmark-all-files
  "!"         #'dired-unmark-all-marks
  " <delete>" #'dired-unmark-backward
  " C-n"      #'dired-next-marked-file
  " C-p"      #'dired-prev-marked-file
  "t"         #'dired-toggle-marks)

other

(general-def 'normal ranger-mode-map
  [remap read-only-mode]   #'dired-toggle-read-only
  [remap toggle-read-only] #'dired-toggle-read-only
  "<delete>"               #'dired-unmark-backward
  [remap undo]             #'dired-undo
  [remap advertised-undo]  #'dired-undo)

make sure that `;` uses `M-x`

(general-def 'normal ranger-mode-map
  ";" #'execute-extended-command)

entry

(use-package! ranger
  :commands deer ranger
  :setq
  (ranger-override-dired-mode . t)
  (ranger-cleanup-eagerly . t)
  (ranger-cleanup-on-disable . t)
  (ranger-omit-regexp . "^\.DS_Store$")
  (ranger-excluded-extensions . '("mkv" "iso" "mp4"))
  (ranger-deer-show-details . nil)
  (ranger-max-preview-size . 10)
  (ranger-modify-header . t)
  (ranger-hide-cursor . t)
  (ranger-dont-show-binary . t))

(setq image-dired-dir (concat VOID:DATA-DIR "image-dir"))
(setq dired-omit-verbose nil)

toggle dotfiles

There’s this wierd intermidiate stage between hidden and format called prefer in which only some files are hidden. That’s wierd, so I get rid of it.

(defadvice! ranger:toggle-dotfiles-a ()
  "Show/hide dot-files."
  :override ranger-toggle-dotfiles
  (interactive)
  (setq ranger-show-hidden
        (cl-case ranger-show-hidden
          (hidden 'format)
          (format 'hidden)))
  (ranger-setup))

silence window check

(defadvice! ranger:window-check-shutup-a (orig-fn &rest args)
  "Silence `ranger-window-check'."
  :around ranger-window-check
  (quiet! (apply orig-fn args)))

refresh

(defadvice! ranger:refresh-after-new-dir (&rest _)
  :after (mkdir dired-do-rename)
  (when (eq major-mode 'ranger)
    (ranger-refresh)))

dired icons

(use-package! all-the-icons-dired :hook ranger-mode-hook)

restart emacs

As it’s name suggests restart-emacs provides a function (called restart-emacs) that restarts emacs. I haven’t tested this in EXWM mode.

(use-package! restart-emacs :commands restart-emacs)

version control

transient

(use-package! transient
  :setq
  (transient-default-level . 5)
  (transient-levels-file   . (concat VOID:DATA-DIR "transient/levels"))
  (transient-values-file   . (concat VOID:DATA-DIR "transient/values"))
  (transient-history-file  . (concat VOID:DATA-DIR "transient/history")))

magit

(use-package! magit
  :commands magit-status magit-get-current-branch
  :idle-require f s with-editor git-commit package eieio lv transient
  :popup ("magit:"
          (display-buffer-at-bottom)
          (window-height . 0.5))
  :bind (:magit-status-mode-map
         ([remap magit-mode-bury-buffer] . magit/quit))
  :setq
  (magit-completing-read-function . #'magit-builtin-completing-read)
  (magit-revision-show-gravatars . '("^Author:     " . "^Commit:     "))
  (magit-diff-refine-hunk . t)
  (magit-auto-revert-mode . nil)
  :defer-config
  (add-hook 'magit-popup-mode-hook #'hide-mode-line-mode))

quitting

(defun magit/quit ()
  "Clean up magit buffers after quitting `magit-status'."
  (interactive)
  (let ((buffers (magit-mode-get-buffers)))
    (magit-restore-window-configuration)
    (mapc #'kill-buffer buffers)))

evil-magit

(use-package! evil-magit
  :before-call magit-status
  :defer-config
  (shut-up! (evil-magit-init))
  (setq evil-magit-state 'normal)
  (require 'evil-magit nil :no-error))

git-gutter

(use-package! git-gutter :commands git-gutter-mode)

server :built-in:

(when (display-graphic-p)
  (after! server
    (when-let* ((name (getenv "EMACS_SERVER_NAME")))
      (setq server-name name))
    (unless (server-running-p)
      (server-start))))

autorevert

(use-feature! autorevert
  :after-call switch-to-buffer find-file
  :setq
  (auto-revert-verbose . t)
  (auto-revert-use-notify . nil)
  (auto-revert-stop-on-user-input . nil)
  (revert-without-query . (list "."))
  :defer-config
  (defhook! auto-revert:buffer-h ()
    "Auto revert current buffer, if necessary."
    :hook void:after-switch-buffer-hook
    (unless (or (bound-and-true-p auto-revert-mode)
                (active-minibuffer-window))
      (auto-revert-handler)))

  (defhook! auto-revert:visible-buffers-h ()
    "Auto revert stale buffers in visible windows, if necessary."
    :hook (focus-in-hook after-save-hook)
    (--each (-uniq (mapcar #'window-buffer (window-list)))
      (with-current-buffer it (auto-revert:buffer-h)))))

security

pass

pass

(use-package! pass
  :commands pass
  :setq
  (pass-username-field . "username"))

get password

(defun pass/get-password ()
  "Copy password from entry into kill ring."
  (interactive)
  (require 'pass)
  (password-store-copy
   (completing-read "Copy password of entry: "
                    (password-store-list (password-store-dir))
                    nil
                    t)))

auth source pass

(use-package! auth-source-pass
  ;; (:after-hook pre-command-hook)
  :setq
  (auth-source-pass-filename . "~/.password-store")
  (auth-source-pass-port-separator . ":")
  :defer-config (auth-source-pass-enable))

epa

(use-feature! epa
  :setq
  (epg-gpg-program . "gpg2")
  (epa-pinentry-mode . 'loopback))

password-generator

I’m sure that pass can generate custom passwords with some options or other, but I do not like dealing with the command line. I want real elisp code please.

(use-package! password-generator
  :commands password-generator-simple password-generator-paranoid)

uuidgen

(use-package! uuidgen)

xr

This package is the inverse of rx. It takes a regular expression and returns the rx representation.

(use-package! xr
  ;; :functions xr xr-pp
  )

pdf-tools

pdf-tools

(use-package! pdf-tools
  :magic ("%PDF" . pdf-view-mode)
  :mode ("\\.[pP][dD][fF]\\'" . pdf-view-mode)
  :bind (:pdf-view-mode-map
         ("j" . pdf-view-next-line-or-next-page)
         ("k" . pdf-view-previous-line-or-previous-page)))

epd-pdf-info-program

(defadvice! pdf-tools:build-pdf-info-program-a ()
  "Build the pdf-info program if it hasn't already been built."
  :before pdf-view-mode
  (unless (file-executable-p pdf-info-epdfinfo-program)
    (let ((wconf (current-window-configuration)))
      (pdf-tools-install)
      (message "Building epdfinfo, this will take a moment...")
      (--each (buffer-list)
        (with-current-buffer it
          (when (eq major-mode 'pdf-view-mode)
            (fundamental-mode))))
      (while compilation-in-progress
        ;; Block until `pdf-tools-install' is done
        (redisplay)
        (sleep-for 1))
      ;; HACK If pdf-tools was loaded by you opening a pdf file, once
      ;;      `pdf-tools-install' completes, `pdf-view-mode' will throw an error
      ;;      because the compilation buffer is focused, not the pdf buffer.
      ;;      Therefore, it is imperative that the window config is restored.
      (when (file-executable-p pdf-info-epdfinfo-program)
        (set-window-configuration wconf)))))

bindings

(general-def 'normal pdf-view-mode-map
  "j" #'pdf-view-next-line-or-next-page
  "k" #'pdf-view-previous-line-or-previous-page
  "0" #'pdf-view-first-page
  "9" #'pdf-view-last-page
  "s" #'pdf-view-fit-width-to-window)

circe

(use-package! circe)

peristent scratch

(use-package! persistent-scratch
  :commands persistent-scratch-restore
  :setq (persistent-scratch-save-file . (concat VOID:DATA-DIR "scratch")))

alert

Notifications are very important. Messages from the *Messages* buffer are not enough.

(use-package! alert
  :setq
  (alert-default-style . 'libnotify)
  (alert-log-messages . t))

sudo-edit

Sometimes I’ll want edit files with root privileges. This package let’s you edit a file from another user (root by default). To use it you just call sudo-edit on the buffer you’d like to edit.

(use-package! sudo-edit :commands sudo-edit)

yadm

(defun void/dotfile-status ()
  (interactive)
  (require 'tramp)
  (add-to-list 'tramp-methods
               '("yadm"
                 (tramp-login-program "yadm")
                 (tramp-login-args (("enter")))
                 (tramp-login-env (("SHELL") ("/bin/sh")))
                 (tramp-remote-shell "/bin/sh")
                 (tramp-remote-shell-args ("-c"))))
  (magit-status "/yadm::"))

plantuml

(use-package! plantuml-mode
  :init
  (after! org
    (add-to-list 'org-src-lang-modes '("plantuml" . plantuml))
    (org-babel-do-load-languages 'org-babel-load-languages '((plantuml . t))))
  :setq
  (plantuml-executable-path . (executable-find "plantuml"))
  (plantuml-jar-path . "/usr/share/java/plantuml/plantuml.jar")
  (plantuml-default-exec-mode . 'jar)
  (org-plantuml-jar-path . "/usr/share/java/plantuml/plantuml.jar")
  (org-plantuml-executable-path . (executable-find "plantuml")))

Languages

lisp

sly

sly is an alternative to slime.

(use-package! sly
  :setq (inferior-lisp-program . "/usr/bin/sbcl"))

clojure

cider is a repl for clojure.

(use-package! cider :commands cider)

emacs lisp

printing

(setq eval-expression-print-length nil)
(setq eval-expression-print-level nil)

electric-pair

fix elisp indentation

A problem with elisp indentation is indents quoted lists the way functions should be indented. It has been discussed in at least three stackoverflow questions here, here and here. In all these questions the solutions have not been satisfactory. Some of them recommend using common-lisp-indent-function as the value of lisp-indent-function. This works for indenting a quoted list properly, but at the expense of changing the way that many other elisp forms are indented. Common Lisp’s indentation is different from Elisp’s. Others recommend using Fuco1’s lisp indent function hack. This also is not ideal. For one thing it only works for quoted lists with keywords but not generic symbols. Another thing is that the change should really be occurring in calculate-lisp-indent. calculate-lisp-indent is a function that returns what the indentation should be for the line at point. Since Fuco1 did not modify calculate-lisp-indent the wrong indentation still returned by this function and the modified lisp-indent-function just cleans up the mess. Better is just fixing the source of the problem. You can check out a more in-depth explanation looking at my reddit-post or looking at an answer I gave to this question.

(defadvice! void:calculate-lisp-indent-a (&optional parse-start)
  "Add better indentation for quoted and backquoted lists.
The change to this function."
  :override calculate-lisp-indent
  (defvar calculate-lisp-indent-last-sexp)
  (save-excursion
    (beginning-of-line)
    (let ((indent-point (point))
          state
          ;; setting this to a number inhibits calling hook
          (desired-indent nil)
          (retry t)
          calculate-lisp-indent-last-sexp containing-sexp)
      (cond ((or (markerp parse-start) (integerp parse-start))
             (goto-char parse-start))
            ((null parse-start) (beginning-of-defun))
            (t (setq state parse-start)))
      (unless state
        ;; Find outermost containing sexp
        (while (< (point) indent-point)
          (setq state (parse-partial-sexp (point) indent-point 0))))
      ;; Find innermost containing sexp
      (while (and retry
                  state
                  (> (elt state 0) 0))
        (setq retry nil)
        (setq calculate-lisp-indent-last-sexp (elt state 2))
        (setq containing-sexp (elt state 1))
        ;; Position following last unclosed open.
        (goto-char (1+ containing-sexp))
        ;; Is there a complete sexp since then?
        (if (and calculate-lisp-indent-last-sexp
                 (> calculate-lisp-indent-last-sexp (point)))
            ;; Yes, but is there a containing sexp after that?
            (let ((peek (parse-partial-sexp calculate-lisp-indent-last-sexp
                                            indent-point 0)))
              (if (setq retry (car (cdr peek))) (setq state peek)))))
      (if retry
          nil
        ;; Innermost containing sexp found
        (goto-char (1+ containing-sexp))
        (if (not calculate-lisp-indent-last-sexp)
            ;; indent-point immediately follows open paren.
            ;; Don't call hook.
            (setq desired-indent (current-column))
          ;; Find the start of first element of containing sexp.
          (parse-partial-sexp (point) calculate-lisp-indent-last-sexp 0 t)
          (cond ((looking-at "\\s(")
                 ;; First element of containing sexp is a list.
                 ;; Indent under that list.
                 )
                ((> (save-excursion (forward-line 1) (point))
                    calculate-lisp-indent-last-sexp)
                 ;; This is the first line to start within the containing sexp.
                 ;; It's almost certainly a function call.
                 (if (or
                      (= (point) calculate-lisp-indent-last-sexp)

                      (when-let (after (char-after (1+ containing-sexp)))
                        (char-equal after ?:))

                      (when-let (point (char-before containing-sexp))
                        (char-equal point ?'))

                      (let ((quoted-p nil)
                            (point nil)
                            (positions (nreverse (butlast (elt state 9)))))
                        (while (and positions (not quoted-p))
                          (setq point (pop positions))
                          (setq quoted-p
                                (or
                                 (and (char-before point)
                                      (char-equal (char-before point) ?'))
                                 (save-excursion
                                   (goto-char (1+ point))
                                   (looking-at-p "quote[\t\n\f\s]+(")))))
                        quoted-p))
                     ;; Containing sexp has nothing before this line
                     ;; except the first element.  Indent under that element.
                     nil
                   ;; Skip the first element, find start of second (the first
                   ;; argument of the function call) and indent under.
                   (progn (forward-sexp 1)
                          (parse-partial-sexp (point)
                                              calculate-lisp-indent-last-sexp
                                              0 t)))
                 (backward-prefix-chars))
                (t
                 ;; Indent beneath first sexp on same line as
                 ;; `calculate-lisp-indent-last-sexp'.  Again, it's
                 ;; almost certainly a function call.
                 (goto-char calculate-lisp-indent-last-sexp)
                 (beginning-of-line)
                 (parse-partial-sexp (point) calculate-lisp-indent-last-sexp
                                     0 t)
                 (backward-prefix-chars)))))
      ;; Point is at the point to indent under unless we are inside a string.
      ;; Call indentation hook except when overridden by lisp-indent-offset
      ;; or if the desired indentation has already been computed.
      (let ((normal-indent (current-column)))
        (cond ((elt state 3)
               ;; Inside a string, don't change indentation.
               nil)
              ((and (integerp lisp-indent-offset) containing-sexp)
               ;; Indent by constant offset
               (goto-char containing-sexp)
               (+ (current-column) lisp-indent-offset))
              ;; in this case calculate-lisp-indent-last-sexp is not nil
              (calculate-lisp-indent-last-sexp
               (or
                ;; try to align the parameters of a known function
                (and lisp-indent-function
                     (not retry)
                     (funcall lisp-indent-function indent-point state))
                ;; If the function has no special alignment
                ;; or it does not apply to this argument,
                ;; try to align a constant-symbol under the last
                ;; preceding constant symbol, if there is such one of
                ;; the last 2 preceding symbols, in the previous
                ;; uncommented line.
                (and (save-excursion
                       (goto-char indent-point)
                       (skip-chars-forward " \t")
                       (looking-at ":"))
                     ;; The last sexp may not be at the indentation
                     ;; where it begins, so find that one, instead.
                     (save-excursion
                       (goto-char calculate-lisp-indent-last-sexp)
                       ;; Handle prefix characters and whitespace
                       ;; following an open paren.  (Bug#1012)
                       (backward-prefix-chars)
                       (while (not (or (looking-back "^[ \t]*\\|([ \t]+"
                                                     (line-beginning-position))
                                       (and containing-sexp
                                            (>= (1+ containing-sexp) (point)))))
                         (forward-sexp -1)
                         (backward-prefix-chars))
                       (setq calculate-lisp-indent-last-sexp (point)))
                     (> calculate-lisp-indent-last-sexp
                        (save-excursion
                          (goto-char (1+ containing-sexp))
                          (parse-partial-sexp (point) calculate-lisp-indent-last-sexp 0 t)
                          (point)))
                     (let ((parse-sexp-ignore-comments t)
                           indent)
                       (goto-char calculate-lisp-indent-last-sexp)
                       (or (and (looking-at ":")
                                (setq indent (current-column)))
                           (and (< (line-beginning-position)
                                   (prog2 (backward-sexp) (point)))
                                (looking-at ":")
                                (setq indent (current-column))))
                       indent))
                ;; another symbols or constants not preceded by a constant
                ;; as defined above.
                normal-indent))
              ;; in this case calculate-lisp-indent-last-sexp is nil
              (desired-indent)
              (t
               normal-indent))))))

highlight-quoted

highlight-quoted highlights quotes, backticks and.

(use-package! highlight-quoted
  :hook emacs-lisp-mode-hook)

buttercup

buttercup is an emacs debugging suite.

(use-package! buttercup)

outorg

Outorg adds overlays to make an org buffer look more readable. I do not want these overlays.

(use-package! outorg
  ;; TODO: should be changed to `:functions'
  :commands outorg-convert-back-to-code outorg-convert-to-org)

(defadvice! outorg:do-not-add-overlays-a (orig-fn &rest args)
  :around outorg-wrap-source-in-block
  (cl-letf (((symbol-function #'overlay-put) #'ignore))
    (apply orig-fn args)))

outshine

outshine is a clever package that tries to make elisp mode more like org mode. It colors certain comments like org headings, and adds function for convertion from elisp to org. My void:init-file is written with outshine in mind.

(use-package! outshine
  :hook emacs-lisp-mode-hook
  :defer-config
  (general-def '(normal) emacs-lisp-mode-map
    "TAB" #'outline-toggle-children))

macrostep

macrostep

(use-package! macrostep
  :commands (macrostep-expand macrostep-collapse macrostep-collapse-all)
  :init (define-localleader-key!
          :infix "m"
          :keymaps 'emacs-lisp-mode-map
          "e" (list :def #'macrostep-expand :wk "expand")
          "c" (list :def #'macrostep-collapse :wk "collapse")
          "C" (list :def #'macrostep-collapse-all :wk "collapse all")))

hy

(use-package! hy-mode :mode "\\.hy\\'")

markdown

I’m adding markdown-mode so I can see README files.

(use-package! markdown-mode :mode "\\.md\\'")

org

Org mode introduces an elegant way of dealing with different languages in one file. In an org file the background language is Org’s own markup language that’s typically composed mostly of outline headlines. In the org markup language you can embed multiple different languages in [[][source blocks]]. Additionally, org mode provides a library of functions for dealing with these files. This includes things like executing (or evaluating) source blocks, moving headlines to other files, or even converting an org mode document into another format. As the name org suggests, org is tool that’s used for organization of data.

structures

todo-keywords

todo keywords

(after! org
  (setq org-todo-keywords
        '((sequence "TODO(t)" "PROJ(p)" "NEXT" "WAITING" "|" "DONE")
          (sequence "|" "DUPLICATE")
          (sequence "|" "CANCELLED"))))

return todo-keywords

Knowing what the exact todo-keywords are is important so that I know exactly when headline contents begin.

(defun org:todo-keywords ()
  "Return list of all TODO keywords."
  (--filter (and (stringp it) (not (string= "|" it)))
            (flatten-list org-todo-keywords)))

heading start

(defun org:heading-start-regexp ()
  "Compute regexp for heading start."
  (rx-to-string `(: bol (1+ "*") space (opt (or ,@(org:todo-keywords)) space))))

(defun org:heading-goto-start ()
  "Go to first letter of headline."
  (let (case-fold-search)
    (beginning-of-line)
    (re-search-forward (org:heading-start-regexp)
                       (line-end-position))))

return

(defun org/dwim-return ()
  "Do what I mean."
  (interactive)
  (cond
   (and (org-at-heading-p)
        (looking-at-p (rx (* (or "\s" "\t"))
                          (opt (1+ ":" (1+ letter)) ":") eol)))
   (org/insert-heading-below)
   (t
    (call-interactively #'org-return))))

scroll window to top

I need this function for some org actions. Evil has this as evil-scroll-line-to-top but I didn’t want to depend on evil.

(defun org:scroll-window-to-top ()
  (let ((line (line-number-at-pos (point)))
        (col (current-column)))
    (goto-char (point-min))
    (forward-line (1- line))
    (move-to-column col)))

fix nearby line adjustment

counsel-org-goto is lets you fuzzy search a term among org headings.

(defun org:prettify-nearby-headlines ()
  "Prettify display of nearby headlines."
  (save-excursion
    (while (org-up-heading-safe)
      (outline-show-children)))
  (outline-show-children)
  (let ((line (line-number-at-pos (point))))
    (goto-char (point-min))
    (forward-line (1- line)))
  (recenter (1- (max 1 scroll-margin)))
  (org-beginning-of-line))

helpers

org-heading-folded-p

(defun org:heading-folded-p ()
  "Return t if an current heading is folded."
  (outline-invisible-p (line-end-position)))

headline-name

(defun org:heading-name ()
  "Return the headline of the current heading."
  (interactive)
  (save-excursion
    (org-back-to-heading)
    (unless org-complex-heading-regexp
      (let ((major-mode 'org-mode))
        (org-set-regexps-and-options)))
    (looking-at org-complex-heading-regexp)
    (match-string 4)))

beginning-of-headline

(defun org:beginning-of-headline (&optional end)
  "Return the character position at the end of the headline."
  (let (case-fold-search)
    (save-excursion
      (org-back-to-heading)
      (looking-at org-complex-heading-regexp)
      (funcall (if end #'match-end #'match-beginning) 4))))

end-of-headline

(defun org:end-of-headline ()
  "Return the character position at the end of the headline."
  (interactive)
  (org:beginning-of-headline t))

heading

(defun org:heading-end-of-heading ()
  "Return point at end of heading.")

(defun org:heading-block-lang ()
  "Return the language of the current language's source block."
  (save-excursion
    (org-back-to-heading)
    (re-search-forward org-babel-src-block-regexp)))

preserve point

If possible org commands should preserve point. If this isn’t possible (ie. when deleting a subtree with), then should leave point at a place that is easy to predict and convenient (as opposed to a random location).

start on beginning of first heading

It looks nice if when I’m on a heading when I first enter an org file.

(defhook! org:goto-first-heading-h ()
  "Go to first heading when entering an org-mode file."
  :hook org-mode-hook
  (when (org-at-heading-p)
    (beginning-of-line)
    (org:heading-goto-start)))

fix bug with next visible heading

outline-next-visible-heading continues to EOB after reaching the last visible heading. It should just stop at the last visible heading. This advice checks to see if it’s gone farther than it should have and in that case goes back.

(defadvice! outline:dont-end-at-eob-a (orig-fn &rest args)
  "Fix bug where the next heading moves past last visible heading."
  :around outline-next-visible-heading
  (apply orig-fn args)
  (when (eobp) (apply #'outline-previous-visible-heading args)))

go to proper point after refile

(defadvice! org:end-at-start-of-headline-a (&rest _)
  "After running body end at headline start."
  :after org-refile org-cut-subtree org-copy-subtree org/jump-to-headline
  (when (org-at-heading-p) (org:heading-goto-start)))

commands

dwim

insert

(defun org/dwim-insert-elisp-block ()
  "Insert elisp block."
  (interactive)
  (save-excursion
    (unless (org-at-heading-p)
      (org-back-to-heading))
    (org-end-of-subtree)
    (goto-char (line-end-position))
    (insert (concat "\n\n"
                    "#+begin_src emacs-lisp"
                    "\n"
                    "#+end_src"))
    (forward-line -1)))

eval

(defun org/dwim-eval-block ()
  "Eval block contents."
  (interactive)
  (unless (org-at-heading-p)
    (user-error "Not in source block"))
  (save-window-excursion
    (org-babel-execute-subtree)))

next-line

(defun org/dwim-next-line (&optional backward)
  "Go to the start of the next heading.
If DIR is a negative integer, go the opposite direction: the start of the
  previous heading."
  (interactive)
  (outline-next-visible-heading (if backward -1 1))
  (when (org-at-heading-p)
    (org:heading-goto-start)))

previous-line

(defun org/dwim-previous-line (&optional forward)
  (interactive)
  (funcall #'org/dwim-next-line (not forward)))

up-heading

(defun org/dwim-up-heading ()
  ""
  (interactive)
  (condition-case nil
      (progn (outline-up-heading 1)
             (outline-hide-subtree)
             (outline-show-children)
             (org:heading-goto-start))
    (error
     (unless (outline-invisible-p (line-end-position))
       (outline-hide-subtree))
     (org:heading-goto-start))))

jump to heading

(defun org/avy-jump-to-heading ()
  "Jump to the beginning of a visible heading using `avy'."
  (interactive)
  (org-back-to-heading)
  (avy-jump (rx bol (1+ "*") space (group nonl))
            :beg (window-start)
            :end (window-end)
            :pred `(lambda () (/= (1+ ,(point)) (point)))
            :action (lambda (point) (goto-char point)
                      (org:heading-goto-start))
            :group 1))

dwim jump to heading

(defun org/dwim-jump-to-heading ()
  ""
  (interactive)
  (let ((origin (point)))
    (if (and (org/avy-jump-to-heading)
             (org:heading-folded-p))
        (progn (outline-toggle-children)
               (org:scroll-window-to-top))
      (goto-char origin))))

inserting

In my eyes, many Org functions are unnecessarily complicated and long. Often they need to perform a simple task (like inserting a heading) but lose their fundamental purpose in their inclusion of numerous obscure and opinionated options. For this reason I wrote my own insert heading functions.

newlines between headings

(defvar org:newlines-between-headings "\n\n"
  "Number of newlines between headings.")

heading above

(defun org/insert-heading-above (&optional below)
  "Insert a heading above the current heading."
  (interactive)
  (funcall #'org/insert-heading-below (not below)))

heading below

(defun org/insert-heading-below (&optional above)
  "Insert heading below."
  (interactive)
  (let* ((on-heading-p (ignore-errors (org-back-to-heading)))
         (newlines org:newlines-between-headings)
         (level (or (org-current-level) 1))
         (heading (concat (make-string level ?*) "\s")))
    (cond ((not on-heading-p)
           (insert heading))
          (above
           (goto-char (line-beginning-position))
           (insert heading)
           (save-excursion (insert newlines)))
          (t ; below
           (org-end-of-subtree)
           (insert (concat newlines heading))))
    (run-hooks 'org-insert-heading-hook)))

subheading

(defun org/insert-subheading ()
  "Insert subheading below current heading."
  (interactive)
  (org/insert-heading-below)
  (org-demote))

source blocks

Many of these org-src variables are not very applicable to me anymore because I use edit-indirect to edit source blocks.

(use-feature! org-src
  :setq
  (org-edit-src-persistent-message . nil)
  (org-src-window-setup . 'current-window)
  (org-src-fontify-natively . t)
  (org-src-ask-before-returning-to-edit-buffer . nil)
  (org-src-preserve-indentation . t)
  (org-src-tab-acts-natively . t)
  (org-confirm-babel-evaluate . nil)
  (org-babel-default-header-args . '((:session . "none")
                                     (:results . "silent")
                                     (:exports . "code")
                                     (:cache . "no")
                                     (:initeb . "no")
                                     (:hlines . "no")
                                     (:tangle . "yes"))))

org-mode

(use-package! org
  :idle-require
  calendar find-func format-spec org-macs org-compat org-faces org-entities
  org-list org-pcomplete org-src org-footnote org-macro ob org org-agenda
  org-capture
  :setq
  (org-directory . VOID:ORG-DIR)
  (org-archive-location . (concat org-directory "archive.org::"))
  (org-default-notes-file . (concat org-directory "notes.org"))
  (org-fontify-emphasized-text . t)
  (org-hide-emphasis-markers . t)
  (org-pretty-entities . t)
  (org-fontify-whole-heading-line . t)
  (org-fontify-done-headline . t)
  (org-fontify-quote-and-verse-blocks . t)
  (org-adapt-indentation . nil)
  (org-cycle-separator-lines . 2)
  (outline-blank-line . t)
  (org-enforce-todo-dependencies . t)
  (org-use-fast-tag-selection . nil)
  (org-tags-column . -80)
  (org-tag-alist . nil))

asthetic

To be honest, org mode has some pretty ugly syntax. The asterixes at the beginning of a heading are ugly, org block end and begin lines are ugly, property drawers are ugly. For a nice-looking, minimal, and non-distracting appearance all this needs to be improved.

visibility

hide lines

hide-lines is a package which, as its name suggests, hides certain lines. Specifically, it hides lines that match a regular expression you provide. You can reveal them with hide-lines-show-all.

hide lines

Particularly in boilerplate heavy languages like Org, hiding certain lines can make reading documents much easier by reducing visual distraction. This package though is in need of an update. It didn’t work out of the box (see hide-lines and hl overlay fix).

(use-package! hide-lines
  :commands hide-lines hide-lines-matching)

`hl` overlay fix

The line (overlay-put overlay 'invisible 'hl) in hide-lines-add-overlay wouldn’t work with the argument hl. It works when you set it to t instead. Maybe hl is depreciated.

(defadvice! hide:lines-fix-add-overlay-a (start end)
  "Add an overlay from `start' to `end' in the current buffer.
Push the overlay into `hide-lines-invisible-areas'."
  :override hide-lines-add-overlay
  (let ((overlay (make-overlay start end)))
    (setq hide-lines-invisible-areas (cons overlay hide-lines-invisible-areas))
    (overlay-put overlay 'invisible t)))

make sure all lines are hidden

When I tried hiding property drawers hide-lines-matching left out the start and end property lines. Only the property block body was hidden. This advice fixes this.

(defadvice! hide:lines-fix-hide-matching-a  (search-text)
  :override hide-lines-matching
  "Hide lines matching the specified regexp."
  (interactive "MHide lines matching regexp: ")
  (set (make-local-variable 'line-move-ignore-invisible) t)
  (save-excursion
    (goto-char (point-min))
    (while (re-search-forward search-text nil t)
      (hide-lines-add-overlay (match-beginning 0) (match-end 0)))))

toggle org properties

I want properties to exist–they are useful even if it’s just to store an ID. Yet, like most raw org syntax it looks ugly and takes up a lot of space. Unless I explicitly ask for properties I don’t want to see them.

(defun org/hide-property-drawers ()
  "Hide property drawers."
  (interactive)
  (let (selective-display-ellipses org-ellipsis)
    ;; If properties are folded, ellipsis will show.
    (org-show-all '(drawers))
    (hide-lines-matching (concat (s-chop-suffix "$" org-property-re) "\n"))))

toggle end source lines

(defun org/hide-source-block-delimiters ()
  "Hide property drawers."
  (interactive)
  (let (selective-display-ellipses org-ellipsis)
    ;; If properties are folded, ellipsis will show.
    (org-show-all)
    (hide-lines-matching (rx "#+" (or "begin" "end") "_src" (* nonl) "\n"))))

ensure that everything is folded

(setq-default org-startup-folded 'fold)

(defadvice! org:set-startup-visibility-h ()
  "Completely hide all text properties."
  :override org-set-startup-visibility
  ;; Hide property drawers on startup.
  (org/hide-property-drawers)
  (org-overview))

ensure headings are visible

Sometimes the heading inserted doesn’t remain visible.

(defhook! org:ensure-heading-visible-h ()
  "Ensure that heading remains visible."
  :hook org-insert-heading-hook
  (-when-let (o (cdr (get-char-property-and-overlay (point) 'invisible)))
    (move-overlay o (overlay-start o) (line-end-position 0))))

display children in window

(defun org:display-children-in-window ()
  "Scroll up window to maximize view of unfolded subtree.
If the subtree is unfolded and the end of the current subtree is outside of the
visible window, scroll up until the whole subtree is visible. If the whole
subtree can't fit on the visible window, only scroll up until the top of the
subtree is on the first line of the window (in other words, the beginning of
th subtree should always be visible)."
  (interactive)
  ;; Don't use `window-beg' and `window-end' because their values are
  ;; unreliable.
  (let ((subtree-beg
         (save-excursion (org-back-to-heading)
                         (line-beginning-position)))
        (subtree-end
         (save-excursion (org-end-of-subtree)
                         (line-end-position))))
    (save-excursion
      (while (and (pos-visible-in-window-p subtree-beg)
                  (not (pos-visible-in-window-p subtree-end)))
        (scroll-up 1))
      ;; Sometimes the line at the end is not fully visible. So I try to
      ;; scroll down an extra line.
      (unless (pos-visible-in-window-p subtree-beg)
        (scroll-down 1)))))

ensure children are visible

If I unfold a subtree and the end of the subtree is outside of the window and there’s space in the window above the subtree, scroll up as much as possible.

Note that I don’t use window-start and window-end because their values are unreliable. They update when redisplay is called; and for efficiency, I don’t want to call this function through every iteration of the loop. Instead I used pos-visible-in-window-p to tell me if a point is still in the visible window. In hindsight, using this function is even easier than using window-beg and window-end because it doesn’t require any math on my part.

(defadvice! org:ensure-children-visible-a ()
  "Ensure children are visible after toggling."
  :after outline-toggle-children
  (unless (org:heading-folded-p)
    (org:display-children-in-window)))

fancy priorities

org-fancy-priorities is a package that displays org priorities with an icon.

(use-package! org-fancy-priorities
  :hook org-mode-hook
  :setq
  (org-fancy-priorities-list . (list (all-the-icons-material "priority_high")
                                     (all-the-icons-octicon "arrow-up")
                                     (all-the-icons-octicon "arrow-down")
                                     (all-the-icons-material "low_priority"))))

org superstar

org-superstar is a an org-bullets remake redesigned from the ground up.

(use-package! org-superstar
  :hook org-mode-hook
  :pre-setq
  (org-superstar-headline-bullets-list . (list "◉" "○" "▷"))
  :setq
  (org-superstar-special-todo-items . t)
  (org-superstar-leading-bullet . ?\s))

links

To me links are one of the biggest drawing points to org-mode. The ability to have documentation that can link to websites, files, info docs and even github commits is too juicy to pass up. Why in the 21st century do we still have to deal with such weak, plain text code documentation when we could use a more powerful markup language?

ol

(use-feature! ol
  :after org
  :custom
  (org-link-descriptive . t)
  (org-link-use-indirect-buffer-for-internals . t))

custom link types

helpvar

helpvar I a new link type that when pressed, opens a help buffer from helpful if it’s installed, otherwise it defaults to bringing up an regular emacs help buffer.

(after! org
  (defun ol:helpvar-face (link)
    (if (boundp (intern link)) 'org-link 'error))

  (defun ol:helpvar-follow (link)
    (let ((var (intern link)))
      (if (require 'helpful nil :noerror)
          (helpful-variable var)
        (describe-variable var))))

  (org-link-set-parameters "helpvar" :face #'ol:helpvar:face :follow #'ol:helpvar:follow))

helpfn

helpfn is the same as helpvar except with functions.

(after! org
  (defun ol:helpfn-face (link)
    (let ((fn (intern link)))
      (if (fboundp fn) 'org-link 'error)))

  (defun ol:helpfn-follow (link)
    (let ((fn (intern link)))
      (if (require 'helpful nil :no-error)
          (helpful-callable fn)
        (describe-function fn))))

  (org-link-set-parameters "helpfn" :face #'ol:helpfn-face :follow #'ol:helpfn-follow))

toggle link display

(general-def
  (:localleader "t")
  (:map org-mode-map)
  ("l" #'org-toggle-link-display)
  ("p" #'org/toggle-property-drawer-display))

org capture

Ever been in the middle of doing something when a thought in your head pops up about some thing else? You can stop what you’re doing but then you lose focus. You can resolve to make note of it later but then you might forget. Capturing is designed to confront this problem. While in the middle of a task you can quickly jump into a small org buffer and write down an idea that you have, then close it.

org capture

(use-feature! org-capture
  :after org
  :commands org-capture)

completing read for templates

The default Org capture templates use this ido-like popup for selecting capture templates. They shouldn’t have made this popup. Org should have just left this for completing read. Fortunately, there’s a package that provides a completing-read-using replacement for org-capture called counsel-org-capture-string.

(use-package! counsel-org-capture-string
  :after org ivy
  :commands counsel-org-capture-string)

remove capture headerline

This was the answer to my question. I need to disable org-capture's header-line.

(defhook! org:capture-turn-off-header-line-h ()
  "Turn of the header line message."
  :hook org-capture-mode-hook
  (setq-local header-line-format nil))

doct

doct is a package designed to ease writing and understanding capture templates by allowing you to write them in a declarative style (see [[][doct docstring]]). In org mode, capture templates are [[][represented as plain lists]]. This makes it easy to forget what a certain element meant or to accidentally omit a capture template element as you’re writing it.

(use-package! doct
  :after org-capture
  :require t
  :config
  ;; (require 'doct)
  ;; doct just returns the new template.
  (defadvice! doct:add-to-capture-templates (orig-fn &rest args)
    "Automatically add the template to capture templates."
    :around doct
    (alet (apply orig-fn args)
      (prepend! org-capture-templates it))))

capture templates

emacs

(after! org-capture
  (doct (list "Emacs"
              :keys "e"
              :file (lambda nil (concat VOID:ORG-DIR "todo.org"))
              :prepend t
              :empty-lines 1
              :ID (lambda () (require 'uuidgen) (uuidgen-4))
              :template '("* %{todo-state} %?"
                          ":PROPERTIES:"
                          ":ID: %{ID}"
                          ":CREATED: %U"
                          ":END:")
              :children
              '(("Todo" :keys "1" :todo-state "TODO")
                ("Bug" :keys "2" :todo-state "BUG")))))

notes

Sometimes there are things I want to capture that’s not a TODO, but more like information I don’t want to forget or that I feel like I might need to reference in the future. I use this template for this.

(after! org-capture
  (doct (list "Notes"
              :keys "n"
              :file (lambda nil (concat VOID:ORG-DIR "notes.org"))
              :prepend t
              :empty-lines 1
              :ID (lambda () (require 'uuidgen) (uuidgen-4))
              :template '("* %?"
                          ":PROPERTIES:"
                          ":ID: %{ID}"
                          ":CREATED: %U"
                          ":END:"))))

org agenda

org-agenda-list is the function that actually takes you to the agenda for the current week.

(use-feature! org-agenda
  :after org
  :commands (org-agenda org-agenda-list)
  :setq
  (org-agenda-files . (mapcar (lambda (it) (concat org-directory it))
                               '("todo.org")))
  (org-agenda-start-on-weekday . 0)
  (org-agenda-timegrid-use-ampm . nil)
  (org-agenda-skip-unavailable-files . nil)
  (org-agenda-time-leading-zero . t)
  (org-agenda-text-search-extra-files . '(agenda-archives))
  (org-agenda-dim-blocked-tasks . nil)
  (org-agenda-inhibit-startup . t))

org refile

(use-feature! org-refile
  :after org
  :setq
  (org-refile-targets . `((,VOID:README-FILE . (:maxlevel . 10))
                          (,VOID:TODO-FILE . (:maxlevel . 1))))
  (org-refile-use-outline-path . 'file)
  (org-refile-allow-creating-parent-nodes . t)
  (org-reverse-note-order . t)
  (org-outline-path-complete-in-steps . nil))

org id

org-id is a built-in package that creates that provides tools for creating and storing universally unique IDs. This is primarily used to disguish and referenance org headlines.

(use-feature! org-id
  :commands org-id-get-create
  :setq
  (org-id-locations-file . (concat VOID:DATA-DIR "org-id-locations"))
  ;; Global ID state means we can have ID links anywhere. This is required for
  ;; `org-brain', however.
  (org-id-locations-file-relative . t)
  :hook (org-insert-heading-hook . org-id-get-create))

org clock

org-clock is a built-in package that provides time logging functions for tracking the time you spend on a particular task.

(use-feature! org-clock
  :commands org-clock-in
  ;; :before-call ((org-clock-in org-clock-out org-clock-in-last org-clock-goto org-clock-cancel) . (org-clock-load))
  :hook (kill-emacs-hook . org-clock-save)
  :setq
  ;; org-clock-sound
  ;; org-show-notification-handler
  (org-clock-persist . 'history)
  (org-clock-persist-file . (concat VOID:DATA-DIR "org-clock-save.el"))
  ;; Resume when clocking into task with open clock
  (org-clock-in-resume . t)
  :config
  ;; set up hooks for persistence.
  (org-clock-persistence-insinuate))

org crypt

(use-feature! org-crypt
  :commands org-encrypt-entries org-encrypt-entry org-decrypt-entries org-decrypt-entry
  :hook (org-reveal-start . org-decrypt-entry)
  ;; :preface
  ;; ;; org-crypt falls back to CRYPTKEY property then `epa-file-encrypt-to', which
  ;; ;; is a better default than the empty string `org-crypt-key' defaults to.
  ;; (defvar org-crypt-key nil)
  ;; (after! org
  ;;   (add-to-list 'org-tags-exclude-from-inheritance "crypt")
  ;;   (add-hook! 'org-mode-hook
  ;;              (add-hook 'before-save-hook 'org-encrypt-entries nil t)))
  )

org-journal

org-journal is a package that provides functions to maintain a simple diary/journal using org-mode.

(use-package! org-journal
  :commands org-journal-new-entry
  :setq
  (org-journal-file-type . 'yearly)
  (org-journal-dir . (concat VOID:ORG-DIR "journal/"))
  (org-journal-find-file . 'find-file))

keybindings

narrowing and widening

(general-def
  (:localleader "n")
  (:map org-mode-map)
  (:wk "Narrow" "" nil)
  (:wk "To Element" :n "e" #'org-narrow-to-element)
  (:wk "To Block"   :n "b" #'org-narrow-to-block)
  (:wk "To Subtree" :n "s" #'org-narrow-to-subtree)
  (:wk "Widen"      :n "w" #'widen))

replace evil folding commands to outline folding

By default evil binds za to evil-open-folds and zb to evil-close-folds. They do work in org-mode but I’d rather use the folding commands provided by outline.el. The outline api actually seems pretty solid; better coded and simpler than the org api it seems.

;; (general-def
;;   (:leader "z")
;;   (:n "a" #'outline-show-all)
;;   (:n "m" #'outline:hide-all-sublevels))

(general-def 'normal org-mode-map
  [tab] #'outline-toggle-children
  "TAB" #'outline-toggle-children)

(defun outline:hide-all-sublevels ()
  (interactive)
  (outline-hide-sublevels 1))

(general-def 'normal org-mode-map
  "j" #'org/dwim-next-line
  "k" #'org/dwim-previous-line
  "b" #'org/dwim-insert-elisp-block
  "o" #'org/insert-heading-below
  "O" #'org/insert-heading-above
  "l" #'org-do-demote
  "h" #'org-promote-subtree
  "L" #'org-demote-subtree
  "t" #'org-set-tags-command
  "r" #'org-capture
  "s" #'org-schedule
  "S" #'org-deadline
  "R" #'org-refile
  "T" #'org-todo
  "D" #'org-cut-subtree
  "Y" #'org-copy-subtree
  "K" #'org-metaup
  "J" #'org-metadown)

lua

(use-package! lua-mode :mode "\\.lua\\'")

cpp

modern font lock

(use-package! modern-cpp-font-lock
  :hook (c++-mode-hook . modern-c++-font-lock-mode))

demangle

(use-package! demangle-mode
  :hook llvm-mode-hook)

latex

tex

(use-feature! tex
  :mode ("\\.tex\\'" . LaTeX-mode)
  :hook (LaTex-mode-hook . visual-line-mode)
  :setq
  (TeX-parse-self . t)
  (TeX-auto-save . t)
  ;; use hidden dirs for auctex files
  (TeX-auto-local . ".auctex-auto")
  (TeX-style-local . ".auctex-style")
  (TeX-source-correlate-mode . t)
  (TeX-source-correlate-method . 'synctex)
  ;; don't start the emacs server when correlating sources
  (TeX-source-correlate-start-server . nil)
  ;; automatically insert braces after sub/superscript in math mode
  (TeX-electric-sub-and-superscript . t))

auctex

(use-package! auctex)

adaptive wrap

(use-package! adaptive-wrap
  :hook (LaTeX-mode . adaptive-wrap-prefix-mode)
  :setq-default (adaptive-wrap-extra-indent . 0))

preview pane

(use-package! latex-preview-pane)

User Interface

hydra

Using emacs you’ll enavitably encounter many keybindings. Muscle memory is good but often it can be useful to able to also see the keybindings.

pretty hydra

(use-package! pretty-hydra)

pretty hydra title

I got this from centaur emacs.

(cl-defun pretty-hydra-title (title &optional icon-type icon-name
                                    &key face height v-adjust)
  "Add an icon in the hydra title."
  (let ((face (or face `(:foreground ,(face-background 'highlight))))
        (height (or height 1.0))
        (v-adjust (or v-adjust 0.0)))
    (concat
     (when (and (icons-displayable-p) icon-type icon-name)
       (let ((f (intern (format "all-the-icons-%s" icon-type))))
         (when (fboundp f)
           (concat
            (apply f (list icon-name :face face :height height :v-adjust v-adjust))
            " "))))
     (propertize title 'face face))))

toggle

(pretty-hydra-define hydra:toggle (:title (pretty-hydra-title "Toggles" 'faicon "toggle-on")
                                   :color amaranth :quit-key "q")
  ("No Title"
   (("l" display-line-numbers "line-numbers")
    ("c" caps-lock "caps-lock")
    ("d" debug-on-error "debug"))
   "Other"
   (("f" void/set-font "font face")
    ("L" org-toggle-link-display "link display")
    ("s" void/set-font-size "font size"))))

theme

(pretty-hydra-define hydra:theme (:title (pretty-hydra-title "Themes" 'faicon "paint-brush")
                                  :color amaranth :quit-key "q")
  ("Traverse"
   (("j" theme-looper-enable-next-theme "next")
    ("k" theme-looper-enable-previous-theme "previous"))
   "Favorites"
   (("f" theme-looper/add-current-theme-to-favorites "favorites")
    ("f" theme-looper/add-current-theme-to-ignored "ignore"))
   "Random"
   (;; ("d" theme-looper/enable-random-dark-theme "dark")
    ;; ("l" theme-looper/enable-random-light-theme "light")
    ("r" theme-looper-enable-random-theme "random")
    ("I" theme-looper/enable-random-ignored-theme "ignored")
    ("F" theme-looper/enable-random-favorite-theme "favorite"))
   "circadian"
   (("t" circadian/set-current-theme-for-time "display at particular time"))))

window

(pretty-hydra-define hydra:window (:title (pretty-hydra-title "Windows" 'faicon "windows")
                                   :color amaranth
                                   :quit-key "q")
  ("Traverse"
   (("h" windmove-left "move left")
    ("j" windmove-down "move down")
    ("k" windmove-up "move up")
    ("l" windmove-right "move right"))
   "Resize"
   (("M" maximize-window "maximize")
    ("m" minimize-window "minimize")
    ("b" balance-windows "balance"))
   "Split"
   (("s" split-window-horizontally "horizontally")
    ("v" split-window-vertically "vertically"))
   "Transpose"
   (("t" transpose-frame "vertically")
    ("v" transpose- "horizontally"))
   "Actions"
   (("a" ace-select-window "select")
    ("w" ace-swap-window "swap")
    ("d" delete-window "delete")
    ("D" delete-other-windows "delete others"))
   "Zoom"
   (("z" zoom-in "zoom-in")
    ("Z" zoom-out "zoom-out"))))

help

(pretty-hydra-define hydra:help (:title (pretty-hydra-title "Help" 'material "help")
                                 :color amaranth :quit-key "q")
  ("Describe"
   (("v" describe-variable "variable")
    ("f" describe-function "function")
    ("k" describe-key "key"))
   "Apropos"
   (("a" apropos "apropos")
    ("V" apropos-variable "variable"))))

packages

(pretty-hydra-define hydra:packages (:title (pretty-hydra-title "Packages" 'octicon "package")
                                     :color pink :quit-key "q")
  ("Installation"
   (("i" package-install "install")
    ("c" remove "remove")
    ("l" paradox "debug"))
   ""
   (("f" #'paradox-list-packages "font face")
    ("L" org-toggle-link-display "link display")
    ("s" void/set-font-size "font size"))))

quit

(pretty-hydra-define hydra:quit (:title (pretty-hydra-title "quit" 'faicon "power-off")
                                 :color amaranth :quit-key "q")
  ("Emacs"
   (("q" evil-quit-all "next")
    ("s" void/quit-emacs-no-prompt "with no prompt")
    ("Q" evil-save-and-quit "and save")
    ("D" void/kill-emacs-no-hook "with no hook")
    ("Q" void/kill-emacs-brutally "brutally"))
   "Restart"
   (("r" restart-emacs "and restart"))
   "Processes"
   (("p" void/kill-emacs-processes "favorites"))))

app

(pretty-hydra-define hydra:app (:title (pretty-hydra-title "Apps" 'faicon "")
                                :color amaranth :quit-key "q")
  ("Browsers"
   (("f" firefox "next")
    ("q" qutebrowser "with no hook")
    ("n" next "random"))
   "Processes"
   (("p" void/kill-emacs-processes "favorites"))))

help and documentation

helpful

helpful provides a complete replacement for the built-in Emacs help facility which provides much more contextual information in a better format.

(use-package! helpful
  :ignore-buffers ("\\*Help.*")
  :popup
  ("\\*Help.*"
   (display-buffer-at-bottom)
   (window-width . 0.50)
   (side . bottom)
   (slot . 4))
  :bind
  ([remap describe-function] . helpful-callable)
  ([remap describe-command]  . helpful-command)
  ([remap describe-variable] . helpful-variable)
  ([remap describe-key]      . helpful-key))

elisp demos

This package improves help further by allowing you to add examples on how to use a function or macro. It seems simple but having examples can really ease the understanding of a verbally terse and dry command description.

(use-package! elisp-demos
  ;; :functions elisp-demos-advice-helpful-update
  :advice (:after helpful-update elisp-demos-advice-helpful-update)
  :commands elisp-demos-add-demo)

Asthetic

It’s easy to underestimate how much of a difference having an asthetically pleasing Emacs configuration can have. Ugliness really can take its toll.

which-key

Emacs is full of so many keybindings, that it can be difficult to keep track of them. Especially when you’re starting out, but even when you’re an Emacs-pro, it’s easy to forget what a particular functionality is bound to. Typically, you’ll remember the first few key strokes but struggle with the rest. To address this which-key displays key binding sequences in the minibuffer as your typing them ([[][]] and [[][]] are screenshots of this in action). By doing this you can “discover” the commands as you go along.

(use-package! which-key
  :hook emacs-startup-hook
  :setq
  (which-key-sort-uppercase-first . nil)
  (which-key-max-display-columns . nil)
  (which-key-add-column-padding . 1)
  (which-key-min-display-lines . 6)
  (which-key-side-window-slot . -10)
  (which-key-sort-order . #'which-key-prefix-then-key-order)
  (which-key-popup-type . 'minibuffer)
  :config
  (which-key-mode)
  (defhook! which:key-set-line-spacing-h ()
    :hook which-key-init-buffer-hook
    (setq line-spacing 3))
  (which-key-add-key-based-replacements void:leader-key "<leader>")
  (which-key-add-key-based-replacements void:localleader-key "<localleader>"))

dashboard

dashboard is an extensible emacs startup screen. I love the idea of dashboard: having an extensible, fast, nice-looking dashboard when starting emacs is nice. It’s not only nice asthetically, it’s also strategic too. First, you can use it as a launching point to get to your tasks quicker. And second, it doesn’t require any expensive modes. I’ve often been starting out with the scratch buffer and I’ve wanted to have the scratch buffer start off with emacs-lisp-mode, but I don’t want it to trigger company, yasnippet, etc. on startup. If I start my emacs with dashboard I can avoid this.

dashboard

(use-package! dashboard
  :require t
  :hook (window-setup-hook . dashboard-insert-startupify-lists)
  :setq
  (dashboard-items . nil)
  (dashboard-startup-banner . 2)
  (dashboard-center-content . t)
  (initial-buffer-choice . (lambda () (get-buffer-create dashboard-buffer-name))))

dashboard-init-info

void:init-time is more accurate than dashboard’s init time measure. So I use it instead.

(defadvice! dashboard:set-init-info-a (&rest _)
  :before dashboard-insert-startupify-lists
  (setq dashboard-init-info
        (format "%d packages loaded in %.2f seconds"
                (cond ((featurep 'straight)
                       (hash-table-size straight--profile-cache))
                      ((featurep 'package) (length package-activated-list))
                      (t 0))
                (string-to-number (emacs-init-time)))))

banner path

(defadvice! dashboard:custom-banner-path-a (&rest _)
  "Use the Void text banner."
  :override dashboard-get-banner-path
  (concat VOID:LOCAL-DIR "void-banner.txt"))

navigator buttons

navigator button

This is a convenience macro that allows navigation buttons to be defined declaratively and with a “defun-like” syntax.

(defmacro dashboard:define-naviator-button! (name args description &rest body)
  "Define a dashboard navigator button."
  (declare (indent defun))
  (let ((dashboard-fn dashboard:name-button)
        ((&plist ))
        ((&plist ) icon))
    `(alet (list ()
                 ,name
                 ,description
                 #',dashboard-fn)
       (push it dashboard-navigator-buttons))))

github link

(dashboard:define-naviator-button! Homepage ()
  "Browse Homepage."
  :icon "mark-github"
  (browse-url "https://github.com/Luis-Henriquez-Perez/dotfiles"))

go to readme

(dashboard:define-naviator-button! README ()
  "Go to README."
  :icon "eye"
  :type faicon
  (browse-url "https://github.com/Luis-Henriquez-Perez/dotfiles"))

hide-mode-line

hide-mode-line is another package that does exactly what it’s name says: hide the mode line.

(use-package! hide-mode-line
  :hook Man-mode completion-list-mode)

all-the-icons

A little bit of decoration and spice can go a long way. As its name suggests, all-the-icons is a package that contains a lot of icons ([[][here]] you can see a few). In practice I use these icons to (1) make things look nicer and more colorful and (2) enhance readability of plain text.

install all the icons if not installed

This will install the icons if they’re not already installed. Unless somehow the fonts are deleted, this code should only take effect the first time installing void. This helps achieve the goal to automate as much as possible on a fresh VOID install. For writing this code I referenced the body of all-the-icons-install-fonts.

(let ((font-dir
       (cl-case window-system
         (x (concat (or (getenv "XDG_DATA_HOME")
                        (concat (getenv "HOME") "/.local/share"))
                    "/fonts/"))
         (mac (concat (getenv "HOME") "/Library/Fonts/" ))
         (ns (concat (getenv "HOME") "/Library/Fonts/" )))))
  (unless (--all-p (file-exists-p (concat font-dir it))
                   '("all-the-icons.ttf"
                     "file-icons.ttf"
                     "fontawesome.ttf"
                     "material-design-icons.ttf"
                     "octicons.ttf"
                     "weathericons.ttf"))
    (void:log "No icons installed. Installing...")
    (all-the-icons-install-fonts :ignore-prompt)))

boostrap

(use-package! all-the-icons
  :commands (all-the-icons-octicon
             all-the-icons-faicon
             all-the-icons-fileicon
             all-the-icons-wicon
             all-the-icons-material
             all-the-icons-alltheicon))

disable in tty

In terminals these icons will not display correctly. I usually use emacs as a graphical interface but.

(defadvice! void:disable-all-the-icons-in-tty-a (orig-fn &rest args)
  "Disable icons in tty."
  :around (all-the-icons-octicon
           all-the-icons-material
           all-the-icons-faicon
           all-the-icons-fileicon
           all-the-icons-wicon
           all-the-icons-alltheicon)
  (if (display-graphic-p) (apply orig-fn args) ""))

themes

themes

(use-package! humanoid-themes
  :pre-setq (humanoid-org-bold . nil))

(use-package! spacemacs-theme
  :pre-setq
  (spacemacs-theme-org-bold . nil)
  (spacemacs-theme-comment-italic . t)
  (spacemacs-theme-org-bold . nil)
  (spacemacs-theme-org-height . nil))

(use-package! tao-theme)

(use-package! one-themes
  :setq (emacs-one-use-variable-pitch . nil))

(use-package! avk-emacs-themes)

(use-package! hemera-theme)

circadian

circadian manages the loading of themes at certain time.

(use-package! circadian)

Keybindings

general

This heading is dedicated to general keybinding decisions I make.

execute extended command

One of the most common–if not the most common–command you use in Emacs is execute-extended-command. This command let’s you search any other command and upon pressing enter, then you execute the command. The fact that this command is invoked so frequently demands it have one of the shortest, easiest to press bindings. I chose to give it SPC SPC and ;. SPC SPC is short and quick to type as well as consistent with other SPC bindings. While ; is super fast to press as well and even faster than SPC SPC.

(define-leader-key! "SPC" (list :def #'execute-extended-command :wk "M-x"))

(general-def
  "A-x" #'execute-extended-command
  "M-x" #'execute-extended-command)

(general-def 'normal ";" #'execute-extended-command
  "q" #'delete-window)

scrolling pages

I scroll pages all the time. The default binding for scrolling pages in evil are C-j to scroll down and C-k to scroll up. These chords are too much for such common commands however, so I bound them to J and K respectively.

(general-def 'normal
  "K" #'evil-scroll-page-up
  "J" #'evil-scroll-page-down)

increasing text scale

As someone who spends much of his day on the computer.

(general-def '(emacs normal)
  "M--" #'text-scale-decrease
  "M-=" #'text-scale-increase)

windows

Efficient window management in Emacs crucial for success. These keys all pertain to window/workspace actions.

(define-leader-key!
  :infix "w"
  ""  (list :ignore nil                              :wk "window")
  "w" (list :def #'display-buffer :wk "display buffer")
  "o" (list :def #'other-window                      :wk "other window")
  "S" (list :def #'void/window-split-below-and-focus :wk "split below and focus")
  "V" (list :def #'void/window-split-right-and-focus :wk "split right and focus")
  "s" (list :def #'split-window-below                :wk "split below")
  "v" (list :def #'split-window-right                :wk "split right")
  "M" (list :def #'maximize-window                   :wk "maximize")
  "m" (list :def #'minimize-window                   :wk "minimize")
  "b" (list :def #'balance-windows                   :wk "move left")
  "d" (list :def #'delete-window                     :wk "delete current")
  "D" (list :def #'delete-other-windows              :wk "delete others")
  "h" (list :def #'windmove-left                     :wk "move left")
  "j" (list :def #'windmove-down                     :wk "move down")
  "k" (list :def #'windmove-up                       :wk "move up")
  "l" (list :def #'windmove-right                    :wk "move right")
  "x" (list :def #'ace-swap-window                   :wk "swap windows")
  "t" (list :def #'transpose-frame                   :wk "transpose")
  "n" (list :def #'eyebrowse-create-window-config    :wk "save window config")
  "J" (list :def #'eyebrowse-next-window-config      :wk "next window config")
  "K" (list :def #'eyebrowse-prev-window-config      :wk "prev window config"))

buffer

In emacs, we change the buffer a window’s displaying pretty often. That’s why efficient buffer navigation is a must. There are particular buffers which I visit so often that it’s worth having keybindings just for them.

(define-leader-key!
  :infix "b"
  ""  (list :def nil                            :wk "buffer")
  "e" (list :def #'buffer-expose                :wk "expose")
  "p" (list :def #'previous-buffer              :wk "previous")
  "n" (list :def #'next-buffer                  :wk "next")
  "s" (list :def #'switch-to-buffer             :wk "switch")
  "b" (list :def #'switch-to-buffer             :wk "display")
  "d" (list :def #'display-buffer               :wk "display")
  "t" (list :def #'void/switch-to-todo-file     :wk "Void TODO")
  "S" (list :def #'void/open-scratch            :wk "*scratch*")
  "i" (list :def #'void/switch-to-init-org-file :wk "fallback")
  "I" (list :def #'void/switch-to-main-elisp    :wk "main.el")
  "m" (list :def #'void/switch-to-main-org-file :wk "Void README")
  "M" (list :def #'void/switch-to-messages      :wk "*messages*"))

(define-leader-key!
  :infix "b k"
  ""  (list :ignore t             :wk "kill")
  "c" (list #'kill-current-buffer :wk "current"))

app

These keybindings are for opening particular apps. When I’m testing Void I like to open another emacs instance.

(define-leader-key!
  :infix "a"
  ""  (list :ignore t                       :wk "app")
  "a" (list :def #'counsel-linux-app :wk "open app")
  "E" (list :def #'elfeed                   :wk "elfeed")
  "d" (list :def #'deer                     :wk "deer")
  "r" (list :def #'ranger                   :wk "ranger")
  "e" (list :def #'void/open-emacs-instance :wk "emacs")
  "q" (list :def #'void/open-qutebrowser    :wk "qutebrowser")
  "q" (list :def #'void/open-next           :wk "next")
  "w" (list :def #'w3m                      :wk "w3m")
  "c" (list :def #'org-capture              :wk "capture"))

file

(define-leader-key!
  :infix "f"
  ""  (list :ignore t          :wk "file")
  "S" (list :def #'sudo-edit   :wk "sudo")
  "s" (list :def #'save-buffer :wk "save buffer")
  "f" (list :def #'find-file   :wk "find file")
  "r" (list :def #'ranger      :wk "ranger")
  "d" (list :def #'deer        :wk "deer"))

eval

(define-leader-key!
  :infix "e"
  ""  (list :ignore t                   :wk "eval")
  "r" (list :def #'eval-region          :wk "region")
  "d" (list :def #'eval-defun           :wk "defun")
  "l" (list :def #'eval-print-last-sexp :wk "sexp")
  "b" (list :def #'eval-buffer          :wk "buffer"))

code

These bindings are for generally working with code.

(define-leader-key!
  :infix "c"
  ""  (list :ignore t                                   :wk "code")
  "a" (list :def #'ialign                               :wk "align")
  "l" (list :def #'lispyville-comment-or-uncomment-line :wk "toggle comment")
  "y" (list :def #'lispyvile-comment-and-cone-dwim      :wk "copy comment"))

toggle

(define-leader-key!
  :infix "t"
  ""  (list :ignore t                    :wk "toggle/set")
  "r" (list :def #'read-only-mode        :wk "read-only")
  "t" (list :def #'load-theme            :wk "load theme")
  "c" (list :def #'caps-lock-mode        :wk "caps lock")
  "d" (list :def #'toggle-debug-on-error :wk "debug")
  "F" (list :def #'void/set-font         :wk "set font")
  "f" (list :def #'void/set-font-size    :wk "font size"))

(define-leader-key!
  :infix "t"
  :keymaps 'org-mode-map
  "l" (list :def #'org-toggle-link-display :wk "link display"))

help

There’s a lot of documentation finding and information searching involved in Emacs and for that we need all the help we can get.

(define-leader-key!
  :infix "h"
  ""  (list :ignore t                      :wk "help")
  "h" (list :def #'describe-function       :wk "function")
  "v" (list :def #'describe-variable       :wk "variable")
  "c" (list :def #'describe-char           :wk "char")
  "k" (list :def #'describe-key            :wk "key")
  "f" (list :def #'describe-function       :wk "function")
  "l" (list :def #'global-command-log-mode :wk "command log")
  "a" (list :def #'apropos                 :wk "apropos"))

quit

There’s many ways to quit Emacs. Sometimes I’d like to save all the buffers I had been working on. Sometimes, when I’m testing something and I mess up kill-emacs-hook I want Emacs to just quit even if it means ignoring that hook. Most of the time, I know what I’m doing when I quit Emacs, so I don’t want a prompt asking me if I’m sure.

(define-leader-key!
  :infix "q"
  ""  (list :ignore t                        :wk "quit")
  "q" (list :def #'evil-quit-all             :wk "normally")
  "s" (list :def #'void/quit-emacs-no-prompt :wk "with no prompt")
  "Q" (list :def #'evil-save-and-quit        :wk "and save")
  "x" (list :def #'void/kill-emacs-no-hook   :wk "with no hook")
  "e" (list :def #'void/kill-emacs-processes :wk "emacs processes")
  "b" (list :def #'void/kill-emacs-brutally  :wk "brutally")
  "r" (list :def #'restart-emacs             :wk "and restart"))

packages

(define-leader-key!
  :infix "p"
  ""  (list :ignore t                       :wk "package")
  "i" (list :def #'straight-use-package     :wk "install")
  "r" (list :def #'straight-rebuild-package :wk "rebuild")
  "p" (list :def #'straight-pull-package    :wk "pull")
  "s" (list :def #'straight/search-package  :wk "search"))

search

(define-leader-key!
  :infix "s"
  ""  (list :ignore t :wk "search")
  "s" (list :def #'selectrum/swiper :wk "swiper"))

(define-leader-key!
  :infix "s"
  :keymaps 'org-mode-map
  "h" (list :def #'selectrum/org-outline-headings :wk "headlines"))

git

(define-leader-key!
  :infix "g"
  ""  (list :ignore t           :wk "git")
  "c" (list :def #'magit-commit :wk "commit")
  "s" (list :def #'magit-status :wk "status"))

Luis-Henriquez-Perez/.emacs.d

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages