itch

Switch to and create scratch buffers
git clone https://git.jamzattack.xyz/itch
Log | Files | Refs | LICENSE

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+