emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Move docs/api.org to emacs-lisp module

Browse source
This commit is contained in:
Henrik Lissner 2021-01-17 15:53:12 -05:00
parent 1ddeb119dd
commit 1c8451e509
2 changed files with 61 additions and 143 deletions
Download patch file Download diff file Expand all files Collapse all files

4
modules/lang/emacs-lisp/config.el
View file

@ -183,12 +183,12 @@ employed so that flycheck still does *some* helpful linting.")
"Add Doom's own demos to help buffers." "Add Doom's own demos to help buffers."
:around #'elisp-demos--search :around #'elisp-demos--search
(or (funcall orig-fn symbol) (or (funcall orig-fn symbol)
(when-let (demos-file (doom-glob doom-docs-dir "api.org")) (when-let (demos-file (doom-module-locate-path :lang 'emacs-lisp "demos.org"))
(with-temp-buffer (with-temp-buffer
(insert-file-contents demos-file) (insert-file-contents demos-file)
(goto-char (point-min)) (goto-char (point-min))
(when (re-search-forward (when (re-search-forward
(format "^\\*\\*\\* %s$" (regexp-quote (symbol-name symbol))) (format "^\\*\\* %s$" (regexp-quote (symbol-name symbol)))
nil t) nil t)
(let (beg end) (let (beg end)
(forward-line 1) (forward-line 1)

200
docs/api.org → modules/lang/emacs-lisp/demos.org
View file

@ -1,48 +1,42 @@
#+TITLE: API Demos #+TITLE: API Demos
#+PROPERTY: header-args:elisp :results pp #+PROPERTY: header-args:elisp :results pp
This appendix serves as a reference on how to use Doom Emacs' standard library. This file contains demos of Doom's public API; its core library, macros, and
It is integrated into Helpful, in Doom. autodefs. It is used by the =elisp-demos= package to display examples of their
usage from their documentation (e.g. =SPC h f add-hook\!=).
* Table of Contents :TOC_3: * Table of Contents :TOC_3:
- [[#examples-for-dooms-library][Examples for Doom's library]] - [[#core-lib][core-lib]]
- [[#core-lib][core-lib]] - [[#add-hook][add-hook!]]
- [[#add-hook][add-hook!]] - [[#add-transient-hook][add-transient-hook!]]
- [[#add-transient-hook][add-transient-hook!]] - [[#after][after!]]
- [[#after][after!]] - [[#appendq][appendq!]]
- [[#appendq][appendq!]] - [[#custom-set-faces][custom-set-faces!]]
- [[#custom-set-faces][custom-set-faces!]] - [[#custom-theme-set-faces][custom-theme-set-faces!]]
- [[#custom-theme-set-faces][custom-theme-set-faces!]] - [[#defer-feature][defer-feature!]]
- [[#defer-feature][defer-feature!]] - [[#defer-until][defer-until!]]
- [[#defer-until][defer-until!]] - [[#disable-packages][disable-packages!]]
- [[#disable-packages][disable-packages!]] - [[#doom][doom!]]
- [[#doom][doom!]] - [[#file-exists-p][file-exists-p!]]
- [[#file-exists-p][file-exists-p!]] - [[#cmd][cmd!]]
- [[#cmd][cmd!]] - [[#cmd-1][cmd!!]]
- [[#cmd-1][cmd!!]] - [[#cmds][cmds!]]
- [[#cmds][cmds!]] - [[#kbd][kbd!]]
- [[#kbd][kbd!]] - [[#letenv][letenv!]]
- [[#letenv][letenv!]] - [[#load][load!]]
- [[#load][load!]] - [[#map][map!]]
- [[#map][map!]] - [[#package][package!]]
- [[#package][package!]] - [[#pushnew][pushnew!]]
- [[#pushnew][pushnew!]] - [[#prependq][prependq!]]
- [[#prependq][prependq!]] - [[#quiet][quiet!]]
- [[#quiet][quiet!]] - [[#remove-hook][remove-hook!]]
- [[#remove-hook][remove-hook!]] - [[#setq][setq!]]
- [[#setq][setq!]] - [[#setq-hook][setq-hook!]]
- [[#setq-hook][setq-hook!]] - [[#unsetq-hook][unsetq-hook!]]
- [[#unsetq-hook][unsetq-hook!]] - [[#use-package][use-package!]]
- [[#use-package][use-package!]]
- [[#interesting-snippets][Interesting snippets]]
- [[#center-emacs-initial-frame-with-a-fixed-size][Center Emacs' initial frame with a fixed size]]
- [[#persist-emacs-initial-frame-position-dimensions-andor-full-screen-state-across-sessions][Persist Emacs' initial frame position, dimensions and/or full-screen state across sessions]]
- [[#update-cursor-shape-under-terminal-emacs][Update cursor shape under terminal Emacs]]
- [[#create-a-paste-transient-state-to-cycle-through-kill-ring-on-paste][Create a paste-transient-state to cycle through kill ring on paste]]
* Examples for Doom's library * core-lib
** core-lib ** add-hook!
*** add-hook!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;; With only one hook and one function, this is identical to `add-hook'. In that ;; With only one hook and one function, this is identical to `add-hook'. In that
;; case, use that instead. ;; case, use that instead.
@ -70,8 +64,8 @@ It is integrated into Helpful, in Doom.
...)) ...))
#+END_SRC #+END_SRC
*** TODO add-transient-hook! ** TODO add-transient-hook!
*** after! ** after!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;;; `after!' will take: ;;; `after!' will take:
@ -97,7 +91,7 @@ It is integrated into Helpful, in Doom.
(after! rustic ...) (after! rustic ...)
(after! python ...) (after! python ...)
#+END_SRC #+END_SRC
*** appendq! ** appendq!
#+BEGIN_SRC elisp #+BEGIN_SRC elisp
(let ((x '(a b c))) (let ((x '(a b c)))
(appendq! x '(c d e)) (appendq! x '(c d e))
@ -118,7 +112,7 @@ It is integrated into Helpful, in Doom.
#+RESULTS: #+RESULTS:
: (a b c c d e f g h) : (a b c c d e f g h)
*** custom-set-faces! ** custom-set-faces!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
(custom-set-faces! (custom-set-faces!
'(outline-1 :weight normal) '(outline-1 :weight normal)
@ -152,7 +146,7 @@ It is integrated into Helpful, in Doom.
`(outline-2 :background ,(doom-color 'blue))) `(outline-2 :background ,(doom-color 'blue)))
#+END_SRC #+END_SRC
*** custom-theme-set-faces! ** custom-theme-set-faces!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
(custom-theme-set-faces! 'doom-one (custom-theme-set-faces! 'doom-one
'(outline-1 :weight normal) '(outline-1 :weight normal)
@ -186,15 +180,15 @@ It is integrated into Helpful, in Doom.
`(outline-2 :background ,(doom-color 'blue))) `(outline-2 :background ,(doom-color 'blue)))
#+END_SRC #+END_SRC
*** TODO defer-feature! ** TODO defer-feature!
*** TODO defer-until! ** TODO defer-until!
*** disable-packages! ** disable-packages!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;; Disable packages enabled by DOOM ;; Disable packages enabled by DOOM
(disable-packages! some-package second-package) (disable-packages! some-package second-package)
#+END_SRC #+END_SRC
*** doom! ** doom!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
(doom! :completion (doom! :completion
company company
@ -224,7 +218,7 @@ It is integrated into Helpful, in Doom.
(default +bindings +smartparens)) (default +bindings +smartparens))
#+END_SRC #+END_SRC
*** file-exists-p! ** file-exists-p!
#+BEGIN_SRC elisp #+BEGIN_SRC elisp
(file-exists-p! "init.el" doom-emacs-dir) (file-exists-p! "init.el" doom-emacs-dir)
#+END_SRC #+END_SRC
@ -241,12 +235,12 @@ It is integrated into Helpful, in Doom.
#+RESULTS: #+RESULTS:
: /home/hlissner/.emacs.d/LICENSE : /home/hlissner/.emacs.d/LICENSE
*** cmd! ** cmd!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
(map! "C-j" (cmd! (newline) (indent-according-to-mode))) (map! "C-j" (cmd! (newline) (indent-according-to-mode)))
#+END_SRC #+END_SRC
*** cmd!! ** cmd!!
When ~newline~ is passed a numerical prefix argument (=C-u 5 M-x newline=), it When ~newline~ is passed a numerical prefix argument (=C-u 5 M-x newline=), it
inserts N newlines. We can use ~cmd!!~ to easily create a keybinds that bakes in inserts N newlines. We can use ~cmd!!~ to easily create a keybinds that bakes in
the prefix arg into the command call: the prefix arg into the command call:
@ -265,7 +259,7 @@ Or to create aliases for functions that behave differently:
(fset 'org-reset-global-visibility (cmd!! #'org-global-cycle '(4)) (fset 'org-reset-global-visibility (cmd!! #'org-global-cycle '(4))
#+END_SRC #+END_SRC
*** cmds! ** cmds!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
(map! :i [tab] (cmds! (and (featurep! :editor snippets) (map! :i [tab] (cmds! (and (featurep! :editor snippets)
(bound-and-true-p yas-minor-mode) (bound-and-true-p yas-minor-mode)
@ -285,13 +279,13 @@ Or to create aliases for functions that behave differently:
#'evil-jump-item)) #'evil-jump-item))
#+END_SRC #+END_SRC
*** kbd! ** kbd!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
(map! "," (kbd! "SPC") (map! "," (kbd! "SPC")
";" (kbd! ":")) ";" (kbd! ":"))
#+END_SRC #+END_SRC
*** letenv! ** letenv!
#+BEGIN_SRC elisp #+BEGIN_SRC elisp
(letenv! (("SHELL" "/bin/sh")) (letenv! (("SHELL" "/bin/sh"))
(shell-command-to-string "echo $SHELL")) (shell-command-to-string "echo $SHELL"))
@ -300,7 +294,7 @@ Or to create aliases for functions that behave differently:
#+RESULTS: #+RESULTS:
: "/bin/sh\n" : "/bin/sh\n"
*** load! ** load!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;;; Lets say we're in ~/.doom.d/config.el ;;; Lets say we're in ~/.doom.d/config.el
(load! "lisp/module") ; loads ~/.doom.d/lisp/module.el (load! "lisp/module") ; loads ~/.doom.d/lisp/module.el
@ -311,7 +305,7 @@ Or to create aliases for functions that behave differently:
(load! "~/.maynotexist" nil t) (load! "~/.maynotexist" nil t)
#+END_SRC #+END_SRC
*** map! ** map!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
(map! :map magit-mode-map (map! :map magit-mode-map
:m "C-r" 'do-something ; C-r in motion state :m "C-r" 'do-something ; C-r in motion state
@ -406,7 +400,7 @@ These are side-by-side comparisons, showing how to bind keys with and without
(:map go-lisp-mode :n "C-x x" #'do-something-else)) (:map go-lisp-mode :n "C-x x" #'do-something-else))
#+END_SRC #+END_SRC
*** package! ** package!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;; To install a package that can be found on ELPA or any of the sources ;; To install a package that can be found on ELPA or any of the sources
;; specified in `straight-recipe-repositories': ;; specified in `straight-recipe-repositories':
@ -438,7 +432,7 @@ These are side-by-side comparisons, showing how to bind keys with and without
(package! evil :ignore (not (equal system-name "my-desktop"))) (package! evil :ignore (not (equal system-name "my-desktop")))
#+END_SRC #+END_SRC
*** pushnew! ** pushnew!
#+BEGIN_SRC elisp #+BEGIN_SRC elisp
(let ((list '(a b c))) (let ((list '(a b c)))
(pushnew! list 'c 'd 'e) (pushnew! list 'c 'd 'e)
@ -448,7 +442,7 @@ These are side-by-side comparisons, showing how to bind keys with and without
#+RESULTS: #+RESULTS:
: (e d a b c) : (e d a b c)
*** prependq! ** prependq!
#+BEGIN_SRC elisp #+BEGIN_SRC elisp
(let ((x '(a b c))) (let ((x '(a b c)))
(prependq! x '(c d e)) (prependq! x '(c d e))
@ -469,12 +463,12 @@ These are side-by-side comparisons, showing how to bind keys with and without
#+RESULTS: #+RESULTS:
: (c d e f g h a b c) : (c d e f g h a b c)
*** quiet! ** quiet!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;; Enters recentf-mode without extra output ;; Enters recentf-mode without extra output
(quiet! (recentf-mode +1)) (quiet! (recentf-mode +1))
#+END_SRC #+END_SRC
*** remove-hook! ** remove-hook!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;; With only one hook and one function, this is identical to `remove-hook'. In ;; With only one hook and one function, this is identical to `remove-hook'. In
;; that case, use that instead. ;; that case, use that instead.
@ -492,7 +486,7 @@ These are side-by-side comparisons, showing how to bind keys with and without
;; Removing arbitrary forms (must be exactly the same as the definition) ;; Removing arbitrary forms (must be exactly the same as the definition)
(remove-hook! (one-mode second-mode) (setq v 5) (setq a 2)) (remove-hook! (one-mode second-mode) (setq v 5) (setq a 2))
#+END_SRC #+END_SRC
*** setq! ** setq!
#+BEGIN_SRC elisp #+BEGIN_SRC elisp
;; Each of these have a setter associated with them, which must be triggered in ;; Each of these have a setter associated with them, which must be triggered in
;; order for their new values to have an effect. ;; order for their new values to have an effect.
@ -500,7 +494,7 @@ These are side-by-side comparisons, showing how to bind keys with and without
evil-want-C-u-scroll nil evil-want-C-u-scroll nil
evil-want-C-d-scroll nil) evil-want-C-d-scroll nil)
#+END_SRC #+END_SRC
*** setq-hook! ** setq-hook!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;; Set multiple variables after a hook ;; Set multiple variables after a hook
(setq-hook! 'markdown-mode-hook (setq-hook! 'markdown-mode-hook
@ -512,7 +506,7 @@ These are side-by-side comparisons, showing how to bind keys with and without
hscroll-margin 0) hscroll-margin 0)
#+END_SRC #+END_SRC
*** unsetq-hook! ** unsetq-hook!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
(unsetq-hook! 'markdown-mode-hook line-spacing) (unsetq-hook! 'markdown-mode-hook line-spacing)
@ -526,7 +520,7 @@ These are side-by-side comparisons, showing how to bind keys with and without
(unsetq-hook! (one-mode second-mode) enable-something) (unsetq-hook! (one-mode second-mode) enable-something)
#+END_SRC #+END_SRC
*** use-package! ** use-package!
#+BEGIN_SRC elisp :eval no #+BEGIN_SRC elisp :eval no
;; Use after-call to load package before hook ;; Use after-call to load package before hook
(use-package! projectile (use-package! projectile
@ -541,79 +535,3 @@ These are side-by-side comparisons, showing how to bind keys with and without
(use-package! abc (use-package! abc
:defer-incrementally t) :defer-incrementally t)
#+END_SRC #+END_SRC
* Interesting snippets
** Center Emacs' initial frame with a fixed size
#+BEGIN_SRC elisp
(let ((width 500)
(height 250)
(display-height (display-pixel-height))
(display-width (display-pixel-width)))
(pushnew! initial-frame-alist
`(left . ,(- (/ display-width 2) (/ width 2)))
`(top . ,(- (/ display-height 2) (/ height 2)))
`(width text-pixels ,width)
`(height text-pixels ,height)))
#+END_SRC
** Persist Emacs' initial frame position, dimensions and/or full-screen state across sessions
#+BEGIN_SRC elisp
;; add to ~/.doom.d/config.el
(when-let (dims (doom-store-get 'last-frame-size))
(cl-destructuring-bind ((left . top) width height fullscreen) dims
(setq initial-frame-alist
(append initial-frame-alist
`((left . ,left)
(top . ,top)
(width . ,width)
(height . ,height)
(fullscreen . ,fullscreen))))))
(defun save-frame-dimensions ()
(doom-store-put 'last-frame-size
(list (frame-position)
(frame-width)
(frame-height)
(frame-parameter nil 'fullscreen))))
(add-hook 'kill-emacs-hook #'save-frame-dimensions)
#+END_SRC
** Update cursor shape under terminal Emacs
Install [[https://github.com/7696122/evil-terminal-cursor-changer][evil-terminal-cursor-changer]]. The package isn't included in Doom because
it is not maintained, unreasonably buggy, and lacks support for a number of
terminals. Where it fails, it inserts unexpected characters into the buffer. To
uphold the principle of least surprise, an unchanging cursor is less surprising
than unwarranted characters.
#+BEGIN_SRC elisp
;; ~/.doom.d/packages.el
(package! evil-terminal-cursor-changer)
;; ~/.doom.d/config.el
(use-package! evil-terminal-cursor-changer
:hook (tty-setup . evil-terminal-cursor-changer-activate))
#+END_SRC
Alternatively, an updated version exists at
[[https://github.com/amosbird/evil-terminal-cursor-changer][amosbird/evil-terminal-cursor-changer]], with support for urxvt and tmux.
** Create a paste-transient-state to cycle through kill ring on paste
Replaces the default evil-paste binding to paste then let you cycle through entries in your kill ring. Gives you more flexibility when copying to your clipboard, making edits, then deciding to paste after.
You will need to enable the `hydra` module first.
#+BEGIN_SRC elisp
(defhydra hydra-paste (:color red
:hint nil)
"\n[%s(length kill-ring-yank-pointer)/%s(length kill-ring)] \
[_C-j_/_C-k_] cycles through yanked text, [_p_/_P_] pastes the same text \
above or below. Anything else exits."
("C-j" evil-paste-pop)
("C-k" evil-paste-pop-next)
("p" evil-paste-after)
("P" evil-paste-before))
(map! :nv "p" #'hydra-paste/evil-paste-after
:nv "P" #'hydra-paste/evil-paste-before)
#+END_SRC