#+TITLE: Colors layer

#+TAGS: layer|theme

[[file:img/rainbow_dash.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#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 by enhancing the existing coloration of identifiers as well as providing you with a more colorful
process indicator.

** Features:
- Colorize all identifiers (christmas tree mode :-)) with mostly unique colors, and the ability to choose saturation and lightness
  with [[https://github.com/Fanael/rainbow-identifiers][rainbow-identifiers]].
- Colorize only identifiers recognized as variables with [[https://github.com/ankurdave/color-identifiers-mode][color-identifiers]].
- Colorize strings representing colors with the color they represent as background with
  [[https://jblevins.org/log/rainbow-mode][rainbow-mode]].
- Display a Nyan cat progress bar in the mode-line with [[https://github.com/syl20bnr/nyan-mode][nyan-mode]].

* 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.

Two handy built-in functions makes both of those steps very easy.

Example:

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

For all themes that lack per-theme overrides, it uses default saturation and lightness.
You can configure your own defaults via =colors-default-rainbow-identifiers-sat=
and =colors-default-rainbow-identifiers-light=, which can be set via =variables=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (colors :variables
      colors-colorize-identifiers 'all
      colors-default-rainbow-identifiers-sat 42
      colors-default-rainbow-identifiers-light 86)
    )
#+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.