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
    <https://metacpan.org/release/ColorTheme>.

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

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.

SEE ALSO
    DefHash

AUTHOR
    perlancar <perlancar@cpan.org>

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.

