/ 
ColorTheme-2.1.5
River stage one • 1 direct dependent • 1 total dependent
/ ColorTheme

NAME

ColorTheme - Color themes

SPECIFICATION VERSION

2

VERSION

This document describes version 2.1.5 of ColorTheme (from Perl distribution ColorTheme), released on 2024-07-17.

DESCRIPTION

This document specifies a way to create and use color themes.

If you want a quick way to create a color theme module, modify an existing one for a specific application. For example, for JSON::Color, see ColorTheme::JSON::Color::default_rgb or ColorTheme::JSON::Color::bright256.

SPECIFICATION STATUS

The series 2.x version is still unstable. API might still change between releases.

GLOSSARY

color theme

Essentially, a mapping of item names and item colors. 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::* 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. Application-specific color themes should be put under ColorTheme::MODULE::NAME::* or ColorTheme::APP::NAME::*.

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 $ctheme_obj = 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.

  • get_struct

    Usage:

    my $ctheme_struct = ColorTheme::NAME->get_struct;
my $ctheme_struct = $ctheme_obj->get_struct;

    Provide a method way of getting the "color theme structure". Must also work as a static method. A client can also access the %THEME package variable directly.

  • get_args

    Usage:

    my $args = $ctheme_obj->get_args;

    Provide a method way of getting the arguments to the constructor. The official implementation ColorThemeBase::Constructor stores this in the 'args' key of the hash object, but the proper way to access the arguments should be via this method.

  • 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_item_color

    Usage:

    my $color = $theme_class->get_item_color($item_name [ , \%args ]);

    Get color for an item. See "Item color".

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 "items" 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.

  • items

    Required. Hash of item names as keys and item colors as values. See "Item color".

Item color

The color of an item can be one of three things.

First, the simplest, a single RGB value in the form of 6-hexdigit string, e.g. ffcc00.

Second, a DefHash called "item colors hash" containing one or more of these properties: fg (foreground RGB color), bg (background RGB color), ansi_fg (foreground ANSI escape sequence string), ansi_bg (background ANSI escape sequence string). It can also contain additional information like summary (a summary describing the item), description, tags, and so on. Properties like ansi_fg and ansi_bg are used to support specifying things that are not representable by RGB, e.g. reverse or bold.

Third, a coderef which if called is expected to return one of the two formerly mentioned value (RGB string or the "item colors hash"). A coderef cannot return another coderef. Coderef will be called with arguments ($self, $name, \%args) where $self is the color theme class (from which you can access the color theme structure as well as arguments to the constructor), $name is the item name requested, and \%args is hashref to additional, per-item arguments.

Allowing coderef as color allows for flexibility, e.g. for doing gradation border color, random color, context-sensitive color, etc.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/ColorTheme.

SOURCE

Source repository is at https://github.com/perlancar/perl-ColorTheme.

SEE ALSO

DefHash

Somewhat related: BorderStyle specification, because they are often used together in an application.

HISTORY

Color::Theme is an older specification, superseded by this document.

AUTHOR

perlancar <perlancar@cpan.org>

CONTRIBUTING

To contribute, you can send patches by email/via RT, or send pull requests on GitHub.

Most of the time, you don't need to build the distribution yourself. You can simply modify the code, then test via:

% prove -l

If you want to build the distribution (e.g. to try to install it locally on your system), you can install Dist::Zilla, Dist::Zilla::PluginBundle::Author::PERLANCAR, Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps required beyond that are considered a bug and can be reported to me.

COPYRIGHT AND LICENSE

This software is copyright (c) 2024, 2023, 2020, 2018, 2014 by perlancar <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.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=ColorTheme

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.