Commit ce2d6b80d473470ec9528bfef33003bcfb371bbc - lua-ldoc

+27

-0

changes.md less more

	0	## Version 1.4.4
	1
	2	### Features
	3	* better Lua 5.3 support
	4	* handles tables with integer_keys as well as string keys
	5	* `--testing` - version and date does not change
	6	* `--no_args_infer` to completely switch off argument inference and parsing
	7	* `custom_csv` option to specify extra CSS file
	8	* explicit warnings if we cannot deduce item from following code
	9	* modules may return a single _function_ (see tests/funmod.lua)
	10	* honours the `SOURCE_DATE_EPOCH` environment variable
	11	* Moonscript fat arrow and auto-assign ctor support
	12	* Better Discount support. All varieties including Debian lua-discount package (binding to libmarkdown2)
	13	* prettier output for `ldoc -m` on Unix
	14	* updated global builtin documentation
	15
	16
	17	### Fixes
	18	* consistently using Unix line-endings
	19	* `--fatalwarnings` now also works with parser errors (#255)
	20	* user-specific temporary directory for expanding templates
	21	* blank line after comment of code block suppressed (#240)
	22	* comments at end of code blocks were not highlighting
	23	* strip left spaces from usage code (#191)
	24	* don't parse `module` if it's a field name (e.g `foo.module()`)
	25	* temporary files on Windows fix
	26
0	27	## Version 1.4.3
1	28
2	29	### Features

+91

-118

doc/doc.md less more

17	17	Otherwise, the output is very similar, which is no accident since the HTML templates are
18	18	based directly on LuaDoc. You can ship your own customized templates and style sheets with
19	19	your [own project](http://nilnor.github.com/textui/docs/) (also see Graham Hannington's
20		documentation for [Lua for z/OS](lua4z.com/doc/)). LDoc comes with three extra themes; 'pale'
	20	documentation for [Lua for z/OS](http://lua4z.com/doc/)). LDoc comes with three extra themes; 'pale'
21	21	for those who like whitespace, 'one' for one-column output, and 'fixed' for a fixed navigation
22	22	bar down the left side.
23	23

91	91	* @classmod Like @module but describing a class
92	92	* @submodule A file containing definitions that you wish to put into the named _master_ module
93	93	* @script A Lua program
94		* @author (multiple), copyright, @license, @release only used for _project-level_ tags like @module
	94	* @author (multiple), @copyright, @license, @release only used for _project-level_ tags like @module
95	95	* @function, @lfunction. Functions inside a module
96	96	* @param formal arguments of a function (multiple)
97	97	* @return returned values of a function (multiple)

250	250
251	251	### Doing modules the Lua 5.1 way
252	252
253		As an alternative to using the 'module' tag as described before, you
	253	As an alternative to using the 'module' tag as described previously, you
254	254	can still start your modules the Lua 5.1 way:
255	255
256	256	--- solvers for common equations.

260	260	common to see less 'magic' ways of creating modules, as seen in the description
261	261	of the 'module' tag previously with the explicitely returned module table.
262	262
263		#### Repeating tags
	263	### Repeating tags
264	264
265	265	Tags like 'param' and 'return' can be specified multiple times, whereas a type
266	266	tag like 'function' can only occur once in a comment.

310	310	--- we need to give a hint here for foo
311	311	-- @local here
312	312	function foo(...) .. end
313
	313
314	314	### Alternative way of specifying tags
315	315
316	316	Since 1.3, LDoc allows the use of _colons_ instead of @.
317	317
318	318	--- a simple function.
319		-- string name person's name
	319	-- string: name person's name
320	320	-- int: age age of person
321	321	-- !person: person object
322	322	-- treturn: ?string

328	328
329	329	(see @{colon.lua}, rendered [here](http://stevedonovan.github.io/ldoc/examples/colon))
330	330
331		### Which files are processed
	331	## Sections
	332
	333	LDoc supports _explicit_ sections. By default, the implicit sections correspond to the pre-existing
	334	types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
	335	'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new
	336	sections can be added; the first mechanism is when you @{Adding_new_Tags\|define a new type}
	337	(say 'macro'). Then a new section ('Macros') is created to contain these types.
	338
	339	There is also a way to declare ad-hoc sections using the @section tag.
	340	The need occurs when a module has a lot of functions that need to be put into logical
	341	sections.
	342
	343	--- File functions.
	344	-- Useful utilities for opening foobar format files.
	345	-- @section file
	346
	347	--- open a file
	348	...
	349
	350	--- read a file
	351	...
	352
	353	--- Encoding operations.
	354	-- Encoding foobar output in different ways.
	355	-- @section encoding
	356
	357	...
	358
	359	A section doc-comment has the same structure as a normal doc-comment; the summary is used as
	360	the new section title, and the description will be output at the start of the function
	361	details for that section; the name is not used, but must be unique.
	362
	363	Sections appear under 'Contents' on the left-hand side. See the
	364	[winapi](http://stevedonovan.github.com/winapi/api.html) documentation for an example of how
	365	this looks.
	366
	367	Arguably a module writer should not write such very long modules, but it is not the job of
	368	the documentation tool to limit the programmer!
	369
	370	A specialized kind of section is `type`: it is used for documenting classes. The functions
	371	(or fields) within a type section are considered to be the methods of that class.
	372
	373	--- A File class.
	374	-- @type File
	375
	376	....
	377	--- get the modification time.
	378	-- @return standard time since epoch
	379	function File:mtime()
	380	...
	381	end
	382
	383	(In an ideal world, we would use the word 'class' instead of 'type', but this would conflict
	384	with the LuaDoc `class` tag.)
	385
	386	A section continues until the next section is found, `@section end`, or end of file.
	387
	388	You can put items into _implicit sections_ using @within. This allows you to put
	389	adjacent functions in different sections, so that you are not forced to order your code
	390	in a particular way.
	391
	392	With 1.4, there is another option for documenting classes, which is the top-level type
	393	`classmod`. It is intended for larger classes which are implemented within one module,
	394	and the advantage that methods can be put into sections.
	395
	396	Sometimes a module may logically span several files, which can easily happen with large
	397	There will be a master module with name
	398	'foo' and other files which when required add functions to that module. If these files have
	399	a @submodule tag, their contents will be placed in the master module documentation. However,
	400	a current limitation is that the master module must be processed before the submodules.
	401
	402	See the `tests/submodule` example for how this works in practice.
	403
	404	## Which files are processed?
332	405
333	406	By default, LDoc will process any file ending in '.lua' or '.luadoc' in a specified
334	407	directory; you may point it to a single file as well. A 'project' usually consists of many

345	418
346	419	If you want to document scripts, then use @script instead of @module. New with 1.4 is
347	420	@classmod which is a module which exports a single class.
348
349	421
350	422	## See References
351	423

491	563	the template is expanded. Generally configuration variables that effect template expansion
492	564	are modifiable in this way. For instance, if you wish that the contents of a particular module
493	565	be sorted, then `@set sort=true` will do it _just_ for that module.
494
495		## Sections
496
497		LDoc supports _explicit_ sections. By default, the implicit sections correspond to the pre-existing
498		types in a module: 'Functions', 'Tables' and 'Fields' (There is another default section
499		'Local Functions' which only appears if LDoc is invoked with the `--all` flag.) But new
500		sections can be added; the first mechanism is when you @{Adding_new_Tags\|define a new type}
501		(say 'macro'). Then a new section ('Macros') is created to contain these types.
502
503		There is also a way to declare ad-hoc sections using the @section tag.
504		The need occurs when a module has a lot of functions that need to be put into logical
505		sections.
506
507		--- File functions.
508		-- Useful utilities for opening foobar format files.
509		-- @section file
510
511		--- open a file
512		...
513
514		--- read a file
515		...
516
517		--- Encoding operations.
518		-- Encoding foobar output in different ways.
519		-- @section encoding
520
521		...
522
523		A section doc-comment has the same structure as a normal doc-comment; the summary is used as
524		the new section title, and the description will be output at the start of the function
525		details for that section; the name is not used, but must be unique.
526
527		Sections appear under 'Contents' on the left-hand side. See the
528		[winapi](http://stevedonovan.github.com/winapi/api.html) documentation for an example of how
529		this looks.
530
531		Arguably a module writer should not write such very long modules, but it is not the job of
532		the documentation tool to limit the programmer!
533
534		A specialized kind of section is `type`: it is used for documenting classes. The functions
535		(or fields) within a type section are considered to be the methods of that class.
536
537		--- A File class.
538		-- @type File
539
540		....
541		--- get the modification time.
542		-- @return standard time since epoch
543		function File:mtime()
544		...
545		end
546
547		(In an ideal world, we would use the word 'class' instead of 'type', but this would conflict
548		with the LuaDoc `class` tag.)
549
550		A section continues until the next section is found, `@section end`, or end of file.
551
552		You can put items into an implicit section using @within. This allows you to put
553		adjacent functions in different sections, so that you are not forced to order your code
554		in a particular way.
555
556		With 1.4, there is another option for documenting classes, which is the top-level type
557		`classmod`. It is intended for larger classes which are implemented within one module,
558		and the advantage that methods can be put into sections.
559
560		Sometimes a module may logically span several files, which can easily happen with large
561		There will be a master module with name
562		'foo' and other files which when required add functions to that module. If these files have
563		a @submodule tag, their contents will be placed in the master module documentation. However,
564		a current limitation is that the master module must be processed before the submodules.
565
566		See the `tests/submodule` example for how this works in practice.
567
568		## Differences from LuaDoc
569
570		LDoc only does 'module' documentation, so the idea of 'files' is redundant.
571
572		One added convenience is that it is easier to name entities:
573
574		------------
575		-- a simple module.
576		-- (LuaDoc)
577		-- @class module
578		-- @name simple
579
580		becomes:
581
582		------------
583		-- a simple module.
584		-- (LDoc)
585		-- @module simple
586
587		This is because type names (like 'function', 'module', 'table', etc) can function as tags.
588		LDoc also provides a means to add new types (e.g. 'macro') using a configuration file which
589		can be shipped with the source. If you become bored with typing 'param' repeatedly then you
590		can define an alias for it, such as 'p'. This can also be specified in the configuration file.
591
592		LDoc will also work with C/C++ files, since extension writers clearly have the same
593		documentation needs as Lua module writers.
594
595		LDoc allows you to attach a _type_ to a parameter or return value with `tparam` or `treturn`,
596		and gives the documenter the option to use Markdown to parse the contents of comments.
597		You may also include code examples which will be prettified, and readme files which will be
598		rendered with Markdown and contain prettified code blocks.
599	566
600	567	## Adding new Tags
601	568

721	688
722	689	1.4 introduces basic support for [Moonscript](http://moonscript.org). Moonscript module
723	690	conventions are just the same as Lua, except for an explicit class construct.
724		@{list.moon} shows how @classmod can declare modules that export one class, with metamethods
	691	@{List.moon} shows how @classmod can declare modules that export one class, with metamethods
725	692	and methods put implicitly into a separate section.
726	693
727	694	## Basic Usage

1246	1213	when using Markdown. When explicit will expand non-references in backticks into `<code>` elements
1247	1214	- `plain` set to true if `format` is set but you don't want code comments processed
1248	1215	- `wrap` set to true if you want to allow long names to wrap in the summaries
1249		- `manual_url` point to an alternative or local location for the Lua manual, e.g.
1250		'file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'
	1216	- `manual_url(url)` point to an alternative or local location for the Lua manual, e.g.
	1217	'manual_url file:///D:/dev/lua/projects/lua-5.1.4/doc/manual.html'. Remember it is a function!
1251	1218	- `no_summary` suppress the Contents summary
1252	1219	- `custom_tags` define some new tags, which will be presented after the function description.
1253	1220	The format is `{<name>,[title=<name>,}{hidden=false,}{format=nil}}`. For instance
1254	1221	`custom_tags={'remark',title='Remarks'}` will add a little `Remarks` section to the docs for any function
1255	1222	containing this tag. `format` can be a function - if not present the default formatter will be used,
1256	1223	e.g. Markdown
1257		- `custom_see_handler` function that filters see-references
1258		- `custom_display_name_handler` function that formats an item's name. The arguments are the item
	1224	- `custom_see_handler(pat,handler)` function that filters see-references
	1225	- `custom_display_name_handler(item, default_handler)` function that formats an item's name. The arguments are the item
1259	1226	and the default function used to format the name. For example, to show an icon or label beside any
1260	1227	function tagged with a certain tag:
1261	1228

1274	1241	- `no_space_before_args` set to `true` if you do not want a space between a function's name and its arguments.
1275	1242	- `template_escape` overrides the usual '#' used for Lua code in templates.
1276	1243	This needs to be changed if the output format is Markdown, for instance.
	1244	- `user_keywords` A list of keywords that will be marked in "prettified" code. Useful if
	1245	you want to display your own functions in a special way. Each keyword may be styled differently
	1246	(using CSS). Only works when `pretty` is set to 'lua' (the default).
	1247	- `postprocess_html` function that allows a last-minute modification to the produced HTML page.
	1248	The arguments are the raw HTML that's intended to be written out (a string), and the module object.
	1249	The string this function returns will be what's actually gets written out.
1277	1250
1278	1251	_Available functions are:_
1279	1252

+46

-90

ldoc/builtin/global.lua less more

2	2	module 'global'
3	3
4	4	---
5		-- Issues an error when the value of its argument `v` is false (i.e.,
6		-- nil or false); otherwise, returns all its arguments. `message` is an error
7		-- message; when absent, it defaults to "assertion failed!"
	5	-- Issues an error when its argument `v` is false.
	6	-- That is, nil or false. otherwise, returns all its arguments.
	7	-- `message` is an error when absent, it defaults to "assertion failed!"
8	8	function assert(v , message) end
9	9
10	10	---

20	20	-- want to control the step size you must experimentally tune the value of
21	21	-- * "arg". Returns true if the step finished a collection cycle.
22	22	-- * "setpause": sets `arg` as the new value for the pause of the collector
23		-- (see §2.10). Returns the previous value for pause.
	23	-- (see 2.10). Returns the previous value for pause.
24	24	-- * "setstepmul": sets `arg` as the new value for the step multiplier
25		-- of the collector (see §2.10). Returns the previous value for step.
	25	-- of the collector (see 2.10). Returns the previous value for step.
26	26	--
27	27	function collectgarbage(opt , arg) end
28	28

35	35	function dofile(filename) end
36	36
37	37	---
38		-- Terminates the last protected function called and returns `message`
39		-- as the error message. Function `error` never returns.
	38	-- Terminates the last protected function called.
	39	-- Returns `message` as the error message.
	40	-- Function `error` never returns.
40	41	-- Usually, `error` adds some information about the error position at the
41	42	-- beginning of the message. The `level` argument specifies how to get the
42	43	-- error position. With level 1 (the default), the error position is where the

48	49	---
49	50	-- A global variable (not a function) that holds the global environment
50	51	-- (that is, `_G._G = _G`). Lua itself does not use this variable; changing
51		-- its value does not affect any environment, nor vice-versa. (Use `setfenv`
52		-- to change environments.)
53		-- function _G end
54		-- * `_G._G`: _G._G
55
56		---
57		-- Returns the current environment in use by the function.
58		-- `f` can be a Lua function or a number that specifies the function at that
59		-- stack level: Level 1 is the function calling `getfenv`. If the given
60		-- function is not a Lua function, or if `f` is 0, `getfenv` returns the
61		-- global environment. The default for `f` is 1.
62		function getfenv(f) end
	52	-- its value does not affect any environment, nor vice-versa. (Set `__ENV`
	53	-- to change environments in functions)
	54	-- @table _G
63	55
64	56	---
65	57	-- If `object` does not have a metatable, returns nil. Otherwise, if the

68	60	function getmetatable(object) end
69	61
70	62	---
71		-- Returns three values: an iterator function, the table `t`, and 0,
	63	-- For iterating over sequences. Returns three values: an iterator function, the table `t`, and 0,
72	64	-- so that the construction
73	65	-- for i,v in ipairs(t) do body end
74	66	-- will iterate over the pairs (`1,t[1]`), (`2,t[2]`), ..., up to the

76	68	function ipairs(t) end
77	69
78	70	---
79		-- Loads a chunk using function `func` to get its pieces. Each call to
80		-- `func` must return a string that concatenates with previous results. A
81		-- return of an empty string, nil, or no value signals the end of the chunk.
82		-- If there are no errors, returns the compiled chunk as a function; otherwise,
83		-- returns nil plus the error message. The environment of the returned function
84		-- is the global environment.
85		-- `chunkname` is used as the chunk name for error messages and debug
86		-- information. When absent, it defaults to "`=(load)`".
87		function load(func , chunkname) end
88
89		---
90		-- Similar to `load`, but gets the chunk from file `filename` or from the
	71	-- Loads a chunk.
	72	-- If `ld` is a string, the chunk is this string.
	73	-- If `ld` is a function, load calls it repeatedly to get the chunk pieces. Each call to `ld` must return a
	74	-- string that concatenates with previous results. A return of an empty string, nil, or no value
	75	-- signals the end of the chunk.
	76	-- If there are no syntactic errors, returns the compiled chunk as a function;
	77	-- otherwise, returns nil plus the error message.
	78	-- If the resulting function has upvalues, the first upvalue is set to the value of the global environment or to `env`,
	79	-- if that parameter is given. When loading main chunks, the first upvalue will be the`_ENV` variable (see 2.2).
	80	-- `source` is used as the source of the chunk for error messages and debug information (see 4.9).
	81	-- When absent, it defaults to `ld`, if `ld` is a string, or to "=(load)" otherwise.
	82	-- The string `mode` controls whether the chunk can be text or binary (that is, a precompiled chunk).
	83	-- It may be the string "b" (only binary chunks), "t" (only text chunks), or "bt" (both binary and text).
	84	-- The default is "bt"
	85	function load (ld [, source [, mode [, env]]]) end
	86
	87	---
	88	-- Similar to `load`, but gets the chunk from file `filename`. Or from the
91	89	-- standard input, if no file name is given.
92		function loadfile(filename) end
93
94		---
95		-- Similar to `load`, but gets the chunk from the given string.
96		-- To load and run a given string, use the idiom
97		-- assert(loadstring(s))()
98		-- When absent, `chunkname` defaults to the given string.
99		function loadstring(string , chunkname) end
	90	function loadfile (filename [, mode [, env]]]) end
100	91
101	92	---
102	93	-- Allows a program to traverse all fields of a table. Its first argument is

120	111	function next(table , index) end
121	112
122	113	---
	114	-- For iterating over all key-value pairs of a table.
123	115	-- Returns three values: the `next` function, the table `t`, and nil,
124	116	-- so that the construction
125	117	-- for k,v in pairs(t) do body end
126		-- will iterate over all key–value pairs of table `t`.
	118	-- will iterate over all key-value pairs of table `t`.
127	119	-- See function `next` for the caveats of modifying the table during its
128	120	-- traversal.
129	121	function pairs(t) end

138	130	function pcall(f, arg1, ...) end
139	131
140	132	---
141		-- Receives any number of arguments, and prints their values to `stdout`,
142		-- using the `tostring` function to convert them to strings. `print` is not
	133	--Prints any number of values to `stdout`.
	134	-- Uses the `tostring` function to convert them to strings. `print` is not
143	135	-- intended for formatted output, but only as a quick way to show a value,
144	136	-- typically for debugging. For formatted output, use `string.format`.
145	137	function print(...) end
146	138
147	139	---
148		-- Checks whether `v1` is equal to `v2`, without invoking any
	140	-- Checks whether `v1` is equal to `v2`. Does not invoke any
149	141	-- metamethod. Returns a boolean.
150	142	function rawequal(v1, v2) end
151	143
152	144	---
153		-- Gets the real value of `table[index]`, without invoking any
	145	-- Gets the real value of `table[index]`. Does not invoke any
154	146	-- metamethod. `table` must be a table; `index` may be any value.
155	147	function rawget(table, index) end
156	148
157	149	---
158		-- Sets the real value of `table[index]` to `value`, without invoking any
	150	-- Sets the real value of `table[index]` to `value`. Does not invoke any
159	151	-- metamethod. `table` must be a table, `index` any value different from nil,
160	152	-- and `value` any Lua value.
161	153	-- This function returns `table`.
162	154	function rawset(table, index, value) end
163	155
164	156	---
165		-- If `index` is a number, returns all arguments after argument number
	157	-- Returns all arguments after argument number
166	158	-- `index`. Otherwise, `index` must be the string `"#"`, and `select` returns
167	159	-- the total number of extra arguments it received.
168	160	function select(index, ...) end
169
170		---
171		-- Sets the environment to be used by the given function. `f` can be a Lua
172		-- function or a number that specifies the function at that stack level: Level
173		-- 1 is the function calling `setfenv`. `setfenv` returns the given function.
174		-- As a special case, when `f` is 0 `setfenv` changes the environment of the
175		-- running thread. In this case, `setfenv` returns no values.
176		function setfenv(f, table) end
177	161
178	162	---
179	163	-- Sets the metatable for the given table. (You cannot change the metatable

192	176	-- letter '`A`' (in either upper or lower case) represents 10, '`B`' represents
193	177	-- 11, and so forth, with '`Z`' representing 35. In base 10 (the default),
194	178	-- the number can have a decimal part, as well as an optional exponent part
195		-- (see §2.1). In other bases, only unsigned integers are accepted.
196		function tonumber(e , base) end
197
198		---
199		-- Receives an argument of any type and converts it to a string in a
200		-- reasonable format. For complete control of how numbers are converted, use
201		-- `string.format`.
	179	-- (see 2.1). In other bases, only unsigned integers are accepted.
	180	function tonumber(e [, base]) end
	181
	182	---
	183	-- Converts any value to a string in a reasonable format.
	184	-- For complete control of how numbers are converted, use `string.format`.
202	185	-- If the metatable of `e` has a `"__tostring"` field, then `tostring` calls
203	186	-- the corresponding value with `e` as argument, and uses the result of the
204	187	-- call as its result.

212	195	function type(v) end
213	196
214	197	---
215		-- Returns the elements from the given table. This function is equivalent to
216		-- return list[i], list[i+1], ..., list[j]
217		-- except that the above code can be written only for a fixed number of
218		-- elements. By default, `i` is 1 and `j` is the length of the list, as
219		-- defined by the length operator (see §2.5.5).
220		function unpack(list , i , j) end
221
222		---
223	198	-- A global variable (not a function) that holds a string containing the
224	199	-- current interpreter version. The current contents of this variable is
225	200	-- "`Lua 5.1`".
226		-- function _VERSION end
227		-- * `_G._VERSION`: _G._VERSION
	201	-- @table _VERSION
228	202
229	203	---
230	204	-- This function is similar to `pcall`, except that you can set a new

237	211	-- also returns all results from the call, after this first result. In case
238	212	-- of any error, `xpcall` returns false plus the result from `err`.
239	213	function xpcall(f, err) end
240
241		---
242		-- Creates a module. If there is a table in `package.loaded[name]`,
243		-- this table is the module. Otherwise, if there is a global table `t`
244		-- with the given name, this table is the module. Otherwise creates a new
245		-- table `t` and sets it as the value of the global `name` and the value of
246		-- `package.loaded[name]`. This function also initializes `t._NAME` with the
247		-- given name, `t._M` with the module (`t` itself), and `t._PACKAGE` with the
248		-- package name (the full module name minus last component; see below). Finally,
249		-- `module` sets `t` as the new environment of the current function and the
250		-- new value of `package.loaded[name]`, so that `require` returns `t`.
251		-- If `name` is a compound name (that is, one with components separated by
252		-- dots), `module` creates (or reuses, if they already exist) tables for each
253		-- component. For instance, if `name` is `a.b.c`, then `module` stores the
254		-- module table in field `c` of field `b` of global `a`.
255		-- This function can receive optional options after the module name, where
256		-- each option is a function to be applied over the module.
257		function module(name , ...) end
258	214
259	215	---
260	216	-- Loads the given module. The function starts by looking into the

+20

-6

ldoc/builtin/globals.lua less more

2	2	local tools = require 'ldoc.tools'
3	3	local globals = {}
4	4	local lua52 = _VERSION:match '5.2'
	5	local lua53 = _VERSION:match '5.3'
5	6
6	7
7	8	globals.functions = {
8	9	assert = true,
9	10	collectgarbage = true,
10	11	dofile = true,
	12	error = true,
11	13	getmetatable = true,
12	14	setmetatable = true,
13	15	pairs = true,

31	33	}
32	34	local functions = globals.functions
33	35
34		if not lua52 then
	36	if lua52 or lua53 then
	37	functions.rawlen = true
	38	else
35	39	functions.setfenv = true
36	40	functions.getfenv = true
37	41	functions.unpack = true
38		else
39		functions.rawlen = true
40	42	end
41	43
42	44	local manual, fun_ref

46	48	fun_ref = manual..'pdf-'
47	49	end
48	50
49		if lua52 then
	51	if lua53 then
	52	globals.tables = {
	53	io = '6.8',
	54	package = '6.3',
	55	math = '6.7',
	56	os = '6.9',
	57	string = '6.4',
	58	table = '6.6',
	59	coroutine = '6.2',
	60	debug = '6.10'
	61	}
	62	globals.set_manual_url 'https://www.lua.org/manual/5.3/manual.html'
	63	elseif lua52 then
50	64	globals.tables = {
51	65	io = '6.8',
52	66	package = '6.3',

57	71	coroutine = '6.2',
58	72	debug = '6.10'
59	73	}
60		globals.set_manual_url 'http://www.lua.org/manual/5.2/manual.html'
	74	globals.set_manual_url 'https://www.lua.org/manual/5.2/manual.html'
61	75	else
62	76	globals.tables = {
63	77	io = '5.7',

69	83	coroutine = '5.2',
70	84	debug = '5.9'
71	85	}
72		globals.set_manual_url 'http://www.lua.org/manual/5.1/manual.html'
	86	globals.set_manual_url 'https://www.lua.org/manual/5.1/manual.html'
73	87	end
74	88
75	89	local file_methods = {

+16

-0

ldoc/builtin/string.lua less more

170	170	-- definition of what a lowercase letter is depends on the current locale.
171	171	function string.upper(s) end
172	172
	173	---
	174	-- (5.3) Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form)
	175	--- according to the format string fmt (see 6.4.2).
	176	function string.pack (fmt, v1, v2, ···) end
	177
	178	---
	179	-- (5.3) Returns the size of a string resulting from string.pack with the given format.
	180	-- The format string cannot have the variable-length options 's' or 'z' (see 6.4.2).
	181	function string.packsize (fmt) end
	182
	183	---
	184	-- (5.3) Returns the values packed in string s (see string.pack) according to the format string fmt (see 6.4.2).
	185	-- An optional pos marks where to start reading in s (default is 1)
	186	-- After the read values, this function also returns the index of the first unread byte in s.
	187	function string.unpack (fmt, s [, pos]) end
	188
173	189	return string
174	190

+12

-6

ldoc/builtin/table.lua less more

18	18	function table.insert(table, pos, value) end
19	19
20	20	---
21		-- Returns the largest positive numerical index of the given table, or
22		-- zero if the table has no positive numerical indices. (To do its job this
23		-- function does a linear traversal of the whole table.)
24		function table.maxn(table) end
25
26		---
27	21	-- Removes from `table` the element at position `pos`, shifting down other
28	22	-- elements to close the space, if necessary. Returns the value of the removed
29	23	-- element. The default value for `pos` is `n`, where `n` is the length of the

31	25	-- `t`.
32	26	function table.remove(table , pos) end
33	27
	28	---
	29	-- Returns a new table with all parameters stored into keys 1, 2, etc. and with a field "n" with
	30	-- the total number of parameters. Note that the resulting table may not be a sequence.
	31	function table.pack (···) end
34	32	---
35	33	-- Sorts table elements in a given order,
36	34	-- in-place, from `table[1]` to `table[n]`, where `n` is the length of the

40	38	-- is not given, then the '<' operator will be used.
41	39	function table.sort(table , comp) end
42	40
	41	---
	42	-- Returns the elements from the given table. This function is equivalent to
	43	-- return list[i], list[i+1], ..., list[j]
	44	-- except that the above code can be written only for a fixed number of
	45	-- elements. By default, `i` is 1 and `j` is the length of the list, as
	46	-- defined by the length operator (see §2.5.5).
	47	function unpack(list , i , j) end
	48
43	49	return table

+48

-0

ldoc/builtin/utf8.lua less more

	0	--- This library provides basic support for UTF-8 encoding.
	1	-- @module utf8
	2
	3	local utf8 = {}
	4
	5	---
	6	-- Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence and returns
	7	-- a string with the concatenation of all these sequences.
	8	function utf8.char (...) end
	9
	10	---
	11	-- The pattern "[\0-\x7F\xC2-\xF4][\x80-\xBF]*" , which matches exactly one
	12	-- UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string.
	13	-- @field charpattern
	14
	15	---
	16	-- Iterate over all characters in string.
	17	--
	18	-- for p, c in utf8.codes(s) do body end
	19	--
	20	-- will iterate over all characters in string s, with p being the position (in bytes) and c the code point
	21	-- of each character. It raises an error if it meets any invalid byte sequence.
	22	function utf8.codes (s) end
	23
	24	---
	25	-- Returns the codepoints (as integers) from all characters in s that start between byte position i and j (both included).
	26	-- The default for i is 1 and for j is i. It raises an error if it meets any invalid byte sequence.
	27	function utf8.codepoint (s [, i [, j]]) end
	28
	29	---
	30	-- Returns the number of UTF-8 characters in string s that start between positions i and j (both inclusive).
	31	-- The default for i is 1 and for j is -1. If it finds any invalid byte sequence, returns a false value plus
	32	-- the position of the first invalid byte.
	33	function utf8.len (s [, i [, j]]) end
	34
	35	---
	36	-- Returns the position (in bytes) where the encoding of the n-th character of s (counting from position i) starts.
	37	-- A negative n gets characters before position i. The default for i is 1 when n is non-negative
	38	-- and #s + 1 otherwise, so that utf8.offset(s, -n) gets the offset of the n-th character from the end
	39	-- of the string.
	40	-- If the specified character is neither in the subject nor right after its end, the function returns nil.
	41	--
	42	-- 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.
	43	--
	44	-- This function assumes that s is a valid UTF-8 string.
	45	function utf8.offset (s, n [, i]) end
	46
	47

+38

-8

ldoc/doc.lua less more

5	5	local utils = require 'pl.utils'
6	6	local List = require 'pl.List'
7	7	local Map = require 'pl.Map'
	8	local text = require 'pl.text'
8	9
9	10	local doc = {}
10	11	local global = require 'ldoc.builtin.globals'

22	23	-- - 'T' tags which represent a type, like 'function' (TAG_TYPE)
23	24	local known_tags = {
24	25	param = 'M', see = 'M', comment = 'M', usage = 'ML', ['return'] = 'M', field = 'M', author='M',set='M';
25		class = 'id', name = 'id', pragma = 'id', alias = 'id', within = 'id',
	26	class = 'id', name = 'id', pragma = 'id', alias = 'id',
26	27	copyright = 'S', summary = 'S', description = 'S', release = 'S', license = 'S',
27		fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S',
	28	fixme = 'S', todo = 'S', warning = 'S', raise = 'S', charset = 'S', within = 'S',
28	29	['local'] = 'N', export = 'N', private = 'N', constructor = 'N', static = 'N',include = 'S',
29	30	-- project-level
30	31	module = 'T', script = 'T', example = 'T', topic = 'T', submodule='T', classmod='T', file='T',

140	141	tags:add('name',item_name..'-'..tag..acount)
141	142	acount = acount + 1
142	143	return true
143		elseif tag == 'return' then
	144	elseif tags.error and tag == 'return' then
144	145	last_item:set_tag(tag,value)
145	146	end
146	147	end

293	294	end
294	295	item.display_name = display_name
295	296	this_mod.section = item
	297	-- the purpose of this little hack is to properly distinguish
	298	-- between built-in kinds and any user-defined kinds.
296	299	this_mod.kinds:add_kind(display_name,display_name..' ',nil,item)
297	300	this_mod.sections:append(item)
298	301	this_mod.sections.by_name[lookup_name:gsub('%A','_')] = item

535	538	if avalue then value = avalue..' '..value end
536	539	if amod then
537	540	modifiers = modifiers or {}
	541	local value_tokens = utils.split(value)
538	542	for m,v in pairs(amod) do
539		local idx = v:match('^%$(%d+)')
	543	local idx = tonumber(v:match('^%$(%d+)'))
540	544	if idx then
541	545	v, value = value:match('(%S+)(.*)')
	546	-- v = value_tokens[idx]
	547	-- value_tokens[idx] = ''
542	548	end
543	549	modifiers[m] = v
544	550	end
	551	-- value = table.concat(value_tokens, ' ')
545	552	end
546	553	else -- has to be a function that at least returns tag, value
547	554	return alias(tags,value,modifiers)

614	621	tags.see = read_del(tags,'see')
615	622	if tags.see then
616	623	tags.see = tools.identifier_list(tags.see)
	624	end
	625	if self.usage then
	626	for i = 1,#self.usage do
	627	local usage = self.usage[i]:gsub('^%s*\n','')
	628	self.usage[i] = text.dedent(usage)
	629	end
617	630	end
618	631	if doc.project_level(self.type) then
619	632	-- we are a module, so become one!

912	925	local struct_return_type = '*'
913	926
914	927	function Item:build_return_groups()
	928	local quote = tools.quote
915	929	local modifiers = self.modifiers
916	930	local retmod = modifiers['return']
917	931	local groups = List()

1018	1032	if type(file) == 'table' then require 'pl.pretty'.dump(file); file = '?' end
1019	1033	file = file or '?'
1020	1034	io.stderr:write(file,':',self.lineno or '1',': ',self.name or '?',': ',msg,'\n')
	1035	Item.had_warning = true
1021	1036	return nil
1022	1037	end
1023	1038

1196	1211	-- and try to to resolve this.
1197	1212	function Module:resolve_references(modules)
1198	1213	local found = List()
1199		for item in self.items:iter() do
	1214	-- Resolve see references in item. Can be Module or Item type.
	1215	local function resolve_item_references(item)
1200	1216	local see = item.tags.see
1201	1217	if see then -- this guy has @see references
1202	1218	item.see = List()

1211	1227	end
1212	1228	end
1213	1229	end
	1230
	1231	resolve_item_references(self); -- Resolve module-level see references.
	1232	for item in self.items:iter() do
	1233	resolve_item_references(item); -- Resolve item-level see references.
	1234	end
1214	1235	-- mark as found, so we don't waste time re-searching
1215	1236	for f in found:iter() do
1216	1237	f[1].tags.see:remove_value(f[2])

1243	1264	end
1244	1265	end
1245	1266
	1267	-- ANSI colour codes for making important stuff BOLD
	1268	-- (but not on Windows)
	1269	local bold,default = '\x1B[1m','\x1B[0m'
	1270	if utils.dir_separator == '\\' then
	1271	bold,default = '',''
	1272	end
	1273
1246	1274	function Module:dump(verbose)
1247	1275	if not doc.project_level(self.type) then return end
1248	1276	print '----'
1249		print(self.type..':',self.name,self.summary)
	1277	print(self.type..':',bold..self.name,self.summary..default)
1250	1278	if self.description then print(self.description) end
1251	1279	dump_tags (self.tags)
1252	1280	for item in self.items:iter() do

1271	1299	end
1272	1300	if verbose then
1273	1301	print()
	1302	io.write(bold)
1274	1303	print(self.type,name)
	1304	io.write(default)
1275	1305	print(self.summary)
1276	1306	if self.description and self.description:match '%S' then
1277	1307	print 'description:'
1278	1308	print(self.description)
1279	1309	end
1280		if #self.params > 0 then
	1310	if self.params and #self.params > 0 then
1281	1311	print 'parameters:'
1282	1312	for _,p in ipairs(self.params) do
1283	1313	print('',p,self.params.map[p])

1291	1321	end
1292	1322	dump_tags(self.tags)
1293	1323	else
1294		print('* '..name..' - '..self.summary)
	1324	print('* '..bold..name..default..' - '..self.summary)
1295	1325	end
1296	1326	end
1297	1327

+19

-0

ldoc/html/_code_css.lua less more

	0	return [[
	1
	2	/* styles for prettification of source */
	3	pre .comment { color: #558817; }
	4	pre .constant { color: #a8660d; }
	5	pre .escape { color: #844631; }
	6	pre .keyword { color: #aa5050; font-weight: bold; }
	7	pre .library { color: #0e7c6b; }
	8	pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
	9	pre .string { color: #8080ff; }
	10	pre .number { color: #f8660d; }
	11	pre .operator { color: #2239a8; font-weight: bold; }
	12	pre .preprocessor, pre .prepro { color: #a33243; }
	13	pre .global { color: #800080; }
	14	pre .user-keyword { color: #800080; }
	15	pre .prompt { color: #558817; }
	16	pre .url { color: #272fc2; text-decoration: underline; }
	17
	18	]]

+66

-0

ldoc/html/_reset_css.lua less more

	0	return [[
	1	/* BEGIN RESET
	2
	3	Copyright (c) 2010, Yahoo! Inc. All rights reserved.
	4	Code licensed under the BSD License:
	5	http://developer.yahoo.com/yui/license.html
	6	version: 2.8.2r1
	7	*/
	8	html {
	9	color: #000;
	10	background: #FFF;
	11	}
	12	body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
	13	margin: 0;
	14	padding: 0;
	15	}
	16	table {
	17	border-collapse: collapse;
	18	border-spacing: 0;
	19	}
	20	fieldset,img {
	21	border: 0;
	22	}
	23	address,caption,cite,code,dfn,em,strong,th,var,optgroup {
	24	font-style: inherit;
	25	font-weight: inherit;
	26	}
	27	del,ins {
	28	text-decoration: none;
	29	}
	30	li {
	31	margin-left: 20px;
	32	}
	33	caption,th {
	34	text-align: left;
	35	}
	36	h1,h2,h3,h4,h5,h6 {
	37	font-size: 100%;
	38	font-weight: bold;
	39	}
	40	q:before,q:after {
	41	content: '';
	42	}
	43	abbr,acronym {
	44	border: 0;
	45	font-variant: normal;
	46	}
	47	sup {
	48	vertical-align: baseline;
	49	}
	50	sub {
	51	vertical-align: baseline;
	52	}
	53	legend {
	54	color: #000;
	55	}
	56	input,button,textarea,select,optgroup,option {
	57	font-family: inherit;
	58	font-size: inherit;
	59	font-style: inherit;
	60	font-weight: inherit;
	61	}
	62	input,button,textarea,select {*font-size:100%;
	63	}
	64	/* END RESET */
	65	]]

+8

-94

ldoc/html/ldoc_css.lua less more

0		return [==[
1		/* BEGIN RESET
2
3		Copyright (c) 2010, Yahoo! Inc. All rights reserved.
4		Code licensed under the BSD License:
5		http://developer.yahoo.com/yui/license.html
6		version: 2.8.2r1
7		*/
8		html {
9		color: #000;
10		background: #FFF;
11		}
12		body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
13		margin: 0;
14		padding: 0;
15		}
16		table {
17		border-collapse: collapse;
18		border-spacing: 0;
19		}
20		fieldset,img {
21		border: 0;
22		}
23		address,caption,cite,code,dfn,em,strong,th,var,optgroup {
24		font-style: inherit;
25		font-weight: inherit;
26		}
27		del,ins {
28		text-decoration: none;
29		}
30		li {
31		list-style: disc;
32		margin-left: 20px;
33		}
34		caption,th {
35		text-align: left;
36		}
37		h1,h2,h3,h4,h5,h6 {
38		font-size: 100%;
39		font-weight: bold;
40		}
41		q:before,q:after {
42		content: '';
43		}
44		abbr,acronym {
45		border: 0;
46		font-variant: normal;
47		}
48		sup {
49		vertical-align: baseline;
50		}
51		sub {
52		vertical-align: baseline;
53		}
54		legend {
55		color: #000;
56		}
57		input,button,textarea,select,optgroup,option {
58		font-family: inherit;
59		font-size: inherit;
60		font-style: inherit;
61		font-weight: inherit;
62		}
63		input,button,textarea,select {*font-size:100%;
64		}
65		/* END RESET */
	0	return require('ldoc.html._reset_css') .. [[
66	1
67	2	body {
68	3	margin-left: 1em;

88	23
89	24	h1 {
90	25	font-size: 1.5em;
91		margin: 0 0 20px 0;
	26	margin: 20px 0 20px 0;
92	27	}
93	28	h2, h3, h4 { margin: 15px 0 10px 0; }
94	29	h2 { font-size: 1.25em; }

114	49	padding-top: 1em;
115	50	}
116	51
117		pre.example {
118		background-color: rgb(245, 245, 245);
119		border: 1px solid silver;
120		padding: 10px;
121		margin: 10px 0 10px 0;
122		font-family: "Andale Mono", monospace;
123		font-size: .85em;
124		}
125
126	52	pre {
127	53	background-color: rgb(245, 245, 245);
128		border: 1px solid silver;
	54	border: 1px solid #C0C0C0; /* silver */
129	55	padding: 10px;
130	56	margin: 10px 0 10px 0;
131	57	overflow: auto;
132	58	font-family: "Andale Mono", monospace;
133	59	}
134	60
	61	pre.example {
	62	font-size: .85em;
	63	}
135	64
136	65	table.index { border: 1px #00007f; }
137	66	table.index td { text-align: left; vertical-align: top; }

291	220	background-color: #FF9;
292	221	}
293	222
294		/* styles for prettification of source */
295		pre .comment { color: #558817; }
296		pre .constant { color: #a8660d; }
297		pre .escape { color: #844631; }
298		pre .keyword { color: #aa5050; font-weight: bold; }
299		pre .library { color: #0e7c6b; }
300		pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
301		pre .string { color: #8080ff; }
302		pre .number { color: #f8660d; }
303		pre .operator { color: #2239a8; font-weight: bold; }
304		pre .preprocessor, pre .prepro { color: #a33243; }
305		pre .global { color: #800080; }
306		pre .prompt { color: #558817; }
307		pre .url { color: #272fc2; text-decoration: underline; }
308		]==]
309
310
	223	]]
	224	.. require('ldoc.html._code_css')

+7

-91

ldoc/html/ldoc_fixed_css.lua less more

0		return [[
1		/* BEGIN RESET
2
3		Copyright (c) 2010, Yahoo! Inc. All rights reserved.
4		Code licensed under the BSD License:
5		http://developer.yahoo.com/yui/license.html
6		version: 2.8.2r1
7		*/
8		html {
9		color: #000;
10		background: #FFF;
11		}
12		body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
13		margin: 0;
14		padding: 0;
15		}
16		table {
17		border-collapse: collapse;
18		border-spacing: 0;
19		}
20		fieldset,img {
21		border: 0;
22		}
23		address,caption,cite,code,dfn,em,strong,th,var,optgroup {
24		font-style: inherit;
25		font-weight: inherit;
26		}
27		del,ins {
28		text-decoration: none;
29		}
30		li {
31		list-style: bullet;
32		margin-left: 20px;
33		}
34		caption,th {
35		text-align: left;
36		}
37		h1,h2,h3,h4,h5,h6 {
38		font-size: 100%;
39		font-weight: bold;
40		}
41		q:before,q:after {
42		content: '';
43		}
44		abbr,acronym {
45		border: 0;
46		font-variant: normal;
47		}
48		sup {
49		vertical-align: baseline;
50		}
51		sub {
52		vertical-align: baseline;
53		}
54		legend {
55		color: #000;
56		}
57		input,button,textarea,select,optgroup,option {
58		font-family: inherit;
59		font-size: inherit;
60		font-style: inherit;
61		font-weight: inherit;
62		}
63		input,button,textarea,select {*font-size:100%;
64		}
65		/* END RESET */
	0	return require('ldoc.html._reset_css') .. [[
66	1
67	2	body {
68	3	margin-left: 1em;

114	49	padding-top: 1em;
115	50	}
116	51
117		pre.example {
	52	pre {
118	53	background-color: rgb(245, 245, 245);
119		border: 1px solid silver;
120		padding: 10px;
121		margin: 10px 0 10px 0;
122		font-family: "Andale Mono", monospace;
123		font-size: .85em;
124		}
125
126		pre {
127		background-color: rgb(245,245,255); // rgb(245, 245, 245);
128		border: 1px solid #cccccc; //silver;
	54	border: 1px solid #C0C0C0; /* silver */
129	55	padding: 10px;
130	56	margin: 10px 0 10px 0;
131	57	overflow: auto;
132	58	font-family: "Andale Mono", monospace;
133	59	}
134	60
	61	pre.example {
	62	font-size: .85em;
	63	}
135	64
136	65	table.index { border: 1px #00007f; }
137	66	table.index td { text-align: left; vertical-align: top; }

299	228	background-color: #FF9;
300	229	}
301	230
302		/* styles for prettification of source */
303		pre .comment { color: #558817; }
304		pre .constant { color: #a8660d; }
305		pre .escape { color: #844631; }
306		pre .keyword { color: #aa5050; font-weight: bold; }
307		pre .library { color: #0e7c6b; }
308		pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
309		pre .string { color: #8080ff; }
310		pre .number { color: #f8660d; }
311		pre .operator { color: #2239a8; font-weight: bold; }
312		pre .preprocessor, pre .prepro { color: #a33243; }
313		pre .global { color: #800080; }
314		pre .prompt { color: #558817; }
315		pre .url { color: #272fc2; text-decoration: underline; }
316	231	]]
	232	.. require('ldoc.html._code_css')

+23

-6

ldoc/html/ldoc_ltp.lua less more

5	5	<head>
6	6	<title>$(ldoc.title)</title>
7	7	<link rel="stylesheet" href="$(ldoc.css)" type="text/css" />
	8	# if ldoc.custom_css then -- add custom CSS file if configured.
	9	<link rel="stylesheet" href="$(ldoc.custom_css)" type="text/css" />
	10	# end
8	11	</head>
9	12	<body>
10	13

64	67	# for kind, mods, type in ldoc.kinds() do
65	68	# if ldoc.allowed_in_contents(type,module) then
66	69	<h2>$(kind)</h2>
67		<ul class="$(kind=='Topics' and '' or 'nowrap'">
68		# for mod in mods() do local name = ldoc.module_name(mod)
	70	<ul class="$(kind=='Topics' and '' or 'nowrap')">
	71	# for mod in mods() do local name = display_name(mod)
69	72	# if mod.name == this_mod then
70	73	<li><strong>$(name)</strong></li>
71	74	# else

89	92	# if module.tags.include then
90	93	$(M(ldoc.include_file(module.tags.include)))
91	94	# end
	95	# if module.see then
	96	# local li,il = use_li(module.see)
	97	<h3>See also:</h3>
	98	<ul>
	99	# for see in iter(module.see) do
	100	$(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
	101	# end -- for
	102	</ul>
	103	# end -- if see
92	104	# if module.usage then
93	105	# local li,il = use_li(module.usage)
94	106	<h3>Usage:</h3>

133	145	# local show_parms = show_return
134	146	# for kind, items in module.kinds() do
135	147	# local kitem = module.kinds:get_item(kind)
136		<h2><a name="$(no_spaces(kind))"></a>$(kind)</h2>
	148	# local has_description = kitem and ldoc.descript(kitem) ~= ""
	149	<h2 class="section-header $(has_description and 'has-description')"><a name="$(no_spaces(kind))"></a>$(kind)</h2>
137	150	$(M(module.kinds:get_section_description(kind),nil))
138	151	# if kitem then
139		$(M(ldoc.descript(kitem),kitem))
	152	# if has_description then
	153	<div class="section-description">
	154	$(M(ldoc.descript(kitem),kitem))
	155	</div>
	156	# end
140	157	# if kitem.usage then
141	158	<h3>Usage:</h3>
142	159	<pre class="example">$(ldoc.prettify(kitem.usage[1]))</pre>

147	164	<dt>
148	165	<a name = "$(item.name)"></a>
149	166	<strong>$(display_name(item))</strong>
150		# if ldoc.prettify_files then
	167	# if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
151	168	<a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
152	169	# end
153	170	</dt>

288	305	</div> <!-- id="content" -->
289	306	</div> <!-- id="main" -->
290	307	<div id="about">
291		<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.3</a></i>
	308	<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc $(ldoc.version)</a></i>
292	309	<i style="float:right;">Last updated $(ldoc.updatetime) </i>
293	310	</div> <!-- id="about" -->
294	311	</div> <!-- id="container" -->

+17

-100

ldoc/html/ldoc_one_css.lua less more

0		return [==[
1		/* BEGIN RESET
2
3		Copyright (c) 2010, Yahoo! Inc. All rights reserved.
4		Code licensed under the BSD License:
5		http://developer.yahoo.com/yui/license.html
6		version: 2.8.2r1
7		*/
8		html {
9		color: #000;
10		background: #FFF;
11		}
12		body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
13		margin: 0;
14		padding: 0;
15		}
16		table {
17		border-collapse: collapse;
18		border-spacing: 0;
19		}
20		fieldset,img {
21		border: 0;
22		}
23		address,caption,cite,code,dfn,em,strong,th,var,optgroup {
24		font-style: inherit;
25		font-weight: inherit;
26		}
27		del,ins {
28		text-decoration: none;
29		}
30		li {
31		list-style: bullet;
32		margin-left: 20px;
33		}
34		caption,th {
35		text-align: left;
36		}
37		h1,h2,h3,h4,h5,h6 {
38		font-size: 100%;
39		font-weight: bold;
40		}
41		q:before,q:after {
42		content: '';
43		}
44		abbr,acronym {
45		border: 0;
46		font-variant: normal;
47		}
48		sup {
49		vertical-align: baseline;
50		}
51		sub {
52		vertical-align: baseline;
53		}
54		legend {
55		color: #000;
56		}
57		input,button,textarea,select,optgroup,option {
58		font-family: inherit;
59		font-size: inherit;
60		font-style: inherit;
61		font-weight: inherit;
62		}
63		input,button,textarea,select {*font-size:100%;
64		}
65		/* END RESET */
	0	return require('ldoc.html._reset_css') .. [[
66	1
67	2	body {
68	3	margin-left: 1em;

108	43	font-family: "Andale Mono", monospace;
109	44	padding-top: 1em;
110	45	}
111
112		pre.example {
113		background-color: rgb(245, 245, 245);
114		border: 1px solid silver;
115		padding: 10px;
116		margin: 10px 0 10px 0;
117		font-family: "Andale Mono", monospace;
118		font-size: .85em;
119		}
120
121		pre {
122		background-color: rgb(245, 245, 245);
123		border: 1px solid silver;
124		padding: 10px;
125		margin: 10px 0 10px 0;
126		font-family: "Andale Mono", monospace;
127		}
128
129
	46
	47	pre {
	48	background-color: rgb(245, 245, 245);
	49	border: 1px solid #C0C0C0; /* silver */
	50	padding: 10px;
	51	margin: 10px 0 10px 0;
	52	overflow: auto;
	53	font-family: "Andale Mono", monospace;
	54	}
	55
	56	pre.example {
	57	font-size: .85em;
	58	}
	59
130	60	table.index { border: 1px #00007f; }
131	61	table.index td { text-align: left; vertical-align: top; }
132	62

267	197	dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
268	198	dl.table h3, dl.function h3 {font-size: .95em;}
269	199
270		/* styles for prettification of source */
271		pre .comment { color: #558817; }
272		pre .constant { color: #a8660d; }
273		pre .escape { color: #844631; }
274		pre .keyword { color: #aa5050; font-weight: bold; }
275		pre .library { color: #0e7c6b; }
276		pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
277		pre .string { color: #8080ff; }
278		pre .number { color: #f8660d; }
279		pre .operator { color: #2239a8; font-weight: bold; }
280		pre .preprocessor, pre .prepro { color: #a33243; }
281		pre .global { color: #800080; }
282		pre .prompt { color: #558817; }
283		pre .url { color: #272fc2; text-decoration: underline; }
284		]==]
	200	]]
	201	.. require('ldoc.html._code_css')

+7

-90

ldoc/html/ldoc_pale_css.lua less more

0		return [[/* BEGIN RESET
1
2		Copyright (c) 2010, Yahoo! Inc. All rights reserved.
3		Code licensed under the BSD License:
4		http://developer.yahoo.com/yui/license.html
5		version: 2.8.2r1
6		*/
7		html {
8		color: #000;
9		background: #FFF;
10		}
11		body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
12		margin: 0;
13		padding: 0;
14		}
15		table {
16		border-collapse: collapse;
17		border-spacing: 0;
18		}
19		fieldset,img {
20		border: 0;
21		}
22		address,caption,cite,code,dfn,em,strong,th,var,optgroup {
23		font-style: inherit;
24		font-weight: inherit;
25		}
26		del,ins {
27		text-decoration: none;
28		}
29		li {
30		list-style: bullet;
31		margin-left: 20px;
32		}
33		caption,th {
34		text-align: left;
35		}
36		h1,h2,h3,h4,h5,h6 {
37		font-size: 100%;
38		font-weight: bold;
39		}
40		q:before,q:after {
41		content: '';
42		}
43		abbr,acronym {
44		border: 0;
45		font-variant: normal;
46		}
47		sup {
48		vertical-align: baseline;
49		}
50		sub {
51		vertical-align: baseline;
52		}
53		legend {
54		color: #000;
55		}
56		input,button,textarea,select,optgroup,option {
57		font-family: inherit;
58		font-size: inherit;
59		font-style: inherit;
60		font-weight: inherit;
61		}
62		input,button,textarea,select {*font-size:100%;
63		}
64		/* END RESET */
	0	return require('ldoc.html._reset_css') .. [[
65	1
66	2	body {
67	3	margin-left: 1em;

113	49	padding-top: 1em;
114	50	}
115	51
116		pre.example {
	52	pre {
117	53	background-color: rgb(245, 245, 245);
118		border: 1px solid silver;
119		padding: 10px;
120		margin: 10px 0 10px 0;
121		font-family: "Andale Mono", monospace;
122		font-size: .85em;
123		}
124
125		pre {
126		background-color: rgb(245,245,255); // rgb(245, 245, 245);
127		border: 1px solid #cccccc; //silver;
	54	border: 1px solid #C0C0C0; /* silver */
128	55	padding: 10px;
129	56	margin: 10px 0 10px 0;
130	57	overflow: auto;
131	58	font-family: "Andale Mono", monospace;
132	59	}
133	60
	61	pre.example {
	62	font-size: .85em;
	63	}
134	64
135	65	table.index { border: 1px #00007f; }
136	66	table.index td { text-align: left; vertical-align: top; }

290	220	background-color: #FF9;
291	221	}
292	222
293		/* styles for prettification of source */
294		pre .comment { color: #558817; }
295		pre .constant { color: #a8660d; }
296		pre .escape { color: #844631; }
297		pre .keyword { color: #aa5050; font-weight: bold; }
298		pre .library { color: #0e7c6b; }
299		pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
300		pre .string { color: #8080ff; }
301		pre .number { color: #f8660d; }
302		pre .operator { color: #2239a8; font-weight: bold; }
303		pre .preprocessor, pre .prepro { color: #a33243; }
304		pre .global { color: #800080; }
305		pre .prompt { color: #558817; }
306		pre .url { color: #272fc2; text-decoration: underline; }
307	223	]]
	224	.. require('ldoc.html._code_css')

+35

-19

ldoc/html.lua less more

92	92
93	93	-- Item descriptions come from combining the summary and description fields
94	94	function ldoc.descript(item)
95		return (item.summary or '?')..' '..(item.description or '')
	95	return tools.join(' ', item.summary, item.description)
96	96	end
97	97
98	98	function ldoc.module_name (mod)

175	175	end
176	176
177	177	function ldoc.default_display_name(item)
	178	-- Project-level items:
	179	if doc.project_level(item.type) then
	180	return ldoc.module_name(item)
	181	end
	182	-- Module-level items:
178	183	local name = item.display_name or item.name
179	184	if item.type == 'function' or item.type == 'lfunction' then
180	185	if not ldoc.no_space_before_args then

272	277	quit("template not found at '"..args.template.."' Use -l to specify directory containing ldoc.ltp")
273	278	end
274	279
275		local css = ldoc.css
	280	-- Runs a template on a module to generate HTML page.
	281	local function templatize(template_str, ldoc, module)
	282	local out, err = template.substitute(template_str, {
	283	ldoc = ldoc,
	284	module = module,
	285	_escape = ldoc.template_escape
	286	})
	287	if not out then
	288	quit(("template failed for %s: %s"):format(
	289	module and module.name or ldoc.output or "index",
	290	err))
	291	end
	292	if ldoc.postprocess_html then
	293	out = ldoc.postprocess_html(out, module)
	294	end
	295	return cleanup_whitespaces(out)
	296	end
	297
	298	local css, custom_css = ldoc.css, ldoc.custom_css
276	299	ldoc.output = args.output
277	300	ldoc.ipairs = ipairs
278	301	ldoc.pairs = pairs

293	316	save_and_set_ldoc(ldoc.module.tags.set)
294	317	end
295	318	set_charset(ldoc)
296		local out,err = template.substitute(module_template,{
297		ldoc = ldoc,
298		module = ldoc.module,
299		_escape = ldoc.template_escape
300		})
	319	local out = templatize(module_template, ldoc, ldoc.module)
301	320	ldoc.root = false
302		if not out then quit("template failed: "..err) end
303	321	restore_ldoc()
304	322
305	323	check_directory(args.dir) -- make sure output directory is ok

308	326
309	327	if css then -- has CSS been copied?
310	328	check_file(args.dir..css, path.join(args.style,css))
	329	end
	330
	331	if custom_css then -- has custom CSS been copied?
	332	check_file(args.dir..custom_css, custom_css)
311	333	end
312	334
313	335	-- write out the module index

329	351	-- e.g. when reading a topic the other Topics will be listed first.
330	352	if css then
331	353	ldoc.css = '../'..css
	354	end
	355	if custom_css then
	356	ldoc.custom_css = '../'..custom_css
332	357	end
333	358	for m in mods:iter() do
334	359	local kind, lkind, modules = unpack(m)

346	371	if ldoc.body and m.postprocess then
347	372	ldoc.body = m.postprocess(ldoc.body)
348	373	end
349		out,err = template.substitute(module_template,{
350		module=m,
351		ldoc = ldoc,
352		_escape = ldoc.template_escape
353		})
354		if not out then
355		quit('template failed for '..m.name..': '..err)
356		else
357		out = cleanup_whitespaces(out)
358		writefile(args.dir..lkind..'/'..m.name..args.ext,out)
359		end
	374	local out = templatize(module_template, ldoc, m)
	375	writefile(args.dir..lkind..'/'..m.name..args.ext,out)
360	376	restore_ldoc()
361	377	end
362	378	end

+24

-9

ldoc/lang.lua less more

150	150	parser = parse_lua_function_header
151	151	elseif t == 'iden' then
152	152	local name,t,v = tools.get_fun_name(tok,v)
153		if t ~= '=' then return nil end -- probably invalid code...
	153	if t ~= '=' then return nil,"not 'name = function,table or value'" end
154	154	t,v = tnext(tok)
155	155	if t == 'keyword' and v == 'function' then -- case [2]
156	156	tnext(tok) -- skip '('

188	188	parse_lua_table(tags,tok)
189	189	end
190	190	else
191		return nil
192		end
	191	return nil,'not returning function or table'
	192	end
	193	else
	194	return nil,"not 'name=value' or 'return value'"
193	195	end
194	196	return parser, is_local, case
195	197	end

319	321	self.start_comment_ = '^%s*%-%-%-+' -- used for doc comment line start
320	322	self.block_comment = '^%-%-%[=*%[%-+' -- used for block doc comments
321	323	self.end_comment_ = '[^%-]%-%-+\n$' ---- exclude --- this kind of comment ---
322		self.method_call = '.'
	324	self.method_call = '\\'
323	325	self:finalize()
	326	end
	327
	328	--- much like Lua, BUT auto-assign parameters start with @
	329	function Moon:extract_arg (tl,idx)
	330	idx = idx or 1
	331	local auto_assign = tl[idx][1] == '@'
	332	if auto_assign then idx = idx + 1 end
	333	local res = tl[idx][2]
	334	return res
324	335	end
325	336
326	337	function Moon:item_follows (t,v,tok)

337	348	tags:add('name',name)
338	349	end
339	350	elseif t == '=' or t == ':' then -- function/method
	351	local fat = false
340	352	t,v = tnext(tok)
341	353	return function(tags,tok)
342	354	if not tags.name then
343	355	tags:add('name',name)
344	356	end
345	357	if t == '(' then
346		tags.formal_args,t,v = tools.get_parameters(tok)
	358	tags.formal_args,t,v = tools.get_parameters(tok,')',',',self)
347	359	else
348	360	tags.formal_args = List()
349	361	end
	362	t,v = tnext(tok)
350	363	tags:add('class','function')
351		if t == '=' then
352		tags.formal_args:insert(1,'self')
353		tags.formal_args.comments = {self=''}
	364	if t == '>' then
	365	--~ tags.formal_args:insert(1,'self')
	366	--~ tags.formal_args.comments = {self=''}
	367	else
	368	tags.static = true
354	369	end
355	370	end
356	371	else
357		return nil
	372	return nil, "expecting '=' or ':'"
358	373	end
359	374	end
360	375	end

+2

-0

ldoc/lexer.lua less more

304	304	{'^`[^`]+`',bdump},
305	305	{'^%-%-%[(=*)%[.-%]%1%]',cdump},
306	306	{'^%-%-.-\n',cdump},
	307	{'^%-%-.-$',cdump},
307	308	{'^%[(=*)%[.-%]%1%]',sdump_l},
308	309	{'^==',tdump},
309	310	{'^~=',tdump},

353	354	{STRING1,chdump},
354	355	{STRING2,sdump},
355	356	{'^//.-\n',cdump},
	357	{'^//.-$',cdump},
356	358	{'^/%.-%/',cdump},
357	359	{'^==',tdump},
358	360	{'^!=',tdump},

+38

-2

ldoc/markup.lua less more

89	89	end
90	90	local title = line:match (title_pat)
91	91	if title then
	92	--- Windows line endings are the cockroaches of text
	93	title = title:gsub('\r$','')
92	94	-- Markdown allows trailing '#'...
93	95	title = title:gsub('%s*#+$','')
94	96	sections[L] = F:add_document_section(lstrip(title))

168	170	end
169	171	pretty_code (code,fence)
170	172	line = getline() -- skip fence
	173	if not line then break end
171	174	end
172	175	indent, line = indent_line(line)
173	176	if indent >= 4 then -- indented code block

230	233	end
231	234	return ok and markdown
232	235	end,
233		discount = generic_formatter,
	236	discount = function(format)
	237	local ok, markdown = pcall(require, 'discount')
	238	if ok then
	239	if 'function' == type(markdown) then
	240	-- lua-discount by A.S. Bradbury, https://luarocks.org/modules/luarocks/lua-discount
	241	elseif 'table' == type(markdown) and ('function' == type(markdown.compile) or 'function' == type(markdown.to_html)) then
	242	-- discount by Craig Barnes, https://luarocks.org/modules/craigb/discount
	243	-- result of apt-get install lua-discount (links against libmarkdown2)
	244	local mysterious_debian_variant = markdown.to_html ~= nil
	245	markdown = markdown.compile or markdown.to_html
	246	return function(text)
	247	local result, errmsg = markdown(text)
	248	if result then
	249	if mysterious_debian_variant then
	250	return result
	251	else
	252	return result.body
	253	end
	254	else
	255	io.stderr:write('LDoc discount failed with error ',errmsg)
	256	io.exit(1)
	257	end
	258	end
	259	else
	260	ok = false
	261	end
	262	end
	263	if not ok then
	264	print('format: using built-in markdown')
	265	ok, markdown = pcall(require, 'ldoc.markdown')
	266	end
	267	return ok and markdown
	268	end,
234	269	lunamark = function(format)
235	270	local ok, lunamark = pcall(require, format)
236	271	if ok then

318	353	end
319	354
320	355
321		function markup.create (ldoc, format, pretty)
	356	function markup.create (ldoc, format, pretty, user_keywords)
322	357	local processor
323	358	markup.plain = true
324	359	if format == 'backtick' then

328	363	backtick_references = ldoc.backtick_references
329	364	global_context = ldoc.package and ldoc.package .. '.'
330	365	prettify.set_prettifier(pretty)
	366	prettify.set_user_keywords(user_keywords)
331	367
332	368	markup.process_reference = function(name,istype)
333	369	if local_context == 'none.' and not name:match '%.' then

+44

-13

ldoc/parse.lua less more

21	21	-- followed by the value, which may extend over several lines.
22	22	local luadoc_tag = '^%s*@(%w+)'
23	23	local luadoc_tag_value = luadoc_tag..'(.*)'
24		local luadoc_tag_mod_and_value = luadoc_tag..'%[(.)%](.)'
	24	local luadoc_tag_mod_and_value = luadoc_tag..'%[([^%]])%](.)'
25	25
26	26	-- assumes that the doc comment consists of distinct tag lines
27	27	local function parse_at_tags(text)

120	120	return self._order:iter()
121	121	end
122	122
	123	local function comment_contains_tags (comment,args)
	124	return (args.colon and comment:find ': ') or (not args.colon and comment:find '@')
	125	end
	126
123	127	-- This takes the collected comment block, and uses the docstyle to
124	128	-- extract tags and values. Assume that the summary ends in a period or a question
125	129	-- mark, and everything else in the preamble is the description.

192	196	function F:warning (msg,kind,line)
193	197	kind = kind or 'warning'
194	198	line = line or lineno()
	199	Item.had_warning = true
195	200	io.stderr:write(fname..':'..line..': '..msg,'\n')
196	201	end
197	202

224	229	return nil
225	230	end
226	231	end
227		if lang.parse_module_call and t ~= 'comment'then
228		while t and not (t == 'iden' and v == 'module') do
229		t,v = tnext(tok)
	232	if lang.parse_module_call and t ~= 'comment' then
	233	local prev_token
	234	while t do
	235	if prev_token ~= '.' and prev_token ~= ':' and t == 'iden' and v == 'module' then
	236	break
	237	end
	238	prev_token = t
	239	t, v = tnext(tok)
230	240	end
231	241	if not t then
232	242	if not args.ignore then

235	245	--return nil
236	246	else
237	247	mod,t,v = lang:parse_module_call(tok,t,v)
238		if mod ~= '...' then
	248	if mod and mod ~= '...' then
239	249	add_module(Tags.new{summary='(no description)'},mod,true)
240	250	first_comment = false
241	251	module_found = true

270	280
271	281	if t == 'space' then t,v = tnext(tok) end
272	282
273		local item_follows, tags, is_local, case
	283	local item_follows, tags, is_local, case, parse_error
274	284	if ldoc_comment then
275	285	comment = table.concat(comment)
276	286	if comment:match '^%s*$' then

282	292	first_comment = false
283	293	else
284	294	item_follows, is_local, case = lang:item_follows(t,v,tok)
285		end
286		if item_follows or comment:find '@' or comment:find ': ' then
	295	if not item_follows then
	296	parse_error = is_local
	297	is_local = false
	298	end
	299	end
	300
	301	if item_follows or comment_contains_tags(comment,args) then
287	302	tags = extract_tags(comment,args)
	303
288	304	-- explicitly named @module (which is recommended)
289	305	if doc.project_level(tags.class) then
290	306	module_found = tags.name
291	307	-- might be a module returning a single function!
292	308	if tags.param or tags['return'] then
293	309	local parms, ret, summ = tags.param, tags['return'],tags.summary
	310	local name = tags.name
294	311	tags.param = nil
295	312	tags['return'] = nil
296		tags.summary = nil
297		add_module(tags,tags.name,false)
	313	tags['class'] = nil
	314	tags['name'] = nil
	315	add_module(tags,name,false)
298	316	tags = {
299		summary = summ,
	317	summary = '',
300	318	name = 'returns...',
301	319	class = 'function',
302	320	['return'] = ret,

307	325	doc.expand_annotation_item(tags,current_item)
308	326	-- if the item has an explicit name or defined meaning
309	327	-- then don't continue to do any code analysis!
	328	-- Watch out for the case where there are field or param tags
	329	-- but no class, since these will be fixed up later as module/class
	330	-- entities
	331	if (tags.field or tags.param) and not tags.class then
	332	parse_error = false
	333	end
310	334	if tags.name then
311	335	if not tags.class then
312	336	F:warning("no type specified, assuming function: '"..tags.name.."'")
313	337	tags:add('class','function')
314	338	end
315		item_follows, is_local = false, false
316		elseif lang:is_module_modifier (tags) then
	339	item_follows, is_local, parse_error = false, false, false
	340	elseif args.no_args_infer then
	341	F:error("No name and type provided (no_args_infer)")
	342	elseif lang:is_module_modifier (tags) then
317	343	if not item_follows then
318	344	F:warning("@usage or @export followed by unknown code")
319	345	break

330	356	end
331	357	end
332	358	end
	359	if parse_error then
	360	F:warning('definition cannot be parsed - '..parse_error)
	361	end
333	362	end
334	363	-- some hackery necessary to find the module() call
335	364	if not module_found and ldoc_comment then

358	387	if item_follows then -- parse the item definition
359	388	local err = item_follows(tags,tok)
360	389	if err then F:error(err) end
	390	elseif parse_error then
	391	F:warning('definition cannot be parsed - '..parse_error)
361	392	else
362	393	lang:parse_extra(tags,tok,case)
363	394	end

+17

-1

ldoc/prettify.lua less more

3	3	-- A module reference to an example `test-fun.lua` would look like
4	4	-- `@{example:test-fun}`.
5	5	local List = require 'pl.List'
	6	local tablex = require 'pl.tablex'
6	7	local globals = require 'ldoc.builtin.globals'
7	8	local prettify = {}
	9
	10	local user_keywords = {}
8	11
9	12	local escaped_chars = {
10	13	['&'] = '&',

46	49	io.stderr:write(fname..':'..tok:lineno()+initial_lineno..': '..msg,'\n')
47	50	end
48	51	}
	52	local last_t, last_val
49	53	local t,val = tok()
50	54	if not t then return nil,"empty file" end
51	55	while t do

57	61	if globals.functions[val] or globals.tables[val] then
58	62	t = 'global'
59	63	end
60		if spans[t] then
	64	if user_keywords[val] then
	65	res:append(span('user-keyword keyword-' .. val,val))
	66	elseif spans[t] then
61	67	if t == 'comment' or t == 'backtick' then -- may contain @{ref} or `..`
62	68	val = prettify.resolve_inline_references(val,error_reporter)
63	69	end

65	71	else
66	72	res:append(val)
67	73	end
	74	last_t, last_val = t,val
68	75	t,val = tok()
	76	end
	77	if last_t == 'comment' then
	78	res[#res] = span('comment',last_val:gsub('\r*\n$',''))
69	79	end
70	80	local last = res[#res]
71	81	if last:match '\n$' then

110	120	end
111	121	end
112	122
	123	function prettify.set_user_keywords(keywords)
	124	if keywords then
	125	user_keywords = tablex.makeset(keywords)
	126	end
	127	end
	128
113	129	return prettify
114	130

+34

-5

ldoc/tools.lua less more

13	13	local append = table.insert
14	14	local lexer = require 'ldoc.lexer'
15	15	local quit = utils.quit
16		local lfs = require 'lfs'
17	16
18	17	-- at rendering time, can access the ldoc table from any module item,
19	18	-- or the item itself if it's a module

108	107	local group = item[self.fieldname] -- which wd be item's type or section
109	108	local kname = self.klass.types_by_tag[group] -- the kind name
110	109	if not self[kname] then
111		-- print(kname,group,self.fieldname)
112	110	self[kname] = M.type_iterator (items,self.fieldname,group)
113	111	self.klass.descriptions[kname] = description
114	112	end

201	199	return s:gsub('^%s+',''):gsub('%s+$','')
202	200	end
203	201
	202	-- Joins strings using a separator.
	203	--
	204	-- Empty strings and nil arguments are ignored:
	205	--
	206	-- assert(join('+', 'one', '', 'two', nil, 'three') == 'one+two+three')
	207	-- assert(join(' ', '', '') == '')
	208	--
	209	-- This is especially useful for the last case demonstrated above,
	210	-- where "conventional" solutions (".." or table.concat) would result
	211	-- in a spurious space.
	212	function M.join(sep, ...)
	213	local contents = {}
	214	for i = 1, select('#', ...) do
	215	local value = select(i, ...)
	216	if value and value ~= "" then
	217	contents[#contents + 1] = value
	218	end
	219	end
	220	return table.concat(contents, sep)
	221	end
	222
204	223	function M.check_directory(d)
205	224	if not path.isdir(d) then
206		lfs.mkdir(d)
	225	if not dir.makepath(d) then
	226	quit("Could not create "..d.." directory")
	227	end
207	228	end
208	229	end
209	230

220	241	end
221	242
222	243	function M.writefile(name,text)
223		local ok,err = utils.writefile(name,text)
	244	local f,err = io.open(name,"wb")
	245	--~ local ok,err = utils.writefile(name,text)
224	246	if err then quit(err) end
	247	f:write(text)
	248	f:close()
225	249	end
226	250
227	251	function M.name_of (lpath)

314	338	return text:match("%s%-%-+%s(.*)")
315	339	end
316	340	extract_arg = function(tl,idx)
317		return value_of(tl[idx or 1])
	341	idx = idx or 1
	342	local res = value_of(tl[idx])
	343	if res == '[' then -- we do allow array indices in tables now
	344	res = '['..value_of(tl[idx + 1])..']'
	345	end
	346	return res
318	347	end
319	348	end
320	349

+0

-61

~~ldoc-1.3.12-1.rockspec~~ less more

0		package = "ldoc"
1		version = "1.3.12-1"
2
3		source = {
4		dir="ldoc",
5		url = "http://stevedonovan.github.com/files/ldoc-1.3.12.zip"
6		}
7
8		description = {
9		summary = "A Lua Documentation Tool",
10		detailed = [[
11		LDoc is a LuaDoc-compatible documentation generator which can also
12		process C extension source. Markdown may be optionally used to
13		render comments, as well as integrated readme documentation and
14		pretty-printed example files
15		]],
16		homepage='http://stevedonovan.github.com/ldoc',
17		maintainer='steve.j.donovan@gmail.com',
18		license = "MIT/X11",
19		}
20
21
22		dependencies = {
23		"penlight","markdown"
24		}
25
26		build = {
27		type = "builtin",
28		modules = {
29		["ldoc.tools"] = "ldoc/tools.lua",
30		["ldoc.lang"] = "ldoc/lang.lua",
31		["ldoc.parse"] = "ldoc/parse.lua",
32		["ldoc.html"] = "ldoc/html.lua",
33		["ldoc.lexer"] = "ldoc/lexer.lua",
34		["ldoc.markup"] = "ldoc/markup.lua",
35		["ldoc.prettify"] = "ldoc/prettify.lua",
36		["ldoc.doc"] = "ldoc/doc.lua",
37		["ldoc.html.ldoc_css"] = "ldoc/html/ldoc_css.lua",
38		["ldoc.html.ldoc_ltp"] = "ldoc/html/ldoc_ltp.lua",
39		["ldoc.html.ldoc_one_css"] = "ldoc/html/ldoc_one_css.lua",
40		["ldoc.builtin.globals"] = "ldoc/builtin/globals.lua",
41		["ldoc.builtin.coroutine"] = "ldoc/builtin/coroutine.lua",
42		["ldoc.builtin.global"] = "ldoc/builtin/global.lua",
43		["ldoc.builtin.debug"] = "ldoc/builtin/debug.lua",
44		["ldoc.builtin.io"] = "ldoc/builtin/io.lua",
45		["ldoc.builtin.lfs"] = "ldoc/builtin/lfs.lua",
46		["ldoc.builtin.lpeg"] = "ldoc/builtin/lpeg.lua",
47		["ldoc.builtin.math"] = "ldoc/builtin/math.lua",
48		["ldoc.builtin.os"] = "ldoc/builtin/os.lua",
49		["ldoc.builtin.package"] = "ldoc/builtin/package.lua",
50		["ldoc.builtin.string"] = "ldoc/builtin/string.lua",
51		["ldoc.builtin.table"] = "ldoc/builtin/table.lua",
52		},
53		install = {
54		bin = {
55		ldoc = "ldoc.lua"
56		}
57		}
58		}
59
60

+0

-61

~~ldoc-1.3.8-2.rockspec~~ less more

0		package = "ldoc"
1		version = "1.3.8-2"
2
3		source = {
4		dir="ldoc",
5		url = "http://stevedonovan.github.com/files/ldoc-1.3.8.zip"
6		}
7
8		description = {
9		summary = "A Lua Documentation Tool",
10		detailed = [[
11		LDoc is a LuaDoc-compatible documentation generator which can also
12		process C extension source. Markdown may be optionally used to
13		render comments, as well as integrated readme documentation and
14		pretty-printed example files
15		]],
16		homepage='http://stevedonovan.github.com/ldoc',
17		maintainer='steve.j.donovan@gmail.com',
18		license = "MIT/X11",
19		}
20
21
22		dependencies = {
23		"penlight","markdown"
24		}
25
26		build = {
27		type = "builtin",
28		modules = {
29		["ldoc.tools"] = "ldoc/tools.lua",
30		["ldoc.lang"] = "ldoc/lang.lua",
31		["ldoc.parse"] = "ldoc/parse.lua",
32		["ldoc.html"] = "ldoc/html.lua",
33		["ldoc.lexer"] = "ldoc/lexer.lua",
34		["ldoc.markup"] = "ldoc/markup.lua",
35		["ldoc.prettify"] = "ldoc/prettify.lua",
36		["ldoc.doc"] = "ldoc/doc.lua",
37		["ldoc.html.ldoc_css"] = "ldoc/html/ldoc_css.lua",
38		["ldoc.html.ldoc_ltp"] = "ldoc/html/ldoc_ltp.lua",
39		["ldoc.html.ldoc_one_css"] = "ldoc/html/ldoc_one_css.lua",
40		["ldoc.builtin.globals"] = "ldoc/builtin/globals.lua",
41		["ldoc.builtin.coroutine"] = "ldoc/builtin/coroutine.lua",
42		["ldoc.builtin.global"] = "ldoc/builtin/global.lua",
43		["ldoc.builtin.debug"] = "ldoc/builtin/debug.lua",
44		["ldoc.builtin.io"] = "ldoc/builtin/io.lua",
45		["ldoc.builtin.lfs"] = "ldoc/builtin/lfs.lua",
46		["ldoc.builtin.lpeg"] = "ldoc/builtin/lpeg.lua",
47		["ldoc.builtin.math"] = "ldoc/builtin/math.lua",
48		["ldoc.builtin.os"] = "ldoc/builtin/os.lua",
49		["ldoc.builtin.package"] = "ldoc/builtin/package.lua",
50		["ldoc.builtin.string"] = "ldoc/builtin/string.lua",
51		["ldoc.builtin.table"] = "ldoc/builtin/table.lua",
52		},
53		install = {
54		bin = {
55		"ldoc.lua"
56		}
57		}
58		}
59
60

+6

-3

ldoc-scm-2.rockspec less more

2	2
3	3	source = {
4	4	dir="LDoc",
5		url = "git://github.com/stevedonovan/LDoc.git"
	5	url = "git+https://github.com/stevedonovan/LDoc.git"
6	6	}
7	7
8	8	description = {

34	34	["ldoc.prettify"] = "ldoc/prettify.lua",
35	35	["ldoc.markdown"] = "ldoc/markdown.lua",
36	36	["ldoc.doc"] = "ldoc/doc.lua",
	37	["ldoc.html.ldoc_ltp"] = "ldoc/html/ldoc_ltp.lua",
	38	["ldoc.html.ldoc_md_ltp"] = "ldoc/html/ldoc_md_ltp.lua",
37	39	["ldoc.html.ldoc_css"] = "ldoc/html/ldoc_css.lua",
38		["ldoc.html.ldoc_ltp"] = "ldoc/html/ldoc_ltp.lua",
	40	["ldoc.html._code_css"] = "ldoc/html/_code_css.lua",
	41	["ldoc.html._reset_css"] = "ldoc/html/_reset_css.lua",
39	42	["ldoc.html.ldoc_one_css"] = "ldoc/html/ldoc_one_css.lua",
40	43	["ldoc.html.ldoc_pale_css"] = "ldoc/html/ldoc_pale_css.lua",
	44	["ldoc.html.ldoc_fixed_css"] = "ldoc/html/ldoc_fixed_css.lua",
41	45	["ldoc.builtin.globals"] = "ldoc/builtin/globals.lua",
42	46	["ldoc.builtin.coroutine"] = "ldoc/builtin/coroutine.lua",
43	47	["ldoc.builtin.global"] = "ldoc/builtin/global.lua",

58	62	}
59	63	}
60	64	}
61

+63

-17

ldoc.lua less more

6	6	--
7	7	-- C/C++ support for Lua extensions is provided.
8	8	--
9		-- Available from LuaRocks as 'ldoc' and as a [Zip file](http://stevedonovan.github.com/files/ldoc-1.4.2.zip)
	9	-- Available from LuaRocks as 'ldoc' and as a [Zip file](http://stevedonovan.github.com/files/ldoc-1.4.3.zip)
10	10	--
11	11	-- [Github Page](https://github.com/stevedonovan/ldoc)
12	12	--

26	26
27	27	-- Penlight compatibility
28	28	utils.unpack = utils.unpack or unpack or table.unpack
29
30	29	local append = table.insert
31
32	30	local lapp = require 'pl.lapp'
	31
	32	local version = '1.4.6'
33	33
34	34	-- so we can find our private modules
35	35	app.require_here()
36	36
37	37	--- @usage
38	38	local usage = [[
39		ldoc, a documentation generator for Lua, vs 1.4.3
	39	ldoc, a documentation generator for Lua, vs ]]..version..[[
	40
40	41	-d,--dir (default doc) output directory
41	42	-o,--output (default 'index') output name
42	43	-v,--verbose verbose

56	57	-X,--not_luadoc break LuaDoc compatibility. Descriptions may continue after tags.
57	58	-D,--define (default none) set a flag to be used in config.ld
58	59	-C,--colon use colon style
	60	-N,--no_args_infer don't infer arguments from source
59	61	-B,--boilerplate ignore first comment in source files
60	62	-M,--merge allow module merging
61	63	-S,--simple no return or params, no summary
62	64	-O,--one one-column output layout
	65	--date (default system) use this date in generated doc
63	66	--dump debug output dump
64	67	--filter (default none) filter output as Lua data (e.g pl.pretty.dump)
65	68	--tags (default none) show all references to given tags, comma-separated
	69	--fatalwarnings non-zero exit status on any warning
	70	--testing reproducible build; no date or version on output
	71
66	72	<file> (string) source file or directory containing source
67	73
68	74	`ldoc .` reads options from an `config.ld` file in same directory;

98	104	self.fieldname = 'type'
99	105	end
100	106
101
102
103	107	local lua, cc = lang.lua, lang.cc
104	108
105	109	local file_types = {

117	121	------- ldoc external API ------------
118	122
119	123	-- the ldoc table represents the API available in `config.ld`.
120		local ldoc = { charset = 'UTF-8' }
	124	local ldoc = { charset = 'UTF-8', version = version }
121	125
122	126	local known_types, kind_names = {}
123	127

141	145	ModuleMap:add_kind(lookup('function','Functions','Parameters'))
142	146	ModuleMap:add_kind(lookup('table','Tables','Fields'))
143	147	ModuleMap:add_kind(lookup('field','Fields'))
	148	ModuleMap:add_kind(lookup('type','Types'))
144	149	ModuleMap:add_kind(lookup('lfunction','Local Functions','Parameters'))
145	150	ModuleMap:add_kind(lookup('annotation','Issues'))
146	151

232	237	'no_return_or_parms','no_summary','full_description','backtick_references', 'custom_see_handler',
233	238	'no_space_before_args','parse_extra','no_lua_ref','sort_modules','use_markdown_titles',
234	239	'unqualified', 'custom_display_name_handler', 'kind_names', 'custom_references',
235		'dont_escape_underscore','global_lookup','prettify_files','convert_opt'
	240	'dont_escape_underscore','global_lookup','prettify_files','convert_opt', 'user_keywords',
	241	'postprocess_html',
	242	'custom_css','version',
	243	'no_args_infer'
236	244	}
237	245	ldoc_contents = tablex.makeset(ldoc_contents)
238	246

417	425
418	426	setup_package_base()
419	427
	428	override 'no_args_infer'
420	429	override 'colon'
421	430	override 'merge'
422	431	override 'not_luadoc'

463	472
464	473	if type(args.file) == 'table' then
465	474	-- this can only be set from config file so we can assume config is already read
466		process_all_files(args.file)
467
	475	process_all_files(args.file)
	476
468	477	elseif path.isdir(args.file) then
469	478	-- use any configuration file we find, if not already specified
470	479	if not config_dir then

479	488	end
480	489	end
481	490	end
482
	491
483	492	process_all_files({args.file})
484
	493
485	494	elseif path.isfile(args.file) then
486	495	-- a single file may be accompanied by a config.ld in the same dir
487	496	if not config_dir then

503	512	-- (this also will initialize the code prettifier used)
504	513	override ('format','plain')
505	514	override 'pretty'
506		ldoc.markup = markup.create(ldoc, args.format,args.pretty)
	515	ldoc.markup = markup.create(ldoc, args.format, args.pretty, ldoc.user_keywords)
507	516
508	517	------ 'Special' Project-level entities ---------------------------------------
509	518	-- Examples and Topics do not contain code to be processed for doc comments.

527	536	return item, F
528	537	end
529	538
530		local function prettify_source_files(files,class,linemap)
	539	local function prettify_source_files(files,class,linemap)
531	540	local prettify = require 'ldoc.prettify'
532	541
533	542	process_file_list (files, '.', function(f)

555	564	prettify_source_files(ldoc.examples,"example")
556	565	end
557	566
	567	ldoc.is_file_prettified = {}
	568
558	569	if ldoc.prettify_files then
559	570	local files = List()
560	571	local linemap = {}

567	578	end
568	579	linemap[F.filename] = ls
569	580	end
	581
	582	if type(ldoc.prettify_files) == 'table' then
	583	files = tools.expand_file_list(ldoc.prettify_files, '.')
	584	elseif type(ldoc.prettify_files) == 'string' then
	585	-- the gotcha is that if the person has a folder called 'show', only the contents
	586	-- of that directory will be converted. So, we warn of this amibiguity
	587	if ldoc.prettify_files == 'show' then
	588	-- just fall through with all module files collected above
	589	if path.exists 'show' then
	590	print("Notice: if you only want to prettify files in `show`, then set prettify_files to `show/`")
	591	end
	592	else
	593	files = tools.expand_file_list({ldoc.prettify_files}, '.')
	594	end
	595	end
	596
	597	ldoc.is_file_prettified = tablex.makeset(files)
570	598	prettify_source_files(files,"file",linemap)
571	599	end
572	600

745	773	local builtin_style, builtin_template = match_bang(args.style),match_bang(args.template)
746	774	if builtin_style or builtin_template then
747	775	-- '!' here means 'use built-in templates'
748		local tmpdir = path.join(path.is_windows and os.getenv('TMP') or '/tmp','ldoc')
	776	local user = path.expanduser('~'):gsub('[/\\: ]','_')
	777	local tmpdir = path.join(path.is_windows and os.getenv('TMP') or '/tmp','ldoc'..user)
749	778	if not path.isdir(tmpdir) then
750	779	lfs.mkdir(tmpdir)
751	780	end
752	781	local function tmpwrite (name)
753	782	local ok,text = pcall(require,'ldoc.html.'..name:gsub('%.','_'))
754	783	if not ok then
755		quit("cannot find builtin template "..name)
	784	quit("cannot find builtin template "..name.." ("..text..")")
756	785	end
757	786	if not utils.writefile(path.join(tmpdir,name),text) then
758	787	quit("cannot write to temp directory "..tmpdir)

780	809	ldoc.title = ldoc.title or args.title
781	810	ldoc.project = ldoc.project or args.project
782	811	ldoc.package = args.package:match '%a+' and args.package or nil
783		ldoc.updatetime = os.date("%Y-%m-%d %H:%M:%S")
	812
	813	local source_date_epoch = os.getenv("SOURCE_DATE_EPOCH")
	814	if args.testing then
	815	ldoc.updatetime = "2015-01-01 12:00:00"
	816	ldoc.version = 'TESTING'
	817	elseif source_date_epoch == nil then
	818	if args.date == 'system' then
	819	ldoc.updatetime = os.date("%Y-%m-%d %H:%M:%S")
	820	else
	821	ldoc.updatetime = args.date
	822	end
	823	else
	824	ldoc.updatetime = os.date("!%Y-%m-%d %H:%M:%S",source_date_epoch)
	825	end
784	826
785	827	local html = require 'ldoc.html'
786	828

790	832	print 'modules'
791	833	for k in pairs(module_list.by_name) do print(k) end
792	834	end
	835
	836	if args.fatalwarnings and Item.had_warning then
	837	os.exit(1)
	838	end

+18

-0

run-tests.lua less more

	0	local run
	1	if not arg[1] then
	2	run = function (dir)
	3	local cmd = 'cd '..dir..' && ldoc --testing . && diff -r doc cdocs'
	4	print(cmd)
	5	os.execute(cmd)
	6	end
	7	elseif arg[1] == 'update' then
	8	run = function (dir)
	9	local cmd = 'cd '..dir..' && ldoc --dir cdocs --testing .'
	10	print(cmd)
	11	os.execute(cmd)
	12	end
	13	end
	14
	15	for _,d in ipairs{'tests','tests/example','tests/md-test'} do
	16	run(d)
	17	end

+13

-0

tests/bad.lua less more

	0	-------
	1	-- @module bad
	2
	3	local bad = {}
	4
	5	--------
	6	-- inference fails! Have to explicitly
	7	-- declare the function and its arguments
	8	bad['entry'] = function(one)
	9	end
	10
	11	return bad
	12

+1

-1

tests/classes.lua less more

9	9	_M.Bonzo = class()
10	10
11	11	--- a method.
12		-- function one
	12	-- function one; reference to @{one.md.classes\|documentation}
13	13	function Bonzo:one()
14	14
15	15	end

+1

-1

tests/config.ld less more

1	1	project = 'Basic Example'
2	2	file = {'types.lua','classes.lua'}
3	3	use_markdown_titles=true
4		topics = {'one 1.md','two.md'}
	4	topics = {'one.md','two.md'}

+13

-0

tests/funmod.lua less more

	0	-------
	1	-- Summing values.
	2	-- Returns a single function.
	3	-- @param a first
	4	-- @param b second
	5	-- @param c third
	6	-- @return sum of parameters
	7	-- @module funmod
	8
	9	return function(a,b,c)
	10	return a + b + c
	11	end
	12

+1

-1

tests/moonscript/config.ld less more

0		file = 'list.moon'
	0	file = 'List.moon'
1	1	no_return_or_parms=true
2	2	no_summary=true
3	3	format = 'markdown'

+11

-0

tests/one.md less more

	0	# Documentation
	1
	2	## types
	3
	4	A reference to @{types.first}
	5
	6	A `first` topic
	7
	8	## classes
	9
	10	A `second` topic

+4

-3

tests/styles/opt.lua less more

0	0	------------
1		-- Functions with options and custom tags
	1	-- ### Functions with options and custom tags.
	2	-- (use `ldoc -c opt.ld opt.lua` for converting.)
2	3	--
3	4	-- @include opt.md
4	5
5	6	---- testing [opt]
6	7	-- @param one
7	8	-- @param[opt] two
8		-- @param[opt]three
	9	-- @param[opt] three
9	10	-- @param[opt] four
10	11	-- @remark use with caution!
11	12	function use_opt (one,two,three,four)
12	13	end
13	14
14	15	--- an explicit table.
15		-- Can now use tparam aliases in table defns
	16	-- Can use tparam aliases in table defns
16	17	-- @string name
17	18	-- @int[opt=0] age
18	19	-- @table person2