Aire-One
/
LDoc2tl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #331 from alerque/lint-and-test

This commit is contained in:
Caleb Maclennan 2020-10-02 01:15:27 +03:00 committed by GitHub
parent 9fa1150194 ce1229b434
commit 380c7db50c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
22 changed files with 695 additions and 668 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
.github/workflows/luacheck.yml vendored Normal file
View File

@ -0,0 +1,23 @@
name: Luacheck
on: [push, pull_request]
jobs:
luacheck:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
- name: Setup Lua
uses: leafo/gh-actions-lua@v6
with:
luaVersion: 5.4
- name: Setup Lua Rocks
uses: leafo/gh-actions-luarocks@v2
- name: Setup dependencies
run: luarocks install luacheck
- name: Run Code Linter
run: |
luacheck .
luarocks lint *.rockspec

21
.luacheckrc Normal file
View File

@ -0,0 +1,21 @@
unused_args = false
redefined = false
max_line_length = false
include_files = {
"**/*.lua",
"*.rockspec",
".luacheckrc",
}
exclude_files = {
-- Tests are too messy to lint
"tests",
-- Travis Lua environment
"here/*.lua",
"here/**/*.lua",
-- GH Actions Lua Environment
".lua",
".luarocks",
".install",
}

15
Makefile
View File

@ -3,6 +3,8 @@ LUA_BINDIR= $(shell echo `dirname $(LUA)`)
LUA_PREFIX= $(shell echo `dirname $(LUA_BINDIR)`)
LUA_SHAREDIR=$(LUA_PREFIX)/share/lua/5.1
_REPODIR != cd "$(shell dirname $(firstword $(MAKEFILE_LIST)))/" && pwd
ldoc:
install: install_parts
@ -28,23 +30,26 @@ uninstall:
test: test-basic test-example test-md test-tables
RUN=&& ldoc . && diff -r docs cdocs && echo ok
RUN=&& lua $(_REPODIR)/ldoc.lua . && diff -r doc cdocs && echo ok
test-prep:
find -type d -name doc -execdir rsync -av --del {}/ cdocs/ \;
test-basic:
cd tests $(RUN)
test-example:
cd tests && cd example $(RUN)
cd tests/example $(RUN)
test-md:
cd tests && cd md-test $(RUN)
cd tests/md-test $(RUN)
test-tables:
cd tests && cd simple $(RUN)
cd tests/simple $(RUN)
test-clean: clean-basic clean-example clean-md clean-tables
CLEAN=&& ldoc . && rd /S /Q cdocs && cp -rf docs cdocs
CLEAN=&& lua $(_REPODIR)/ldoc.lua . && rd /S /Q cdocs && cp -rf doc cdocs
clean-basic:
cd tests $(CLEAN)

2
README.md
View File

@ -1,5 +1,7 @@
# LDoc - A Lua Documentation Tool
[![Luacheck](https://github.com/lunarmodules/LDoc/workflows/Luacheck/badge.svg)](https://github.com/lunarmodules/LDoc/actions)
Copyright (C) 2011-2012 Steve Donovan.
## Rationale

17
ldoc.lua
View File

@ -27,7 +27,6 @@ local tablex = require 'pl.tablex'
-- Penlight compatibility
utils.unpack = utils.unpack or unpack or table.unpack
local append = table.insert
local lapp = require 'pl.lapp'
local version = '1.4.6'
@ -91,7 +90,7 @@ local global = require 'ldoc.builtin.globals'
local markup = require 'ldoc.markup'
local parse = require 'ldoc.parse'
local KindMap = tools.KindMap
local Item,File,Module = doc.Item,doc.File,doc.Module
local Item,File = doc.Item,doc.File
local quit = utils.quit
if args.version then
@ -176,7 +175,6 @@ local function setup_kinds ()
end
local add_language_extension
-- hacky way for doc module to be passed options...
doc.ldoc = ldoc
@ -258,14 +256,15 @@ ldoc_contents = tablex.makeset(ldoc_contents)
local function loadstr (ldoc,txt)
local chunk, err
local load
-- 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
load = load or utils.load
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
@ -277,7 +276,7 @@ local function read_ldoc_config (fname)
if directory == '' then
directory = '.'
end
local chunk, err, ok
local chunk, err, _
if args.filter == 'none' then
print('reading configuration from '..fname)
end
@ -286,7 +285,7 @@ local function read_ldoc_config (fname)
chunk, err = loadstr(ldoc,txt)
if chunk then
if args.define ~= 'none' then ldoc[args.define] = true end
ok,err = pcall(chunk)
_,err = pcall(chunk)
end
end
if err then quit('error loading config file '..fname..': '..err) end
@ -301,7 +300,6 @@ end
local quote = tools.quote
--- processing command line and preparing for output ---
local F
local file_list = List()
File.list = file_list
local config_dir
@ -316,7 +314,7 @@ if args.module then
if args.file:match '^%a+$' and global.functions[args.file] then
args.file = 'global.'..args.file
end
local fullpath,mod,on_docpath = tools.lookup_existing_module_or_function (args.file, doc_path)
local fullpath,mod,_ = tools.lookup_existing_module_or_function (args.file, doc_path)
if not fullpath then
quit(mod)
else
@ -337,7 +335,6 @@ if args.file == '.' then
print('changing to directory',config_path)
lfs.chdir(config_path)
end
config_is_read = true
args.file = ldoc.file or '.'
if args.file == '.' then
args.file = lfs.currentdir()

248
ldoc/builtin/debug.lua
View File

@ -1,124 +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, function , what) end
---
-- This function returns the name and the value of the local variable with
-- index `local` 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, local) 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 `local` 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, local, 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
--- 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

22
ldoc/builtin/global.lua
View File

@ -2,9 +2,11 @@
module 'global'
-- luacheck: ignore 121
---
-- Issues an error when its argument `v` is false.
-- That is, nil or false. otherwise, returns all its arguments.
-- 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
@ -69,26 +71,26 @@ function getmetatable(object) end
function ipairs(t) end
---
-- Loads a chunk.
-- 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
-- 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.
-- 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.
-- 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).
-- 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.
-- 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
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
function loadfile (filename , mode , env) end
---
-- Allows a program to traverse all fields of a table. Its first argument is
@ -178,7 +180,7 @@ function setmetatable(table, metatable) end
-- 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
function tonumber(e , base) end
---
-- Converts any value to a string in a reasonable format.

321
ldoc/builtin/io.lua
View File

@ -1,159 +1,162 @@
--- Reading and Writing Files.
-- @module io
local io = {}
---
-- 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
--- 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

382
ldoc/builtin/string.lua
View File

@ -1,191 +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(function) 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
--- 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

88
ldoc/builtin/table.lua
View File

@ -1,44 +1,46 @@
--- 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
--- 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]
@ -46,5 +48,5 @@ function table.sort(table , comp) end
-- 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
return table

54
ldoc/builtin/utf8.lua
View File

@ -1,48 +1,48 @@
--- This library provides basic support for UTF-8 encoding.
-- @module utf8
local utf8 = {}
--- 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
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
-- @field charpattern
---
-- Iterate over all characters in string.
--
-- 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
-- of each character. It raises an error if it meets any invalid byte sequence.
function utf8.codes (s) end
---
-- Returns the number of UTF-8 characters in string s that start between positions i and j (both inclusive).
-- 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
-- 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
-- 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
--
-- 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

25
ldoc/doc.lua
View File

@ -192,12 +192,6 @@ function File:export_item (name)
self:warning('no docs '..tools.quote(name))
end
local function has_prefix (name,prefix)
local i1,i2 = name:find(prefix)
return i1 == 1 and i2 == #prefix
end
local function mod_section_type (this_mod)
return this_mod and this_mod.section and this_mod.section.type
end
@ -236,6 +230,7 @@ function File:finish()
end
item:finish()
-- the default is not to show local functions in the documentation.
-- luacheck: push ignore 542
if not self.args.all and (item.type=='lfunction' or (item.tags and item.tags['local'])) then
-- don't add to the module --
elseif doc.project_level(item.type) then
@ -257,9 +252,9 @@ function File:finish()
end
end
elseif item.type == 'submodule' then
local mf
local _
submodule = true
this_mod,mf = self:find_module_in_files(item.name)
this_mod,_ = self:find_module_in_files(item.name)
if this_mod == nil then
self:error("'"..item.name.."' not found for submodule")
end
@ -409,6 +404,7 @@ function File:finish()
-- must be a free-standing function (sometimes a problem...)
end
end
-- luacheck: pop
item.names_hierarchy = require('pl.utils').split(
item.name,
'[.:]'
@ -495,7 +491,6 @@ function Item:set_tag (tag,value)
end
self.tags[tag] = value
elseif ttype == TAG_ID then
local modifiers
if type(value) == 'table' then
if value.append then -- it was a List!
-- such tags are _not_ multiple, e.g. name
@ -506,7 +501,6 @@ function Item:set_tag (tag,value)
end
end
value = value[1]
modifiers = value.modifiers
end
if value == nil then self:error("Tag without value: "..tag) end
local id, rest = tools.extract_identifier(value)
@ -543,17 +537,13 @@ function Item.check_tag(tags,tag, value, modifiers)
if avalue then value = avalue..' '..value end
if amod then
modifiers = modifiers or {}
local value_tokens = utils.split(value)
for m,v in pairs(amod) do
local idx = tonumber(v:match('^%$(%d+)'))
if idx then
v, value = value:match('(%S+)(.*)')
-- v = value_tokens[idx]
-- value_tokens[idx] = ''
end
modifiers[m] = v
end
-- value = table.concat(value_tokens, ' ')
end
else -- has to be a function that at least returns tag, value
return alias(tags,value,modifiers)
@ -927,8 +917,6 @@ function Item:return_type(r)
return r.type, r.ctypes
end
local struct_return_type = '*'
function Item:build_return_groups()
local quote = tools.quote
local modifiers = self.modifiers
@ -1062,8 +1050,6 @@ function Module:hunt_for_reference (packmod, modules)
return mod_ref
end
local err = io.stderr
local function custom_see_references (s)
for pat, action in pairs(see_reference_handlers) do
if s:match(pat) then
@ -1099,7 +1085,7 @@ end
function Module:process_see_reference (s,modules,istype)
if s == nil then return nil end
local mod_ref,fun_ref,name,packmod
local fun_ref
local ref = custom_see_references(s)
if ref then return ref end
if not s:match '^[%w_%.\\%:%-]+$' or not s:match '[%w_]$' then
@ -1301,7 +1287,6 @@ function File:dump(verbose)
end
function Item:dump(verbose)
local tags = self.tags
local name = self.name
if self.type == 'function' then
name = name .. self.args

10
ldoc/html.lua
View File

@ -152,9 +152,9 @@ function html.generate_output(ldoc, args, project)
end
return base..name..'.html'
end
function ldoc.include_file (file)
local text,e = utils.readfile(file)
local text,_ = utils.readfile(file)
if not text then quit("unable to include "..file)
else
return text
@ -212,7 +212,7 @@ function ldoc.source_ref (fun)
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+','')
@ -234,7 +234,7 @@ function ldoc.source_ref (fun)
local types = {}
for name in tp:gmatch("[^|]+") do
local sym = name:match '([%w%.%:]+)'
local ref,err = markup.process_reference(sym,true)
local ref,_ = markup.process_reference(sym,true)
if ref then
if ref.label and sym == name then
name = ref.label
@ -273,7 +273,7 @@ function ldoc.source_ref (fun)
ldoc.doc_charset = (m and m.tags.charset) or ldoc.charset
end
local module_template,err = utils.readfile (path.join(args.template,ldoc.templ))
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

2
ldoc/html/ldoc_new_css.lua
View File

@ -1,5 +1,5 @@
return [[
body {
body {
color: #47555c;
font-size: 16px;
font-family: "Open Sans", sans-serif;

29
ldoc/lang.lua
View File

@ -93,6 +93,7 @@ function Lua:grab_block_comment(v,tok)
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
@ -102,6 +103,7 @@ function Lua:parse_module_call(tok,t,v)
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
@ -150,7 +152,7 @@ function Lua:item_follows(t,v,tok)
case = 1
parser = parse_lua_function_header
elseif t == 'iden' then
local name,t,v = tools.get_fun_name(tok,v)
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]
@ -229,7 +231,7 @@ function Lua:parse_module_modifier (tags, tok, F)
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 t, v = tools.grab_block_comment('',tok,'%]%]')
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
@ -285,12 +287,13 @@ function CC:item_follows (t,v,tok)
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!
t,v = tnext(tok)
_,v = tnext(tok)
end
-- types may have multiple tokens: example, const char *bonzo(...)
local return_type, name = v
t,v = tnext(tok)
_,v = tnext(tok)
name = v
t,v = tnext(tok)
while t ~= '(' do
@ -305,7 +308,7 @@ function CC:item_follows (t,v,tok)
end
tags:add('class','function')
if t == '(' then
tags.formal_args,t,v = tools.get_parameters(tok,')',',',self)
tags.formal_args,t,_ = tools.get_parameters(tok,')',',',self)
if return_type ~= 'void' then
tags.formal_args.return_type = return_type
end
@ -342,30 +345,28 @@ function Moon:item_follows (t,v,tok)
if t == 'iden' then
local name,t,v = tools.get_fun_name(tok,v,'')
if name == 'class' then
name,t,v = tools.get_fun_name(tok,v,'')
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 fat = false
t,v = tnext(tok)
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,v = tools.get_parameters(tok,')',',',self)
tags.formal_args,t,_ = tools.get_parameters(tok,')',',',self)
else
tags.formal_args = List()
end
t,v = tnext(tok)
t,_ = tnext(tok)
tags:add('class','function')
if t == '>' then
--~ tags.formal_args:insert(1,'self')
--~ tags.formal_args.comments = {self=''}
else
if t ~= '>' then
tags.static = true
end
end

2
ldoc/lexer.lua
View File

@ -171,7 +171,7 @@ function lexer.scan (s,matches,filter,options)
end
matches = plain_matches
end
local i1,i2,idx,res1,res2,tok,pat,fun,capt
local i1,i2,tok,pat,fun
local line = 1
if file then
s = file:read()

20
ldoc/markdown.lua
View File

@ -149,9 +149,6 @@ local function map(t, f)
return out
end
-- The identity function, useful as a placeholder.
local function identity(text) return text end
-- Functional style if statement. (NOTE: no short circuit evaluation)
local function iff(t, a, b) if t then return a else return b end end
@ -252,7 +249,7 @@ local function tokenize_html(html)
end
if not stop then
-- error("Could not match html tag " .. html:sub(start,start+30))
table.insert(tokens, {type="text", text=html:sub(start, start)})
table.insert(tokens, {type="text", text=html:sub(start, start)})
pos = start + 1
else
table.insert(tokens, {type="tag", text=html:sub(start, stop)})
@ -641,12 +638,14 @@ local function blockquotes(lines)
local stop = #lines
for i = start+1, #lines do
-- luacheck: push ignore 542
if lines[i].type == "blank" or lines[i].type == "blockquote" then
elseif lines[i].type == "normal" then
if lines[i-1].type == "blank" then stop = i-1 break end
else
stop = i-1 break
end
-- luacheck: pop
end
while lines[stop].type == "blank" do stop = stop - 1 end
return start, stop
@ -766,14 +765,6 @@ function block_transform(text, sublist)
return text
end
-- Debug function for printing a line array to see the result
-- of partial transforms.
local function print_lines(lines)
for i, line in ipairs(lines) do
print(i, line.type, line.text or line.line)
end
end
----------------------------------------------------------------------
-- Span transform
----------------------------------------------------------------------
@ -880,7 +871,6 @@ local function code_spans(s)
pos = stop + 1
end
end
return s
end
-- Encode alt text... enodes &, and ".
@ -1177,10 +1167,12 @@ function OptionParser:run(args)
while pos <= #args do
local arg = args[pos]
if arg == "--" then
-- luacheck: push ignore 512
for i=pos+1,#args do
if self.arg then self.arg(args[i]) end
return true
end
-- luacheck: pop
end
if arg:match("^%-%-") then
local info = self.long[arg:sub(3)]
@ -1229,7 +1221,7 @@ local function run_command_line(arg)
local function run(s, options)
s = markdown(s)
if not options.wrap_header then return s end
local header = ""
local header
if options.header then
local f = io.open(options.header) or error("Could not open file: " .. options.header)
header = f:read("*a")

12
ldoc/markup.lua
View File

@ -7,7 +7,7 @@ local doc = require 'ldoc.doc'
local utils = require 'pl.utils'
local stringx = require 'pl.stringx'
local prettify = require 'ldoc.prettify'
local quit, concat, lstrip = utils.quit, table.concat, stringx.lstrip
local concat = table.concat
local markup = {}
local backtick_references
@ -53,7 +53,7 @@ local function resolve_inline_references (ldoc, txt, item, plain)
end))
if backtick_references then
res = res:gsub('`([^`]+)`',function(name)
local ref,err = markup.process_reference(name)
local ref,_ = markup.process_reference(name)
local label = name
if name and do_escape then
label = name:gsub('_', '\\_')
@ -135,10 +135,10 @@ local function process_multiline_markdown(ldoc, txt, F, filename, deflang)
local function pretty_code (code, lang)
code = concat(code,'\n')
if code ~= '' then
local err
local _
-- If we omit the following '\n', a '--' (or '//') comment on the
-- last line won't be recognized.
code, err = prettify.code(lang,filename,code..'\n',L,false)
code, _ = prettify.code(lang,filename,code..'\n',L,false)
code = resolve_inline_references(ldoc, code, err_item,true)
append(res,'<pre>')
append(res, code)
@ -237,6 +237,7 @@ local formatters =
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
@ -254,12 +255,13 @@ local formatters =
end
else
io.stderr:write('LDoc discount failed with error ',errmsg)
io.exit(1)
os.exit(1)
end
end
else
ok = false
end
-- luacheck: pop
end
if not ok then
print('format: using built-in markdown')

14
ldoc/parse.lua
View File

@ -2,7 +2,7 @@
local utils = require 'pl.utils'
local List = require 'pl.List'
local Map = require 'pl.Map'
-- local Map = require 'pl.Map'
local stringio = require 'pl.stringio'
local lexer = require 'ldoc.lexer'
local tools = require 'ldoc.tools'
@ -161,12 +161,6 @@ local function extract_tags (s,args)
return tags --Map(tags)
end
local _xpcall = xpcall
if true then
_xpcall = function(f) return true, f() end
end
-- parses a Lua or C file, looking for ldoc comments. These are like LuaDoc comments;
-- they start with multiple '-'. (Block commments are allowed)
@ -176,7 +170,6 @@ end
-- module if there isn't an explicit module name specified.
local function parse_file(fname, lang, package, args)
local line,f = 1
local F = File(fname)
local module_found, first_comment = false,true
local current_item, module_item
@ -192,10 +185,7 @@ local function parse_file(fname, lang, package, args)
return tok:lineno()
end
local function filename () return fname end
function F:warning (msg,kind,line)
kind = kind or 'warning'
line = line or lineno()
Item.had_warning = true
io.stderr:write(fname..':'..line..': '..msg,'\n')
@ -307,7 +297,7 @@ local function parse_file(fname, lang, package, args)
module_found = tags.name
-- might be a module returning a single function!
if tags.param or tags['return'] then
local parms, ret, summ = tags.param, tags['return'],tags.summary
local parms, ret = tags.param, tags['return']
local name = tags.name
tags.param = nil
tags['return'] = nil

4
ldoc/prettify.lua
View File

@ -30,8 +30,8 @@ local spans = {keyword=true,number=true,string=true,comment=true,global=true,bac
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, tokenizer = List(), require 'ldoc.lexer'
local tnext = lexer.skipws
local res, lexer = List(), require 'ldoc.lexer'
local tokenizer
local ik = 1
if not cpp_lang[lang] then
tokenizer = lexer.lua

14
ldoc/tools.lua
View File

@ -79,7 +79,7 @@ end
function KindMap:put_kind_first (kind)
-- find this kind in our kind list
local kinds = self.klass.kinds,kind
local kinds = self.klass.kinds
local idx = tablex.find(kinds,kind)
-- and swop with the start!
if idx then
@ -232,8 +232,9 @@ end
function M.check_file (f,original)
if not path.exists(f) or path.getmtime(original) > path.getmtime(f) then
local text,err = utils.readfile(original)
local _
if text then
text,err = utils.writefile(f,text)
_,err = utils.writefile(f,text)
end
if err then
quit("Could not copy "..original.." to "..f)
@ -250,13 +251,12 @@ function M.writefile(name,text)
end
function M.name_of (lpath)
local ext
lpath,ext = path.splitext(lpath)
local _
lpath,_ = path.splitext(lpath)
return lpath
end
function M.this_module_name (basename,fname)
local ext
if basename == '' then
return M.name_of(fname)
end
@ -429,7 +429,7 @@ end
-- Set `colon` to be the secondary separator, '' for none.
function M.get_fun_name (tok,first,colon)
local res = {}
local t,name,sep
local t,name,sep,_
colon = colon or ':'
if not first then
t,name = tnext(tok)
@ -441,7 +441,7 @@ function M.get_fun_name (tok,first,colon)
while sep == '.' or sep == colon do
append(res,name)
append(res,sep)
t,name = tnext(tok)
_,name = tnext(tok)
t,sep = tnext(tok)
end
append(res,name)

38
run-tests.lua
View File

@ -1,18 +1,20 @@
local run
if not arg[1] then
run = function (dir)
local cmd = 'cd '..dir..' && ldoc --testing . && diff -r doc cdocs'
print(cmd)
os.execute(cmd)
end
elseif arg[1] == 'update' then
run = function (dir)
local cmd = 'cd '..dir..' && ldoc --dir cdocs --testing .'
print(cmd)
os.execute(cmd)
end
end
for _,d in ipairs{'tests','tests/example','tests/md-test'} do
run(d)
end
local PWD = os.getenv("PWD")
local run
if not arg[1] then
run = function (dir)
local cmd = 'cd '..dir..' && lua '..PWD..'/ldoc.lua --testing . && diff -r doc cdocs'
print(cmd)
os.execute(cmd)
end
elseif arg[1] == 'update' then
run = function (dir)
local cmd = 'cd '..dir..' && lua '..PWD..'/ldoc.lua --dir cdocs --testing .'
print(cmd)
os.execute(cmd)
end
end
for _,d in ipairs{'tests','tests/example','tests/md-test'} do
run(d)
end