| -------------------------------------------------------------------------------- |
| -- Copyright (c) 2011-2012 Sierra Wireless. |
| -- All rights reserved. This program and the accompanying materials |
| -- are made available under the terms of the Eclipse Public License v1.0 |
| -- which accompanies this distribution, and is available at |
| -- http://www.eclipse.org/legal/epl-v10.html |
| -- |
| -- Contributors: |
| -- Kevin KIN-FOO <kkinfoo@sierrawireless.com> |
| -- - initial API and implementation and initial documentation |
| -------------------------------------------------------------------------------- |
| --- |
| -- This library provide html description of elements from the externalapi |
| local M = {} |
| |
| -- Load template engine |
| local pltemplate = require 'pl.template' |
| |
| -- Markdown handling |
| local markdown = require 'markdown' |
| |
| -- apply template to the given element |
| function M.applytemplate(elem, ident, templatetype,...) |
| -- define environment |
| local env = M.getenv(elem, ident,...) |
| |
| -- load template |
| local template = M.gettemplate(elem,templatetype) |
| if not template then |
| templatetype = templatetype and string.format(' "%s"', templatetype) or '' |
| local elementname = string.format(' for %s', elem.tag or 'untagged element') |
| error(string.format('Unable to load %s template %s', templatetype, elementname)) |
| end |
| |
| -- apply template |
| local str, err = pltemplate.substitute(template, env) |
| |
| --manage errors |
| if not str then |
| local templateerror = templatetype and string.format(' parsing "%s" template ', templatetype) or '' |
| error(string.format('An error occured%s for "%s"\n%s',templateerror, elem.tag, err)) |
| end |
| return str |
| end |
| |
| -- get the a new environment for this element |
| function M.getenv(elem, ident,...) |
| local currentenv ={} |
| for k,v in pairs(M.env) do currentenv[k] = v end |
| if elem and elem.tag then |
| currentenv['_'..elem.tag]= elem |
| end |
| currentenv['i']= ident or 1 |
| currentenv['templateparams']= {...} |
| return currentenv |
| end |
| |
| -- get the template for this element |
| function M.gettemplate(elem,templatetype) |
| local tag = elem and elem.tag |
| if tag then |
| if templatetype then |
| return require ("template." .. templatetype.. "." .. tag) |
| else |
| return require ("template." .. tag) |
| end |
| end |
| end |
| |
| |
| --- |
| -- Allow user to format text in descriptions. |
| -- Default implementation replaces @{---} tags with links and apply markdown. |
| -- @return #string |
| local function format(string) |
| -- Allow to replace encountered tags with valid links |
| local replace = function(found) |
| local apiobj = M.env.getelement(found) |
| if apiobj then |
| return M.env.fulllinkto(apiobj) |
| end |
| return found |
| end |
| string = string:gsub('@{%s*(.-)%s*}', replace) |
| return M.env.markdown( string ) |
| end |
| --- |
| -- Disable Markdown processing on a specific string |
| -- @param #string s Content to browse |
| -- @param #string escaped What Markdown should not process |
| -- @return #string Original `s` #string with `escaped` #string backslashed |
| local function escape(s, escaped) |
| return string.gsub(s, escaped, '\\'..escaped) |
| end |
| --- |
| -- Provide a full link to an element using `prettyname` and `linkto`. |
| -- Default implementation is for HTML. |
| local function fulllinkto(o,...) |
| local ref = M.env.linkto(o,...) |
| local name = M.env.prettyname(o,...) |
| if not ref then |
| return name |
| end |
| return string.format('<a href="%s">%s</a>', ref, escape(name, '_')) |
| end |
| -- |
| -- Define default template environnement |
| -- |
| local defaultenv = { |
| table = table, |
| ipairs = ipairs, |
| pairs = pairs, |
| markdown = markdown, |
| applytemplate = M.applytemplate, |
| format = format, |
| linkto = function(str) return str end, |
| fulllinkto = fulllinkto, |
| prettyname = function(s) return s end, |
| getelement = function(s) return nil end |
| } |
| |
| -- this is the global env accessible in the templates |
| -- env should be redefine by docgenerator user to add functions or redefine it. |
| M.env = defaultenv |
| return M |