Archive/TombEngine
0
0
Fork 0
mirror of https://github.com/TombEngine/TombEngine.git synced 2025-04-28 15:57:59 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Ldoc portable compiler (#1330)

Browse source 
* Add portable ldoc compiler and build event

* Remove broken ldoc compiler

* Remove unneeded file, remove timestamp

* Update documentation
This commit is contained in:
Lwmte 2024-02-13 19:02:25 +02:00 • committed by GitHub
parent f9fd81266f
commit 3c4b6fcf3c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
135 changed files with 10029 additions and 81 deletions
Download patch file Download diff file Expand all files Collapse all files

7
Documentation/compile.bat Normal file
View file

@ -0,0 +1,7 @@
@echo off
setlocal
set LDOC_DIR=.\compiler\ldoc
set LUA_PATH=.\compiler\?.lua
set LUA_CPATH=.\compiler\?.dll
.\compiler\lua.exe %LDOC_DIR%\\ldoc.lua %*
exit /b %ERRORLEVEL%

22
Documentation/compiler/ldoc/COPYRIGHT Normal file
View file

@ -0,0 +1,22 @@
LDoc License
-----------
Copyright (C) 2011 Steve Donovan.
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.

66
Documentation/compiler/ldoc/ldoc-scm-3.rockspec Normal file
View file

@ -0,0 +1,66 @@
package = "ldoc"
version = "scm-3"
source = {
dir="LDoc",
url = "git+https://github.com/stevedonovan/LDoc.git"
}
description = {
summary = "A Lua Documentation Tool",
detailed = [[
LDoc is a LuaDoc-compatible documentation generator which can also
process C extension source. Markdown may be optionally used to
render comments, as well as integrated readme documentation and
pretty-printed example files
]],
homepage='https://github.com/lunarmodules/LDoc',
maintainer='steve.j.donovan@gmail.com',
license = "MIT/X11",
}
dependencies = {
"penlight","markdown"
}
build = {
type = "builtin",
modules = {
["ldoc.tools"] = "ldoc/tools.lua",
["ldoc.lang"] = "ldoc/lang.lua",
["ldoc.parse"] = "ldoc/parse.lua",
["ldoc.html"] = "ldoc/html.lua",
["ldoc.lexer"] = "ldoc/lexer.lua",
["ldoc.markup"] = "ldoc/markup.lua",
["ldoc.prettify"] = "ldoc/prettify.lua",
["ldoc.markdown"] = "ldoc/markdown.lua",
["ldoc.doc"] = "ldoc/doc.lua",
["ldoc.html.ldoc_ltp"] = "ldoc/html/ldoc_ltp.lua",
["ldoc.html.ldoc_md_ltp"] = "ldoc/html/ldoc_md_ltp.lua",
["ldoc.html.ldoc_css"] = "ldoc/html/ldoc_css.lua",
["ldoc.html._code_css"] = "ldoc/html/_code_css.lua",
["ldoc.html._reset_css"] = "ldoc/html/_reset_css.lua",
["ldoc.html.ldoc_one_css"] = "ldoc/html/ldoc_one_css.lua",
["ldoc.html.ldoc_pale_css"] = "ldoc/html/ldoc_pale_css.lua",
["ldoc.html.ldoc_new_css"] = "ldoc/html/ldoc_new_css.lua",
["ldoc.html.ldoc_fixed_css"] = "ldoc/html/ldoc_fixed_css.lua",
["ldoc.builtin.globals"] = "ldoc/builtin/globals.lua",
["ldoc.builtin.coroutine"] = "ldoc/builtin/coroutine.lua",
["ldoc.builtin.global"] = "ldoc/builtin/global.lua",
["ldoc.builtin.debug"] = "ldoc/builtin/debug.lua",
["ldoc.builtin.io"] = "ldoc/builtin/io.lua",
["ldoc.builtin.lfs"] = "ldoc/builtin/lfs.lua",
["ldoc.builtin.lpeg"] = "ldoc/builtin/lpeg.lua",
["ldoc.builtin.math"] = "ldoc/builtin/math.lua",
["ldoc.builtin.os"] = "ldoc/builtin/os.lua",
["ldoc.builtin.package"] = "ldoc/builtin/package.lua",
["ldoc.builtin.string"] = "ldoc/builtin/string.lua",
["ldoc.builtin.table"] = "ldoc/builtin/table.lua",
},
copy_directories = {'doc','tests'},
install = {
bin = {
ldoc = "ldoc.lua"
}
}
}

866
Documentation/compiler/ldoc/ldoc.lua Normal file
View file

@ -0,0 +1,866 @@
#!/usr/bin/env lua
---------------
-- ## ldoc, a Lua documentation generator.
--
-- Compatible with luadoc-style annotations, but providing
-- easier customization options.
--
-- C/C++ support for Lua extensions is provided.
--
-- Available from LuaRocks as 'ldoc' and as a [Zip file](http://stevedonovan.github.com/files/ldoc-1.4.3.zip)
--
-- [Github Page](https://github.com/stevedonovan/ldoc)
--
-- @author Steve Donovan
-- @copyright 2011
-- @license MIT/X11
-- @script ldoc
local class = require 'pl.class'
local app = require 'pl.app'
local path = require 'pl.path'
local dir = require 'pl.dir'
local utils = require 'pl.utils'
local List = require 'pl.List'
local stringx = require 'pl.stringx'
local tablex = require 'pl.tablex'
-- Penlight compatibility
utils.unpack = utils.unpack or unpack or table.unpack
local lapp = require 'pl.lapp'
local version = '1.4.6'
-- so we can find our private modules
app.require_here()
--- @usage
local usage = [[
ldoc, a documentation generator for Lua, v]]..version..[[
Invocation:
ldoc [options] <file>
ldoc --version
Options:
-d,--dir (default doc) output directory
-o,--output (default 'index') output name
-v,--verbose verbose
-a,--all show local functions, etc, in docs
-q,--quiet suppress output
-m,--module module docs as text
-s,--style (default !) directory for style sheet (ldoc.css)
-l,--template (default !) directory for template (ldoc.ltp)
-p,--project (default ldoc) project name
-t,--title (default Reference) page title
-f,--format (default plain) formatting - can be markdown, discount or plain
-b,--package (default .) top-level package basename (needed for module(...))
-x,--ext (default html) output file extension
-c,--config (default config.ld) configuration name
-u,--unqualified don't show package name in sidebar links
-i,--ignore ignore any 'no doc comment or no module' warnings
-X,--not_luadoc break LuaDoc compatibility. Descriptions may continue after tags.
-D,--define (default none) set a flag to be used in config.ld
-C,--colon use colon style
-N,--no_args_infer don't infer arguments from source
-B,--boilerplate ignore first comment in source files
-M,--merge allow module merging
-S,--simple no return or params, no summary
-O,--one one-column output layout
-V,--version show version information
--date (default system) use this date in generated doc
--dump debug output dump
--filter (default none) filter output as Lua data (e.g pl.pretty.dump)
--tags (default none) show all references to given tags, comma-separated
--fatalwarnings non-zero exit status on any warning
--testing reproducible build; no date or version on output
--icon (default none) an image that will be displayed under the project name on all pages
<file> (string) source file or directory containing source
`ldoc .` reads options from an `config.ld` file in same directory;
`ldoc -c path/to/myconfig.ld <file>` reads options from `path/to/myconfig.ld`
and processes <file> if 'file' was not defined in the ld file.
]]
local args = lapp(usage)
local lfs = require 'lfs'
local doc = require 'ldoc.doc'
local lang = require 'ldoc.lang'
local tools = require 'ldoc.tools'
local global = require 'ldoc.builtin.globals'
local markup = require 'ldoc.markup'
local parse = require 'ldoc.parse'
local KindMap = tools.KindMap
local Item,File = doc.Item,doc.File
local quit = utils.quit
if args.version then
print('LDoc v' .. version)
os.exit(0)
end
local ModuleMap = class(KindMap)
doc.ModuleMap = ModuleMap
function ModuleMap:_init ()
self.klass = ModuleMap
self.fieldname = 'section'
end
local ProjectMap = class(KindMap)
ProjectMap.project_level = true
function ProjectMap:_init ()
self.klass = ProjectMap
self.fieldname = 'type'
end
local lua, cc = lang.lua, lang.cc
local file_types = {
['.lua'] = lua,
['.ldoc'] = lua,
['.luadoc'] = lua,
['.c'] = cc,
['.h'] = cc,
['.cpp'] = cc,
['.cxx'] = cc,
['.C'] = cc,
['.mm'] = cc,
['.cs'] = cc,
['.moon'] = lang.moon,
}
------- ldoc external API ------------
-- the ldoc table represents the API available in `config.ld`.
local ldoc = { charset = 'UTF-8', version = version }
local known_types, kind_names = {}
local function lookup (itype,igroup,isubgroup)
local kn = kind_names[itype]
known_types[itype] = true
if kn then
if type(kn) == 'string' then
igroup = kn
else
igroup = kn[1]
isubgroup = kn[2]
end
end
return itype, igroup, isubgroup
end
local function setup_kinds ()
kind_names = ldoc.kind_names or {}
ModuleMap:add_kind(lookup('function','Functions','Parameters'))
ModuleMap:add_kind(lookup('table','Tables','Fields'))
ModuleMap:add_kind(lookup('field','Fields'))
ModuleMap:add_kind(lookup('type','Types'))
ModuleMap:add_kind(lookup('lfunction','Local Functions','Parameters'))
ModuleMap:add_kind(lookup('annotation','Issues'))
ProjectMap:add_kind(lookup('module','Modules'))
ProjectMap:add_kind(lookup('script','Scripts'))
ProjectMap:add_kind(lookup('classmod','Classes'))
ProjectMap:add_kind(lookup('topic','Topics'))
ProjectMap:add_kind(lookup('example','Examples'))
ProjectMap:add_kind(lookup('file','Source'))
for k in pairs(kind_names) do
if not known_types[k] then
quit("unknown item type "..tools.quote(k).." in kind_names")
end
end
end
-- hacky way for doc module to be passed options...
doc.ldoc = ldoc
-- if the corresponding argument was the default, then any ldoc field overrides
local function override (field,defval)
defval = defval or false
if args[field] == defval and ldoc[field] ~= nil then args[field] = ldoc[field] end
end
-- aliases to existing tags can be defined. E.g. just 'p' for 'param'
function ldoc.alias (a,tag)
doc.add_alias(a,tag)
end
-- standard aliases --
ldoc.alias('tparam',{'param',modifiers={type="$1"}})
ldoc.alias('treturn',{'return',modifiers={type="$1"}})
ldoc.alias('tfield',{'field',modifiers={type="$1"}})
function ldoc.tparam_alias (name,type)
type = type or name
ldoc.alias(name,{'param',modifiers={type=type}})
end
ldoc.alias ('error',doc.error_macro)
ldoc.tparam_alias 'string'
ldoc.tparam_alias 'number'
ldoc.tparam_alias 'int'
ldoc.tparam_alias 'bool'
ldoc.tparam_alias 'func'
ldoc.tparam_alias 'tab'
ldoc.tparam_alias 'thread'
function ldoc.add_language_extension(ext, lang)
lang = (lang=='c' and cc) or (lang=='lua' and lua) or quit('unknown language')
if ext:sub(1,1) ~= '.' then ext = '.'..ext end
file_types[ext] = lang
end
function ldoc.add_section (name, title, subname)
ModuleMap:add_kind(name,title,subname)
end
-- new tags can be added, which can be on a project level.
function ldoc.new_type (tag, header, project_level,subfield)
doc.add_tag(tag,doc.TAG_TYPE,project_level)
if project_level then
ProjectMap:add_kind(tag,header,subfield)
else
ModuleMap:add_kind(tag,header,subfield)
end
end
function ldoc.manual_url (url)
global.set_manual_url(url)
end
function ldoc.custom_see_handler(pat, handler)
doc.add_custom_see_handler(pat, handler)
end
local ldoc_contents = {
'alias','add_language_extension','custom_tags','new_type','add_section', 'tparam_alias',
'file','project','title','package', 'icon','format','output','dir','ext', 'topics',
'one','style','template','description','examples', 'pretty', 'charset', 'plain',
'readme','all','manual_url', 'ignore', 'colon', 'sort', 'module_file','vars',
'boilerplate','merge', 'wrap', 'not_luadoc', 'template_escape','merge_error_groups',
'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
'no_space_before_args','parse_extra','no_lua_ref','sort_modules','use_markdown_titles',
'unqualified', 'custom_display_name_handler', 'kind_names', 'custom_references',
'dont_escape_underscore','global_lookup','prettify_files','convert_opt', 'user_keywords',
'postprocess_html',
'custom_css','version',
'no_args_infer',
'keep_menu_order'
}
ldoc_contents = tablex.makeset(ldoc_contents)
local function loadstr (ldoc,txt)
local chunk, err
-- Penlight's Lua 5.2 compatibility has wobbled over the years...
if not rawget(_G,'loadin') then -- Penlight 0.9.5
-- Penlight 0.9.7; no more global load() override
local load = load or utils.load
chunk,err = load(txt,'config',nil,ldoc)
else
-- luacheck: push ignore 113
chunk,err = loadin(ldoc,txt)
-- luacheck: pop
end
return chunk, err
end
-- any file called 'config.ld' found in the source tree will be
-- handled specially. It will be loaded using 'ldoc' as the environment.
local function read_ldoc_config (fname)
local directory = path.dirname(fname)
if directory == '' then
directory = '.'
end
local chunk, err, _
if args.filter == 'none' then
print('reading configuration from '..fname)
end
local txt,not_found = utils.readfile(fname)
if txt then
chunk, err = loadstr(ldoc,txt)
if chunk then
if args.define ~= 'none' then ldoc[args.define] = true end
_,err = pcall(chunk)
end
end
if err then quit('error loading config file '..fname..': '..err) end
for k in pairs(ldoc) do
if not ldoc_contents[k] then
quit("this config file field/function is unrecognized: "..k)
end
end
return directory, not_found
end
local quote = tools.quote
--- processing command line and preparing for output ---
local file_list = List()
File.list = file_list
local config_dir
local ldoc_dir = arg[0]:gsub('[^/\\]+$','')
local doc_path = ldoc_dir..'/ldoc/builtin/?.lua'
-- ldoc -m is expecting a Lua package; this converts this to a file path
if args.module then
-- first check if we've been given a global Lua lib function
if args.file:match '^%a+$' and global.functions[args.file] then
args.file = 'global.'..args.file
end
local fullpath,mod,_ = tools.lookup_existing_module_or_function (args.file, doc_path)
if not fullpath then
quit(mod)
else
args.file = fullpath
args.module = mod
end
end
local abspath = tools.abspath
-- a special case: 'ldoc .' can get all its parameters from config.ld
if args.file == '.' then
local err
config_dir,err = read_ldoc_config(args.config)
if err then quit("no "..quote(args.config).." found") end
local config_path = path.dirname(args.config)
if config_path ~= '' then
print('changing to directory',config_path)
lfs.chdir(config_path)
end
args.file = ldoc.file or '.'
if args.file == '.' then
args.file = lfs.currentdir()
elseif type(args.file) == 'table' then
for i,f in ipairs(args.file) do
args.file[i] = abspath(f)
end
else
args.file = abspath(args.file)
end
else
-- user-provided config file
if args.config ~= 'config.ld' then
local err
config_dir,err = read_ldoc_config(args.config)
if err then quit("no "..quote(args.config).." found") end
end
-- with user-provided file
if args.file == nil then
lapp.error('missing required parameter: file')
end
args.file = abspath(args.file)
end
if type(ldoc.custom_tags) == 'table' then -- custom tags
for i, custom in ipairs(ldoc.custom_tags) do
if type(custom) == 'string' then
custom = {custom}
ldoc.custom_tags[i] = custom
end
doc.add_tag(custom[1], 'ML')
end
end -- custom tags
local source_dir = args.file
if type(source_dir) == 'table' then
source_dir = source_dir[1]
end
if type(source_dir) == 'string' and path.isfile(source_dir) then
source_dir = path.splitpath(source_dir)
end
source_dir = source_dir:gsub('[/\\]%.$','')
---------- specifying the package for inferring module names --------
-- If you use module(...), or forget to explicitly use @module, then
-- ldoc has to infer the module name. There are three sensible values for
-- `args.package`:
--
-- * '.' the actual source is in an immediate subdir of the path given
-- * '..' the path given points to the source directory
-- * 'NAME' explicitly give the base module package name
--
override ('package','.')
local function setup_package_base()
if ldoc.package then args.package = ldoc.package end
if args.package == '.' then
args.package = source_dir
elseif args.package == '..' then
args.package = path.splitpath(source_dir)
elseif not args.package:find '[\\/]' then
local subdir,dir = path.splitpath(source_dir)
if dir == args.package then
args.package = subdir
elseif path.isdir(path.join(source_dir,args.package)) then
args.package = source_dir
else
quit("args.package is not the name of the source directory")
end
end
end
--------- processing files ---------------------
-- ldoc may be given a file, or a directory. `args.file` may also be specified in config.ld
-- where it is a list of files or directories. If specified on the command-line, we have
-- to find an optional associated config.ld, if not already loaded.
if ldoc.ignore then args.ignore = true end
local function process_file (f, flist)
local ext = path.extension(f)
local ftype = file_types[ext]
if ftype then
if args.verbose then print(f) end
ftype.extra = ldoc.parse_extra or {}
local F,err = parse.file(f,ftype,args)
if err then
if F then
F:warning("internal LDoc error")
end
quit(err)
end
flist:append(F)
end
end
local process_file_list = tools.process_file_list
setup_package_base()
override 'no_args_infer'
override 'colon'
override 'merge'
override 'not_luadoc'
override 'module_file'
override 'boilerplate'
override 'all'
setup_kinds()
-- LDoc is doing plain ole C, don't want random Lua references!
if ldoc.parse_extra and ldoc.parse_extra.C then
ldoc.no_lua_ref = true
end
if ldoc.merge_error_groups == nil then
ldoc.merge_error_groups = 'Error Message'
end
-- ldoc.module_file establishes a partial ordering where the
-- master module files are processed first.
local function reorder_module_file ()
if args.module_file then
local mf = {}
for mname, f in pairs(args.module_file) do
local fullpath = abspath(f)
mf[fullpath] = true
end
return function(x,y)
return mf[x] and not mf[y]
end
end
end
-- process files, optionally in order that respects master module files
local function process_all_files(files)
local sortfn = reorder_module_file()
local files = tools.expand_file_list(files,'*.*')
if sortfn then files:sort(sortfn) end
for f in files:iter() do
process_file(f, file_list)
end
if #file_list == 0 then quit "no source files found" end
end
if type(args.file) == 'table' then
-- this can only be set from config file so we can assume config is already read
process_all_files(args.file)
elseif path.isdir(args.file) then
-- use any configuration file we find, if not already specified
if not config_dir then
local files = List(dir.getallfiles(args.file,'*.*'))
local config_files = files:filter(function(f)
return path.basename(f) == args.config
end)
if #config_files > 0 then
config_dir = read_ldoc_config(config_files[1])
if #config_files > 1 then
print('warning: other config files found: '..config_files[2])
end
end
end
process_all_files({args.file})
elseif path.isfile(args.file) then
-- a single file may be accompanied by a config.ld in the same dir
if not config_dir then
config_dir = path.dirname(args.file)
if config_dir == '' then config_dir = '.' end
local config = path.join(config_dir,args.config)
if path.isfile(config) then
read_ldoc_config(config)
end
end
process_file(args.file, file_list)
if #file_list == 0 then quit "unsupported file extension" end
else
quit ("file or directory does not exist: "..quote(args.file))
end
-- create the function that renders text (descriptions and summaries)
-- (this also will initialize the code prettifier used)
override ('format','plain')
override 'pretty'
ldoc.markup = markup.create(ldoc, args.format, args.pretty, ldoc.user_keywords)
------ 'Special' Project-level entities ---------------------------------------
-- Examples and Topics do not contain code to be processed for doc comments.
-- Instead, they are intended to be rendered nicely as-is, whether as pretty-lua
-- or as Markdown text. Treating them as 'modules' does stretch the meaning of
-- of the term, but allows them to be treated much as modules or scripts.
-- They define an item 'body' field (containing the file's text) and a 'postprocess'
-- field which is used later to convert them into HTML. They may contain @{ref}s.
local function add_special_project_entity (f,tags,process)
local F = File(f)
tags.name = path.basename(f)
local text = utils.readfile(f)
local item = F:new_item(tags,1)
if process then
text = process(F, text)
end
F:finish()
file_list:append(F)
item.body = text
return item, F
end
local function prettify_source_files(files,class,linemap)
local prettify = require 'ldoc.prettify'
process_file_list (files, '*.*', function(f)
local ext = path.extension(f)
local ftype = file_types[ext]
if ftype then
local item = add_special_project_entity(f,{
class = class,
})
-- wrap prettify for this example so it knows which file to blame
-- if there's a problem
local lang = ext:sub(2)
item.postprocess = function(code)
return '<h2>'..path.basename(f)..'</h2>\n' ..
prettify.lua(lang,f,code,0,true,linemap and linemap[f])
end
end
end)
end
if type(ldoc.examples) == 'string' then
ldoc.examples = {ldoc.examples}
end
if type(ldoc.examples) == 'table' then
prettify_source_files(ldoc.examples,"example")
end
ldoc.is_file_prettified = {}
if ldoc.prettify_files then
local files = List()
local linemap = {}
for F in file_list:iter() do
files:append(F.filename)
local mod = F.modules[1]
if mod then
local ls = List()
for item in mod.items:iter() do
ls:append(item.lineno)
end
linemap[F.filename] = ls
end
end
if type(ldoc.prettify_files) == 'table' then
files = tools.expand_file_list(ldoc.prettify_files, '*.*')
elseif type(ldoc.prettify_files) == 'string' then
-- the gotcha is that if the person has a folder called 'show', only the contents
-- of that directory will be converted. So, we warn of this amibiguity
if ldoc.prettify_files == 'show' then
-- just fall through with all module files collected above
if path.exists 'show' then
print("Notice: if you only want to prettify files in `show`, then set prettify_files to `show/`")
end
else
files = tools.expand_file_list({ldoc.prettify_files}, '*.*')
end
end
ldoc.is_file_prettified = tablex.makeset(files)
prettify_source_files(files,"file",linemap)
end
if args.simple then
ldoc.no_return_or_parms=true
ldoc.no_summary=true
end
ldoc.readme = ldoc.readme or ldoc.topics
if type(ldoc.readme) == 'string' then
ldoc.readme = {ldoc.readme}
end
if type(ldoc.readme) == 'table' then
process_file_list(ldoc.readme, '*.md', function(f)
local item, F = add_special_project_entity(f,{
class = 'topic'
}, markup.add_sections)
-- add_sections above has created sections corresponding to the 2nd level
-- headers in the readme, which are attached to the File. So
-- we pass the File to the postprocesser, which will insert the section markers
-- and resolve inline @ references.
if ldoc.use_markdown_titles then
item.display_name = F.display_name
end
item.postprocess = function(txt) return ldoc.markup(txt,F) end
end)
end
-- extract modules from the file objects, resolve references and sort appropriately ---
local first_module
local project = ProjectMap()
local module_list = List()
module_list.by_name = {}
local modcount = 0
for F in file_list:iter() do
for mod in F.modules:iter() do
if not first_module then first_module = mod end
if doc.code_tag(mod.type) then modcount = modcount + 1 end
module_list:append(mod)
module_list.by_name[mod.name] = mod
end
end
local handle = io.open("output.xml", "w")
io.output(handle)
for mod in module_list:iter() do
mod:dumpToXML()
end
io.close(handle)
for mod in module_list:iter() do
if not args.module then -- no point if we're just showing docs on the console
mod:resolve_references(module_list)
end
project:add(mod,module_list)
end
if ldoc.sort_modules then
table.sort(module_list,function(m1,m2)
return m1.name < m2.name
end)
end
ldoc.single = modcount == 1 and first_module or nil
--do return end
-------- three ways to dump the object graph after processing -----
-- ldoc -m will give a quick & dirty dump of the module's documentation;
-- using -v will make it more verbose
if args.module then
if #module_list == 0 then quit("no modules found") end
if args.module == true then
file_list[1]:dump(args.verbose)
else
local M,name = module_list[1], args.module
local fun = M.items.by_name[name]
if not fun then
fun = M.items.by_name[M.mod_name..':'..name]
end
if not fun then quit(quote(name).." is not part of "..quote(args.file)) end
fun:dump(true)
end
return
end
-- ldoc --dump will do the same as -m, except for the currently specified files
if args.dump then
for mod in module_list:iter() do
mod:dump(true)
end
os.exit()
end
if args.tags ~= 'none' then
local tagset = {}
for t in stringx.split(args.tags,','):iter() do
tagset[t] = true
end
for mod in module_list:iter() do
mod:dump_tags(tagset)
end
os.exit()
end
-- ldoc --filter mod.name will load the module `mod` and pass the object graph
-- to the function `name`. As a special case --filter dump will use pl.pretty.dump.
if args.filter ~= 'none' then
doc.filter_objects_through_function(args.filter, module_list)
os.exit()
end
-- can specify format, output, dir and ext in config.ld
override ('output','index')
override ('dir','doc')
override ('ext','html')
override 'one'
-- handling styling and templates --
ldoc.css, ldoc.templ = 'ldoc.css','ldoc.ltp'
-- special case: user wants to generate a .md file from a .lua file
if args.ext == 'md' then
if #module_list ~= 1 then
quit("can currently only generate Markdown output from one module only")
end
if not ldoc.template or ldoc.template == '!' then
ldoc.template = '!md'
end
args.output = module_list[1].name
args.dir = '.'
ldoc.template_escape = '>'
ldoc.style = false
args.ext = '.md'
end
local function match_bang (s)
if type(s) ~= 'string' then return end
return s:match '^!(.*)'
end
local function style_dir (sname)
local style = ldoc[sname]
local dir
if style==false and sname == 'style' then
args.style = false
ldoc.css = false
end
if style then
if style == true then
dir = config_dir
elseif type(style) == 'string' and (path.isdir(style) or match_bang(style)) then
dir = style
else
quit(quote(tostring(style)).." is not a directory")
end
args[sname] = dir
end
end
-- the directories for template and stylesheet can be specified
-- either by command-line '--template','--style' arguments or by 'template and
-- 'style' fields in config.ld.
-- The assumption here is that if these variables are simply true then the directory
-- containing config.ld contains a ldoc.css and a ldoc.ltp respectively. Otherwise
-- they must be a valid subdirectory.
style_dir 'style'
style_dir 'template'
if not args.ext:find '^%.' then
args.ext = '.'..args.ext
end
if args.one then
ldoc.style = '!one'
end
local builtin_style, builtin_template = match_bang(args.style),match_bang(args.template)
if builtin_style or builtin_template then
-- '!' here means 'use built-in templates'
local user = path.expanduser('~'):gsub('[/\\: ]','_')
local tmpdir = path.join(path.is_windows and os.getenv('TMP') or (os.getenv('TMPDIR') or '/tmp'),'ldoc'..user)
if not path.isdir(tmpdir) then
lfs.mkdir(tmpdir)
end
local function tmpwrite (name)
local ok,text = pcall(require,'ldoc.html.'..name:gsub('%.','_'))
if not ok then
quit("cannot find builtin template "..name.." ("..text..")")
end
if not utils.writefile(path.join(tmpdir,name),text) then
quit("cannot write to temp directory "..tmpdir)
end
end
if builtin_style then
if builtin_style ~= '' then
ldoc.css = 'ldoc_'..builtin_style..'.css'
end
tmpwrite(ldoc.css)
args.style = tmpdir
end
if builtin_template then
if builtin_template ~= '' then
ldoc.templ = 'ldoc_'..builtin_template..'.ltp'
end
tmpwrite(ldoc.templ)
args.template = tmpdir
end
end
-- default icon to nil
if args.icon == 'none' then args.icon = nil end
ldoc.log = print
ldoc.kinds = project
ldoc.modules = module_list
ldoc.title = ldoc.title or args.title
ldoc.project = ldoc.project or args.project
ldoc.package = args.package:match '%a+' and args.package or nil
ldoc.icon = ldoc.icon or args.icon
local source_date_epoch = os.getenv("SOURCE_DATE_EPOCH")
if args.testing then
ldoc.updatetime = "2015-01-01 12:00:00"
ldoc.version = 'TESTING'
elseif source_date_epoch == nil then
if args.date == 'system' then
ldoc.updatetime = os.date("%Y-%m-%d %H:%M:%S")
else
ldoc.updatetime = args.date
end
else
ldoc.updatetime = os.date("!%Y-%m-%d %H:%M:%S",source_date_epoch)
end
local html = require 'ldoc.html'
html.generate_output(ldoc, args, project)
if args.verbose then
print 'modules'
for k in pairs(module_list.by_name) do print(k) end
end
if args.fatalwarnings and Item.had_warning then
os.exit(1)
end

3
Documentation/compiler/ldoc/ldoc/SciTE.properties Normal file
View file

@ -0,0 +1,3 @@
tabsize=3
indent.size=3
use.tabs=0

50
Documentation/compiler/ldoc/ldoc/builtin/coroutine.lua Normal file
View file

@ -0,0 +1,50 @@
--- creating and controlling coroutines.
-- @module coroutine
local coroutine = {}
---
-- Creates a new coroutine, with body `f`. `f` must be a Lua
-- function. Returns this new coroutine, an object with type `"thread"`.
function coroutine.create(f) end
---
-- Starts or continues the execution of coroutine `co`. The first time
-- you resume a coroutine, it starts running its body. The values
-- ... are passed as the arguments to the body function. If the coroutine
-- has yielded, `resume` restarts it; the values ... are passed
-- as the results from the yield.
-- If the coroutine runs without any errors, `resume` returns true plus any
-- values passed to `yield` (if the coroutine yields) or any values returned
-- by the body function (if the coroutine terminates). If there is any error,
-- `resume` returns false plus the error message.
function coroutine.resume(co , ...) end
---
-- Returns the running coroutine. Or nil when called by the main thread.
function coroutine.running() end
---
-- Returns the status of coroutine `co`. Result is a string: `"running"`, if
-- the coroutine is running (that is, it called `status`); `"suspended"`, if
-- the coroutine is suspended in a call to `yield`, or if it has not started
-- running yet; `"normal"` if the coroutine is active but not running (that
-- is, it has resumed another coroutine); and `"dead"` if the coroutine has
-- finished its body function, or if it has stopped with an error.
function coroutine.status(co) end
---
-- Creates a new coroutine, with body `f`. `f` must be a Lua
-- function. Returns a function that resumes the coroutine each time it is
-- called. Any arguments passed to the function behave as the extra arguments to
-- `resume`. Returns the same values returned by `resume`, except the first
-- boolean. In case of error, propagates the error.
function coroutine.wrap(f) end
---
-- Suspends the execution of the calling coroutine. The coroutine cannot
-- be running a C function, a metamethod, or an iterator. Any arguments to
-- `yield` are passed as extra results to `resume`.
function coroutine.yield(...) end
return coroutine

124
Documentation/compiler/ldoc/ldoc/builtin/debug.lua Normal file
View file

@ -0,0 +1,124 @@
--- getting runtime debug information.
-- @module debug
local debug = {}
---
-- Enters an interactive mode with the user, running each string that
-- the user enters. Using simple commands and other debug facilities,
-- the user can inspect global and local variables, change their values,
-- evaluate expressions, and so on. A line containing only the word `cont`
-- finishes this function, so that the caller continues its execution.
-- Note that commands for `debug.debug` are not lexically nested within any
-- function, and so have no direct access to local variables.
function debug.debug() end
---
-- Returns the environment of object `o`.
function debug.getfenv(o) end
---
-- Returns the current hook settings of the thread, as three values: the
-- current hook function, the current hook mask, and the current hook count
-- (as set by the `debug.sethook` function).
function debug.gethook(thread) end
---
-- Returns a table with information about a function. You can give the
-- function directly, or you can give a number as the value of `function`,
-- which means the function running at level `function` of the call stack
-- of the given thread: level 0 is the current function (`getinfo` itself);
-- level 1 is the function that called `getinfo`; and so on. If `function`
-- is a number larger than the number of active functions, then `getinfo`
-- returns nil.
--
-- `thread` and `what` are optional.
--
-- The returned table can contain all the fields returned by `lua_getinfo`,
-- with the string `what` describing which fields to fill in. The default for
-- `what` is to get all information available, except the table of valid
-- lines. If present, the option '`f`' adds a field named `func` with
-- the function itself. If present, the option '`L`' adds a field named
-- `activelines` with the table of valid lines.
-- For instance, the expression `debug.getinfo(1,"n").name` returns a table
-- with a name for the current function, if a reasonable name can be found,
-- and the expression `debug.getinfo(print)` returns a table with all available
-- information about the `print` function.
function debug.getinfo(thread, func , what) end
---
-- This function returns the name and the value of the local variable with
-- index `loc` of the function at level `level` of the stack. (The first
-- parameter or local variable has index 1, and so on, until the last active
-- local variable.) The function returns nil if there is no local variable
-- with the given index, and raises an error when called with a `level` out
-- of range. (You can call `debug.getinfo` to check whether the level is valid.)
-- Variable names starting with '`(`' (open parentheses) represent internal
-- variables (loop control variables, temporaries, and C function locals).
function debug.getlocal(thread, level, loc) end
---
-- Returns the metatable of the given `object` or nil if it does not have
-- a metatable.
function debug.getmetatable(object) end
---
-- Returns the registry table (see §3.5).
function debug.getregistry() end
---
-- This function returns the name and the value of the upvalue with index
-- `up` of the function `func`. The function returns nil if there is no
-- upvalue with the given index.
function debug.getupvalue(func, up) end
---
-- Sets the environment of the given `object` to the given `table`. Returns
-- `object`.
function debug.setfenv(object, table) end
---
-- Sets the given function as a hook. The string `mask` and the number
-- `count` describe when the hook will be called. The string mask may have
-- the following characters, with the given meaning:
--
-- * `"c"`: the hook is called every time Lua calls a function;
-- * `"r"`: the hook is called every time Lua returns from a function;
-- * `"l"`: the hook is called every time Lua enters a new line of code.
--
-- With a `count` different from zero, the hook is called after every `count`
-- instructions.
--
-- When called without arguments, `debug.sethook` turns off the hook.
--
-- When the hook is called, its first parameter is a string describing
-- the event that has triggered its call: `"call"`, `"return"` (or `"tail
-- return"`, when simulating a return from a tail call), `"line"`, and
-- `"count"`. For line events, the hook also gets the new line number as its
-- second parameter. Inside a hook, you can call `getinfo` with level 2 to
-- get more information about the running function (level 0 is the `getinfo`
-- function, and level 1 is the hook function), unless the event is `"tail
-- return"`. In this case, Lua is only simulating the return, and a call to
-- `getinfo` will return invalid data.
function debug.sethook(thread, hook, mask , count) end
---
-- This function assigns the value `value` to the local variable with
-- index `loc` of the function at level `level` of the stack. The function
-- returns nil if there is no local variable with the given index, and raises
-- an error when called with a `level` out of range. (You can call `getinfo`
-- to check whether the level is valid.) Otherwise, it returns the name of
-- the local variable.
function debug.setlocal(thread, level, loc, value) end
---
-- Sets the metatable for the given `object` to the given `table` (which
-- can be nil).
function debug.setmetatable(object, table) end
---
-- This function assigns the value `value` to the upvalue with index `up`
-- of the function `func`. The function returns nil if there is no upvalue
-- with the given index. Otherwise, it returns the name of the upvalue.
function debug.setupvalue(func, up, value) end
return debug

243
Documentation/compiler/ldoc/ldoc/builtin/global.lua Normal file
View file

@ -0,0 +1,243 @@
--- Lua global functions.
module 'global'
-- luacheck: ignore 121
---
-- Issues an error when its argument `v` is false.
-- That is, nil or false. otherwise, returns all its arguments.
-- `message` is an error when absent, it defaults to "assertion failed!"
function assert(v , message) end
---
-- This function is a generic interface to the garbage collector. It
-- performs different functions according to its first argument, `opt`:
--
-- * "stop": stops the garbage collector.
-- * "restart": restarts the garbage collector.
-- * "collect": performs a full garbage-collection cycle.
-- * "count": returns the total memory in use by Lua (in Kbytes).
-- * "step": performs a garbage-collection step. The step "size" is controlled
-- by `arg` (larger values mean more steps) in a non-specified way. If you
-- want to control the step size you must experimentally tune the value of
-- * "arg". Returns true if the step finished a collection cycle.
-- * "setpause": sets `arg` as the new value for the *pause* of the collector
-- (see 2.10). Returns the previous value for *pause*.
-- * "setstepmul": sets `arg` as the new value for the *step multiplier*
-- of the collector (see 2.10). Returns the previous value for *step*.
--
function collectgarbage(opt , arg) end
---
-- Opens the named file and executes its contents as a Lua chunk. When
-- called without arguments,
-- `dofile` executes the contents of the standard input (`stdin`). Returns
-- all values returned by the chunk. In case of errors, `dofile` propagates
-- the error to its caller (that is, `dofile` does not run in protected mode).
function dofile(filename) end
---
-- Terminates the last protected function called.
-- Returns `message` as the error message.
-- Function `error` never returns.
-- Usually, `error` adds some information about the error position at the
-- beginning of the message. The `level` argument specifies how to get the
-- error position. With level 1 (the default), the error position is where the
-- `error` function was called. Level 2 points the error to where the function
-- that called `error` was called; and so on. Passing a level 0 avoids the
-- addition of error position information to the message.
function error(message , level) end
---
-- A global variable (not a function) that holds the global environment
-- (that is, `_G._G = _G`). Lua itself does not use this variable; changing
-- its value does not affect any environment, nor vice-versa. (Set `__ENV`
-- to change environments in functions)
-- @table _G
---
-- If `object` does not have a metatable, returns nil. Otherwise, if the
-- object's metatable has a `"__metatable"` field, returns the associated
-- value. Otherwise, returns the metatable of the given object.
function getmetatable(object) end
---
-- For iterating over sequences. Returns three values: an iterator function, the table `t`, and 0,
-- so that the construction
-- for i,v in ipairs(t) do *body* end
-- will iterate over the pairs (`1,t[1]`), (`2,t[2]`), ..., up to the
-- first integer key absent from the table.
function ipairs(t) end
---
-- Loads a chunk.
-- If `ld` is a string, the chunk is this string.
-- If `ld` is a function, load calls it repeatedly to get the chunk pieces. Each call to `ld` must return a
-- string that concatenates with previous results. A return of an empty string, nil, or no value
-- signals the end of the chunk.
-- If there are no syntactic errors, returns the compiled chunk as a function;
-- otherwise, returns nil plus the error message.
-- If the resulting function has upvalues, the first upvalue is set to the value of the global environment or to `env`,
-- if that parameter is given. When loading main chunks, the first upvalue will be the`_ENV` variable (see 2.2).
-- `source` is used as the source of the chunk for error messages and debug information (see 4.9).
-- When absent, it defaults to `ld`, if `ld` is a string, or to "=(load)" otherwise.
-- The string `mode` controls whether the chunk can be text or binary (that is, a precompiled chunk).
-- It may be the string "b" (only binary chunks), "t" (only text chunks), or "bt" (both binary and text).
-- The default is "bt"
function load (ld , source , mode , env) end
---
-- Similar to `load`, but gets the chunk from file `filename`. Or from the
-- standard input, if no file name is given.
function loadfile (filename , mode , env) end
---
-- Allows a program to traverse all fields of a table. Its first argument is
-- a table and its second argument is an index in this table. `next` returns
-- the next index of the table and its associated value.
--
-- When called with nil
-- as its second argument, `next` returns an initial index and its associated
-- value. When called with the last index, or with nil in an empty table, `next`
-- returns nil.
--
-- If the second argument is absent, then it is interpreted as
-- nil. In particular, you can use `next(t)` to check whether a table is empty.
-- The order in which the indices are enumerated is not specified, *even for
-- numeric indices*. (To traverse a table in numeric order, use a numerical
-- for or the `ipairs` function.)
--
-- The behavior of `next` is *undefined* if, during the traversal, you assign
-- any value to a non-existent field in the table. You may however modify
-- existing fields. In particular, you may clear existing fields.
function next(table , index) end
---
-- For iterating over all key-value pairs of a table.
-- Returns three values: the `next` function, the table `t`, and nil,
-- so that the construction
-- for k,v in pairs(t) do *body* end
-- will iterate over all key-value pairs of table `t`.
-- See function `next` for the caveats of modifying the table during its
-- traversal.
function pairs(t) end
---
-- Calls function `f` with the given arguments in *protected mode*. This
-- means that any error inside `f` is not propagated; instead, `pcall` catches
-- the error and returns a status code. Its first result is the status code (a
-- boolean), which is true if the call succeeds without errors. In such case,
-- `pcall` also returns all results from the call, after this first result. In
-- case of any error, `pcall` returns false plus the error message.
function pcall(f, arg1, ...) end
---
--Prints any number of values to `stdout`.
-- Uses the `tostring` function to convert them to strings. `print` is not
-- intended for formatted output, but only as a quick way to show a value,
-- typically for debugging. For formatted output, use `string.format`.
function print(...) end
---
-- Checks whether `v1` is equal to `v2`. Does not invoke any
-- metamethod. Returns a boolean.
function rawequal(v1, v2) end
---
-- Gets the real value of `table[index]`. Does not invoke any
-- metamethod. `table` must be a table; `index` may be any value.
function rawget(table, index) end
---
-- Sets the real value of `table[index]` to `value`. Does not invoke any
-- metamethod. `table` must be a table, `index` any value different from nil,
-- and `value` any Lua value.
-- This function returns `table`.
function rawset(table, index, value) end
---
-- Returns all arguments after argument number
-- `index`. Otherwise, `index` must be the string `"#"`, and `select` returns
-- the total number of extra arguments it received.
function select(index, ...) end
---
-- Sets the metatable for the given table. (You cannot change the metatable
-- of other types from Lua, only from C.) If `metatable` is nil, removes the
-- metatable of the given table. If the original metatable has a `"__metatable"`
-- field, raises an error.
-- This function returns `table`.
function setmetatable(table, metatable) end
---
-- Tries to convert its argument to a number. If the argument is already
-- a number or a string convertible to a number, then `tonumber` returns this
-- number; otherwise, it returns nil.
-- An optional argument specifies the base to interpret the numeral. The base
-- may be any integer between 2 and 36, inclusive. In bases above 10, the
-- letter '`A`' (in either upper or lower case) represents 10, '`B`' represents
-- 11, and so forth, with '`Z`' representing 35. In base 10 (the default),
-- the number can have a decimal part, as well as an optional exponent part
-- (see 2.1). In other bases, only unsigned integers are accepted.
function tonumber(e , base) end
---
-- Converts any value to a string in a reasonable format.
-- For complete control of how numbers are converted, use `string.format`.
-- If the metatable of `e` has a `"__tostring"` field, then `tostring` calls
-- the corresponding value with `e` as argument, and uses the result of the
-- call as its result.
function tostring(e) end
---
-- Returns the type of its only argument, coded as a string. The possible
-- results of this function are "
-- `nil`" (a string, not the value nil), "`number`", "`string`", "`boolean`",
-- "`table`", "`function`", "`thread`", and "`userdata`".
function type(v) end
---
-- A global variable (not a function) that holds a string containing the
-- current interpreter version. The current contents of this variable is
-- "`Lua 5.1`".
-- @table _VERSION
---
-- This function is similar to `pcall`, except that you can set a new
-- error handler.
-- `xpcall` calls function `f` in protected mode, using `err` as the error
-- handler. Any error inside `f` is not propagated; instead, `xpcall` catches
-- the error, calls the `err` function with the original error object, and
-- returns a status code. Its first result is the status code (a boolean),
-- which is true if the call succeeds without errors. In this case, `xpcall`
-- also returns all results from the call, after this first result. In case
-- of any error, `xpcall` returns false plus the result from `err`.
function xpcall(f, err) end
---
-- Loads the given module. The function starts by looking into the
-- `package.loaded` table to determine whether `modname` is already
-- loaded. If it is, then `require` returns the value stored at
-- `package.loaded[modname]`. Otherwise, it tries to find a *loader* for
-- the module.
-- To find a loader, `require` is guided by the `package.loaders` array. By
-- changing this array, we can change how `require` looks for a module. The
-- following explanation is based on the default configuration for
-- `package.loaders`.
-- First `require` queries `package.preload[modname]`. If it has a value,
-- this value (which should be a function) is the loader. Otherwise `require`
-- searches for a Lua loader using the path stored in `package.path`. If
-- that also fails, it searches for a C loader using the path stored in
-- `package.cpath`. If that also fails, it tries an *all-in-one* loader (see
-- `package.loaders`).
-- Once a loader is found, `require` calls the loader with a single argument,
-- `modname`. If the loader returns any value, `require` assigns the returned
-- value to `package.loaded[modname]`. If the loader returns no value and
-- has not assigned any value to `package.loaded[modname]`, then `require`
-- assigns true to this entry. In any case, `require` returns the final value
-- of `package.loaded[modname]`.
-- If there is any error loading or running the module, or if it cannot find
-- any loader for the module, then `require` signals an error.
function require(modname) end

186
Documentation/compiler/ldoc/ldoc/builtin/globals.lua Normal file
View file

@ -0,0 +1,186 @@
-------
-- global functions and tables
local tools = require 'ldoc.tools'
local globals = {}
local lua52 = _VERSION:match '5.2'
local lua53 = _VERSION:match '5.3'
local lua54 = _VERSION:match '5.4'
globals.functions = {
assert = true,
collectgarbage = true,
dofile = true,
error = true,
getmetatable = true,
setmetatable = true,
pairs = true,
ipairs = true,
load = true,
loadfile = true,
loadstring = true,
next = true,
pcall = true,
print = true,
rawequal = true,
rawget = true,
rawset = true,
select = true,
tonumber = true,
tostring = true,
type = true,
xpcall = true,
module = true,
require = true,
}
local functions = globals.functions
if lua54 then
functions.warn = true
functions.rawlen = true
elseif lua52 or lua53 then
functions.rawlen = true
else
functions.setfenv = true
functions.getfenv = true
functions.unpack = true
end
local manual, fun_ref
function globals.set_manual_url(url)
manual = url .. '#'
fun_ref = manual..'pdf-'
end
if lua54 then
globals.tables = {
io = '6.8',
package = '6.3',
math = '6.7',
os = '6.9',
string = '6.4',
table = '6.6',
coroutine = '6.2',
debug = '6.10'
}
globals.set_manual_url 'https://www.lua.org/manual/5.4/manual.html'
elseif lua53 then
globals.tables = {
io = '6.8',
package = '6.3',
math = '6.7',
os = '6.9',
string = '6.4',
table = '6.6',
coroutine = '6.2',
debug = '6.10'
}
globals.set_manual_url 'https://www.lua.org/manual/5.3/manual.html'
elseif lua52 then
globals.tables = {
io = '6.8',
package = '6.3',
math = '6.6',
os = '6.9',
string = '6.4',
table = '6.5',
coroutine = '6.2',
debug = '6.10'
}
globals.set_manual_url 'https://www.lua.org/manual/5.2/manual.html'
else
globals.tables = {
io = '5.7',
package = '5.3',
math = '5.6',
os = '5.8',
string = '5.4',
table = '5.5',
coroutine = '5.2',
debug = '5.9'
}
globals.set_manual_url 'https://www.lua.org/manual/5.1/manual.html'
end
local file_methods = {
close = true,
flush = true,
lines = true,
read = true,
seek = true,
setvbuf = true,
write = true,
}
-- external libs tracked by LDoc using LDoc style
local xlibs = {
lfs='lfs.html', lpeg='lpeg.html',
}
local xlib_url = 'http://stevedonovan.github.io/lua-stdlibs/modules/'
local tables = globals.tables
local function function_ref (name,tbl)
local href
if not tbl then -- can only be a standard Lua global function
if globals.functions[name] then
return {href = fun_ref..name, label = name}
else
return nil
end
end
if tbl == 'file' then -- special case: file objects!
if not file_methods[name] then
return nil
end
name = 'file:'..name
href = fun_ref..name
elseif tables[tbl] then -- function inside standard Lua table
local t = rawget(_G,tbl) -- do a quick sanity check
if not rawget(t,name) then
return nil
end
name = tbl..'.'..name
href = fun_ref..name
elseif xlibs[tbl] then -- in external libs, use LDoc style
local t = require('ldoc.builtin.'..tbl)
if not rawget(t,name) then
return nil
end
href = xlib_url..xlibs[tbl]..'#'..name
name = tbl..'.'..name
else
return nil
end
return {href = href, label = name}
end
local function module_ref (tbl)
local href
if tables[tbl] ~= nil then -- standard Lua table
href = manual..tables[tbl]
elseif xlibs[tbl] then -- external lib
href = xlib_url..xlibs[tbl]
else
return nil
end
return {href = href, label = tbl}
end
function globals.lua_manual_ref (name)
local tbl,fname = tools.split_dotted_name(name)
local ref
if not tbl then -- plain symbol
ref = function_ref(name)
if ref then return ref end
ref = module_ref(name)
if ref then return ref end
else
ref = function_ref(fname,tbl)
if ref then return ref end
end
return nil
end
return globals

162
Documentation/compiler/ldoc/ldoc/builtin/io.lua Normal file
View file

@ -0,0 +1,162 @@
--- Reading and Writing Files.
-- @module io
local io = {}
-- luacheck: ignore 241
local file = {}
---
-- Equivalent to `file:close()`. Without a `file`, closes the default
-- output file.
function io.close(file) end
---
-- Equivalent to `file:flush` over the default output file.
function io.flush() end
---
-- When called with a file name, it opens the named file (in text mode),
-- and sets its handle as the default input file. When called with a file
-- handle, it simply sets this file handle as the default input file. When
-- called without parameters, it returns the current default input file.
-- In case of errors this function raises the error, instead of returning an
-- error code.
function io.input(file) end
---
-- Opens the given file name in read mode and returns an iterator function
-- that, each time it is called, returns a new line from the file. Therefore,
-- the construction
-- for line in io.lines(filename) do *body* end
-- will iterate over all lines of the file. When the iterator function detects
-- the end of file, it returns nil (to finish the loop) and automatically
-- closes the file.
-- The call `io.lines()` (with no file name) is equivalent to
-- `io.input():lines()`; that is, it iterates over the lines of the default
-- input file. In this case it does not close the file when the loop ends.
function io.lines(filename) end
---
-- This function opens a file, in the mode specified in the string `mode`. It
-- returns a new file handle, or, in case of errors, nil plus an error message.
-- The `mode` string can be any of the following:
-- "r": read mode (the default);
-- "w": write mode;
-- "a": append mode;
-- "r+": update mode, all previous data is preserved;
-- "w+": update mode, all previous data is erased;
-- "a+": append update mode, previous data is preserved, writing is only
-- allowed at the end of file.
-- The `mode` string can also have a '`b`' at the end, which is needed in
-- some systems to open the file in binary mode. This string is exactly what
-- is used in the standard C function `fopen`.
function io.open(filename , mode) end
---
-- Similar to `io.input`, but operates over the default output file.
function io.output(file) end
---
-- Starts program `prog` in a separated process and returns a file handle
-- that you can use to read data from this program (if `mode` is `"r"`,
-- the default) or to write data to this program (if `mode` is `"w"`).
-- This function is system dependent and is not available on all platforms.
function io.popen(prog , mode) end
---
-- Equivalent to `io.input():read`.
function io.read(...) end
-- * `io.stderr`: Standard error.
-- * `io.stdin`: Standard in.
-- * `io.stdout`: Standard out.
---
-- Returns a handle for a temporary file. This file is opened in update
-- mode and it is automatically removed when the program ends.
function io.tmpfile() end
---
-- Checks whether `obj` is a valid file handle. Returns the string `"file"`
-- if `obj` is an open file handle, `"closed file"` if `obj` is a closed file
-- handle, or nil if `obj` is not a file handle.
function io.type(obj) end
---
-- Equivalent to `io.output():write`.
function io.write(...) end
---
-- Closes `file`. Note that files are automatically closed when their
-- handles are garbage collected, but that takes an unpredictable amount of
-- time to happen.
function file:close() end
---
-- Saves any written data to `file`.
function file:flush() end
---
-- Returns an iterator function that, each time it is called, returns a
-- new line from the file. Therefore, the construction
-- for line in file:lines() do *body* end
-- will iterate over all lines of the file. (Unlike `io.lines`, this function
-- does not close the file when the loop ends.)
function file:lines() end
---
-- Reads the file `file`, according to the given formats, which specify
-- what to read. For each format, the function returns a string (or a number)
-- with the characters read, or nil if it cannot read data with the specified
-- format. When called without formats, it uses a default format that reads
-- the entire next line (see below).
-- The available formats are
-- "*n": reads a number; this is the only format that returns a number
-- instead of a string.
-- "*a": reads the whole file, starting at the current position. On end of
-- file, it returns the empty string.
-- "*l": reads the next line (skipping the end of line), returning nil on
-- end of file. This is the default format.
-- *number*: reads a string with up to this number of characters, returning
-- nil on end of file. If number is zero, it reads nothing and returns an
-- empty string, or nil on end of file.
function file:read(...) end
---
-- Sets and gets the file position, measured from the beginning of the
-- file, to the position given by `offset` plus a base specified by the string
-- `whence`, as follows:
-- "set": base is position 0 (beginning of the file);
-- "cur": base is current position;
-- "end": base is end of file;
-- In case of success, function `seek` returns the final file position,
-- measured in bytes from the beginning of the file. If this function fails,
-- it returns nil, plus a string describing the error.
-- The default value for `whence` is `"cur"`, and for `offset` is 0. Therefore,
-- the call `file:seek()` returns the current file position, without changing
-- it; the call `file:seek("set")` sets the position to the beginning of the
-- file (and returns 0); and the call `file:seek("end")` sets the position
-- to the end of the file, and returns its size.
function file:seek(whence , offset) end
---
-- Sets the buffering mode for an output file. There are three available
-- modes:
--
-- * "no": no buffering; the result of any output operation appears immediately.
-- * "full": full buffering; output operation is performed only when the
-- buffer is full (or when you explicitly `flush` the file (see `io.flush`)).
-- * "line": line buffering; output is buffered until a newline is output or
-- there is any input from some special files (such as a terminal device).
-- For the last two cases, `size` specifies the size of the buffer, in
-- bytes. The default is an appropriate size.
function file:setvbuf(mode , size) end
---
-- Writes the value of each of its arguments to the `file`. The arguments
-- must be strings or numbers. To write other values, use `tostring` or
-- `string.format` before `write`.
function file:write(...) end
return io

125
Documentation/compiler/ldoc/ldoc/builtin/lfs.lua Normal file
View file

@ -0,0 +1,125 @@
--- File and Directory manipulation
-- @module lfs
local lfs = {}
---
-- Returns a table with the file attributes corresponding to filepath (or nil
-- followed by an error message in case of error). If the second optional
-- argument is given, then only the value of the named attribute is returned
-- (this use is equivalent to lfs.attributes(filepath).aname, but the table is
-- not created and only one attribute is retrieved from the O.S.). The
-- attributes are described as follows; attribute mode is a string, all the
-- others are numbers, and the time related attributes use the same time
-- reference of os.time:
--
-- - dev: on Unix systems, this represents the device that the inode resides on.
-- On Windows systems, represents the drive number of the disk containing
-- the file
-- - ino: on Unix systems, this represents the inode number. On Windows systems
-- this has no meaning
-- - mode: string representing the associated protection mode (the values could
-- be file, directory, link, socket, named pipe, char device, block
-- device or other)
-- - nlink: number of hard links to the file
-- - uid: user-id of owner (Unix only, always 0 on Windows)
-- - gid: group-id of owner (Unix only, always 0 on Windows)
-- - rdev: on Unix systems, represents the device type, for special file inodes.
-- On Windows systems represents the same as dev
-- - access: time of last access
-- - modification: time of last data modification
-- - change: time of last file status change
-- - size: file size, in bytes
-- - blocks: block allocated for file; (Unix only)
-- - blksize: optimal file system I/O blocksize; (Unix only)
-- This function uses stat internally thus if the given filepath is a symbolic
-- link, it is followed (if it points to another link the chain is followed
-- recursively) and the information is about the file it refers to. To obtain
-- information about the link itself, see function lfs.symlinkattributes.
function lfs.attributes(filepath , aname) end
---
-- Changes the current working directory to the given path.
-- Returns true in case of success or nil plus an error string.
function lfs.chdir(path) end
---
-- Creates a lockfile (called lockfile.lfs) in path if it does not exist and
-- returns the lock. If the lock already exists checks it it's stale, using the
-- second parameter (default for the second parameter is INT_MAX, which in
-- practice means the lock will never be stale. To free the the lock call
-- lock:free().
-- In case of any errors it returns nil and the error message. In particular,
-- if the lock exists and is not stale it returns the "File exists" message.
function lfs.lock_dir(path, seconds_stale) end
---
-- Returns a string with the current working directory or nil plus an error
-- string.
function lfs.currentdir() end
---
-- Lua iterator over the entries of a given directory. Each time the iterator is
-- called with dir_obj it returns a directory entry's name as a string, or nil
-- if there are no more entries. You can also iterate by calling `dir_obj:next()`,
-- and explicitly close the directory before the iteration finished with
-- `dir_obj:close()`. Raises an error if path is not a directory.
function lfs.dir(path) end
---
-- Locks a file or a part of it. This function works on open files; the file
-- handle should be specified as the first argument. The string mode could be
-- either r (for a read/shared lock) or w (for a write/exclusive lock). The
-- optional arguments start and length can be used to specify a starting point
-- and its length; both should be numbers.
-- Returns true if the operation was successful; in case of error, it returns
-- nil plus an error string.
function lfs.lock(filehandle, mode, start, length) end
---
-- Creates a new directory. The argument is the name of the new directory.
-- Returns true if the operation was successful; in case of error, it returns
-- nil plus an error string.
function lfs.mkdir(dirname) end
---
-- Removes an existing directory. The argument is the name of the directory.
-- Returns true if the operation was successful; in case of error, it returns
-- nil plus an error string.
function lfs.rmdir(dirname) end
---
-- Sets the writing mode for a file. The mode string can be either binary or
-- text. Returns the previous mode string for the file. This function is only
-- available in Windows, so you may want to make sure that lfs.setmode exists
-- before using it.
function lfs.setmode(file, mode) end
---
-- Identical to lfs.attributes except that it obtains information about the link
-- itself (not the file it refers to). This function is not available in Windows
-- so you may want to make sure that lfs.symlinkattributes exists before using
-- it.
function lfs.symlinkattributes(filepath , aname) end
---
-- Set access and modification times of a file. This function is a bind to utime
-- function. The first argument is the filename, the second argument (atime) is
-- the access time, and the third argument (mtime) is the modification time.
-- Both times are provided in seconds (which should be generated with Lua
-- standard function os.time). If the modification time is omitted, the access
-- time provided is used; if both times are omitted, the current time is used.
-- Returns true if the operation was successful; in case of error, it returns
-- nil plus an error string.
function lfs.touch(filepath , atime , mtime) end
---
-- Unlocks a file or a part of it. This function works on open files; the file
-- handle should be specified as the first argument. The optional arguments
-- start and length can be used to specify a starting point and its length; both
-- should be numbers.
-- Returns true if the operation was successful; in case of error, it returns
-- nil plus an error string.
function lfs.unlock(filehandle, start, length) end
return lfs

214
Documentation/compiler/ldoc/ldoc/builtin/lpeg.lua Normal file
View file

@ -0,0 +1,214 @@
--- LPeg PEG pattern matching.
-- @module lpeg
local lpeg = {}
---
-- The matching function. It attempts to match the given pattern against the
-- subject string. If the match succeeds, returns the index in the subject of
-- the first character after the match, or the captured values (if the pattern
-- captured any value).
--
-- An optional numeric argument init makes the match starts at that position in
-- the subject string. As usual in Lua libraries, a negative value counts from
-- the end.
--
-- Unlike typical pattern-matching functions, match works only in anchored mode;
-- that is, it tries to match the pattern with a prefix of the given subject
-- string (at position init), not with an arbitrary substring of the subject.
-- So, if we want to find a pattern anywhere in a string, we must either write a
-- loop in Lua or write a pattern that matches anywhere. This second approach is
-- easy and quite efficient; see examples.
function lpeg.match(pattern, subject , init) end
---
-- If the given value is a pattern, returns the string "pattern". Otherwise
-- returns nil.
function lpeg.type(value) end
---
-- Returns a string with the running version of LPeg.
function lpeg.version() end
---
-- Sets the maximum size for the backtrack stack used by LPeg to track calls and
-- choices. Most well-written patterns need little backtrack levels and
-- therefore you seldom need to change this maximum; but a few useful patterns
-- may need more space. Before changing this maximum you should try to rewrite
-- your pattern to avoid the need for extra space.
function lpeg.setmaxstack(max) end
---
-- Converts the given value into a proper pattern, according to the following
-- rules:
-- * If the argument is a pattern, it is returned unmodified.
-- * If the argument is a string, it is translated to a pattern that matches
-- literally the string.
-- * If the argument is a non-negative number n, the result is a pattern that
-- matches exactly n characters.
-- * If the argument is a negative number -n, the result is a pattern that
-- succeeds only if the input string does not have n characters: lpeg.P(-n)
-- is equivalent to -lpeg.P(n) (see the unary minus operation).
-- * If the argument is a boolean, the result is a pattern that always
-- succeeds or always fails (according to the boolean value), without
-- consuming any input.
-- * If the argument is a table, it is interpreted as a grammar (see
-- Grammars).
-- * If the argument is a function, returns a pattern equivalent to a
-- match-time capture over the empty string.
function lpeg.P(value) end
---
-- Returns a pattern that matches any single character belonging to one of the
-- given ranges. Each range is a string xy of length 2, representing all
-- characters with code between the codes of x and y (both inclusive).
-- As an example, the pattern `lpeg.R("09")` matches any digit, and `lpeg.R("az",
-- "AZ")` matches any ASCII letter.
function lpeg.R(range) end
---
-- Returns a pattern that matches any single character that appears in the given
-- string. (The S stands for Set.)
-- As an example, the pattern lpeg.S("+-*/") matches any arithmetic operator.
-- Note that, if s is a character (that is, a string of length 1), then
-- lpeg.P(s) is equivalent to lpeg.S(s) which is equivalent to lpeg.R(s..s).
-- Note also that both lpeg.S("") and lpeg.R() are patterns that always fail.
function lpeg.S(string) end
---
-- This operation creates a non-terminal (a variable) for a grammar. The created
-- non-terminal refers to the rule indexed by v in the enclosing grammar. (See
-- Grammars for details.)
function lpeg.V(v) end
---
-- Returns a table with patterns for matching some character classes according
-- to the current locale. The table has fields:
--
-- * alnum
-- * alpha
-- * cntrl
-- * digit
-- * graph
-- * lower
-- * print
-- * punct
-- * space
-- * upper
-- * xdigit
--
-- each one containing a
-- correspondent pattern. Each pattern matches any single character that belongs
-- to its class.
--
-- If called with an argument table, then it creates those fields inside the
-- given table and returns that table.
function lpeg.locale(table) end
---
-- Creates a simple capture, which captures the substring of the subject that
-- matches patt. The captured value is a string. If patt has other captures,
-- their values are returned after this one.
function lpeg.C(patt) end
---
-- Creates an argument capture. This pattern matches the empty string and
-- produces the value given as the nth extra argument given in the call to
-- lpeg.match.
function lpeg.Carg(n) end
---
-- Creates a back capture. This pattern matches the empty string and produces
-- the values produced by the most recent group capture named name.
-- Most recent means the last complete outermost group capture with the given
-- name. A Complete capture means that the entire pattern corresponding to the
-- capture has matched. An Outermost capture means that the capture is not
-- inside another complete capture.
function lpeg.Cb(name) end
---
-- Creates a constant capture. This pattern matches the empty string and
-- produces all given values as its captured values.
function lpeg.Cc(...) end
---
-- Creates a fold capture. If patt produces a list of captures C1 C2 ... Cn,
-- this capture will produce the value func(...func(func(C1, C2), C3)..., Cn),
-- that is, it will fold (or accumulate, or reduce) the captures from patt using
-- function func.
--
-- This capture assumes that patt should produce at least one capture with at
-- least one value (of any type), which becomes the initial value of an
-- accumulator. (If you need a specific initial value, you may prefix a constant
-- capture to patt.) For each subsequent capture LPeg calls func with this
-- accumulator as the first argument and all values produced by the capture as
-- extra arguments; the value returned by this call becomes the new value for
-- the accumulator. The final value of the accumulator becomes the captured
-- value.
--
-- As an example, the following pattern matches a list of numbers separated by
-- commas and returns their addition:
--
-- -- matches a numeral and captures its value
-- number = lpeg.R"09"^1 / tonumber
-- -- matches a list of numbers, captures their values
-- list = number * ("," * number)^0
-- -- auxiliary function to add two numbers
-- function add (acc, newvalue) return acc + newvalue end
-- -- folds the list of numbers adding them
-- sum = lpeg.Cf(list, add)
-- -- example of use
-- print(sum:match("10,30,43")) --> 83
--
function lpeg.Cf(patt, func) end
---
-- Creates a group capture. It groups all values returned by patt into a single
-- capture. The group may be anonymous (if no name is given) or named with the
-- given name.
-- An anonymous group serves to join values from several captures into a single
-- capture. A named group has a different behavior. In most situations, a named
-- group returns no values at all. Its values are only relevant for a following
-- back capture or when used inside a table capture.
function lpeg.Cg(patt , name) end
---
-- Creates a position capture. It matches the empty string and captures the
-- position in the subject where the match occurs. The captured value is a
-- number.
function lpeg.Cp() end
---
-- Creates a substitution capture, which captures the substring of the subject
-- that matches patt, with substitutions. For any capture inside patt with a
-- value, the substring that matched the capture is replaced by the capture
-- value (which should be a string). The final captured value is the string
-- resulting from all replacements.
function lpeg.Cs(patt) end
---
-- Creates a table capture. This capture creates a table and puts all values
-- from all anonymous captures made by patt inside this table in successive
-- integer keys, starting at 1. Moreover, for each named capture group created
-- by patt, the first value of the group is put into the table with the group
-- name as its key. The captured value is only the table.
function lpeg.Ct(patt) end
---
-- Creates a match-time capture. Unlike all other captures, this one is
-- evaluated immediately when a match occurs. It forces the immediate evaluation
-- of all its nested captures and then calls func.
-- The given function gets as arguments the entire subject, the current position
-- (after the match of patt), plus any capture values produced by patt.
-- The first value returned by function defines how the match happens. If the
-- call returns a number, the match succeeds and the returned number becomes the
-- new current position. (Assuming a subject s and current position i, the
-- returned number must be in the range [i, len(s) + 1].) If the call returns
-- true, the match succeeds without consuming any input. (So, to return true is
-- equivalent to return i.) If the call returns false, nil, or no value, the
-- match fails.
-- Any extra values returned by the function become the values produced by the
-- capture.
function lpeg.Cmt(patt, func) end
return lpeg

144
Documentation/compiler/ldoc/ldoc/builtin/math.lua Normal file
View file

@ -0,0 +1,144 @@
--- standard mathematical functions.
-- @module math
local math = {}
---
-- Returns the absolute value of `x`.
function math.abs(x) end
---
-- Returns the arc cosine of `x` (in radians).
function math.acos(x) end
---
-- Returns the arc sine of `x` (in radians).
function math.asin(x) end
---
-- Returns the arc tangent of `x` (in radians).
function math.atan(x) end
---
-- Returns the arc tangent of `y/x` (in radians), but uses the signs
-- of both parameters to find the quadrant of the result. (It also handles
-- correctly the case of `x` being zero.)
function math.atan2(y, x) end
---
-- Returns the smallest integer larger than or equal to `x`.
function math.ceil(x) end
---
-- Returns the cosine of `x` (assumed to be in radians).
function math.cos(x) end
---
-- Returns the hyperbolic cosine of `x`.
function math.cosh(x) end
---
-- Returns the angle `x` (given in radians) in degrees.
function math.deg(x) end
---
-- Returns the value *e^x*.
function math.exp(x) end
---
-- Returns the largest integer smaller than or equal to `x`.
function math.floor(x) end
---
-- Returns the remainder of the division of `x` by `y` that rounds the
-- quotient towards zero.
function math.fmod(x, y) end
---
-- Returns `m` and `e` such that *x = m2^e*, `e` is an integer and the
-- absolute value of `m` is in the range *[0.5, 1)* (or zero when `x` is zero).
function math.frexp(x) end
---
-- The value `HUGE_VAL`, a value larger than or equal to any other
-- numerical value.
-- function math.huge end
-- * `math.HUGE_VAL`: math.HUGE_VAL
---
-- Returns *m2^e* (`e` should be an integer).
function math.ldexp(m, e) end
---
-- Returns the natural logarithm of `x`.
function math.log(x) end
---
-- Returns the base-10 logarithm of `x`.
function math.log10(x) end
---
-- Returns the maximum value among its arguments.
function math.max(x, ...) end
---
-- Returns the minimum value among its arguments.
function math.min(x, ...) end
---
-- Returns two numbers, the integral part of `x` and the fractional part of
-- `x`.
function math.modf(x) end
---
-- The value of *pi*.
-- function math.pi end
-- * `math.pi`: math.pi
---
-- Returns *x^y*. (You can also use the expression `x^y` to compute this
-- value.)
function math.pow(x, y) end
---
-- Returns the angle `x` (given in degrees) in radians.
function math.rad(x) end
---
-- This function is an interface to the simple pseudo-random generator
-- function `rand` provided by ANSI C. (No guarantees can be given for its
-- statistical properties.)
-- When called without arguments, returns a uniform pseudo-random real
-- number in the range *[0,1)*. When called with an integer number `m`,
-- `math.random` returns a uniform pseudo-random integer in the range *[1,
-- m]*. When called with two integer numbers `m` and `n`, `math.random`
-- returns a uniform pseudo-random integer in the range *[m, n]*.
function math.random(m , n) end
---
-- Sets `x` as the "seed" for the pseudo-random generator: equal seeds
-- produce equal sequences of numbers.
function math.randomseed(x) end
---
-- Returns the sine of `x` (assumed to be in radians).
function math.sin(x) end
---
-- Returns the hyperbolic sine of `x`.
function math.sinh(x) end
---
-- Returns the square root of `x`. (You can also use the expression `x^0.5`
-- to compute this value.)
function math.sqrt(x) end
---
-- Returns the tangent of `x` (assumed to be in radians).
function math.tan(x) end
---
-- Returns the hyperbolic tangent of `x`.
function math.tanh(x) end
return math

112
Documentation/compiler/ldoc/ldoc/builtin/os.lua Normal file
View file

@ -0,0 +1,112 @@
--- Operating System facilities like date, time and program execution.
-- @module os
local os = {}
---
-- Returns an approximation of the amount in seconds of CPU time used by
-- the program.
function os.clock() end
---
-- Returns a string or a table containing date and time, formatted according
-- to the given string `format`.
--
-- If the `time` argument is present, this is the time to be formatted
-- (see the `os.time` function for a description of this value). Otherwise,
-- `date` formats the current time.
--
-- If `format` starts with '`!`', then the date is formatted in Coordinated
-- Universal Time. After this optional character, if `format` is the string
-- "`*t`", then `date` returns a table with the following fields:
--
-- * `year` (four digits)
-- * `month` (1--12)
-- * `day` (1--31)
-- * `hour` (0--23)
-- * `min` (0--59)
-- * `sec` (0--61)
-- * `wday` (weekday, Sunday is 1)
-- * `yday` (day of the year)
-- * `isdst` (daylight saving flag, a boolean).
--
-- If `format` is not "`*t`", then `date` returns the date as a string,
-- formatted according to the same rules as the C function `strftime`.
-- When called without arguments, `date` returns a reasonable date and time
-- representation that depends on the host system and on the current locale
-- (that is, `os.date()` is equivalent to `os.date("%c")`).
function os.date(format , time) end
---
-- Returns the number of seconds from time `t1` to time `t2`. In POSIX,
-- Windows, and some other systems, this value is exactly `t2`*-*`t1`.
function os.difftime(t2, t1) end
---
-- This function is equivalent to the C function `system`. It passes
-- `command` to be executed by an operating system shell. It returns a status
-- code, which is system-dependent. If `command` is absent, then it returns
-- nonzero if a shell is available and zero otherwise.
function os.execute(command) end
---
-- Calls the C function `exit`, with an optional `code`, to terminate the
-- host program. The default value for `code` is the success code.
function os.exit(code) end
---
-- Returns the value of the process environment variable `varname`, or
-- nil if the variable is not defined.
function os.getenv(varname) end
---
-- Deletes the file or directory with the given name. Directories must be
-- empty to be removed. If this function fails, it returns nil, plus a string
-- describing the error.
function os.remove(filename) end
---
-- Renames file or directory named `oldname` to `newname`. If this function
-- fails, it returns nil, plus a string describing the error.
function os.rename(oldname, newname) end
---
-- Sets the current locale of the program. `locale` is a string specifying
-- a locale; `category` is an optional string describing which category to
-- change: `"all"`, `"collate"`, `"ctype"`, `"monetary"`, `"numeric"`, or
-- `"time"`; the default category is `"all"`. The function returns the name
-- of the new locale, or nil if the request cannot be honored.
-- If `locale` is the empty string, the current locale is set to an
-- implementation-defined native locale. If `locale` is the string "`C`",
-- the current locale is set to the standard C locale.
-- When called with nil as the first argument, this function only returns
-- the name of the current locale for the given category.
function os.setlocale(locale , category) end
---
-- Returns the current time when called without arguments, or a time
-- representing the date and time specified by the given table. This table
-- must have fields `year`, `month`, and `day`, and may have fields `hour`,
-- `min`, `sec`, and `isdst` (for a description of these fields, see the
-- `os.date` function).
-- The returned value is a number, whose meaning depends on your system. In
-- POSIX, Windows, and some other systems, this number counts the number
-- of seconds since some given start time (the "epoch"). In other systems,
-- the meaning is not specified, and the number returned by `time` can be
-- used only as an argument to `date` and `difftime`.
function os.time(table) end
---
-- Returns a string with a file name that can be used for a temporary
-- file. The file must be explicitly opened before its use and explicitly
-- removed when no longer needed.
-- On some systems (POSIX), this function also creates a file with that
-- name, to avoid security risks. (Someone else might create the file with
-- wrong permissions in the time between getting the name and creating the
-- file.) You still have to open the file to use it and to remove it (even
-- if you do not use it).
-- When possible, you may prefer to use `io.tmpfile`, which automatically
-- removes the file when the program ends.
function os.tmpname() end
return os

97
Documentation/compiler/ldoc/ldoc/builtin/package.lua Normal file
View file

@ -0,0 +1,97 @@
--- controlling how `require` finds packages.
-- @module package
local package = {}
---
-- The path used by `require` to search for a C loader.
-- Lua initializes the C path `package.cpath` in the same way it initializes
-- the Lua path `package.path`, using the environment variable `LUA_CPATH`
-- or a default path defined in `luaconf.h`.
-- function package.cpath end
-- * `package.cpath`: package.cpath
---
-- A table used by `require` to control which modules are already
-- loaded. When you require a module `modname` and `package.loaded[modname]`
-- is not false, `require` simply returns the value stored there.
-- function package.loaded end
-- * `package.loaded`: package.loaded
---
-- A table used by `require` to control how to load modules.
-- Each entry in this table is a *searcher function*. When looking for a module,
-- `require` calls each of these searchers in ascending order, with the module
-- name (the argument given to `require`) as its sole parameter. The function
-- can return another function (the module *loader*) or a string explaining
-- why it did not find that module (or nil if it has nothing to say). Lua
-- initializes this table with four functions.
-- The first searcher simply looks for a loader in the `package.preload` table.
-- The second searcher looks for a loader as a Lua library, using the path
-- stored at `package.path`. A path is a sequence of *templates* separated by
-- semicolons. For each template, the searcher will change each interrogation
-- mark in the template by `filename`, which is the module name with each dot
-- replaced by a "directory separator" (such as "`/`" in Unix); then it will
-- try to open the resulting file name. So, for instance, if the Lua path is
-- the string
-- "./?.lua;./?.lc;/usr/local/?/init.lua"
-- the search for a Lua file for module `foo` will try to open the files
-- `./foo.lua`, `./foo.lc`, and `/usr/local/foo/init.lua`, in that order.
-- The third searcher looks for a loader as a C library, using the path given
-- by the variable `package.cpath`. For instance, if the C path is the string
-- "./?.so;./?.dll;/usr/local/?/init.so"
-- the searcher for module `foo` will try to open the files `./foo.so`,
-- `./foo.dll`, and `/usr/local/foo/init.so`, in that order. Once it finds
-- a C library, this searcher first uses a dynamic link facility to link the
-- application with the library. Then it tries to find a C function inside the
-- library to be used as the loader. The name of this C function is the string
-- "`luaopen_`" concatenated with a copy of the module name where each dot
-- is replaced by an underscore. Moreover, if the module name has a hyphen,
-- its prefix up to (and including) the first hyphen is removed. For instance,
-- if the module name is `a.v1-b.c`, the function name will be `luaopen_b_c`.
-- The fourth searcher tries an *all-in-one loader*. It searches the C
-- path for a library for the root name of the given module. For instance,
-- when requiring `a.b.c`, it will search for a C library for `a`. If found,
-- it looks into it for an open function for the submodule; in our example,
-- that would be `luaopen_a_b_c`. With this facility, a package can pack
-- several C submodules into one single library, with each submodule keeping
-- its original open function.
-- function package.loaders end
-- * `package.loaders`: package.loaders
---
-- Dynamically links the host program with the C library `libname`. Inside
-- this library, looks for a function `funcname` and returns this function as a
-- C function. (So, `funcname` must follow the protocol (see `lua_CFunction`)).
-- This is a low-level function. It completely bypasses the package and module
-- system. Unlike `require`, it does not perform any path searching and does
-- not automatically adds extensions. `libname` must be the complete file name
-- of the C library, including if necessary a path and extension. `funcname`
-- must be the exact name exported by the C library (which may depend on the
-- C compiler and linker used).
-- This function is not supported by ANSI C. As such, it is only available
-- on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix
-- systems that support the `dlfcn` standard).
function package.loadlib(libname, funcname) end
---
-- The path used by `require` to search for a Lua loader.
-- At start-up, Lua initializes this variable with the value of the environment
-- variable `LUA_PATH` or with a default path defined in `luaconf.h`, if
-- the environment variable is not defined. Any "`;;`" in the value of the
-- environment variable is replaced by the default path.
-- function package.path end
-- * `package.path`: package.path
---
-- A table to store loaders for specific modules (see `require`).
-- function package.preload end
-- * `package.preload`: package.preload
---
-- Sets a metatable for `module` with its `__index` field referring to the
-- global environment, so that this module inherits values from the global
-- environment. To be used as an option to function `module`.
function package.seeall(module) end
return package

191
Documentation/compiler/ldoc/ldoc/builtin/string.lua Normal file
View file

@ -0,0 +1,191 @@
--- string operations like searching and matching.
-- @module string
local string = {}
---
-- Returns the internal numerical codes of the characters `s[i]`, `s[i+1]`,
-- ..., `s[j]`. The default value for `i` is 1; the default value for `j`
-- is `i`.
-- Note that numerical codes are not necessarily portable across platforms.
function string.byte(s , i , j) end
---
-- Receives zero or more integers. Returns a string with length equal to
-- the number of arguments, in which each character has the internal numerical
-- code equal to its corresponding argument.
-- Note that numerical codes are not necessarily portable across platforms.
function string.char(...) end
---
-- Returns a string containing a binary representation of the given
-- function, so that a later `loadstring` on this string returns a copy of
-- the function. `function` must be a Lua function without upvalues.
function string.dump(func) end
---
-- Looks for the first match of `pattern` in the string `s`. If it finds a
-- match, then `find` returns the indices of `s` where this occurrence starts
-- and ends; otherwise, it returns nil. A third, optional numerical argument
-- `init` specifies where to start the search; its default value is 1 and
-- can be negative. A value of true as a fourth, optional argument `plain`
-- turns off the pattern matching facilities, so the function does a plain
-- "find substring" operation, with no characters in `pattern` being considered
-- "magic". Note that if `plain` is given, then `init` must be given as well.
-- If the pattern has captures, then in a successful match the captured values
-- are also returned, after the two indices.
function string.find(s, pattern , init , plain) end
---
-- Returns a formatted version of its variable number of arguments following
-- the description given in its first argument (which must be a string). The
-- format string follows the same rules as the `printf` family of standard C
-- functions. The only differences are that the options/modifiers `*`, `l`,
-- `L`, `n`, `p`, and `h` are not supported and that there is an extra option,
-- `q`. The `q` option formats a string in a form suitable to be safely read
-- back by the Lua interpreter: the string is written between double quotes,
-- and all double quotes, newlines, embedded zeros, and backslashes in the
-- string are correctly escaped when written. For instance, the call
--
-- string.format('%q', 'a string with "quotes" and \n new line')
--
-- will produce the string:
--
-- "a string with \"quotes\" and \
-- new line"
--
-- The options `c`, `d`, `E`, `e`, `f`, `g`, `G`, `i`, `o`, `u`, `X`, and
-- `x` all expect a number as argument, whereas `q` and `s` expect a string.
-- This function does not accept string values containing embedded zeros,
-- except as arguments to the `q` option.
function string.format(formatstring, ...) end
---
-- Returns an iterator function that, each time it is called, returns the
-- next captures from `pattern` over string `s`. If `pattern` specifies no
-- captures, then the whole match is produced in each call.
-- As an example, the following loop
--
-- s = "hello world from Lua"
-- for w in string.gmatch(s, "%a+") do
-- print(w)
-- end
--
-- will iterate over all the words from string `s`, printing one per line. The
-- next example collects all pairs `key=value` from the given string into
-- a table:
--
-- t = {}
-- s = "from=world, to=Lua"
-- for k, v in string.gmatch(s, "(%w+)=(%w+)") do
-- t[k] = v
-- end
--
-- For this function, a '`^`' at the start of a pattern does not work as an
-- anchor, as this would prevent the iteration.
function string.gmatch(s, pattern) end
---
-- Returns a copy of `s` in which all (or the first `n`, if given)
-- occurrences of the `pattern` have been replaced by a replacement string
-- specified by `repl`, which can be a string, a table, or a function. `gsub`
-- also returns, as its second value, the total number of matches that occurred.
--
-- If `repl` is a string, then its value is used for replacement. The character
-- `%` works as an escape character: any sequence in `repl` of the form `%n`,
-- with *n* between 1 and 9, stands for the value of the *n*-th captured
-- substring (see below). The sequence `%0` stands for the whole match. The
-- sequence `%%` stands for a single `%`.
--
-- If `repl` is a table, then the table is queried for every match, using
-- the first capture as the key; if the pattern specifies no captures, then
-- the whole match is used as the key.
--
-- If `repl` is a function, then this function is called every time a match
-- occurs, with all captured substrings passed as arguments, in order; if
-- the pattern specifies no captures, then the whole match is passed as a
-- sole argument.
--
-- If the value returned by the table query or by the function call is a
-- string or a number, then it is used as the replacement string; otherwise,
-- if it is false or nil, then there is no replacement (that is, the original
-- match is kept in the string).
--
-- Here are some examples:
-- x = string.gsub("hello world", "(%w+)", "%1 %1")
-- --> x="hello hello world world"
-- x = string.gsub("hello world", "%w+", "%0 %0", 1)
-- --> x="hello hello world"
-- x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
-- --> x="world hello Lua from"
-- x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
-- --> x="home = /home/roberto, user = roberto"
-- x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
-- return loadstring(s)()
-- end)
-- --> x="4+5 = 9"
-- local t = {name="lua", version="5.1"}
-- x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
-- --> x="lua-5.1.tar.gz"
function string.gsub(s, pattern, repl , n) end
---
-- Receives a string and returns its length. The empty string `""` has
-- length 0. Embedded zeros are counted, so `"a\000bc\000"` has length 5.
function string.len(s) end
---
-- Receives a string and returns a copy of this string with all uppercase
-- letters changed to lowercase. All other characters are left unchanged. The
-- definition of what an uppercase letter is depends on the current locale.
function string.lower(s) end
---
-- Looks for the first *match* of `pattern` in the string `s`. If it
-- finds one, then `match` returns the captures from the pattern; otherwise
-- it returns nil. If `pattern` specifies no captures, then the whole match
-- is returned. A third, optional numerical argument `init` specifies where
-- to start the search; its default value is 1 and can be negative.
function string.match(s, pattern , init) end
---
-- Returns a string that is the concatenation of `n` copies of the string
-- `s`.
function string.rep(s, n) end
---
-- Returns a string that is the string `s` reversed.
function string.reverse(s) end
---
-- Returns the substring of `s` that starts at `i` and continues until
-- `j`; `i` and `j` can be negative. If `j` is absent, then it is assumed to
-- be equal to -1 (which is the same as the string length). In particular,
-- the call `string.sub(s,1,j)` returns a prefix of `s` with length `j`, and
-- `string.sub(s, -i)` returns a suffix of `s` with length `i`.
function string.sub(s, i , j) end
---
-- Receives a string and returns a copy of this string with all lowercase
-- letters changed to uppercase. All other characters are left unchanged. The
-- definition of what a lowercase letter is depends on the current locale.
function string.upper(s) end
---
-- (5.3) Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form)
--- according to the format string fmt (see 6.4.2).
function string.pack (fmt, v1, v2, ...) end
---
-- (5.3) Returns the size of a string resulting from string.pack with the given format.
-- The format string cannot have the variable-length options 's' or 'z' (see 6.4.2).
function string.packsize (fmt) end
---
-- (5.3) Returns the values packed in string s (see string.pack) according to the format string fmt (see 6.4.2).
-- An optional pos marks where to start reading in s (default is 1)
-- After the read values, this function also returns the index of the first unread byte in s.
function string.unpack (fmt, s , pos) end
return string

52
Documentation/compiler/ldoc/ldoc/builtin/table.lua Normal file
View file

@ -0,0 +1,52 @@
--- manipulating Lua tables.
-- @module table
local table = {}
---
-- Given an array where all elements are strings or numbers, returns
-- `table[i]..sep..table[i+1] ... sep..table[j]`. The default value for
-- `sep` is the empty string, the default for `i` is 1, and the default for
-- `j` is the length of the table. If `i` is greater than `j`, returns the
-- empty string.
function table.concat(table , sep , i , j) end
---
-- Inserts element `value` at position `pos` in `table`, shifting up
-- other elements to open space, if necessary. The default value for `pos` is
-- `n+1`, where `n` is the length of the table (see §2.5.5), so that a call
-- `table.insert(t,x)` inserts `x` at the end of table `t`.
function table.insert(table, pos, value) end
---
-- Removes from `table` the element at position `pos`, shifting down other
-- elements to close the space, if necessary. Returns the value of the removed
-- element. The default value for `pos` is `n`, where `n` is the length of the
-- table, so that a call `table.remove(t)` removes the last element of table
-- `t`.
function table.remove(table , pos) end
---
-- Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "n" with
-- the total number of parameters. Note that the resulting table may not be a sequence.
function table.pack (...) end
---
-- Sorts table elements in a given order,
-- *in-place*, from `table[1]` to `table[n]`, where `n` is the length of the
-- table. If `comp` is given, then it must be a function that receives two
-- table elements, and returns true when the first is less than the second
-- (so that `not comp(a[i+1],a[i])` will be true after the sort). If `comp`
-- is not given, then the '<' operator will be used.
function table.sort(table , comp) end
-- luacheck: ignore 121
---
-- Returns the elements from the given table. This function is equivalent to
-- return list[i], list[i+1], ..., list[j]
-- except that the above code can be written only for a fixed number of
-- elements. By default, `i` is 1 and `j` is the length of the list, as
-- defined by the length operator (see §2.5.5).
function unpack(list , i , j) end
return table

48
Documentation/compiler/ldoc/ldoc/builtin/utf8.lua Normal file
View file

@ -0,0 +1,48 @@
--- This library provides basic support for UTF-8 encoding.
-- @module utf8
local utf8 = {}
---
-- Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence and returns
-- a string with the concatenation of all these sequences.
function utf8.char (...) end
---
-- The pattern "[\0-\x7F\xC2-\xF4][\x80-\xBF]*" , which matches exactly one
-- UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string.
-- @field charpattern
---
-- Iterate over all characters in string.
--
-- for p, c in utf8.codes(s) do body end
--
-- will iterate over all characters in string s, with p being the position (in bytes) and c the code point
-- of each character. It raises an error if it meets any invalid byte sequence.
function utf8.codes (s) end
---
-- Returns the codepoints (as integers) from all characters in s that start between byte position i and j (both included).
-- The default for i is 1 and for j is i. It raises an error if it meets any invalid byte sequence.
function utf8.codepoint (s , i , j) end
---
-- Returns the number of UTF-8 characters in string s that start between positions i and j (both inclusive).
-- The default for i is 1 and for j is -1. If it finds any invalid byte sequence, returns a false value plus
-- the position of the first invalid byte.
function utf8.len (s , i , j) end
---
-- Returns the position (in bytes) where the encoding of the n-th character of s (counting from position i) starts.
-- A negative n gets characters before position i. The default for i is 1 when n is non-negative
-- and #s + 1 otherwise, so that utf8.offset(s, -n) gets the offset of the n-th character from the end
-- of the string.
-- If the specified character is neither in the subject nor right after its end, the function returns nil.
--
-- As a special case, when n is 0 the function returns the start of the encoding of the character that contains the i-th byte of s.
--
-- This function assumes that s is a valid UTF-8 string.
function utf8.offset (s, n , i) end
return utf8

11
Documentation/compiler/ldoc/ldoc/config.ld Normal file
View file

@ -0,0 +1,11 @@
project = 'Lua'
description = 'Lua Standard Libraries'
full_description = [[
These are the built-in libraries of Lua 5.1
Plus documentation for lpeg and luafilesystem.
]]
file = {'builtin',exclude = {'builtin/globals.lua'}}
no_summary = true
no_return_or_parms = true
format = 'discount'

1515
Documentation/compiler/ldoc/ldoc/doc.lua Normal file
View file

File diff suppressed because it is too large Load diff

402
Documentation/compiler/ldoc/ldoc/html.lua Normal file
View file

@ -0,0 +1,402 @@
------ generating HTML output ---------
-- Although this can be generalized for outputting any format, since the template
-- is language-agnostic, this implementation concentrates on HTML.
-- This does the actual generation of HTML, and provides support functions in the ldoc
-- table for the template
--
-- A fair amount of the complexity comes from operating in two basic modes; first, where
-- there is a number of modules (classic LuaDoc) or otherwise, where there is only one
-- module and the index contains the documentation for that module.
--
-- Like LuaDoc, LDoc puts similar kinds of documentation files in their own directories.
-- So module docs go into 'modules/', scripts go into 'scripts/', and so forth. LDoc
-- generalizes the idea of these project-level categories and in fact custom categories
-- can be created (refered to as 'kinds' in the code)
local List = require 'pl.List'
local utils = require 'pl.utils'
local path = require 'pl.path'
local stringx = require 'pl.stringx'
local template = require 'pl.template'
local tablex = require 'pl.tablex'
local OrderedMap = require 'pl.OrderedMap'
local tools = require 'ldoc.tools'
local markup = require 'ldoc.markup'
local prettify = require 'ldoc.prettify'
local doc = require 'ldoc.doc'
local unpack = utils.unpack
local html = {}
local quit = utils.quit
local function cleanup_whitespaces(text)
local lines = stringx.splitlines(text)
for i = 1, #lines do
lines[i] = stringx.rstrip(lines[i])
end
lines[#lines + 1] = "" -- Little trick: file should end with newline
return table.concat(lines, "\n")
end
local function get_module_info(m)
local info = OrderedMap()
for tag in doc.module_info_tags() do
local val = m.tags[tag]
if type(val)=='table' then
val = table.concat(val,',')
end
tag = stringx.title(tag)
info:set(tag,val)
end
if #info:keys() > 0 then
return info
end
end
local escape_table = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;", [">"] = "&gt;", ["&"] = "&amp;" }
function html.generate_output(ldoc, args, project)
local check_directory, check_file, writefile = tools.check_directory, tools.check_file, tools.writefile
local original_ldoc
local function save_and_set_ldoc (set)
if not set then return end
if not original_ldoc then
original_ldoc = tablex.copy(ldoc)
end
for s in set:iter() do
local var,val = s:match('([^=]+)=(.+)')
local num = tonumber(val)
if num then val = num
elseif val == 'true' then val = true
elseif val == 'false' then val = false
end
print('setting',var,val)
ldoc[var] = val
end
end
local function restore_ldoc ()
if original_ldoc then
ldoc = original_ldoc
end
end
function ldoc.escape(str)
return (str:gsub("['&<>\"]", escape_table))
end
function ldoc.prettify(str)
return prettify.code('lua','usage',str,0,false)
end
-- Item descriptions come from combining the summary and description fields
function ldoc.descript(item)
return tools.join(' ', item.summary, item.description)
end
function ldoc.module_name (mod)
local name = mod.name
if args.unqualified and (mod.type == 'module' or mod.type == 'classmod') then -- leave out package
name = name:gsub('^.-%.','')
elseif mod.type == 'topic' then
if mod.display_name then
name = mod.display_name
else -- leave out md extension
name = name:gsub('%..*$','')
end
end
return name
end
-- this generates the internal module/function references
function ldoc.href(see)
if see.href then -- explict reference, e.g. to Lua manual
return see.href
elseif doc.Module:class_of(see) then
return ldoc.ref_to_module(see)
else
return ldoc.ref_to_module(see.mod)..'#'..see.name
end
end
-- this is either called from the 'root' (index or single module) or
-- from the 'modules' etc directories. If we are in one of those directories,
-- then linking to another kind is `../kind/name`; to the same kind is just `name`.
-- If we are in the root, then it is `kind/name`.
function ldoc.ref_to_module (mod)
local base = "" -- default: same directory
mod = mod or ldoc.module
local kind, module = mod.kind, ldoc.module
local name = mod.name -- default: name of module
if not ldoc.single then
if module then -- we are in kind/
if module.type ~= type then -- cross ref to ../kind/
base = "../"..kind.."/"
end
else -- we are in root: index
base = kind..'/'
end
else -- single module
if mod == ldoc.single then
name = ldoc.output
if not ldoc.root then base = '../' end
elseif ldoc.root then -- ref to other kinds (like examples)
base = kind..'/'
else
if module.type ~= type then -- cross ref to ../kind/
base = "../"..kind.."/"
end
end
end
return base..name..'.html'
end
function ldoc.include_file (file)
local text,_ = utils.readfile(file)
if not text then quit("unable to include "..file)
else
return text
end
end
-- these references are never from the index...?
function ldoc.source_ref (fun)
local modname = fun.module.name
local pack,name = tools.split_dotted_name(modname)
if not pack then
name = modname
end
return (ldoc.single and "" or "../").."source/"..name..'.lua.html#'..fun.lineno
end
function ldoc.use_li(ls)
if #ls > 1 then return '<li>','</li>' else return '','' end
end
function ldoc.default_display_name(item)
-- Project-level items:
if doc.project_level(item.type) then
return ldoc.module_name(item)
end
-- Module-level items:
local name = item.display_name or item.name
if item.type == 'function' or item.type == 'lfunction' then
if not ldoc.no_space_before_args then
name = name..' '
end
return name..item.args
else
return name
end
end
function ldoc.display_name(item)
if ldoc.custom_display_name_handler then
return ldoc.custom_display_name_handler(item, ldoc.default_display_name)
else
return ldoc.default_display_name(item)
end
end
function ldoc.no_spaces(s)
s = s:gsub('%s*$','')
return (s:gsub('%W','_'))
end
function ldoc.module_typename(m)
return doc.presentation_name(m.type)
end
function ldoc.is_list (t)
return type(t) == 'table' and t.append
end
function ldoc.strip_header (s)
if not s then return s end
return s:gsub('^%s*#+%s+','')
end
function ldoc.typename (tp)
if not tp or tp == '' or tp:match '^@' then return '' end
local optional
-- ?<type> is short for ?nil|<type>
if tp:match("^%?") and not tp:match '|' then
tp = '?|'..tp:sub(2)
end
local tp2 = tp:match("%?|?(.*)")
if tp2 then
optional = true
tp = tp2
end
local types = {}
for name in tp:gmatch("[^|]+") do
local sym = name:match '([%w%.%:]+)'
local ref,_ = markup.process_reference(sym,true)
if ref then
if ref.label and sym == name then
name = ref.label
end
local shortName = name:match("%.(%w*)$")
if shortName then
name = shortName
end
types[#types+1] = ('<a class="type" href="%s">%s</a>'):format(ldoc.href(ref),name)
else
types[#types+1] = '<span class="type">'..name..'</span>'
end
end
local names = table.concat(types, ", ", 1, math.max(#types-1, 1))
if #types > 1 then names = names.." or "..types[#types] end
if optional then
if names ~= '' then
if #types == 1 then names = "optional "..names end
else
names = "optional"
end
end
return names
end
-- the somewhat tangled logic that controls whether a type appears in the
-- navigation sidebar. (At least it's no longer in the template ;))
function ldoc.allowed_in_contents(type,module)
local allowed = true
if ldoc.kinds_allowed then
allowed = ldoc.kinds_allowed[type]
elseif ldoc.prettify_files and type == 'file' then
allowed = ldoc.prettify_files == 'show' or (module and module.type == 'file')
end
return allowed
end
local function set_charset (ldoc,m)
m = m or ldoc.module
ldoc.doc_charset = (m and m.tags.charset) or ldoc.charset
end
local module_template,_ = utils.readfile (path.join(args.template,ldoc.templ))
if not module_template then
quit("template not found at '"..args.template.."' Use -l to specify directory containing ldoc.ltp")
end
-- Runs a template on a module to generate HTML page.
local function templatize(template_str, ldoc, module)
local out, err = template.substitute(template_str, {
ldoc = ldoc,
module = module,
_escape = ldoc.template_escape
})
if not out then
quit(("template failed for %s: %s"):format(
module and module.name or ldoc.output or "index",
err))
end
if ldoc.postprocess_html then
out = ldoc.postprocess_html(out, module)
end
return cleanup_whitespaces(out)
end
local css, custom_css = ldoc.css, ldoc.custom_css
ldoc.output = args.output
ldoc.ipairs = ipairs
ldoc.pairs = pairs
ldoc.print = print
-- Bang out the index.
-- in single mode there is one module and the 'index' is the
-- documentation for that module.
ldoc.module = ldoc.single
if ldoc.single and args.one then
ldoc.kinds_allowed = {module = true, topic = true}
ldoc.one = true
end
ldoc.root = true
if ldoc.module then
ldoc.module.info = get_module_info(ldoc.module)
ldoc.module.ldoc = ldoc
save_and_set_ldoc(ldoc.module.tags.set)
end
set_charset(ldoc)
local out = templatize(module_template, ldoc, ldoc.module)
ldoc.root = false
restore_ldoc()
check_directory(args.dir) -- make sure output directory is ok
-- project icon
if ldoc.icon then
local dir_data = args.dir .. '/data'
if not path.isdir(dir_data) then
-- luacheck: push ignore lfs
lfs.mkdir(dir_data)
-- luacheck: pop
end
local file = require 'pl.file'
file.copy(ldoc.icon, dir_data)
end
args.dir = args.dir .. path.sep
if css then -- has CSS been copied?
check_file(args.dir..css, path.join(args.style,css))
end
if custom_css then -- has custom CSS been copied?
check_file(args.dir..custom_css, custom_css)
end
-- write out the module index
out = cleanup_whitespaces(out)
writefile(args.dir..args.output..args.ext,out)
-- in single mode, we exclude any modules since the module has been done;
-- ext step is then only for putting out any examples or topics
local mods = List()
for kind, modules in project() do
local lkind = kind:lower()
if not ldoc.single or ldoc.single and lkind ~= 'modules' then
mods:append {kind, lkind, modules}
end
end
-- write out the per-module documentation
-- note that we reset the internal ordering of the 'kinds' so that
-- e.g. when reading a topic the other Topics will be listed first.
if css then
ldoc.css = '../'..css
end
if custom_css then
ldoc.custom_css = '../'..custom_css
end
for m in mods:iter() do
local kind, lkind, modules = unpack(m)
check_directory(args.dir..lkind)
if not ldoc.keep_menu_order then
project:put_kind_first(kind)
end
for m in modules() do
ldoc.module = m
ldoc.body = m.body
m.ldoc = ldoc
if m.tags.set then
save_and_set_ldoc(m.tags.set)
end
set_charset(ldoc)
m.info = get_module_info(m)
if ldoc.body and m.postprocess then
ldoc.body = m.postprocess(ldoc.body)
end
local out = templatize(module_template, ldoc, m)
writefile(args.dir..lkind..'/'..m.name..args.ext,out)
restore_ldoc()
end
end
if not args.quiet then print('output written to '..tools.abspath(args.dir)) end
end
return html

19
Documentation/compiler/ldoc/ldoc/html/_code_css.lua Normal file
View file

@ -0,0 +1,19 @@
return [[
/* styles for prettification of source */
pre .comment { color: #558817; }
pre .constant { color: #a8660d; }
pre .escape { color: #844631; }
pre .keyword { color: #aa5050; font-weight: bold; }
pre .library { color: #0e7c6b; }
pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
pre .string { color: #8080ff; }
pre .number { color: #f8660d; }
pre .operator { color: #2239a8; font-weight: bold; }
pre .preprocessor, pre .prepro { color: #a33243; }
pre .global { color: #800080; }
pre .user-keyword { color: #800080; }
pre .prompt { color: #558817; }
pre .url { color: #272fc2; text-decoration: underline; }
]]

66
Documentation/compiler/ldoc/ldoc/html/_reset_css.lua Normal file
View file

@ -0,0 +1,66 @@
return [[
/* BEGIN RESET
Copyright (c) 2010, Yahoo! Inc. All rights reserved.
Code licensed under the BSD License:
http://developer.yahoo.com/yui/license.html
version: 2.8.2r1
*/
html {
color: #000;
background: #FFF;
}
body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
margin: 0;
padding: 0;
}
table {
border-collapse: collapse;
border-spacing: 0;
}
fieldset,img {
border: 0;
}
address,caption,cite,code,dfn,em,strong,th,var,optgroup {
font-style: inherit;
font-weight: inherit;
}
del,ins {
text-decoration: none;
}
li {
margin-left: 20px;
}
caption,th {
text-align: left;
}
h1,h2,h3,h4,h5,h6 {
font-size: 100%;
font-weight: bold;
}
q:before,q:after {
content: '';
}
abbr,acronym {
border: 0;
font-variant: normal;
}
sup {
vertical-align: baseline;
}
sub {
vertical-align: baseline;
}
legend {
color: #000;
}
input,button,textarea,select,optgroup,option {
font-family: inherit;
font-size: inherit;
font-style: inherit;
font-weight: inherit;
}
input,button,textarea,select {*font-size:100%;
}
/* END RESET */
]]

225
Documentation/compiler/ldoc/ldoc/html/ldoc_css.lua Normal file
View file

@ -0,0 +1,225 @@
return require('ldoc.html._reset_css') .. [[
body {
margin-left: 1em;
margin-right: 1em;
font-family: arial, helvetica, geneva, sans-serif;
background-color: #ffffff; margin: 0px;
}
code, tt { font-family: monospace; font-size: 1.1em; }
span.parameter { font-family:monospace; }
span.parameter:after { content:":"; }
span.types:before { content:"("; }
span.types:after { content:")"; }
.type { font-weight: bold; font-style:italic }
body, p, td, th { font-size: .95em; line-height: 1.2em;}
p, ul { margin: 10px 0 0 0px;}
strong { font-weight: bold;}
em { font-style: italic;}
h1 {
font-size: 1.5em;
margin: 20px 0 20px 0;
}
h2, h3, h4 { margin: 15px 0 10px 0; }
h2 { font-size: 1.25em; }
h3 { font-size: 1.15em; }
h4 { font-size: 1.06em; }
a:link { font-weight: bold; color: #004080; text-decoration: none; }
a:visited { font-weight: bold; color: #006699; text-decoration: none; }
a:link:hover { text-decoration: underline; }
hr {
color:#cccccc;
background: #00007f;
height: 1px;
}
blockquote { margin-left: 3em; }
ul { list-style-type: disc; }
p.name {
font-family: "Andale Mono", monospace;
padding-top: 1em;
}
pre {
background-color: rgb(245, 245, 245);
border: 1px solid #C0C0C0; /* silver */
padding: 10px;
margin: 10px 0 10px 0;
overflow: auto;
font-family: "Andale Mono", monospace;
}
pre.example {
font-size: .85em;
}
table.index { border: 1px #00007f; }
table.index td { text-align: left; vertical-align: top; }
#container {
margin-left: 1em;
margin-right: 1em;
background-color: #f0f0f0;
}
#product {
text-align: center;
border-bottom: 1px solid #cccccc;
background-color: #ffffff;
}
#product big {
font-size: 2em;
}
#main {
background-color: #f0f0f0;
border-left: 2px solid #cccccc;
}
#navigation {
float: left;
width: 14em;
vertical-align: top;
background-color: #f0f0f0;
overflow: visible;
}
#navigation h2 {
background-color:#e7e7e7;
font-size:1.1em;
color:#000000;
text-align: left;
padding:0.2em;
border-top:1px solid #dddddd;
border-bottom:1px solid #dddddd;
}
#navigation ul
{
font-size:1em;
list-style-type: none;
margin: 1px 1px 10px 1px;
}
#navigation li {
text-indent: -1em;
display: block;
margin: 3px 0px 0px 22px;
}
#navigation li li a {
margin: 0px 3px 0px -1em;
}
#content {
margin-left: 14em;
padding: 1em;
width: 700px;
border-left: 2px solid #cccccc;
border-right: 2px solid #cccccc;
background-color: #ffffff;
}
#about {
clear: both;
padding: 5px;
border-top: 2px solid #cccccc;
background-color: #ffffff;
}
@media print {
body {
font: 12pt "Times New Roman", "TimeNR", Times, serif;
}
a { font-weight: bold; color: #004080; text-decoration: underline; }
#main {
background-color: #ffffff;
border-left: 0px;
}
#container {
margin-left: 2%;
margin-right: 2%;
background-color: #ffffff;
}
#content {
padding: 1em;
background-color: #ffffff;
}
#navigation {
display: none;
}
pre.example {
font-family: "Andale Mono", monospace;
font-size: 10pt;
page-break-inside: avoid;
}
}
table.module_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.module_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.module_list td.name { background-color: #f0f0f0; min-width: 200px; }
table.module_list td.summary { width: 100%; }
table.function_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.function_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.function_list td.name { background-color: #f0f0f0; min-width: 200px; }
table.function_list td.summary { width: 100%; }
ul.nowrap {
overflow:auto;
white-space:nowrap;
}
dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
dl.table h3, dl.function h3 {font-size: .95em;}
/* stop sublists from having initial vertical space */
ul ul { margin-top: 0px; }
ol ul { margin-top: 0px; }
ol ol { margin-top: 0px; }
ul ol { margin-top: 0px; }
/* make the target distinct; helps when we're navigating to a function */
a:target + * {
background-color: #FF9;
}
]]
.. require('ldoc.html._code_css')

233
Documentation/compiler/ldoc/ldoc/html/ldoc_fixed_css.lua Normal file
View file

@ -0,0 +1,233 @@
return require('ldoc.html._reset_css') .. [[
body {
margin-left: 1em;
margin-right: 1em;
font-family: arial, helvetica, geneva, sans-serif;
background-color: #ffffff; margin: 0px;
}
code, tt { font-family: monospace; font-size: 1.1em; }
span.parameter { font-family:monospace; }
span.parameter:after { content:":"; }
span.types:before { content:"("; }
span.types:after { content:")"; }
.type { font-weight: bold; font-style:italic }
body, p, td, th { font-size: .95em; line-height: 1.2em;}
p, ul { margin: 10px 0 0 0px;}
strong { font-weight: bold;}
em { font-style: italic;}
h1 {
font-size: 1.5em;
margin: 0 0 20px 0;
}
h2, h3, h4 { margin: 15px 0 10px 0; }
h2 { font-size: 1.25em; }
h3 { font-size: 1.15em; }
h4 { font-size: 1.06em; }
a:link { font-weight: bold; color: #004080; text-decoration: none; }
a:visited { font-weight: bold; color: #006699; text-decoration: none; }
a:link:hover { text-decoration: underline; }
hr {
color:#cccccc;
background: #00007f;
height: 1px;
}
blockquote { margin-left: 3em; }
ul { list-style-type: disc; }
p.name {
font-family: "Andale Mono", monospace;
padding-top: 1em;
}
pre {
background-color: rgb(245, 245, 245);
border: 1px solid #C0C0C0; /* silver */
padding: 10px;
margin: 10px 0 10px 0;
overflow: auto;
font-family: "Andale Mono", monospace;
}
pre.example {
font-size: .85em;
}
table.index { border: 1px #00007f; }
table.index td { text-align: left; vertical-align: top; }
#container {
margin-left: 1em;
margin-right: 1em;
background-color: #ffffff;
}
#product {
text-align: center;
border-bottom: 1px solid #cccccc;
background-color: #ffffff;
}
#product big {
font-size: 2em;
}
#main {
background-color:#FFFFFF; // #f0f0f0;
border-left: 1px solid #cccccc;
}
#navigation {
position: fixed;
top: 0;
left: 0;
float: left;
width: 14em;
vertical-align: top;
background-color:#FFFFFF; // #f0f0f0;
border-right: 2px solid #cccccc;
overflow: visible;
overflow-y: scroll;
height: 100%;
padding-left: 1em;
}
#navigation h2 {
background-color:#FFFFFF;//:#e7e7e7;
font-size:1.1em;
color:#000000;
text-align: left;
padding:0.2em;
border-bottom:1px solid #dddddd;
}
#navigation ul
{
font-size:1em;
list-style-type: none;
margin: 1px 1px 10px 1px;
}
#navigation li {
text-indent: -1em;
display: block;
margin: 3px 0px 0px 22px;
}
#navigation li li a {
margin: 0px 3px 0px -1em;
}
#content {
margin-left: 14em;
padding: 1em;
padding-left: 2em;
width: 700px;
border-left: 2px solid #cccccc;
// border-right: 2px solid #cccccc;
background-color: #ffffff;
}
#about {
clear: both;
padding-left: 1em;
margin-left: 14em; // avoid the damn sidebar!
border-top: 2px solid #cccccc;
border-left: 2px solid #cccccc;
background-color: #ffffff;
}
@media print {
body {
font: 12pt "Times New Roman", "TimeNR", Times, serif;
}
a { font-weight: bold; color: #004080; text-decoration: underline; }
#main {
background-color: #ffffff;
border-left: 0px;
}
#container {
margin-left: 2%;
margin-right: 2%;
background-color: #ffffff;
}
#content {
padding: 1em;
background-color: #ffffff;
}
#navigation {
display: none;
}
pre.example {
font-family: "Andale Mono", monospace;
font-size: 10pt;
page-break-inside: avoid;
}
}
table.module_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.module_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.module_list td.name { background-color: #f0f0f0; ; min-width: 200px; }
table.module_list td.summary { width: 100%; }
table.function_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.function_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.function_list td.name { background-color: #f6f6ff; ; min-width: 200px; }
table.function_list td.summary { width: 100%; }
dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
dl.table h3, dl.function h3 {font-size: .95em;}
ul.nowrap {
overflow:auto;
whitespace:nowrap;
}
/* stop sublists from having initial vertical space */
ul ul { margin-top: 0px; }
ol ul { margin-top: 0px; }
ol ol { margin-top: 0px; }
ul ol { margin-top: 0px; }
/* make the target distinct; helps when we're navigating to a function */
a:target + * {
background-color: #FF9;
}
]]
.. require('ldoc.html._code_css')

324
Documentation/compiler/ldoc/ldoc/html/ldoc_ltp.lua Normal file
View file

@ -0,0 +1,324 @@
return [==[
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=$(ldoc.doc_charset)"/>
<head>
<title>$(ldoc.title)</title>
<link rel="stylesheet" href="$(ldoc.css)" type="text/css" />
# if ldoc.custom_css then -- add custom CSS file if configured.
<link rel="stylesheet" href="$(ldoc.custom_css)" type="text/css" />
# end
</head>
<body>
<div id="container">
<div id="product">
<div id="product_logo"></div>
<div id="product_name"><big><b></b></big></div>
<div id="product_description"></div>
</div> <!-- id="product" -->
<div id="main">
# local no_spaces = ldoc.no_spaces
# local use_li = ldoc.use_li
# local display_name = ldoc.display_name
# local iter = ldoc.modules.iter
# local function M(txt,item) return ldoc.markup(txt,item,ldoc.plain) end
# local nowrap = ldoc.wrap and '' or 'nowrap'
<!-- Menu -->
<div id="navigation">
<br/>
<h1>$(ldoc.project)</h1>
# if ldoc.icon then
# if module then
<img src="../data/$(ldoc.icon)" />
# else
<img src="data/$(ldoc.icon)" />
# end
# end
# if not ldoc.single and module then -- reference back to project index
<ul>
<li><a href="../$(ldoc.output).html">Index</a></li>
</ul>
# end
# --------- contents of module -------------
# if module and not ldoc.no_summary and #module.items > 0 then
<h2>Contents</h2>
<ul>
# for kind,items in module.kinds() do
<li><a href="#$(no_spaces(kind))">$(kind)</a></li>
# end
</ul>
# end
# if ldoc.no_summary and module and not ldoc.one then -- bang out the functions on the side
# for kind, items in module.kinds() do
<h2>$(kind)</h2>
<ul class="nowrap">
# for item in items() do
<li><a href="#$(item.name)">$(display_name(item))</a></li>
# end
</ul>
# end
# end
# -------- contents of project ----------
# local this_mod = module and module.name
# for kind, mods, type in ldoc.kinds() do
# if ldoc.allowed_in_contents(type,module) then
<h2>$(kind)</h2>
<ul class="$(kind=='Topics' and '' or 'nowrap')">
# for mod in mods() do local name = display_name(mod)
# if mod.name == this_mod then
<li><strong>$(name)</strong></li>
# else
<li><a href="$(ldoc.ref_to_module(mod))">$(name)</a></li>
# end
# end
# end
</ul>
# end
</div>
<div id="content">
# if ldoc.body then -- verbatim HTML as contents; 'non-code' entries
$(ldoc.body)
# elseif module then -- module documentation
<h1>$(ldoc.module_typename(module)) <code>$(module.name)</code></h1>
<p>$(M(module.summary,module))</p>
<p>$(M(module.description,module))</p>
# if module.tags.include then
$(M(ldoc.include_file(module.tags.include)))
# end
# if module.see then
# local li,il = use_li(module.see)
<h3>See also:</h3>
<ul>
# for see in iter(module.see) do
$(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
# end -- for
</ul>
# end -- if see
# if module.usage then
# local li,il = use_li(module.usage)
<h3>Usage:</h3>
<ul>
# for usage in iter(module.usage) do
$(li)<pre class="example">$(ldoc.escape(usage))</pre>$(il)
# end -- for
</ul>
# end -- if usage
# if module.info then
<h3>Info:</h3>
<ul>
# for tag, value in module.info:iter() do
<li><strong>$(tag)</strong>: $(M(value,module))</li>
# end
</ul>
# end -- if module.info
# if not ldoc.no_summary then
# -- bang out the tables of item types for this module (e.g Functions, Tables, etc)
# for kind,items in module.kinds() do
<h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
<table class="function_list">
# for item in items() do
<tr>
<td class="name" $(nowrap)><a href="#$(item.name)">$(display_name(item))</a></td>
<td class="summary">$(M(item.summary,item))</td>
</tr>
# end -- for items
</table>
#end -- for kinds
<br/>
<br/>
#end -- if not no_summary
# --- currently works for both Functions and Tables. The params field either contains
# --- function parameters or table fields.
# local show_return = not ldoc.no_return_or_parms
# local show_parms = show_return
# for kind, items in module.kinds() do
# local kitem = module.kinds:get_item(kind)
# local has_description = kitem and ldoc.descript(kitem) ~= ""
<h2 class="section-header $(has_description and 'has-description')"><a name="$(no_spaces(kind))"></a>$(kind)</h2>
$(M(module.kinds:get_section_description(kind),nil))
# if kitem then
# if has_description then
<div class="section-description">
$(M(ldoc.descript(kitem),kitem))
</div>
# end
# if kitem.usage then
<h3>Usage:</h3>
<pre class="example">$(ldoc.prettify(kitem.usage[1]))</pre>
# end
# end
<dl class="function">
# for item in items() do
<dt>
<a name = "$(item.name)"></a>
<strong>$(display_name(item))</strong>
# if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
<a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
# end
</dt>
<dd>
$(M(ldoc.descript(item),item))
# if ldoc.custom_tags then
# for custom in iter(ldoc.custom_tags) do
# local tag = item.tags[custom[1]]
# if tag and not custom.hidden then
# local li,il = use_li(tag)
<h3>$(custom.title or custom[1]):</h3>
<ul>
# for value in iter(tag) do
$(li)$(custom.format and custom.format(value) or M(value))$(il)
# end -- for
# end -- if tag
</ul>
# end -- iter tags
# end
# if show_parms and item.params and #item.params > 0 then
# local subnames = module.kinds:type_of(item).subnames
# if subnames then
<h3>$(subnames):</h3>
# end
<ul>
# for parm in iter(item.params) do
# local param,sublist = item:subparam(parm)
# if sublist then
<li><span class="parameter">$(sublist)</span>$(M(item.params.map[sublist],item))
<ul>
# end
# for p in iter(param) do
# local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p)
<li><span class="parameter">$(name)</span>
# if tp ~= '' then
<span class="types">$(tp)</span>
# end
$(M(item.params.map[p],item))
# if def == true then
(<em>optional</em>)
# elseif def then
(<em>default</em> $(def))
# end
# if item:readonly(p) then
<em>readonly</em>
# end
</li>
# end
# if sublist then
</li></ul>
# end
# end -- for
</ul>
# end -- if params
# if show_return and item.retgroups then local groups = item.retgroups
<h3>Returns:</h3>
# for i,group in ldoc.ipairs(groups) do local li,il = use_li(group)
<ol>
# for r in group:iter() do local type, ctypes = item:return_type(r); local rt = ldoc.typename(type)
$(li)
# if rt ~= '' then
<span class="types">$(rt)</span>
# end
$(M(r.text,item))$(il)
# if ctypes then
<ul>
# for c in ctypes:iter() do
<li><span class="parameter">$(c.name)</span>
<span class="types">$(ldoc.typename(c.type))</span>
$(M(c.comment,item))</li>
# end
</ul>
# end -- if ctypes
# end -- for r
</ol>
# if i < #groups then
<h3>Or</h3>
# end
# end -- for group
# end -- if returns
# if show_return and item.raise then
<h3>Raises:</h3>
$(M(item.raise,item))
# end
# if item.see then
# local li,il = use_li(item.see)
<h3>See also:</h3>
<ul>
# for see in iter(item.see) do
$(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
# end -- for
</ul>
# end -- if see
# if item.usage then
# local li,il = use_li(item.usage)
<h3>Usage:</h3>
<ul>
# for usage in iter(item.usage) do
$(li)<pre class="example">$(ldoc.prettify(usage))</pre>$(il)
# end -- for
</ul>
# end -- if usage
</dd>
# end -- for items
</dl>
# end -- for kinds
# else -- if module; project-level contents
# if ldoc.description then
<h2>$(M(ldoc.description,nil))</h2>
# end
# if ldoc.full_description then
<p>$(M(ldoc.full_description,nil))</p>
# end
# for kind, mods in ldoc.kinds() do
<h2>$(kind)</h2>
# kind = kind:lower()
<table class="module_list">
# for m in mods() do
<tr>
<td class="name" $(nowrap)><a href="$(no_spaces(kind))/$(m.name).html">$(m.name)</a></td>
<td class="summary">$(M(ldoc.strip_header(m.summary),m))</td>
</tr>
# end -- for modules
</table>
# end -- for kinds
# end -- if module
</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc $(ldoc.version)</a></i>
<i style="float:right;">Last updated $(ldoc.updatetime) </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
]==]

17
Documentation/compiler/ldoc/ldoc/html/ldoc_md_ltp.lua Normal file
View file

@ -0,0 +1,17 @@
return [[
> local lev = ldoc.level or 2
> local lev1,lev2 = ('#'):rep(lev),('#'):rep(lev+1)
> for kind, items in module.kinds() do
> local kitem = module.kinds:get_item(kind)
> if kitem then
$(lev1) $(ldoc.descript(kitem))
> end
> for item in items() do
$(lev2) $(ldoc.display_name(item))
$(ldoc.descript(item))
> end
> end
]]

292
Documentation/compiler/ldoc/ldoc/html/ldoc_new_css.lua Normal file
View file

@ -0,0 +1,292 @@
return [[
body {
color: #47555c;
font-size: 16px;
font-family: "Open Sans", sans-serif;
margin: 0;
background: #eff4ff;
}
a:link { color: #008fee; }
a:visited { color: #008fee; }
a:hover { color: #22a7ff; }
h1 { font-size:26px; font-weight: normal; }
h2 { font-size:22px; font-weight: normal; }
h3 { font-size:18px; font-weight: normal; }
h4 { font-size:16px; font-weight: bold; }
hr {
height: 1px;
background: #c1cce4;
border: 0px;
margin: 15px 0;
}
code, tt {
font-family: monospace;
}
span.parameter {
font-family: monospace;
font-weight: bold;
color: rgb(99, 115, 131);
}
span.parameter:after {
content:":";
}
span.types:before {
content:"(";
}
span.types:after {
content:")";
}
.type {
font-weight: bold; font-style:italic
}
p.name {
font-family: "Andale Mono", monospace;
}
#navigation {
float: left;
background-color: white;
border-right: 1px solid #d3dbec;
border-bottom: 1px solid #d3dbec;
width: 14em;
vertical-align: top;
overflow: visible;
}
#navigation br {
display: none;
}
#navigation h1 {
background-color: white;
border-bottom: 1px solid #d3dbec;
padding: 15px;
margin-top: 0px;
margin-bottom: 0px;
}
#navigation h2 {
font-size: 18px;
background-color: white;
border-bottom: 1px solid #d3dbec;
padding-left: 15px;
padding-right: 15px;
padding-top: 10px;
padding-bottom: 10px;
margin-top: 30px;
margin-bottom: 0px;
}
#content h1 {
background-color: #2c3e67;
color: white;
padding: 15px;
margin: 0px;
}
#content h2 {
background-color: #6c7ea7;
color: white;
padding: 15px;
padding-top: 15px;
padding-bottom: 15px;
margin-top: 0px;
}
#content h2 a {
background-color: #6c7ea7;
color: white;
text-decoration: none;
}
#content h2 a:hover {
text-decoration: underline;
}
#content h3 {
font-style: italic;
padding-top: 15px;
padding-bottom: 4px;
margin-right: 15px;
margin-left: 15px;
margin-bottom: 5px;
border-bottom: solid 1px #bcd;
}
#content h4 {
margin-right: 15px;
margin-left: 15px;
border-bottom: solid 1px #bcd;
}
#content pre {
margin: 15px;
}
pre {
background-color: rgb(50, 55, 68);
color: white;
border-radius: 3px;
/* border: 1px solid #C0C0C0; /* silver */
padding: 15px;
overflow: auto;
font-family: "Andale Mono", monospace;
}
#content ul pre.example {
margin-left: 0px;
}
table.index {
/* border: 1px #00007f; */
}
table.index td { text-align: left; vertical-align: top; }
#navigation ul
{
font-size:1em;
list-style-type: none;
margin: 1px 1px 10px 1px;
}
#navigation li {
text-indent: -1em;
display: block;
margin: 3px 0px 0px 22px;
}
#navigation li li a {
margin: 0px 3px 0px -1em;
}
#content {
margin-left: 14em;
}
#content p {
padding-left: 15px;
padding-right: 15px;
}
#content table {
padding-left: 15px;
padding-right: 15px;
background-color: white;
}
#content p, #content table, #content ol, #content ul, #content dl {
max-width: 900px;
}
#about {
padding: 15px;
padding-left: 16em;
background-color: white;
border-top: 1px solid #d3dbec;
border-bottom: 1px solid #d3dbec;
}
table.module_list, table.function_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
margin: 15px;
}
table.module_list td, table.function_list td {
border-width: 1px;
padding-left: 10px;
padding-right: 10px;
padding-top: 5px;
padding-bottom: 5px;
border: solid 1px rgb(193, 204, 228);
}
table.module_list td.name, table.function_list td.name {
background-color: white; min-width: 200px; border-right-width: 0px;
}
table.module_list td.summary, table.function_list td.summary {
background-color: white; width: 100%; border-left-width: 0px;
}
dl.function {
margin-right: 15px;
margin-left: 15px;
border-bottom: solid 1px rgb(193, 204, 228);
border-left: solid 1px rgb(193, 204, 228);
border-right: solid 1px rgb(193, 204, 228);
background-color: white;
}
dl.function dt {
color: rgb(99, 123, 188);
font-family: monospace;
border-top: solid 1px rgb(193, 204, 228);
padding: 15px;
}
dl.function dd {
margin-left: 15px;
margin-right: 15px;
margin-top: 5px;
margin-bottom: 15px;
}
#content dl.function dd h3 {
margin-top: 0px;
margin-left: 0px;
padding-left: 0px;
font-size: 16px;
color: rgb(128, 128, 128);
border-bottom: solid 1px #def;
}
#content dl.function dd ul, #content dl.function dd ol {
padding: 0px;
padding-left: 15px;
list-style-type: none;
}
ul.nowrap {
overflow:auto;
white-space:nowrap;
}
.section-description {
padding-left: 15px;
padding-right: 15px;
}
/* stop sublists from having initial vertical space */
ul ul { margin-top: 0px; }
ol ul { margin-top: 0px; }
ol ol { margin-top: 0px; }
ul ol { margin-top: 0px; }
/* make the target distinct; helps when we're navigating to a function */
a:target + * {
background-color: #FF9;
}
/* styles for prettification of source */
pre .comment { color: #bbccaa; }
pre .constant { color: #a8660d; }
pre .escape { color: #844631; }
pre .keyword { color: #ffc090; font-weight: bold; }
pre .library { color: #0e7c6b; }
pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
pre .string { color: #8080ff; }
pre .number { color: #f8660d; }
pre .operator { color: #2239a8; font-weight: bold; }
pre .preprocessor, pre .prepro { color: #a33243; }
pre .global { color: #c040c0; }
pre .user-keyword { color: #800080; }
pre .prompt { color: #558817; }
pre .url { color: #272fc2; text-decoration: underline; }
]]

202
Documentation/compiler/ldoc/ldoc/html/ldoc_one_css.lua Normal file
View file

@ -0,0 +1,202 @@
return require('ldoc.html._reset_css') .. [[
body {
margin-left: 1em;
margin-right: 1em;
font-family: arial, helvetica, geneva, sans-serif;
background-color: #ffffff; margin: 0px;
}
code, tt { font-family: monospace; font-size: 1.1em; }
body, p, td, th { font-size: .95em; line-height: 1.2em;}
p, ul { margin: 10px 0 0 10px;}
strong { font-weight: bold;}
em { font-style: italic;}
h1 {
font-size: 1.5em;
margin: 0 0 20px 0;
}
h2, h3, h4 { margin: 15px 0 10px 0; }
h2 { font-size: 1.25em; }
h3 { font-size: 1.15em; }
h4 { font-size: 1.06em; }
a:link { font-weight: bold; color: #004080; text-decoration: none; }
a:visited { font-weight: bold; color: #2808FF; text-decoration: none; }
a:link:hover { text-decoration: underline; }
hr {
color:#cccccc;
background: #00007f;
height: 1px;
}
blockquote { margin-left: 3em; }
ul { list-style-type: disc; }
p.name {
font-family: "Andale Mono", monospace;
padding-top: 1em;
}
pre {
background-color: rgb(245, 245, 245);
border: 1px solid #C0C0C0; /* silver */
padding: 10px;
margin: 10px 0 10px 0;
overflow: auto;
font-family: "Andale Mono", monospace;
}
pre.example {
font-size: .85em;
}
table.index { border: 1px #00007f; }
table.index td { text-align: left; vertical-align: top; }
#container {
margin-left: 1em;
margin-right: 1em;
background-color: #f5f5f5;
}
#product {
text-align: center;
border-bottom: 1px solid #cccccc;
background-color: #ffffff;
}
#product big {
font-size: 2em;
}
#main {
border-left: 2px solid #cccccc;
border-right: 2px solid #cccccc;
}
#navigation {
float: top;
vertical-align: top;
background-color: #f5f5f5;
overflow: visible;
}
#navigation h2 {
background-color:#e7e7e7;
font-size:1.1em;
color:#000000;
text-align: left;
padding:0.2em;
border-top:1px solid #dddddd;
border-bottom:1px solid #dddddd;
}
#navigation ul
{
font-size:1em;
list-style-type: none;
margin: 1px 1px 10px 1px;
}
#navigation li {
text-indent: -1em;
display: block;
margin: 3px 0px 0px 22px;
}
#navigation li li a {
margin: 0px 3px 0px -1em;
}
#content {
padding: 1em;
background-color: #ffffff;
}
#about {
clear: both;
padding: 5px;
border-top: 2px solid #cccccc;
background-color: #ffffff;
}
@media print {
body {
font: 12pt "Times New Roman", "TimeNR", Times, serif;
}
a { font-weight: bold; color: #004080; text-decoration: underline; }
#main {
background-color: #ffffff;
border-left: 0px;
}
#container {
margin-left: 2%;
margin-right: 2%;
background-color: #ffffff;
}
#content {
padding: 1em;
background-color: #ffffff;
}
#navigation {
display: none;
}
pre.example {
font-family: "Andale Mono", monospace;
font-size: 10pt;
page-break-inside: avoid;
}
}
table.module_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.module_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.module_list td.name { background-color: #f5f5f5; }
table.module_list td.summary { width: 100%; }
table.function_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.function_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.function_list td.name {
background-color: #f5f5f5;
white-space: normal; /* voids the "nowrap" in HTML */
}
table.function_list td.summary { width: 100%; }
dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
dl.table h3, dl.function h3 {font-size: .95em;}
]]
.. require('ldoc.html._code_css')

225
Documentation/compiler/ldoc/ldoc/html/ldoc_pale_css.lua Normal file
View file

@ -0,0 +1,225 @@
return require('ldoc.html._reset_css') .. [[
body {
margin-left: 1em;
margin-right: 1em;
font-family: arial, helvetica, geneva, sans-serif;
background-color: #ffffff; margin: 0px;
}
code, tt { font-family: monospace; font-size: 1.1em; }
span.parameter { font-family:monospace; }
span.parameter:after { content:":"; }
span.types:before { content:"("; }
span.types:after { content:")"; }
.type { font-weight: bold; font-style:italic }
body, p, td, th { font-size: .95em; line-height: 1.2em;}
p, ul { margin: 10px 0 0 0px;}
strong { font-weight: bold;}
em { font-style: italic;}
h1 {
font-size: 1.5em;
margin: 0 0 20px 0;
}
h2, h3, h4 { margin: 15px 0 10px 0; }
h2 { font-size: 1.25em; }
h3 { font-size: 1.15em; }
h4 { font-size: 1.06em; }
a:link { font-weight: bold; color: #004080; text-decoration: none; }
a:visited { font-weight: bold; color: #006699; text-decoration: none; }
a:link:hover { text-decoration: underline; }
hr {
color:#cccccc;
background: #00007f;
height: 1px;
}
blockquote { margin-left: 3em; }
ul { list-style-type: disc; }
p.name {
font-family: "Andale Mono", monospace;
padding-top: 1em;
}
pre {
background-color: rgb(245, 245, 245);
border: 1px solid #C0C0C0; /* silver */
padding: 10px;
margin: 10px 0 10px 0;
overflow: auto;
font-family: "Andale Mono", monospace;
}
pre.example {
font-size: .85em;
}
table.index { border: 1px #00007f; }
table.index td { text-align: left; vertical-align: top; }
#container {
margin-left: 1em;
margin-right: 1em;
background-color: #ffffff;
}
#product {
text-align: center;
border-bottom: 1px solid #cccccc;
background-color: #ffffff;
}
#product big {
font-size: 2em;
}
#main {
background-color:#FFFFFF; // #f0f0f0;
//border-left: 2px solid #cccccc;
}
#navigation {
float: left;
width: 14em;
vertical-align: top;
background-color:#FFFFFF; // #f0f0f0;
border-right: 2px solid #cccccc;
overflow: visible;
}
#navigation h2 {
background-color:#FFFFFF;//:#e7e7e7;
font-size:1.1em;
color:#000000;
text-align: left;
padding:0.2em;
//border-top:1px solid #dddddd;
border-bottom:1px solid #dddddd;
}
#navigation ul
{
font-size:1em;
list-style-type: none;
margin: 1px 1px 10px 1px;
}
#navigation li {
text-indent: -1em;
display: block;
margin: 3px 0px 0px 22px;
}
#navigation li li a {
margin: 0px 3px 0px -1em;
}
#content {
margin-left: 14em;
padding: 1em;
width: 700px;
border-left: 2px solid #cccccc;
// border-right: 2px solid #cccccc;
background-color: #ffffff;
}
#about {
clear: both;
padding: 5px;
border-top: 2px solid #cccccc;
background-color: #ffffff;
}
@media print {
body {
font: 12pt "Times New Roman", "TimeNR", Times, serif;
}
a { font-weight: bold; color: #004080; text-decoration: underline; }
#main {
background-color: #ffffff;
border-left: 0px;
}
#container {
margin-left: 2%;
margin-right: 2%;
background-color: #ffffff;
}
#content {
padding: 1em;
background-color: #ffffff;
}
#navigation {
display: none;
}
pre.example {
font-family: "Andale Mono", monospace;
font-size: 10pt;
page-break-inside: avoid;
}
}
table.module_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.module_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.module_list td.name { background-color: #f0f0f0; ; min-width: 200px; }
table.module_list td.summary { width: 100%; }
table.function_list {
border-width: 1px;
border-style: solid;
border-color: #cccccc;
border-collapse: collapse;
}
table.function_list td {
border-width: 1px;
padding: 3px;
border-style: solid;
border-color: #cccccc;
}
table.function_list td.name { background-color: #f6f6ff; ; min-width: 200px; }
table.function_list td.summary { width: 100%; }
dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
dl.table h3, dl.function h3 {font-size: .95em;}
ul.nowrap {
overflow:auto;
whitespace:nowrap;
}
/* stop sublists from having initial vertical space */
ul ul { margin-top: 0px; }
ol ul { margin-top: 0px; }
ol ol { margin-top: 0px; }
ul ol { margin-top: 0px; }
/* make the target distinct; helps when we're navigating to a function */
a:target + * {
background-color: #FF9;
}
]]
.. require('ldoc.html._code_css')

379
Documentation/compiler/ldoc/ldoc/lang.lua Normal file
View file

@ -0,0 +1,379 @@
------------
-- Language-dependent parsing of code.
-- This encapsulates the different strategies needed for parsing C and Lua
-- source code.
local class = require 'pl.class'
local utils = require 'pl.utils'
local List = require 'pl.List'
local tools = require 'ldoc.tools'
local lexer = require 'ldoc.lexer'
local quit = utils.quit
local tnext = lexer.skipws
local Lang = class()
function Lang:trim_comment (s)
return s:gsub(self.line_comment,'')
end
function Lang:start_comment (v)
local line = v:match (self.start_comment_)
if line and self.end_comment_ and v:match (self.end_comment_) then
return nil
end
local block = v:match(self.block_comment)
return line or block, block
end
function Lang:empty_comment (v)
return v:match(self.empty_comment_)
end
function Lang:grab_block_comment(v,tok)
v = v:gsub(self.block_comment,'')
return tools.grab_block_comment(v,tok,self.end_comment)
end
function Lang:find_module(tok,t,v)
return '...',t,v
end
function Lang:item_follows(t,v)
return false
end
function Lang:finalize()
self.empty_comment_ = self.start_comment_..'%s*$'
end
function Lang:search_for_token (tok,type,value,t,v)
while t and not (t == type and v == value) do
if t == 'comment' and self:start_comment(v) then return nil,t,v end
t,v = tnext(tok)
end
return t ~= nil,t,v
end
function Lang:parse_extra (tags,tok)
end
function Lang:is_module_modifier ()
return false
end
function Lang:parse_module_modifier (tags, tok)
return nil, "@usage or @exports deduction not implemented for this language"
end
local Lua = class(Lang)
function Lua:_init()
self.line_comment = '^%-%-+' -- used for stripping
self.start_comment_ = '^%-%-%-+' -- used for doc comment line start
self.block_comment = '^%-%-%[=*%[%-+' -- used for block doc comments
self.end_comment_ = '[^%-]%-%-+[^-]*\n$' ---- exclude --- this kind of comment ---
self.method_call = ':'
self:finalize()
end
function Lua.lexer(fname)
local f,e = io.open(fname)
if not f then quit(e) end
return lexer.lua(f,{}),f
end
function Lua:grab_block_comment(v,tok)
local equals = v:match('^%-%-%[(=*)%[')
if not equals then return v end
v = v:gsub(self.block_comment,'')
return tools.grab_block_comment(v,tok,'%]'..equals..'%]')
end
-- luacheck: push ignore 312
function Lua:parse_module_call(tok,t,v)
t,v = tnext(tok)
if t == '(' then t,v = tnext(tok) end
if t == 'string' then -- explicit name, cool
return v,t,v
elseif t == '...' then -- we have to guess!
return '...',t,v
end
end
-- luacheck: pop
-- If a module name was not provided, then we look for an explicit module()
-- call. However, we should not try too hard; if we hit a doc comment then
-- we should go back and process it. Likewise, module(...) also means
-- that we must infer the module name.
function Lua:find_module(tok,t,v)
local res
res,t,v = self:search_for_token(tok,'iden','module',t,v)
if not res then return nil,t,v end
return self:parse_module_call(tok,t,v)
end
local function parse_lua_parameters (tags,tok)
tags.formal_args = tools.get_parameters(tok)
tags:add('class','function')
end
local function parse_lua_function_header (tags,tok)
if not tags.name then
tags:add('name',tools.get_fun_name(tok))
end
if not tags.name then return 'function has no name' end
parse_lua_parameters(tags,tok)
end
local function parse_lua_table (tags,tok)
tags.formal_args = tools.get_parameters(tok,'}',function(s)
return s == ',' or s == ';'
end)
end
--------------- function and variable inferrence -----------
-- After a doc comment, there may be a local followed by:
-- [1] (l)function: function NAME
-- [2] (l)function: NAME = function
-- [3] table: NAME = {
-- [4] field: NAME = <anything else> (this is a module-level field)
--
-- Depending on the case successfully detected, returns a function which
-- will be called later to fill in inferred item tags
function Lua:item_follows(t,v,tok)
local parser, case
local is_local = t == 'keyword' and v == 'local'
if is_local then t,v = tnext(tok) end
if t == 'keyword' and v == 'function' then -- case [1]
case = 1
parser = parse_lua_function_header
elseif t == 'iden' then
local name,t,_ = tools.get_fun_name(tok,v)
if t ~= '=' then return nil,"not 'name = function,table or value'" end
t,v = tnext(tok)
if t == 'keyword' and v == 'function' then -- case [2]
tnext(tok) -- skip '('
case = 2
parser = function(tags,tok)
tags:add('name',name)
parse_lua_parameters(tags,tok)
end
elseif t == '{' then -- case [3]
case = 3
parser = function(tags,tok)
tags:add('class','table')
tags:add('name',name)
parse_lua_table (tags,tok)
end
else -- case [4]
case = 4
parser = function(tags)
tags:add('class','field')
tags:add('name',name)
end
end
elseif t == 'keyword' and v == 'return' then
t, v = tnext(tok)
if t == 'keyword' and v == 'function' then
-- return function(a, b, c)
tnext(tok) -- skip '('
case = 2
parser = parse_lua_parameters
elseif t == '{' then
-- return {...}
case = 5
parser = function(tags,tok)
tags:add('class','table')
parse_lua_table(tags,tok)
end
else
return nil,'not returning function or table'
end
else
return nil,"not 'name=value' or 'return value'"
end
return parser, is_local, case
end
-- we only call the function returned by the item_follows above if there
-- is not already a name and a type.
-- Otherwise, this is called. Currrently only tries to fill in the fields
-- of a table from a table definition as identified above
function Lua:parse_extra (tags,tok,case)
if tags.class == 'table' and not tags.field and case == 3 then
parse_lua_table(tags,tok)
end
end
-- For Lua, a --- @usage comment means that a long
-- string containing the usage follows, which we
-- use to update the module usage tag. Likewise, the @export
-- tag alone in a doc comment refers to the following returned
-- Lua table of functions
function Lua:is_module_modifier (tags)
return tags.summary == '' and (tags.usage or tags.export)
end
-- Allow for private name convention.
function Lua:is_private_var (name)
return name:match '^_' or name:match '_$'
end
function Lua:parse_module_modifier (tags, tok, F)
if tags.usage then
if tags.class ~= 'field' then return nil,"cannot deduce @usage" end
local t1= tnext(tok)
if t1 ~= '[' then return nil, t1..' '..': not a long string' end
local _, v = tools.grab_block_comment('',tok,'%]%]')
return true, v, 'usage'
elseif tags.export then
if tags.class ~= 'table' then return nil, "cannot deduce @export" end
for f in tags.formal_args:iter() do
if not self:is_private_var(f) then
F:export_item(f)
end
end
return true
end
end
-- note a difference here: we scan C/C++ code in full-text mode, not line by line.
-- This is because we can't detect multiline comments in line mode.
-- Note: this applies to C/C++ code used to generate _Lua_ documentation!
local CC = class(Lang)
function CC:_init()
self.line_comment = '^//+'
self.start_comment_ = '^///+'
self.block_comment = '^/%*%*+'
self.method_call = ':'
self:finalize()
end
function CC.lexer(f)
local err
f,err = utils.readfile(f)
if not f then quit(err) end
return lexer.cpp(f,{},nil,true)
end
function CC:grab_block_comment(v,tok)
v = v:gsub(self.block_comment,''):gsub('\n%s*%*','\n')
return 'comment',v:sub(1,-3)
end
--- here the argument name is always last, and the type is composed of any tokens before
function CC:extract_arg (tl,idx)
idx = idx or 1
local res = List()
for i = idx,#tl-1 do
res:append(tl[i][2])
end
local type = res:join ' '
return tl[#tl][2], type
end
function CC:item_follows (t,v,tok)
if not self.extra.C then
return false
end
if t == 'iden' or t == 'keyword' then --
local _
if v == self.extra.export then -- this is not part of the return type!
_,v = tnext(tok)
end
-- types may have multiple tokens: example, const char *bonzo(...)
local return_type, name = v
_,v = tnext(tok)
name = v
t,v = tnext(tok)
while t ~= '(' do
return_type = return_type .. ' ' .. name
name = v
t,v = tnext(tok)
end
--print ('got',name,t,v,return_type)
return function(tags,tok)
if not tags.name then
tags:add('name',name)
end
tags:add('class','function')
if t == '(' then
tags.formal_args,t,_ = tools.get_parameters(tok,')',',',self)
if return_type ~= 'void' then
tags.formal_args.return_type = return_type
end
end
end
end
return false
end
local Moon = class(Lua)
function Moon:_init()
self.line_comment = '^%-%-+' -- used for stripping
self.start_comment_ = '^%s*%-%-%-+' -- used for doc comment line start
self.block_comment = '^%-%-%[=*%[%-+' -- used for block doc comments
self.end_comment_ = '[^%-]%-%-+\n$' ---- exclude --- this kind of comment ---
self.method_call = '\\'
self:finalize()
end
--- much like Lua, BUT auto-assign parameters start with @
function Moon:extract_arg (tl,idx)
idx = idx or 1
local auto_assign = tl[idx][1] == '@'
if auto_assign then idx = idx + 1 end
local res = tl[idx][2]
return res
end
function Moon:item_follows (t,v,tok)
if t == '.' then -- enclosed in with statement
t,v = tnext(tok)
end
if t == 'iden' then
local name,t,v = tools.get_fun_name(tok,v,'')
if name == 'class' then
local _
name,_,_ = tools.get_fun_name(tok,v,'')
-- class!
return function(tags,tok)
tags:add('class','type')
tags:add('name',name)
end
elseif t == '=' or t == ':' then -- function/method
local _
t,_ = tnext(tok)
return function(tags,tok)
if not tags.name then
tags:add('name',name)
end
if t == '(' then
tags.formal_args,t,_ = tools.get_parameters(tok,')',',',self)
else
tags.formal_args = List()
end
t,_ = tnext(tok)
tags:add('class','function')
if t ~= '>' then
tags.static = true
end
end
else
return nil, "expecting '=' or ':'"
end
end
end
return { lua = Lua(), cc = CC(), moon = Moon() }

504
Documentation/compiler/ldoc/ldoc/lexer.lua Normal file
View file

@ -0,0 +1,504 @@
--- Lexical scanner for creating a sequence of tokens from text. <br>
-- <p><code>lexer.scan(s)</code> returns an iterator over all tokens found in the
-- string <code>s</code>. This iterator returns two values, a token type string
-- (such as 'string' for quoted string, 'iden' for identifier) and the value of the
-- token.
-- <p>
-- Versions specialized for Lua and C are available; these also handle block comments
-- and classify keywords as 'keyword' tokens. For example:
-- <pre class=example>
-- > s = 'for i=1,n do'
-- > for t,v in lexer.lua(s) do print(t,v) end
-- keyword for
-- iden i
-- = =
-- number 1
-- , ,
-- iden n
-- keyword do
-- </pre>
--
-- Based on pl.lexer from Penlight
local strfind = string.find
local strsub = string.sub
local append = table.insert
local function assert_arg(idx,val,tp)
if type(val) ~= tp then
error("argument "..idx.." must be "..tp, 2)
end
end
local lexer = {}
local NUMBER1 = '^[%+%-]?%d+%.?%d*[eE][%+%-]?%d+'
local NUMBER2 = '^[%+%-]?%d+%.?%d*'
local NUMBER3 = '^0x[%da-fA-F]+'
local NUMBER4 = '^%d+%.?%d*[eE][%+%-]?%d+'
local NUMBER5 = '^%d+%.?%d*'
local IDEN = '^[%a_][%w_]*'
local WSPACE = '^%s+'
local STRING1 = [[^'.-[^\\]']]
local STRING2 = [[^".-[^\\]"]]
local STRING3 = "^((['\"])%2)" -- empty string
local PREPRO = '^#.-[^\\]\n'
local plain_matches,lua_matches,cpp_matches,cpp_matches_no_string,lua_keyword,cpp_keyword
local function tdump(tok)
return tok,tok
end
local function ndump(tok,options)
if options and options.number then
tok = tonumber(tok)
end
return "number",tok
end
-- regular strings, single or double quotes; usually we want them
-- without the quotes
local function sdump(tok,options)
if options and options.string then
tok = tok:sub(2,-2)
end
return "string",tok
end
-- strings enclosed in back ticks
local function bdump(tok,options)
if options and options.string then
tok = tok:sub(2,-2)
end
return "backtick",tok
end
-- long Lua strings need extra work to get rid of the quotes
local function sdump_l(tok,options)
if options and options.string then
tok = tok:sub(3,-3)
end
return "string",tok
end
local function chdump(tok,options)
if options and options.string then
tok = tok:sub(2,-2)
end
return "char",tok
end
local function cdump(tok)
return 'comment',tok
end
local function wsdump (tok)
return "space",tok
end
local function pdump (tok)
return 'prepro',tok
end
local function plain_vdump(tok)
return "iden",tok
end
local function lua_vdump(tok)
if lua_keyword[tok] then
return "keyword",tok
else
return "iden",tok
end
end
local function cpp_vdump(tok)
if cpp_keyword[tok] then
return "keyword",tok
else
return "iden",tok
end
end
local function count_lines(line, text)
local index, limit = 1, #text
while index <= limit do
local start, stop = text:find('\r\n', index, true)
if not start then
start, stop = text:find('[\r\n\f]', index)
if not start then break end
end
index = stop + 1
line = line + 1
end
return line
end
local multiline = { comment = true, space = true }
--- create a plain token iterator from a string or file-like object.
-- @param s the string
-- @param matches an optional match table (set of pattern-action pairs)
-- @param filter a table of token types to exclude, by default {space=true}
-- @param options a table of options; by default, {number=true,string=true},
-- which means convert numbers and strip string quotes.
function lexer.scan (s,matches,filter,options)
--assert_arg(1,s,'string')
local file = type(s) ~= 'string' and s
filter = filter or {space=true}
options = options or {number=true,string=true}
if filter then
if filter.space then filter[wsdump] = true end
if filter.comments then
filter[cdump] = true
end
end
if not matches then
if not plain_matches then
plain_matches = {
{WSPACE,wsdump},
{NUMBER3,ndump},
{IDEN,plain_vdump},
{NUMBER1,ndump},
{NUMBER2,ndump},
{STRING3,sdump},
{STRING1,sdump},
{STRING2,sdump},
{'^.',tdump}
}
end
matches = plain_matches
end
local i1,i2,tok,pat,fun
local line = 1
if file then
s = file:read()
if not s then return nil end -- empty file
if s:match '^\239\187' then -- UTF-8 BOM Abomination
s = s:sub(4)
end
s = s ..'\n'
end
local sz = #s
local idx = 1
if sz == 0 then return nil end -- empty file
local res = {}
local mt = {}
mt.__index = mt
setmetatable(res,mt)
function mt.lineno() return line end
function mt.getline()
if idx < sz then
tok = strsub(s,idx,-2)
idx = sz + 1
line = line + 1
return tok
else
idx = sz + 1
line = line + 1
return file:read()
end
end
function mt.next (tok)
local t,v = tok()
while t == 'space' do
t,v = tok()
end
return t,v
end
function mt.__call ()
if not s then return end
while true do
for _,m in ipairs(matches) do
pat,fun = m[1],m[2]
if fun == nil then error("no match for "..pat) end
i1,i2 = strfind(s,pat,idx)
if i1 then
tok = strsub(s,i1,i2)
idx = i2 + 1
if not (filter and filter[fun]) then
lexer.finished = idx > sz
local t,v = fun(tok,options)
if not file and multiline[t] then
line = count_lines(line,v)
end
return t,v
end
end
end
if idx > sz then
if file then
line = line + 1
s = file:read()
if not s then return end
s = s .. '\n'
idx ,sz = 1,#s
else
return
end
end
end
end
return res
end
--- get everything in a stream upto a newline.
-- @param tok a token stream
-- @return a string
function lexer.getline (tok)
return tok:getline()
end
--- get current line number. <br>
-- Only available if the input source is a file-like object.
-- @param tok a token stream
-- @return the line number and current column
function lexer.lineno (tok)
return tok:lineno()
end
--- get the Lua keywords as a set-like table.
-- So <code>res["and"]</code> etc would be <code>true</code>.
-- @return a table
function lexer.get_keywords ()
if not lua_keyword then
lua_keyword = {
["and"] = true, ["break"] = true, ["do"] = true,
["else"] = true, ["elseif"] = true, ["end"] = true,
["false"] = true, ["for"] = true, ["function"] = true,
["if"] = true, ["in"] = true, ["local"] = true, ["nil"] = true,
["not"] = true, ["or"] = true, ["repeat"] = true,
["return"] = true, ["then"] = true, ["true"] = true,
["until"] = true, ["while"] = true
}
end
return lua_keyword
end
--- create a Lua token iterator from a string or file-like object.
-- Will return the token type and value.
-- @param s the string
-- @param filter a table of token types to exclude, by default {space=true,comments=true}
-- @param options a table of options; by default, {number=true,string=true},
-- which means convert numbers and strip string quotes.
function lexer.lua(s,filter,options)
filter = filter or {space=true,comments=true}
lexer.get_keywords()
if not lua_matches then
lua_matches = {
{WSPACE,wsdump},
{NUMBER3,ndump},
{IDEN,lua_vdump},
{NUMBER4,ndump},
{NUMBER5,ndump},
{STRING3,sdump},
{STRING1,sdump},
{STRING2,sdump},
{'^`[^`]+`',bdump},
{'^%-%-%[(=*)%[.-%]%1%]',cdump},
{'^%-%-.-\n',cdump},
{'^%-%-.-$',cdump},
{'^%[(=*)%[.-%]%1%]',sdump_l},
{'^==',tdump},
{'^~=',tdump},
{'^<=',tdump},
{'^>=',tdump},
{'^%.%.%.',tdump},
{'^%.%.',tdump},
{'^.',tdump}
}
end
return lexer.scan(s,lua_matches,filter,options)
end
--- create a C/C++ token iterator from a string or file-like object.
-- Will return the token type type and value.
-- @param s the string
-- @param filter a table of token types to exclude, by default {space=true,comments=true}
-- @param options a table of options; by default, {number=true,string=true},
-- which means convert numbers and strip string quotes.
function lexer.cpp(s,filter,options,no_string)
filter = filter or {comments=true}
if not cpp_keyword then
cpp_keyword = {
["class"] = true, ["break"] = true, ["do"] = true, ["sizeof"] = true,
["else"] = true, ["continue"] = true, ["struct"] = true,
["false"] = true, ["for"] = true, ["public"] = true, ["void"] = true,
["private"] = true, ["protected"] = true, ["goto"] = true,
["if"] = true, ["static"] = true, ["const"] = true, ["typedef"] = true,
["enum"] = true, ["char"] = true, ["int"] = true, ["bool"] = true,
["long"] = true, ["float"] = true, ["true"] = true, ["delete"] = true,
["double"] = true, ["while"] = true, ["new"] = true,
["namespace"] = true, ["try"] = true, ["catch"] = true,
["switch"] = true, ["case"] = true, ["extern"] = true,
["return"] = true,["default"] = true,['unsigned'] = true,['signed'] = true,
["union"] = true, ["volatile"] = true, ["register"] = true,["short"] = true,
}
end
if not cpp_matches then
cpp_matches = {
{WSPACE,wsdump},
{PREPRO,pdump},
{NUMBER3,ndump},
{IDEN,cpp_vdump},
{NUMBER4,ndump},
{NUMBER5,ndump},
{STRING3,sdump},
{STRING1,chdump},
{STRING2,sdump},
{'^//.-\n',cdump},
{'^//.-$',cdump},
{'^/%*.-%*/',cdump},
{'^==',tdump},
{'^!=',tdump},
{'^<=',tdump},
{'^>=',tdump},
{'^->',tdump},
{'^&&',tdump},
{'^||',tdump},
{'^%+%+',tdump},
{'^%-%-',tdump},
{'^%+=',tdump},
{'^%-=',tdump},
{'^%*=',tdump},
{'^/=',tdump},
{'^|=',tdump},
{'^%^=',tdump},
{'^::',tdump},
{'^%.%.%.',tdump},
{'^.',tdump}
}
end
if not cpp_matches_no_string then
cpp_matches_no_string = {
{WSPACE,wsdump},
{PREPRO,pdump},
{NUMBER3,ndump},
{IDEN,cpp_vdump},
{NUMBER4,ndump},
{NUMBER5,ndump},
{'^//.-\n',cdump},
{'^/%*.-%*/',cdump},
{'^==',tdump},
{'^!=',tdump},
{'^<=',tdump},
{'^>=',tdump},
{'^->',tdump},
{'^&&',tdump},
{'^||',tdump},
{'^%+%+',tdump},
{'^%-%-',tdump},
{'^%+=',tdump},
{'^%-=',tdump},
{'^%*=',tdump},
{'^/=',tdump},
{'^|=',tdump},
{'^%^=',tdump},
{'^::',tdump},
{'^%.%.%.',tdump},
{'^.',tdump}
}
end
return lexer.scan(s,
not no_string and cpp_matches or cpp_matches_no_string,
filter,options)
end
--- get a list of parameters separated by a delimiter from a stream.
-- @param tok the token stream
-- @param endtoken end of list (default ')'). Can be '\n'
-- @param delim separator (default ',')
-- @return a list of token lists.
function lexer.get_separated_list(tok,endtoken,delim)
endtoken = endtoken or ')'
delim = delim or ','
local function tappend (tl,t,val)
val = val or t
append(tl,{t,val})
end
local is_end
if endtoken == '\n' then
is_end = function(t,val)
return t == 'space' and val:find '\n'
end
else
is_end = function (t)
return t == endtoken
end
end
local is_delim
if type(delim) == 'function' then
is_delim = delim
else
is_delim = function(t)
return t == delim
end
end
local parm_values = {}
local level = 1 -- used to count ( and )
local tl = {}
local token,value
while true do
token,value=tok()
if not token then return nil,'EOS' end -- end of stream is an error!
if is_end(token,value) and level == 1 then
if next(tl) then
append(parm_values,tl)
end
break
elseif token == '(' then
level = level + 1
tappend(tl,'(')
elseif token == ')' then
level = level - 1
if level == 0 then -- finished with parm list
append(parm_values,tl)
break
else
tappend(tl,')')
end
elseif level == 1 and is_delim(token) then
append(parm_values,tl) -- a new parm
tl = {}
else
tappend(tl,token,value)
end
end
return parm_values,{token,value}
end
--- get the next non-space token from the stream.
-- @param tok the token stream.
function lexer.skipws (tok)
return tok:next()
end
local skipws = lexer.skipws
--- get the next token, which must be of the expected type.
-- Throws an error if this type does not match!
-- @param tok the token stream
-- @param expected_type the token type
-- @param no_skip_ws whether we should skip whitespace
function lexer.expecting (tok,expected_type,no_skip_ws)
assert_arg(1,tok,'function')
assert_arg(2,expected_type,'string')
local t,v
if no_skip_ws then
t,v = tok()
else
t,v = skipws(tok)
end
if t ~= expected_type then error ("expecting "..expected_type,2) end
return v
end
return lexer

1357
Documentation/compiler/ldoc/ldoc/markdown.lua Normal file
View file

File diff suppressed because it is too large Load diff

420
Documentation/compiler/ldoc/ldoc/markup.lua Normal file
View file

@ -0,0 +1,420 @@
--------------
-- Handling markup transformation.
-- Currently just does Markdown, but this is intended to
-- be the general module for managing other formats as well.
local doc = require 'ldoc.doc'
local utils = require 'pl.utils'
local stringx = require 'pl.stringx'
local prettify = require 'ldoc.prettify'
local concat = table.concat
local markup = {}
local backtick_references
-- inline <references> use same lookup as @see
local function resolve_inline_references (ldoc, txt, item, plain)
local do_escape = not plain and not ldoc.dont_escape_underscore
local res = (txt:gsub('@{([^}]-)}',function (name)
if name:match '^\\' then return '@{'..name:sub(2)..'}' end
local qname,label = utils.splitv(name,'%s*|')
if not qname then
qname = name
end
local ref, err
local custom_ref, refname = utils.splitv(qname,':')
if custom_ref and ldoc.custom_references then
custom_ref = ldoc.custom_references[custom_ref]
if custom_ref then
ref,err = custom_ref(refname)
end
end
if not ref then
ref,err = markup.process_reference(qname)
end
if not ref then
err = err .. ' ' .. qname
if item and item.warning then item:warning(err)
else
io.stderr:write('nofile error: ',err,'\n')
end
return '???'
end
if not label then
label = ref.label
end
if label and do_escape then -- a nastiness with markdown.lua and underscores
label = label:gsub('_','\\_')
end
local html = ldoc.href(ref) or '#'
label = ldoc.escape(label or qname)
local res = ('<a href="%s">%s</a>'):format(html,label)
return res
end))
if backtick_references then
res = res:gsub('`([^`]+)`',function(name)
local ref,_ = markup.process_reference(name)
local label = name
if name and do_escape then
label = name:gsub('_', '\\_')
end
label = ldoc.escape(label)
if ref then
return ('<a href="%s">%s</a>'):format(ldoc.href(ref),label)
else
return '<code>'..label..'</code>'
end
end)
end
return res
end
-- for readme text, the idea here is to create module sections at ## so that
-- they can appear in the contents list as a ToC.
function markup.add_sections(F, txt)
local sections, L, first = {}, 1, true
local title_pat
local lstrip = stringx.lstrip
for line in stringx.lines(txt) do
if first then
local level,header = line:match '^(#+)%s*(.+)'
if level then
level = level .. '#'
else
level = '##'
end
title_pat = '^'..level..'([^#]%s*.+)'
title_pat = lstrip(title_pat)
first = false
F.display_name = header
end
local title = line:match (title_pat)
if title then
--- Windows line endings are the cockroaches of text
title = title:gsub('\r$','')
-- Markdown allows trailing '#'...
title = title:gsub('%s*#+$','')
sections[L] = F:add_document_section(lstrip(title))
end
L = L + 1
end
F.sections = sections
return txt
end
local function indent_line (line)
line = line:gsub('\t',' ') -- support for barbarians ;)
local indent = #line:match '^%s*'
return indent,line
end
local function blank (line)
return not line:find '%S'
end
local global_context, local_context
-- before we pass Markdown documents to markdown/discount, we need to do three things:
-- - resolve any @{refs} and (optionally) `refs`
-- - any @lookup directives that set local context for ref lookup
-- - insert any section ids which were generated by add_sections above
-- - prettify any code blocks
local function process_multiline_markdown(ldoc, txt, F, filename, deflang)
local res, L, append = {}, 0, table.insert
local err_item = {
warning = function (self,msg)
io.stderr:write(filename..':'..L..': '..msg,'\n')
end
}
local get = stringx.lines(txt)
local getline = function()
L = L + 1
return get()
end
local function pretty_code (code, lang)
code = concat(code,'\n')
if code ~= '' then
local _
-- If we omit the following '\n', a '--' (or '//') comment on the
-- last line won't be recognized.
code, _ = prettify.code(lang,filename,code..'\n',L,false)
code = resolve_inline_references(ldoc, code, err_item,true)
append(res,'<pre>')
append(res, code)
append(res,'</pre>')
else
append(res,code)
end
end
local indent,start_indent
local_context = nil
local line = getline()
while line do
local name = line:match '^@lookup%s+(%S+)'
if name then
local_context = name .. '.'
line = getline()
end
local fence = line:match '^```(.*)'
if fence then
local plain = fence==''
line = getline()
local code = {}
while not line:match '^```' do
if not plain then
append(code, line)
else
append(res, ' '..line)
end
line = getline()
end
pretty_code (code,fence)
line = getline() -- skip fence
if not line then break end
end
indent, line = indent_line(line)
if indent >= 4 then -- indented code block
local code = {}
local plain
while indent >= 4 or blank(line) do
if not start_indent then
start_indent = indent
if line:match '^%s*@plain%s*$' then
plain = true
line = getline()
end
end
if not plain then
append(code,line:sub(start_indent + 1))
else
append(res,line)
end
line = getline()
if line == nil then break end
indent, line = indent_line(line)
end
start_indent = nil
while #code > 1 and blank(code[#code]) do -- trim blank lines.
table.remove(code)
end
pretty_code (code,deflang)
else
local section = F and F.sections[L]
if section then
append(res,('<a name="%s"></a>'):format(section))
end
line = resolve_inline_references(ldoc, line, err_item)
append(res,line)
line = getline()
end
end
res = concat(res,'\n')
return res
end
-- Handle markdown formatters
-- Try to get the one the user has asked for, but if it's not available,
-- try all the others we know about. If they don't work, fall back to text.
local function generic_formatter(format)
local ok, f = pcall(require, format)
return ok and f
end
local formatters =
{
markdown = function(format)
local ok, markdown = pcall(require, 'markdown')
if not ok then
print('format: using built-in markdown')
ok, markdown = pcall(require, 'ldoc.markdown')
end
return ok and markdown
end,
discount = function(format)
local ok, markdown = pcall(require, 'discount')
if ok then
-- luacheck: push ignore 542
if 'function' == type(markdown) then
-- lua-discount by A.S. Bradbury, https://luarocks.org/modules/luarocks/lua-discount
elseif 'table' == type(markdown) and ('function' == type(markdown.compile) or 'function' == type(markdown.to_html)) then
-- discount by Craig Barnes, https://luarocks.org/modules/craigb/discount
-- result of apt-get install lua-discount (links against libmarkdown2)
local mysterious_debian_variant = markdown.to_html ~= nil
markdown = markdown.compile or markdown.to_html
return function(text)
local result, errmsg = markdown(text)
if result then
if mysterious_debian_variant then
return result
else
return result.body
end
else
io.stderr:write('LDoc discount failed with error ',errmsg)
os.exit(1)
end
end
else
ok = false
end
-- luacheck: pop
end
if not ok then
print('format: using built-in markdown')
ok, markdown = pcall(require, 'ldoc.markdown')
end
return ok and markdown
end,
lunamark = function(format)
local ok, lunamark = pcall(require, format)
if ok then
local writer = lunamark.writer.html.new()
local parse = lunamark.reader.markdown.new(writer,
{ smart = true })
return function(text) return parse(text) end
end
end,
commonmark = function(format)
local ok, cmark = pcall(require, 'cmark')
if ok then
return function(text)
local doc = cmark.parse_document(text, string.len(text), cmark.OPT_DEFAULT)
return cmark.render_html(doc, cmark.OPT_DEFAULT)
end
end
end
}
local function get_formatter(format)
local used_format = format
local formatter = (formatters[format] or generic_formatter)(format)
if not formatter then -- try another equivalent processor
for name, f in pairs(formatters) do
formatter = f(name)
if formatter then
print('format: '..format..' not found, using '..name)
used_format = name
break
end
end
end
return formatter, used_format
end
local function text_processor(ldoc)
return function(txt,item)
if txt == nil then return '' end
-- hack to separate paragraphs with blank lines
txt = txt:gsub('\n\n','\n<p>')
return resolve_inline_references(ldoc, txt, item, true)
end
end
local plain_processor
local function markdown_processor(ldoc, formatter)
return function (txt,item,plain)
if txt == nil then return '' end
if plain then
if not plain_processor then
plain_processor = text_processor(ldoc)
end
return plain_processor(txt,item)
end
local is_file = utils.is_type(item,doc.File)
local is_module = not is_file and item and doc.project_level(item.type)
if is_file or is_module then
local deflang = 'lua'
if ldoc.parse_extra and ldoc.parse_extra.C then
deflang = 'c'
end
if is_module then
txt = process_multiline_markdown(ldoc, txt, nil, item.file.filename, deflang)
else
txt = process_multiline_markdown(ldoc, txt, item, item.filename, deflang)
end
else
txt = resolve_inline_references(ldoc, txt, item)
end
txt = formatter(txt)
-- We will add our own paragraph tags, if needed.
return (txt:gsub('^%s*<p>(.+)</p>%s*$','%1'))
end
end
local function get_processor(ldoc, format)
if format == 'plain' then return text_processor(ldoc) end
local formatter,actual_format = get_formatter(format)
if formatter then
markup.plain = false
-- AFAIK only markdown.lua has underscore-in-identifier problem...
if ldoc.dont_escape_underscore ~= nil then
ldoc.dont_escape_underscore = actual_format ~= 'markdown'
end
return markdown_processor(ldoc, formatter)
end
print('format: '..format..' not found, falling back to text')
return text_processor(ldoc)
end
function markup.create (ldoc, format, pretty, user_keywords)
local processor
markup.plain = true
if format == 'backtick' then
ldoc.backtick_references = true
format = 'plain'
end
backtick_references = ldoc.backtick_references
global_context = ldoc.package and ldoc.package .. '.'
prettify.set_prettifier(pretty)
prettify.set_user_keywords(user_keywords)
markup.process_reference = function(name,istype)
if local_context == 'none.' and not name:match '%.' then
return nil,'not found'
end
local mod = ldoc.single or ldoc.module or ldoc.modules[1]
local ref,err = mod:process_see_reference(name, ldoc.modules, istype)
if ref then return ref end
if global_context then
local qname = global_context .. name
ref = mod:process_see_reference(qname, ldoc.modules, istype)
if ref then return ref end
end
if local_context then
local qname = local_context .. name
ref = mod:process_see_reference(qname, ldoc.modules, istype)
if ref then return ref end
end
-- note that we'll return the original error!
return ref,err
end
markup.href = function(ref)
return ldoc.href(ref)
end
processor = get_processor(ldoc, format)
if not markup.plain and backtick_references == nil then
backtick_references = true
end
markup.resolve_inline_references = function(txt, errfn)
return resolve_inline_references(ldoc, txt, errfn, markup.plain)
end
markup.processor = processor
prettify.resolve_inline_references = function(txt, errfn)
return resolve_inline_references(ldoc, txt, errfn, true)
end
return processor
end
return markup

430
Documentation/compiler/ldoc/ldoc/parse.lua Normal file
View file

@ -0,0 +1,430 @@
-- parsing code for doc comments
local utils = require 'pl.utils'
local List = require 'pl.List'
-- local Map = require 'pl.Map'
local stringio = require 'pl.stringio'
local lexer = require 'ldoc.lexer'
local tools = require 'ldoc.tools'
local doc = require 'ldoc.doc'
local Item,File = doc.Item,doc.File
local unpack = utils.unpack
------ Parsing the Source --------------
-- This uses the lexer from PL, but it should be possible to use Peter Odding's
-- excellent Lpeg based lexer instead.
local parse = {}
local tnext, append = lexer.skipws, table.insert
-- a pattern particular to LuaDoc tag lines: the line must begin with @TAG,
-- followed by the value, which may extend over several lines.
local luadoc_tag = '^%s*@(%w+)'
local luadoc_tag_value = luadoc_tag..'(.*)'
local luadoc_tag_mod_and_value = luadoc_tag..'%[([^%]]*)%](.*)'
-- assumes that the doc comment consists of distinct tag lines
local function parse_at_tags(text)
local lines = stringio.lines(text)
local preamble, line = tools.grab_while_not(lines,luadoc_tag)
local tag_items = {}
local follows
while line do
local tag, mod_string, rest = line :match(luadoc_tag_mod_and_value)
if not tag then tag, rest = line :match (luadoc_tag_value) end
local modifiers
if mod_string then
modifiers = { }
for x in mod_string :gmatch "[^,]+" do
local k, v = x :match "^([^=]+)=(.*)$"
if not k then k, v = x, true end -- wuz x, x
modifiers[k] = v
end
end
-- follows: end of current tag
-- line: beginning of next tag (for next iteration)
follows, line = tools.grab_while_not(lines,luadoc_tag)
append(tag_items,{tag, rest .. '\n' .. follows, modifiers})
end
return preamble,tag_items
end
--local colon_tag = '%s*(%a+):%s'
local colon_tag = '%s*(%S-):%s'
local colon_tag_value = colon_tag..'(.*)'
local function parse_colon_tags (text)
local lines = stringio.lines(text)
local preamble, line = tools.grab_while_not(lines,colon_tag)
local tag_items, follows = {}
while line do
local tag, rest = line:match(colon_tag_value)
follows, line = tools.grab_while_not(lines,colon_tag)
local value = rest .. '\n' .. follows
if tag:match '^[%?!]' then
tag = tag:gsub('^!','')
value = tag .. ' ' .. value
tag = 'tparam'
end
append(tag_items,{tag, value})
end
return preamble,tag_items
end
-- Tags are stored as an ordered multi map from strings to strings
-- If the same key is used, then the value becomes a list
local Tags = {}
Tags.__index = Tags
function Tags.new (t,name)
local class
if name then
class = t
t = {}
end
t._order = List()
local tags = setmetatable(t,Tags)
if name then
tags:add('class',class)
tags:add('name',name)
end
return tags
end
function Tags:add (tag,value,modifiers)
if modifiers then -- how modifiers are encoded
value = {value,modifiers=modifiers}
end
local ovalue = self:get(tag)
if ovalue then
ovalue:append(value)
value = ovalue
end
rawset(self,tag,value)
if not ovalue then
self._order:append(tag)
end
end
function Tags:get (tag)
local ovalue = rawget(self,tag)
if ovalue then -- previous value?
if getmetatable(ovalue) ~= List then
ovalue = List{ovalue}
end
return ovalue
end
end
function Tags:iter ()
return self._order:iter()
end
local function comment_contains_tags (comment,args)
return (args.colon and comment:find ': ') or (not args.colon and comment:find '@')
end
-- This takes the collected comment block, and uses the docstyle to
-- extract tags and values. Assume that the summary ends in a period or a question
-- mark, and everything else in the preamble is the description.
-- If a tag appears more than once, then its value becomes a list of strings.
-- Alias substitution and @TYPE NAME shortcutting is handled by Item.check_tag
local function extract_tags (s,args)
local preamble,tag_items
if s:match '^%s*$' then return {} end
if args.colon then --and s:match ':%s' and not s:match '@%a' then
preamble,tag_items = parse_colon_tags(s)
else
preamble,tag_items = parse_at_tags(s)
end
local strip = tools.strip
local summary, description = preamble:match('^(.-[%.?])(%s.+)')
if not summary then
-- perhaps the first sentence did not have a . or ? terminating it.
-- Then try split at linefeed
summary, description = preamble:match('^(.-\n\n)(.+)')
if not summary then
summary = preamble
end
end -- and strip(description) ?
local tags = Tags.new{summary=summary and strip(summary) or '',description=description or ''}
for _,item in ipairs(tag_items) do
local tag, value, modifiers = Item.check_tag(tags,unpack(item))
-- treat multiline values more gently..
if not value:match '\n[^\n]+\n' then
value = strip(value)
end
tags:add(tag,value,modifiers)
end
return tags --Map(tags)
end
-- parses a Lua or C file, looking for ldoc comments. These are like LuaDoc comments;
-- they start with multiple '-'. (Block commments are allowed)
-- If they don't define a name tag, then by default
-- it is assumed that a function definition follows. If it is the first comment
-- encountered, then ldoc looks for a call to module() to find the name of the
-- module if there isn't an explicit module name specified.
local function parse_file(fname, lang, package, args)
local F = File(fname)
local module_found, first_comment = false,true
local current_item, module_item
F.args = args
F.lang = lang
F.base = package
local tok,f = lang.lexer(fname)
if not tok then return nil end
local function lineno ()
return tok:lineno()
end
function F:warning (msg,kind,line)
line = line or lineno()
Item.had_warning = true
io.stderr:write(fname..':'..line..': '..msg,'\n')
end
function F:error (msg)
self:warning(msg,'error')
io.stderr:write('LDoc error\n')
os.exit(1)
end
local function add_module(tags,module_found,old_style)
tags:add('name',module_found)
tags:add('class','module')
local item = F:new_item(tags,lineno())
item.old_style = old_style
module_item = item
end
local mod
local t,v = tnext(tok)
-- with some coding styles first comment is standard boilerplate; option to ignore this.
if args.boilerplate and t == 'comment' then
-- hack to deal with boilerplate inside Lua block comments
if v:match '%s*%-%-%[%[' then lang:grab_block_comment(v,tok) end
t,v = tnext(tok)
end
if t == '#' then -- skip Lua shebang line, if present
while t and t ~= 'comment' do t,v = tnext(tok) end
if t == nil then
F:warning('empty file')
return nil
end
end
if lang.parse_module_call and t ~= 'comment' then
local prev_token
while t do
if prev_token ~= '.' and prev_token ~= ':' and t == 'iden' and v == 'module' then
break
end
prev_token = t
t, v = tnext(tok)
end
if not t then
if not args.ignore then
F:warning("no module() call found; no initial doc comment")
end
--return nil
else
mod,t,v = lang:parse_module_call(tok,t,v)
if mod and mod ~= '...' then
add_module(Tags.new{summary='(no description)'},mod,true)
first_comment = false
module_found = true
end
end
end
local ok, err = xpcall(function()
while t do
if t == 'comment' then
local comment = {}
local ldoc_comment,block = lang:start_comment(v)
if ldoc_comment and block then
t,v = lang:grab_block_comment(v,tok)
end
if lang:empty_comment(v) then -- ignore rest of empty start comments
t,v = tok()
if t == 'space' and not v:match '\n' then
t,v = tok()
end
end
while t and t == 'comment' do
v = lang:trim_comment(v)
append(comment,v)
t,v = tok()
if t == 'space' and not v:match '\n' then
t,v = tok()
end
end
if t == 'space' then t,v = tnext(tok) end
local item_follows, tags, is_local, case, parse_error
if ldoc_comment then
comment = table.concat(comment)
if comment:match '^%s*$' then
ldoc_comment = nil
end
end
if ldoc_comment then
if first_comment then
first_comment = false
else
item_follows, is_local, case = lang:item_follows(t,v,tok)
if not item_follows then
parse_error = is_local
is_local = false
end
end
if item_follows or comment_contains_tags(comment,args) then
tags = extract_tags(comment,args)
-- explicitly named @module (which is recommended)
if doc.project_level(tags.class) then
module_found = tags.name
-- might be a module returning a single function!
if tags.param or tags['return'] then
local parms, ret = tags.param, tags['return']
local name = tags.name
tags.param = nil
tags['return'] = nil
tags['class'] = nil
tags['name'] = nil
add_module(tags,name,false)
tags = {
summary = '',
name = 'returns...',
class = 'function',
['return'] = ret,
param = parms
}
end
end
doc.expand_annotation_item(tags,current_item)
-- if the item has an explicit name or defined meaning
-- then don't continue to do any code analysis!
-- Watch out for the case where there are field or param tags
-- but no class, since these will be fixed up later as module/class
-- entities
if (tags.field or tags.param) and not tags.class then
parse_error = false
end
if tags.name then
if not tags.class then
F:warning("no type specified, assuming function: '"..tags.name.."'")
tags:add('class','function')
end
item_follows, is_local, parse_error = false, false, false
elseif args.no_args_infer then
F:error("No name and type provided (no_args_infer)")
elseif lang:is_module_modifier (tags) then
if not item_follows then
F:warning("@usage or @export followed by unknown code")
break
end
item_follows(tags,tok)
local res, value, tagname = lang:parse_module_modifier(tags,tok,F)
if not res then F:warning(value); break
else
if tagname then
module_item:set_tag(tagname,value)
end
-- don't continue to make an item!
ldoc_comment = false
end
end
end
if parse_error then
F:warning('definition cannot be parsed - '..parse_error)
end
end
-- some hackery necessary to find the module() call
if not module_found and ldoc_comment then
local old_style
module_found,t,v = lang:find_module(tok,t,v)
-- right, we can add the module object ...
old_style = module_found ~= nil
if not module_found or module_found == '...' then
-- we have to guess the module name
module_found = tools.this_module_name(package,fname)
end
if not tags then tags = extract_tags(comment,args) end
add_module(tags,module_found,old_style)
tags = nil
if not t then
F:warning('contains no items','warning',1)
break;
end -- run out of file!
-- if we did bump into a doc comment, then we can continue parsing it
end
-- end of a block of document comments
if ldoc_comment and tags then
local line = lineno()
if t ~= nil then
if item_follows then -- parse the item definition
local err = item_follows(tags,tok)
if err then F:error(err) end
elseif parse_error then
F:warning('definition cannot be parsed - '..parse_error)
else
lang:parse_extra(tags,tok,case)
end
end
if is_local or tags['local'] then
tags:add('local',true)
end
-- support for standalone fields/properties of classes/modules
if (tags.field or tags.param) and not tags.class then
-- the hack is to take a subfield and pull out its name,
-- (see Tag:add above) but let the subfield itself go through
-- with any modifiers.
local fp = tags.field or tags.param
if type(fp) == 'table' then fp = fp[1] end
fp = tools.extract_identifier(fp)
tags:add('name',fp)
tags:add('class','field')
end
if tags.name then
current_item = F:new_item(tags,line)
current_item.inferred = item_follows ~= nil
if doc.project_level(tags.class) then
if module_item then
F:error("Module already declared!")
end
module_item = current_item
end
end
if not t then break end
end
end
if t ~= 'comment' then t,v = tok() end
end
end,debug.traceback)
if not ok then return F, err end
if f then f:close() end
return F
end
function parse.file(name,lang, args)
local F,err = parse_file(name,lang,args.package,args)
if err or not F then return F,err end
local ok,err = xpcall(function() F:finish() end,debug.traceback)
if not ok then return F,err end
return F
end
return parse

131
Documentation/compiler/ldoc/ldoc/prettify.lua Normal file
View file

@ -0,0 +1,131 @@
-- Making Lua source code look pretty.
-- A simple scanner based prettifier, which scans comments for @{ref} and code
-- for known modules and functions.
-- A module reference to an example `test-fun.lua` would look like
-- `@{example:test-fun}`.
local List = require 'pl.List'
local tablex = require 'pl.tablex'
local globals = require 'ldoc.builtin.globals'
local prettify = {}
local user_keywords = {}
local escaped_chars = {
['&'] = '&amp;',
['<'] = '&lt;',
['>'] = '&gt;',
}
local escape_pat = '[&<>]'
local function escape(str)
return (str:gsub(escape_pat,escaped_chars))
end
local function span(t,val)
return ('<span class="%s">%s</span>'):format(t,val)
end
local spans = {keyword=true,number=true,string=true,comment=true,global=true,backtick=true}
local cpp_lang = {C = true, c = true, cpp = true, cxx = true, h = true}
function prettify.lua (lang, fname, code, initial_lineno, pre, linenos)
local res, lexer = List(), require 'ldoc.lexer'
local tokenizer
local ik = 1
if not cpp_lang[lang] then
tokenizer = lexer.lua
else
tokenizer = lexer.cpp
end
if pre then
res:append '<pre>\n'
end
initial_lineno = initial_lineno or 0
local tok = tokenizer(code,{},{})
local error_reporter = {
warning = function (self,msg)
io.stderr:write(fname..':'..tok:lineno()+initial_lineno..': '..msg,'\n')
end
}
local last_t, last_val
local t,val = tok()
if not t then return nil,"empty file" end
while t do
val = escape(val)
if linenos and tok:lineno() == linenos[ik] then
res:append('<a id="'..linenos[ik]..'"></a>')
ik = ik + 1
end
if globals.functions[val] or globals.tables[val] then
t = 'global'
end
if user_keywords[val] then
res:append(span('user-keyword keyword-' .. val,val))
elseif spans[t] then
if t == 'comment' or t == 'backtick' then -- may contain @{ref} or `..`
val = prettify.resolve_inline_references(val,error_reporter)
end
res:append(span(t,val))
else
res:append(val)
end
last_t, last_val = t,val
t,val = tok()
end
if last_t == 'comment' then
res[#res] = span('comment',last_val:gsub('\r*\n$',''))
end
local last = res[#res]
if last:match '\n$' then
res[#res] = last:gsub('\n+','')
end
if pre then
res:append '</pre>\n'
end
return res:join ()
end
local lxsh
local lxsh_highlighers = {bib=true,c=true,lua=true,sh=true}
function prettify.code (lang,fname,code,initial_lineno,pre)
if not lxsh then
return prettify.lua (lang,fname, code, initial_lineno, pre)
else
if not lxsh_highlighers[lang] then
lang = 'lua'
end
code = lxsh.highlighters[lang](code, {
formatter = lxsh.formatters.html,
external = true
})
if not pre then
code = code:gsub("^<pre.->(.-)%s*</pre>$", '%1')
end
return code
end
end
function prettify.set_prettifier (pretty)
local ok
if pretty == 'lxsh' then
ok,lxsh = pcall(require,'lxsh')
if not ok then
print('pretty: '..pretty..' not found, using built-in Lua')
lxsh = nil
end
end
end
function prettify.set_user_keywords(keywords)
if keywords then
user_keywords = tablex.makeset(keywords)
end
end
return prettify

544
Documentation/compiler/ldoc/ldoc/tools.lua Normal file
View file

@ -0,0 +1,544 @@
---------
-- General utility functions for ldoc
-- @module tools
local class = require 'pl.class'
local List = require 'pl.List'
local path = require 'pl.path'
local utils = require 'pl.utils'
local tablex = require 'pl.tablex'
local stringx = require 'pl.stringx'
local dir = require 'pl.dir'
local tools = {}
local M = tools
local append = table.insert
local lexer = require 'ldoc.lexer'
local quit = utils.quit
-- at rendering time, can access the ldoc table from any module item,
-- or the item itself if it's a module
function M.item_ldoc (item)
local mod = item and (item.module or item)
return mod and mod.ldoc
end
-- this constructs an iterator over a list of objects which returns only
-- those objects where a field has a certain value. It's used to iterate
-- only over functions or tables, etc. If the list of item has a module
-- with a context, then use that to pre-sort the fltered items.
-- (something rather similar exists in LuaDoc)
function M.type_iterator (list,field,value)
return function()
local fls = list:filter(function(item)
return item[field] == value
end)
local ldoc = M.item_ldoc(fls[1])
if ldoc and ldoc.sort then
fls:sort(function(ia,ib)
return ia.name < ib.name
end)
end
return fls:iter()
end
end
-- KindMap is used to iterate over a set of categories, called _kinds_,
-- and the associated iterator over all items in that category.
-- For instance, a module contains functions, tables, etc and we will
-- want to iterate over these categories in a specified order:
--
-- for kind, items in module.kinds() do
-- print('kind',kind)
-- for item in items() do print(item.name) end
-- end
--
-- The kind is typically used as a label or a Title, so for type 'function' the
-- kind is 'Functions' and so on.
local KindMap = class()
M.KindMap = KindMap
-- calling a KindMap returns an iterator. This returns the kind, the iterator
-- over the items of that type, and the actual type tag value.
function KindMap:__call ()
local i = 1
local klass = self.klass
return function()
local kind = klass.kinds[i]
if not kind then return nil end -- no more kinds
while not self[kind] do
i = i + 1
kind = klass.kinds[i]
if not kind then return nil end
end
i = i + 1
local type = klass.types_by_kind [kind].type
return kind, self[kind], type
end
end
function KindMap:put_kind_first (kind)
-- find this kind in our kind list
local kinds = self.klass.kinds
local idx = tablex.find(kinds,kind)
-- and swop with the start!
if idx then
kinds[1],kinds[idx] = kinds[idx],kinds[1]
end
end
function KindMap:type_of (item)
local klass = self.klass
local kind = klass.types_by_tag[item.type]
return klass.types_by_kind [kind]
end
function KindMap:get_section_description (kind)
return self.klass.descriptions[kind]
end
function KindMap:get_item (kind)
return self.klass.items_by_kind[kind]
end
-- called for each new item. It does not actually create separate lists,
-- (although that would not break the interface) but creates iterators
-- for that item type if not already created.
function KindMap:add (item,items,description)
local group = item[self.fieldname] -- which wd be item's type or section
local kname = self.klass.types_by_tag[group] -- the kind name
if not self[kname] then
self[kname] = M.type_iterator (items,self.fieldname,group)
self.klass.descriptions[kname] = description
end
item.kind = kname:lower()
end
-- KindMap has a 'class constructor' which is used to modify
-- any new base class.
function KindMap._class_init (klass)
klass.kinds = {} -- list in correct order of kinds
klass.types_by_tag = {} -- indexed by tag
klass.types_by_kind = {} -- indexed by kind
klass.descriptions = {} -- optional description for each kind
klass.items_by_kind = {} -- some kinds are items
end
function KindMap.add_kind (klass,tag,kind,subnames,item)
if not klass.types_by_kind[kind] then
klass.types_by_tag[tag] = kind
klass.types_by_kind[kind] = {type=tag,subnames=subnames}
if item then
klass.items_by_kind[kind] = item
end
append(klass.kinds,kind)
end
end
----- some useful utility functions ------
function M.module_basepath()
local lpath = List.split(package.path,';')
for p in lpath:iter() do
local p = path.dirname(p)
if path.isabs(p) then
return p
end
end
end
-- split a qualified name into the module part and the name part,
-- e.g 'pl.utils.split' becomes 'pl.utils' and 'split'. Also
-- must understand colon notation!
function M.split_dotted_name (s)
local s1,s2 = s:match '^(.+)[%.:](.+)$'
if s1 then -- we can split
return s1,s2
else
return nil
end
--~ local s1,s2 = path.splitext(s)
--~ if s2=='' then return nil
--~ else return s1,s2:sub(2)
--~ end
end
-- grab lines from a line iterator `iter` until the line matches the pattern.
-- Returns the joined lines and the line, which may be nil if we run out of
-- lines.
function M.grab_while_not(iter,pattern)
local line = iter()
local res = {}
while line and not line:match(pattern) do
append(res,line)
line = iter()
end
res = table.concat(res,'\n')
return res,line
end
function M.extract_identifier (value)
return value:match('([%.:%-_%w]+)(.*)$')
end
function M.identifier_list (ls)
local ns = List()
if type(ls) == 'string' then ls = List{ns} end
for s in ls:iter() do
if s:match ',' then
ns:extend(List.split(s,'[,%s]+'))
else
ns:append(s)
end
end
return ns
end
function M.strip (s)
return s:gsub('^%s+',''):gsub('%s+$','')
end
-- Joins strings using a separator.
--
-- Empty strings and nil arguments are ignored:
--
-- assert(join('+', 'one', '', 'two', nil, 'three') == 'one+two+three')
-- assert(join(' ', '', '') == '')
--
-- This is especially useful for the last case demonstrated above,
-- where "conventional" solutions (".." or table.concat) would result
-- in a spurious space.
function M.join(sep, ...)
local contents = {}
for i = 1, select('#', ...) do
local value = select(i, ...)
if value and value ~= "" then
contents[#contents + 1] = value
end
end
return table.concat(contents, sep)
end
function M.check_directory(d)
if not path.isdir(d) then
if not dir.makepath(d) then
quit("Could not create "..d.." directory")
end
end
end
function M.check_file (f,original)
if not path.exists(f)
or not path.exists(original)
or path.getmtime(original) > path.getmtime(f) then
local text,err = utils.readfile(original)
local _
if text then
_,err = utils.writefile(f,text)
end
if err then
quit("Could not copy "..original.." to "..f)
end
end
end
function M.writefile(name,text)
local f,err = io.open(name,"wb")
--~ local ok,err = utils.writefile(name,text)
if err then quit(err) end
f:write(text)
f:close()
end
function M.name_of (lpath)
local _
lpath,_ = path.splitext(lpath)
return lpath
end
function M.this_module_name (basename,fname)
if basename == '' then
return M.name_of(fname)
end
basename = path.abspath(basename)
if basename:sub(-1,-1) ~= path.sep then
basename = basename..path.sep
end
local lpath,cnt = fname:gsub('^'..utils.escape(basename),'')
--print('deduce',lpath,cnt,basename)
if cnt ~= 1 then quit("module(...) name deduction failed: base "..basename.." "..fname) end
lpath = lpath:gsub(path.sep,'.')
return (M.name_of(lpath):gsub('%.init$',''))
end
function M.find_existing_module (name, dname, searchfn)
local fullpath,lua = searchfn(name)
local mod = true
if not fullpath then -- maybe it's a function reference?
-- try again with the module part
local mpath,fname = M.split_dotted_name(name)
if mpath then
fullpath,lua = searchfn(mpath)
else
fullpath = nil
end
if not fullpath then
return nil, "module or function '"..dname.."' not found on module path"
else
mod = fname
end
end
if not lua then return nil, "module '"..name.."' is a binary extension" end
return fullpath, mod
end
function M.lookup_existing_module_or_function (name, docpath)
-- first look up on the Lua module path
local on_docpath
local fullpath, mod = M.find_existing_module(name,name,path.package_path)
-- no go; but see if we can find it on the doc path
if not fullpath then
fullpath, mod = M.find_existing_module("ldoc.builtin." .. name,name,path.package_path)
on_docpath = true
--~ fullpath, mod = M.find_existing_module(name, function(name)
--~ local fpath = package.searchpath(name,docpath)
--~ return fpath,true -- result must always be 'lua'!
--~ end)
end
return fullpath, mod, on_docpath -- `mod` can be the error message
end
--------- lexer tools -----
local tnext = lexer.skipws
local function type_of (tok) return tok and tok[1] or 'end' end
local function value_of (tok) return tok[2] end
-- This parses Lua formal argument lists. It will return a list of argument
-- names, which also has a comments field, which will contain any commments
-- following the arguments. ldoc will use these in addition to explicit
-- param tags.
function M.get_parameters (tok,endtoken,delim,lang)
tok = M.space_skip_getter(tok)
local args = List()
args.comments = {}
local ltl,tt = lexer.get_separated_list(tok,endtoken,delim)
if not ltl or not ltl[1] or #ltl[1] == 0 then return args end -- no arguments
local strip_comment, extract_arg
if lang then
strip_comment = utils.bind1(lang.trim_comment,lang)
extract_arg = utils.bind1(lang.extract_arg,lang)
else
strip_comment = function(text)
return text:match("%s*%-%-+%s*(.*)")
end
extract_arg = function(tl,idx)
idx = idx or 1
local res = value_of(tl[idx])
if res == '[' then -- we do allow array indices in tables now
res = '['..value_of(tl[idx + 1])..']'
end
return res
end
end
local function set_comment (idx,tok)
local text = stringx.rstrip(value_of(tok))
text = strip_comment(text)
local arg = args[idx]
local current_comment = args.comments[arg]
if current_comment then
text = current_comment .. " " .. text
end
args.comments[arg] = text
end
local function add_arg (tl,idx)
local name, type = extract_arg(tl,idx)
args:append(name)
if type then
if not args.types then args.types = List() end
args.types:append(type)
end
end
for i = 1,#ltl do
local tl = ltl[i] -- token list for argument
if #tl > 0 then
local j = 1
if type_of(tl[1]) == 'comment' then
-- the comments for the i-1 th arg are in the i th arg...
if i > 1 then
while type_of(tl[j]) == 'comment' do
set_comment(i-1,tl[j])
j = j + 1
end
else -- first comment however is for the function return comment!
args.return_comment = strip_comment(value_of(tl[i]))
j = j + 1
end
if #tl > 1 then
add_arg(tl,j)
end
else
add_arg(tl,1)
end
if i == #ltl and #tl > 1 then
while j <= #tl and type_of(tl[j]) ~= 'comment' do
j = j + 1
end
if j > #tl then break end -- was no comments!
while type_of(tl[j]) == 'comment' do
set_comment(i,tl[j])
j = j + 1
end
end
else
return nil,"empty argument"
end
end
-- we had argument comments
-- but the last one may be outside the parens! (Geoff style)
-- (only try this stunt if it's a function parameter list!)
if (not endtoken or endtoken == ')') and (#args > 0 or next(args.comments)) then
local n = #args
local last_arg = args[n]
if not args.comments[last_arg] then
while true do
tt = {tok()}
if type_of(tt) == 'comment' then
set_comment(n,tt)
else
break
end
end
end
end
-- return what token we ended on as well - can be token _past_ ')'
return args,tt[1],tt[2]
end
-- parse a Lua identifier - contains names separated by . and (optionally) :.
-- Set `colon` to be the secondary separator, '' for none.
function M.get_fun_name (tok,first,colon)
local res = {}
local t,name,sep,_
colon = colon or ':'
if not first then
t,name = tnext(tok)
else
t,name = 'iden',first
end
if t ~= 'iden' then return nil end
t,sep = tnext(tok)
while sep == '.' or sep == colon do
append(res,name)
append(res,sep)
_,name = tnext(tok)
t,sep = tnext(tok)
end
append(res,name)
return table.concat(res),t,sep
end
-- space-skipping version of token iterator
function M.space_skip_getter(tok)
return function ()
local t,v = tok()
while t and t == 'space' do
t,v = tok()
end
return t,v
end
end
function M.quote (s)
return "'"..s.."'"
end
-- The PL Lua lexer does not do block comments
-- when used in line-grabbing mode, so this function grabs each line
-- until we meet the end of the comment
function M.grab_block_comment (v,tok,patt)
local res = {v}
repeat
v = lexer.getline(tok)
if v:match (patt) then break end
append(res,v)
append(res,'\n')
until false
res = table.concat(res)
--print(res)
return 'comment',res
end
local prel = path.normcase('/[^/]-/%.%.')
function M.abspath (f)
local count
local res = path.normcase(path.abspath(f))
while true do
res,count = res:gsub(prel,'')
if count == 0 then break end
end
return res
end
function M.getallfiles(root,mask)
local res = List(dir.getallfiles(root,mask))
res:sort()
return res
end
function M.expand_file_list (list, mask)
local exclude_list = list.exclude and M.files_from_list(list.exclude, mask)
local files = List()
local function process (f)
f = M.abspath(f)
if not exclude_list or exclude_list and exclude_list:index(f) == nil then
files:append(f)
end
end
for _,f in ipairs(list) do
if path.isdir(f) then
local dfiles = M.getallfiles(f,mask)
for f in dfiles:iter() do
process(f)
end
elseif path.isfile(f) then
process(f)
else
quit("file or directory does not exist: "..M.quote(f))
end
end
return files
end
function M.process_file_list (list, mask, operation, ...)
local files = M.expand_file_list(list,mask)
for f in files:iter() do
operation(f,...)
end
end
function M.files_from_list (list, mask)
local excl = List()
M.process_file_list (list, mask, function(f)
excl:append(f)
end)
return excl
end
return tools

0
Documentation/packed/lfs.dll → Documentation/compiler/lfs.dll
View file

0
Documentation/packed/lua.exe → Documentation/compiler/lua.exe
View file

0
Documentation/packed/pl/Date.lua → Documentation/compiler/pl/Date.lua
View file

0
Documentation/packed/pl/List.lua → Documentation/compiler/pl/List.lua
View file

0
Documentation/packed/pl/Map.lua → Documentation/compiler/pl/Map.lua
View file

0
Documentation/packed/pl/MultiMap.lua → Documentation/compiler/pl/MultiMap.lua
View file

0
Documentation/packed/pl/OrderedMap.lua → Documentation/compiler/pl/OrderedMap.lua
View file

0
Documentation/packed/pl/Set.lua → Documentation/compiler/pl/Set.lua
View file

0
Documentation/packed/pl/app.lua → Documentation/compiler/pl/app.lua
View file

0
Documentation/packed/pl/array2d.lua → Documentation/compiler/pl/array2d.lua
View file

0
Documentation/packed/pl/class.lua → Documentation/compiler/pl/class.lua
View file

0
Documentation/packed/pl/compat.lua → Documentation/compiler/pl/compat.lua
View file

0
Documentation/packed/pl/comprehension.lua → Documentation/compiler/pl/comprehension.lua
View file

0
Documentation/packed/pl/config.lua → Documentation/compiler/pl/config.lua
View file

0
Documentation/packed/pl/data.lua → Documentation/compiler/pl/data.lua
View file

0
Documentation/packed/pl/dir.lua → Documentation/compiler/pl/dir.lua
View file

0
Documentation/packed/pl/file.lua → Documentation/compiler/pl/file.lua
View file

0
Documentation/packed/pl/func.lua → Documentation/compiler/pl/func.lua
View file

0
Documentation/packed/pl/import_into.lua → Documentation/compiler/pl/import_into.lua
View file

0
Documentation/packed/pl/init.lua → Documentation/compiler/pl/init.lua
View file

0
Documentation/packed/pl/input.lua → Documentation/compiler/pl/input.lua
View file

0
Documentation/packed/pl/lapp.lua → Documentation/compiler/pl/lapp.lua
View file

0
Documentation/packed/pl/lexer.lua → Documentation/compiler/pl/lexer.lua
View file

0
Documentation/packed/pl/luabalanced.lua → Documentation/compiler/pl/luabalanced.lua
View file

0
Documentation/packed/pl/operator.lua → Documentation/compiler/pl/operator.lua
View file

0
Documentation/packed/pl/path.lua → Documentation/compiler/pl/path.lua
View file

0
Documentation/packed/pl/permute.lua → Documentation/compiler/pl/permute.lua
View file

0
Documentation/packed/pl/pretty.lua → Documentation/compiler/pl/pretty.lua
View file

0
Documentation/packed/pl/seq.lua → Documentation/compiler/pl/seq.lua
View file

0
Documentation/packed/pl/sip.lua → Documentation/compiler/pl/sip.lua
View file

0
Documentation/packed/pl/strict.lua → Documentation/compiler/pl/strict.lua
View file

0
Documentation/packed/pl/stringio.lua → Documentation/compiler/pl/stringio.lua
View file

0
Documentation/packed/pl/stringx.lua → Documentation/compiler/pl/stringx.lua
View file

0
Documentation/packed/pl/tablex.lua → Documentation/compiler/pl/tablex.lua
View file

0
Documentation/packed/pl/template.lua → Documentation/compiler/pl/template.lua
View file

0
Documentation/packed/pl/test.lua → Documentation/compiler/pl/test.lua
View file

0
Documentation/packed/pl/text.lua → Documentation/compiler/pl/text.lua
View file

0
Documentation/packed/pl/types.lua → Documentation/compiler/pl/types.lua
View file

0
Documentation/packed/pl/url.lua → Documentation/compiler/pl/url.lua
View file

0
Documentation/packed/pl/utils.lua → Documentation/compiler/pl/utils.lua
View file

0
Documentation/packed/pl/xml.lua → Documentation/compiler/pl/xml.lua
View file

1
Documentation/doc/1 modules/Effects.html
View file

@ -503,7 +503,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/Flow.html
View file

@ -874,7 +874,6 @@ Specify which translations in the strings table correspond to which languages.
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/Input.html
View file

@ -283,7 +283,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/Inventory.html
View file

@ -253,7 +253,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/Logic.html
View file

@ -522,7 +522,6 @@ end
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/Objects.html
View file

@ -476,7 +476,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/Sound.html
View file

@ -393,7 +393,6 @@ Returns nil if no voice track is playing or no subtitle present.
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/Strings.html
View file

@ -216,7 +216,6 @@ with a call to <a href="../1 modules/Strings.html#ShowString">ShowString</a>, or
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/Util.html
View file

@ -484,7 +484,6 @@ PrintLog(<span class="string">'test error log'</span>, LogLevel.ERROR)
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/1 modules/View.html
View file

@ -543,7 +543,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Flow.Animations.html
View file

@ -117,7 +117,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Flow.Fog.html
View file

@ -244,7 +244,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Flow.InventoryItem.html
View file

@ -202,7 +202,6 @@ EXAMINE
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Flow.Level.html
View file

@ -547,7 +547,6 @@ Must be at least 4.</p>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Flow.Mirror.html
View file

@ -117,7 +117,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Flow.Settings.html
View file

@ -157,7 +157,6 @@ has an unrecoverable error, the game will close.
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Flow.SkyLayer.html
View file

@ -215,7 +215,6 @@ Less is more. City of The Dead, for example, uses a speed value of 16.
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Objects.AIObject.html
View file

@ -418,7 +418,6 @@ aiObj:SetObjectID(TEN.Objects.ObjID.AI_PATROL1)</pre>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Objects.Camera.html
View file

@ -331,7 +331,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Objects.LaraObject.html
View file

@ -740,7 +740,6 @@ ROCKETLAUNCHER
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Objects.Moveable.html
View file

@ -1915,7 +1915,6 @@ sas:SetPosition(newPos, <span class="keyword">false</span>)</pre>
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

1
Documentation/doc/2 classes/Objects.Room.html
View file

@ -370,7 +370,6 @@
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="https://github.com/hispidence/TEN-LDoc">TEN-LDoc</a> (a fork of <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a>)</i>
<i style="float:right;">Last updated 2024-02-11 22:25:15 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

Some files were not shown because too many files have changed in this diff Show more