{ "content": [ { "type": "text", "text": "# Term::ANSIColor (info)\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# 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## DESCRIPTION\n\nThis module has two interfaces, one through color() and colored() and\nthe other through constants. It also offers the utility functions\nuncolor(), colorstrip(), colorvalid(), and coloralias(), which have to\nbe explicitly imported to be used (see \"SYNOPSIS\").\n\n## Sections\n\n- **Term::ANSIColor(3perl) Perl Programmers Reference Guide Term::ANSIColor(3perl)**\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **DIAGNOSTICS**\n- **ENVIRONMENT**\n- **COMPATIBILITY**\n- **RESTRICTIONS**\n- **NOTES**\n- **AUTHORS**\n- **COPYRIGHT AND LICENSE**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Term::ANSIColor", "section": "", "mode": "info", "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": [ { "name": "ANSIColor", "section": "3perl", "url": "https://www.chedong.com/phpMan.php/man/ANSIColor/3perl/json" } ], "section_outline": [ { "name": "Term::ANSIColor(3perl) Perl Programmers Reference Guide Term::ANSIColor(3perl)", "lines": 1, "subsections": [] }, { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 56, "subsections": [] }, { "name": "DESCRIPTION", "lines": 374, "subsections": [] }, { "name": "DIAGNOSTICS", "lines": 66, "subsections": [] }, { "name": "ENVIRONMENT", "lines": 55, "subsections": [] }, { "name": "COMPATIBILITY", "lines": 41, "subsections": [] }, { "name": "RESTRICTIONS", "lines": 33, "subsections": [] }, { "name": "NOTES", "lines": 56, "subsections": [] }, { "name": "AUTHORS", "lines": 8, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 10, "subsections": [] }, { "name": "SEE ALSO", "lines": 34, "subsections": [] } ], "sections": { "Term::ANSIColor(3perl) Perl Programmers Reference Guide Term::ANSIColor(3perl)": { "content": "", "subsections": [] }, "NAME": { "content": "Term::ANSIColor - Color screen output using ANSI escape sequences\n", "subsections": [] }, "SYNOPSIS": { "content": "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\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", "subsections": [] }, "DESCRIPTION": { "content": "This module has two interfaces, one through color() and colored() and\nthe other through constants. It also offers the utility functions\nuncolor(), colorstrip(), colorvalid(), and coloralias(), which have to\nbe explicitly imported to be used (see \"SYNOPSIS\").\n\nIf you are using Term::ANSIColor in a console command, consider\nsupporting the CLICOLOR standard. See \"Supporting CLICOLOR\" for more\ninformation.\n\nSee \"COMPATIBILITY\" for the versions of Term::ANSIColor that introduced\nparticular features and the versions of Perl that included them.\n\nSupported Colors\nTerminal emulators that support color divide into four types: ones that\nsupport only eight colors, ones that support sixteen, ones that support\n256, and ones that support 24-bit color. This module provides the ANSI\nescape 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\n(256-color), and true color (called direct-color by xterm).\n\nUnfortunately, interpretation of colors 0 through 7 often depends on\nwhether the emulator supports eight colors or sixteen colors.\nEmulators that only support eight colors (such as the Linux console)\nwill display colors 0 through 7 with normal brightness and ignore\ncolors 8 through 15, treating them the same as white. Emulators that\nsupport 16 colors, such as gnome-terminal, normally display colors 0\nthrough 7 as dim or darker versions and colors 8 through 15 as normal\nbrightness. On such emulators, the \"normal\" white (color 7) usually is\nshown as pale grey, requiring bright white (15) to be used to get a\nreal white color. Bright black usually is a dark grey color, although\nsome terminals display it as pure black. Some sixteen-color terminal\nemulators 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\nprovides a pair of attributes for each color. For every normal color\n(0 through 7), the corresponding bright color (8 through 15) is\nobtained by prepending the string \"bright\" to the normal color name.\nFor example, \"red\" is color 1 and \"brightred\" is color 9. The same\napplies for background colors: \"onred\" is the normal color and\n\"onbrightred\" is the bright color. Capitalize these strings for the\nconstant interface.\n\nThere is unfortunately no way to know whether the current emulator\nsupports more than eight colors, which makes the choice of colors\ndifficult. The most conservative choice is to use only the regular\ncolors, which are at least displayed on all emulators. However, they\nwill appear dark in sixteen-color terminal emulators, including most\ncommon emulators in UNIX X environments. If you know the display is\none of those emulators, you may wish to use the bright variants\ninstead. Even better, offer the user a way to configure the colors for\na given application to fit their terminal emulator.\n\nFor 256-color emulators, this module additionally provides \"ansi0\"\nthrough \"ansi15\", which are the same as colors 0 through 15 in sixteen-\ncolor emulators but use the 256-color escape syntax, \"grey0\" through\n\"grey23\" ranging from nearly black to nearly white, and a set of RGB\ncolors. The RGB colors are of the form \"rgbRGB\" where R, G, and B are\nnumbers from 0 to 5 giving the intensity of red, green, and blue. The\ngrey and RGB colors are also available as \"ansi16\" through \"ansi255\" if\nyou want simple names for all 256 colors. \"on\" variants of all of\nthese colors are also provided. These colors may be ignored completely\non non-256-color terminals or may be misinterpreted and produce random\nbehavior. Additional attributes such as blink, italic, or bold may not\nwork with the 256-color palette.\n\nFor true color emulators, this module supports attributes of the form\n\"rNNNgNNNbNNN\" and \"onrNNNgNNNbNNN\" for all values of NNN between 0\nand 255. These represent foreground and background colors,\nrespectively, with the RGB values given by the NNN numbers. These\ncolors may be ignored completely on non-true-color terminals or may be\nmisinterpreted and produce random behavior.\n\nFunction Interface\nThe function interface uses attribute strings to describe the colors\nand text attributes to assign to text. The recognized non-color\nattributes are clear, reset, bold, dark, faint, italic, underline,\nunderscore, blink, reverse, and concealed. Clear and reset (reset to\ndefault attributes), dark and faint (dim and saturated), and underline\nand underscore are equivalent, so use whichever is the most intuitive\nto you.\n\nNote that not all attributes are supported by all terminal types, and\nsome terminals may not support any of these sequences. Dark and faint,\nitalic, blink, and concealed in particular are frequently not\nimplemented.\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)\nare:\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 \"rgbRGB\" for R, G, and B values from 0 to 5, such as \"rgb000\" or\n\"rgb515\". Similarly, the recognized background colors are:\n\nonansi0 .. onansi255\nongrey0 .. ongrey23\n\nplus \"onrgbRGB\" for R, G, and B values from 0 to 5.\n\nFor true color terminals, the recognized foreground colors are\n\"rRRRgGGGbBBB\" for RRR, GGG, and BBB values between 0 and 255.\nSimilarly, the recognized background colors are \"onrRRRgGGGbBBB\" for\nRRR, 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\nattribute \"clear\" or \"reset\"). Be careful to do this, or otherwise\nyour attribute will last after your script is done running, and people\nget very annoyed at having their prompt and typing changed to weird\ncolors.\n\ncolor(ATTR[, ATTR ...])\ncolor() takes any number of strings as arguments and considers them\nto be space-separated lists of attributes. It then forms and\nreturns the escape sequence to set those attributes. It doesn't\nprint it out, just returns it, so you'll have to print it yourself\nif you want to. This is so that you can save it as a string, pass\nit to something else, send it to a file handle, or do anything else\nwith it that you might care to. color() throws an exception if\ngiven an invalid attribute.\n\ncolored(STRING, ATTR[, ATTR ...])\ncolored(ATTR-REF, STRING[, STRING...])\nAs an aid in resetting colors, colored() takes a scalar as the\nfirst argument and any number of attribute strings as the second\nargument and returns the scalar wrapped in escape codes so that the\nattributes will be set as requested before the string and reset to\nnormal after the string. Alternately, you can pass a reference to\nan array as the first argument, and then the contents of that array\nwill be taken as attributes and color codes and the remainder of\nthe arguments as text to colorize.\n\nNormally, colored() just puts attribute codes at the beginning and\nend of the string, but if you set $Term::ANSIColor::EACHLINE to\nsome string, that string will be considered the line delimiter and\nthe attribute will be set at the beginning of each line of the\npassed string and reset at the end of each line. This is often\ndesirable if the output contains newlines and you're using\nbackground colors, since a background color that persists across a\nnewline is often interpreted by the terminal as providing the\ndefault background color for the next line. Programs like pagers\ncan also be confused by attributes that span lines. Normally\nyou'll want to set $Term::ANSIColor::EACHLINE to \"\\n\" to use this\nfeature.\n\nParticularly consider setting $Term::ANSIColor::EACHLINE if you are\ninterleaving output to standard output and standard error and you\naren't flushing standard output (via autoflush() or setting $|).\nIf you don't, the code to reset the color may unexpectedly sit in\nthe standard output buffer rather than going to the display,\ncausing standard error output to appear in the wrong color.\n\nuncolor(ESCAPE)\nuncolor() performs the opposite translation as color(), turning\nescape sequences into a list of strings corresponding to the\nattributes being set by those sequences. uncolor() will never\nreturn \"ansi16\" through \"ansi255\", instead preferring the \"grey\"\nand \"rgb\" names (and likewise for \"onansi16\" through\n\"onansi255\").\n\ncolorstrip(STRING[, STRING ...])\ncolorstrip() removes all color escape sequences from the provided\nstrings, returning the modified strings separately in array context\nor joined together in scalar context. Its arguments are not\nmodified.\n\ncolorvalid(ATTR[, ATTR ...])\ncolorvalid() takes attribute strings the same as color() and\nreturns true if all attributes are known and false otherwise.\n\ncoloralias(ALIAS[, ATTR ...])\nIf ATTR is specified, it is interpreted as a list of space-\nseparated strings naming attributes or existing aliases. In this\ncase, coloralias() sets up an alias of ALIAS for the set of\nattributes given by ATTR. From that point forward, ALIAS can be\npassed into color(), colored(), and colorvalid() and will have the\nsame meaning as the sequence of attributes given in ATTR. One\npossible use of this facility is to give more meaningful names to\nthe 256-color RGB colors. Only ASCII alphanumerics, \".\", \"\", and\n\"-\" are allowed in alias names.\n\nIf ATTR includes aliases, those aliases will be expanded at\ndefinition time and their values will be used to define the new\nalias. This means that if you define an alias A in terms of\nanother alias B, and then later redefine alias B, the value of\nalias A will not change.\n\nIf ATTR is not specified, coloralias() returns the standard\nattribute or attributes to which ALIAS is aliased, if any, or undef\nif ALIAS does not exist. If it is aliased to multiple attributes,\nthe return value will be a single string and the attributes will be\nseparated by spaces.\n\nThis is the same facility used by the ANSICOLORSALIASES\nenvironment variable (see \"ENVIRONMENT\" below) but can be used at\nruntime, not just when the module is loaded.\n\nLater invocations of coloralias() with the same ALIAS will override\nearlier aliases. There is 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\nprocess. There is no way to set an alias limited to a particular\nblock of code or a particular object.\n\nConstant Interface\nAlternately, if you import \":constants\", you can use the following\nconstants 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\ntyping:\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\nas described above since a background color is being used.)\n\nIf you import \":constants256\", you can use the following constants\ndirectly:\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\nyou want to mix both, you need to include \":constants\" as well. You\nmay 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\nthe \", RESET\" at the end of each print line, you can set\n$Term::ANSIColor::AUTORESET to a true value. Then, the display mode\nwill automatically be reset if there is no comma after the constant.\nIn other words, with that 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\nto either use say() (in newer versions of Perl) or print the newline\nwith a separate print statement to avoid confusing the terminal.\n\nIf $Term::ANSIColor::AUTOLOCAL is set (see below), it takes precedence\nover $Term::ANSIColor::AUTORESET, and the latter is ignored.\n\nThe subroutine interface has the advantage over the constants interface\nin that only two subroutines are exported into your namespace, versus\nthirty-eight in the constants interface, and aliases and true color\nattributes are supported. On the flip side, the constants interface\nhas the advantage of better compile time error checking, since\nmisspelled names of colors or attributes in calls to color() and\ncolored() won't be caught until runtime whereas misspelled names of\nconstants will be caught at compile time. So, pollute your namespace\nwith almost two dozen subroutines that you may not even use that often,\nor risk a silly bug by mistyping an attribute. Your choice, TMTOWTDI\nafter all.\n\nThe Color Stack\nYou can import \":pushpop\" and maintain a stack of colors using\nPUSHCOLOR, POPCOLOR, and LOCALCOLOR. PUSHCOLOR takes the attribute\nstring that starts its argument and pushes it onto a stack of\nattributes. POPCOLOR removes the top of the stack and restores the\nprevious attributes set by the argument of a prior PUSHCOLOR.\nLOCALCOLOR surrounds its argument in a PUSHCOLOR and POPCOLOR so that\nthe color resets afterward.\n\nIf $Term::ANSIColor::AUTOLOCAL is set, each sequence of color constants\nwill be implicitly preceded by LOCALCOLOR. In other words, the\nfollowing:\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\n$Term::ANSIColor::AUTORESET, and the latter is ignored.\n\nWhen using PUSHCOLOR, POPCOLOR, and LOCALCOLOR, it's particularly\nimportant to not put commas between 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.\nPUSHCOLOR pushes the attributes set by its argument, which is normally\na string of color constants. It can't ask the terminal what the\ncurrent attributes are.\n\nSupporting CLICOLOR\n proposes a standard for enabling and\ndisabling color output from console commands using two environment\nvariables, CLICOLOR and CLICOLORFORCE. Term::ANSIColor cannot\nautomatically support this standard, since the correct action depends\non where the output is going and Term::ANSIColor may be used in a\ncontext where colors should always be generated even if CLICOLOR is set\nin the environment. But you can use the supported environment variable\nANSICOLORSDISABLED to implement CLICOLOR in your own programs with\ncode like 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\nbefore you use any color constants (such as at the very top of your\nscript), since this environment variable is only honored the first time\na color constant is seen.\n\nBe aware that this will export ANSICOLORSDISABLED to any child\nprocesses of your program as well.\n", "subsections": [] }, "DIAGNOSTICS": { "content": "Bad color mapping %s\n(W) The specified color mapping from ANSICOLORSALIASES is not\nvalid and could not be parsed. 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\nunder use strict).\n\nCannot alias standard color %s\n(F) The alias name passed to coloralias() matches a standard color\nname. Standard color names cannot be aliased.\n\nCannot alias standard color %s in %s\n(W) The same, but in ANSICOLORSALIASES. The color mapping was\nignored.\n\nInvalid alias name %s\n(F) You passed an invalid alias name to coloralias(). Alias names\nmust consist only of alphanumerics, \".\", \"-\", and \"\".\n\nInvalid alias name %s in %s\n(W) You specified an invalid alias name on the left hand of the\nequal sign in a color mapping in ANSICOLORSALIASES. The color\nmapping was ignored.\n\nInvalid attribute name %s\n(F) You passed an invalid attribute name to color(), colored(), or\ncoloralias().\n\nInvalid attribute name %s in %s\n(W) You specified an invalid attribute name on the right hand of\nthe equal sign in a color mapping in ANSICOLORSALIASES. The\ncolor 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\norder to force the next error.\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\nof using the constants interface, since you'll immediately know if\nyou mistype a color name.\n\nNo name for escape sequence %s\n(F) The ANSI escape sequence passed to uncolor() contains escapes\nwhich aren't recognized and can't be translated to names.\n", "subsections": [] }, "ENVIRONMENT": { "content": "ANSICOLORSALIASES\nThis environment variable allows the user to specify custom color\naliases that will be understood by color(), colored(), and\ncolorvalid(). None of the other functions will be affected, and no\nnew color constants will be created. The custom colors are aliases\nfor existing color names; no new escape sequences can be\nintroduced. Only alphanumerics, \".\", \"\", and \"-\" are allowed in\nalias names.\n\nThe format is:\n\nANSICOLORSALIASES='newcolor1=oldcolor1,newcolor2=oldcolor2'\n\nWhitespace is ignored. The alias value can be a single attribute\nor a space-separated list of attributes.\n\nFor example the Solarized \ncolors 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\nTerm::ANSIColor module is loaded and is then subsequently ignored.\nChanges to ANSICOLORSALIASES after the module is loaded will have\nno effect. See coloralias() for an equivalent facility that can be\nused at runtime.\n\nANSICOLORSDISABLED\nIf this environment variable is set to a true value, all of the\nfunctions defined by this module (color(), colored(), and all of\nthe constants) will not output any escape sequences and instead\nwill just return the empty string or pass through the original text\nas appropriate. This is intended to support easy use of scripts\nusing this module on platforms that don't support ANSI escape\nsequences.\n\nNOCOLOR\nIf this environment variable is set to any value, it suppresses\ngeneration of escape sequences the same as if ANSICOLORSDISABLED\nis set to a true value. This implements the\n informal standard. Programs that want to\nenable color despite NOCOLOR being set will need to unset that\nenvironment variable before any constant or function provided by\nthis module is used.\n", "subsections": [] }, "COMPATIBILITY": { "content": "Term::ANSIColor was first included with Perl in Perl 5.6.0.\n\nThe uncolor() function and support for ANSICOLORSDISABLED were added\nin Term::ANSIColor 1.04, included in Perl 5.8.0.\n\nSupport for dark was added in Term::ANSIColor 1.08, included in Perl\n5.8.4.\n\nThe color stack, including the \":pushpop\" import tag, PUSHCOLOR,\nPOPCOLOR, LOCALCOLOR, and the $Term::ANSIColor::AUTOLOCAL variable, was\nadded in Term::ANSIColor 2.00, included in Perl 5.10.1.\n\ncolorstrip() was added in Term::ANSIColor 2.01 and colorvalid() was\nadded in Term::ANSIColor 2.02, both included in Perl 5.11.0.\n\nSupport for colors 8 through 15 (the \"bright\" variants) was added in\nTerm::ANSIColor 3.00, included in Perl 5.13.3.\n\nSupport for italic was added in Term::ANSIColor 3.02, included in Perl\n5.17.1.\n\nSupport for colors 16 through 256 (the \"ansi\", \"rgb\", and \"grey\"\ncolors), the \":constants256\" import tag, the coloralias() function, and\nsupport for the ANSICOLORSALIASES environment variable were added in\nTerm::ANSIColor 4.00, included in Perl 5.17.8.\n\n$Term::ANSIColor::AUTOLOCAL was changed to take precedence over\n$Term::ANSIColor::AUTORESET, rather than the other way around, in\nTerm::ANSIColor 4.00, included in Perl 5.17.8.\n\n\"ansi16\" through \"ansi255\", as aliases for the \"rgb\" and \"grey\" colors,\nand the corresponding \"onansi\" names and \"ANSI\" and \"ONANSI\"\nconstants were added in Term::ANSIColor 4.06, included in Perl 5.25.7.\n\nSupport for true color (the \"rNNNgNNNbNNN\" and \"onrNNNgNNNbNNN\"\nattributes), defining aliases in terms of other aliases, and aliases\nmapping to multiple attributes instead of only a single attribute was\nadded in Term::ANSIColor 5.00.\n\nSupport for NOCOLOR was added in Term::ANSIColor 5.01.\n", "subsections": [] }, "RESTRICTIONS": { "content": "Both colored() and many uses of the color constants will add the reset\nescape sequence after a newline. If a program mixes colored output to\nstandard output with output to standard error, this can result in the\nstandard error text having the wrong color because the reset escape\nsequence hasn't yet been flushed to the display (since standard output\nto a terminal is line-buffered by default). To avoid this, either set\nautoflush() on STDOUT or set $Term::ANSIColor::EACHLINE to \"\\n\".\n\nIt would be nice if one could leave off the commas around the constants\nentirely 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\nstring. (Of course, you may consider it a bug that commas between all\nthe constants aren't required, in which case you may feel free to\ninsert 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\nsetting $Term::ANSIColor::AUTORESET or PUSHCOLOR/POPCOLOR so that\nyou'll get a fatal compile error rather than a warning.\n\nIt's not possible to use this module to embed formatting and color\nattributes using Perl formats. They replace the escape character with\na space (as documented in perlform(1)), resulting in garbled output\nfrom the unrecognized attribute. Even if there were a way around that\nproblem, the format doesn't know that the non-printing escape sequence\nis zero-length and would incorrectly format the output. For formatted\noutput using color or other attributes, either use sprintf() instead or\nuse formline() and then add the color or other attributes after\nformatting and before output.\n", "subsections": [] }, "NOTES": { "content": "The codes generated by this module are standard terminal control codes,\ncomplying with ECMA-048 and ISO 6429 (generally referred to as \"ANSI\ncolor\" for the color codes). The non-color control codes (bold, dark,\nitalic, underline, and reverse) are part of the earlier ANSI X3.64\nstandard for control sequences for video terminals and peripherals.\n\nNote that not all displays are ISO 6429-compliant, or even\nX3.64-compliant (or are even attempting to be so). This module will\nnot work as expected on displays that do not honor these escape\nsequences, such as cmd.exe, 4nt.exe, and command.com under either\nWindows NT or Windows 2000. They may just be ignored, or they may\ndisplay as an ESC character followed by some apparent garbage.\n\nJean Delvare provided the following table of different common terminal\nemulators and their support for the various attributes and others have\nhelped me flesh it out:\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\nunder Cygwin on Windows NT, and Mac Terminal is the Terminal\napplication in Mac OS X. Where the entry is other than yes or no, that\nemulator displays the given attribute as something else instead. Note\nthat on an aixterm, clear doesn't reset colors; you have to explicitly\nset the colors back to what you want. More entries in this table are\nwelcome.\n\nSupport for code 3 (italic) is rare and therefore not mentioned in that\ntable. It is not believed to be fully supported by any of the\nterminals listed, although it's displayed as green in the Linux\nconsole, but it is reportedly supported by urxvt.\n\nNote that codes 6 (rapid blink) and 9 (strike-through) are specified in\nANSI X3.64 and ECMA-048 but are not commonly supported by most displays\nand emulators and therefore aren't supported by this module. ECMA-048\nalso specifies a large number of other attributes, including a sequence\nof attributes for font changes, Fraktur characters, double-underlining,\nframing, circling, and overlining. As none of these attributes are\nwidely supported or useful, they also aren't currently supported by\nthis module.\n\nMost modern X terminal emulators support 256 colors. Known to not\nsupport those colors are aterm, rxvt, Terminal.app, and TTY/VC.\n\nFor information on true color support in various terminal emulators,\nsee True Colour support .\n", "subsections": [] }, "AUTHORS": { "content": "Original idea (using constants) by Zenin, reimplemented using subs by\nRuss Allbery , and then combined with the original idea\nby Russ with input from Zenin. 256-color support is based on work by\nKurt Starsinic. Russ Allbery now maintains this module.\n\nPUSHCOLOR, POPCOLOR, and LOCALCOLOR were contributed by openmethods.com\nvoice solutions.\n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "Copyright 1996-1998, 2000-2002, 2005-2006, 2008-2018, 2020 Russ Allbery\n\n\nCopyright 1996 Zenin\n\nCopyright 2012 Kurt Starsinic \n\nThis program is free software; you may redistribute it and/or modify it\nunder the same terms as Perl itself.\n", "subsections": [] }, "SEE ALSO": { "content": "The CPAN module Term::ExtendedColor provides a different and more\ncomprehensive interface for 256-color emulators that may be more\nconvenient. The CPAN module Win32::Console::ANSI provides ANSI color\n(and other escape sequence) support in the Win32 Console environment.\nThe CPAN module Term::Chrome provides a different interface using\nobjects 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\ndoes not own a copy of it. Since the source material for ISO 6429 was\nECMA-048 and the latter is available for free, there seems little\nreason to obtain the ISO standard.\n\nThe 256-color control sequences are documented at\n (search for\n256-color).\n\nInformation about true color support in various terminal emulators and\ntest programs you can run to check the true color support in your\nterminal emulator are available at\n.\n\nCLICOLORS and NOCOLOR are useful standards to be aware of, and ideally follow,\nfor any application using color. Term::ANSIColor complies with the\nlatter.\n\nThe current version of this module is always available from its web\nsite at . It is also\npart of the Perl core distribution as of 5.6.0.\n\nperl v5.34.0 2026-06-23 Term::ANSIColor(3perl)", "subsections": [] } } } }