GUIUtils.lua

----------------------------------------------------------------------------------
--- Mudlet GUI Utils
----------------------------------------------------------------------------------


--- The <i>gaugesTable table</i>. First we need to make this table which will be
--- used later to store important data in.
---
--- @class function
--- @name gaugesTable
gaugesTable = {}



--- The <i>color_table table</i> holds definition of color names. These are intended to be
-- used in conjunction with fg() and bg() colorizer functions.
-- Mudlet's original table - going back a few years - differs from the
-- "standard" which can be found at https://www.w3.org/TR/SVG11/types.html#ColorKeywords
-- Mudlet has additional colours not in the standard:
-- "light_goldenrod", "light_slate_blue", "navy_blue" and "violet_red"
-- Mudlet is missing some colours:
-- "aqua", "fuchsia", "dark_blue", "dark_cyan", "dark_gray"/"dark_grey",
-- "dark_magenta", "dark_red", "indigo", "light_green", "olive", "silver",
-- "teal", "violet_red"
-- Also Mudlet redefines:
-- "gray"/"grey", "green", "maroon" and "purple"
-- All of the above also implies the Camel Case equivalents; in summary:
--  Colour               Mudlet            Web Standard
--  aqua                                     0, 255, 255
--  fuchsia                                255,   0, 255
--  dark_blue                                0,   0, 139
--  dark_gray/dark_grey                    169, 169, 169
--  dark_magenta                           139,   0, 139
--  dark_red                               139,   0,   0
--  gray/grey            190, 190, 190     128, 128, 128
--  green                  0, 255,   0       0, 128,   0
--  indigo                                  75,   0, 130
--  light_goldrod        238, 221, 130
--  light_slate_blue     132, 112, 255
--  light_green                            144, 238, 144
--  maroon               176,  48,  96     128,   0,   0
--  navy_blue              0,   0, 128
--  olive                                  128, 128,   0
--  purple               160,  32, 240     128,   0, 128
--  silver                                 192, 192, 192
--  teal                                     0, 128, 128
--  violet_red                             208,  32, 240
-- @see showColors
-- @see bg
-- @see fg
-- @class function
-- @name color_table
color_table = {
	alice_blue            = {240, 248, 255},
	AliceBlue             = {240, 248, 255},
	antique_white         = {250, 235, 215},
	AntiqueWhite          = {250, 235, 215},
	aquamarine            = {127, 255, 212},
	azure                 = {240, 255, 255},
	beige                 = {245, 245, 220},
	bisque                = {255, 228, 196},
	black                 = {0, 0, 0},
	blanched_almond       = {255, 235, 205},
	BlanchedAlmond        = {255, 235, 205},
	blue                  = {0, 0, 255},
	blue_violet           = {138, 43, 226},
	BlueViolet            = {138, 43, 226},
	brown                 = {165, 42, 42},
	burlywood             = {222, 184, 135},
	cadet_blue            = {95, 158, 160},
	CadetBlue             = {95, 158, 160},
	chartreuse            = {127, 255, 0},
	chocolate             = {210, 105, 30},
	coral                 = {255, 127, 80},
	cornflower_blue       = {100, 149, 237},
	CornflowerBlue        = {100, 149, 237},
	cornsilk              = {255, 248, 220},
	cyan                  = {0, 255, 255},
	dark_goldenrod        = {184, 134, 11},
	DarkGoldenrod         = {184, 134, 11},
	dark_green            = {0, 100, 0},
	DarkGreen             = {0, 100, 0},
	dark_khaki            = {189, 183, 107},
	DarkKhaki             = {189, 183, 107},
	dark_olive_green      = {85, 107, 47},
	DarkOliveGreen        = {85, 107, 47},
	dark_orange           = {255, 140, 0},
	DarkOrange            = {255, 140, 0},
	dark_orchid           = {153, 50, 204},
	DarkOrchid            = {153, 50, 204},
	dark_salmon           = {233, 150, 122},
	DarkSalmon            = {233, 150, 122},
	dark_slate_blue       = {72, 61, 139},
	dark_sea_green        = {143, 188, 143},
	DarkSeaGreen          = {143, 188, 143},
	DarkSlateBlue         = {72, 61, 139},
	dark_slate_gray       = {47, 79, 79},
	DarkSlateGray         = {47, 79, 79},
	dark_slate_grey       = {47, 79, 79},
	DarkSlateGrey         = {47, 79, 79},
	dark_turquoise        = {0, 206, 209},
	DarkTurquoise         = {0, 206, 209},
	dark_violet           = {148, 0, 211},
	DarkViolet            = {148, 0, 211},
	deep_pink             = {255, 20, 147},
	DeepPink              = {255, 20, 147},
	deep_sky_blue         = {0, 191, 255},
	DeepSkyBlue           = {0, 191, 255},
	dodger_blue           = {30, 144, 255},
	DodgerBlue            = {30, 144, 255},
	dim_gray              = {105, 105, 105},
	DimGray               = {105, 105, 105},
	dim_grey              = {105, 105, 105},
	DimGrey               = {105, 105, 105},
	firebrick             = {178, 34, 34},
	floral_white          = {255, 250, 240},
	FloralWhite           = {255, 250, 240},
	forest_green          = {34, 139, 34},
	ForestGreen           = {34, 139, 34},
	gainsboro             = {220, 220, 220},
	ghost_white           = {248, 248, 255},
	GhostWhite            = {248, 248, 255},
	gold                  = {255, 215, 0},
	goldenrod             = {218, 165, 32},
	gray                  = {190, 190, 190},
	grey                  = {190, 190, 190},
	green                 = {0, 255, 0},
	green_yellow          = {173, 255, 47},
	GreenYellow           = {173, 255, 47},
	honeydew              = {240, 255, 240},
	hot_pink              = {255, 105, 180},
	HotPink               = {255, 105, 180},
	indian_red            = {205, 92, 92},
	IndianRed             = {205, 92, 92},
	khaki                 = {240, 230, 140},
	ivory                 = {255, 255, 240},
	lavender              = {230, 230, 250},
	lavender_blush        = {255, 240, 245},
	LavenderBlush         = {255, 240, 245},
	lawn_green            = {124, 252, 0},
	LawnGreen             = {124, 252, 0},
	lemon_chiffon         = {255, 250, 205},
	LemonChiffon          = {255, 250, 205},
	light_blue            = {173, 216, 230},
	LightBlue             = {173, 216, 230},
	light_coral           = {240, 128, 128},
	LightCoral            = {240, 128, 128},
	light_cyan            = {224, 255, 255},
	LightCyan             = {224, 255, 255},
	light_goldenrod       = {238, 221, 130},
	LightGoldenrod        = {238, 221, 130},
	light_goldenrod_yellow= {250, 250, 210},
	LightGoldenrodYellow  = {250, 250, 210},
	light_gray            = {211, 211, 211},
	LightGray             = {211, 211, 211},
	light_grey            = {211, 211, 211},
	LightGrey             = {211, 211, 211},
	light_pink            = {255, 182, 193},
	LightPink             = {255, 182, 193},
	light_salmon          = {255, 160, 122},
	LightSalmon           = {255, 160, 122},
	light_sea_green       = {32, 178, 170},
	LightSeaGreen         = {32, 178, 170},
	light_sky_blue        = {135, 206, 250},
	LightSkyBlue          = {135, 206, 250},
	light_slate_blue      = {132, 112, 255},
	LightSlateBlue        = {132, 112, 255},
	light_slate_gray      = {119, 136, 153},
	LightSlateGray        = {119, 136, 153},
	light_slate_grey      = {119, 136, 153},
	LightSlateGrey        = {119, 136, 153},
	light_steel_blue      = {176, 196, 222},
	LightSteelBlue        = {176, 196, 222},
	light_yellow          = {255, 255, 224},
	LightYellow           = {255, 255, 224},
	lime_green            = {50, 205, 50},
	LimeGreen             = {50, 205, 50},
	linen                 = {250, 240, 230},
	magenta               = {255, 0, 255},
	maroon                = {176, 48, 96},
	medium_aquamarine     = {102, 205, 170},
	MediumAquamarine      = {102, 205, 170},
	medium_blue           = {0, 0, 205},
	MediumBlue            = {0, 0, 205},
	medium_orchid         = {186, 85, 211},
	MediumOrchid          = {186, 85, 211},
	medium_purple         = {147, 112, 219},
	MediumPurple          = {147, 112, 219},
	medium_sea_green      = {60, 179, 113},
	MediumSeaGreen        = {60, 179, 113},
	medium_slate_blue     = {123, 104, 238},
	MediumSlateBlue       = {123, 104, 238},
	medium_spring_green   = {0, 250, 154},
	MediumSpringGreen     = {0, 250, 154},
	medium_turquoise      = {72, 209, 204},
	MediumTurquoise       = {72, 209, 204},
	medium_violet_red     = {199, 21, 133},
	MediumVioletRed       = {199, 21, 133},
	midnight_blue         = {25, 25, 112},
	MidnightBlue          = {25, 25, 112},
	mint_cream            = {245, 255, 250},
	MintCream             = {245, 255, 250},
	misty_rose            = {255, 228, 225},
	MistyRose             = {255, 228, 225},
	moccasin              = {255, 228, 181},
	navajo_white          = {255, 222, 173},
	NavajoWhite           = {255, 222, 173},
	navy                  = {0, 0, 128},
	navy_blue             = {0, 0, 128},
	NavyBlue              = {0, 0, 128},
	old_lace              = {253, 245, 230},
	OldLace               = {253, 245, 230},
	olive_drab            = {107, 142, 35},
	OliveDrab             = {107, 142, 35},
	orange                = {255, 165, 0},
	orange_red            = {255, 69, 0},
	OrangeRed             = {255, 69, 0},
	orchid                = {218, 112, 214},
	pale_goldenrod        = {238, 232, 170},
	PaleGoldenrod         = {238, 232, 170},
	pale_green            = {152, 251, 152},
	PaleGreen             = {152, 251, 152},
	pale_turquoise        = {175, 238, 238},
	PaleTurquoise         = {175, 238, 238},
	pale_violet_red       = {219, 112, 147},
	PaleVioletRed         = {219, 112, 147},
	papaya_whip           = {255, 239, 213},
	PapayaWhip            = {255, 239, 213},
	peach_puff            = {255, 218, 185},
	PeachPuff             = {255, 218, 185},
	peru                  = {205, 133, 63},
	pink                  = {255, 192, 203},
	plum                  = {221, 160, 221},
	powder_blue           = {176, 224, 230},
	PowderBlue            = {176, 224, 230},
	purple                = {160, 32, 240},
	royal_blue            = {65, 105, 225},
	RoyalBlue             = {65, 105, 225},
	red                   = {255, 0, 0},
	rosy_brown            = {188, 143, 143},
	RosyBrown             = {188, 143, 143},
	saddle_brown          = {139, 69, 19},
	SaddleBrown           = {139, 69, 19},
	salmon                = {250, 128, 114},
	sandy_brown           = {244, 164, 96},
	SandyBrown            = {244, 164, 96},
	sea_green             = {46, 139, 87},
	SeaGreen              = {46, 139, 87},
	seashell              = {255, 245, 238},
	sienna                = {160, 82, 45},
	sky_blue              = {135, 206, 235},
	SkyBlue               = {135, 206, 235},
	slate_blue            = {106, 90, 205},
	SlateBlue             = {106, 90, 205},
	slate_gray            = {112, 128, 144},
	SlateGray             = {112, 128, 144},
	slate_grey            = {112, 128, 144},
	SlateGrey             = {112, 128, 144},
	snow                  = {255, 250, 250},
	steel_blue            = {70, 130, 180},
	SteelBlue             = {70, 130, 180},
	spring_green          = {0, 255, 127},
	SpringGreen           = {0, 255, 127},
	tan                   = {210, 180, 140},
	thistle               = {216, 191, 216},
	tomato                = {255, 99, 71},
	turquoise             = {64, 224, 208},
	violet_red            = {208, 32, 144},
	VioletRed             = {208, 32, 144},
	violet                = {238, 130, 238},
	wheat                 = {245, 222, 179},
	white                 = {255, 255, 255},
	white_smoke           = {245, 245, 245},
	WhiteSmoke            = {245, 245, 245},
	yellow                = {255, 255, 0},
	yellow_green          = {154, 205, 50},
	YellowGreen           = {154, 205, 50}
}


--- Move a custom gauge.
---
--- @usage This would move the health bar gauge to the location 1200, 400.
---   <pre>
---   moveGauge("healthBar", 1200, 400)
---   </pre>
---
--- @see createGauge
function moveGauge(gaugeName, x, y)
    assert(gaugesTable[gaugeName], "moveGauge: no such gauge exists.")
    assert(x and y, "moveGauge: need to have both X and Y dimensions.")
    moveWindow(gaugeName .. "_back", x, y)
    moveWindow(gaugeName .. "_text", x, y)
    -- save new values in table
    gaugesTable[gaugeName].x, gaugesTable[gaugeName].y = x, y
    setGauge(gaugeName, gaugesTable[gaugeName].value, 1)
end


--- Hide a custom gauge.
---
--- @usage This should hide the given gauge.
---   <pre>
---   hideGauge("healthBar")
---   </pre>
---
--- @see createGauge, moveGauge, showGauge
function hideGauge(gaugeName)
    assert(gaugesTable[gaugeName], "hideGauge: no such gauge exists.")
    hideWindow(gaugeName .. "_back")
    hideWindow(gaugeName .. "_front")
    hideWindow(gaugeName .. "_text")
end


--- Show a custom gauge.
---
--- @usage This should show the given gauge.
---   <pre>
---   showGauge("healthBar")
---   </pre>
---
--- @see createGauge, moveGauge, hideGauge
function showGauge(gaugeName)
	assert(gaugesTable[gaugeName], "showGauge: no such gauge exists.")
	showWindow(gaugeName .. "_back")
	showWindow(gaugeName .. "_front")
	showWindow(gaugeName .. "_text")
end


--- Set the text on a custom gauge.
---
--- @usage
---   <pre>
---   setGaugeText("healthBar", "HP: 100%", 40, 40, 40)
---   </pre>
--- @usage
---   <pre>
---   setGaugeText("healthBar", "HP: 100%", "red")
---   </pre>
---
--- @param gaugeName
--- @param gaugeText An empty gaugeText will clear the text entirely.
--- @param color1 Colors are optional and will default to 0,0,0(black) if not passed as args.
--- @param color2
--- @param color3
---
--- @see createGauge
function setGaugeText(gaugeName, gaugeText, r, g, b)
        assert(gaugesTable[gaugeName], "setGaugeText: no such gauge exists.")
        if r ~= nil then
                if g == nil then
                        r,g,b = getRGB(r)
                end
        else
                r,g,b = 0,0,0
        end
        gaugeText = gaugeText or ""
        local echoString = [[<font color="#]] .. RGB2Hex(r,g,b) .. [[">]] .. gaugeText .. [[</font>]]
        echo(gaugeName .. "_text", echoString)
        -- save new values in table
        gaugesTable[gaugeName].text = echoString
end



--- Pads a hex number to ensure a minimum of 2 digits.
---
--- @usage Following command will returns "F0".
---   <pre>
---   PadHexNum("F")
---   </pre>
function PadHexNum(incString)
	local l_Return = incString
	if tonumber(incString,16)<16 then
		if tonumber(incString,16)<10 then
			l_Return = "0" .. l_Return
		elseif tonumber(incString,16)>10 then
			l_Return = l_Return .. "0"
		end
	end

	return l_Return
end



--- Converts an RGB value into an HTML compliant(label usable) HEX number.
--- This function is colorNames aware and can take any defined global color as its first argument.
---
--- @usage Both following commands will returns "FFFFFF".
---   <pre>
---   RGB2Hex(255,255,255)
---   RGB2Hex("white")
---   </pre>
---
--- @see showColor
function RGB2Hex(red, green, blue)
	local l_Red, l_Green, l_Blue = 0,0,0
	if green == nil then -- Not an RGB but a "color" instead!
		l_Red, l_Green, l_Blue = getRGB(red)
	else -- Nope, true color here
		l_Red, l_Green, l_Blue = red, green, blue
	end

	return PadHexNum(string.format("%X",l_Red)) ..
		PadHexNum(string.format("%X",l_Green)) ..
		PadHexNum(string.format("%X",l_Blue))
end



--- Get RGB component from color name.
---
--- @usage Following will display "0.255.0" on your screen.
---   <pre>
---   local red, green, blue = getRGB("green")
---   echo(red .. "." .. green .. "." .. blue )
---   </pre>
function getRGB(colorName)
	local red = color_table[colorName][1]
	local green = color_table[colorName][2]
	local blue = color_table[colorName][3]
	return red, green, blue
end



--- Make your very own customized gauge with this function.
---
--- @usage This would make a gauge at that's 300px width, 20px in height, located at Xpos and Ypos and is green.
---   <pre>
---   createGauge("healthBar", 300, 20, 30, 300, nil, 0, 255, 0)
---   </pre>
--- @usage The second example is using the same names you'd use for something like fg() or bg().
---   <pre>
---   createGauge("healthBar", 300, 20, 30, 300, nil, "green")
---   </pre>
--- @usage Finally we'll add some text to our gauge.
---   <pre>
---   createGauge("healthBar", 300, 20, 30, 300, "Now with some text", "green")
---   </pre>
--- @usage You can add an orientation argument as well now:
---   <pre>
---   createGauge("healthBar", 300, 20, 30, 300, "Now with some text", "green", "horizontal, vertical, goofy, or batty")
---   </pre>
function createGauge(gaugeName, width, height, x, y, gaugeText, r, g, b, orientation)
    gaugeText = gaugeText or ""
    if type(r) == "string" then
            orientation = g
            r,g,b = getRGB(r)
    elseif r == nil then
            orientation = orientation or g
            -- default colors
            r,g,b = 128,128,128
    end

    orientation = orientation or "horizontal"
    assert(table.contains({"horizontal","vertical","goofy","batty"},orientation), "createGauge: orientation must be horizontal, vertical, goofy, or batty")
    local tbl = {width = width, height = height, x = x, y = y, text = gaugeText, r = r, g = g, b = b, orientation = orientation, value = 1}
    createLabel(gaugeName .. "_back", 0,0,0,0,1)
    setBackgroundColor(gaugeName .. "_back", r, g, b, 100)

    createLabel(gaugeName .. "_front", 0,0,0,0,1)
    setBackgroundColor(gaugeName .. "_front", r, g, b, 255)

    createLabel(gaugeName .. "_text", 0,0,0,0,1)
    setBackgroundColor(gaugeName .. "_text", 0, 0, 0, 0)

    -- save new values in table
    gaugesTable[gaugeName] = tbl
    resizeGauge(gaugeName, tbl.width, tbl.height)
    moveGauge(gaugeName, tbl.x, tbl.y)
    setGaugeText(gaugeName, gaugeText, "black")
    showGauge(gaugeName)
end



--- Use this function when you want to change the gauges look according to your values.
--- Typical usage would be in a prompt with your current health or whatever value, and throw
--- in some variables instead of the numbers.
---
--- @usage In that example, we'd change the looks of the gauge named healthBar and make it fill
---   to half of its capacity. The height is always remembered.
---   <pre>
---   setGauge("healthBar", 200, 400)
---   </pre>
--- @usage Change the text on your gauge.
---   <pre>
---   setGauge("healthBar", 200, 400, "some text")
---   </pre>
function setGauge(gaugeName, currentValue, maxValue, gaugeText)
    assert(gaugesTable[gaugeName], "setGauge: no such gauge exists.")
    assert(currentValue and maxValue, "setGauge: need to have both current and max values.")
    local value = currentValue / maxValue
    -- save new values in table
    gaugesTable[gaugeName].value = value
    local info = gaugesTable[gaugeName]
    local x,y,w,h = info.x, info.y, info.width, info.height

    if info.orientation == "horizontal" then
    resizeWindow(gaugeName .. "_front", w * value, h)
    moveWindow(gaugeName .. "_front", x, y)
    elseif info.orientation == "vertical" then
    resizeWindow(gaugeName .. "_front", w, h * value)
    moveWindow(gaugeName .. "_front", x, y + h * (1 - value))
    elseif info.orientation == "goofy" then
    resizeWindow(gaugeName .. "_front", w * value, h)
    moveWindow(gaugeName .. "_front", x + w * (1 - value), y)
    elseif info.orientation == "batty" then
    resizeWindow(gaugeName .. "_front", w, h * value)
    moveWindow(gaugeName .. "_front", x, y)
    end
    if gaugeText then
            setGaugeText(gaugeName, gaugeText)
    end
end



--- Make a new console window with ease. The default background is black and text color white.
--- If you wish to change the color you can easily do this when updating your text or manually somewhere, using
--- setFgColor() and setBackgroundColor().
---
--- @usage This will create a miniconsole window that has a font size of 8pt, will display 80 characters in width,
---   hold a maximum of 20 lines and be place at 200x400 of your Mudlet window.
---   <pre>
---   createConsole("myConsoleWindow", 8, 80, 20, 200, 400)
---   </pre>
function createConsole(consoleName, fontSize, charsPerLine, numberOfLines, Xpos, Ypos)
	createMiniConsole(consoleName,0,0,1,1)
	setMiniConsoleFontSize(consoleName, fontSize)
	local x,y = calcFontSize( fontSize )
	resizeWindow(consoleName, x*charsPerLine, y*numberOfLines)
	setWindowWrap(consoleName, charsPerLine)
	moveWindow(consoleName, Xpos, Ypos)

	setBackgroundColor(consoleName,0,0,0,0)
	setFgColor(consoleName, 255,255,255)
end



--- Suffixes text at the end of the current line when used in a trigger.
---
--- @see prefix
function suffix(what, func, fg, bg, window)
	local length = string.len(line)
	moveCursor(window or "main", length-1, getLineNumber())
	if func and (func == cecho or func == decho or func == hecho) then
		func(what, fg, bg, true, window)
	else
		insertText(what)
	end
end



--- Prefixes text at the beginning of the current line when used in a trigger.
---
--- @usage Prefix the hours, minutes and seconds onto our prompt even though Mudlet has a button for that.
---   <pre>
---   prefix(os.date("%H:%M:%S "))
---   </pre>
---
--- @see suffix
function prefix(what, func, fg, bg, window)
	moveCursor(window or "main", 0, getLineNumber());
	if func and (func == cecho or func == decho or func == hecho) then
		func(what, fg, bg, true, window)
	else
		insertText(what)
	end
end



--- Function will gag the whole line. <b>Use deleteLine() instead.</b>
function gagLine()
	deleteLine()
end



--- Replaces all occurrences of what in the current line with <i>with</i>.
---
--- @usage This will replace all occurrences of John with the word Doe.
---   <pre>
---   replaceAll("John", "Doe")
---
---   -- also handles recursive matches:
---   replaceAll("you", "you and me")
---   </pre>
function replaceAll(word, what)
  local startp, endp = 1, 1
  while true do
    startp, endp = getCurrentLine():find(word, endp+(#what-#word)+1)
    if not startp then break end
    selectSection(startp-1, endp-startp+1)
    replace(what)
  end
end



--- Replace the whole with a string you'd like.
---
--- @see deleteLine
function replaceLine(what)
	selectString(line, 1)
	replace("")
	insertText(what)
end



--- Default resizeEvent handler function. Overwrite this function to make a custom event handler
--- if the main window is being resized. <br/><br/>
---
--- The standard implementation of this function does nothing. However, this function gets called whenever
--- the main window is being manually resized. You can overwrite this function in your own scripts to handle window
--- resize events yourself and e.g. adjust the screen position and size of your mini console windows, labels or
--- other relevant GUI elements in your scripts that depend on the size of the main Window. To override this
--- function you can simply put a function with the same name in one of your scripts thus overwriting the
--- original empty implementation of this function.
---   <pre>
---   function handleWindowResizeEvent()
---      -- determine the size of your screen
---      WindowWidth=0;
---      WindowHeight=0;
---      WindowWidth, WindowHeight = getMainWindowSize();
---      -- move mini console "sys" to the far right side of the screen whenever the screen gets resized
---      moveWindow("sys",WindowWidth-300,0)
---   end
---   </pre>
function handleWindowResizeEvent()
end


--- Sets current background color to a named color.
---
--- @usage Set background color to magenta.
---   <pre>
---   bg("magenta")
---
---   bg("my miniconsole", "blue")
---   </pre>
---
--- @see fg
--- @see showColors
function bg(console, colorName)
	local colorName = colorName or console
	if not color_table[colorName] then
		error(string.format("bg: '%s' color doesn't exist - see showColors()", colorName))
	end

	if console == colorName or console == "main" then
		setBgColor(color_table[colorName][1], color_table[colorName][2], color_table[colorName][3])
	else
		setBgColor(console, color_table[colorName][1], color_table[colorName][2], color_table[colorName][3])
	end
end



--- Sets current foreground color to a named color.
---
--- @usage Set foreground color to black.
---   <pre>
---   fg("black")
---   </pre>
---
--- @see bg
--- @see showColors
function fg(console, colorName)
	local colorName = colorName or console
	if not color_table[colorName] then
		error(string.format("fg: '%s' color doesn't exist - see showColors()", colorName))
	end

	if console == colorName or console == "main" then
		setFgColor(color_table[colorName][1], color_table[colorName][2], color_table[colorName][3])
	else
		setFgColor(console, color_table[colorName][1], color_table[colorName][2], color_table[colorName][3])
	end
end



--- Replaces the given wildcard (as a number) with the given text.
---
--- @usage Replace "goodbye" with "hello" on a trigger of "^You wave (goodbye)\.$"
---   <pre>
---   replaceWildcard(2, "hello")
---   </pre>
---   Is equivalent to doing:
---   <pre>
---   selectString(matches[2], 1)
---   replace("hello")
---   </pre>
function replaceWildcard(what, replacement)
	if replacement == nil or what == nil then
		return
	end
	selectCaptureGroup(what)
	replace(replacement)
end



--- Prints out a formatted list of all available named colors, optional arg specifies number of columns to print in, defaults to 3
---
--- @usage Print list in 3 columns by default.
---   <pre>
---   showColors()
---   </pre>
--- @usage Print list in 2 columns.
---   <pre>
---   showColors(2)
---   </pre>
---
--- @see color_table
function showColors(...)
   local args = {...}
   local n = #args
   local cols, search
   if n > 1 then
      cols, search = args[1], args[2]
   elseif n == 1 and type(args[1]) == "string" then
      search = args[1]
   elseif n == 1 and type(args[1]) == "number" then
      cols = args[1]
   elseif n == 0 then
      cols = 4
      search = ""
   else
      error("showColors: Improper usage. Use showColors(columns, search)")
   end
   cols = cols or 4
   search = search and search:lower() or ""
   local i = 1
   for k,v in pairs(color_table) do
      if k:lower():find(search) then
         local fgc
         local red, green, blue
         -- local luminosity = (0.2126 * ((v[1]/255)^2.2)) + (0.7152 * ((v[2]/255)^2.2)) + (0.0722 * ((v[3]/255)^2.2))
         -- The above formula was wrong, according to https://www.w3.org/TR/WCAG20/#relativeluminancedef
         -- it should be:
         if v[1] < 11 then
             red = v[1]/(255 * 12.92)
         else
             red = ((0.055 + v[1]/255)/1.055)^2.4
         end
         if v[2] < 11 then
             green = v[2]/(255 * 12.92)
         else
             green = ((0.055 + v[2]/255)/1.055)^2.4
         end
         if v[3] < 11 then
             blue = v[3]/(255 * 12.92)
         else
             blue = ((0.055 + v[3]/255)/1.055)^2.4
         end
         local luminosity = (0.2126 * red) + (0.7152 * green) + (0.0722 * blue)
         if luminosity > 0.5 then
            fgc = "black"
         else
            fgc = "white"
         end
         fg(fgc)
         bg(k)
         echoLink(k..string.rep(" ", 23-k:len()),[[printCmdLine("]]..k..[[")]],v[1] ..", "..v[2]..", "..v[3],true)
         resetFormat()
         echo("  ")
         if i == cols then
            echo"\n"
            i = 1
         else
            i = i + 1
         end
      end
   end
end




--- <b><u>TODO</u></b> resizeGauge(gaugeName, width, height)
function resizeGauge(gaugeName, width, height)
    assert(gaugesTable[gaugeName], "resizeGauge: no such gauge exists.")
    assert(width and height, "resizeGauge: need to have both width and height.")
    resizeWindow(gaugeName .. "_back", width, height)
    resizeWindow(gaugeName .. "_text", width, height)
    -- save new values in table
    gaugesTable[gaugeName].width, gaugesTable[gaugeName].height = width, height
    setGauge(gaugeName, gaugesTable[gaugeName].value, 1)
end



--- <b><u>TODO</u></b> setGaugeStyleSheet(gaugeName, css, cssback)
function setGaugeStyleSheet(gaugeName, css, cssback, csstext)
    if not setLabelStyleSheet then return end -- mudlet 1.0.5 and lower compatibility
    assert(gaugesTable[gaugeName], "setGaugeStyleSheet: no such gauge exists.")
    setLabelStyleSheet(gaugeName .. "_back", cssback or css)
    setLabelStyleSheet(gaugeName .. "_front", css)
    setLabelStyleSheet(gaugeName .. "_text", csstext or "")
end



if rex then
	_Echos = {
		Patterns = {
			Hex = {
					[[(\x5c?\|c[0-9a-fA-F]{6}?(?:,[0-9a-fA-F]{6})?)|(\|r)]],
					rex.new[[\|c(?:([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2}))?(?:,([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2}))?]],
				},
			Decimal = {
					[[(<[0-9,:]+>)|(<r>)]],
					rex.new[[<(?:([0-9]{1,3}),([0-9]{1,3}),([0-9]{1,3}))?(?::(?=>))?(?::([0-9]{1,3}),([0-9]{1,3}),([0-9]{1,3}))?>]],
				},
			Color = {
					[[(<[a-zA-Z_,:]+>)]],
					rex.new[[<([a-zA-Z_]+)?(?:[:,](?=>))?(?:[:,]([a-zA-Z_]+))?>]],
				},
			Ansi = {
					[[(<[0-9,:]+>)]],
					rex.new[[<([0-9]{1,2})?(?::([0-9]{1,2}))?>]],
				},
			},
		Process = function(str, style)
			local t = {}
			local tonumber, _Echos, color_table = tonumber, _Echos, color_table

			-- s: A subject section (can be an empty string)
			-- c: colour code
			-- r: reset code
			for s, c, r in rex.split(str, _Echos.Patterns[style][1]) do
				if c and (c:byte(1) == 92) then
					c = c:sub(2)
					if s then s = s .. c else s = c end
					c = nil
				end
				if s then t[#t+1] = s end
				if r then t[#t+1] = "\27reset" end
				if c then
					if style == 'Hex' or style == 'Decimal' then
						local fr, fg, fb, br, bg, bb = _Echos.Patterns[style][2]:match(c)
						local color = {}
						if style == 'Hex' then
							if fr and fg and fb then fr, fg, fb = tonumber(fr, 16), tonumber(fg, 16), tonumber(fb, 16) end
							if br and bg and bb then br, bg, bb = tonumber(br, 16), tonumber(bg, 16), tonumber(bb, 16) end
						end
						if fr and fg and fb then color.fg = { fr, fg, fb } end
						if br and bg and bb then color.bg = { br, bg, bb } end

						-- if the colour failed to match anything, then what we captured in <> wasn't a colour -
						-- pass it into the text stream then
						t[#t+1] = ((fr or br) and color or c)
					elseif style == 'Color' then
						if c == "<reset>" then t[#t+1] = "\27reset"
						else
							local fcolor, bcolor = _Echos.Patterns[style][2]:match(c)
							local color = {}
							if fcolor and color_table[fcolor] then color.fg = color_table[fcolor] end
							if bcolor and color_table[bcolor] then color.bg = color_table[bcolor] end
							if color.fg or color.bg then
								t[#t+1] = color
							else
								t[#t+1] = c
							end
						end
					end
				end
			end
			return t
		end,
		}


--- Generic color echo and insert function (allowing hecho, decho, cecho, hinsertText, dinsertText and cinsertText).
---
--- @param style Hex, Decimal or Color
--- @param insert boolean flag to determine echo/insert behaviour
--- @param win windowName optional
--- @param str text with embedded color information
---
--- @see cecho
--- @see decho
--- @see hecho
--- @see cinsertText
--- @see dinsertText
--- @see hinsertText
	function xEcho(style, func, ...)
		local win, str, cmd, hint, fmt
		local out, reset
		local args = {...}
		local n = #args

		if func == 'echoLink' then
			if n < 3 then
				error'Insufficient arguments, usage: ([window, ] string, command, hint)'
			elseif n == 3 then
				str, cmd, hint = ...
			elseif n == 4 and type(args[4]) == 'boolean' then
				str, cmd, hint, fmt = ...
			elseif n >= 4 and type(args[4]) == 'string' then
				win, str, cmd, hint, fmt = ...
				if win == "main" then win = nil end
			else
				error'Improper arguments, usage: ([window, ] string, command, hint)'
			end
		else
			if args[1] and args[2] and args[1] ~= "main" then
				win, str = args[1], args[2]
			elseif args[1] and args[2] and args[1] == "main" then
				str = args[2]
			else
				str = args[1]
			end
		end

		out = function(...)
			_G[func](...)
		end

		if win then
			reset = function()
				resetFormat(win)
			end
		else
			reset = function()
				resetFormat()
			end
		end

		local t = _Echos.Process(str, style)

		deselect()
		reset()

		for _, v in ipairs(t) do
			if type(v) == 'table' then
				if v.fg then
					local fr, fg, fb = unpack(v.fg)
					if win then setFgColor(win, fr, fg, fb) else setFgColor(fr, fg, fb) end
				end
				if v.bg then
					local br, bg, bb = unpack(v.bg)
					if win then setBgColor(win, br, bg, bb) else setBgColor(br, bg, bb) end
				end
			elseif v == "\27reset" then
				reset()
			else
				if func == 'echo' or func == 'insertText' then
					if win then out(win, v) else out(v) end
					if func == 'insertText' then
						moveCursor(window or "main", getColumnNumber() + string.len(v), getLineNumber())
					end
				else
					-- if win and fmt then setUnderline(win, true) elseif fmt then setUnderline(true) end -- not sure if underline is necessary unless asked for
					if win then out(win, v, cmd, hint, (fmt == true and true or false)) else out(v, cmd, hint, (fmt == true and true or false)) end
				end
			end
		end
		reset()
	end



--- Echo string with embedded hex color information. <br/><br/>
---
--- Color changes can be made within the string using the format |cFRFGFB,BRBGBB where FR is the foreground red value,
--- FG is the foreground green value, FB is the foreground blue value, BR is the background red value, etc., BRBGBB is optional.
--- |r can be used within the string to reset the colors to default.
---
--- @usage Print red test on green background.
---   <pre>
---   hecho("|cff0000,00ff00test")
---   </pre>
---
--- @see xEcho
--- @see hinsertText
	function hecho(...) xEcho("Hex", "echo", ...) end



--- Echo string with embedded decimal color information. <br/><br/>
---
--- Color changes can be made using the format &lt;FR,FG,FB:BR,BG,BB&gt; where each field is a number from 0 to 255.
--- The background portion can be omitted using &lt;FR,FG,FB&gt; or the foreground portion can be omitted using &lt;:BR,BG,BB&gt;.
---
--- @usage Print red test on green background.
---   <pre>
---   decho("&lt;255,0,0:0,255,0&gt;test")
---   </pre>
---
--- @see xEcho
--- @see dinsertText
	function decho(...) xEcho("Decimal", "echo", ...) end



--- Echo string with embedded color name information.
---
--- @usage Consider following example:
---   <pre>
---   cecho("&lt;green&gt;green text &lt;blue&gt;blue text &lt;red&gt;red text")
---   </pre>
---
--- @see xEcho
--- @see cinsertText
	function cecho(...) xEcho("Color", "echo", ...) end


--- Inserts string with embedded hex color information.
---
--- @see xEcho
--- @see hecho
	function hinsertText(...) xEcho("Hex", "insertText", ...) end


--- Inserts string with embedded decimal color information.
---
--- @see xEcho
--- @see decho
	function dinsertText(...) xEcho("Decimal", "insertText", ...) end


--- Inserts string with embedded color name information.
---
--- @see xEcho
--- @see cecho
	function cinsertText(...) xEcho("Color", "insertText", ...) end


--- Echos a link with embedded hex color information.
---
--- @usage hechoLink([window, ] string, command, hint)
---
--- @see xEcho
--- @see hecho
	function hechoLink(...) xEcho("Hex", "echoLink", ...) end


--- Echos a link with embedded decimal color information.
---
--- @usage dechoLink([window, ] string, command, hint)
---
--- @see xEcho
--- @see decho
	function dechoLink(...) xEcho("Decimal", "echoLink", ...) end


--- Echos a link with embedded color name information.
---
--- @usage cechoLink([window, ] string, command, hint)
---
--- @see xEcho
--- @see cecho
	function cechoLink(...) xEcho("Color", "echoLink", ...) end


	-- Backwards compatibility
	checho = cecho


else


	-- NOT LUADOC
	-- See xEcho/another cecho for description.
	function cecho(window, text)
       local win = text and window
       local s = text or window
       if win == "main" then win = nil end

       if win then
            resetFormat(win)
       else
            resetFormat()
       end
       for color,text in string.gmatch("<white>"..s, "<([a-z_0-9, :]+)>([^<>]+)") do
          local colist   =   string.split(color..":", "%s*:%s*")
          local fgcol   =   colist[1] ~= "" and colist[1] or "white"
          local bgcol   =   colist[2] ~= "" and colist[2] or "black"
          local FGrgb   =   color_table[fgcol] or string.split(fgcol, ",")
          local BGrgb   =   color_table[bgcol] or string.split(bgcol, ",")

          if win then
             setFgColor(win, FGrgb[1], FGrgb[2], FGrgb[3])
             setBgColor(win, BGrgb[1], BGrgb[2], BGrgb[3])
             echo(win,text)
          else
             setFgColor(FGrgb[1], FGrgb[2], FGrgb[3])
             setBgColor(BGrgb[1], BGrgb[2], BGrgb[3])
             echo(text)
          end
       end

       if win then
          resetFormat(win)
       else
          resetFormat()
       end
    end


	-- NOT LUADOC
	-- See xEcho/another decho for description.
	function decho(window, text)
		local win = text and window
		local s = text or window
		if win == "main" then win = nil end
		local reset
		if win then
			reset = function() resetFormat(win) end
		else
			reset = function() resetFormat() end
		end
		reset()
		for color, text in s:gmatch("<([0-9,:]+)>([^<>]+)") do
			if color == "reset" then
				reset()
				if win then echo(win, text) else echo(text) end
			else
				local colist  =   string.split(color..":", "%s*:%s*")
				local fgcol   =   colist[1] ~= "" and colist[1] or "white"
				local bgcol   =   colist[2] ~= "" and colist[2] or "black"
				local FGrgb   =   color_table[fgcol] or string.split(fgcol, ",")
				local BGrgb   =   color_table[bgcol] or string.split(bgcol, ",")

				if win then
					setFgColor(win, FGrgb[1], FGrgb[2], FGrgb[3])
					setBgColor(win, BGrgb[1], BGrgb[2], BGrgb[3])
					echo(win,text)
				else
					setFgColor(FGrgb[1], FGrgb[2], FGrgb[3])
					setBgColor(BGrgb[1], BGrgb[2], BGrgb[3])
					echo(text)
				end
			end
		end
		reset()
	end


end

-- improve replace to have a third argument, keepcolor
do
	local oldreplace = replace
	function replace(arg1, arg2, arg3)
		local windowname, text, keepcolor

		if arg1 and arg2 and arg3 ~= nil then
			windowname, text, keepcolor = arg1, arg2, arg3
		elseif arg1 and type(arg2) == "string" then
			windowname, text = arg1, arg2
		elseif arg1 and type(arg2) == "boolean" then
			text, keepcolor = arg1, arg2
		else
			text = arg1
		end

		text = text or ""

		if keepcolor then
			if not windowname then
				setBgColor(getBgColor())
				setFgColor(getFgColor())
			else
				setBgColor(windowname, getBgColor(windowname))
				setFgColor(windowname, getFgColor(windowname))
			end
		end

		if windowname then
			oldreplace(windowname, text)
		else
			oldreplace(text)
		end
	end
end


local colours = {
  [0] = {0,0,0}, -- black
  [1] = {128,0,0}, -- red
  [2] = {0,179,0}, -- green
  [3] = {128,128,0}, -- yellow
  [4] = {0,0,128}, --blue
  [5] = {128,0,128}, -- magenta
  [6] = {0,128,128}, -- cyan
  [7] = {192,192,192}, -- white
}

local lightColours = {
  [0] = {128,128,128}, -- black
  [1] = {255,0,0}, -- red
  [2] = {0,255,0}, -- green
  [3] = {255,255,0}, -- yellow
  [4] = {0,0,255}, --blue
  [5] = {255,0,255}, -- magenta
  [6] = {0,255,255}, -- cyan
  [7] = {255,255,255}, -- white
}

-- black + 23 tone grayscale up to white
-- The values are to be used for each of te r, g and b values
local grayscaleComponents = {
  [0]  =   0,
  [1]  =  11,
  [2]  =  22,
  [3]  =  33,
  [4]  =  44,
  [5]  =  55,
  [6]  =  67,
  [7]  =  78,
  [8]  =  89,
  [9]  = 100,
  [10] = 111,
  [11] = 122,
  [12] = 133,
  [13] = 144,
  [14] = 155,
  [15] = 166,
  [16] = 177,
  [17] = 188,
  [18] = 200,
  [19] = 211,
  [20] = 222,
  [21] = 233,
  [22] = 244,
  [23] = 255
}

local ansiPattern = rex.new("\\e\\[([0-9;]+?)m")
-- function for converting raw ANSI string into something decho can process
-- bold, italics, underline not currently supported since decho doesn't support them
function ansi2decho(text)
  -- match each set of ansi tags, ie  and convert to decho equivalent.
  -- this works since both ansi colours and echo don't need closing tags and map to each other
  local result = rex.gsub(text, ansiPattern, function(s)
    local output = {} -- assemble the output into this table

    local t = string.split(s, ";") -- split the codes into an indexed table

    -- given an xterm256 index, returns an rgb string for decho use
    local function convertindex(tag)
      local floor = math.floor
      -- code from Mudlets own decoding in TBuffer::translateToPlainText

      local rgb
      if tag < 8 then
        rgb = colours[tag]
      elseif tag < 16 then
        rgb = lightColours[tag-8]
      elseif tag < 232 then
        tag = tag - 16 -- because color 1-15 behave like normal ANSI colors

        r = floor(tag / 36)
        g = floor((tag-(r*36)) / 6)
        b = floor((tag-(r*36))-(g*6))
        rgb = {r*51, g*51, b*51}
      else
        local component = grayscaleComponents[tag - 232]
        rgb = {component, component, component}
      end

      return rgb
    end

    -- since fg/bg can come in different order and we need them as fg:bg for decho, collect
    -- the data first, then assemble it in the order we need at the end
    local fg,bg
    local i = 1
    local floor = math.floor
    local coloursToUse = colours
    while i <= #t do
      local code = t[i]

      if code == '0' then -- reset attributes
        output[#output+1] = "<r>"
        fg,bg = nil,nil
        coloursToUse = colours
      elseif code == "1" then -- light or bold
        coloursToUse = lightColours
      elseif code == "22" then -- not light or bold
        coloursToUse = colours
      else
        local layerCode = floor(code / 10)  -- extract the "layer": 3 is fore
                                            --                      4 is back
        local cmd = code - (layerCode * 10) -- extract the actual "command"
                                            -- 0-7 is a colour, 8 is xterm256
        local colour = nil
        if cmd == 8 and t[i+1] == '5' then -- xterm256, colour indexed
          colour = convertindex(tonumber(t[i+2]))
          i = i + 2

        elseif cmd == 8 and t[i+1] == '2' then -- xterm256, rgb
          colour = {t[i+2] or '0', t[i+3] or '0', t[i+4] or '0'}
          i = i + 4

        elseif layerCode == 9 or layerCode == 10 then --light colours
            colour = lightColours[cmd]
        elseif layerCode == 4 then -- background colours know no "bright" for
            colour = colours[cmd]  -- mudlet
        else -- usual ANSI colour index
            colour = coloursToUse[cmd]
        end

        if layerCode == 3 or layerCode == 9 then
           fg = colour
        elseif layerCode == 4 or layerCode == 10 then
           bg = colour
        end

      end
      i = i + 1
    end
    -- assemble and return the data
    if fg or bg then
      output[#output+1] = '<'
      if fg then
        output[#output+1] = table.concat(fg, ",")
      end
      output[#output+1] = ':'
      if bg then
        output[#output+1] = table.concat(bg, ",")
      end
      output[#output+1] = '>'
    end

    return table.concat(output)
  end)

  return result
end

--- Form of setFgColor that accepts a hex color string instead of decimal values
--- @param windowName Optional name of the window to use the function on
--- @param colorString hex string for the color to use
function setHexFgColor(windowName, colorString)
  local win = colorString and windowName
  local col = colorString or windowName

  if win == "main" then win = nil end

  if #col ~= 6 then error("setHexFgColor needs a 6 digit hex color code.") end

  local colTable = {
    r = tonumber(col:sub(1,2), 16),
    g = tonumber(col:sub(3,4), 16),
    b = tonumber(col:sub(5,6), 16)
  }

  if win then
    setFgColor(win, colTable.r, colTable.g, colTable.b)
  else
    setFgColor(colTable.r, colTable.g, colTable.b)
  end
end

--- Form of setBgColor that accepts a hex color string instead of decimal values
--- @param windowName Optional name of the window to use the function on
--- @param colorString hex string for the color to use
function setHexBgColor(windowName, colorString)
  local win = colorString and windowName
  local col = colorString or windowName

  if win == "main" then win = nil end

  if #col ~= 6 then error("setHexFgColor needs a 6 digit hex color code.") end

  local colTable = {
    r = tonumber(col:sub(1,2), 16),
    g = tonumber(col:sub(3,4), 16),
    b = tonumber(col:sub(5,6), 16)
  }

  if win then
    setBgColor(win, colTable.r, colTable.g, colTable.b)
  else
    setBgColor(colTable.r, colTable.g, colTable.b)
  end
end