From 6e2eb5b13e4caf8faa0f23f900fa4d314dce3ad6 Mon Sep 17 00:00:00 2001 From: Corey Williamson Date: Thu, 7 Dec 2023 02:30:06 -0600 Subject: [PATCH] Update docgen and commit generated docs so github pages works --- docs/index.html | 597 ++++++++++++++++++++++++++++++++++++++++++++++ scripts/docgen.tl | 150 ++++++------ 2 files changed, 672 insertions(+), 75 deletions(-) create mode 100644 docs/index.html diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..5f6c0dd --- /dev/null +++ b/docs/index.html @@ -0,0 +1,597 @@ + + + + + + +

Cyan API Documentation

+

+This documentation is auto-generated and may be incomplete. +

+ +

Table of Contents

+ + +
+

cyan.ansi +

+

cyan.cli +

+

cyan.colorstring +
ColorString:len +
ColorString:surround +
ColorString:to_raw +
ColorString:tostring +
ColorString +
colorstring.highlight +
colorstring.new +
colorstring.rgb_bg +
colorstring.rgb_fg +

+

cyan.command +
Command +
command.get +
command.merge_args_into_config +
command.new +
command.register_all +

+

cyan.config +
Config +
config.find +
config.is_config +
config.load +

+

cyan.fs.path +
Path.eq +
Path:ancestors +
Path:append +
Path:copy +
Path:exists +
Path:is_absolute +
Path:is_directory +
Path:is_file +
Path:is_in +
Path:match +
Path:match_any +
Path:mk_parent_dirs +
Path:mkdir +
Path:mod_time +
Path:normalize +
Path:prepend +
Path:relative_to +
Path:remove_leading +
Path:to_absolute +
Path:to_real_path +
Path:tostring +
Path +
path.ensure +
path.new +

+

cyan.fs +
fs.chdir +
fs.copy +
fs.cwd +
fs.dir +
fs.extension_split +
fs.get_line +
fs.path_concat +
fs.read +
fs.scan_dir +
fs.search_parent_dirs +

+

cyan.graph +
Dag:find +
Dag:insert_file +
Dag:mark_each +
Dag:marked_nodes +
Dag:nodes +
Dag +
Node +
graph.empty +
graph.scan_dir +

+

cyan.interaction +
interaction.yes_no_prompt +

+

cyan.log +
Logger:cont +
Logger:cont_nonl +
Logger:format +
Logger:format_nonl +
Logger:nonl +
Logger:should_log +
Logger +
Verbosity +
create_logger +
log.set_prefix_padding +
log.set_verbosity +

+

cyan.meta +

+

cyan.sandbox +

+

cyan.script +
script.disable +
script.emit_hook +
script.emitter +
script.ensure_loaded_for_command +
script.register +

+

cyan.tlcommon +
ParseResult +
common.init_env_from_config +
common.init_teal_env +
common.lex_file +
common.make_error_header +
common.parse_file +
common.prepend_to_lua_path +
common.report_config_errors +
common.report_env_results +
common.report_errors +
common.report_result +
common.result_has_errors +
common.search_module +
common.type_check_ast +

+

cyan.util +
str.esc +
str.pad_left +
str.split +
str.split_find +
tab.contains +
tab.filter +
tab.from +
tab.intersperse +
tab.ivalues +
tab.keys +
tab.map +
tab.map_ipairs +
tab.merge_list +
tab.set +
tab.sort_in_place +
tab.values +

+
+ +

cyan.ansi +

+

A small utility library for grabbing the ANSI escapes for colors and such

+

cyan.cli +

+

The command line driver

This is not a module to be used and requiring it will attempt to start the cli and call os.exit

+

cyan.colorstring +

+

Some wrappers/conveniences around working with ansi escape codes. For example getting the length of a string that contains escape codes shouldnt include them

+

ColorString:len(): integer +

+

Get the length of a given ColorString, not counting any escape sequences.

Note that ColorString:len() >= ColorString:tostring():len()

+

ColorString:surround(col: {integer}) +

+

surrounds a string with a color

+

ColorString:to_raw(): string +

+

Converts a Colorstring to a regular string, stripping any ANSI escapes

+

ColorString:tostring(): string +

+

Converts a Colorstring to a regular string with the correct ANSI escapes

+

type ColorString +

+
record ColorString
   content: {string | {integer}}
   len: function(ColorString): integer
   tostring: function(ColorString): string

   metamethod __len: function(ColorString): integer
   metamethod __concat: function(ColorString | string, ColorString | string): ColorString
end
+

The main object that this library consumes and produces. It basically implements the 'string' interface and can be used wherever a string is.

Colors are described as arrays of numbers that directly correspond to ANSI escape sequences

+

colorstring.highlight(hl: {integer}, str: string): ColorString +

+

Create a Colorstring by surrounding a string with the given ANSI color and an ANSI reset

+

colorstring.new(...: string | {integer}): ColorString +

+

The Colorstring constructor

+

colorstring.rgb_bg(r: integer, g: integer, b: integer): {integer, integer, integer, integer, integer} +

+

The ansi escape for an arbitrary RGB background color

+

colorstring.rgb_fg(r: integer, g: integer, b: integer): {integer, integer, integer, integer, integer} +

+

The ansi escape for an arbitrary RGB foreground color

+

cyan.command +

+

The common interface for commands to implement

+

type Command +

+
record Command
   name: string
   description: string
   argparse: function(argparse.Command)
   script_hooks: {string}
   exec: CommandFn
end
+

The interface

+

command.get(name: string): Command +

+

Get a command that was created with command.new

Works whether or not command.register_all was called

+

command.merge_args_into_config(cfg: config.Config, args: Args) +

+

Merge the relevant entries of the provided command arguments into the provided config table

+

command.new(cmd: Command) +

+

Create a new command

This is stored in an internal cache and will do nothing unless command.register_all is called afterwards

+

command.register_all(p: argparse.Parser) +

+

Install all commands created with command.new into the given parser

+

cyan.config +

+

Config loading API

+

type Config +

+
record Config
   loaded_from: fs.Path
   build_dir: string
   source_dir: string
   include: {string}
   exclude: {string}
   global_env_def: string
   include_dir: {string}
   module_name: string
   dont_prune: {string}
   scripts: {string:{string:string|{string}}}
   gen_compat: tl.CompatMode
   gen_target: tl.TargetMode
   disable_warnings: {tl.WarningKind}
   warning_error: {tl.WarningKind}
   externals: {string:any}
end
+

The config data

+

config.find(): fs.Path +

+

Find config.filename in the current or parent directories

+

config.is_config(c: any): Config, {string}, {string} +

+

Check if c conforms to the Config type and return any errors and warnings generated from checking

+

config.load(): Config, {string}, {string} +

+

Try to load tlconfig.lua in the current directory

+

cyan.fs.path +

+

Object oriented lexical path management

+

Path.eq(a: Path | string, b: Path | string, use_os_sep: boolean): boolean +

+

Check if two paths are equal

This function is used for the __eq metamethod with use_os_sep as false

+

Path:ancestors(): function(): Path +

+

Iterate over the leading folders in a path

ex: path.new("foo/bar/baz/bat"):ancestors() will construct Path objects from "foo", "foo/bar", "foo/bar/baz"

+

Path:append(other: string | Path) +

+

Mutate the given Path by appending another path to it

Traversals in the other path will be normalized

 local p = path.new "foo/bar"
 p:append "../baz"
 assert(p == path.new "foo/baz")

+

Path:copy(): Path +

+

Create a copy of the given path

+

Path:exists(): boolean +

+

Check if the path exists

+

Path:is_absolute(): boolean +

+

Returns whether the path is absolute

On windows, checks for paths like "C:\...", elsewhere looks for "/..."

+

Path:is_directory(): boolean +

+

Get whether the "mode" attribute of the given path is set to "directory"

+

Path:is_file(): boolean +

+

Get whether the "mode" attribute of the given path is set to "file"

+

Path:is_in(dirname: string | Path, use_os_sep: boolean): boolean +

+

returns true if the path is inside the given directory

If relative and absolute paths are mixed, the relative path is assumed to be in the current working directory (as determined by lfs.currentdir())

If dirname is a string, a path will be constructed using path.new with use_os_sep

+

Path:match(patt: string): boolean +

+

See if the given path matches the pattern

Path separators in patterns are always represented with '/'.

* characters represent any number of non-path-separator characters

**/ represent any number of directories

+

Path:match_any(patts: {string}): integer, string +

+

See if the given path matches any of the given patterns

+

Path:mk_parent_dirs(): boolean, string +

+

Attempt to create the leading directories of a given path

+

Path:mkdir(): boolean, string +

+

Attempt to create a directory at the given path, creating the parent directories if needed. Can be seen as an equivalent to mkdir -p

+

Path:mod_time(): integer +

+

Get the "modification" attribute of a file

+

Path:normalize() +

+

Modify path in place to remove any traversals that it can

 local p = path.new "foo/bar/../baz"
 p:normalize()
 assert(p == path.new "foo/baz")

if a traversal can't be removed it will remain 

 local p = path.new "../baz"
 p:normalize()
 assert(p == path.new "../baz")

+

Path:prepend(other: string | Path) +

+

Mutate the given Path by prepending another path to it

+

Path:relative_to(other: Path): Path +

+

Expresses a path in terms of another path. If any relative paths are given, they are treated as though they are in the current directory

for example: path.new("/foo/bar/baz"):relative_to(path.new("/foo/bat")) == path.new "../bar/baz"

+

Path:remove_leading(p: string | Path) +

+

Mutate the given path by removing the leading parts from the given path

Will error if you attempt to mix absolute and non-absolute paths

+

Path:to_absolute() +

+

Modify a path in place to become an absolute path

When the path is already absolute, does nothing

Otherwise, prepends the current directory

+

Path:to_real_path(): string +

+

Convert a Path to a string describing a real path

+

Path:tostring(): string +

+

Convert a path to a string. Always uses '/' as a path separator. Intended for displaying purposes. For an actual path in the filesystem, use Path:to_real_path()

Used for the __tostring metamethod

+

type Path +

+
record Path
   {string}

   metamethod __concat: function(Path | string, Path | string): Path
   metamethod __eq: function(Path | string, Path | string): boolean
end
+

The main path object. Basically just an array of strings with some methods and metamethods to interact with other paths

+

path.ensure(s: string | Path, use_os_sep: boolean): Path +

+

Ensures s is a Path.

If s is a string, parse it into a path otherwise return s unmodified

+

path.new(s: string, use_os_sep: boolean): Path +

+

The Path constructor

By default uses '/' as a path separator

+

cyan.fs +

+

Filesystem and path management

+

fs.chdir(p: string | Path): boolean, string +

+

Change the current directory to p

+

fs.copy(source: string | Path, dest: string | Path): boolean, string +

+

Copy a file

uses fs.read internally to get and cache the contents of source

+

fs.cwd(): Path +

+

Get the current working directory as an fs.Path

+

fs.dir(dir: string | Path, include_dotfiles: boolean): function(): Path +

+

Iterate over the given directory, returning fs.Path objects

By default, will not include paths that start with '.'

+

fs.extension_split(p: Path | string, ndots: integer): string, string +

+

Split a path on its extension. Forces the extension to be lowercase.

the ndots argument lets you specify the upper limit of how many dots the extension can have

ex: 

 fs.extension_split("foo.d.tl") => "foo.d", ".tl"
 fs.extension_split("foo.d.tl", 2) => "foo", ".d.tl"
 fs.extension_split("foo.D.TL", 2) => "foo", ".d.tl"

+

fs.get_line(p: string, n: integer): string, string +

+

Gets line n of a file.

if the file is less than n lines, returns nil

if there was an error opening the file, returns nil, err

Uses fs.read() internally, which caches reads

+

fs.path_concat(a: string, b: string): string +

+

Concatenate two strings using the os path separator

+

fs.read(p: string): string, string +

+

Open a file, read it, close the file, return the contents or nil and an error if it couldn't be opened

Additionally caches results so multiple locations can read the same file for minimal cost. There is currently no way to clear out this cache.

+

fs.scan_dir(dir: string | Path, include: {string}, exclude: {string}, include_directories: boolean): function(): Path +

+

Recursively iterate over the files in a directory, following the provided include and exclude patterns

For information on path patterns, see the Path:match() method

+

fs.search_parent_dirs(start_path: string | Path, fname: string): Path +

+

Search for a file in the parent directories of the given path. Returns the path of the file found.

e.g. if file.txt is in /foo/bar, then fs.search_parent_dirs("/foo/bar/baz", "file.txt") == path.new "/foo/bar/file.txt"

+

cyan.graph +

+

A utility for building directed acyclic graphs of Teal source files

This is the main driver behind the build command

+

Dag:find(fstr: string | fs.Path): Node +

+

Find a node in the graph with the given path name

+

Dag:insert_file(fstr: string | fs.Path, in_dir: string | fs.Path): boolean, {string} +

+

Inserts a file and its dependencies into a graph

Ignores absolute paths and non .tl or .lua files

If in_dir is provided, dependencies of the given file will not be added to the graph unless they are inside of the given dir

Returns false if inserting the file introduced a circular dependency along with a list of the filenames in the cycle

+

Dag:mark_each(predicate: function(fs.Path): boolean) +

+

For each node in the graph, if predicate returns true for that input path, the node is marked for compilation, and that node's children are marked for type checking

+

Dag:marked_nodes(): function(): Node +

+

Iterate over every node that has been marked, no matter what the mark is

+

Dag:nodes(): function(): Node +

+

Iterate over nodes in order of dependents

If two nodes have the same number of dependent nodes, the order of iteration between those two nodes is not guaranteed

+

type Dag +

+
record Dag
   
-- private fields
   _nodes_by_filename: {string:Node}

end
+

The graph object

+

type Node +

+
record Node
   input: fs.Path
   output: fs.Path
   modules: {string:fs.Path}
   mark: Mark
   dependents: {Node:boolean}
end
+

The nodes that are stored in the graph

+

graph.empty(): Dag +

+

Initializes an empty graph

+

graph.scan_dir(dir: string | fs.Path, include: {string}, exclude: {string}): Dag, {string} +

+

Recursively scan a directory (using fs.scan_dir) and build up a graph, respecting the given include and exclude patterns

Returns nil if a circular dependency was found, along with a list of the filenames in the cycle

+

cyan.interaction +

+

Module for handling when input from the user is needed

+

interaction.yes_no_prompt( + prompt: string, + logger: log.Logger, + default: boolean, + affirm: {string}, + deny: {string} +): boolean +

+

Ask the user to affirm or deny a given prompt. The user input will be compared against the given affirm and deny lists (case-insensitive), with defaults used if - they are not provided.

The given logger will be used to print the prompt, and log.info if none is provided.

+

cyan.log +

+

Console logging utils, not to be confused with log files

Each logger object has the same __call signature of function(...: any), and by default the following are provided:

Name Stream Description
info stdout General info, should be seen as the default, silenced by --quiet
extra stdout Extra info that isn't strictly necessary, enabled via -v extra, silenced by --quiet
warn stderr Used to display warnings, silenced by --quiet
err stderr Used to display errors
debug stderr Used for debugging, uses the inspect module (if it is found) to print its arguments, enabled by -v debug

You may notice that these are nicely padded and after the first line the prefix is replaced by a '...'. Another function is provided, create_logger,

 create_logger: function(
    stream: FILE,
    verbosity_threshold: Verbosity,
    prefix: string | ColorString,
    cont: string | ColorString,
    inspector: function(any): string
 ): Logger

to automatically generate formatted output. cont defaults to "..." and inspector defaults to tostring. Prefixes will be padded to 10 characters wide by default, so your logging may look off from the default if your prefix is longer.

Additionally, loggers will try to detect whether or not to display colors. This is only handled with the ColorString type to avoid the many pitfalls of trying to parse ANSI escape sequences. If a regular string contains any escape sequences or an inspector produces them (outside of a ColorString) it will not be handled.

+

Logger:cont(...: any) +

+

Log only using the continuation prefix.

+

Logger:cont_nonl(...: any) +

+

Log only using the continuation prefix, but don't put a newline at the end.

+

Logger:format(fmt: string, ...: any) +

+

Call string.format with the given arguments and log that.

+

Logger:format_nonl(fmt: string, ...: any) +

+

Call string.format with the given arguments and log that, without a new line.

+

Logger:nonl(...: any) +

+

Same as calling the logger, but don't put a newline at the end

+

Logger:should_log(): boolean +

+

Returns whether the current verbosity is less than or equal to this loggers verbosity threshold.

+

type Logger +

+
record Logger
   stream: FILE
   verbosity_threshold: Verbosity
   prefix: string | cs.ColorString
   continuation: string | cs.ColorString
   inspector: function(any): string

   metamethod __call: function(...: any)
end
+

The data needed for a logger to do its job.

+

type Verbosity +

+
enum Verbosity
   "quiet"
   "normal"
   "extra"
   "debug"
end
+

The thresholds for loggers to actually write their output

+

create_logger( + stream: FILE, + verbosity_threshold: Verbosity, + prefix: string | cs.ColorString, + cont: string | cs.ColorString, + inspector: function(any): string +): Logger +

+

Creates a Logger as described above

+

log.set_prefix_padding(padding: integer) +

+

Globally set the padding of the prefixes of loggers.

+

log.set_verbosity(level: Verbosity) +

+

Globally set the verbosity of the logging module.

+

cyan.meta +

+

Meta information about Cyan itself

+

cyan.sandbox +

+

Super simplistic sandboxing In the future maybe could be integrated with some very simple debugging utilities for now, we just offer the convenience of exiting gracefully if someone puts while true do end in their config for some reason

+

cyan.script +

+

The script loading api

+

script.disable() +

+

Make everything in this library a no-op, there is currently no way to re-enable this

+

script.emit_hook(name: string, ...: any): boolean, string +

+

Iterates through each loaded script and runs any with the given hook, logging each script that it ran, and stopping early if any error

+

script.emitter(name: string, ...: any): function(): fs.Path, boolean, string +

+

Emit a hook to load and run all registered scripts that run on the given hook.

This function will assert that ensure_loaded_for_command was called before.

Returns an iterator that will run the next script when called and returns the path to the script, whether the script was loaded and ran with no errors, and an error message if it didn't

+

script.ensure_loaded_for_command(name: string): boolean, string | tl.Result +

+

Attempts to load each script that the given command may need

+

script.register(path: string, command_name: string, hooks: string | {string}) +

+

Registers a file path as a lua/teal script to execute for the given hook(s) when script.emit_hook is called

This is called by the cli driver to register the scripts found in the config file with the relevant hooks

Note: this function does not attempt to actually load the file. Scripts are loaded all at once via ensure_loaded_for_command

+

cyan.tlcommon +

+

Common things needed by most commands in addition to wrappers around the tl api, since it isn't super stable

+

type ParseResult +

+
record ParseResult
   tks: {Token}
   ast: Node
   reqs: {string}
   errs: {tl.Error}
end
+

The result from parsing source code including the tokens, ast, calls to require, and errors

+

common.init_env_from_config(cfg: config.Config): tl.Env, string +

+

Initialize a strict Teal environment, using the relevant entries of the config to modify that environment

may return nil and an error message if something could not be applied to the environment

+

common.init_teal_env(gen_compat: boolean | tl.CompatMode, gen_target: tl.TargetMode, env_def: string): tl.Env, string +

+

Initialize a strict Teal environment

+

common.lex_file(path: string): {Token}, {tl.Error}, string +

+

reads a file, calls tl.lex on its contents, caches and returns the results

+

common.make_error_header(file: string, num_errors: integer, category: string): cs.ColorString +

+

Creates a nicely colored header to log errors

For example make_error_header("foo.tl", 10, "foo error") would produce something like 10 foo errors in foo.tl with 10 and foo.tl highlighted

+

common.parse_file(path: string): ParseResult, string +

+

calls lex_file, parses the token stream, caches and returns the results

+

common.prepend_to_lua_path(path_str: string) +

+

Prepend the given string to package.path and package.cpath.

Correctly adds ?.lua and ?/init.lua to the path

+

common.report_config_errors(errs: {string}, warnings: {string}): boolean +

+

use log.warn and log.err to report errors and warnings from config.load

+

common.report_env_results(env: tl.Env, cfg: config.Config): boolean +

+

Report all errors from a tl.Env

Returns false when errors were reported

+

common.report_errors(logger: log.Logger, errs: {tl.Error}, file: string, category: string) +

+

Logs an array of errors with nice colors and a header generated by make_error_header

+

common.report_result(r: tl.Result, c: config.Config): boolean +

+

Logs all the syntax errors, warnings, type errors, etc. from a tl.Result with proper colors

Returns false if there were any errors. This includs warnings that were promoted to errors and doesn't include warnings that were not promoted to errors.

+

common.result_has_errors(r: tl.Result, c: config.Config): boolean +

+

Returns whether or not the result has errors. Doesn't print/log anything

+

common.search_module(name: string, search_dtl: boolean): fs.Path +

+

A wrapper around tl.search_module but, returns an fs.Path and will cache results

+

common.type_check_ast(ast: Node, opts: tl.TypeCheckOptions): tl.Result, string +

+

Just type checks an ast

+

cyan.util +

+

Basically some extensions of the std lib. Currently these lean towards a more functional style

This is split into two main modules, str and tab. For string and table utilities respectively.

+

str.esc(s: string, sub: string | function(string): string | {string:string}): string, integer +

+

escape any special characters in a string

use sub to control how the characters are substituted, by default a special character x will be replaced with %x

returns the new string and the number of characters replaced

+

str.pad_left(s: string, n: integer): string +

+

Prefix s with spaces so the resulting string is at least n characters long

+

str.split(s: string, del: string, no_patt: boolean): function(): string +

+

Split a string by del, returning the substring that was matched

Will error if the delimiter matches the empty string

+

str.split_find(s: string, del: string, no_patt: boolean): function(): integer, integer +

+

Split a string by del, returning the indexes of the match

Will error if the delimiter matches the empty string

+

tab.contains<Value>(t: {Value}, val: Value): boolean +

+

Report if an array contains an element (as determined by the == operator)

+

tab.filter<Value>(t: {Value}, pred: function(Value): boolean): {Value}, {Value} +

+

Create two new lists from t: the values that return true from pred and the values that return false

+

tab.from<Value>(fn: function(...: any): (Value), ...: any): {Value} +

+

Collect all the values of an iterator in a list

+

tab.intersperse<Value>(t: {Value}, val: Value): {Value} +

+

produce a new list by inserting val after each element

+

tab.ivalues<Value>(t: {any:Value}): function(): Value +

+

Iterate over the integer indexed values of a map

+

tab.keys<Key>(t: {Key:any}): function(): Key +

+

Iterate over the keys of a map

+

tab.map<Key, Value, MappedValue>(t: {Key:Value}, fn: function(Value): MappedValue): {Key:MappedValue} +

+

Create a new map from t by passing each value through fn

+

tab.map_ipairs<Value, MappedValue>(t: {Value}, fn: function(Value): MappedValue): function(): integer, MappedValue +

+

iterate over a list like ipairs does, but filter the values through fn

+

tab.merge_list<Value>(a: {Value}, b: {Value}): {Value} +

+

Create a new list by shallow copying the contents of a and b

+

tab.set<Value>(lst: {Value}): {Value:boolean} +

+

Create a Set from a list

+

tab.sort_in_place<Value>(t: {Value}, fn: function(Value, Value): boolean): {Value} +

+

Sort a table (in place) and return that table

+

tab.values<Key, Value>(t: {Key:Value}): function(): Value +

+

Iterate over the values of a map

+ + + diff --git a/scripts/docgen.tl b/scripts/docgen.tl index 259de75..edcef1e 100644 --- a/scripts/docgen.tl +++ b/scripts/docgen.tl @@ -241,9 +241,16 @@ emit["record_declaration"] = function(prefix: {string}, n: ts.Node, out: {string end local query = teal_parser:query[[ - ((comment)+ @com + ((comment) @kind + . (comment)* @docs . (_) @obj - (#match? @com "^%-%-%-@%w+$")) ]] + (#match? @kind "^%-%-%-@%w+$") + (#is-not-comment? @obj)) ]] + :with { + ["is-not-comment?"] = function(n: ts.Node): boolean + return n:type() ~= "comment" + end, + } local record Doc kind: string @@ -263,92 +270,85 @@ local function gen_docs(filename: string, module_name: string): string, {string} local docs : {Doc} = {} for match in query:match(root) do - local caps = match.captures as {ts.Node} - local n = caps[match.capture_count as integer] - local s = n:type() - if s ~= "comment" then - -- obj will match comments as the query will produce EVERY match - -- resulting in the same nodes being matched over and over - -- this basically guarantees the match we actually care about - local obj = table.remove(caps, match.capture_count) - local kind_node = table.remove(caps, 1) - local kind = kind_node:source():match("^%-%-%-@(%w+)") - if kind == "nodoc" then - return - end - local lines = {} - local content: {string} = {} - local current_state: string - local n_leading_spaces: integer - local function ins(str: string) - if str:match("^%s*$") then return end - table.insert(content, str) + local kind_node = match.captures.kind as ts.Node + local kind = kind_node:source():match("^%-%-%-@(%w+)") + local comments = match.captures.docs as {ts.Node} or {} + local obj = match.captures.obj as ts.Node + if kind == "nodoc" then + return + end + local lines = {} + local content: {string} = {} + local current_state: string + local n_leading_spaces: integer + local function ins(str: string) + if str:match("^%s*$") then return end + table.insert(content, str) + end + for i, v in ipairs(comments) do + local src = v:source() + if not src:match("^%-%-%-") then + break end - for i, v in ipairs(caps) do - local src = v:source() - if not src:match("^%-%-%-") then - break - end - local sub , rest = src:match("^%-%-%-@@(%w+)(.*)%s*$") - -- TODO: make a proper state machine for this - if sub then - if sub == "end" then - if current_state == "table" then - ins("

") - elseif current_state == "code" then - ins("

") - end - current_state = nil - elseif current_state then - error("Attempt to use @@" .. sub .. " inside of @@" .. current_state) - else - current_state = sub - if current_state == "table" then - ins("

") - local row = { "" } - for col in rest:gmatch("[^|]+") do - table.insert(row, "") - end - table.insert(row, "") - ins(table.concat(row)) - elseif current_state == "code" then - ins("

")
-                  end
+         local sub , rest  = src:match("^%-%-%-@@(%w+)(.*)%s*$")
+         -- TODO: make a proper state machine for this
+         if sub then
+            if sub == "end" then
+               if current_state == "table" then
+                  ins("
" .. col .. "

") + elseif current_state == "code" then + ins("

") end + current_state = nil + elseif current_state then + error("Attempt to use @@" .. sub .. " inside of @@" .. current_state) else - local leadingws , line = src:match("^%-%-%-(%s*)(.*)%s*$") - if i == 1 then - n_leading_spaces = #leadingws - else - line = leadingws:sub(n_leading_spaces + 1, -1) .. line - end + current_state = sub if current_state == "table" then - local row = { "" } - for col in line:gmatch("[^|]+") do - table.insert(row, "" .. escape_html_chars(col) .. "") + ins("

") + local row = { "" } + for col in rest:gmatch("[^|]+") do + table.insert(row, "") end table.insert(row, "") ins(table.concat(row)) elseif current_state == "code" then - ins(line .. "
") + ins("

")
+               end
+            end
+         else
+            local leadingws , line = src:match("^%-%-%-(%s*)(.*)%s*$")
+            if i == 1 then
+               n_leading_spaces = #leadingws
+            else
+               line = leadingws:sub(n_leading_spaces + 1, -1) .. line
+            end
+            if current_state == "table" then
+               local row = { "
" } + for col in line:gmatch("[^|]+") do + table.insert(row, "") + end + table.insert(row, "") + ins(table.concat(row)) + elseif current_state == "code" then + ins(line .. "
") + else + if line == "" and #content > 0 then + table.insert(lines, "

" .. table.concat(content, " ") .. "

") + content = {} else - if line == "" and #content > 0 then - table.insert(lines, "

" .. table.concat(content, " ") .. "

") - content = {} - else - ins(line) - end + ins(line) end end end - assertf(not current_state, "Unended doc block %q in %s", current_state, filename) - table.insert(lines, "

" .. table.concat(content, " ") .. "

") - table.insert(docs, { - kind = kind, - content = lines, - obj = obj, - }) end + assertf(not current_state, "Unended doc block %q in %s", current_state, filename) + table.insert(lines, "

" .. table.concat(content, " ") .. "

") + table.insert(docs, { + kind = kind, + content = lines, + obj = obj, + }) end local brief: string
" .. col .. "
" .. escape_html_chars(col) .. "