aboutsummaryrefslogtreecommitdiff
path: root/docs/discuss/color-expressions.rst
blob: 0bd3d892fc823baffecd3021f76a44172bfaf258 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
.. _expr:

Color expressions
=================

One of the aims of thcolor was to decode text-based expressions
representing colors with possibilities challenging and even outdo
CSS color expression possibilities. In thcolor, these expressions are
evaluated using :py:meth:`thcolor.decoders.ColorDecoder.decode`,
:py:meth:`thcolor.colors.Color.fromtext` or
:py:meth:`thcolor.angles.Angle.fromtext`.

Concepts
--------

The goal of these expressions was to embrace and extend CSS syntax, so they
are basically either basic expressions or function calls, with the following
argument types:

 * Numbers.
 * Percentages.
 * Angles.
 * Colors.

These elements are separated by separators (either commas, slashes, or simple
spaces) and can be passed to functions, and the calls themselves can be passed
to other functions. A function call is made in the following fashion:

::

	<function name>([<number | percentage | angle | color> [<separator> …]])

If at least one separator (even simple spaces) are required between arguments,
extraneous separators between and after the arguments are ignored. Other than
if spaces are used as separators, spaces around the parenthesis or the
separators (and "between" the separators as spaces are recognized as
separators) are ignored.

Here are some example calls:

::

	rgb(1, 2, 3)
	rgb  ( 1 22 //// 242 , 50.0% ,/,)
	hsl (0 1 50 % / 22)
	gray ( red( #123456 )/0.2/)

.. _explain-decoders:

Decoders
--------

Decoders are the tools within thcolor that handle the actual evaluation of
expressions. They have two important components aside from the decoding
function:

* Options defining the behaviour of base parsing and evaluating.
* A reference of functions, colors and other data indexed by name.

The options currently available are the following:

* Whether natural colors are enabled or not; see :ref:`natural-colors`.
* Whether extended hexadecimal colors, i.e. 4 or 8 digit hexadecimal digits
  preceded with a '#' sign, which includes transparency, are enabled or not.
* Whether names that are not found should be resolved using Netscape-like
  color parsing or not, what is also known as "quirks mode".

The reference contains three kinds of elements, all indexed by name:

* Constants, always to be used as values, e.g. the ``navy`` color.
* Functions, always to be used by calling them, e.g. the ``rgb`` function.
* Functions with fallbacks, which have a behaviour when called and a fallback
  value when used as a value, e.g. the ``red`` function in the extended
  color decoder which extracts the red channel value as a function and acts
  as the color ``red`` if used as a value.

Decoders can be defined using two base classes which act in a very different
way:

* **The manual way.**
  You can define a decoder manually by making it inherit from
  :py:class:`thcolor.decoders.ColorDecoder` and overriding
  ``__mapping__`` to define the reference, and other double-underscore
  properties for options.
* **The user-friendly way.**
  You can define a decoder in an easier way by making it inherit from
  :py:class:`thcolor.decoders.MetaColorDecoder` and defining options,
  functions and data by defining them directly in the class body;
  see :ref:`defining-decoders` for more information.