home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _853fbfcf5b51eaed49bfbc34e584dbb2 < prev    next >
Text File  |  2000-03-23  |  9KB  |  193 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Term::ANSIColor - Color screen output using ANSI escape sequences</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Term::ANSIColor - Color screen output using ANSI escape sequences</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#diagnostics">DIAGNOSTICS</A></LI>
  26.     <LI><A HREF="#restrictions">RESTRICTIONS</A></LI>
  27.     <LI><A HREF="#authors">AUTHORS</A></LI>
  28. </UL>
  29. <!-- INDEX END -->
  30.  
  31. <HR>
  32. <P>
  33. <H1><A NAME="name">NAME</A></H1>
  34. <P>Term::ANSIColor - Color screen output using ANSI escape sequences</P>
  35. <P>
  36. <HR>
  37. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  38. <UL>
  39. <LI>Linux</LI>
  40. <LI>Solaris</LI>
  41. <LI>Windows</LI>
  42. </UL>
  43. <HR>
  44. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  45. <PRE>
  46.     use Term::ANSIColor;
  47.     print color 'bold blue';
  48.     print "This text is bold blue.\n";
  49.     print color 'reset';
  50.     print "This text is normal.\n";
  51.     print colored ("Yellow on magenta.\n", 'yellow on_magenta');
  52.     print "This text is normal.\n";</PRE>
  53. <PRE>
  54.     use Term::ANSIColor qw(:constants);
  55.     print BOLD, BLUE, "This text is in bold blue.\n", RESET;</PRE>
  56. <PRE>
  57.     use Term::ANSIColor qw(:constants);
  58.     $Term::ANSIColor::AUTORESET = 1;
  59.     print BOLD BLUE "This text is in bold blue.\n";
  60.     print "This text is normal.\n";</PRE>
  61. <P>
  62. <HR>
  63. <H1><A NAME="description">DESCRIPTION</A></H1>
  64. <P>This module has two interfaces, one through <CODE>color()</CODE> and <CODE>colored()</CODE> and the
  65. other through constants.
  66. </P>
  67. <PRE>
  68.  
  69. color() takes any number of strings as arguments and considers them to be
  70. space-separated lists of attributes.  It then forms and returns the escape
  71. sequence to set those attributes.  It doesn't print it out, just returns
  72. it, so you'll have to print it yourself if you want to (this is so that
  73. you can save it as a string, pass it to something else, send it to a file
  74. handle, or do anything else with it that you might care to).</PRE>
  75. <P>The recognized attributes (all of which should be fairly intuitive) are
  76. clear, reset, bold, underline, underscore, blink, reverse, concealed,
  77. black, red, green, yellow, blue, magenta, on_black, on_red, on_green,
  78. on_yellow, on_blue, on_magenta, on_cyan, and on_white.  Case is not
  79. significant.  Underline and underscore are equivalent, as are clear and
  80. reset, so use whichever is the most intuitive to you.  The color alone
  81. sets the foreground color, and on_color sets the background color.</P>
  82. <P>Note that attributes, once set, last until they are unset (by sending the
  83. attribute ``reset'').  Be careful to do this, or otherwise your attribute will
  84. last after your script is done running, and people get very annoyed at
  85. having their prompt and typing changed to weird colors.</P>
  86. <P>As an aid to help with this, <CODE>colored()</CODE> takes a scalar as the first
  87. argument and any number of attribute strings as the second argument and
  88. returns the scalar wrapped in escape codes so that the attributes will be
  89. set as requested before the string and reset to normal after the string.
  90. Normally, <CODE>colored()</CODE> just puts attribute codes at the beginning and end of
  91. the string, but if you set $Term::ANSIColor::EACHLINE to some string,
  92. that string will be considered the line delimiter and the attribute will
  93. be set at the beginning of each line of the passed string and reset at the
  94. end of each line.  This is often desirable if the output is being sent to
  95. a program like a pager that can be confused by attributes that span lines.
  96. Normally you'll want to set $Term::ANSIColor::EACHLINE to <CODE>"\n"</CODE> to use
  97. this feature.</P>
  98. <P>Alternately, if you import <CODE>:constants</CODE>, you can use the constants CLEAR,
  99. RESET, BOLD, UNDERLINE, UNDERSCORE, BLINK, REVERSE, CONCEALED, BLACK, RED,
  100. GREEN, YELLOW, BLUE, MAGENTA, ON_BLACK, ON_RED, ON_GREEN, ON_YELLOW,
  101. ON_BLUE, ON_MAGENTA, ON_CYAN, and ON_WHITE directly.  These are the same
  102. as <CODE>color('attribute')</CODE> and can be used if you prefer typing:</P>
  103. <PRE>
  104.     print BOLD BLUE ON_WHITE "Text\n", RESET;</PRE>
  105. <P>to</P>
  106. <PRE>
  107.     print colored ("Text\n", 'bold blue on_white');</PRE>
  108. <P>When using the constants, if you don't want to have to remember to add the
  109. <CODE>, RESET</CODE> at the end of each print line, you can set
  110. $Term::ANSIColor::AUTORESET to a true value.  Then, the display mode will
  111. automatically be reset if there is no comma after the constant.  In other
  112. words, with that variable set:</P>
  113. <PRE>
  114.     print BOLD BLUE "Text\n";</PRE>
  115. <P>will reset the display mode afterwards, whereas:</P>
  116. <PRE>
  117.     print BOLD, BLUE, "Text\n";</PRE>
  118. <P>will not.</P>
  119. <P>The subroutine interface has the advantage over the constants interface in
  120. that only 2 soubrutines are exported into your namespace, verses 22 in the
  121. constants interface.  On the flip side, the constants interface has the
  122. advantage of better compile time error checking, since misspelled names of
  123. colors or attributes in calls to <CODE>color()</CODE> and <CODE>colored()</CODE> won't be caught
  124. until runtime whereas misspelled names of constants will be caught at
  125. compile time.  So, polute your namespace with almost two dozen subrutines
  126. that you may not even use that oftin, or risk a silly bug by mistyping an
  127. attribute.  Your choice, TMTOWTDI after all.</P>
  128. <P>
  129. <HR>
  130. <H1><A NAME="diagnostics">DIAGNOSTICS</A></H1>
  131. <DL>
  132. <DT><STRONG><A NAME="item_Invalid_attribute_name_%25s">Invalid attribute name %s</A></STRONG><BR>
  133. <DD>
  134. You passed an invalid attribute name to either <CODE>color()</CODE> or colored().
  135. <P></P>
  136. <DT><STRONG><A NAME="item_Identifier_%25s_used_only_once%3A_possible_typo">Identifier %s used only once: possible typo</A></STRONG><BR>
  137. <DD>
  138. You probably mistyped a constant color name such as:
  139. <PRE>
  140.     print FOOBAR "This text is color FOOBAR\n";</PRE>
  141. <P>It's probably better to always use commas after constant names in order to
  142. force the next error.</P>
  143. <P></P>
  144. <DT><STRONG><A NAME="item_No_comma_allowed_after_filehandle">No comma allowed after filehandle</A></STRONG><BR>
  145. <DD>
  146. You probably mistyped a constant color name such as:
  147. <PRE>
  148.     print FOOBAR, "This text is color FOOBAR\n";</PRE>
  149. <P>Generating this fatal compile error is one of the main advantages of using
  150. the constants interface, since you'll immediately know if you mistype a
  151. color name.</P>
  152. <P></P>
  153. <DT><STRONG><A NAME="item_Bareword_%25s_not_allowed_while_%22strict_subs%22_">Bareword %s not allowed while ``strict subs'' in use</A></STRONG><BR>
  154. <DD>
  155. You probably mistyped a constant color name such as:
  156. <PRE>
  157.     $Foobar = FOOBAR . "This line should be blue\n";</PRE>
  158. <P>or:</P>
  159. <PRE>
  160.     @Foobar = FOOBAR, "This line should be blue\n";</PRE>
  161. <P>This will only show up under use strict (another good reason to run under
  162. use strict).</P>
  163. <P></P></DL>
  164. <P>
  165. <HR>
  166. <H1><A NAME="restrictions">RESTRICTIONS</A></H1>
  167. <P>It would be nice if one could leave off the commas around the constants
  168. entirely and just say:</P>
  169. <PRE>
  170.     print BOLD BLUE ON_WHITE "Text\n" RESET;</PRE>
  171. <P>but the syntax of Perl doesn't allow this.  You need a comma after the
  172. string.  (Of course, you may consider it a bug that commas between all the
  173. constants aren't required, in which case you may feel free to insert
  174. commas unless you're using $Term::ANSIColor::AUTORESET.)</P>
  175. <P>For easier debuging, you may prefer to always use the commas when not
  176. setting $Term::ANSIColor::AUTORESET so that you'll get a fatal compile
  177. error rather than a warning.</P>
  178. <P>
  179. <HR>
  180. <H1><A NAME="authors">AUTHORS</A></H1>
  181. <P>Original idea (using constants) by Zenin (<A HREF="mailto:zenin@best.com">zenin@best.com</A>), reimplemented
  182. using subs by Russ Allbery (<A HREF="mailto:rra@stanford.edu">rra@stanford.edu</A>), and then combined with the
  183. original idea by Russ with input from Zenin.</P>
  184. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  185. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  186. <STRONG><P CLASS=block> Term::ANSIColor - Color screen output using ANSI escape sequences</P></STRONG>
  187. </TD></TR>
  188. </TABLE>
  189.  
  190. </BODY>
  191.  
  192. </HTML>
  193.