Commit dcd9efdf authored by Renato Figueiro Maia's avatar Renato Figueiro Maia
Browse files

[OPENBUS-2770] Documentar o novo 'busadmin' do OpenBus 2.1

git-svn-id: https://subversion.tecgraf.puc-rio.br/engdist/openbus/core/trunk@163516 ae0415b3-e90b-0410-900d-d0be9363c56b
parent 1e4a2d18
<%
local loader = require "manual.loader"
local html = require "manual.html"
local help = require "openbus.core.admin.help"
package.loaded["openbus.core.admin.help"] = nil
local manual, types = loader.load(help)
return html.output(manual, types)
%>
\ No newline at end of file
pages = {
{ index="BusAdmin", href="busadmin.htm", title="Bus Admin API" },
}
refs = {
{ index="Tecgraf", href="http://www.tecgraf.puc-rio.br/", title="Tecgraf" },
{ index="PUC-Rio", href="http://www.puc-rio.br/" , title="PUC-Rio" },
}
template = [===================================================================[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>OpenBus</title>
<style type="text/css" media="all"><!--
@import "<%=href("gray.css")%>";
@import "<%=href("layout1.css")%>";
--></style>
</head>
<body>
<div class="content">
<% if item.title then return "<h1>"..item.title.."</h1>" end %>
<%
local contents = contents()
if contents then
return contents:gsub("<pre>(.-)</pre>", function(code)
return "<pre>"..code:gsub("\t", " ").."</pre>"
end)
end
%>
</div>
<div class="content">
<p><small><strong>Copyright (C) 2004-2014 Tecgraf, PUC-Rio</strong></small></p>
<small>This project is currently being maintained by <%=link("Tecgraf")%> at <%=link("PUC-Rio")%>.</small>
</div>
</body>
</html> ]===================================================================]
local oo = require "manual.oo"
local Buffer = oo.class{
identcount = 0,
identation = "",
output = table.concat,
}
function Buffer:write(...)
local base = #self
if self.linebreak then
base = base+1
self[base] = "\n"..string.rep("\t", self.identcount)
self.linebreak = nil
end
for index = 1, select("#", ...) do
--
--if type(select(index, ...)) ~= "string" then error("Ooops! "..type(select(index, ...)).."@"..index) end
--
self[base+index] = select(index, ...)
end
end
function Buffer:writeln(...)
self:write(...)
self.linebreak = true
end
function Buffer:ident(shift)
self.identcount = self.identcount+shift
self.identation = string.rep("\t", self.identcount)
end
return Buffer
local Viewer = require "loop.debug.Viewer"
local oo = require "manual.oo"
local Buffer = require "manual.Buffer"
local loader = require "manual.loader"
local i18n = require "manual.i18n"
local CallableFields = {"parameters", "results"}
local HTMLBuffer = oo.class({}, Buffer)
function HTMLBuffer:__new(...)
local self = oo.rawnew(self, ...)
self.viewer = Viewer{
output = self,
linebreak = false,
noindices = true,
nolabels = true,
metaonly = true,
}
return self
end
function HTMLBuffer:value(...)
self:write("<code>")
self.viewer:write(...)
self:write("</code>")
end
function HTMLBuffer:code(...)
self:write("<code>", ...)
self:write("</code>")
end
function HTMLBuffer:emphasis(...)
self:write("<em>", ...)
self:write("</em>")
end
function HTMLBuffer:paragraph(text)
local function replaceRef(id)
local desc = self.types[id]
if desc == nil then
return '<code>'..id..'</code>'
else
return '<a href=#'..id..'>'..(desc.title or desc.name)..'</a>'
end
end
local extra = text:match("^%s+")
if extra ~= nil then
text = text:gsub("\n"..extra, "\n")
:gsub("^"..extra, "")
:gsub("%s+$", "")
end
self:write((text:gsub("\n\n", "</p>\n"..self.identation.."<p>")
:gsub("\n", "\n"..self.identation)
:gsub("<#([_%a][_%w]*)>", replaceRef)))
end
function HTMLBuffer:type(id, label, anchor)
local desc = self.types[id]
local ref
if desc ~= nil then
label, ref = label or desc.title, id
end
label = label or id
local link = ref ~= nil or anchor ~= nil
if link then
self:write('<a')
if anchor ~= nil then
self:write(' name="',anchor,'"')
end
if ref ~= nil then
self:write(' href="#',ref,'"')
end
self:write('>')
end
self:write(label)
if link then
self:write('</a>')
end
end
local summary
local contents
local entries
local TitleOfField = {
parameters = "Parameter",
results = "Returned value",
}
local ClassOfField = {
parameters = "Parameters",
results = "Values Returned",
}
local function method(desc)
contents:writeln('<table>')
contents:ident(1)
local lang = desc.language or loader.language or "en"
local msg = assert(i18n[lang], "output language not supported")
for _, field in ipairs(CallableFields) do
local list = desc[field]
if list ~= nil then
contents:writeln('<tr>')
contents:ident(1)
contents:writeln('<th colspan=4 align=left>',msg.CallableValueHeader[field],'</th>')
contents:ident(-1)
contents:writeln('</tr>')
for index, arg in ipairs(list) do
contents:writeln('<tr>')
contents:ident(1)
contents:writeln('<td><code>',arg.name,'</code></td>')
contents:write('<td><code>=</code></td><td><code>')
if type(arg.type) == "table" then
for index, info in ipairs(arg.type) do
if index > 1 then
contents:write('|')
end
contents:type(info.type, info.type)
end
elseif arg.type ~= nil then
contents:type(arg.type, arg.type)
end
contents:writeln('</code></td>')
contents:writeln('<td>',arg.title or "",'</td>')
contents:ident(-1)
contents:writeln('</tr>')
end
end
end
contents:ident(-1)
contents:writeln('</table>')
contents:write('<p>')
desc:writeDesc(contents)
contents:writeln('</p>')
for _, field in ipairs(CallableFields) do
local list = desc[field]
if list ~= nil then
for _, arg in ipairs(list) do
local msg = assert(i18n[arg.language or lang], "output language not supported")
contents:write('<p>',msg.CallableValueLabel[field],' ')
arg:writeDesc(contents)
contents:writeln('</p>')
end
end
end
end
local function definition(desc)
summary:writeln('<li><a href="#',desc.id,'">',desc.title or desc.name,'</a></li>')
contents:writeln('<h2><a name="',desc.id,'">',desc.title or desc.name,'</a></h2>')
if desc.type == "table" then
contents:write('<p>')
desc:writeDesc(contents)
contents:writeln('</p>')
if desc.fields ~= nil then
contents:writeln('<dl>')
contents:ident(1)
for _, desc in ipairs(desc.fields) do
entries[#entries+1] = desc
contents:write('<dt><code>')
desc:writeId(contents, desc.id)
contents:writeln('</code></dt>')
contents:writeln('<dd>')
contents:ident(1)
if desc.type == "function" or desc.type == "method" then
method(desc)
else
contents:write('<p>')
desc:writeDesc(contents)
contents:writeln('</p>')
end
contents:ident(-1)
contents:writeln('</dd>')
end
contents:ident(-1)
contents:writeln('</dl>')
end
elseif desc.type == "function" then
entries[#entries+1] = desc
contents:write('<h3><code>')
desc:writeId(contents)
contents:writeln('</code></h3>')
method(desc)
else
contents:write('<p>')
desc:writeDesc(contents)
contents:writeln('</p>')
end
end
local function result(root, types)
summary.types = types
contents.types = types
summary:writeln('<h1>',root.title or root.name,'</h1>')
contents:write('<p>')
root:writeDesc(summary)
contents:writeln('</p>')
summary:writeln('<h2>Summary</h2>')
summary:writeln('<ol>')
summary:ident(1)
for index, desc in ipairs(root.fields) do
definition(desc)
end
summary:writeln('<li><a href="#(index)">API Index</a></li>')
summary:ident(-1)
summary:writeln('</ol>')
contents:writeln('<h2><a name=(index)>API Index</a></h2>')
contents:writeln('<table>')
contents:ident(1)
table.sort(entries, function(one, other) return one.id < other.id end)
for _, desc in pairs(entries) do
if desc.name ~= nil then
contents:writeln('<tr>')
contents:ident(1)
contents:writeln('<td><code><a href=#',desc.id,'>',desc.id,'</a><code></td>')
contents:writeln('<td>',desc.title or '','</td>')
contents:ident(-1)
contents:writeln('</tr>')
end
end
contents:ident(-1)
contents:writeln('</table>')
return summary:output().."\n"..contents:output()
end
local module = {}
function module.output(manual, types)
summary = HTMLBuffer()
contents = HTMLBuffer()
entries = {}
return [[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>Lua Man Demo</title>
</head>
<body>
]]..result(manual, types)..[[
</body>
</html>]]
end
return module
return {
en = {
IsEitherA = "is either a",
IsA = "is a",
OrA = "or a",
That = "that",
TheDefaultValueIs = "The default value is",
WhenAbsent = "When absent",
ItIsAbsentWhen = "It is absent when",
CallableValueLabel = {
parameters = "Parameter",
results = "Returned value",
},
CallableValueHeader = {
parameters = "Parameters",
results = "Values Returned",
},
},
pt = {
IsEitherA = "ou é um valor do tipo",
IsA = "é um valor do tipo",
OrA = "ou é um valor do tipo",
That = "que",
TheDefaultValueIs = "O valor default é",
WhenAbsent = "Quando ausente",
ItIsAbsentWhen = "É ausente quando",
CallableValueLabel = {
parameters = "Parametro",
results = "Valor de retorno",
},
CallableValueHeader = {
parameters = "Parametros",
results = "Valores de Retorno",
},
},
}
local oo = require "manual.oo"
local i18n = require "manual.i18n"
local module = {}
local function validId(id)
return id ~= nil and id:match("^[%a_]+[%w_]*$") ~= nil
end
local count = 0
local function newId(id)
count = count + 1
return "(doc"..count..")"
end
local function compareNames(one, other)
return one.name < other.name
end
local function compareTitles(one, other)
one = one.title or one.name
other = other.title or other.name
return one < other
end
local function Sorted(map, comp)
local list = {}
for name, desc in pairs(map) do
if type(name) == "string" then
desc.name = name
list[#list+1] = desc
end
end
table.sort(list, comp or compareNames)
local base = #map
for index, desc in ipairs(list) do
map[base+index] = desc
end
for index, desc in ipairs(map) do
desc.index = index
end
end
local Node = oo.class()
local function Varargs(list, prefix, scope)
if list ~= nil then
for index, item in ipairs(list) do
if item.name == nil then
item.name = prefix..index
end
item.kind = prefix
Node(item, scope)
end
return list
end
end
local function Callable(desc)
desc.parameters = Varargs(desc.parameters, "arg", desc)
desc.results = Varargs(desc.results, "ret", desc)
end
function Node:__new(desc, scope)
oo.rawnew(self, desc)
desc.scope = scope
if scope == nil then
desc.id = desc.name or newId()
elseif desc.type == "method" then
desc.id = scope.id..":"..desc.name
elseif validId(scope.id) then
desc.id = scope.id.."."..desc.name
else
desc.id = desc.name
end
if desc.type == "function" or desc.type == "method" then
Callable(desc)
end
return desc
end
local function writeVarargs(out, list)
local count = 0
for index, value in ipairs(list) do
local optional = value.eventual ~= nil or value.default ~= nil
if optional then
if index > 1 then
out:write(" [")
else
out:write("[")
end
count = count+1
else
out:write(string.rep("]", count))
count = 0
end
if index > 1 then
out:write(", ")
end
out:type(value.type, value.name)
end
if count > 0 then
out:write(string.rep("]", count))
end
end
function Node:writeId(out, ...)
local callable = (self.type == "method" or self.type == "function")
if callable and self.results ~= nil and #self.results > 0 then
writeVarargs(out, self.results)
out:write(' = ')
end
out:type(self.type, self.id, ...)
if callable then
out:write('(')
if self.parameters ~= nil then
writeVarargs(out, self.parameters)
end
out:write(')')
end
end
function Node:writeDesc(out)
local lang = self.language or module.language or "en"
local i18n = assert(i18n[lang], "output language not supported")
local described
if self.name == "..." or validId(self.name) then
out:code(self.name)
if type(self.type) == "table" then
for index, info in ipairs(self.type) do
if index == 1 then
out:write(" ",#self.type == 2 and i18n.IsEitherA or i18n.IsA, " ")
else
out:write("; ",i18n.OrA," ")
end
out:type(info.type)
if info.description ~= nil then
out:write(" ",i18n.That," ")
out:paragraph(info.description)
described = true
end
end
out:write(".")
elseif self.type ~= nil then
out:write(" ",i18n.IsA," ")
out:type(self.type)
if self.description == nil then
out:write(".")
else
out:write(" ",i18n.That)
end
elseif self.description == nil then
out:write(".")
end
end
if self.description ~= nil then
out:write(" ")
out:paragraph(self.description)
elseif not described and self.title ~= nil then
out:emphasis(" ("..self.title..")")
end
if self.default ~= nil and self.kind == "arg" then
out:writeln()
out:write(i18n.TheDefaultValueIs," <code>")
out:value(self.default)
out:write("</code>.")
end
if self.eventual ~= nil then
out:writeln()
out:write(self.kind == "arg" and i18n.WhenAbsent or i18n.ItIsAbsentWhen," ")
out:paragraph(self.eventual)
end
end
local DefinitionTypes = {
["table"] = true,
["function"] = true,
}
local function Definition(desc, types)
if desc.type ~= nil and DefinitionTypes[desc.type] == nil then
error("illegal definition type, got '"..tostring(desc.type).."'")
end
Node(desc)
types[desc.id] = desc
if (desc.type ~= nil and desc.type ~= "table") or desc.name ~= nil then
assert(validId(desc.name),
"illegal definition name, got '"..tostring(desc.name).."'")
desc.id = desc.name
end
if desc.type == "table" then
Sorted(desc.fields)
for index, field in ipairs(desc.fields) do
assert(validId(field.name),
"illegal field name, got '"..tostring(desc.name).."'")
Node(field, desc)
types[field.id] = field
end
end
end
local function Root(desc)
local types = {}
Node(desc)
Sorted(desc.fields, compareTitles)
for index, field in ipairs(desc.fields) do
Definition(field, types)
end
return types
end
function module.load(root)
local types = Root(root)
return root, types
end
return module
local loader = require "manual.loader"
local html = require "manual.html"
local input, output
input, output, loader.