Merge pull request #1227 from morethanoneanimal/gears-color-refactoring

gears.color refactoring

lib/awful/prompt.lua

@@ -287,6 +287,7 @@ end
 -- @param[opt] keypressed_callback The callback function to call
 --   with mod table, key and command as arguments when a key was pressed.
 --   [**DEPRECATED**]
+-- @see gears.color
 function prompt.run(args, textbox, exe_callback, completion_callback,
                     history_path, history_max, done_callback,
                     changed_callback, keypressed_callback)

lib/gears/color.lua

@@ -20,53 +20,77 @@ local surface = require("gears.surface")
 local color = { mt = {} }
 local pattern_cache
 
+--- Create a pattern from a given string.
+-- This function can create solid, linear, radial and png patterns. In general,
+-- patterns are specified as strings formatted as "type:arguments". "arguments"
+-- is specific to the pattern being used. For example, one can use
+-- "radial:50,50,10:55,55,30:0,#ff0000:0.5,#00ff00:1,#0000ff".
+-- Alternatively, patterns can be specified via tables. In this case, the
+-- table's 'type' member specifies the type. For example:
+-- {
+--   type = "radial",
+--   from = { 50, 50, 10 },
+--   to = { 55, 55, 30 },
+--   stops = { { 0, "#ff0000" }, { 0.5, "#00ff00" }, { 1, "#0000ff" } }
+-- }
+-- Any argument that cannot be understood is passed to @{create_solid_pattern}.
+--
+-- Please note that you MUST NOT modify the returned pattern, for example by
+-- calling :set_matrix() on it, because this function uses a cache and your
+-- changes could thus have unintended side effects. Use @{create_pattern_uncached}
+-- if you need to modify the returned pattern.
+-- @see create_pattern_uncached, create_solid_pattern, create_png_pattern,
+--   create_linear_pattern, create_radial_pattern
+-- @tparam string col The string describing the pattern.
+-- @return a cairo pattern object
+-- @function gears.color
+
 --- Parse a HTML-color.
 -- This function can parse colors like `#rrggbb` and `#rrggbbaa` and also `red`.
--- Thanks to #lua for this. :)
+-- Max 4 chars per channel.
 --
 -- @param col The color to parse
--- @return 4 values which each are in the range [0, 1].
+-- @treturn table 4 values representing color in RGBA format (each of them in
+-- [0, 1] range) or nil if input is incorrect.
 -- @usage -- This will return 0, 1, 0, 1
 -- gears.color.parse_color("#00ff00ff")
 function color.parse_color(col)
     local rgb = {}
-    -- Is it a HTML-style color?
     if string.match(col, "^#%x+$") then
-        -- Get all hex chars
+        local hex_str = col:sub(2, #col)
-        for char in string.gmatch(col, "[^#]") do
+        local channels
-            table.insert(rgb, tonumber(char, 16) / 0xf)
+        if #hex_str % 3 == 0 then
+            channels = 3
+        elseif #hex_str % 4 == 0 then
+            channels = 4
+        else
+            return nil
         end
-        -- Merge consecutive values until we have at most four groups (rgba)
+        local chars_per_channel = #hex_str / channels
-        local factor = 0xf
+        if chars_per_channel > 4 then
-        while #rgb > 4 do
+            return nil
-            local merged = {}
+        end
-            local key, value = next(rgb, nil)
+        local dividor = (0x10 ^ chars_per_channel) - 1
-            local next_factor = (factor + 1)*(factor + 1) - 1
+        for idx=1,#hex_str,chars_per_channel do
-            while key do
+            local channel_val = tonumber(hex_str:sub(idx,idx+chars_per_channel-1), 16)
-                local key2, value2 = next(rgb, key)
+            table.insert(rgb, channel_val / dividor)
-                local v1, v2 = value * factor, value2 * factor
+        end
-                local new = v1 * (factor + 1) + v2
+        if channels == 3 then
-                table.insert(merged, new / next_factor)
+            table.insert(rgb, 1)
-                key, value = next(rgb, key2)
-            end
-            rgb = merged
-            factor = next_factor
         end
     else
-        -- Let's ask Pango for its opinion (but this doesn't support alpha!)
         local c = Pango.Color()
-        if c:parse(col) then
+        if not c:parse(col) then
-            rgb = {
+            return nil
-                c.red / 0xffff,
-                c.green / 0xffff,
-                c.blue / 0xffff,
-            }
         end
+        rgb = {
+            c.red / 0xffff,
+            c.green / 0xffff,
+            c.blue / 0xffff,
+            1.0
+        }
     end
-    -- Add missing groups (missing alpha)
+    assert(#rgb == 4, col)
-    while #rgb < 4 do
-        table.insert(rgb, 1)
-    end
     return unpack(rgb)
 end
 
@@ -234,27 +258,9 @@ function color.create_pattern_uncached(col)
     return color.create_solid_pattern(col)
 end
 
---- Create a pattern from a given string.
+--- Create a pattern from a given string, same as `gears.color`.
--- This function can create solid, linear, radial and png patterns. In general,
+-- @see gears.color
--- patterns are specified as strings formatted as"type:arguments". "arguments"
--- is specific to the pattern used. For example, one can use
--- "radial:50,50,10:55,55,30:0,#ff0000:0.5,#00ff00:1,#0000ff"
--- Alternatively, patterns can be specified via tables. In this case, the
--- table's 'type' member specifies the type. For example:
--- { type = "radial", from = { 50, 50, 10 }, to = { 55, 55, 30 },
---   stops = { { 0, "#ff0000" }, { 0.5, "#00ff00" }, { 1, "#0000ff" } } }
--- Any argument that cannot be understood is passed to @{create_solid_pattern}.
---
--- Please note that you MUST NOT modify the returned pattern, for example by
--- calling :set_matrix() on it, because this function uses a cache and your
--- changes could thus have unintended side effects. Use @{create_pattern_uncached}
--- if you need to modify the returned pattern.
--- @see create_pattern_uncached, create_solid_pattern, create_png_pattern,
---   create_linear_pattern, create_radial_pattern
--- @param col The string describing the pattern.
--- @return a cairo pattern object
 function color.create_pattern(col)
-    -- If it already is a cairo pattern, just leave it as that
     if cairo.Pattern:is_type_of(col) then
         return col
     end

lib/gears/wallpaper.lua

@@ -88,6 +88,7 @@ end
 --- Set the current wallpaper.
 -- @param pattern The wallpaper that should be set. This can be a cairo surface,
 --   a description for gears.color or a cairo pattern.
+-- @see gears.color
 function wallpaper.set(pattern)
     if cairo.Surface:is_type_of(pattern) then
         pattern = cairo.Pattern.create_for_surface(pattern)
@@ -107,6 +108,7 @@ end
 --   all screens are set.
 -- @param background The background color that should be used. Gets handled via
 --   gears.color. The default is black.
+-- @see gears.color
 function wallpaper.centered(surf, s, background)
     local geom, cr = wallpaper.prepare_context(s)
     surf = surface.load_uncached(surf)
@@ -188,6 +190,7 @@ end
 --   all screens are set.
 -- @param background The background color that should be used. Gets handled via
 --   gears.color. The default is black.
+-- @see gears.color
 function wallpaper.fit(surf, s, background)
     local geom, cr = wallpaper.prepare_context(s)
     surf = surface.load_uncached(surf)

lib/wibox/drawable.lua

@@ -216,6 +216,7 @@ end
 --- Set the background of the drawable
 -- @param c The background to use. This must either be a cairo pattern object,
 --   nil or a string that gears.color() understands.
+-- @see gears.color
 function drawable:set_bg(c)
     c = c or "#000000"
     local t = type(c)
@@ -263,6 +264,7 @@ end
 --- Set the foreground of the drawable
 -- @param c The foreground to use. This must either be a cairo pattern object,
 --   nil or a string that gears.color() understands.
+-- @see gears.color
 function drawable:set_fg(c)
     c = c or "#FFFFFF"
     if type(c) == "string" or type(c) == "table" then

lib/wibox/widget/graph.lua

@@ -31,18 +31,20 @@ local graph = { mt = {} }
 -- If the value is nil, no border will be drawn.
 --
 -- @property border_color
--- @tparam geats.color border_color The border color to set.
+-- @tparam gears.color border_color The border color to set.
+-- @see gears.color
 
 --- Set the graph foreground color.
 --
 -- @property color
 -- @tparam color color The graph color.
--- @see gears.color.create_pattern
+-- @see gears.color
 
 --- Set the graph background color.
 --
 -- @property background_color
 -- @tparam gears.color background_color The graph background color.
+-- @see gears.color
 
 --- Set the maximum value the graph should handle.
 -- If "scale" is also set, the graph never scales up below this value, but it

lib/wibox/widget/progressbar.lua

@@ -36,6 +36,7 @@ local progressbar = { mt = {} }
 --
 -- @property border_color
 -- @tparam gears.color color The border color to set.
+-- @see gears.color
 
 --- The progressbar border width.
 -- @property border_width
@@ -45,6 +46,7 @@ local progressbar = { mt = {} }
 --
 -- @property bar_border_color
 -- @tparam gears.color color The border color to set.
+-- @see gears.color
 
 --- The progressbar inner border width.
 -- @property bar_border_width
@@ -53,11 +55,13 @@ local progressbar = { mt = {} }
 --
 -- @property color
 -- @tparam gears.color color The progressbar color.
+-- @see gears.color
 
 --- The progressbar background color.
 --
 -- @property background_color
 -- @tparam gears.color color The progressbar background color.
+-- @see gears.color
 
 --- The progressbar inner shape.
 --

spec/gears/color_spec.lua

@@ -42,6 +42,26 @@ describe("gears.color", function()
             test(0x7f, 0xff, 0x00, 0xff, "chartreuse")
         end)
 
+        describe("invalid input", function()
+            local function test_nil(input)
+                local output = color.parse_color(input)
+                assert.is_nil(output)
+            end
+
+            it("nonexisting color", function()
+                test_nil("elephant")
+            end)
+
+            it("invalid format", function()
+                test_nil('#f0f0f')
+            end)
+
+            it("too long", function()
+                test_nil("#00000fffff00000fffff")
+            end)
+        end)
+
+
         describe("different lengths", function()
             local function gray(e, e_a, input)
                 local o_r, o_g, o_b, o_a, unused = color.parse_color(input)