ask.lua

--[[
  Simple help system for Lua modules

  Author: Julio M. Fernandez-Diaz
  Date:   Feb, 2010
  (For Lua 5.1)

  It is not intended to be complete, instead to be `enough'.

  Error messages are displayed in stderr
--]]

-- Change the name of this file for other name if you wish
-- other name for querying help
local NAME = ...

module(NAME, package.seeall)

-- saving global names  -------------------------------------------

local format, rep, gsub, sub = string.format, string.rep, string.gsub, string.sub
local find, char, byte, setlocale = string.find, string.char, string.byte, os.setlocale
local type, io, os, table, ipairs, pairs = type, io, os, table, ipairs, pairs
local _G, setmetatable, require, pcall, error = _G, setmetatable, require, pcall, error
local print = print

-- default css if not provided
local CSS = [[
<style type="text/css">
body {
   font-family: Verdana, Helvetica, Arial, sans-serif;
   font-size: 11pt; color: black; background-color: #fbfbfb;
}
#content {
   top: 120px; margin-left: 225px;
}
#navigate {
   position: fixed; top: 10px; width: 210px; float: left;
	padding: 0 0 0 5px; background-color: #e6e6f2; line-height: 170%;
}
#navigate h1 {
   font-size: large; text-align: left;  
}
#navigate ul {
	margin-left: 5px; padding-left: 10px;
}
#navigate ul ul {
   font-size: 10pt; margin-left: 5px; padding-left: 10px; line-height: 130%;
}
#navigate ul ul ul {
   font-size: 90%; margin-left: 5px; padding-left: 10px; line-height: 110%;
}
#navigate a:link {
	color: #000099; text-decoration: none;
}
#navigate a:visited {
	color: #000099; text-decoration: none;
}
#navigate a:hover {
   color: #996633; text-decoration: none;
}
h1 {
   text-align: center; color: #000000; width: auto;
}
h2 {
   color: #006600; background-color: #ccffff; padding: 10px;
}
h3 {
   color: #000099; background-color: #ffffcc; padding: 5px;
}
h4 {
   font-size: normal; color: #990099;
}
h5 {
   border-top: 1px solid; font-size: medium; color: #990000;
}
h6 {
   font-size: medium; font-style: italic;
}
a:hover {
   color: #996633;
}
p.listoffun {
   word-spacing: 2em;
}
pre {
   font-size: 90%; border: 1px dotted #888888;
   background-color: #f9f9f9; padding: 5pt;
}
code {
   font-size: 95%; color: #006666;
}
var {
   color: #008040; font-style: italic; font-weight: normal;
}
</style>]]

-- private functions    -------------------------------------------

-- returns "utf-8" if detected, nil otherwise
local function detectutf8 ()
   local c = setlocale(nil, "ctype"):lower()
   local e = c:find("utf-8", 1, true) or c:find("utf8", 1, true)
   return e and "utf-8"
end

-- convert utf8 to iso
-- http://lua-users.org/lists/lua-l/2003-10/msg00281.html
local function utf8toiso (s)
   if s:find("[\224-\255]") then error("non-ISO char") end
   s = s:gsub("([\192-\223])(.)", function (c1, c2)
         c1 = byte(c1) - 192
         c2 = byte(c2) - 128
         return char(c1 * 64 + c2)
       end)
   return s
end

-- convert iso to utf8
-- the inverse of
-- http://lua-users.org/lists/lua-l/2003-10/msg00281.html
local function isotoutf8 (s)
   s = s:gsub("([\128-\255])", function (c)
         local b = c:byte()
         return b < 192 and "\194"..c or "\195"..char(b-64)
       end)
   return s
end

-- convert iso-8859 <-> utf-8
local function convertcs (s, cs, uft8)
	if cs == "utf-8" and not utf8 then -- convert to iso
 		return utf8toiso(s)     
   elseif cs ~= "utf-8" and utf8 then -- convert to utf-8
 		return isotoutf8(s)     
   end
	return s
end

-- for formatted writing in a file
local function fprintf (filehandler, fmt, ...)
   filehandler:write(format(fmt, ...))
end

-- print a line of s with n characters in stderr
local function line (s, n)
   n = n or 72
   io.stderr:write(rep(s, n).."\n")
end

-- Prints the file with name filename in the filehandler
local function printcss (filehandler, filename)
   local data
   local f = io.open(filename, "rb")
   if f == nil then
     data = CSS 
   else
     data = f:read("*all")
     f:close()
   end
   filehandler:write(data)
end

-- extract parts in what, by separating
-- [/][spath]^[info]
local function parts (what)
   local absol, spath, info = ""

   if what == nil then return nil end

   what = what:gsub("%s", "")   -- delete blanks
   what = what:gsub("[%.]+", ".")   -- collapse multiple .

   if what:sub(1,1) == "/" then  -- search initial /
      absol = "/"
      what = what:sub(2)
   end

   -- split parts
   -- if more than one "^" appears only the last part is info
   what:gsub("%^", "&")
   what:gsub("^([^&]*)^([^&]*)$", function (w1, w2) spath, info = w1, w2 end)
   if spath == nil then spath, info = what, "" 
   else
      spath:gsub("&", "%^")
      info:gsub("&", "%^")
   end

   -- delete possible initial and final .
   if spath:sub(1,1) == "." then spath = spath:sub(2) end
   if spath:sub(-1) == "." then spath = spath:sub(1,-2) end

   return absol, spath, info
end

-- split a string in fields separated by "."
local function splitdot (s)
   local t = {}
   s:gsub('([^%.]+)(%.*)', function (w, d) t[#t+1] = w end)
   return t
end

-- private variables    -------------------------------------------

local Cases = {"Basic information", "List of functions", "Usage of ",
               "More specific information", "See also", "Examples",
               "Description of functions", "Version", "Notes"}
local cases = {"basic", "list", "usage", "more", "seealso", "example",
               "description", "version", "notes",
              }
local order = {b = 1, l = 2, u = 3, m = 4, s = 5, 
               e = 6, d = 7, v = 8, n = 9} -- order for "all"

local basis = NAME


-- public objects       -------------------------------------------

_H = {
_CHARSET = "iso-8859-15",    -- "utf-8" in other cases
_basic = '`'..NAME..[[` is a system that provides help for modules.

It searches eight types of information:

    basic   list   usage   more   seealso   example   version   notes

Execute `]]..NAME..'"/'..NAME..'^usage"` and `'..NAME..'"/'..NAME..
[[^more"` for more explanation.

Apart from this, documentation in `html` format can 
be generated (see `]]..NAME..'.doc`).',
_usage = '`'..NAME..[[(search)`

@params:

1. `search` is a string in the form `"what^kind"` (a caret
   separates two parts of the argument).

@returns: nothing.

@effects: it prints in `io.stderr`.

`what` is what are looking for; if the first character in it is `/`
an *absolute* path is searched; if not the string defined in `]]..
NAME..[[.base` is used as a basis;

`kind` is the type of information we want, that can be:

    "basic"   | "list"    | "usage"   | "more"   | "seealso"
    "b"       | "l"       | "u"       | "m"      | "s"

    "example" | "version" | "notes"   | "all"  
    "e"       | "v"       | "n"       | "a"

(as we see, we can use only the first letter).
If `all` is requested then all information
(basic, list, usage, seealso, example, version, notes) *if exists* is given.
If no kind is provided (in this case the caret is optional) `"basic"` is assumed.

`]]..NAME..[[(nil)` and `]]..NAME..[[.about(nil)` are equivalent to
`]]..NAME..'"/'..NAME..[[^basic"`, that is, help about this helping system
is given.]],
_more = [[The search of information is controlled by two strings:
`what` and `kind`. Both are typed separated by a caret, `"^"`.

The first, `what`, is what we are searching. Normally this
is a sequence `name1[.name2[.name3 ...] ]` in which `name1` is a module
name, and `name2`, `name3`, ... indicate functions in the module or
tables with functions in the module.

If `what` begins with a slash, `/`, then an absolute path is searched.
Otherwise the help system adds as a prefix the string stored in a local
variable assigned with the function `]]..NAME..[[.base`. This improves the
interactivity because the user is not enforced to always type the
complete path of help.

The second, `kind`, is the type of information we want:

+ `basic`:    the purpose of the module or function inside a module,
+ `list`:     the listing of functions in the module,
+ `usage`:    the use of a function, describing the arguments and returns,
+ `more`:     more specific information,
+ `seealso`:  some related information,
+ `example`:  an example of use,
+ `version`:  information about version and author,
+ `notes`:    other information, usually license one,

+ `all`:      show all the previous information.

For activate the help system the user (interactively) or some module
should invoke

     require"]]..NAME..[["

**Note**: the present help system manages a module variable `_H`.
This means that `_H` cannot be used for other purposes in
the module.]],
_example = [[Some examples (with equivalences):

We assume the *first* invoking after `require"]]..NAME..[["` (by the user
or by some module):

    ]]..NAME..[[""                   --><--    ]]..NAME..[["/]]..NAME..[[^basic"
    ]]..NAME..[["^a"                 --><--    ]]..NAME..[["/]]..NAME..[[^all"
    ]]..NAME..[["/somemodule.fun^u"  --><--    ]]..NAME..[["/somemodule.fun^usage"
    
    ]]..NAME..[[.base"somemodule"    -- changes basis for searching
    
    ]]..NAME..[["^l"                 --><--    ]]..NAME..[["/somemodule^list"
    ]]..NAME..[["fun^u"              --><--    ]]..NAME..[["/somemodule.fun^usage"
    ]]..NAME..[["/]]..NAME..[[^m"             --><--    ]]..NAME..[["/]]..NAME..[[^more"]],
_Name = NAME,
_version = [[by Julio M. Fernández-Díaz, Dept. of Physics,
University of Oviedo, Spain, Version 0.1, February 2010

julio a t uniovi d o t es]],
_notes = [[THIS CODE IS HEREBY PLACED IN PUBLIC DOMAIN.

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.]]
}

_H.about = {
_basic = [[Main function for on line help (synonym of `]]..NAME..[[`)]],
_usage = '`'..NAME..[[.about(search)`


`]]..NAME..[[(search)`

@params:

1. `search` is a string in the form `"what^kind"` (a caret
   separates two parts of the argument).

@returns: nothing.

@effects: it prints in `io.stderr`.

`what` is what are looking for; if the first character in it is `/`
an *absolute* path is searched; if not the string defined through
`]]..NAME..[[.base` is used as a basis;

`kind` is the type of information we want, that can be:

    "basic"   | "list"    | "usage"   | "more"   | "seealso"
    "b"       | "l"       | "u"       | "m"      | "s"

    "example" | "version" | "notes"   | "all"  
    "e"       | "v"       | "n"       | "a"

(as we can see we can use only the first letter).
If `all` is requested then all information,
(basic, list, usage, seealso, example, version, notes) *if exists* is given.
If no kind is provided `"basic"` is assumed.

Spaces typed by the user in the set `what^kind` are deleted before
the search of the help. Also, multiple `"."` are collapsed.

`]]..NAME..[[(nil)` and `]]..NAME..[[.about(nil)` are equivalent to
`]]..NAME..'"/'..NAME..[[^basic"`, that is, help about this helping system
is given.]],
}

function about (what)
   what = what or "/"..NAME.."^basic"
   if what == "" then what = "/"..basis.."^basic" end

   local absol, spath, info = parts(what)

   if absol ~= "/" then
     if spath ~= "" then spath = basis.."."..spath
     else spath = basis end
   end
   if info == "" then info = "basic" end

   local ts = splitdot(spath)
   table.insert(ts, 2, "_H")

   if #info == 1 then
      if info == "a" then info = "all" 
      elseif order[info] then info = cases[order[info]] end
   end

   local tt = {info}
   if info == "all" then
      for k, v in ipairs(cases) do tt[k] = v end
   end

   local H = _G
   local CHARSET = H[ts[1]][ts[2]]["_CHARSET"]
   local UTF8    = detectutf8()

   for k = 1, #ts do
      if H then H = H[ts[k]] end
   end
   if H == nil and info ~= "list" then
      io.stderr:write("No information about '/"..spath.."^"..info.."'\n")
      io.stderr:flush()
      return
   end

   if info == "list" then tt = {"list"} end

   local function fill (t)
      local pH = ""
      local nc, ic, lef = 3, 1, 25

      for j, s in ipairs(t) do
         pH = pH..s..(" "):rep(lef-#s)
         if ic == nc then pH = pH.."\n" end
         ic = ic+1
         if ic > nc then ic = 1 end
      end
      return pH.."\n"
   end

   for k, v in ipairs(tt) do
      local H1, pH = H["_"..v], ""
      if v == "list" then
         -- special case : list
     		local al = {}
     		for a in pairs(H) do
   			if a:sub(1,1) ~= "_" then al[#al+1] = a end
	     	end
      	if #al > 0 then 
            table.sort(al)
            io.stderr:write(">>>>>>>>>>   "..spath..":"..v.."   <<<<<<<<<<\n")
	   		pH = 'List of functions in "'..spath..'":\n\n'..fill(al)
            io.stderr:write(pH)
            line("-")
         end
      elseif H1 and type(H1) ~= "table" then
         io.stderr:write(">>>>>>>>>>   "..spath.." ^ "..v.."   <<<<<<<<<<\n")
         H1 = convertcs(H1, CHARSET, UTF8)
         io.stderr:write(pH..H1.."\n")
         line("-")
      elseif info ~= "all" then
         io.stderr:write(">>No information about '/"..spath.." ^ "..info.."'\n")
      end
   end

   io.stderr:flush()
end

_H.base = {
_basic = [[Establishes a *basis prefix* for help searching]],
_usage = [[`]]..NAME..[[.base(basis)`

@params:

1. `basis`, string.

@returns: nothing.

This function changes the `basis` (a string) to add as a prefix in the
desired information path when this does not begin with a slash, `/`.

When providind `basis` the slashdot `"/"` is not required.

Initially basis has the value `"]]..NAME..[["` but the loading of a module
sets the current `basis` to the module name.

When calling `]]..NAME..[[.base""` the current basis is displayed.

Calling `]]..NAME..[[.base(nil)` establishes `"]]..NAME..[["` as basis.]]
}

function base (b)
   if b == nil or type(b) ~= "string" then b = NAME end
   if b~= "" then
      if b:sub(1,1) == "/" then b = b:sub(2) end
      basis, now = b
      io.stderr:write('--> Changing help basis to "'..basis..'"\n')
   else
      io.stderr:write('--> Help basis is "'..basis..'"\n')
   end
end

_H.doc = {
_basic = [[Create `html` documentation for a module]],
_usage = [[`]]..NAME..[[.doc(modulename, filename)`

@params: 

1. `modulename`: string (optional) is the name of the module
   of which we want the documentation.
   If not provided then the basis is used.
2. `filename`: string (optional) is the name of the output file,
   in `html` format. If not given the name of the module is used.
   If one of the extensions `".html"` or `".htm"` (in lowercase) is
   not provided then automatically `".html"` is added to the filename.

@returns: nothing

@effects: it creates a file.

For generating the documentation module
[markdown.lua](http://www.frykholm.se/programming.html) from Niklas Frykholm
must be accessible. 
(Note: the version in [luaforge.net](http://luaforge.net) is obsolete.)]],
_more = [[A CSS file called `default.css`, which is possible
to customize, is used. This file is embeded in the `html` output file.
If not provided the system uses an internal style.

The resulting `html` file can be converted, v.g., to PS
with [html2ps](http://user.it.uu.se/~jan/html2ps.html), from Jan Kärrman.
After that `ps2pdf` can be used to convert it to PDF format.]],
}

function doc (name, filename)
   if type(name) ~= "string" then
      io.stderr:write("A name of a module must be given\n")
      return
   end

   if name == "" then name = basis end
   if _G[name] == nil then
      io.stderr:write("Module "..name.." not found\n")
      return
   end

   local gn = _G[name]
   if gn._H == nil then
      io.stderr:write("Module "..name.." has no help information\n")
      return
   end
   name = gn._H._Name
   local CHARSET = gn._H._CHARSET

   filename = filename or name
   if type(filename) ~= "string" then
      io.stderr:write("A filename for output must be given\n")
      return
   end

   -- check for .html or .htm extension in filename
   if filename:sub(-5) ~= ".html" and filename:sub(-4) ~= ".htm" then
      filename = filename..".html"
   end

   local f = io.open(filename, "w")
   if f == nil then
      io.stderr:write('"'..filename..' cannot be created\n')
      return
   end

   local md, markdown = pcall(require, "markdown")
   if not md then
      io.stderr:write("Markdown not found. No conversion is applied\n")
      markdown = function (s) return s end
   end

   local cart = {}

   gn = gn._H

   local function pref (s)
      return '<a href="#'..s..'">'..s..'</a>'
   end

   local function listfun (gn)
      -- prepare an alphabetical list of (sub)functions
      local al = {}
      for a in pairs(gn) do
   		if a:sub(1,1) ~= "_" then al[#al+1] = {name = a} end
      end
      if #al > 0 then 
         table.sort(al, function (a, b) return a.name < b.name end)
      end
      for i, a in ipairs(al) do
    		local d = gn[a.name]
         if d then
            local b = listfun(d)
            if #b > 0 then al[i][1] = b end
         end
      end
   	return al
   end

   local allfun = listfun(gn)

   local function showlist (allfun, prev)
		local cart = ""
		for i, a in ipairs(allfun) do
         local pr = prev == "" and "" or prev.."_"
			cart = cart..'<li>'..'<a href="#'..pr..a.name..'">'..a.name..'</a>'
         if #a > 0 then
            cart = cart.."\n<ul>"..showlist(a[1], a.name).."\n</ul>"
         end
         cart = cart..'</li>\n'
      end
      return cart
   end

   local function navigate (gn, level, allfun)
     	-- check in order _-beginning fields
      for i, c in ipairs(cases) do
   		local d = gn["_"..c]
         local Ca = Cases[i]
       	if cases[i] == "usage" then
            Ca = Ca..(level == 2 and "the module" or "function")
         end
         if d or c == "list" then
   			cart[#cart+1] = "<li>"..'<a href="#'..c..'">'..Ca.."</a></li>\n"
         end
         if c == "description" then 
   		   if #allfun > 0 then
      			cart[#cart+1] = "<li>"..'<a href="#'..c..'">'..Ca.."</a>\n"
   				cart[#cart+1] = '<ul>\n'
   				cart[#cart+1] = showlist(allfun, "")
   				cart[#cart+1] = '</ul></li>\n'
     			end
      	end
      end
   end

   -- navigation menu

   cart[#cart+1] = '<div class="noprint" id="navigate">\n'
   cart[#cart+1] = '<h1>Module <code>'..name..'</code></h1>\n\n'
   cart[#cart+1] = '<ul>\n'

   navigate(gn, 2, allfun)

   cart[#cart+1] = '</ul></div>\n'

   -- main part

   local function inside (gn, level, previous)
      -- prepare an alphabetical list of (sub)functions
      local al = {}
      for a in pairs(gn) do
   		if a:sub(1,1) ~= "_" then al[#al+1] = a end
      end
      if #al > 0 then table.sort(al) end
   
     	-- check in order _-beginning fields
      for i, c in ipairs(cases) do
   		local d = gn["_"..c]
         local Ca = Cases[i]
       	if cases[i] == "usage" then
            Ca = Ca..(level == 2 and "the module" or "function")
         end
         local pH = "\n"
         if c == "list" and #al > 0 then
            local ts = splitdot(previous)
            table.remove(ts, 1)
            local s = table.concat(ts, "_")
            if #s > 0 then s = s.."_" end
            pH = pH..'<p class="listoffun">\n'
            for j, fun in ipairs(al) do
               pH = pH..'<a href="#'..s..fun..'">'..fun..'</a>\n'
            end
            pH = pH.."</p>\n\n"
				local cc = level == 2 and ' id ="'..c..'"' or ""
   			cart[#cart+1] = '\n<h'..level..cc..'>'..Ca..'</h'..level..'>\n'
            cart[#cart+1] = pH
            cart[#cart+1] = "\n"
         end
         if c == "description" and #al > 0 then
           table.sort(al)
   		  cart[#cart+1] = '\n<h'..level..
                           ' id = "description">Description of functions</h'..
                           level..'>\n\n'
           local level1 = level+1
           for i, a in ipairs(al) do
              local pre = previous == "" and a or previous.."."..a 
              local ts = splitdot(pre)
              table.remove(ts, 1)
              local s = table.concat(ts, "_")
     	        cart[#cart+1] = '<h'..level1..' id="'..s..
                              '">'..pre..'</h'..level1..'>\n'
          	  local d = gn[a]
              if d then inside(d, level1+1, pre) end
           end
         end
         if d then
				local cc = level == 2 and ' id ="'..c..'"' or ""
				--local cc = ' id ="'..c..'"'
   			cart[#cart+1] = '\n<h'..level..cc..'>'..Ca..'</h'..level..'>\n'
            cart[#cart+1] = pH..markdown(d)
            cart[#cart+1] = "\n"
         end
      end
   
   end

   cart[#cart+1] = '<div id="content">\n'
   cart[#cart+1] = "<h1>Module "..name.."</h1>\n"

   inside(gn, 2, name)

   cart[#cart+1] = '</div>\n'

   -- printing
   local s = table.concat(cart, "\n")


   local head = [[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
   <meta http-equiv="content-type" content="text/html; charset=]]..CHARSET..[[" />
   <title>%s</title>]]
   local head1 = "\n</head> <body>\n"

   local foot = "\n</body></html>\n"
   
   fprintf(f, head, "Module "..name)

   -- embeding CSS file

   printcss(f, "default.css")

   f:write(head1)
   f:write(s)
   f:write(foot)
   
   f:close()
end

io.stderr:write('A help system is available. Call '..NAME..'(nil) for information.\n')

base(NAME)

__call = function (t, s, ...)
   if s == nil then
      about(nil)
   elseif type(s) == "string" then
      about(s)
   else
      return t[s](...)
   end
end

setmetatable(_G[NAME], _G[NAME])