spacemacs/layers/+themes/colors/README.org

#+TITLE: Colors layer

[[file:img/rainbow_dash.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
- [[#description][Description]]
- [[#install][Install]]
- [[#configuration][Configuration]]
  - [[#colorize-identifiers][Colorize identifiers]]
  - [[#enable-nyan-cat][Enable Nyan cat]]
- [[#key-bindings][Key bindings]]
  - [[#colorize-identifiers-1][Colorize Identifiers]]
  - [[#rainbow-mode][Rainbow Mode]]
  - [[#nyan-mode][Nyan Mode]]

* Description
This layer colors your life with the help of the following packages:
- [[https://github.com/Fanael/rainbow-identifiers][rainbow-identifiers]] mode will colorize all identifiers (christmas tree mode :-))
  with mostly unique colors, and the ability to choose saturation and lightness.
- [[https://github.com/ankurdave/color-identifiers-mode][color-identifiers]] mode will colorize only identifiers recognized as variables.
- [[https://julien.danjou.info/projects/emacs-packages][rainbow-mode]] displays strings representing colors with the color they
  represent as background.
- [[https://github.com/syl20bnr/nyan-mode][nyan-mode]] display a Nyan cat progress bar in the mode-line.

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =colors= to the existing =dotspacemacs-configuration-layers= list in this
file.

* Configuration
** Colorize identifiers
To colorize variable identifiers using color-identifiers and its supported languages,
set the layer variable =colors-colorize-identifiers= to =variables=.

If you want to colorize all identifiers using the more universal rainbow-identifiers
method instead, set the layer variable =colors-colorize-identifiers= to =all=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (colors :variables colors-colorize-identifiers 'all)))
#+END_SRC

When using the value =all= (rainbow-identifiers method), the Saturation and Lightness
used for colors can be set on a per-theme basis by adding an entry to the variable
=colors-theme-identifiers-sat&light=. This is an alist where the key is a theme symbol
and the value is a pair =(saturation lightness)=.

For now, saturation and lightness are not supported via a =variables= value!
Instead, you must push themes into the alist in your =dotspacemacs/user-config= section,
and then refresh the values to ensure your overrides are applied to your current theme.

Example:

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs/user-config ()
    ;; add per-theme sat&light overrides and refresh values for your current theme
    (push '(mytheme . (50 50)) colors-theme-identifiers-sat&light)
    (push '(anothertheme . (90 40)) colors-theme-identifiers-sat&light)
    (colors//tweak-theme-colors spacemacs--cur-theme)
    )
#+END_SRC

** Enable Nyan cat
To enable the package =nyan-mode= just set the variable
=colors-enable-nyan-cat-progress-bar= to =t=:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (colors :variables colors-enable-nyan-cat-progress-bar t)))
#+END_SRC

It may be handy to enable it only when Emacs is running in a GUI.
You can do that by using a quasi-quoted list which checks the Emacs mode:

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (colors :variables
            colors-enable-nyan-cat-progress-bar (display-graphic-p))))
#+END_SRC

* Key bindings
** Colorize Identifiers

| Key Binding   | Description                                                           |
|---------------+-----------------------------------------------------------------------|
| ~SPC t C a~   | colorize all identifiers in current buffer (rainbow-identifiers mode) |
| ~SPC t C C-a~ | globally colorize all identifiers and all subsequent buffers          |
| ~SPC t C v~   | colorize only variables in current buffer (color-identifiers mode)    |
| ~SPC t C C-v~ | globally colorize only variables and all subsequent buffers           |

The =saturation= and =lightness= of rainbow-identifier mode's colors
can be adjusted live via the following transient-state:

| Key Binding     | Description                              |
|-----------------+------------------------------------------|
| ~SPC C i s~     | initiate change =saturation= mini-mode   |
| ~SPC C i l~     | initiate change =lightness= mini-mode    |
| ~+~             | increase the =saturation= or =lightness= |
| ~-~             | decrease the =saturation= or =lightness= |
| ~=~             | reset the =saturation= or =lightness=    |
| ~Any other key~ | leave the change mini-mode               |

** Rainbow Mode

[[file:img/rainbow-mode.png]]

=rainbow-mode= mode is different from both rainbow-identifiers and color-identifiers.
It can be used together with either (or none) of the identifier colorizers.

All detected color codes in the current buffer will be be highlighted as their
actual color. However, for accurate display, this mode requires that you use
GUI Emacs and that you haven't disabled sRGB mode (if your platform uses that).

To enable, you must manually toggle it on and off on a per-buffer basis with:

 ~SPC t C c~

** Nyan Mode

=nyan-mode= mode can be toggled on and off with:

 ~SPC t m n~

Note that the toggle is local to the current buffer.