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

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.