README.org (3645B)
1 #+title: Itch.el -- Switch to and create scratch buffers easily 2 #+author: Jamie Beardslee 3 #+email: jdb@jamzattack.xyz 4 5 This library provides a unified interface to switch to and create 6 buffers of a particular major mode. Basically, I wanted to switch 7 to the scratch buffer quickly but that wasn't high-tech enough. 8 9 * Semantics of buffer switching and creation 10 - If prefix arg is a number, the buffer is named "NAME<PREFIX>". 11 e.g. =C-2 M-x itch-org RET= will switch to "*org*<2>" 12 13 - If prefix arg is (16) (that is, a list whose sole element is the 14 number 16, accessible with a double universal prefix =C-u C-u=), 15 switch to a buffer chosen from all existing buffers in MODE whose 16 name starts with NAME 17 18 - If the current buffer is in MODE and its name starts with NAME, bury 19 it. 20 21 * Defining new commands with [[help:itch][itch]] 22 23 The function [[help:itch][itch]] is the powerhouse of this package, and allows you to 24 define new commands that use the [[*Semantics of buffer switching and creation][above logic]]. 25 26 It takes 4 arguments: =MODE= =NAME= /&optional/ =PREFIX= =POST-CREATE-FUNCTION= 27 - =MODE= is the major mode of the new buffer 28 - =NAME= is the name of the new buffer 29 - =PREFIX= is intended to be the prefix argument (see its docstring for 30 details) 31 - =POST-CREATE-FUNCTION= is run within all newly created buffers 32 33 For example, to create a new [[help:org-mode][org-mode]] scratch buffer called =*notes*= in 34 =~/org/notes= and insert a timestamp, you could use: 35 #+begin_src emacs-lisp :exports code 36 (defun itch-notes (&optional arg) 37 (interactive "P") 38 (itch 'org-mode "*notes*" arg 39 (lambda () 40 (setq default-directory "~/org/notes") 41 (insert (format-time-string 42 "#+date: [%Y-%m-%d %a %H:%M]\n\n"))))) 43 #+end_src 44 45 * Command index 46 - *Function*: ([[help:itch][itch]] mode name &optional prefix post-create-function) 47 48 Create a temporary buffer in MODE called NAME. 49 This follows some complex but intuitive logic (in order): 50 - If PREFIX is a number, the buffer is named "NAME<PREFIX>" 51 - If PREFIX is (16), switch to a buffer chosen from all existing 52 buffers in MODE whose name starts with NAME 53 - If the current buffer is in MODE and its name starts with NAME, 54 bury it. 55 - If the buffer is newly created (i.e. empty and not narrowed), 56 POST-CREATE-FUNCTION will be called in the new buffer. 57 58 - *Function*: ([[help:itch-eshell][itch-eshell]] &optional arg) 59 60 Create or switch to an eshell buffer. 61 Prefix ARG is passed to [[help:itch][itch]]. See its docstring for usage. 62 63 - *Function*: ([[help:itch-switch-to-eshell][itch-switch-to-eshell]]) 64 65 Switch to an existing eshell buffer. 66 67 - *Function*: ([[help:itch-elisp][itch-elisp]] &optional arg) 68 69 Create or switch to an emacs lisp buffer. 70 Prefix ARG is passed to [[help:itch][itch]]. See its docstring for usage. 71 72 - *Function*: ([[help:itch-switch-to-elisp][itch-switch-to-elisp]]) 73 74 Switch to an existing emacs lisp scratch buffer. 75 76 - *Function*: ([[help:itch-org][itch-org]] &optional arg) 77 78 Create or switch to an org buffer. 79 Prefix ARG is passed to [[help:itch][itch]]. See its docstring for usage. 80 81 - *Function*: ([[help:itch-switch-to-org][itch-switch-to-org]]) 82 83 Switch to an existing org scratch buffer. 84 85 - *Function*: ([[help:itch-fundamental][itch-fundamental]] &optional arg) 86 87 Create or switch to a [[help:fundamental-mode][fundamental-mode]] buffer. 88 Prefix ARG is passed to [[help:itch][itch]]. See its docstring for usage. 89 90 - *Function*: ([[help:itch-switch-to-fundamental][itch-switch-to-fundamental]]) 91 92 Switch to an existing [[help:fundamental-mode][fundamental-mode]] scratch buffer. 93 94 * License 95 GPL3+