Revamp of terminal color codes

The core module related to coloring terminal output was old and needed
some love.  The main thing here was an attempt to get rid of the
obscene number of stack-local buffers that were allocated for no other
reason than to colorize some output.  Instead, this uses a simple trick
to allocate several buffers within threadlocal storage, then
automatically rotates between them, so that you can make multiple calls
to the colorization routine within one function and not need to
allocate multiple buffers.

Review: https://reviewboard.asterisk.org/r/2241/
Patches:
    bug.patch uploaded by Tilghman Lesher


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@381448 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 57 insertions, 16 deletions

diff --git a/include/asterisk/term.h b/include/asterisk/term.h
index bbdc75319..18d743b76 100644
--- a/include/asterisk/term.h
+++ b/include/asterisk/term.h
@@ -29,7 +29,7 @@ extern "C" {
 
 #define ESC 0x1b
 
-/*! \name Terminal Attributes 
+/*! \name Terminal Attributes
 */
 /*@{ */
 #define ATTR_RESET	0
@@ -44,17 +44,17 @@ extern "C" {
 /*! \name Terminal Colors
 */
 /*@{ */
-#define COLOR_BLACK 	30
-#define COLOR_GRAY  	(30 | 128)
-#define COLOR_RED	31
-#define COLOR_BRRED	(31 | 128)
-#define COLOR_GREEN	32
-#define COLOR_BRGREEN	(32 | 128)
-#define COLOR_BROWN	33
-#define COLOR_YELLOW	(33 | 128)
-#define COLOR_BLUE	34
-#define COLOR_BRBLUE	(34 | 128)
-#define COLOR_MAGENTA	35
+#define COLOR_BLACK     30
+#define COLOR_GRAY      (30 | 128)
+#define COLOR_RED       31
+#define COLOR_BRRED     (31 | 128)
+#define COLOR_GREEN     32
+#define COLOR_BRGREEN   (32 | 128)
+#define COLOR_BROWN     33
+#define COLOR_YELLOW    (33 | 128)
+#define COLOR_BLUE      34
+#define COLOR_BRBLUE    (34 | 128)
+#define COLOR_MAGENTA   35
 #define COLOR_BRMAGENTA (35 | 128)
 #define COLOR_CYAN      36
 #define COLOR_BRCYAN    (36 | 128)
@@ -62,10 +62,27 @@ extern "C" {
 #define COLOR_BRWHITE   (37 | 128)
 /*@} */
 
+/*! \brief Shortcut macros for coloring a set of text
+ */
+#define COLORIZE_FMT	"%s%s%s"
+#define COLORIZE(fg, bg, str)	ast_term_color(fg,bg),str,ast_term_reset()
 /*! \brief Maximum number of characters needed for a color escape sequence,
  *         plus a null char */
-#define AST_TERM_MAX_ESCAPE_CHARS   23
+#define AST_TERM_MAX_ESCAPE_CHARS   12
+#define AST_TERM_MAX_ROTATING_BUFFERS	15
 
+/*! \brief Colorize a specified string by adding terminal color codes
+ *
+ * \param outbuf Result buffer
+ * \param inbuf Starting string
+ * \param fgcolor Foreground color, specified as one of the constants in include/asterisk/term.h.  Use '0' if the want the normal terminal foreground color.
+ * \param bgcolor Background color, specified as one of the constants in include/asterisk/term.h.  Use '0' if you want the normal terminal background color.
+ * \param maxout Maximum size of outbuf
+ *
+ * \return outbuf
+ *
+ * \deprecated Due to the necessity of pre-sizing a result buffer, new code should avoid using this function in preference to ast_term_color_code() or ast_term_color().
+ */
 char *term_color(char *outbuf, const char *inbuf, int fgcolor, int bgcolor, int maxout);
 
 /*!
@@ -81,28 +98,52 @@ char *term_color(char *outbuf, const char *inbuf, int fgcolor, int bgcolor, int
 int ast_term_color_code(struct ast_str **str, int fgcolor, int bgcolor);
 
 /*!
+ * \brief Return a color sequence string
+ * \param fgcolor foreground color
+ * \param bgcolor background color
+ * \note This function may be called up to 15 times within the arguments to a single function without the danger of overwriting a common buffer.
+ *
+ * \return A color sequence string, or the empty string, on error
+ */
+const char *ast_term_color(int fgcolor, int bgcolor);
+
+/*!
+ * \brief Returns the terminal reset code
+ * \return String which, when sent to the screen, resets the terminal colors
+ */
+const char *ast_term_reset(void);
+
+/*!
  * \brief Write a color sequence to a string
  *
  * \param outbuf the location to write to
  * \param fgcolor foreground color
  * \param bgcolor background color
  * \param maxout maximum number of characters to write
+ * \deprecated You should use ast_term_color_code or ast_term_color, instead.
  *
  * \return outbuf
  */
 char *term_color_code(char *outbuf, int fgcolor, int bgcolor, int maxout);
 
+/*!
+ * \brief Remove colorings from a specified string
+ * \param outbuf the location to write to
+ * \param inbuf the original string
+ * \param maxout the available size of outbuf
+ * \return outbuf
+ */
 char *term_strip(char *outbuf, const char *inbuf, int maxout);
 
 void term_filter_escapes(char *line);
 
 char *term_prompt(char *outbuf, const char *inbuf, int maxout);
 
-char *term_prep(void);
+const char *term_prep(void);
 
-char *term_end(void);
+const char *term_end(void);
 
-char *term_quit(void);
+const char *term_quit(void);
 
 #if defined(__cplusplus) || defined(c_plusplus)
 }