yeet

.config/emacs/modules/config/literate/README.org

@@ -0,0 +1,106 @@
+#+TITLE:   config/literate
+#+DATE:    May 4, 2020
+#+SINCE:   v2.0.9
+#+STARTUP: inlineimages nofold
+
+* Table of Contents :TOC_3:noexport:
+- [[#description][Description]]
+  - [[#maintainers][Maintainers]]
+  - [[#module-flags][Module Flags]]
+  - [[#plugins][Plugins]]
+- [[#prerequisites][Prerequisites]]
+- [[#features][Features]]
+- [[#configuration][Configuration]]
+  - [[#change-the-location-of-configorg][Change the location of config.org]]
+  - [[#change-where-src-blocks-are-tangled-or-prevent-it-entirely][Change where src blocks are tangled or prevent it entirely]]
+- [[#troubleshooting][Troubleshooting]]
+  - [[#how-to-tangle-to-doomdirinitel][How to tangle to =DOOMDIR/init.el=]]
+  - [[#how-to-disable-tangle-on-save][How to disable tangle-on-save]]
+
+* Description
+This module enables support for a literate config.
+
+A literate config consists of a =DOOMDIR/config.org=. All src blocks within are
+tangled =DOOMDIR/config.el=, by default, when ~doom sync~ is executed.
+
+** Maintainers
+This module has no dedicated maintainers.
+
+** Module Flags
+This module provides no flags.
+
+** Plugins
+This module installs no plugins.
+
+* Prerequisites
+This module has no prerequisites.
+
+* Features
++ Automatically tangles ~config.org~ to ~config.el~ when saving. See
+  Troubleshooting section belong on how to disable it.
+
+* Configuration
+** Change the location of config.org
+The ~+literate-config-file~ variable controls where to look for your config.org.
+To change this it must be modified early -- in =DOOMDIR/init.el= or
+=DOOMDIR/cli.el=.
+
+Source blocks needs to be in some language to be automatically tangled, for
+example ~#+BEGIN_SRC elisp~, but it doesn't matter what language is used. All
+blocks are tangled to ~config.el~, but ~elisp~ gives correct syntax
+highlighting. If you don't want to specify language in block you can also
+enforce tangling by adding ~#+BEGIN_SRC :tangle yes~
+
+** Change where src blocks are tangled or prevent it entirely
+By default, this module tangles all src emacs-lisp blocks to config.el unless
+otherwise specified.
+
+To specify otherwise use the =:tangle= parameter to:
+
+- Specify a destination other than config.el: ~:tangle packages.el~
+- Disable tangling of the block altogether with ~:tangle no~
+- Or force non-elisp src blocks to tangle somewhere
+
+For example:
+#+BEGIN_SRC org
+,#+BEGIN_SRC elisp :tangle no
+(message "Don't tangle me")
+,#+END_SRC
+
+,#+BEGIN_SRC elisp :tangle packages.el
+(package! my-package)
+(package! other-package)
+,#+END_SRC
+
+,#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755)
+#!/usr/bin/env bash
+echo Hello world
+,#+END_SRC
+
+,#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash"
+echo Hello world
+,#+END_SRC
+#+END_SRC
+
+You'll find more information about babel src blocks and what parameters they
+support [[https://orgmode.org/manual/Working-with-Source-Code.html][in the manual]].
+
+* Troubleshooting
+** How to tangle to =DOOMDIR/init.el=
+If your literate needs are more complex (e.g. you want to make your init.el
+literate), this module won't cut it. =init.el= is loaded long before
+=config.org= is tangled in the ~doom sync~ process.
+
+However, Doom comes with a [[file:../../../bin/org-tangle][bin/org-tangle]] script which can be used to tangle
+arbitrary org files from the command line. Use it to create your own compilation
+workflows. This is /much/ faster than using ~org-babel-load-file~ directly to
+load your literate config every time Doom is started.
+
+** How to disable tangle-on-save
+There are occasions where tangling on save may be undesirable. Maybe it's too
+slow, produces too much noise, or happens too often (on unrelated org files in
+your =DOOMDIR=). This behavior can be disabled with:
+#+BEGIN_SRC elisp
+;; add to DOOMDIR/config.el
+(remove-hook 'org-mode-hook #'+literate-enable-recompile-h)
+#+END_SRC

.config/emacs/modules/config/literate/autoload.el

@@ -0,0 +1,75 @@
+;;; config/literate/autoload.el -*- lexical-binding: t; -*-
+
+(defvar +literate-config-file
+  (concat doom-private-dir "config.org")
+  "The file path of your literate config file.")
+
+(defvar +literate-config-cache-file
+  (concat doom-cache-dir "literate-last-compile")
+  "The file path that `+literate-config-file' will be tangled to, then
+byte-compiled from.")
+
+(defvar org-mode-hook)
+(defvar org-inhibit-startup)
+
+;;;###autoload (add-hook 'org-mode-hook #'+literate-enable-recompile-h)
+
+;;;###autoload
+(defun +literate-tangle-h ()
+  "Tangles `+literate-config-file' if it has changed."
+  (and (not (getenv "__NOTANGLE"))
+       (require 'ox nil t)
+       (require 'ob-tangle nil t)
+       (letf! ((default-directory doom-private-dir)
+               (target +literate-config-file)
+               (cache +literate-config-cache-file)
+               (dest (expand-file-name (concat doom-module-config-file ".el")))
+               ;; Ensure output conforms to the formatting of all doom CLIs
+               (defun message (msg &rest args)
+                 (when msg
+                   (print! (info "%s") (apply #'format msg args)))))
+         (print! (start "Compiling your literate config..."))
+         (print-group!
+          (let (;; Do as little unnecessary work as possible in these org files.
+                (org-startup-indented nil)
+                (org-startup-folded nil)
+                (vc-handled-backends nil)
+                ;; Prevent unwanted entries in recentf, or formatters, or
+                ;; anything that could be on these hooks, really. Nothing else
+                ;; should be touching these files (particularly in interactive
+                ;; sessions).
+                (write-file-functions nil)
+                (before-save-hook nil)
+                (after-save-hook nil)
+                ;; Prevent infinite recursion due to recompile-on-save hooks
+                ;; later, and speed up `org-mode' init.
+                (org-mode-hook nil)
+                (org-inhibit-startup t)
+                ;; Allow evaluation of src blocks at tangle-time (would abort
+                ;; them otherwise). This is a security hazard, but Doom will
+                ;; trust that you know what you're doing!
+                (org-confirm-babel-evaluate nil))
+            (org-babel-tangle-file target dest))
+          ;; Write an empty file to serve as our mtime cache
+          (with-temp-file cache)
+          (if doom-interactive-p t
+            (message "Restarting..." )
+            (throw 'exit "__DOOMRESTART=1 __NOTANGLE=1 $@"))))))
+
+;;;###autoload
+(defalias '+literate/reload #'doom/reload)
+
+;;;###autoload
+(defun +literate-enable-recompile-h ()
+  "Enable literate-compiling-on-save in the current buffer."
+  (add-hook 'after-save-hook #'+literate-recompile-maybe-h nil 'local))
+
+;;;###autoload
+(defun +literate-recompile-maybe-h ()
+  "Recompile literate config to `doom-private-dir'.
+
+We assume any org file in `doom-private-dir' is connected to your literate
+config, and should trigger a recompile if changed."
+  (and (file-in-directory-p
+        buffer-file-name (file-name-directory +literate-config-file))
+       (+literate-tangle-h)))

.config/emacs/modules/config/literate/cli.el

@@ -0,0 +1,6 @@
+;;; config/literate/cli.el -*- lexical-binding: t; -*-
+
+(load! "autoload")
+
+;; Tangle the user's config.org before 'doom sync' runs
+(add-hook 'doom-sync-pre-hook #'+literate-tangle-h)