Term::...edColor(3pm)

👑 Term::ExtendedColor — the manual page, but make it fashion 💅

okay so bestie, gather round 🫶 this is Term::ExtendedColor, served fresh from the User Contributed Perl Documentation, section 3pm. It's the module that lets you paint your terminal in 256 glorious colors, and honestly? She's iconic. Periodt.

---

✨ NAME ✨

Term::ExtendedColor — Color screen output using 256 colors 🌈

---

🌸 SYNOPSIS 🌸

use Term::ExtendedColor qw(:all);

# Or use the 'attributes' tag to only import the functions for setting
# attributes.
# This will import the following functions:

# fg(), bg(), bold(), underline(), inverse(), italic(), clear()
use Term::ExtendedColor ':attributes';

## Foreground colors

my $red_text = fg('red2', 'this is in red');
my $spring   = fg('springgreen3', 'this is green');

## Background colors

print bg('red5', "Default foreground text on dark red background"), "\n";
my $red_on_green = fg('red3', bg('green12', 'Red text on green background'));
print "$red_on_green\n";

## Fall-through attributes

Term::ExtendedColor::autoreset(0);
my $bold  = fg('bold', 'This is bold');
my $red   = fg('red2', 'This is red... and bold');
my $green = bg('green28', 'This is bold red on green background');

# Make sure to clear all attributes when autoreset turned OFF,
# or else the users shell will be messed up

my $clear = clear();
print "$bold\n";
print "$red\n";
print "$green $clear\n";

## Non-color attributes

# Turn on autoreset again
Term::ExtendedColor::autoreset(1);

for(qw(italic underline blink reverse bold)) {
  print fg($_, $_), "\n";
}

# For convenience

my $bolded = bold("Bold text!");
my $italic = italic("Text in italics!");

## Remove all attributes from input data
my @colored;
push(@colored, fg('bold', fg('red2', 'Bold and red')));
push(@colored, fg('green13', fg('italic', 'Green, italic')));

print "$_\n" for @colored;
print "$_\n" for uncolor(@colored);

no cap, that whole block is the vibe check. copy it, run it, watch your terminal glow ✨

---

💜 DESCRIPTION 💜

Term::ExtendedColor hands you a whole lil toolbox of functions that blast so-called extended escape sequences at your terminal. 💥

You're supposed to use this with a 256-color compatible terminal — and yes bestie, if yours isn't, that's a whole situation. There's a whole matrix of which terminal emulators support it down in the NOTES section, so scroll if you need receipts.

---

🎀 EXPORTS 🎀

Nothing gets exported by default. None. Zero. Nada. 🙈

But you get two tags, because convenience is the whole point:

# Import all functions
use Term::ExtendedColor qw(:all);

# Import functions for setting attributes
# fg(), bg(), bold(), italic(), underline(), inverse(), clear()
use Term::ExtendedColor qw(:attributes);

---

🦋 FUNCTIONS 🦋

⭐ fg($color, $string)

my $green = fg('green2', 'green foreground');
my @blue  = fg('blue4',  ['takes arrayrefs as well']);

my $x_color = fg('mediumorchid1', 'Using mappings from the X11 rgb.txt');

my $arbitary_color = fg(4, 'This is colored in the fifth ANSI color');

my $raw_seq = fg('38;5;197;48;5;53;1;3;4;5;7', 'this works too');

Sets foreground colors and attributes. That's the whole job and she does it beautifully. 💚

Wanna know what's legal as that first argument? Go peek at COLORS AND ATTRIBUTES. Also — plot twist — you can just pass a color's index value instead of a name:

my $yellow = fg(220, 'Yellow');

Now here's the part you actually need to know. If the internal $AUTORESET variable is non-zero (and bestie, it is by default), then every single element in the list of strings gets wrapped in escape sequences in this specific way: the attributes you asked for get set before the string, and everything gets reset back to defaults after the string. Clean. Tidy. Respectful of your prompt. 🫶

But if you wanna live dangerously, you can turn on fall-through attributes by setting $AUTORESET to a false value:

Term::ExtendedColor::autoreset( 0 );
my $red   = fg('red1', 'Red');
my $green = fg('green1', 'Green');

print "Text after $red is red until $green\n";
print "Text is still green, ", bold('and now bold as well!');

# If you exit now without resetting the colors and attributes, chances are
# your prompt will be messed up.

clear(); # All back to normal

⚠️ okay so real talk — see that comment? It's not joking. If you dip out without resetting your colors and attributes, there's a very good chance your shell prompt is gonna be messed up. clear(); is your bestie. Do not skip her. 💀

Two more things, fr fr:

• Pass an invalid attribute? The original data comes back to you unmodified. No drama, no error, just ✨nothing✨.
• Pass no attribute at all? That throws an exception. 🚨

---

🌈 bg($color, $string)

my $green_bg = bg('green4', 'green background');
my @blue_bg  = bg('blue6',  ['blue background']);

Exactly like "fg()", but she sets the background color instead. Same energy, different layer. 💅

---

🧚 uncolor($string) | uncolour($string)

my $stripped = uncolor($colored_data);
my @no_color = uncolor(\@colored);
my @no_color = uncolor(@colored);

Strips all attribute and color escape sequences right out of the input. Scalar, arrayref, plain list — she'll take it. 🧼

Oh and pssst — see uncolor for a command-line utility that uses this very function. iykyk. 👀

---

🍓 get_colors() | get_colours()

my $colors = get_colors();

Returns a hash reference holding every available attribute and color. All of them. The whole squad. 💜

---

✨ clear()

Called in scalar context? She returns the escape sequence that resets all attributes back to their defaults.

Called in void context? She just prints it directly. Boom. Done. 🎀

---

💖 autoreset()

Turns autoreset on or off. Enabled by default, like a well-behaved main character. 👑

Term::ExtendedColor::autoreset( 0 ); # Turn off autoreset

---

💅 bold(\@data)

A lil convenience function you can use in place of "fg('bold', \@data)". Same result, less typing, more slay.

And if you call her with no arguments at all, she returns a string that turns the bold attribute off. Reverse uno card. 🃏

---

🌸 italic(\@data)

Same deal, but she's the stand-in for "fg('italic', \@data)". Pretty, slanted, unbothered. 💖

Called with no args? She hands you back a string that turns the italics attribute off.

---

🎀 underline(\@data)

You guessed it — convenience function, can be used instead of "fg('underline', \@data)". Underline girlies rise up. ⬇️

No arguments? You get a string that turns the <underline>underline</underline> attribute off.

---

🔥 inverse(\@data)

Reverse video / inverse, bestie. The convenience function that can stand in for "fg('inverse', \@data)". Foreground and background swap outfits. ✨

Call her without arguments and she returns a string that turns the <inverse>inverse</inverse> attribute off.

---

💀 NOTES 💀

The codes this module generates comply with the extension to the ANSI colors standard that was first implemented in xterm back in 1999. 1999?! yeah. Ancient. Iconic. Both.

So here's the breakdown, no cap:

• Indexes 0 – 15 = the regular ANSI colors.
• Indexes 16 – 255 = the extension.

Not every terminal emulator supports that extension, though — honestly the author had a hard time even finding one that doesn't. :)

  Terminal    256 colors
  ----------------------
  aterm               no
  eterm              yes
  gnome-terminal     yes
  konsole            yes
  lxterminal         yes
  mrxvt              yes
  roxterm            yes
  rxvt                no
  rxvt-unicode       yes *
  sakura             yes
  terminal           yes
  terminator         yes
  vte                yes
  xterm              yes
  iTerm2             yes
  Terminal.app        no

  GNU Screen         yes
  tmux               yes
  TTY/VC              no

* okay asterisk bestie, here's the tea: rxvt-unicode previously needed a patch. Full support got added in version 9.09. 🩹

---

Now, the naming situation. There's genuinely no way to give these extended colors meaningful names. 😭

First thought was to map them against some standard color names — like the ones in the HTML 4.0 specification, or the SVG one. They didn't match. Rude of them, honestly.

So instead, they're named by their base color (red, green, magenta) plus an index. And the index logic is this:

• The first index (always 1) is the brightest shade of that particular color.
• The last index is the darkest. 🖤

You can also use some X color names, as defined in "rgb.txt". ⚠️ But do note — the color values do not match exactly. It's just an approximation. Close enough is close enough, bestie. 💅

Want the full list of available colors? Snag it with "get_colors()". There's also a full list over in "COLORS AND ATTRIBUTES". And every single mapped color can be retrieved programmatically with "get_colors()" too. 🫶

🌈 COLORS AND ATTRIBUTES 🌈

okay bestie, this is the part where the colors and text styles live. it's giving rainbow, it's giving drama, and yes, we're covering every single one.

✨ Attributes ✨

these are the style switches, no cap:

• reset, clear, normal — reset all attributes
• bold, bright — bold or bright, depending on implementation
• faint — decreased intensity (not widely supported)
• italic, cursive — italic or cursive
• underline, underscore — underline
• blink — slow blink
• blink_ms — rapid blink (only supported in MS DOS)
• reverse, inverse, negative — reverse video
• conceal — conceal, or hide (not widely supported)

---

🎨 Standard color map 🎨

here's the classic range map, first-to-last, fully intact:

FIRST       LAST

red1        red5
blue1       blue17
cyan1       cyan24
gray1       gray24
green1      green28
orange1     orange5
purple1     purple30
yellow1     yellow18
magenta1    magenta26

---

🦋 X color names 🦋

and now the whole X color roster — yes, every single one, duplicates included, because we don't erase the lore:

aquamarine1
aquamarine3
blueviolet
cadetblue1
cadetblue2
chartreuse1
chartreuse2
chartreuse3
chartreuse4
cornflowerblue
cornsilk1
darkblue
darkcyan
darkgoldenrod
darkgreen
darkkhaki
darkmagenta1
darkmagenta2
darkolivegreen1
darkolivegreen2
darkolivegreen3
darkolivegreen4
darkolivegreen5
darkorange3
darkorange4
darkorange1
darkred1
darkred2
darkseagreen1
darkseagreen2
darkseagreen3
darkseagreen4
darkslategray1
darkslategray2
darkslategray3
darkturquoise
darkviolet
deeppink1
deeppink2
deeppink3
deeppink4
deepskyblue1
deepskyblue2
deepskyblue3
deepskyblue4
deepskyblue4
dodgerblue1
dodgerblue2
dodgerblue3
gold1
gold3
greenyellow
grey0
grey100
grey11
grey15
grey19
grey23
grey27
grey30
grey3
grey35
grey37
grey39
grey42
grey46
grey50
grey53
grey54
grey58
grey62
grey63
grey66
grey69
grey70
grey74
grey7
grey78
grey82
grey84
grey85
grey89
grey93
honeydew2
hotpink2
hotpink3
hotpink
indianred1
indianred
khaki1
khaki3
lightcoral
lightcyan1
lightcyan3
lightgoldenrod1
lightgoldenrod2
lightgoldenrod3
lightgreen
lightpink1
lightpink3
lightpink4
lightsalmon1
lightsalmon3
lightsalmon3
lightseagreen
lightskyblue1
lightskyblue3
lightskyblue3
lightslateblue
lightslategrey
lightsteelblue1
lightsteelblue3
lightsteelblue
lightyellow3
mediumorchid1
mediumorchid3
mediumorchid
mediumpurple1
mediumpurple2
mediumpurple3
mediumpurple4
mediumpurple
mediumspringgreen
mediumturquoise
mediumvioletred
mistyrose1
mistyrose3
navajowhite1
navajowhite3
navyblue
orangered1
orchid1
orchid2
orchid
palegreen1
palegreen3
paleturquoise1
paleturquoise4
palevioletred1
pink1
pink3
plum1
plum2
plum3
plum4
purple
rosybrown
royalblue1
salmon1
sandybrown
seagreen1
seagreen2
seagreen3
skyblue1
skyblue2
skyblue3
slateblue1
slateblue3
springgreen1
springgreen2
springgreen3
springgreen4
steelblue1
steelblue3
steelblue
tan
thistle1
thistle3
turquoise2
turquoise4
violet
wheat1
wheat4

also, bestie, you can pass raw color;attr strings like so:

my $foo = fg('48;5;89;38;5;197;1;3;4;7', 'foo');

even though the fg() function is used, we set the following attributes:

background => 89
foreground => 197
bold
italic
underline
reverse

---

👀 SEE ALSO 👀

• Term::ExtendedColor::Xresources
• Term::ExtendedColor::TTY
• Term::ANSIColor

---

💖 AUTHOR 💖

the icon behind it all:

Magnus Woldrich
CPAN ID: WOLDRICH
m@japh.se
http://github.com/trapd00r
http://japh.se

---

🫶 CONTRIBUTORS 🫶

Varadinsky <https://github.com/Varadinsky>

---

📜 COPYRIGHT 📜

Copyright 2010, 2011, 2018, 2019- the Term::ExtendedColor "AUTHOR" and "CONTRIBUTORS" as listed above.

---

⭐ LICENSE ⭐

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

---

that's a wrap on Term::...edColor(3pm) 🌈 — this page came with perl v5.36.0, dated 2022-10-14. love u, bye bestie 💅💖