{
"content": [
{
"type": "text",
"text": "# Term::ANSIColor (perldoc)\n\n**Summary:** Term::ANSIColor - Color screen output using ANSI escape sequences\n\n**Synopsis:** use Term::ANSIColor;\nprint color('bold blue');\nprint \"This text is bold blue.\\n\";\nprint color('reset');\nprint \"This text is normal.\\n\";\nprint colored(\"Yellow on magenta.\", 'yellow onmagenta'), \"\\n\";\nprint \"This text is normal.\\n\";\nprint colored(['yellow onmagenta'], 'Yellow on magenta.', \"\\n\");\nprint colored(['red onbrightyellow'], 'Red on bright yellow.', \"\\n\");\nprint colored(['brightred onblack'], 'Bright red on black.', \"\\n\");\nprint \"\\n\";\n# Map escape sequences back to color names.\nuse Term::ANSIColor 1.04 qw(uncolor);\nmy @names = uncolor('01;31');\nprint join(q{ }, @names), \"\\n\";\n# Strip all color escape sequences.\nuse Term::ANSIColor 2.01 qw(colorstrip);\nprint colorstrip(\"\\e[1mThis is bold\\e[0m\"), \"\\n\";\n# Determine whether a color is valid.\nuse Term::ANSIColor 2.02 qw(colorvalid);\nmy $valid = colorvalid('blue bold', 'onmagenta');\nprint \"Color string is \", $valid ? \"valid\\n\" : \"invalid\\n\";\n# Create new aliases for colors.\nuse Term::ANSIColor 4.00 qw(coloralias);\ncoloralias('alert', 'red');\nprint \"Alert is \", coloralias('alert'), \"\\n\";\nprint colored(\"This is in red.\", 'alert'), \"\\n\";\nuse Term::ANSIColor qw(:constants);\nprint BOLD, BLUE, \"This text is in bold blue.\\n\", RESET;\nuse Term::ANSIColor qw(:constants);\n{\nlocal $Term::ANSIColor::AUTORESET = 1;\nprint BOLD BLUE \"This text is in bold blue.\\n\";\nprint \"This text is normal.\\n\";\n}\nuse Term::ANSIColor 2.00 qw(:pushpop);\nprint PUSHCOLOR RED ONGREEN \"This text is red on green.\\n\";\nprint PUSHCOLOR BRIGHTBLUE \"This text is bright blue on green.\\n\";\nprint RESET BRIGHTBLUE \"This text is just bright blue.\\n\";\nprint POPCOLOR \"Back to red on green.\\n\";\nprint LOCALCOLOR GREEN ONBLUE \"This text is green on blue.\\n\";\nprint \"This text is red on green.\\n\";\n{\nlocal $Term::ANSIColor::AUTOLOCAL = 1;\nprint ONBLUE \"This text is red on blue.\\n\";\nprint \"This text is red on green.\\n\";\n}\nprint POPCOLOR \"Back to whatever we started as.\\n\";\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (56 lines)\n- **DESCRIPTION** (2 lines) — 13 subsections\n - coloralias (6 lines)\n - Supported Colors (48 lines)\n - Function Interface (52 lines)\n - color (7 lines)\n - colored (1 lines)\n - colored (22 lines)\n - uncolor (5 lines)\n - colorstrip (4 lines)\n - colorvalid (3 lines)\n - coloralias (28 lines)\n - Constant Interface (73 lines)\n - The Color Stack (34 lines)\n - Supporting CLICOLOR (21 lines)\n- **DIAGNOSTICS** (60 lines)\n- **ENVIRONMENT** (46 lines)\n- **COMPATIBILITY** (11 lines) — 1 subsections\n - colorstrip (24 lines)\n- **RESTRICTIONS** (28 lines)\n- **NOTES** (50 lines)\n- **AUTHORS** (6 lines)\n- **COPYRIGHT AND LICENSE** (9 lines)\n- **SEE ALSO** (27 lines)\n\n## Full Content\n\n### NAME\n\nTerm::ANSIColor - Color screen output using ANSI escape sequences\n\n### SYNOPSIS\n\nuse Term::ANSIColor;\nprint color('bold blue');\nprint \"This text is bold blue.\\n\";\nprint color('reset');\nprint \"This text is normal.\\n\";\nprint colored(\"Yellow on magenta.\", 'yellow onmagenta'), \"\\n\";\nprint \"This text is normal.\\n\";\nprint colored(['yellow onmagenta'], 'Yellow on magenta.', \"\\n\");\nprint colored(['red onbrightyellow'], 'Red on bright yellow.', \"\\n\");\nprint colored(['brightred onblack'], 'Bright red on black.', \"\\n\");\nprint \"\\n\";\n\n# Map escape sequences back to color names.\nuse Term::ANSIColor 1.04 qw(uncolor);\nmy @names = uncolor('01;31');\nprint join(q{ }, @names), \"\\n\";\n\n# Strip all color escape sequences.\nuse Term::ANSIColor 2.01 qw(colorstrip);\nprint colorstrip(\"\\e[1mThis is bold\\e[0m\"), \"\\n\";\n\n# Determine whether a color is valid.\nuse Term::ANSIColor 2.02 qw(colorvalid);\nmy $valid = colorvalid('blue bold', 'onmagenta');\nprint \"Color string is \", $valid ? \"valid\\n\" : \"invalid\\n\";\n\n# Create new aliases for colors.\nuse Term::ANSIColor 4.00 qw(coloralias);\ncoloralias('alert', 'red');\nprint \"Alert is \", coloralias('alert'), \"\\n\";\nprint colored(\"This is in red.\", 'alert'), \"\\n\";\n\nuse Term::ANSIColor qw(:constants);\nprint BOLD, BLUE, \"This text is in bold blue.\\n\", RESET;\n\nuse Term::ANSIColor qw(:constants);\n{\nlocal $Term::ANSIColor::AUTORESET = 1;\nprint BOLD BLUE \"This text is in bold blue.\\n\";\nprint \"This text is normal.\\n\";\n}\n\nuse Term::ANSIColor 2.00 qw(:pushpop);\nprint PUSHCOLOR RED ONGREEN \"This text is red on green.\\n\";\nprint PUSHCOLOR BRIGHTBLUE \"This text is bright blue on green.\\n\";\nprint RESET BRIGHTBLUE \"This text is just bright blue.\\n\";\nprint POPCOLOR \"Back to red on green.\\n\";\nprint LOCALCOLOR GREEN ONBLUE \"This text is green on blue.\\n\";\nprint \"This text is red on green.\\n\";\n{\nlocal $Term::ANSIColor::AUTOLOCAL = 1;\nprint ONBLUE \"This text is red on blue.\\n\";\nprint \"This text is red on green.\\n\";\n}\nprint POPCOLOR \"Back to whatever we started as.\\n\";\n\n### DESCRIPTION\n\nThis module has two interfaces, one through color() and colored() and the other through\nconstants. It also offers the utility functions uncolor(), colorstrip(), colorvalid(), and\n\n#### coloralias\n\nIf you are using Term::ANSIColor in a console command, consider supporting the CLICOLOR\nstandard. See \"Supporting CLICOLOR\" for more information.\n\nSee \"COMPATIBILITY\" for the versions of Term::ANSIColor that introduced particular features and\nthe versions of Perl that included them.\n\n#### Supported Colors\n\nTerminal emulators that support color divide into four types: ones that support only eight\ncolors, ones that support sixteen, ones that support 256, and ones that support 24-bit color.\nThis module provides the ANSI escape codes for all of them. These colors are referred to as ANSI\ncolors 0 through 7 (normal), 8 through 15 (16-color), 16 through 255 (256-color), and true color\n(called direct-color by xterm).\n\nUnfortunately, interpretation of colors 0 through 7 often depends on whether the emulator\nsupports eight colors or sixteen colors. Emulators that only support eight colors (such as the\nLinux console) will display colors 0 through 7 with normal brightness and ignore colors 8\nthrough 15, treating them the same as white. Emulators that support 16 colors, such as\ngnome-terminal, normally display colors 0 through 7 as dim or darker versions and colors 8\nthrough 15 as normal brightness. On such emulators, the \"normal\" white (color 7) usually is\nshown as pale grey, requiring bright white (15) to be used to get a real white color. Bright\nblack usually is a dark grey color, although some terminals display it as pure black. Some\nsixteen-color terminal emulators also treat normal yellow (color 3) as orange or brown, and\nbright yellow (color 11) as yellow.\n\nFollowing the normal convention of sixteen-color emulators, this module provides a pair of\nattributes for each color. For every normal color (0 through 7), the corresponding bright color\n(8 through 15) is obtained by prepending the string \"bright\" to the normal color name. For\nexample, \"red\" is color 1 and \"brightred\" is color 9. The same applies for background colors:\n\"onred\" is the normal color and \"onbrightred\" is the bright color. Capitalize these strings\nfor the constant interface.\n\nThere is unfortunately no way to know whether the current emulator supports more than eight\ncolors, which makes the choice of colors difficult. The most conservative choice is to use only\nthe regular colors, which are at least displayed on all emulators. However, they will appear\ndark in sixteen-color terminal emulators, including most common emulators in UNIX X\nenvironments. If you know the display is one of those emulators, you may wish to use the bright\nvariants instead. Even better, offer the user a way to configure the colors for a given\napplication to fit their terminal emulator.\n\nFor 256-color emulators, this module additionally provides \"ansi0\" through \"ansi15\", which are\nthe same as colors 0 through 15 in sixteen-color emulators but use the 256-color escape syntax,\n\"grey0\" through \"grey23\" ranging from nearly black to nearly white, and a set of RGB colors. The\nRGB colors are of the form \"rgb*RGB*\" where *R*, *G*, and *B* are numbers from 0 to 5 giving the\nintensity of red, green, and blue. The grey and RGB colors are also available as \"ansi16\"\nthrough \"ansi255\" if you want simple names for all 256 colors. \"on\" variants of all of these\ncolors are also provided. These colors may be ignored completely on non-256-color terminals or\nmay be misinterpreted and produce random behavior. Additional attributes such as blink, italic,\nor bold may not work with the 256-color palette.\n\nFor true color emulators, this module supports attributes of the form \"r*NNN*g*NNN*b*NNN*\" and\n\"onr*NNN*g*NNN*b*NNN*\" for all values of *NNN* between 0 and 255. These represent foreground\nand background colors, respectively, with the RGB values given by the *NNN* numbers. These\ncolors may be ignored completely on non-true-color terminals or may be misinterpreted and\nproduce random behavior.\n\n#### Function Interface\n\nThe function interface uses attribute strings to describe the colors and text attributes to\nassign to text. The recognized non-color attributes are clear, reset, bold, dark, faint, italic,\nunderline, underscore, blink, reverse, and concealed. Clear and reset (reset to default\nattributes), dark and faint (dim and saturated), and underline and underscore are equivalent, so\nuse whichever is the most intuitive to you.\n\nNote that not all attributes are supported by all terminal types, and some terminals may not\nsupport any of these sequences. Dark and faint, italic, blink, and concealed in particular are\nfrequently not implemented.\n\nThe recognized normal foreground color attributes (colors 0 to 7) are:\n\nblack red green yellow blue magenta cyan white\n\nThe corresponding bright foreground color attributes (colors 8 to 15) are:\n\nbrightblack brightred brightgreen brightyellow\nbrightblue brightmagenta brightcyan brightwhite\n\nThe recognized normal background color attributes (colors 0 to 7) are:\n\nonblack onred ongreen on yellow\nonblue onmagenta oncyan onwhite\n\nThe recognized bright background color attributes (colors 8 to 15) are:\n\nonbrightblack onbrightred onbrightgreen onbrightyellow\nonbrightblue onbrightmagenta onbrightcyan onbrightwhite\n\nFor 256-color terminals, the recognized foreground colors are:\n\nansi0 .. ansi255\ngrey0 .. grey23\n\nplus \"rgb*RGB*\" for *R*, *G*, and *B* values from 0 to 5, such as \"rgb000\" or \"rgb515\".\nSimilarly, the recognized background colors are:\n\nonansi0 .. onansi255\nongrey0 .. ongrey23\n\nplus \"onrgb*RGB*\" for *R*, *G*, and *B* values from 0 to 5.\n\nFor true color terminals, the recognized foreground colors are \"r*RRR*g*GGG*b*BBB*\" for *RRR*,\n*GGG*, and *BBB* values between 0 and 255. Similarly, the recognized background colors are\n\"onr*RRR*g*GGG*b*BBB*\" for *RRR*, *GGG*, and *BBB* values between 0 and 255.\n\nFor any of the above listed attributes, case is not significant.\n\nAttributes, once set, last until they are unset (by printing the attribute \"clear\" or \"reset\").\nBe careful to do this, or otherwise your attribute will last after your script is done running,\nand people get very annoyed at having their prompt and typing changed to weird colors.\n\n#### color\n\ncolor() takes any number of strings as arguments and considers them to be space-separated\nlists of attributes. It then forms and returns the escape sequence to set those attributes.\nIt doesn't print it out, just returns it, so you'll have to print it yourself if you want\nto. This is so that you can save it as a string, pass it to something else, send it to a\nfile handle, or do anything else with it that you might care to. color() throws an exception\nif given an invalid attribute.\n\n#### colored\n\n#### colored\n\nAs an aid in resetting colors, colored() takes a scalar as the first argument and any number\nof attribute strings as the second argument and returns the scalar wrapped in escape codes\nso that the attributes will be set as requested before the string and reset to normal after\nthe string. Alternately, you can pass a reference to an array as the first argument, and\nthen the contents of that array will be taken as attributes and color codes and the\nremainder of the arguments as text to colorize.\n\nNormally, colored() just puts attribute codes at the beginning and end of the string, but if\nyou set $Term::ANSIColor::EACHLINE to some string, that string will be considered the line\ndelimiter and the attribute will be set at the beginning of each line of the passed string\nand reset at the end of each line. This is often desirable if the output contains newlines\nand you're using background colors, since a background color that persists across a newline\nis often interpreted by the terminal as providing the default background color for the next\nline. Programs like pagers can also be confused by attributes that span lines. Normally\nyou'll want to set $Term::ANSIColor::EACHLINE to \"\\n\" to use this feature.\n\nParticularly consider setting $Term::ANSIColor::EACHLINE if you are interleaving output to\nstandard output and standard error and you aren't flushing standard output (via autoflush()\nor setting $|). If you don't, the code to reset the color may unexpectedly sit in the\nstandard output buffer rather than going to the display, causing standard error output to\nappear in the wrong color.\n\n#### uncolor\n\nuncolor() performs the opposite translation as color(), turning escape sequences into a list\nof strings corresponding to the attributes being set by those sequences. uncolor() will\nnever return \"ansi16\" through \"ansi255\", instead preferring the \"grey\" and \"rgb\" names (and\nlikewise for \"onansi16\" through \"onansi255\").\n\n#### colorstrip\n\ncolorstrip() removes all color escape sequences from the provided strings, returning the\nmodified strings separately in array context or joined together in scalar context. Its\narguments are not modified.\n\n#### colorvalid\n\ncolorvalid() takes attribute strings the same as color() and returns true if all attributes\nare known and false otherwise.\n\n#### coloralias\n\nIf ATTR is specified, it is interpreted as a list of space-separated strings naming\nattributes or existing aliases. In this case, coloralias() sets up an alias of ALIAS for the\nset of attributes given by ATTR. From that point forward, ALIAS can be passed into color(),\ncolored(), and colorvalid() and will have the same meaning as the sequence of attributes\ngiven in ATTR. One possible use of this facility is to give more meaningful names to the\n256-color RGB colors. Only ASCII alphanumerics, \".\", \"\", and \"-\" are allowed in alias\nnames.\n\nIf ATTR includes aliases, those aliases will be expanded at definition time and their values\nwill be used to define the new alias. This means that if you define an alias A in terms of\nanother alias B, and then later redefine alias B, the value of alias A will not change.\n\nIf ATTR is not specified, coloralias() returns the standard attribute or attributes to which\nALIAS is aliased, if any, or undef if ALIAS does not exist. If it is aliased to multiple\nattributes, the return value will be a single string and the attributes will be separated by\nspaces.\n\nThis is the same facility used by the ANSICOLORSALIASES environment variable (see\n\"ENVIRONMENT\" below) but can be used at runtime, not just when the module is loaded.\n\nLater invocations of coloralias() with the same ALIAS will override earlier aliases. There\nis no way to remove an alias.\n\nAliases have no effect on the return value of uncolor().\n\nWARNING: Aliases are global and affect all callers in the same process. There is no way to\nset an alias limited to a particular block of code or a particular object.\n\n#### Constant Interface\n\nAlternately, if you import \":constants\", you can use the following constants directly:\n\nCLEAR RESET BOLD DARK\nFAINT ITALIC UNDERLINE UNDERSCORE\nBLINK REVERSE CONCEALED\n\nBLACK RED GREEN YELLOW\nBLUE MAGENTA CYAN WHITE\nBRIGHTBLACK BRIGHTRED BRIGHTGREEN BRIGHTYELLOW\nBRIGHTBLUE BRIGHTMAGENTA BRIGHTCYAN BRIGHTWHITE\n\nONBLACK ONRED ONGREEN ONYELLOW\nONBLUE ONMAGENTA ONCYAN ONWHITE\nONBRIGHTBLACK ONBRIGHTRED ONBRIGHTGREEN ONBRIGHTYELLOW\nONBRIGHTBLUE ONBRIGHTMAGENTA ONBRIGHTCYAN ONBRIGHTWHITE\n\nThese are the same as color('attribute') and can be used if you prefer typing:\n\nprint BOLD BLUE ONWHITE \"Text\", RESET, \"\\n\";\n\nto\n\nprint colored (\"Text\", 'bold blue onwhite'), \"\\n\";\n\n(Note that the newline is kept separate to avoid confusing the terminal as described above since\na background color is being used.)\n\nIf you import \":constants256\", you can use the following constants directly:\n\nANSI0 .. ANSI255\nGREY0 .. GREY23\n\nRGBXYZ (for X, Y, and Z values from 0 to 5, like RGB000 or RGB515)\n\nONANSI0 .. ONANSI255\nONGREY0 .. ONGREY23\n\nONRGBXYZ (for X, Y, and Z values from 0 to 5)\n\nNote that \":constants256\" does not include the other constants, so if you want to mix both, you\nneed to include \":constants\" as well. You may want to explicitly import at least \"RESET\", as in:\n\nuse Term::ANSIColor 4.00 qw(RESET :constants256);\n\nTrue color and aliases are not supported by the constant interface.\n\nWhen using the constants, if you don't want to have to remember to add the \", RESET\" at the end\nof each print line, you can set $Term::ANSIColor::AUTORESET to a true value. Then, the display\nmode will automatically be reset if there is no comma after the constant. In other words, with\nthat variable set:\n\nprint BOLD BLUE \"Text\\n\";\n\nwill reset the display mode afterward, whereas:\n\nprint BOLD, BLUE, \"Text\\n\";\n\nwill not. If you are using background colors, you will probably want to either use say() (in\nnewer versions of Perl) or print the newline with a separate print statement to avoid confusing\nthe terminal.\n\nIf $Term::ANSIColor::AUTOLOCAL is set (see below), it takes precedence over\n$Term::ANSIColor::AUTORESET, and the latter is ignored.\n\nThe subroutine interface has the advantage over the constants interface in that only two\nsubroutines are exported into your namespace, versus thirty-eight in the constants interface,\nand aliases and true color attributes are supported. On the flip side, the constants interface\nhas the advantage of better compile time error checking, since misspelled names of colors or\nattributes in calls to color() and colored() won't be caught until runtime whereas misspelled\nnames of constants will be caught at compile time. So, pollute your namespace with almost two\ndozen subroutines that you may not even use that often, or risk a silly bug by mistyping an\nattribute. Your choice, TMTOWTDI after all.\n\n#### The Color Stack\n\nYou can import \":pushpop\" and maintain a stack of colors using PUSHCOLOR, POPCOLOR, and\nLOCALCOLOR. PUSHCOLOR takes the attribute string that starts its argument and pushes it onto a\nstack of attributes. POPCOLOR removes the top of the stack and restores the previous attributes\nset by the argument of a prior PUSHCOLOR. LOCALCOLOR surrounds its argument in a PUSHCOLOR and\nPOPCOLOR so that the color resets afterward.\n\nIf $Term::ANSIColor::AUTOLOCAL is set, each sequence of color constants will be implicitly\npreceded by LOCALCOLOR. In other words, the following:\n\n{\nlocal $Term::ANSIColor::AUTOLOCAL = 1;\nprint BLUE \"Text\\n\";\n}\n\nis equivalent to:\n\nprint LOCALCOLOR BLUE \"Text\\n\";\n\nIf $Term::ANSIColor::AUTOLOCAL is set, it takes precedence over $Term::ANSIColor::AUTORESET, and\nthe latter is ignored.\n\nWhen using PUSHCOLOR, POPCOLOR, and LOCALCOLOR, it's particularly important to not put commas\nbetween the constants.\n\nprint PUSHCOLOR BLUE \"Text\\n\";\n\nwill correctly push BLUE onto the top of the stack.\n\nprint PUSHCOLOR, BLUE, \"Text\\n\"; # wrong!\n\nwill not, and a subsequent pop won't restore the correct attributes. PUSHCOLOR pushes the\nattributes set by its argument, which is normally a string of color constants. It can't ask the\nterminal what the current attributes are.\n\n#### Supporting CLICOLOR\n\n proposes a standard for enabling and disabling color output\nfrom console commands using two environment variables, CLICOLOR and CLICOLORFORCE.\nTerm::ANSIColor cannot automatically support this standard, since the correct action depends on\nwhere the output is going and Term::ANSIColor may be used in a context where colors should\nalways be generated even if CLICOLOR is set in the environment. But you can use the supported\nenvironment variable ANSICOLORSDISABLED to implement CLICOLOR in your own programs with code\nlike this:\n\nif (exists($ENV{CLICOLOR}) && $ENV{CLICOLOR} == 0) {\nif (!$ENV{CLICOLORFORCE}) {\n$ENV{ANSICOLORSDISABLED} = 1;\n}\n}\n\nIf you are using the constant interface, be sure to include this code before you use any color\nconstants (such as at the very top of your script), since this environment variable is only\nhonored the first time a color constant is seen.\n\nBe aware that this will export ANSICOLORSDISABLED to any child processes of your program as\nwell.\n\n### DIAGNOSTICS\n\nBad color mapping %s\n(W) The specified color mapping from ANSICOLORSALIASES is not valid and could not be\nparsed. It was ignored.\n\nBad escape sequence %s\n(F) You passed an invalid ANSI escape sequence to uncolor().\n\nBareword \"%s\" not allowed while \"strict subs\" in use\n(F) You probably mistyped a constant color name such as:\n\n$Foobar = FOOBAR . \"This line should be blue\\n\";\n\nor:\n\n@Foobar = FOOBAR, \"This line should be blue\\n\";\n\nThis will only show up under use strict (another good reason to run under use strict).\n\nCannot alias standard color %s\n(F) The alias name passed to coloralias() matches a standard color name. Standard color\nnames cannot be aliased.\n\nCannot alias standard color %s in %s\n(W) The same, but in ANSICOLORSALIASES. The color mapping was ignored.\n\nInvalid alias name %s\n(F) You passed an invalid alias name to coloralias(). Alias names must consist only of\nalphanumerics, \".\", \"-\", and \"\".\n\nInvalid alias name %s in %s\n(W) You specified an invalid alias name on the left hand of the equal sign in a color\nmapping in ANSICOLORSALIASES. The color mapping was ignored.\n\nInvalid attribute name %s\n(F) You passed an invalid attribute name to color(), colored(), or coloralias().\n\nInvalid attribute name %s in %s\n(W) You specified an invalid attribute name on the right hand of the equal sign in a color\nmapping in ANSICOLORSALIASES. The color mapping was ignored.\n\nName \"%s\" used only once: possible typo\n(W) You probably mistyped a constant color name such as:\n\nprint FOOBAR \"This text is color FOOBAR\\n\";\n\nIt's probably better to always use commas after constant names in order to force the next\nerror.\n\nNo comma allowed after filehandle\n(F) You probably mistyped a constant color name such as:\n\nprint FOOBAR, \"This text is color FOOBAR\\n\";\n\nGenerating this fatal compile error is one of the main advantages of using the constants\ninterface, since you'll immediately know if you mistype a color name.\n\nNo name for escape sequence %s\n(F) The ANSI escape sequence passed to uncolor() contains escapes which aren't recognized\nand can't be translated to names.\n\n### ENVIRONMENT\n\nANSICOLORSALIASES\nThis environment variable allows the user to specify custom color aliases that will be\nunderstood by color(), colored(), and colorvalid(). None of the other functions will be\naffected, and no new color constants will be created. The custom colors are aliases for\nexisting color names; no new escape sequences can be introduced. Only alphanumerics, \".\",\n\"\", and \"-\" are allowed in alias names.\n\nThe format is:\n\nANSICOLORSALIASES='newcolor1=oldcolor1,newcolor2=oldcolor2'\n\nWhitespace is ignored. The alias value can be a single attribute or a space-separated list\nof attributes.\n\nFor example the Solarized colors can be mapped with:\n\nANSICOLORSALIASES='\\\nbase00=brightyellow, onbase00=onbrightyellow,\\\nbase01=brightgreen, onbase01=onbrightgreen, \\\nbase02=black, onbase02=onblack, \\\nbase03=brightblack, onbase03=onbrightblack, \\\nbase0=brightblue, onbase0=onbrightblue, \\\nbase1=brightcyan, onbase1=onbrightcyan, \\\nbase2=white, onbase2=onwhite, \\\nbase3=brightwhite, onbase3=onbrightwhite, \\\norange=brightred, onorange=onbrightred, \\\nviolet=brightmagenta,onviolet=onbrightmagenta'\n\nThis environment variable is read and applied when the Term::ANSIColor module is loaded and\nis then subsequently ignored. Changes to ANSICOLORSALIASES after the module is loaded will\nhave no effect. See coloralias() for an equivalent facility that can be used at runtime.\n\nANSICOLORSDISABLED\nIf this environment variable is set to a true value, all of the functions defined by this\nmodule (color(), colored(), and all of the constants) will not output any escape sequences\nand instead will just return the empty string or pass through the original text as\nappropriate. This is intended to support easy use of scripts using this module on platforms\nthat don't support ANSI escape sequences.\n\nNOCOLOR\nIf this environment variable is set to any value, it suppresses generation of escape\nsequences the same as if ANSICOLORSDISABLED is set to a true value. This implements the\n informal standard. Programs that want to enable color despite\nNOCOLOR being set will need to unset that environment variable before any constant or\nfunction provided by this module is used.\n\n### COMPATIBILITY\n\nTerm::ANSIColor was first included with Perl in Perl 5.6.0.\n\nThe uncolor() function and support for ANSICOLORSDISABLED were added in Term::ANSIColor 1.04,\nincluded in Perl 5.8.0.\n\nSupport for dark was added in Term::ANSIColor 1.08, included in Perl 5.8.4.\n\nThe color stack, including the \":pushpop\" import tag, PUSHCOLOR, POPCOLOR, LOCALCOLOR, and the\n$Term::ANSIColor::AUTOLOCAL variable, was added in Term::ANSIColor 2.00, included in Perl\n5.10.1.\n\n#### colorstrip\n\n2.02, both included in Perl 5.11.0.\n\nSupport for colors 8 through 15 (the \"bright\" variants) was added in Term::ANSIColor 3.00,\nincluded in Perl 5.13.3.\n\nSupport for italic was added in Term::ANSIColor 3.02, included in Perl 5.17.1.\n\nSupport for colors 16 through 256 (the \"ansi\", \"rgb\", and \"grey\" colors), the \":constants256\"\nimport tag, the coloralias() function, and support for the ANSICOLORSALIASES environment\nvariable were added in Term::ANSIColor 4.00, included in Perl 5.17.8.\n\n$Term::ANSIColor::AUTOLOCAL was changed to take precedence over $Term::ANSIColor::AUTORESET,\nrather than the other way around, in Term::ANSIColor 4.00, included in Perl 5.17.8.\n\n\"ansi16\" through \"ansi255\", as aliases for the \"rgb\" and \"grey\" colors, and the corresponding\n\"onansi\" names and \"ANSI\" and \"ONANSI\" constants were added in Term::ANSIColor 4.06, included\nin Perl 5.25.7.\n\nSupport for true color (the \"rNNNgNNNbNNN\" and \"onrNNNgNNNbNNN\" attributes), defining aliases\nin terms of other aliases, and aliases mapping to multiple attributes instead of only a single\nattribute was added in Term::ANSIColor 5.00.\n\nSupport for NOCOLOR was added in Term::ANSIColor 5.01.\n\n### RESTRICTIONS\n\nBoth colored() and many uses of the color constants will add the reset escape sequence after a\nnewline. If a program mixes colored output to standard output with output to standard error,\nthis can result in the standard error text having the wrong color because the reset escape\nsequence hasn't yet been flushed to the display (since standard output to a terminal is\nline-buffered by default). To avoid this, either set autoflush() on STDOUT or set\n$Term::ANSIColor::EACHLINE to \"\\n\".\n\nIt would be nice if one could leave off the commas around the constants entirely and just say:\n\nprint BOLD BLUE ONWHITE \"Text\\n\" RESET;\n\nbut the syntax of Perl doesn't allow this. You need a comma after the string. (Of course, you\nmay consider it a bug that commas between all the constants aren't required, in which case you\nmay feel free to insert commas unless you're using $Term::ANSIColor::AUTORESET or\nPUSHCOLOR/POPCOLOR.)\n\nFor easier debugging, you may prefer to always use the commas when not setting\n$Term::ANSIColor::AUTORESET or PUSHCOLOR/POPCOLOR so that you'll get a fatal compile error\nrather than a warning.\n\nIt's not possible to use this module to embed formatting and color attributes using Perl\nformats. They replace the escape character with a space (as documented in perlform(1)),\nresulting in garbled output from the unrecognized attribute. Even if there were a way around\nthat problem, the format doesn't know that the non-printing escape sequence is zero-length and\nwould incorrectly format the output. For formatted output using color or other attributes,\neither use sprintf() instead or use formline() and then add the color or other attributes after\nformatting and before output.\n\n### NOTES\n\nThe codes generated by this module are standard terminal control codes, complying with ECMA-048\nand ISO 6429 (generally referred to as \"ANSI color\" for the color codes). The non-color control\ncodes (bold, dark, italic, underline, and reverse) are part of the earlier ANSI X3.64 standard\nfor control sequences for video terminals and peripherals.\n\nNote that not all displays are ISO 6429-compliant, or even X3.64-compliant (or are even\nattempting to be so). This module will not work as expected on displays that do not honor these\nescape sequences, such as cmd.exe, 4nt.exe, and command.com under either Windows NT or Windows\n2000. They may just be ignored, or they may display as an ESC character followed by some\napparent garbage.\n\nJean Delvare provided the following table of different common terminal emulators and their\nsupport for the various attributes and others have helped me flesh it out:\n\nclear bold faint under blink reverse conceal\n------------------------------------------------------------------------\nxterm yes yes no yes yes yes yes\nlinux yes yes yes bold yes yes no\nrxvt yes yes no yes bold/black yes no\ndtterm yes yes yes yes reverse yes yes\nteraterm yes reverse no yes rev/red yes no\naixterm kinda normal no yes no yes yes\nPuTTY yes color no yes no yes no\nWindows yes no no no no yes no\nCygwin SSH yes yes no color color color yes\nTerminal.app yes yes no yes yes yes yes\n\nWindows is Windows telnet, Cygwin SSH is the OpenSSH implementation under Cygwin on Windows NT,\nand Mac Terminal is the Terminal application in Mac OS X. Where the entry is other than yes or\nno, that emulator displays the given attribute as something else instead. Note that on an\naixterm, clear doesn't reset colors; you have to explicitly set the colors back to what you\nwant. More entries in this table are welcome.\n\nSupport for code 3 (italic) is rare and therefore not mentioned in that table. It is not\nbelieved to be fully supported by any of the terminals listed, although it's displayed as green\nin the Linux console, but it is reportedly supported by urxvt.\n\nNote that codes 6 (rapid blink) and 9 (strike-through) are specified in ANSI X3.64 and ECMA-048\nbut are not commonly supported by most displays and emulators and therefore aren't supported by\nthis module. ECMA-048 also specifies a large number of other attributes, including a sequence of\nattributes for font changes, Fraktur characters, double-underlining, framing, circling, and\noverlining. As none of these attributes are widely supported or useful, they also aren't\ncurrently supported by this module.\n\nMost modern X terminal emulators support 256 colors. Known to not support those colors are\naterm, rxvt, Terminal.app, and TTY/VC.\n\nFor information on true color support in various terminal emulators, see True Colour support\n.\n\n### AUTHORS\n\nOriginal idea (using constants) by Zenin, reimplemented using subs by Russ Allbery\n, and then combined with the original idea by Russ with input from Zenin.\n256-color support is based on work by Kurt Starsinic. Russ Allbery now maintains this module.\n\nPUSHCOLOR, POPCOLOR, and LOCALCOLOR were contributed by openmethods.com voice solutions.\n\n### COPYRIGHT AND LICENSE\n\nCopyright 1996-1998, 2000-2002, 2005-2006, 2008-2018, 2020 Russ Allbery \n\nCopyright 1996 Zenin\n\nCopyright 2012 Kurt Starsinic \n\nThis program is free software; you may redistribute it and/or modify it under the same terms as\nPerl itself.\n\n### SEE ALSO\n\nThe CPAN module Term::ExtendedColor provides a different and more comprehensive interface for\n256-color emulators that may be more convenient. The CPAN module Win32::Console::ANSI provides\nANSI color (and other escape sequence) support in the Win32 Console environment. The CPAN module\nTerm::Chrome provides a different interface using objects and operator overloading.\n\nECMA-048 is available on-line (at least at the time of this writing) at\n.\n\nISO 6429 is available from ISO for a charge; the author of this module does not own a copy of\nit. Since the source material for ISO 6429 was ECMA-048 and the latter is available for free,\nthere seems little reason to obtain the ISO standard.\n\nThe 256-color control sequences are documented at\n (search for 256-color).\n\nInformation about true color support in various terminal emulators and test programs you can run\nto check the true color support in your terminal emulator are available at\n.\n\nCLICOLORS and NOCOLOR are useful\nstandards to be aware of, and ideally follow, for any application using color. Term::ANSIColor\ncomplies with the latter.\n\nThe current version of this module is always available from its web site at\n. It is also part of the Perl core\ndistribution as of 5.6.0.\n\n"
}
],
"structuredContent": {
"command": "Term::ANSIColor",
"section": "",
"mode": "perldoc",
"summary": "Term::ANSIColor - Color screen output using ANSI escape sequences",
"synopsis": "use Term::ANSIColor;\nprint color('bold blue');\nprint \"This text is bold blue.\\n\";\nprint color('reset');\nprint \"This text is normal.\\n\";\nprint colored(\"Yellow on magenta.\", 'yellow onmagenta'), \"\\n\";\nprint \"This text is normal.\\n\";\nprint colored(['yellow onmagenta'], 'Yellow on magenta.', \"\\n\");\nprint colored(['red onbrightyellow'], 'Red on bright yellow.', \"\\n\");\nprint colored(['brightred onblack'], 'Bright red on black.', \"\\n\");\nprint \"\\n\";\n# Map escape sequences back to color names.\nuse Term::ANSIColor 1.04 qw(uncolor);\nmy @names = uncolor('01;31');\nprint join(q{ }, @names), \"\\n\";\n# Strip all color escape sequences.\nuse Term::ANSIColor 2.01 qw(colorstrip);\nprint colorstrip(\"\\e[1mThis is bold\\e[0m\"), \"\\n\";\n# Determine whether a color is valid.\nuse Term::ANSIColor 2.02 qw(colorvalid);\nmy $valid = colorvalid('blue bold', 'onmagenta');\nprint \"Color string is \", $valid ? \"valid\\n\" : \"invalid\\n\";\n# Create new aliases for colors.\nuse Term::ANSIColor 4.00 qw(coloralias);\ncoloralias('alert', 'red');\nprint \"Alert is \", coloralias('alert'), \"\\n\";\nprint colored(\"This is in red.\", 'alert'), \"\\n\";\nuse Term::ANSIColor qw(:constants);\nprint BOLD, BLUE, \"This text is in bold blue.\\n\", RESET;\nuse Term::ANSIColor qw(:constants);\n{\nlocal $Term::ANSIColor::AUTORESET = 1;\nprint BOLD BLUE \"This text is in bold blue.\\n\";\nprint \"This text is normal.\\n\";\n}\nuse Term::ANSIColor 2.00 qw(:pushpop);\nprint PUSHCOLOR RED ONGREEN \"This text is red on green.\\n\";\nprint PUSHCOLOR BRIGHTBLUE \"This text is bright blue on green.\\n\";\nprint RESET BRIGHTBLUE \"This text is just bright blue.\\n\";\nprint POPCOLOR \"Back to red on green.\\n\";\nprint LOCALCOLOR GREEN ONBLUE \"This text is green on blue.\\n\";\nprint \"This text is red on green.\\n\";\n{\nlocal $Term::ANSIColor::AUTOLOCAL = 1;\nprint ONBLUE \"This text is red on blue.\\n\";\nprint \"This text is red on green.\\n\";\n}\nprint POPCOLOR \"Back to whatever we started as.\\n\";",
"tldr_summary": null,
"tldr_examples": [],
"tldr_source": null,
"flags": [],
"examples": [],
"see_also": [],
"section_outline": [
{
"name": "NAME",
"lines": 2,
"subsections": []
},
{
"name": "SYNOPSIS",
"lines": 56,
"subsections": []
},
{
"name": "DESCRIPTION",
"lines": 2,
"subsections": [
{
"name": "coloralias",
"lines": 6
},
{
"name": "Supported Colors",
"lines": 48
},
{
"name": "Function Interface",
"lines": 52
},
{
"name": "color",
"lines": 7
},
{
"name": "colored",
"lines": 1
},
{
"name": "colored",
"lines": 22
},
{
"name": "uncolor",
"lines": 5
},
{
"name": "colorstrip",
"lines": 4
},
{
"name": "colorvalid",
"lines": 3
},
{
"name": "coloralias",
"lines": 28
},
{
"name": "Constant Interface",
"lines": 73
},
{
"name": "The Color Stack",
"lines": 34
},
{
"name": "Supporting CLICOLOR",
"lines": 21
}
]
},
{
"name": "DIAGNOSTICS",
"lines": 60,
"subsections": []
},
{
"name": "ENVIRONMENT",
"lines": 46,
"subsections": []
},
{
"name": "COMPATIBILITY",
"lines": 11,
"subsections": [
{
"name": "colorstrip",
"lines": 24
}
]
},
{
"name": "RESTRICTIONS",
"lines": 28,
"subsections": []
},
{
"name": "NOTES",
"lines": 50,
"subsections": []
},
{
"name": "AUTHORS",
"lines": 6,
"subsections": []
},
{
"name": "COPYRIGHT AND LICENSE",
"lines": 9,
"subsections": []
},
{
"name": "SEE ALSO",
"lines": 27,
"subsections": []
}
]
}
}