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.