Changing colors to use the same OOP style as everything else and

updating it's documentation.

docs/howto.md → doc/howto.md

@@ -780,14 +780,23 @@ Unlike lightness and saturdation, hue _loops_: the hue of 360 is actually the sa
 Creating a color in HSL space and converting it to RGB
 
     > require("colors")
-    > c = colors.Color:new(130, .8, 0.3) -- green, pretty saturated, somewhat dark
+    > c = colors.new(130, .8, 0.3) -- green, pretty saturated, somewhat dark
     > =tostring(c)
     #0f8923
 
 <table>
  <tr><td width="100"></td><td width="160" style="background: #0f8923">&nbsp;</td></tr>
 </table>
 
+You can also create this color from it's RGB code:
+
+    > require("colors")
+    > c = colors.new("#0f8923") -- green, pretty saturated, somewhat dark
+    > =tostring(c)
+    #0f8923
+
+The color converts to its RGB representation when forced into a string:
+
     > =c -- convert implicitly
     #0f8923
 

lua/colors.lua

@@ -1,19 +1,45 @@
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Provides support for color manipulation in HSL color space.
--- (rgb_to_hsl() implementation was contributed by Markus Fleck-Graffe.)
----------------------------------------------------------------------------------------------------
+--
+-- http://sputnik.freewisdom.org/lib/colors/
+--
+-- License: MIT/X
+-- 
+-- (c) 2008 Yuri Takhteyev ([email protected]) *
+--
+-- * rgb_to_hsl() implementation was contributed by Markus Fleck-Graffe.
+-----------------------------------------------------------------------------
 
 module(..., package.seeall)
 
----------------------------------------------------------------------------------------------------
+local Color = {}
+local Color_mt = {__metatable = {}, __index = Color}
+
+-----------------------------------------------------------------------------
+-- Instantiates a new "color".
+--
+-- @param H              hue (0-360) _or_ an RGB string ("#930219")
+-- @param S              saturation (0.0-1.0)
+-- @param L              lightness (0.0-1.0)
+-- @return               an instance of Color
+-----------------------------------------------------------------------------
+function new(H, S, L)
+   if type(H) == "string" and H:sub(1,1)=="#" and H:len() == 7 then
+      H, S, L = rgb_string_to_hsl(H)
+   end
+   assert(Color_mt)
+   return setmetatable({H = H, S = S, L = L}, Color_mt)
+end
+
+-----------------------------------------------------------------------------
 -- Converts an HSL triplet to RGB
 -- (see http://homepages.cwi.nl/~steven/css/hsl.html).
 -- 
 -- @param h              hue (0-360)
 -- @param s              saturation (0.0-1.0)
 -- @param L              lightness (0.0-1.0)
 -- @return               an R, G, and B component of RGB
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 
 function hsl_to_rgb(h, s, L)
    h = h/360
@@ -42,15 +68,15 @@ function hsl_to_rgb(h, s, L)
    return _h2rgb(m1, m2, h+1/3), _h2rgb(m1, m2, h), _h2rgb(m1, m2, h-1/3)
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Converts an RGB triplet to HSL.
 -- (see http://easyrgb.com)
 -- 
 -- @param r              red (0.0-1.0)
 -- @param g              green (0.0-1.0)
 -- @param b              blue (0.0-1.0)
 -- @return               corresponding H, S and L components
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 
 function rgb_to_hsl(r, g, b)
    --r, g, b = r/255, g/255, b/255
@@ -82,33 +108,12 @@ function rgb_string_to_hsl(rgb)
                      tonumber(rgb:sub(6,7), 16)/256)
 end
 
-Color = {}
-
----------------------------------------------------------------------------------------------------
--- Instantiates a new "color".
---
--- @param H              hue (0-360) _or_ an RGB string ("#930219")
--- @param S              saturation (0.0-1.0)
--- @param L              lightness (0.0-1.0)
--- @return               an instance of Color
----------------------------------------------------------------------------------------------------
-function Color:new(H, S, L)
-   if type(H) == "string" and H:sub(1,1)=="#" and H:len() == 7 then
-      H, S, L = rgb_string_to_hsl(H)
-   end
-   local obj = {H = H, S = S, L = L}
-   setmetatable(obj, self)		
-   self.__index = self
-   self.__tostring = self.to_rgb
-   return obj
-end
-
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Converts the color to an RGB string.
 --
--- @return               a 6-digit RGB representation of the color prefixed with "#" (suitable for 
---                       inclusion in HTML)
----------------------------------------------------------------------------------------------------
+-- @return               a 6-digit RGB representation of the color prefixed
+--                       with "#" (suitable for inclusion in HTML)
+-----------------------------------------------------------------------------
 
 function Color:to_rgb()
    local r, g, b = hsl_to_rgb(self.H, self.S, self.L)
@@ -120,102 +125,105 @@ function Color:to_rgb()
    return buffer
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates a new color with hue different by delta.
 --
 -- @param delta          a delta for hue.
 -- @return               a new instance of Color.
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:hue_offset(delta)
-   return self:new((self.H + delta) % 360, self.S, self.L)
+   return new((self.H + delta) % 360, self.S, self.L)
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates a complementary color.
 --
 -- @return               a new instance of Color
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:complementary() 
    return self:hue_offset(180)
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates two neighboring colors (by hue), offset by "angle".
 --
--- @param angle          the difference in hue between this color and the neighbors
+-- @param angle          the difference in hue between this color and the 
+--                       neighbors
 -- @return               two new instances of Color
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:neighbors(angle)
    local angle = angle or 30
    return self:hue_offset(angle), self:hue_offset(360-angle)
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates two new colors to make a triadic color scheme.
 --
 -- @return               two new instances of Color
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:triadic() 
    return self:neighbors(120)
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates two new colors, offset by angle from this colors complementary.
 --
--- @param angle          the difference in hue between the complementary and the returned colors
+-- @param angle          the difference in hue between the complementary and
+--                       the returned colors
 -- @return               two new instances of Color
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:split_complementary(angle)
    return self:neighbors(180-(angle or 30))
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates a new color with saturation set to a new value.
 --
 -- @param saturation     the new saturation value (0.0 - 1.0)
 -- @return               a new instance of Color
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:desaturate_to(saturation)
-   return self:new(self.H, saturation, self.L)
+   return new(self.H, saturation, self.L)
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates a new color with saturation set to a old saturation times r.
 --
 -- @param r              the multiplier for the new saturation
 -- @return               a new instance of Color
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:desaturate_by(r)
-   return self:new(self.H, self.S*r, self.L)
+   return new(self.H, self.S*r, self.L)
 end	      
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates a new color with lightness set to a new value.
 --
 -- @param lightness      the new lightness value (0.0 - 1.0)
 -- @return               a new instance of Color
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:lighten_to(lightness)
-   return self:new(self.H, self.S, lightness)
+   return new(self.H, self.S, lightness)
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates a new color with lightness set to a old lightness times r.
 --
 -- @param r              the multiplier for the new lightness
 -- @return               a new instance of Color
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:lighten_by(r)
-   return self:new(self.H, self.S, self.L*r)
+   return new(self.H, self.S, self.L*r)
 end
 
----------------------------------------------------------------------------------------------------
--- Creates n variations of this color using supplied function and returns them as a table.
+-----------------------------------------------------------------------------
+-- Creates n variations of this color using supplied function and returns
+-- them as a table.
 --
 -- @param f              the function to create variations
 -- @param n              the number of variations
 -- @return               a table with n values containing the new colors
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:variations(f, n)
    n = n or 5
    local results = {}
@@ -225,25 +233,25 @@ function Color:variations(f, n)
    return results
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates n tints of this color and returns them as a table
 --
 -- @param n              the number of tints
 -- @return               a table with n values containing the new colors
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:tints(n)
    local f = function (color, i, n) 
                 return color:lighten_to(color.L + (1-color.L)/n*i)
              end
    return self:variations(f, n)
 end
 
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 -- Creates n shades of this color and returns them as a table
 --
 -- @param n              the number of shades
 -- @return               a table with n values containing the new colors
----------------------------------------------------------------------------------------------------
+-----------------------------------------------------------------------------
 function Color:shades(n)
    local f = function (color, i, n) 
                 return color:lighten_to(color.L - (color.L)/n*i)
@@ -259,5 +267,4 @@ function Color:shade(r)
       return self:lighten_to(self.L - self.L*r)
 end
 
-
-
+Color_mt.__tostring = Color.to_rgb

petrodoc

@@ -1,44 +1,49 @@
 package    = 'Colors'
 versions   = {
+   {'8.05.26', 'May 26, 2008', 'added ability to create colors from RGB codes'},
    {'8.03.08', 'March 8, 2008', 'updated petrodoc, no functional changes'},
    {'8.02.23', 'Feb. 23, 2008', 'added Luadoc comments'},
    {'8.02.03', 'Feb. 2, 2008',  'cleaned up for a stand-alone release'}
 }
 summary    = 'HSL Color Theory Computation in Lua'
-author     = 'Yuri Takhteyev'
-maintainer = author
-email      = '[email protected]'
+maintainer = 'Yuri Takhteyev <[email protected]>'
 
 detailed   = [[ Colors library provides methods to do color computation in
                 HSL color space and for finding "harmonious" color palettes. ]]
 license    = 'MIT/X11'
 
-homepage   = 'http://sputnik.freewisdom.org/colors/'
+homepage   = 'http://sputnik.freewisdom.org/lib/colors/'
 favicon    = 'http://media.freewisdom.org/etc/sputnik-icon.png'
 download   = 'http://sputnik.freewisdom.org/files/colors-$version.tar.gz'
 
-logo       = 'http://sputnik.freewisdom.org/colors/colors.png'
+push       = "scp %s [email protected]:~/webapps/static/files/"
+
+logo       = 'http://sputnik.freewisdom.org/lib/colors/colors.png'
 keywords   = 'Lua, HSL'
 rss        = homepage.."releases.rss"
 --------------------------------------------------------------------------------
 
 dependencies = ""
-build = nil
 
 Installation = [[
   Colors consists of a single file (colors.lua) of slightly more 
-  than 100 lines, plus a test script (test.lua).  Here is a list of recent
-  releases:
+  than 100 lines, plus a test script (test.lua).  
+  Just put colors.lua somewhere in your Lua path.  
+
+  Here is a list of recent releases:
 
   <ul>
   $do_versions[=[<li><a href="$url">$package-$version</a> - $comment ($date) </li> ]=]
   </ul>
 
-  Colors installs like any other single-file Lua module: just put it somewhere in
-  your Lua path.  
+  You can also install it using LuaRocks with
+
+    luarocks install colors
+
+  or:
+
+    luarocks --from=http://sputnik.freewisdom.org/rocks/earth install colors
 
-  You can also install Colors as a LuaRock from the repository at 
-  http://sputnik.freewisdom.org/rocks/.
 ]] ----------------------------------------------------------------------------
 
 Contact = [[
@@ -52,9 +57,9 @@ Contact = [[
 TOC = {
    { "Overview",     "<p>"..detailed.."</p>" },
    { "Installation", markdown(Installation) },
-   { "Using Colors", markdown(include("docs/howto.md")) },
+   { "Using Colors", markdown(include("doc/howto.md")) },
    { "Contact",      markdown(Contact)},
-   { "LuaDoc",       luadoc{"colors.lua"} },
+   { "LuaDoc",       make_luadoc{"colors.lua"} },
    { "License",      markdown(include("LICENSE.txt")) }
 }
 -------------------------------------------------------------------------------