diff options
Diffstat (limited to 'docs/expressions.rst')
-rw-r--r-- | docs/expressions.rst | 89 |
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 |