Graphics::Toolkit::Color::Manual::Format(3)

NAME
Graphics::Toolkit::Color::Manual::Format - shapes of acceptable color definitions

SYNOPSIS
This manual page lists and describes all forms a color definition may have. A color definition is a piece of data that defines a color unambiguously and from which GTC can create a color object. It is a rule of the GTC philosophy that every format that can be read should also be produced as output and vice versa. This principle is held up with the exception of the "list" and "array" formats. Values from any color space can be written in these formats but when read, RGB is assumed, because there is no attached information about the color space. See a quick overview of all formats here.

This page is especially important to understand the capabilities of the methods new and values.

FORMATS

  name
The format "name" refers to a color name string like:

    'blue'

and a full_name contains also a color scheme name like in:

    'SVG:green'

Read all about them under "SYNTAX" in Graphics::Toolkit::Color::Manual::Name. They are read by the constructor but written by name and closest_name. There you can provide the argument "full" to get a full name.

  hex_string
A "hex_string" starts with the pound sign '#' followed by three (short version) or six (long version) hexadecimal digits that might be written in upper or lower case. It always depicts an RGB color. The following examples represent the same color:

    '#123'
    '#112233'

  named_string
"named_string" is GTC's own simple string format for data serialisation. Similar to a "full_name" it has the color space name on the left side of the colon in lower case and without any special characters. Right of the colon are the comma separated values. The placement of any whitespace is optional but the commas are not. Also optional are value suffixes like '%' in HWB.

    'rgb: 1, 2, 3'

  css_string
"css_string" is a format standardized by the W3C that is closely related to a "named_string" with a few important differences. Here are the commas and the suffix optional. But if you omit the commas, you have to separate the values by whitespace. And the values have to be encompassed by round braces. GTC does not yet support a "css_string" that includes an alpha channel.

    'rgb( 1, 2, 3)'

  list
"list" is the default format of the values method. It is simply a list with the color values. They follow the same order as the axis names. If used as an input, GTC reads them as standard RGB values.

    (1,2,3)

  array
"array" is just a list inside square brackets (ARRAY reference), hence almost the same rules apply as for "list" (it's read as RGB by default). This format has the sole advantage over a "list", that it is from a Perl perspective a scalar and can be therefore used for an argument like to in methods like distance. You may use it for values in other spaces too but then you have to provide the space name via the argument in.

    [1,2,3]

  named_array
"named_array" fixes the disadvantage of the "array" format by prepending the color space name in front of the values. Color space names can be written with a great degree of freedom, which is explained here. Please note the usage of a fat comma for your own convenience. Both examples are semantically identical.

    [ RGB =>  1,2,3 ]
    ['RGB',   1,2,3 ]

  nested_array
"nested_array" is just a variation on a "named_array", where the values are enclosed in another ARRAY reference. To some people it just makes intuitively more sense.

    [RGB => [1,2,3]]

  hash
"hash" is the most expressive and spacious format. It is a HASH reference with long axis names as keys. It requires all axes to be presented by name, even if GTC will accept any mix of long and short axis names. If you order "hash" as output format you will get long axis names only. The biggest downside of this format is its ambiguity, especially because GTC supports over 10 RGB spaces. Please read about the search order to see which and how spaces get overshadowed by others. In short, look at the name of a color space family to see which space is dominant. If you want to define a color in a color space that is not dominant, you have to either use another format that contains the color space name or you provide the space name via the argument in.

    {red => 1, green => 2, blue => 3}

  char_hash
"char_hash" is the format name to make sure the output of values is a HASH with short axis names as keys. Other than that - it's the same as "hash".

    {r => 1, g => 2, b => 3}

AUTHOR
Herbert Breunung, <lichtkind@cpan.org>

COPYRIGHT
Copyright 2026 Herbert Breunung.

LICENSE
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.