aboutsummaryrefslogtreecommitdiff
path: root/docs/expressions.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/expressions.rst')
-rw-r--r--docs/expressions.rst89
1 files changed, 89 insertions, 0 deletions
diff --git a/docs/expressions.rst b/docs/expressions.rst
new file mode 100644
index 0000000..6f9e645
--- /dev/null
+++ b/docs/expressions.rst
@@ -0,0 +1,89 @@
+.. _expr:
+
+Expressions
+===========
+
+One of the aims of the ``thcolor`` module was to decode text-based expressions
+representing colors with possibilities challenging and even outdo
+CSS color expression possibilities. This is what the following static method
+is for:
+
+.. automethod:: thcolor.Color.from_text
+
+Expression 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:
+
+.. autoclass:: thcolor.Reference.number
+ :members:
+
+.. autoclass:: thcolor.Reference.percentage
+ :members:
+
+.. autoclass:: thcolor.Reference.angle
+ :members:
+
+.. autoclass:: thcolor.Reference.color
+ :members:
+
+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/)
+
+In case of incorrectly formatted string, the following exception is returned:
+
+.. autoexception:: thcolor.ColorExpressionDecodingError
+ :members:
+
+Defining a reference
+--------------------
+
+Functions and color names are defined in a reference:
+
+- color names are defined behind an overload of
+ :meth:`thcolor.Reference._color`.
+- functions are defined as reference class methods and use `type hints
+ <https://www.python.org/dev/peps/pep-0484/>`_ to describe the types
+ they are expecting.
+
+The reference must be a derivative of the following class:
+
+.. autoclass:: thcolor.Reference
+ :members: _color, functions, colors, default
+
+Builtin references
+------------------
+
+The following references are defined:
+
+.. autoclass:: thcolor.CSS1Reference
+
+.. autoclass:: thcolor.CSS2Reference
+
+.. autoclass:: thcolor.CSS3Reference
+
+.. autoclass:: thcolor.CSS4Reference
+
+.. autoclass:: thcolor.DefaultReference