Doc, and cleanup of core functions.

3 files changed, 72 insertions, 69 deletions

diff --git a/README.md b/README.md
index fce822b..0c5a901 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # Lua *system* package
 
+Note: some functions only work on UNIX systems.
+
 ## Dependencies
 Torch7 (www.torch.ch)
 
@@ -9,40 +11,68 @@ $ torch-rocks install sys
 ```
 
 ## Use
-```
+
+```lua
 $ torch
 > require 'sys'
-> for k in pairs(sys) print(k) end  -- gives you all the included functions
-dirname
-dirp
-usleep
-ls
-prefix
-uname
-pwd
-fstat
-COLORS
-lla
-tic
-toc
-OS
-la
-execute
-ll
-concat
-basename
-clock
-filep
+```
+
+### Time / Clock
+
+```lua
+> t = sys.clock()  -- high precision clock (us precision)
+> sys.tic()
+> -- do something
+> t = sys.toc()    -- high precision tic/toc
+> sys.sleep(1.5)   -- sleep 1.5 seconds
+```
+
+### Paths
+
+```lua
+> path,fname = sys.fpath()
+```
+
+Always returns the path of the file in which this call is made. Useful
+to access local resources (non-lua files).
+
+### Execute
+
+By default, Lua's `os.execute` doesn't pipe its results (stdout). This
+function uses popen to pipe its results into a Lua string:
+
+```lua
+> res = sys.execute('ls -l')
+> print(res)
+```
+
+Derived from this, a few commands:
+
+```lua
+> print(sys.uname())
+linux
+```
+
+UNIX-only: shortcuts to run bash commands:
+
+```lua
+> ls()
+> ll()
+> lla()
 ```
 
 ### sys.COLORS
+
 If you'd like print in colours, follow the following snippets of code. Let start by listing the available colours
-```
+
+```lua
 $ torch
 > for k in pairs(sys.COLORS) do print(k) end
 ```
+
 Then, we can generate a shortcut `c = sys.COLORS` and use it within a `print`
-```
+
+```lua
 > c = sys.COLORS
 > print(c.magenta .. 'This ' .. c.red .. 'is ' .. c.yellow .. 'a ' .. c.green .. 'rainbow' .. c.cyan .. '!')
 ```
diff --git a/init.lua b/init.lua
index 07076ed..31e04ec 100644
--- a/init.lua
+++ b/init.lua
@@ -1,35 +1,5 @@
 ----------------------------------------------------------------------
---
--- Copyright (c) 2011 Clement Farabet
---
--- Permission is hereby granted, free of charge, to any person obtaining
--- a copy of this software and associated documentation files (the
--- "Software"), to deal in the Software without restriction, including
--- without limitation the rights to use, copy, modify, merge, publish,
--- distribute, sublicense, and/or sell copies of the Software, and to
--- permit persons to whom the Software is furnished to do so, subject to
--- the following conditions:
---
--- The above copyright notice and this permission notice shall be
--- included in all copies or substantial portions of the Software.
---
--- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
--- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
--- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
--- NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
--- LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
--- OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
--- WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
---
-----------------------------------------------------------------------
--- description:
---     sys - a package that provides simple system (unix) tools
---
--- ack:
---     the C lib was largely taken from Torch5 (code from Ronan)
---
--- history:
---     March 27, 2011, 9:58PM - creation - Clement Farabet
+-- sys - a package that provides simple system (unix) tools
 ----------------------------------------------------------------------
 
 require 'os'
@@ -47,12 +17,12 @@ local ipairs = ipairs
 local paths = paths
 
 module 'sys'
-_lib = require 'libsys'
-_G.libsys = nil
 
 --------------------------------------------------------------------------------
 -- load all functions from lib
 --------------------------------------------------------------------------------
+_lib = require 'libsys'
+_G.libsys = nil
 for k,v in pairs(_lib) do
    _G.sys[k] = v
 end
@@ -71,9 +41,22 @@ toc = function(verbose)
 
 --------------------------------------------------------------------------------
 -- execute an OS command, but retrieves the result in a string
+--------------------------------------------------------------------------------
+execute = function(cmd)
+             local cmd = cmd .. ' 2>&1'
+             local f = io.popen(cmd, 'r')
+             local s = f:read('*all')
+             f:close()
+             s = s:gsub('^%s*',''):gsub('%s*$','')
+             return s
+          end
+
+--------------------------------------------------------------------------------
+-- execute an OS command, but retrieves the result in a string
 -- side effect: file in /tmp
+-- this call is typically more robust than the one above (on some systems)
 --------------------------------------------------------------------------------
-execute = function(cmd, readwhat)
+fexecute = function(cmd, readwhat)
              local tmpfile = os.tmpname()
              local cmd = cmd .. ' 1>'.. tmpfile..' 2>' .. tmpfile
              os.execute(cmd)
@@ -85,16 +68,6 @@ execute = function(cmd, readwhat)
              return s
           end
 
--- TODO: use the following code, which would avoid the side effect.
--- Issue: popen seems broken on OSX
--- execute = function(cmd)
---              local f = io.popen(cmd, 'r')
---              local s = f:read('*all')
---              f:close()
---              s = s:gsub('^%s*',''):gsub('%s*$','')
---              return s
---           end
-
 --------------------------------------------------------------------------------
 -- returns the name of the OS in use
 -- warning, this method is extremely dumb, and should be replaced by something
diff --git a/sys.c b/sys.c
index 4930d1b..a25a5b2 100644
--- a/sys.c
+++ b/sys.c
@@ -31,7 +31,7 @@ static int l_clock(lua_State *L) {
   struct tm *tm;
   gettimeofday(&tv, &tz);
   tm=localtime(&tv.tv_sec);
-  double precise_time = tm->tm_hour*3600 + tm->tm_min*60 + tm->tm_sec + tv.tv_usec / 1000000.0;
+  double precise_time = tv.tv_sec + tv.tv_usec / 1e6;
   lua_pushnumber(L,precise_time);
   return 1;
 }