NAME
    ColorTheme - Color theme class and color theme structure

SPECIFICATION VERSION
    2

VERSION
    This document describes version 2.0.0 of ColorTheme (from Perl
    distribution ColorTheme), released on 2020-06-07.

DESCRIPTION
    This document specifies ColorTheme classes, classes that contain color
    themes.

GLOSSARY
  Color theme structure
    %THEME package variable declared in the color theme class, containing
    the list of colors.

  Static theme
    A theme where all the items are specified in the %THEME color theme
    structure. For these themes, a client can by-pass the method and access
    %THEME directly.

SPECIFICATION
  Color theme class
    A color theme class must be put in "ColorTheme::" namespace, or for
    application-specific themes, in "YOUR::APP::ColorTheme::*", where
    "YOUR::APP" is your application namespace.

    The color theme class must declare a package hash variable named %THEME
    (color theme structure). It is a DefHash with "v" set to 2 (this
    specification version). See "Color theme structure" for more details.

    Color theme class must also 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.

    *   get_color_list

        Usage:

         my @item_names = $theme_class->get_color_list;
         my $item_names = $theme_class->get_color_list;

        Must return list of item names in this 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. Must be set to 2 (this specification version).

    *   summary

        String. Optional. From DefHash.

    *   description

        String. Optional. From DefHash.

    *   dynamic

        Boolean, optional. Must be set to true if the theme class is not
        static, i.e. the "colors" property does not contain all (or even
        any) of the items of the theme. Client must call "get_color_list" 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.

        Multiple color codes in the DefHash color are used to support
        foreground/background values or ANSI color codes that are not
        representable by RGB, among other things.

        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-Color-Theme>.

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.