search

alphapapa / prism.el

Disperse Lisp forms (and other languages) into a spectrum of colors by depth
GNU General Public License v3.0
291 stars 4 forks source link
emacs syntax-highlighting

readme

+TITLE: prism.el

+PROPERTY: LOGGING nil

Note: This readme works with the org-make-toc https://github.com/alphapapa/org-make-toc package, which automatically updates the table of contents.

+HTML:

[[https://melpa.org/#/package-name][file:https://melpa.org/packages/prism-badge.svg]] [[https://stable.melpa.org/#/package-name][file:https://stable.melpa.org/packages/prism-badge.svg]]

=prism= disperses lisp forms (and other languages) into a spectrum of color by depth. It's similar to =rainbow-blocks=, but it respects existing non-color face properties, and allows flexible configuration of faces and colors. It also optionally colorizes strings and/or comments by code depth in a similar, customizable way.

** Lisp and C-like languages :PROPERTIES: :TOC: :include descendants :depth 1 :END: :CONTENTS:

One of the benefits of =prism= is making it easy to see which list elements are in. For example, in this excerpt from =org-get-entries-from-diary= from =org-agenda.el=, the =funcall='s first argument is an unusually indented =if= form, and the indentation nearly aligns the =funcall='s second argument, =date=, at the column where the =if='s /else/ clause would usually be. But with depth-based colorization, it's easy to see that =date= and =1= are arguments to =funcall=, not part of the =if= form.

It's also easy to distinguish the =diary-list-entries-hook= variable's value form from other variables, and the =entries= variable's different color clearly shows that it has no value form.

[[images/one-armed-if.png]]

It is also useful for non-Lisp languages. For example, here's an example of JSON in =prism-mode=:

[[images/json.png]]

Here's an Emacs C function:

[[images/c.png]]

It might even help save you from deeply nested, callback-style JavaScript, turning this:

[[images/js-before.png]]

Into this (using theme =doom-outrun-electric=). Note how the =bind= is the same color as the =function= keyword and braces that it corresponds to:

[[images/js-after.png]]

*** Colorize parens distinctly

Inspired by [[https://github.com/tarsius/paren-face][paren-face]], when the option =prism-parens= is enabled, parens (any character classified as parenthesis-like syntax by the buffer's mode) may be colored distinctly from other text, e.g. to make them fade away or stand out. For example, this shows parens being blended into the background with 50% opacity:

[[images/parens-0.5.png]]

And here, at 25%:

[[images/parens-0.25.png]]

*** Highlighting mistakes

In this screenshot, the second and third top-level forms are colorized differently than the first, which points to a programmer error: the first ~defun~'s closing parens are on a line after a comment.

[[images/prism-shows-mistakes.png]]

** Whitespace-sensitive languages

For whitespace-sensitive languages, =prism-whitespace-mode= determines depth by a combination of indentation and list nesting. For example, Python (showing theme =doom-vibrant= with these faces set in variable =prism-colors=: =font-lock-type-face=, =font-lock-function-name-face=, =font-lock-constant-face=, and =font-lock-keyword-face=):

[[images/python.png]]

This example shows Python with =prism-comments= enabled (showing theme =doom-challenger-deep=):

[[images/python-doom-challenger-deep.png]]

Here, even though these ~if~ statements' conditions are parenthesized and split across lines, they are colorized at the same logical depth--and the parts of them in brackets, at a deeper logical depth, are also colorized at the proper depth:

[[images/python-3.png]]

Thanks to Emacs's mode-specific syntax tables, even complex shell scripts are properly interpreted. In this example, even though the subsequent lines of this shell function are indented more deeply than the first, they are at the same logical depth because of their being continued lines, so they are colorized at the same initial depth, with their parenthesized and bracketed portions colorized at deeper depths (showing theme =doom-solarized-dark= with a reversed-rainbow palette):

[[images/shell-1.png]]

And in this function, even though Emacs indents each part of the the doubly continued line more deeply, they're colorized with the same color, because they're at the same logical depth:

[[images/shell-2.png]]

It even works in Haskell (showing theme =doom-molokai=):

[[images/haskell-doom-molokai.png]]

** Customizable colors

It's easy to adjust the colors with ~prism-set-colors~. Here are some examples.

You can use just a few faces in combination with the =desaturations= and =lightens= to create a palette of colors:

[[images/2-faces.png]] [[images/4-faces.png]]

Or even a single color, going in one direction:

[[images/1-color.png]]

...or the other:

[[images/1-color-reversed.png]]

The default configuration looks decent in the default Emacs theme:

[[images/default-emacs.png]]

If you use [[https://github.com/hlissner/emacs-doom-themes][Doom themes]], you can use =doom-color= to get colors from the theme:

[[images/doom-spacegrey.png]]

But some of them look nice without any customization, like =doom-gruvbox=:

[[images/doom-gruvbox.png]]

If you use [[https://github.com/bbatsov/solarized-emacs][solarized-theme]], you can use ~solarized-with-color-variables~ to get colors from the theme:

[[images/1.png]]

And you can adjust the palette extensively by changing the applied desaturation and lightening:

[[images/2.png]] [[images/5.png]]

You can shuffle the order of the colors until you find a pattern you like:

[[images/shuffled.png]]

** Buffer-local themes

You can even set themes buffer-locally (the theme-choosing command shown here is not included, but you can easily define your own "chooser" command using [[https://github.com/alphapapa/unpackaged.el#define-a-chooser-command][unpackaged/define-chooser]]):

[[images/prism-themes.gif]]

=prism= is much like [[https://github.com/istib/rainbow-blocks][rainbow-blocks]], but it differs in a few ways:

The easiest way is to use [[https://framagit.org/steckerhalter/quelpa-use-package][quelpa-use-package]] like this:

+BEGIN_SRC elisp

(use-package prism :quelpa (prism :fetcher github :repo "alphapapa/prism.el"))

+END_SRC

  1. Run the appropriate command for the current buffer:
    • For Lisp and C-like languages, use =prism-mode=.
    • For significant-whitespace languages like Python, or ones whose depth is not always indicated by parenthetical characters, like shell, use =prism-whitespace-mode= instead.
  2. Enjoy.

** Advanced

More advanced customization of faces is done by calling =prism-set-colors=, which can override the default settings and perform additional color manipulations. The primary argument is =COLORS=, which should be a list of colors, each of which may be a name, a hex RGB string, or a face name (of which the foreground color is used). Note that the list of colors need not be as long as the number of faces that's actually set (e.g. the default is 16 faces), because the colors are automatically repeated and adjusted as necessary.

Faces may be remapped buffer-locally by setting the =LOCAL= argument to =t= (interactively, with one universal prefix); if set to =reset= (interactively, with two prefixes), local remappings are cleared.

If =prism-set-colors= is called with the =SAVE= argument, the results are saved to customization options so that =prism-mode= will use those colors by default.

Here's an example that the author finds pleasant (seen in the first screenshot):

+BEGIN_SRC elisp :exports code :results silent

(prism-set-colors :num 16 :desaturations (cl-loop for i from 0 below 16 collect ( i 2.5)) :lightens (cl-loop for i from 0 below 16 collect ( i 2.5)) :colors (list "dodgerblue" "medium sea green" "sandy brown")

:comments-fn
(lambda (color)
  (prism-blend color
               (face-attribute 'font-lock-comment-face :foreground) 0.25))

:strings-fn
(lambda (color)
  (prism-blend color "white" 0.5)))

+END_SRC

** 0.4-pre

Additions

Changes

Fixes

** 0.3.5

Fixes

** 0.3.4

Fixes

** 0.3.3

Compatibility

Fixes

** 0.3.2

Fixed

** 0.3.1

Added

Fixed

** 0.3

Added

Changed

Fixed

** 0.2.3

Fixed

** 0.2.2

Fixed

** 0.2.1

Fixed

** 0.2

Added

Fixed

** 0.1

First tagged version. Possibly a few sneaky bugs lurking, but seems to work well.

Inspired by [[https://github.com/istib/rainbow-blocks][rainbow-blocks]], [[https://github.com/Fanael/rainbow-identifiers][rainbow-identifiers]], and [[https://github.com/Fanael/rainbow-delimiters][rainbow-delimiters]].

Bug reports, feature requests, suggestions — /oh my/!

In the event that a bug in the font-locking functions cause Emacs to enter an infinite loop, you can stop it without killing Emacs by following these steps:

  1. From a shell, run ~pkill -SIGUSR2 emacs~. Usually once is enough, but not always.
  2. After Emacs displays a backtrace, switch to the buffer where ~prism-mode~ was enabled and call ~prism-mode~ again to disable it.
  3. Please report the backtrace to the issue tracker so it can be fixed. Include contents of the buffer when possible.

GPLv3

Local Variables:

eval: (require 'org-make-toc)

before-save-hook: org-make-toc

org-export-with-properties: ()

org-export-with-title: t

End: