From d31750cb9375a961bf225ede210435751edfe7c9 Mon Sep 17 00:00:00 2001
From: red-001 <red-001@outlook.ie>
Date: Fri, 17 Mar 2017 18:20:13 +0000
Subject: [PATCH] Give CSM access to use `core.colorize()` (#5113)

---
 builtin/common/misc_helpers.lua | 32 +++++++++++++++++++++++++++
 builtin/game/misc.lua           | 31 ---------------------------
 clientmods/preview/init.lua     |  6 ++++++
 doc/client_lua_api.md           | 38 +++++++++++++++++++++++++++++++--
 4 files changed, 74 insertions(+), 33 deletions(-)

diff --git a/builtin/common/misc_helpers.lua b/builtin/common/misc_helpers.lua
index 70b23600a..e145a5bfc 100644
--- a/builtin/common/misc_helpers.lua
+++ b/builtin/common/misc_helpers.lua
@@ -638,3 +638,35 @@ if INIT == "client" or INIT == "mainmenu" then
 		return core.formspec_escape(fgettext_ne(text, ...))
 	end
 end
+
+-- Client-sided mods don't have access to getbool
+if core.setting_getbool and core.setting_getbool("disable_escape_sequences") then
+
+	function core.get_color_escape_sequence(color)
+		return ""
+	end
+
+	function core.get_background_escape_sequence(color)
+		return ""
+	end
+
+	function core.colorize(color, message)
+		return message
+	end
+
+else
+
+	local ESCAPE_CHAR = string.char(0x1b)
+	function core.get_color_escape_sequence(color)
+		return ESCAPE_CHAR .. "(c@" .. color .. ")"
+	end
+
+	function core.get_background_escape_sequence(color)
+		return ESCAPE_CHAR .. "(b@" .. color .. ")"
+	end
+
+	function core.colorize(color, message)
+		return core.get_color_escape_sequence(color) .. message .. core.get_color_escape_sequence("#ffffff")
+	end
+
+end
diff --git a/builtin/game/misc.lua b/builtin/game/misc.lua
index 25376c180..618d4d97f 100644
--- a/builtin/game/misc.lua
+++ b/builtin/game/misc.lua
@@ -170,37 +170,6 @@ function core.http_add_fetch(httpenv)
 	return httpenv
 end
 
-if minetest.setting_getbool("disable_escape_sequences") then
-
-	function core.get_color_escape_sequence(color)
-		return ""
-	end
-
-	function core.get_background_escape_sequence(color)
-		return ""
-	end
-
-	function core.colorize(color, message)
-		return message
-	end
-
-else
-
-	local ESCAPE_CHAR = string.char(0x1b)
-	function core.get_color_escape_sequence(color)
-		return ESCAPE_CHAR .. "(c@" .. color .. ")"
-	end
-
-	function core.get_background_escape_sequence(color)
-		return ESCAPE_CHAR .. "(b@" .. color .. ")"
-	end
-
-	function core.colorize(color, message)
-		return core.get_color_escape_sequence(color) .. message .. core.get_color_escape_sequence("#ffffff")
-	end
-
-end
-
 function core.close_formspec(player_name, formname)
 	return minetest.show_formspec(player_name, formname, "")
 end
diff --git a/clientmods/preview/init.lua b/clientmods/preview/init.lua
index 25a61da51..008f7ac14 100644
--- a/clientmods/preview/init.lua
+++ b/clientmods/preview/init.lua
@@ -40,6 +40,12 @@ core.register_chatcommand("dump", {
 	end,
 })
 
+core.register_chatcommand("colorize_test", {
+	func = function(param)
+		return true, core.colorize("red", param)
+	end,
+})
+
 core.register_chatcommand("test_node", {
 	func = function(param)
 		core.display_chat_message(dump(core.get_node({x=0, y=0, z=0})))
diff --git a/doc/client_lua_api.md b/doc/client_lua_api.md
index 70716ee41..5fba66c69 100644
--- a/doc/client_lua_api.md
+++ b/doc/client_lua_api.md
@@ -787,12 +787,12 @@ Call these functions only at load time!
       extra arguments and return the result
 * `fgettext(string, ...)` : returns string
     * same as fgettext_ne(), but calls core.formspec_escape before returning result
-* `show_formspec(formname, formspec)` : returns true on success
-	* Shows a formspec to the player
 
 ### UI
 * `minetest.ui.minimap`
     * Reference to the minimap object. See `Minimap` class reference for methods.
+* `show_formspec(formname, formspec)` : returns true on success
+	* Shows a formspec to the player
 
 Class reference
 ---------------
@@ -837,3 +837,37 @@ Definition tables
         func = function(name, param), -- Called when command is run.
                                       -- Returns boolean success and text output.
     }
+
+Escape sequences
+----------------
+Most text can contain escape sequences, that can for example color the text.
+There are a few exceptions: tab headers, dropdowns and vertical labels can't.
+The following functions provide escape sequences:
+* `core.get_color_escape_sequence(color)`:
+    * `color` is a ColorString
+    * The escape sequence sets the text color to `color`
+* `core.colorize(color, message)`:
+    * Equivalent to:
+      `core.get_color_escape_sequence(color) ..
+       message ..
+       core.get_color_escape_sequence("#ffffff")`
+* `color.get_background_escape_sequence(color)`
+    * `color` is a ColorString
+    * The escape sequence sets the background of the whole text element to
+      `color`. Only defined for item descriptions and tooltips.
+	  
+`ColorString`
+-------------
+`#RGB` defines a color in hexadecimal format.
+
+`#RGBA` defines a color in hexadecimal format and alpha channel.
+
+`#RRGGBB` defines a color in hexadecimal format.
+
+`#RRGGBBAA` defines a color in hexadecimal format and alpha channel.
+
+Named colors are also supported and are equivalent to
+[CSS Color Module Level 4](http://dev.w3.org/csswg/css-color/#named-colors).
+To specify the value of the alpha channel, append `#AA` to the end of the color name
+(e.g. `colorname#08`). For named colors the hexadecimal string representing the alpha
+value must (always) be two hexadecima
\ No newline at end of file