Support to Lua 5.0 -- Fidelis Assis

[rrdtool.git] / doc / rrdlua.pod

diff --git a/doc/rrdlua.pod b/doc/rrdlua.pod
index a6240f2..7d234fe 100644 (file)
--- a/doc/rrdlua.pod
+++ b/doc/rrdlua.pod
@@ -27,43 +27,104 @@ This module accesses RRDtool functionality directly from within Lua.
 The arguments to the functions listed in the SYNOPSIS are explained in
 the regular RRDtool documentation. The command-line call
 
 The arguments to the functions listed in the SYNOPSIS are explained in
 the regular RRDtool documentation. The command-line call
 

-  rrdtool update mydemo.rrd --template in:out N:12:13
+    rrdtool update mydemo.rrd --template in:out N:12:13

 
 gets turned into
 
 
 gets turned into
 

-  rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13")
-
-Note that
-
-  --template=in:out is also valid.
+    rrd.update ("mydemo.rrd", "--template", "in:out", "N:12:13")
+
+Note that --template=in:out is also valid.
+
+=head2 Using with Lua 5.1
+
+Start your programs with:
+
+    ---------------------------------------------------------------
+    package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.1/?.so;' ..
+                    package.cpath
+    require 'rrd'
+    ---------------------------------------------------------------
+   
+OBS: If you configured with --enable-lua-site-install, you don't need
+to set package.cpath like above.
+
+=head2 Using with Lua 5.0
+
+The Lua binding for RRDtool needs the Lua module compat-5.1 to work with
+Lua 5.0. Some Linux distros, like Ubuntu gutsy and hardy, have it already
+integrated in Lua 5.0 -dev packages, so you just have to require it:
+
+    require 'compat-5.1'
+
+For other platforms, the compat-5.1 module that comes with this binding
+will be installed for you in the same dir where RRDtool was installed,
+under the subdir .../lib/lua/5.0. In this case, you must tell your Lua
+programs where to find it by changing the Lua var LUA_PATH:
+
+    -- compat-5.1.lua is only necessary for Lua 5.0 ----------------
+    -- try only compat-5.1 installed with RRDtool package
+    local original_LUA_PATH = LUA_PATH
+    LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
+    require 'compat-5.1'
+    LUA_PATH = original_LUA_PATH
+    original_LUA_PATH = nil
+    --- end of code to require compat-5.1 ---------------------------
+    
+    Now we can require the rrd module in the same way we did for 5.1 above:
+    
+    ---------------------------------------------------------------
+    package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
+                    package.cpath
+    require 'rrd'
+    ---------------------------------------------------------------

 
 =head2 Error Handling
 
 The Lua RRDTool module functions will abort your program with a stack
 traceback when they can not make sense out of the arguments you fed them.
 
 =head2 Error Handling
 
 The Lua RRDTool module functions will abort your program with a stack
 traceback when they can not make sense out of the arguments you fed them.

-
-  Ex:
-
-  -- If the Lua RRDTool module was installed together with RRDTool,
-  -- in $prefix/lib/lua/$lua_version, package.cpath must be set like
-  -- in the example below, so that 'require' can find the module:
-
-  package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' ..
-                  package.cpath
-  local rrd = require 'rrd'
-  rrd.update ("mydemo.rrd","N:12:13")
-
-  $ lua t.lua
-
-  lua: t.lua:8: opening 'mydemo.rrd': No such file or directory
-  stack traceback:
-          [C]: in function 'update'
-          t.lua:8: in main chunk
-          [C]: ?
-
-You may capture and handle the errors yourself, instead of just letting
-the program abort, by calling the module functions through Lua protected
-calls - 'pcall' or 'xpcall'.
+However, you can capture and handle the errors yourself, instead of just
+letting the program abort, by calling the module functions through Lua
+protected calls - 'pcall' or 'xpcall'.
+
+     Ex: program t.lua
+      
+     --- compat-5.1.lua is only necessary for Lua 5.0 ----------------
+     -- uncomment below if your distro has not compat-5.1
+     -- original_LUA_PATH = LUA_PATH
+     -- try only compat-5.1.lua installed with RRDtool package
+     -- LUA_PATH = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.lua'
+      
+     -- here we use a protected call to require compat-5.1
+     local r = pcall(require, 'compat-5.1')
+     if not r then
+       print('** could not load compat-5.1.lua')
+       os.exit(1)
+     end
+     
+     -- uncomment below if your distro has not compat-5.1
+     -- LUA_PATH = original_LUA_PATH
+     -- original_LUA_PATH = nil
+     --- end of code to require compat-5.1 ---------------------------
+     
+     -- If the Lua RRDTool module was installed together with RRDTool,
+     -- in /usr/local/rrdtool-1.3.2/lib/lua/5.0, package.cpath must be
+     -- set accordingly so that 'require' can find the module:
+    
+     package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
+                     package.cpath
+      
+     local rrd = require 'rrd'
+     rrd.update ("mydemo.rrd","N:12:13")
+     
+If we execute the program above we'll get:
+
+     $ lua t.lua
+      
+     lua: t.lua:27: opening 'mydemo.rrd': No such file or directory
+     stack traceback:
+           [C]: in function `update'
+           t.lua:27: in main chunk
+           [C]: ?

 
 =head2 Return Values
 
 
 =head2 Return Values
 


@@ -74,26 +135,26 @@ B<rrd.first> returns a single INTEGER representing the timestamp of the
 first data sample in an RRA within an RRD file. Example returning the
 first timestamp of the third RRA (index 2):
 
 first data sample in an RRA within an RRD file. Example returning the
 first timestamp of the third RRA (index 2):
 

-  local firstdate = rrd.first('example.rrd', '--rraindex', 2)
+     local firstdate = rrd.first('example.rrd', '--rraindex', 2)

 
 B<rrd.last> returns a single INTEGER representing the last update time.
 
 
 B<rrd.last> returns a single INTEGER representing the last update time.
 

-  local lastupdate = rrd.last('example.rrd')
+     local lastupdate = rrd.last('example.rrd')

 
 B<rrd.graph> returns the x-size and y-size of the created image and a table
 with the results of the PRINT arguments.
 
 
 B<rrd.graph> returns the x-size and y-size of the created image and a table
 with the results of the PRINT arguments.
 

-  local xsize, ysize, averages = rrd.graph ...
-  print(string.format("Image size: %dx%d", xsize, ysize)
-  print("Averages: ", table.concat(averages, ', '))
+     local xsize, ysize, averages = rrd.graph ...
+     print(string.format("Image size: %dx%d", xsize, ysize)
+     print("Averages: ", table.concat(averages, ', '))

 
 B<rrd.info> returns a table where the keys and the values represent property
 names and property values of the RRD.
 
 
 B<rrd.info> returns a table where the keys and the values represent property
 names and property values of the RRD.
 

-  local info = rrd.info("test.rrd")
-  for key, value in pairs(info) do
-    print(key, ' = ', value)
-  end
+     local info = rrd.info("test.rrd")
+     for key, value in pairs(info) do
+       print(key, ' = ', value)
+     end

 
 B<rrd.graphv> takes the same parameters as rrd.graph but it returns a table
 only. The table returned contains meta information about the graph, like
 
 B<rrd.graphv> takes the same parameters as rrd.graph but it returns a table
 only. The table returned contains meta information about the graph, like


@@ -111,27 +172,33 @@ returns 5 values: the initial timestamp, the step, two parallel arrays
 containing the data source names and their data points respectively, and
 the final timestamp.
 
 containing the data source names and their data points respectively, and
 the final timestamp.
 

-  package.cpath = '/usr/local/rrdtool-1.3.3/lib/lua/5.1/?.so;' ..
-                   package.cpath
-  local rrd = require "rrd"
-  local first, last = rrd.first("test.rrd"), rrd.last("test.rrd")
-  local start, step, names, data =
-    rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE")
-  io.write(string.format("Start:       %s (%d)\n",
-                         os.date("%c", start),start))
-  io.write("Step size:   ", step, " seconds\n")
-  io.write("DS names:    ", table.concat(names, ', '), "\n")
-  io.write("Data points: ", #data[1], "\n")
-  io.write("Data:\n")
-  for i,dp in ipairs(data) do
-    io.write(os.date("%t", start), " (", start, "): ")
-    start = start + step
-    for j,v in ipairs(dp) do
-      io.write(v, " ")
-    end
-  io.write("\n")
-  end
+     --require compat-5.1 if necessary
+    
+     package.cpath = '/usr/local/rrdtool-1.3.2/lib/lua/5.0/?.so;' ..
+                     package.cpath
+    
+     local rrd = require "rrd"
+     local first, last = rrd.first("test.rrd"), rrd.last("test.rrd")
+     local start, step, names, data =
+       rrd.fetch("test.rrd", "--start", first, "--end", last, "AVERAGE")
+     io.write(string.format("Start:       %s (%d)\n",
+                            os.date("%c", start),start))
+     io.write("Step size:   ", step, " seconds\n")
+     io.write("DS names:    ", table.concat(names, ', '), "\n")
+     io.write("Data points: ", #data[1], "\n")
+     io.write("Data:\n")
+     for i,dp in ipairs(data) do
+       io.write(os.date("%t", start), " (", start, "): ")
+       start = start + step
+       for j,v in ipairs(dp) do
+         io.write(v, " ")
+       end
+     io.write("\n")
+     end

 
 =head1 AUTHOR
 
 Fidelis Assis E<lt>fidelis@pobox.comE<gt>
 
 =head1 AUTHOR
 
 Fidelis Assis E<lt>fidelis@pobox.comE<gt>

+
+
+