273 lines
8.5 KiB
Org Mode
273 lines
8.5 KiB
Org Mode
#+TITLE: API Demos
|
|
#+PROPERTY: header-args:elisp :results pp
|
|
|
|
This appendix serves as a reference on how to use Doom Emacs' standard library.
|
|
It is integrated into Helpful, in Doom.
|
|
|
|
* Table of Contents :TOC_3:
|
|
- [[#examples-for-dooms-core-library][Examples for Doom's core library]]
|
|
- [[#core-lib][core-lib]]
|
|
- [[#add-hook][add-hook!]]
|
|
- [[#add-transient-hook][add-transient-hook!]]
|
|
- [[#after][after!]]
|
|
- [[#custom-set-faces][custom-set-faces!]]
|
|
- [[#custom-theme-set-faces][custom-theme-set-faces!]]
|
|
- [[#defer-feature][defer-feature!]]
|
|
- [[#defer-until][defer-until!]]
|
|
- [[#disable-packages][disable-packages!]]
|
|
- [[#doom][doom!]]
|
|
- [[#file-exists-p][file-exists-p!]]
|
|
- [[#lambda][lambda!]]
|
|
- [[#lambda-1][lambda!!]]
|
|
- [[#load][load!]]
|
|
- [[#map][map!]]
|
|
- [[#package][package!]]
|
|
- [[#pushnew][pushnew!]]
|
|
- [[#quiet][quiet!]]
|
|
- [[#remove-hook][remove-hook!]]
|
|
- [[#setq-hook][setq-hook!]]
|
|
- [[#unsetq-hook][unsetq-hook!]]
|
|
- [[#interesting-snippets][Interesting snippets]]
|
|
- [[#persist-emacs-initial-frame-size-across-sessions][Persist Emacs' initial frame size across sessions]]
|
|
- [[#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]]
|
|
|
|
* Examples for Doom's core library
|
|
** core-lib
|
|
*** add-hook!
|
|
#+BEGIN_SRC elisp :eval no
|
|
;; With only one hook and one function, this is identical to `add-hook'. In that
|
|
;; case, use that instead.
|
|
(add-hook! 'some-mode-hook #'enable-something)
|
|
|
|
;; Adding many-to-many functions to hooks
|
|
(add-hook! some-mode #'enable-something #'and-another)
|
|
(add-hook! some-mode #'(enable-something and-another))
|
|
(add-hook! '(one-mode-hook second-mode-hook) #'enable-something)
|
|
(add-hook! (one-mode second-mode) #'enable-something)
|
|
|
|
;; Appending and local hooks
|
|
(add-hook! (one-mode second-mode) :append #'enable-something)
|
|
(add-hook! (one-mode second-mode) :local #'enable-something)
|
|
|
|
;; With arbitrary forms
|
|
(add-hook! (one-mode second-mode) (setq v 5) (setq a 2))
|
|
(add-hook! (one-mode second-mode) :append :local (setq v 5) (setq a 2))
|
|
|
|
;; Inline named hook functions
|
|
(add-hook! '(one-mode-hook second-mode-hook)
|
|
(defun do-something ()
|
|
...)
|
|
(defun do-another-thing ()
|
|
...))
|
|
#+END_SRC
|
|
|
|
*** TODO add-transient-hook!
|
|
*** TODO after!
|
|
*** custom-set-faces!
|
|
#+BEGIN_SRC elisp :eval no
|
|
(custom-set-faces!
|
|
'(outline-1 :weight normal)
|
|
'(outline-2 :weight normal)
|
|
'(outline-3 :weight normal)
|
|
'(outline-4 :weight normal)
|
|
'(outline-5 :weight normal)
|
|
'(outline-6 :weight normal)
|
|
'(default :background "red" :weight bold)
|
|
'(region :background "red" :weight bold))
|
|
|
|
(custom-set-faces!
|
|
'((outline-1 outline-2 outline-3 outline-4 outline-5 outline-6)
|
|
:weight normal)
|
|
'((default region)
|
|
:background "red" :weight bold))
|
|
|
|
(let ((red-bg-faces '(default region)))
|
|
(custom-set-faces!
|
|
`(,(cl-loop for i from 0 to 6 collect (intern (format "outline-%d" i)))
|
|
:weight normal)
|
|
`(,red-bg-faces
|
|
:background "red" :weight bold)))
|
|
#+END_SRC
|
|
|
|
*** custom-theme-set-faces!
|
|
#+BEGIN_SRC elisp :eval no
|
|
(custom-theme-set-faces! 'doom-one-theme
|
|
'(outline-1 :weight normal)
|
|
'(outline-2 :weight normal)
|
|
'(outline-3 :weight normal)
|
|
'(outline-4 :weight normal)
|
|
'(outline-5 :weight normal)
|
|
'(outline-6 :weight normal)
|
|
'(default :background "red" :weight bold)
|
|
'(region :background "red" :weight bold))
|
|
|
|
(custom-theme-set-faces! '(doom-one-theme doom-one-light-theme)
|
|
'((outline-1 outline-2 outline-3 outline-4 outline-5 outline-6)
|
|
:weight normal)
|
|
'((default region)
|
|
:background "red" :weight bold))
|
|
|
|
(let ((red-bg-faces '(default region)))
|
|
(custom-theme-set-faces! '(doom-one-theme doom-one-light-theme)
|
|
`(,(cl-loop for i from 0 to 6 collect (intern (format "outline-%d" i)))
|
|
:weight normal)
|
|
`(,red-bg-faces
|
|
:background "red" :weight bold)))
|
|
#+END_SRC
|
|
|
|
*** TODO defer-feature!
|
|
*** TODO defer-until!
|
|
*** TODO disable-packages!
|
|
*** doom!
|
|
#+BEGIN_SRC elisp :eval no
|
|
(doom! :completion
|
|
company
|
|
ivy
|
|
;;helm
|
|
|
|
:tools
|
|
(:if IS-MAC macos)
|
|
docker
|
|
lsp
|
|
|
|
:lang
|
|
(cc +lsp)
|
|
(:cond ((string= system-name "work-pc")
|
|
python
|
|
rust
|
|
web)
|
|
((string= system-name "writing-pc")
|
|
(org +dragndrop)
|
|
ruby))
|
|
(:if IS-LINUX
|
|
(web +lsp)
|
|
web)
|
|
|
|
:config
|
|
literate
|
|
(default +bindings +smartparens))
|
|
#+END_SRC
|
|
|
|
*** file-exists-p!
|
|
#+BEGIN_SRC elisp
|
|
(file-exists-p! "init.el" doom-emacs-dir)
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
: /home/hlissner/.emacs.d/init.el
|
|
|
|
#+BEGIN_SRC elisp
|
|
(file-exists-p! (and (or "doesnotexist" "init.el")
|
|
"LICENSE")
|
|
doom-emacs-dir)
|
|
#+END_SRC
|
|
|
|
#+RESULTS:
|
|
: /home/hlissner/.emacs.d/LICENSE
|
|
|
|
*** TODO lambda!
|
|
*** TODO lambda!!
|
|
*** load!
|
|
#+BEGIN_SRC elisp :eval no
|
|
;;; Lets say we're in ~/.doom.d/config.el
|
|
(load! "lisp/module") ; loads ~/.doom.d/lisp/module.el
|
|
(load! "somefile" doom-emacs-dir) ; loads ~/.emacs.d/somefile.el
|
|
(load! "anotherfile" doom-private-dir) ; loads ~/.doom.d/anotherfile.el
|
|
|
|
;; If you don't want a `load!' call to throw an error if the file doesn't exist:
|
|
(load! "~/.maynotexist" nil t)
|
|
#+END_SRC
|
|
|
|
*** TODO map!
|
|
*** package!
|
|
#+BEGIN_SRC elisp :eval no
|
|
;; To install a package that can be found on ELPA or any of the sources
|
|
;; specified in `doom-core-package-sources':
|
|
(package! evil)
|
|
(package! js2-mode)
|
|
(package! rainbow-delimiters)
|
|
|
|
;; To disable a package included with Doom (which will no-op all its `after!'
|
|
;; and `use-package!' blocks):
|
|
(package! evil :disable t)
|
|
(package! rainbow-delimiters :disable t)
|
|
|
|
;; To install a package from a github repo
|
|
(package! so-long :recipe (:host github :repo "hlissner/emacs-so-long"))
|
|
|
|
;; If a package is particularly big and comes with submodules you don't need,
|
|
;; you can tell the package manager not to clone the repo recursively:
|
|
(package! ansible :recipe (:nonrecursive t))
|
|
|
|
;; To install a particular branch, commit or tag:
|
|
(package! evil
|
|
;; if :host and :fetcher aren't specified, the package manager will fall back
|
|
;; to evil's default source provided by their (M)ELPA recipes:
|
|
:recipe (:commit "e7bc39de2f961505e8e112da8c1b315ae8afce52"))
|
|
|
|
(package! evil :recipe (:branch "stable"))
|
|
|
|
(package! evil :recipe (:tag "1.2.9"))
|
|
|
|
;; If you share your config between two computers, and don't want bin/doom
|
|
;; refresh to delete packages used only on one system, use :ignore
|
|
(package! evil :ignore (not (equal system-name "my-desktop")))
|
|
#+END_SRC
|
|
|
|
*** TODO pushnew!
|
|
*** TODO quiet!
|
|
*** remove-hook!
|
|
#+BEGIN_SRC elisp :eval no
|
|
;; With only one hook and one function, this is identical to `remove-hook'. In
|
|
;; that case, use that instead.
|
|
(remove-hook! 'some-mode-hook #'enable-something)
|
|
|
|
;; Removing N functions from M hooks
|
|
(remove-hook! some-mode #'enable-something #'and-another)
|
|
(remove-hook! some-mode #'(enable-something and-another))
|
|
(remove-hook! '(one-mode-hook second-mode-hook) #'enable-something)
|
|
(remove-hook! (one-mode second-mode) #'enable-something)
|
|
|
|
;; Removing buffer-local hooks
|
|
(remove-hook! (one-mode second-mode) :local #'enable-something)
|
|
|
|
;; Removing arbitrary forms (must be exactly the same as the definition)
|
|
(remove-hook! (one-mode second-mode) (setq v 5) (setq a 2))
|
|
#+END_SRC
|
|
*** TODO setq-hook!
|
|
*** TODO unsetq-hook!
|
|
|
|
* Interesting snippets
|
|
** Persist Emacs' initial frame size across sessions
|
|
#+BEGIN_SRC elisp
|
|
(let ((display-height (display-pixel-height))
|
|
(display-width (display-pixel-width)))
|
|
(add-to-list 'initial-frame-alist
|
|
`((left . ,(/ new-frame-width 2))
|
|
(top . ,(/ new-frame-height 2))
|
|
(width . ,(/ display-width 2))
|
|
(height . ,(/ display-height 2)))))
|
|
#+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-cache-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-cache-set 'last-frame-size
|
|
(list (frame-position)
|
|
(frame-width)
|
|
(frame-height)
|
|
(frame-parameter nil 'fullscreen))))
|
|
|
|
(add-hook 'kill-emacs-hook #'save-frame-dimensions)
|
|
#+END_SRC
|