lex-hl

Highlight lexically bound variables
git clone https://git.jamzattack.xyz/lex-hl
Log | Files | Refs | LICENSE

README.org (2737B)


      1 #+title: Lex-hl
      2 #+author: Jamie Beardslee
      3 #+email: jdb@jamzattack.xyz
      4 
      5 This package provides a very primitive way to highlight lexically
      6 bound variables in Elisp code.
      7 
      8 ** Motivation
      9 When reading (not writing) Elisp, I often find it hard to figure out
     10 which variables are bound where.  I wanted a single keypress to
     11 highlight all the variables in a =let= form or lambda list.
     12 
     13 ** Example
     14 An example, showing the highlighted source of [[help:lex-hl-prompt][lex-hl-prompt]]:
     15 https://jamzattack.xyz/lex-hl.png
     16 
     17 ** Extensibility
     18 The highlighting for each form (e.g. [[help:lex-hl--let][let]], [[help:lex-hl--dolist][dolist]], [[help:lex-hl--defun][defun]]) is
     19 implemented as a separate function, added as a symbol property.
     20 
     21 To add a new highlighter, simply define a function takes a single
     22 argument (a sexp, e.g. =(let ((a 1) (b 2)) (+ a b))=) and highlights the
     23 names of the variables bound within that sexp.  Then, let =lex-hl= know
     24 about it with [[help:lex-hl-add-form][lex-hl-add-form]].
     25 
     26 The currently supported forms are:
     27 - =cl-labels=
     28 - =dolist=
     29 - =let*=
     30 - =let=
     31 - =lambda=
     32 - =defun=
     33 - =defmacro=
     34 
     35 * Installation
     36 ** package.el
     37 Download lex-hl.el, and use =M-x package-install-file RET
     38 path/to/lex-hl.el=.
     39 
     40 ** straight.el
     41 Use the following recipe:
     42 
     43 #+begin_src emacs-lisp
     44   (lex-hl :type git
     45 	  :flavor melpa
     46 	  :repo "https://git.jamzattack.xyz/lex-hl")
     47 #+end_src
     48 
     49 ** Manual installation
     50 1. Download lex-hl.el
     51 2. Stick it in [[help:load-path][load-path]]
     52 3. Update autoloads
     53 4. (optionally) byte-compile it
     54 
     55 * Command index
     56 
     57 - *Function*: ([[help:lex-hl-unhighlight][lex-hl-unhighlight]])
     58 
     59   Remove all hi-lock faces from the current buffer.
     60 
     61 - *Function*: ([[help:lex-hl-top-level][lex-hl-top-level]])
     62 
     63   Highlight variables bound in the top level form at point.
     64   See the variable [[help:lex-hl-forms][lex-hl-forms]] for a list of supported forms.
     65 
     66 - *Function*: ([[help:lex-hl-prompt][lex-hl-prompt]] bounds)
     67 
     68   Highlight variables bound in the form chosen from the minibuffer.
     69   This is limited to the region specified by BOUNDS which,
     70   interactively, is the top level form (aka defun) at point, or the
     71   active region with a prefix argument.
     72 
     73 - *Function*: ([[help:lex-hl-nearest][lex-hl-nearest]] n)
     74 
     75   Highlight variables bound in the Nth nearest form.
     76   See the variable [[help:lex-hl-forms][lex-hl-forms]] for a list of supported forms.
     77 
     78 - *Minor Mode*: [[help:lex-hl-mode][lex-hl-mode]]
     79 
     80   Add some keybindings to highlight lexical variables.
     81   
     82   - Keymap: 
     83   | =C-c '= | [[help:lex-hl-top-level][lex-hl-top-level]]   |
     84   | =C-c ,= | [[help:lex-hl-prompt][lex-hl-prompt]]      |
     85   | =C-c .= | [[help:lex-hl-nearest][lex-hl-nearest]]     |
     86   | =C-c `= | [[help:lex-hl-unhighlight][lex-hl-unhighlight]] |
     87 
     88 * License
     89 
     90 GPL3+