Doc: update 'utils' documentation; Utils: reafactored;

Author: kazupon

doc/api/utils.markdown

@@ -1,15 +1,86 @@
-# utils
+# Utils
 
-These functions are in the module `'util'`. Use `require('util')` to access
+These functions and properties are in the module `'utils'`. Use `require('utils')` to access
 them.
 
-## functions
+---
+
+## Properties
+Use the color in the output. This Property used `dump`, `prettyPrint` and `debug` functions.
+
+### useColors
+* value : boolean
+* default : true
+
+    local utils = require('utils')
+    utils.useColors = false
+    ...
+    utils.prettyPrint('hello world')
+
+If you would not like to color output, set `false` to this property.
+
+---
+
+## Functions
 
 ### bind(fn, self, [...])
+Creates a new function that, when called, has its `self` keyword set to the provided value, with a given sequence of arguments preceding any provided when the new function was called.
+
+#### parameters
+* fn : a target function (required)
+* self : a target object (required)
+* ... : arguments of `fn` function (optional)
+
+#### returns
+Return a bound function.
+
+    local say = function (self, x, y, z)
+      print(self.message, x, y, z)
+      return self.message, x, y, z
+    end
+
+    local fn = utils.bind(say, { message = 'hello' })
+    print(fn(1, 2, 3)) -- 'hello', 1, 2, 3
+
 
 ### debug([...])
+A synchronous dump output function. Will block the process and output arguments immediately to `stderr`.
+
+#### parameters
+* ... : some arguments (optional)
+
+#### returns
+Return the `nil`.
+
+    utils.debug('hello world', 12, true)
+
+If `useColors` is `false`, this function does not output the color codes.
+
+
+### dump(v, [depth])
+Return a string representation of value, which is useful for debugging.
+
+#### parameters
+* o : a target value (required)
+* depth : an indent level (optional, default: 0)
+
+#### returns
+Return a string of value. If `useColors` is `false`, Return a string does not include the color codes.
+
+    print(utils.dump(true))
+    print(utils.dump({ hoge = 'hoge', foo = 1, bar = { a = 1, b = 2 } }, 2)
 
-### dump(o, [depth])
 
 ### prettyPrint([...])
+A synchronous dump output function. Will block the process and output arguments immediately to `stdout`.
+
+#### parameters
+* ... : some arguments (optional)
+
+#### returns
+Return the `nil`.
+
+    utils.prettyPrint('hello world', 12, true)
+
+If `useColors` is `false`, this function does not output the color codes.
 

lib/lev/utils.lua

@@ -41,71 +41,56 @@ local colors = {
   Bwhite   = "1;37"
 }
 
-if utils._useColors == nil then
-  utils._useColors = true
+if utils.useColors == nil then
+  utils.useColors = true
 end
 
-function utils.color(color_name)
-  if utils._useColors then
-    return "\27[" .. (colors[color_name] or "0") .. "m"
-  else
-    return ""
-  end
-end
-
-function utils.colorize(color_name, string, reset_name)
-  return utils.color(color_name) .. tostring(string) .. utils.color(reset_name)
+function color(color_name)
+  return utils.useColors and ("\27[" .. (colors[color_name] or "0") .. "m") or ""
 end
 
-local backslash, null, newline, carriage, tab, quote, quote2, obracket, cbracket
-
-function utils.loadColors (n)
-  if n ~= nil then utils._useColors = n end
-  backslash = utils.colorize("Bgreen", "\\\\", "green")
-  null      = utils.colorize("Bgreen", "\\0", "green")
-  newline   = utils.colorize("Bgreen", "\\n", "green")
-  carriage  = utils.colorize("Bgreen", "\\r", "green")
-  tab       = utils.colorize("Bgreen", "\\t", "green")
-  quote     = utils.colorize("Bgreen", '"', "green")
-  quote2    = utils.colorize("Bgreen", '"')
-  obracket  = utils.colorize("B", '[')
-  cbracket  = utils.colorize("B", ']')
+function colorize(color_name, string, reset_name)
+  return color(color_name) .. tostring(string) .. color(reset_name)
 end
 
-utils.loadColors ()
-
 function utils.dump(o, depth)
   local t = type(o)
   if t == 'string' then
-    return quote .. o:gsub("\\", backslash):gsub("%z", null):gsub("\n", newline):gsub("\r", carriage):gsub("\t", tab) .. quote2
+    return colorize("Bgreen", '"', "green") 
+      .. o:gsub("\\", colorize("Bgreen", "\\\\", "green"))
+      :gsub("%z", colorize("Bgreen", "\\0", "green"))
+      :gsub("\n", colorize("Bgreen", "\\n", "green"))
+      :gsub("\r", colorize("Bgreen", "\\r", "green"))
+      :gsub("\t", colorize("Bgreen", "\\t", "green")) 
+      .. colorize("Bgreen", '"')
   end
   if t == 'nil' then
-    return utils.colorize("Bblack", "nil")
+    return colorize("Bblack", "nil")
   end
   if t == 'boolean' then
-    return utils.colorize("yellow", tostring(o))
+    return colorize("yellow", tostring(o))
   end
   if t == 'number' then
-    return utils.colorize("blue", tostring(o))
+    return colorize("blue", tostring(o))
   end
   if t == 'userdata' then
-    return utils.colorize("magenta", tostring(o))
+    return colorize("magenta", tostring(o))
   end
   if t == 'thread' then
-    return utils.colorize("Bred", tostring(o))
+    return colorize("Bred", tostring(o))
   end
   if t == 'function' then
-    return utils.colorize("cyan", tostring(o))
+    return colorize("cyan", tostring(o))
   end
   if t == 'cdata' then
-    return utils.colorize("Bmagenta", tostring(o))
+    return colorize("Bmagenta", tostring(o))
   end
   if t == 'table' then
     if type(depth) == 'nil' then
       depth = 0
     end
     if depth > 1 then
-      return utils.colorize("yellow", tostring(o))
+      return colorize("yellow", tostring(o))
     end
     local indent = ("  "):rep(depth)
 
@@ -213,25 +198,3 @@ end
 
 return utils
 
---print("nil", dump(nil))
-
---print("number", dump(42))
-
---print("boolean", dump(true), dump(false))
-
---print("string", dump("\"Hello\""), dump("world\nwith\r\nnewlines\r\t\n"))
-
---print("funct", dump(print))
-
---print("table", dump({
---  ["nil"] = nil,
---  ["8"] = 8,
---  ["number"] = 42,
---  ["boolean"] = true,
---  ["table"] = {age = 29, name="Tim"},
---  ["string"] = "Another String",
---  ["function"] = dump,
---  ["thread"] = coroutine.create(dump),
---  [print] = {{"deep"},{{"nesting"}},3,4,5},
---  [{1,2,3}] = {4,5,6}
---}))

tests/test-utils.lua

@@ -0,0 +1,118 @@
+--[[
+
+Copyright 2012 The lev Authors. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS-IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+--]]
+
+local utils = require('utils')
+
+local exports = {}
+
+exports['lev.utils:\tdump: default'] = function (test)
+  local dump = utils.dump
+  test.ok(utils.useColors)
+
+  test.equal("\27[1;30mnil\27[0m", dump(nil)) -- nil
+  test.equal('\27[1;32m"\27[0;32mh\27[1;32m\\\\\27[0;32me\27[1;32m\\n\27[0;32ml\27[1;32m\\r\27[0;32ml\27[1;32m\\t\27[0;32mowor\27[1;32m\\0\27[0;32mld\27[1;32m"\27[0m', dump('h\\e\nl\rl\towor\0ld')) -- string
+  test.equal("\27[0;33mtrue\27[0m", dump(true)) -- boolean
+  test.equal("\27[0;34m42\27[0m", dump(42)) -- number
+  test.equal("\27[0;36m" .. tostring(print) .. "\27[0m", dump(print)) -- function
+
+  local thread = _coroutine.create(function () end)
+  test.equal("\27[1;31m" .. tostring(thread) .. "\27[0m", dump(thread)) -- thread
+
+  -- table
+  test.equal("{  }", dump({}))  -- empty
+  local inner_table = {}
+  local ot = "{ a = \27[0;34m1\27[0m, b = { a = \27[0;34m2\27[0m, c = \27[0;33m" .. tostring(inner_table) .. "\27[0m } }"
+  test.equal(ot, dump({ a = 1, b = { a = 2, c = inner_table } }))
+  
+  -- TODO: dump userdata & cdata tests
+  -- TODO: dump depth test
+
+  test.done()
+end
+
+exports['lev.utils:\tdump: not use color'] = function (test)
+  local dump = utils.dump
+  utils.useColors = false
+
+  test.equal("nil", dump(nil)) -- nil
+  test.equal('"h\\\\e\\nl\\rl\\towor\\0ld"', dump('h\\e\nl\rl\towor\0ld')) -- string
+  test.equal("true", dump(true)) -- boolean
+  test.equal("42", dump(42)) -- number
+  test.equal(tostring(print), dump(print)) -- function
+
+  local thread = _coroutine.create(function () end)
+  test.equal(tostring(thread), dump(thread)) -- thread
+
+  -- table
+  test.equal("{  }", dump({}))  -- empty
+  local inner_table = {}
+  local ot = "{ a = 1, b = { a = 2, c = " .. tostring(inner_table) .. " } }"
+  test.equal(ot, dump({ a = 1, b = { a = 2, c = inner_table } }))
+  
+  -- TODO: dump userdata & cdata tests
+  -- TODO: dump depth test
+
+  test.done()
+end
+
+exports['lev.utils:\tprint'] = function (test)
+  test.not_throws(utils.print, 1)
+  test.not_throws(utils.print, 1, 2)
+  test.not_throws(utils.print, 1, 2, 'hello')
+
+  test.done()
+end
+
+exports['lev.utils:\tprettyPrint'] = function (test)
+  local thread = _coroutine.create(function () end)
+  local io = require('io')
+  test.not_throws(utils.prettyPrint, 1)
+  test.not_throws(utils.prettyPrint, 1, true)
+  test.not_throws(utils.prettyPrint, 1, true, 'hello', print, thread, {}, io)
+
+  test.done()
+end
+
+exports['lev.utils:\tdebug'] = function (test)
+  local thread = _coroutine.create(function () end)
+  local io = require('io')
+  test.not_throws(utils.debug, 1)
+  test.not_throws(utils.debug, 1, true)
+  test.not_throws(utils.debug, 1, true, 'hello', print, thread, {}, io)
+
+  test.done()
+end
+
+exports['lev.utils:\tbind'] = function (test)
+  local say = function (self, x, y, z)
+    print(self.message, x, y, z)
+    return self.message, x, y, z
+  end
+
+  local fn = utils.bind(say, { message = 'hello' });
+  test.ok(type(fn) == 'function')
+  local msg, x, y, z = fn(1, 2, 3)
+  test.equal('hello', msg)
+  test.equal(1, x)
+  test.equal(2, y)
+  test.equal(3, z)
+
+  test.done()
+end
+
+return exports