NAME ColorTheme - Color themes SPECIFICATION VERSION 2 VERSION This document describes version 2.0.1 of ColorTheme (from Perl distribution ColorTheme), released on 2020-06-08. DESCRIPTION This document specifies a way to create and use color themes. GLOSSARY color theme Essentially, a mapping of item names and color codes. For example, a color theme for syntax-coloring JSON might be something like: { string => "ffff00", number => "00ffff", comma => "", brace => "", bracket => "", null => "ff0000", true => "00ff00", false => "008000", } An application (in this case, a JSON pretty-printer) will consult the color theme to get the color codes for various items. By using a different color theme which contains the same item names, a user can change the appearance of an application or its output (in terms of color) simply by using another compatible color theme, i.e. color theme which provides color codes for the same items. color theme structure A DefHash which contains the "color theme" and additional data. A simple (static) theme has all its information accessible from the color theme structure. color theme class A Perl module in the "ColorTheme::*" or "SOME::APP::ColorTheme::*" namespace following this specification. A color theme class contains "color theme structure" in its %THEME package variable, as well as some required methods to access the information in the structure. A simple (static) theme has all its information accessible from the color theme structure, so client can actually bypass the methods and access the color theme structure directly. Although it is recommended to always use the methods to access information in the color theme. static color theme A color theme where all the items are specified in the color theme structure. A client can by-pass the method and access %THEME directly. See also: "dynamic color theme". dynamic color theme A color theme where one must call "/list_items" to get all the items, because not all (or any) of the items are specified in the color theme structure. A dynamic color theme can produce items on-demand or transform other color themes, e.g. provide a tint or duotone color effect on an existing theme. When a color theme is dynamic, it must set the property "dynamic" in the color theme structure to true. See also: "static color theme". SPECIFICATION Color theme class A color theme class must be put in "ColorTheme::" namespace, or for application-specific themes, in "SOME::APP::ColorTheme::*", where "SOME::APP" is an application namespace. The color theme class must declare a package hash variable named %THEME containing the color theme structure. It also must provide these methods: * new Usage: my $theme_class = ColorTheme::NAME->new([ %args ]); Constructor. Known arguments will depend on the particular theme class and must be specified in the color theme structure under the "args" key. * list_items Usage: my @item_names = $theme_class->list_items; my $item_names = $theme_class->list_items; Must return list of item names provided by theq theme. Each item has a color associated with it and the color can be retrieved using "get_color". * get_color Usage: my $color = $theme_class->get_color($item_name [ , \%args ]); Get color for an item. The color can be a single RGB value, e.g. "ffcc00" or a DefHash e.g. "{fg=>'ffcc00', bg=>'333333', summary=>'...'}" (all keys optional). Color theme structure Color theme structure is a DefHash containing these keys: * v Required. Float. From DefHash. Must be set to 2 (this specification version). * summary String. Optional. From DefHash. * description String. Optional. From DefHash. * args Hash of argument names as keys, and argument specification DefHash as values. The argument specification resembles that specified in Rinci::function. Some of the important or relevant properties: "req", "schema", "default". * dynamic Boolean, optional. Must be set to true if the theme class is dynamic, i.e. the "colors" property does not contain all (or even any) of the items of the theme. Client must call "list_items" to list all the items in the theme. * colors Required. Hash of item names as keys and colors as values. Color can be a single RGB value, e.g. "ffcc00" or a DefHash e.g. "{fg=>'ffcc00', bg=>'cc0000', ansi_fg=>..., ansi_bg=>..., summary=>..., ...}" (all keys optional) or a coderef. The coderef will be supplied arguments of "get_color" and is expected to retruen an RGB string or a DefHash. A DefHash color containing multiple color codes is used to support specifying foreground/background values or ANSI color codes that are not representable by RGB, among other things. You can also put summary and additional information in the DefHash. Allowing coderef as color allows for flexibility, e.g. for doing gradation border color, random color, etc. HISTORY Color::Theme is an older specification, superseded by this document. HOMEPAGE Please visit the project's homepage at . SOURCE Source repository is at . BUGS Please report any bugs or feature requests on the bugtracker website When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. SEE ALSO DefHash AUTHOR perlancar COPYRIGHT AND LICENSE This software is copyright (c) 2020, 2018, 2014 by perlancar@cpan.org. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.