From 8a683f51ba7abc0284d2cbd22908c7784913b65d Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 20:26:16 +0300 Subject: [PATCH 01/15] chore: Setup luacheck config file for project --- .luacheckrc | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .luacheckrc diff --git a/.luacheckrc b/.luacheckrc new file mode 100644 index 0000000..681b66a --- /dev/null +++ b/.luacheckrc @@ -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", +} From 144199119b79888c04b859b75d277d2b1483a5c0 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 20:26:41 +0300 Subject: [PATCH 02/15] ci: Add CI job that runs Lua linter --- .github/workflows/luacheck.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .github/workflows/luacheck.yml diff --git a/.github/workflows/luacheck.yml b/.github/workflows/luacheck.yml new file mode 100644 index 0000000..675b3ce --- /dev/null +++ b/.github/workflows/luacheck.yml @@ -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 From 6118163064d73024abd88577aab765b23c91164a Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 20:27:48 +0300 Subject: [PATCH 03/15] chore: Add status badge for linter to readme --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 0f3dbf0..0f8b6bb 100644 --- a/README.md +++ b/README.md @@ -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 From 6ef3a8ccc3c1267d253ef048b1955e10123ee1ee Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 21:41:56 +0300 Subject: [PATCH 04/15] feat: Add make target to generate test 'before' condition' --- Makefile | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 4fe351e..258699e 100644 --- a/Makefile +++ b/Makefile @@ -30,17 +30,20 @@ test: test-basic test-example test-md test-tables RUN=&& ldoc . && diff -r docs 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 From c780179897a5c8bd6af1bbc179577e7d95276d1f Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 20:29:21 +0300 Subject: [PATCH 05/15] =?UTF-8?q?style:=20Fix=20file=20encoding,=20dos?= =?UTF-8?q?=E2=86=92unix=20line=20endings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ldoc/builtin/debug.lua | 248 +++++++++++++------------- ldoc/builtin/global.lua | 10 +- ldoc/builtin/io.lua | 318 ++++++++++++++++----------------- ldoc/builtin/string.lua | 382 ++++++++++++++++++++-------------------- ldoc/builtin/table.lua | 86 ++++----- ldoc/builtin/utf8.lua | 52 +++--- run-tests.lua | 36 ++-- 7 files changed, 565 insertions(+), 567 deletions(-) diff --git a/ldoc/builtin/debug.lua b/ldoc/builtin/debug.lua index 981a638..b59926f 100644 --- a/ldoc/builtin/debug.lua +++ b/ldoc/builtin/debug.lua @@ -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, 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 diff --git a/ldoc/builtin/global.lua b/ldoc/builtin/global.lua index c9aabe5..1234835 100644 --- a/ldoc/builtin/global.lua +++ b/ldoc/builtin/global.lua @@ -69,17 +69,17 @@ 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 -- 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" diff --git a/ldoc/builtin/io.lua b/ldoc/builtin/io.lua index 28253df..44a827a 100644 --- a/ldoc/builtin/io.lua +++ b/ldoc/builtin/io.lua @@ -1,159 +1,159 @@ ---- 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 = {} + +--- +-- 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 diff --git a/ldoc/builtin/string.lua b/ldoc/builtin/string.lua index 73b4cc4..c80c210 100644 --- a/ldoc/builtin/string.lua +++ b/ldoc/builtin/string.lua @@ -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(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 + diff --git a/ldoc/builtin/table.lua b/ldoc/builtin/table.lua index fb88fdf..94852e5 100644 --- a/ldoc/builtin/table.lua +++ b/ldoc/builtin/table.lua @@ -1,44 +1,44 @@ ---- 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 + --- -- Returns the elements from the given table. This function is equivalent to -- return list[i], list[i+1], ..., list[j] @@ -46,5 +46,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 diff --git a/ldoc/builtin/utf8.lua b/ldoc/builtin/utf8.lua index a96f3c6..c3af02e 100644 --- a/ldoc/builtin/utf8.lua +++ b/ldoc/builtin/utf8.lua @@ -1,48 +1,46 @@ ---- 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 diff --git a/run-tests.lua b/run-tests.lua index 6d10a7d..26e4f64 100644 --- a/run-tests.lua +++ b/run-tests.lua @@ -1,18 +1,18 @@ -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 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 From 59b728ca200e894adf46d2125b73d76192d77213 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Thu, 1 Oct 2020 14:58:40 +0300 Subject: [PATCH 06/15] style: Cleanup whitespace --- ldoc/builtin/global.lua | 4 ++-- ldoc/builtin/string.lua | 2 +- ldoc/html.lua | 4 ++-- ldoc/html/ldoc_new_css.lua | 2 +- ldoc/markdown.lua | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/ldoc/builtin/global.lua b/ldoc/builtin/global.lua index 1234835..157cce3 100644 --- a/ldoc/builtin/global.lua +++ b/ldoc/builtin/global.lua @@ -4,7 +4,7 @@ module 'global' --- -- 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 @@ -71,7 +71,7 @@ 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 +-- 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; diff --git a/ldoc/builtin/string.lua b/ldoc/builtin/string.lua index c80c210..e4032aa 100644 --- a/ldoc/builtin/string.lua +++ b/ldoc/builtin/string.lua @@ -177,7 +177,7 @@ function string.upper(s) end function string.pack (fmt, v1, v2, ···) end --- --- (5.3) Returns the size of a string resulting from string.pack with the given format. +-- (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 diff --git a/ldoc/html.lua b/ldoc/html.lua index d1eb888..80e7a59 100644 --- a/ldoc/html.lua +++ b/ldoc/html.lua @@ -152,7 +152,7 @@ function html.generate_output(ldoc, args, project) end return base..name..'.html' end - + function ldoc.include_file (file) local text,e = utils.readfile(file) if not text then quit("unable to include "..file) @@ -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+','') diff --git a/ldoc/html/ldoc_new_css.lua b/ldoc/html/ldoc_new_css.lua index 30191ab..eb57e9b 100644 --- a/ldoc/html/ldoc_new_css.lua +++ b/ldoc/html/ldoc_new_css.lua @@ -1,5 +1,5 @@ return [[ -body { +body { color: #47555c; font-size: 16px; font-family: "Open Sans", sans-serif; diff --git a/ldoc/markdown.lua b/ldoc/markdown.lua index 96d9b31..456b64e 100644 --- a/ldoc/markdown.lua +++ b/ldoc/markdown.lua @@ -252,7 +252,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)}) From 874d845ee97e56ca151f4cdf3ec211aa8a9ce0d8 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 21:22:07 +0300 Subject: [PATCH 07/15] fix: Use current repository ldoc for tests, not system installed one --- Makefile | 6 ++++-- run-tests.lua | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 258699e..5e3e3f2 100644 --- a/Makefile +++ b/Makefile @@ -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,7 +30,7 @@ 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 docs cdocs && echo ok test-prep: find -type d -name doc -execdir rsync -av --del {}/ cdocs/ \; @@ -47,7 +49,7 @@ test-tables: 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 docs cdocs clean-basic: cd tests $(CLEAN) diff --git a/run-tests.lua b/run-tests.lua index 26e4f64..062c431 100644 --- a/run-tests.lua +++ b/run-tests.lua @@ -1,13 +1,15 @@ +local PWD = os.getenv("PWD") + local run if not arg[1] then run = function (dir) - local cmd = 'cd '..dir..' && ldoc --testing . && diff -r doc cdocs' + 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..' && ldoc --dir cdocs --testing .' + local cmd = 'cd '..dir..' && lua '..PWD..'/ldoc.lua --dir cdocs --testing .' print(cmd) os.execute(cmd) end From 12a981491179afdf286bd16aa558b7f32674d953 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 21:36:57 +0300 Subject: [PATCH 08/15] fix: Test targets compare non-existent directory --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 5e3e3f2..dade791 100644 --- a/Makefile +++ b/Makefile @@ -30,7 +30,7 @@ uninstall: test: test-basic test-example test-md test-tables -RUN=&& lua $(_REPODIR)/ldoc.lua . && 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/ \; @@ -49,7 +49,7 @@ test-tables: test-clean: clean-basic clean-example clean-md clean-tables -CLEAN=&& lua $(_REPODIR)/ldoc.lua . && 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) From f70542c626864d5b136cbf25d1d8cb2927e1ddd1 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 21:51:48 +0300 Subject: [PATCH 09/15] refactor: Remove unused require()s --- ldoc/parse.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ldoc/parse.lua b/ldoc/parse.lua index 9292b56..dc83a43 100644 --- a/ldoc/parse.lua +++ b/ldoc/parse.lua @@ -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' From f1b3f76aca135b9fb626af19127702a923f1bb92 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 21:54:15 +0300 Subject: [PATCH 10/15] refactor: Remove what seems to be unused debug cruft --- ldoc.lua | 10 +++------- ldoc/doc.lua | 12 ------------ ldoc/lang.lua | 5 +---- ldoc/markdown.lua | 11 ----------- ldoc/parse.lua | 8 -------- 5 files changed, 4 insertions(+), 42 deletions(-) diff --git a/ldoc.lua b/ldoc.lua index e39254e..1cd9f54 100644 --- a/ldoc.lua +++ b/ldoc.lua @@ -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' @@ -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 @@ -277,7 +275,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 +284,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 +299,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 +313,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 +334,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() diff --git a/ldoc/doc.lua b/ldoc/doc.lua index d5d4584..b272cd5 100644 --- a/ldoc/doc.lua +++ b/ldoc/doc.lua @@ -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 @@ -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 diff --git a/ldoc/lang.lua b/ldoc/lang.lua index f42c1de..afec061 100644 --- a/ldoc/lang.lua +++ b/ldoc/lang.lua @@ -362,10 +362,7 @@ function Moon:item_follows (t,v,tok) end t,v = 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 diff --git a/ldoc/markdown.lua b/ldoc/markdown.lua index 456b64e..cce10d1 100644 --- a/ldoc/markdown.lua +++ b/ldoc/markdown.lua @@ -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 @@ -766,14 +763,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 ---------------------------------------------------------------------- diff --git a/ldoc/parse.lua b/ldoc/parse.lua index dc83a43..5c84be4 100644 --- a/ldoc/parse.lua +++ b/ldoc/parse.lua @@ -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) @@ -192,8 +186,6 @@ 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() From 92a6714d9adf10c4234bcb3def1a04e889762ba9 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 30 Sep 2020 21:45:22 +0300 Subject: [PATCH 11/15] refactor: Drop completely unused variable references --- ldoc.lua | 2 +- ldoc/doc.lua | 11 +++-------- ldoc/html.lua | 6 +++--- ldoc/lang.lua | 22 ++++++++++++---------- ldoc/lexer.lua | 2 +- ldoc/markdown.lua | 2 +- ldoc/markup.lua | 8 ++++---- ldoc/parse.lua | 4 +--- ldoc/prettify.lua | 4 ++-- ldoc/tools.lua | 14 +++++++------- 10 files changed, 35 insertions(+), 40 deletions(-) diff --git a/ldoc.lua b/ldoc.lua index 1cd9f54..8ba58ec 100644 --- a/ldoc.lua +++ b/ldoc.lua @@ -90,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 diff --git a/ldoc/doc.lua b/ldoc/doc.lua index b272cd5..e5e0606 100644 --- a/ldoc/doc.lua +++ b/ldoc/doc.lua @@ -251,9 +251,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 @@ -489,7 +489,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 @@ -500,7 +499,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) @@ -1050,8 +1048,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 @@ -1087,7 +1083,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 @@ -1289,7 +1285,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 diff --git a/ldoc/html.lua b/ldoc/html.lua index 80e7a59..3e3d1cf 100644 --- a/ldoc/html.lua +++ b/ldoc/html.lua @@ -154,7 +154,7 @@ function html.generate_output(ldoc, args, project) 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 @@ -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 diff --git a/ldoc/lang.lua b/ldoc/lang.lua index afec061..7dc07b9 100644 --- a/ldoc/lang.lua +++ b/ldoc/lang.lua @@ -150,7 +150,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 +229,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 +285,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 +306,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,25 +343,26 @@ 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.static = true diff --git a/ldoc/lexer.lua b/ldoc/lexer.lua index c04a504..aafb07d 100644 --- a/ldoc/lexer.lua +++ b/ldoc/lexer.lua @@ -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() diff --git a/ldoc/markdown.lua b/ldoc/markdown.lua index cce10d1..7a6a9a1 100644 --- a/ldoc/markdown.lua +++ b/ldoc/markdown.lua @@ -1218,7 +1218,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") diff --git a/ldoc/markup.lua b/ldoc/markup.lua index d080c16..90cb86d 100644 --- a/ldoc/markup.lua +++ b/ldoc/markup.lua @@ -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,'
')
          append(res, code)
diff --git a/ldoc/parse.lua b/ldoc/parse.lua
index 5c84be4..fe6e96e 100644
--- a/ldoc/parse.lua
+++ b/ldoc/parse.lua
@@ -170,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
@@ -187,7 +186,6 @@ local function parse_file(fname, lang, package, args)
    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')
@@ -299,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
diff --git a/ldoc/prettify.lua b/ldoc/prettify.lua
index a57eddc..1dc625c 100644
--- a/ldoc/prettify.lua
+++ b/ldoc/prettify.lua
@@ -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
diff --git a/ldoc/tools.lua b/ldoc/tools.lua
index c716bf4..6918dab 100644
--- a/ldoc/tools.lua
+++ b/ldoc/tools.lua
@@ -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)

From a3e8db19de685fbf1e24504b6d659cd9254e3018 Mon Sep 17 00:00:00 2001
From: Caleb Maclennan 
Date: Thu, 1 Oct 2020 14:55:35 +0300
Subject: [PATCH 12/15] =?UTF-8?q?fix:=20Fix=20bug=20in=20error=20handler,?=
 =?UTF-8?q?=20io.exit()=E2=86=92os.exit()?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ldoc/markup.lua | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ldoc/markup.lua b/ldoc/markup.lua
index 90cb86d..31050d0 100644
--- a/ldoc/markup.lua
+++ b/ldoc/markup.lua
@@ -254,7 +254,7 @@ local formatters =
                   end
                else
                   io.stderr:write('LDoc discount failed with error ',errmsg)
-                  io.exit(1)
+                  os.exit(1)
                end
             end
          else

From f979400edb5fa86227ee119df93e42b66d0cdbee Mon Sep 17 00:00:00 2001
From: Caleb Maclennan 
Date: Thu, 1 Oct 2020 14:54:02 +0300
Subject: [PATCH 13/15] chore: Add lint ignore overrides for warnings that get
 a pass

Mostly because refactoring these is hard, double negatives are much
harder to follow logic wise and there isn't much point in refactoring
these loops unless they need other work.
---
 ldoc.lua                | 2 ++
 ldoc/builtin/global.lua | 2 ++
 ldoc/builtin/table.lua  | 2 ++
 ldoc/doc.lua            | 2 ++
 ldoc/lang.lua           | 2 ++
 ldoc/markdown.lua       | 5 ++++-
 ldoc/markup.lua         | 2 ++
 7 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/ldoc.lua b/ldoc.lua
index 8ba58ec..907c4fb 100644
--- a/ldoc.lua
+++ b/ldoc.lua
@@ -263,7 +263,9 @@ local function loadstr (ldoc,txt)
       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
diff --git a/ldoc/builtin/global.lua b/ldoc/builtin/global.lua
index 157cce3..e927067 100644
--- a/ldoc/builtin/global.lua
+++ b/ldoc/builtin/global.lua
@@ -2,6 +2,8 @@
 
 module 'global'
 
+-- luacheck: ignore 121
+
 ---
 -- Issues an error when  its argument `v` is false.
 -- That is, nil or false. otherwise, returns all its arguments.
diff --git a/ldoc/builtin/table.lua b/ldoc/builtin/table.lua
index 94852e5..b4b7d80 100644
--- a/ldoc/builtin/table.lua
+++ b/ldoc/builtin/table.lua
@@ -39,6 +39,8 @@ function table.pack (···) end
 -- 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]
diff --git a/ldoc/doc.lua b/ldoc/doc.lua
index e5e0606..c4908c9 100644
--- a/ldoc/doc.lua
+++ b/ldoc/doc.lua
@@ -230,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
@@ -403,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,
         '[.:]'
diff --git a/ldoc/lang.lua b/ldoc/lang.lua
index 7dc07b9..4ef1859 100644
--- a/ldoc/lang.lua
+++ b/ldoc/lang.lua
@@ -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
diff --git a/ldoc/markdown.lua b/ldoc/markdown.lua
index 7a6a9a1..2044bb7 100644
--- a/ldoc/markdown.lua
+++ b/ldoc/markdown.lua
@@ -638,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
@@ -869,7 +871,6 @@ local function code_spans(s)
 			pos = stop + 1
 		end
 	end
-	return s
 end
 
 -- Encode alt text... enodes &, and ".
@@ -1166,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)]
diff --git a/ldoc/markup.lua b/ldoc/markup.lua
index 31050d0..425fb07 100644
--- a/ldoc/markup.lua
+++ b/ldoc/markup.lua
@@ -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
@@ -260,6 +261,7 @@ local formatters =
          else
             ok = false
          end
+         -- luacheck: pop
       end
       if not ok then
          print('format: using built-in markdown')

From 42311877f0f62ac94e70d01193b1ab4ddbd14cda Mon Sep 17 00:00:00 2001
From: Caleb Maclennan 
Date: Thu, 1 Oct 2020 15:36:50 +0300
Subject: [PATCH 14/15] fix: Fix builtin module doc's invalid syntax

These are kind of pseudo code, but there doesn't seem to be any reason
to use bogus Lua syntax either.
---
 ldoc/builtin/debug.lua  | 10 +++++-----
 ldoc/builtin/global.lua |  6 +++---
 ldoc/builtin/io.lua     |  3 +++
 ldoc/builtin/string.lua |  6 +++---
 ldoc/builtin/table.lua  |  2 +-
 ldoc/builtin/utf8.lua   |  8 +++++---
 6 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/ldoc/builtin/debug.lua b/ldoc/builtin/debug.lua
index b59926f..6121a8f 100644
--- a/ldoc/builtin/debug.lua
+++ b/ldoc/builtin/debug.lua
@@ -43,18 +43,18 @@ function debug.gethook(thread) end
 -- 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
+function debug.getinfo(thread, func , 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
+-- 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, local) end
+function debug.getlocal(thread, level, loc) end
 
 ---
 -- Returns the metatable of the given `object` or nil if it does not have
@@ -103,12 +103,12 @@ 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
+-- 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, local, value) end
+function debug.setlocal(thread, level, loc, value) end
 
 ---
 -- Sets the metatable for the given `object` to the given `table` (which
diff --git a/ldoc/builtin/global.lua b/ldoc/builtin/global.lua
index e927067..b1799c3 100644
--- a/ldoc/builtin/global.lua
+++ b/ldoc/builtin/global.lua
@@ -85,12 +85,12 @@ function ipairs(t) end
 -- 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
@@ -180,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.
diff --git a/ldoc/builtin/io.lua b/ldoc/builtin/io.lua
index 44a827a..c97cb4e 100644
--- a/ldoc/builtin/io.lua
+++ b/ldoc/builtin/io.lua
@@ -3,6 +3,9 @@
 
 local io = {}
 
+-- luacheck: ignore 241
+local file = {}
+
 ---
 -- Equivalent to `file:close()`. Without a `file`, closes the default
 -- output file.
diff --git a/ldoc/builtin/string.lua b/ldoc/builtin/string.lua
index e4032aa..cb4d2eb 100644
--- a/ldoc/builtin/string.lua
+++ b/ldoc/builtin/string.lua
@@ -21,7 +21,7 @@ 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
+function string.dump(func) end
 
 ---
 -- Looks for the first match of `pattern` in the string `s`. If it finds a
@@ -174,7 +174,7 @@ 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
+function string.pack (fmt, v1, v2, ...) end
 
 ---
 -- (5.3) Returns the size of a string resulting from string.pack with the given format.
@@ -185,7 +185,7 @@ 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
+function string.unpack (fmt, s , pos) end
 
 return string
 
diff --git a/ldoc/builtin/table.lua b/ldoc/builtin/table.lua
index b4b7d80..92704e7 100644
--- a/ldoc/builtin/table.lua
+++ b/ldoc/builtin/table.lua
@@ -29,7 +29,7 @@ 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
+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
diff --git a/ldoc/builtin/utf8.lua b/ldoc/builtin/utf8.lua
index c3af02e..ec91c4f 100644
--- a/ldoc/builtin/utf8.lua
+++ b/ldoc/builtin/utf8.lua
@@ -25,13 +25,13 @@ 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
+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
+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.
@@ -43,4 +43,6 @@ function utf8.len (s [, i [, j]]) 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
+function utf8.offset (s, n , i) end
+
+return utf8

From ce1229b434c4f8447e92fd0b12288cd4fd4ed24d Mon Sep 17 00:00:00 2001
From: Caleb Maclennan 
Date: Thu, 1 Oct 2020 15:55:53 +0300
Subject: [PATCH 15/15] refactor: Don't assign scope to variable from Lua VM

---
 ldoc.lua | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/ldoc.lua b/ldoc.lua
index 907c4fb..87efd9a 100644
--- a/ldoc.lua
+++ b/ldoc.lua
@@ -256,11 +256,10 @@ 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