Something went wrong. Try again.
Library of 45+ independent Lua modules improving Neovim experience with minimal effort nvim-mini.org/mini.nvim
Something went wrong. Try again.
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372--- *mini.doc* Generate Neovim help files------ MIT License Copyright (c) 2022 Evgeni Chasnovski
--- Key design ideas:--- - Keep documentation next to code by writing EmmyLua-like annotation--- comments. They will be parsed as is, so formatting should follow built-in--- guide in |help-writing|. However, custom hooks are allowed at many--- generation stages for more granular management of output help file.------ - Generation is done by processing a set of ordered files line by line.--- Each line can either be considered as a part of documentation block (if--- it matches certain configurable pattern) or not (considered to be an--- "afterline" of documentation block). See |MiniDoc.generate()| for more--- details.------ - Processing is done by using nested data structures (section, block, file,--- doc) describing certain parts of help file. See |MiniDoc-data-structures|--- for more details.------ - Project specific script can be written as plain Lua file with--- configuratble path. See |MiniDoc.generate()| for more details.------ What it doesn't do:--- - It doesn't support markdown or other markup language inside annotations.--- - It doesn't use treesitter in favor of Lua string manipulation for basic--- tasks (parsing annotations, formatting, auto-generating tags, etc.). This--- is done to manage complexity and be dependency free.------ # Setup ~------ This module needs a setup with `require('mini.doc').setup({})` (replace--- `{}` with your `config` table). It will create global Lua table `MiniDoc`--- which you can use for scripting or manually (with `:lua MiniDoc.*`).------ See |MiniDoc.config| for available config settings.------ You can override runtime config settings locally to buffer inside--- `vim.b.minidoc_config` which should have same structure as `MiniDoc.config`.--- See |mini.nvim-buffer-local-config| for more details.------ To stop module from showing non-error feedback, set `config.silent = true`.------ # Tips ~------ - Some settings tips that might make writing annotation comments easier:--- - Set up appropriate |'comments'| for `lua` file type to respect--- EmmyLua-like's `---` comment leader. Value `:---,:--` seems to work.--- - Set up appropriate |'formatoptions'| (see also |fo-table|). Consider--- adding `j`, `n`, `q`, and `r` flags.--- - Set up appropriate |'formatlistpat'| to help auto-formatting lists (if--- `n` flag is added to |'formatoptions'|). One suggestion (not entirely--- ideal) is a value `^\s*[0-9\-\+\*]\+[\.\)]*\s\+`. This reads as "at--- least one special character (digit, `-`, `+`, `*`) possibly followed--- by some punctuation (`.` or `)`) followed by at least one space is a--- start of list item".--- - Probably one of the most reliable resources for what is considered to be--- best practice when using this module is this whole plugin. Look at source--- code for the reference.------ # Comparisons ~------ - [tjdevries/tree-sitter-lua](https://github.com/tjdevries/tree-sitter-lua):--- - Its key design is to use treesitter grammar to parse both Lua code--- and annotation comments. This makes it not easy to install,--- customize, and support.--- - It takes more care about automating output formatting (like auto--- indentation and line width fit). This plugin leans more to manual--- formatting with option to supply customized post-processing hooks.---@tag MiniDoc
--- Data structures------ Data structures are basically arrays of other structures accompanied with--- some fields (keys with data values) and methods (keys with function--- values):--- - `Section structure` is an array of string lines describing one aspect--- (determined by section id like `@param`, `@return`, `@text`) of an--- annotation subject. All lines will be used directly in help file.--- - `Block structure` is an array of sections describing one annotation--- subject like function, table, concept.--- - `File structure` is an array of blocks describing certain file on disk.--- Basically, file is split into consecutive blocks: annotation lines go--- inside block, non-annotation - inside `block_afterlines` element of info.--- - `Doc structure` is an array of files describing a final help file. Each--- string line from section (when traversed in depth-first fashion) goes--- directly into output file.------ All structures have these keys:--- - Fields:--- - `info` - contains additional information about current structure.--- For more details see next section.--- - `parent` - table of parent structure (if exists).--- - `parent_index` - index of this structure in its parent's array. Useful--- for adding to parent another structure near current one.--- - `type` - string with structure type (section, block, file, doc).--- - Methods (use them as `x:method(args)`):--- - `insert(self, [index,] child)` - insert `child` to `self` at position--- `index` (optional; if not supplied, child will be appended to end).--- Basically, a `table.insert()`, but adds `parent` and `parent_index`--- fields to `child` while properly updating `self`.--- - `remove(self [,index])` - remove from `self` element at position--- `index`. Basically, a `table.remove()`, but properly updates `self`.--- - `has_descendant(self, predicate)` - whether there is a descendant--- (structure or string) for which `predicate` returns `true`. In case of--- success also returns the first such descendant as second value.--- - `has_lines(self)` - whether structure has any lines (even empty ones)--- to be put in output file. For section structures this is equivalent to--- `#self`, but more useful for higher order structures.--- - `clear_lines(self)` - remove all lines from structure. As a result,--- this structure won't contribute to output help file.------ Description of `info` fields per structure type:--- - `Section`:--- - `id` - captured section identifier. Can be empty string meaning no--- identifier is captured.--- - `line_begin` - line number inside file at which section begins (-1 if--- not generated from file).--- - `line_end` - line number inside file at which section ends (-1 if not--- generated from file).--- - `Block`:--- - `afterlines` - array of strings which were parsed from file after--- this annotation block (up until the next block or end of file).--- Useful for making automated decisions about what is being documented.--- - `line_begin` - line number inside file at which block begins (-1 if--- not generated from file).--- - `line_end` - line number inside file at which block ends (-1 if not--- generated from file).--- - `File`:--- - `path` - absolute path to a file (`''` if not generated from file).--- - `Doc`:--- - `input` - array of input file paths (as in |MiniDoc.generate()|).--- - `output` - output path (as in |MiniDoc.generate()|).--- - `config` - configuration used (as in |MiniDoc.generate()|).---@tag MiniDoc-data-structures
-- Module definition ==========================================================local MiniDoc = {}local H = {}
--- Module setup------@param config table|nil Module config table. See |MiniDoc.config|.------@usage >lua--- require('mini.doc').setup() -- use default config--- -- OR--- require('mini.doc').setup({}) -- replace {} with your config table--- <MiniDoc.setup = function(config) -- TODO: Remove after Neovim=0.9 support is dropped if vim.fn.has('nvim-0.10') == 0 then vim.notify( '(mini.doc) Neovim<0.10 is soft deprecated (module works but is not supported).' .. " It will be deprecated after the next 'mini.nvim' release (module might not work)." .. ' Please update your Neovim version.' ) end
-- Export module _G.MiniDoc = MiniDoc
-- Setup config config = H.setup_config(config)
-- Apply config H.apply_config(config)end
--- Defaults ~---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)---@text # Notes ~------ - `annotation_extractor` takes single string line as input. Output--- describes what makes an input to be an annotation (if anything). It--- should be similar to `string.find` with one capture group: start and end--- of annotation indicator (whole part will be removed from help line) with--- third value being string of section id (if input describes first line of--- section; `nil` or empty string otherwise). Output should be `nil` if line--- is not part of annotation.--- Default value means that annotation line should:--- - Start with `---` at first column.--- - Any non-whitespace after `---` will be treated as new section id.--- - Single whitespace at the start of main text will be ignored.--- - Hooks are expected to be functions. Their default values might do many--- things which might change over time, so for more information please look--- at source code. Some more information can be found in--- |MiniDoc.default_hooks|.MiniDoc.config = { -- Function which extracts part of line used to denote annotation. -- For more information see 'Notes' in |MiniDoc.config|. annotation_extractor = function(l) return string.find(l, '^%-%-%-(%S*) ?') end,
-- Identifier of block annotation lines until first captured identifier default_section_id = '@text',
-- Hooks to be applied at certain stage of document life cycle. Should -- modify its input in place (and not return new one). hooks = { -- Applied to block before anything else --minidoc_replace_start block_pre = --<function: infers header sections (tag and/or signature)>, block_pre = function(b) -- Infer metadata based on afterlines if b:has_lines() and #b.info.afterlines > 0 then H.infer_header(b) end end, --minidoc_replace_end
-- Applied to section before anything else --minidoc_replace_start section_pre = --<function: replaces current aliases>, section_pre = function(s) H.alias_replace(s) end, --minidoc_replace_end
-- Applied if section has specified captured id sections = { --minidoc_replace_start ['@alias'] = --<function: registers alias in MiniDoc.current.aliases>, ['@alias'] = function(s) H.alias_register(s) -- NOTE: don't use `s.parent:remove(s.parent_index)` here because it -- disrupts iteration over block's section during hook application -- (skips next section). s:clear_lines() end, --minidoc_replace_end --minidoc_replace_start ['@class'] = --<function>, ['@class'] = function(s) H.enclose_var_name(s) H.add_section_heading(s, 'Class') end, --minidoc_replace_end --minidoc_replace_start ['@diagnostic'] = --<function: ignores any section content>, ['@diagnostic'] = function(s) s:clear_lines() end, --minidoc_replace_end -- For most typical usage see |MiniDoc.afterlines_to_code| --minidoc_replace_start ['@eval'] = --<function: evaluates lines; replaces with their return>, ['@eval'] = function(s) local src = table.concat(s, '\n') local is_loaded, code = pcall(function() return assert(loadstring(src)) end) local output if is_loaded then MiniDoc.current.eval_section = s output = code() MiniDoc.current.eval_section = nil else output = 'MINIDOC ERROR. Parsing Lua code gave the following error:\n' .. code end
s:clear_lines()
if output == nil then return end if type(output) == 'string' then output = vim.split(output, '\n') end if type(output) ~= 'table' then s[1] = 'MINIDOC ERROR. Returned value should be `nil`, `string`, or `table`.' return end for _, x in ipairs(output) do s:insert(x) end end, --minidoc_replace_end --minidoc_replace_start ['@field'] = --<function>, ['@field'] = function(s) H.mark_optional(s) H.enclose_var_name(s) local col_past_var_name = s[1]:match('^%s*%S+%s+`%(optional%)`()') or s[1]:match('^%s*%S+()') or 1 H.enclose_type(s, col_past_var_name) end, --minidoc_replace_end --minidoc_replace_start ['@overload'] = --<function>, ['@overload'] = function(s) s[1] = '`' .. s[1] .. '`' H.add_section_heading(s, 'Overload') end, --minidoc_replace_end --minidoc_replace_start ['@param'] = --<function>, ['@param'] = function(s) H.mark_optional(s) H.enclose_var_name(s) local col_past_var_name = s[1]:match('^%s*%S+%s+`%(optional%)`()') or s[1]:match('^%s*%S+()') or 1 H.enclose_type(s, col_past_var_name) end, --minidoc_replace_end --minidoc_replace_start ['@private'] = --<function: registers block for removal>, ['@private'] = function(s) s.parent:clear_lines() end, --minidoc_replace_end --minidoc_replace_start ['@return'] = --<function>, ['@return'] = function(s) H.mark_optional(s) H.enclose_type(s, 1) H.add_section_heading(s, 'Return') end, --minidoc_replace_end --minidoc_replace_start ['@seealso'] = --<function>, ['@seealso'] = function(s) H.add_section_heading(s, 'See also') end, --minidoc_replace_end --minidoc_replace_start ['@signature'] = --<function: formats signature of documented object>, ['@signature'] = function(s) for i, _ in ipairs(s) do -- Add extra formatting to make it stand out s[i] = H.format_signature(s[i])
-- Align accounting for concealed characters s[i] = H.align_text(s[i], 78, 'center') end end, --minidoc_replace_end --minidoc_replace_start ['@tag'] = --<function: turns its line in proper tag lines>, ['@tag'] = function(s) for i, _ in ipairs(s) do -- Enclose every word in `*` s[i] = s[i]:gsub('(%S+)', '%*%1%*')
-- Align to right edge accounting for concealed characters s[i] = H.align_text(s[i], 78, 'right') end end, --minidoc_replace_end --minidoc_replace_start ['@text'] = --<function: purposefully does nothing>, ['@text'] = function() end, --minidoc_replace_end --minidoc_replace_start ['@toc'] = --<function: clears all section lines>, ['@toc'] = function(s) s:clear_lines() end, --minidoc_replace_end --minidoc_replace_start ['@toc_entry'] = --<function: registers lines for table of contents>, ['@toc_entry'] = function(s) H.toc_register(s) end, --minidoc_replace_end --minidoc_replace_start ['@type'] = --<function>, ['@type'] = function(s) H.enclose_type(s, 1) H.add_section_heading(s, 'Type') end, --minidoc_replace_end --minidoc_replace_start ['@usage'] = --<function>, ['@usage'] = function(s) H.add_section_heading(s, 'Usage') end, --minidoc_replace_end },
-- Applied to section after all previous steps --minidoc_replace_start section_post = --<function: currently does nothing>, section_post = function(s) end, --minidoc_replace_end
-- Applied to block after all previous steps --minidoc_replace_start block_post = --<function: does many things>, block_post = function(b) if not b:has_lines() then return end
local found_param, found_field = false, false local n_tag_sections, last_line = 0, nil H.apply_recursively(function(x) if not (type(x) == 'table' and x.type == 'section') then return end
-- Add headings before first occurrence of a section which type usually -- appear several times if not found_param and x.info.id == '@param' then H.add_section_heading(x, 'Parameters') found_param = true end if not found_field and x.info.id == '@field' then H.add_section_heading(x, 'Fields') found_field = true end
if x.info.id == '@tag' then x.parent:remove(x.parent_index) n_tag_sections = n_tag_sections + 1 x.parent:insert(n_tag_sections, x) elseif type(x[#x]) == 'string' then last_line = x[#x] end end, b)
b:insert(1, H.as_struct({ string.rep('-', 78) }, 'section')) -- Append empty line only if last line is not visibly blank (closing code -- block with "<" is concealed) if string.find(last_line, '^<?%s*$') == nil then b:insert(H.as_struct({ '' }, 'section')) end end, --minidoc_replace_end
-- Applied to file after all previous steps --minidoc_replace_start file = --<function: adds separator>, file = function(f) if not f:has_lines() then return end
f:insert(1, H.as_struct({ H.as_struct({ string.rep('=', 78) }, 'section') }, 'block')) f:insert(H.as_struct({ H.as_struct({ '' }, 'section') }, 'block')) end, --minidoc_replace_end
-- Applied to doc after all previous steps --minidoc_replace_start doc = --<function: adds modeline>, doc = function(d) -- Render table of contents H.apply_recursively(function(x) if not (type(x) == 'table' and x.type == 'section' and x.info.id == '@toc') then return end H.toc_insert(x) end, d)
-- Insert modeline d:insert( H.as_struct( { H.as_struct({ H.as_struct({ ' vim:tw=78:ts=8:noet:ft=help:norl:' }, 'section') }, 'block') }, 'file' ) ) end, --minidoc_replace_end
-- Applied before output file is written. Takes lines array as argument. --minidoc_replace_start write_pre = --<function: removes delimiters at the top>, write_pre = function(l) -- Remove first two lines with `======` and `------` delimiters to comply -- with `:h local-additions` template if l[1]:find('^=+$') ~= nil then table.remove(l, 1) end if l[1]:find('^-+$') ~= nil then table.remove(l, 1) end return l end, --minidoc_replace_end
-- Applied after output help file is written. Takes doc as argument. --minidoc_replace_start write_post = --<function: various convenience actions>, write_post = function(d) local output = d.info.output
-- Generate help tags for directory of output file vim.cmd('helptags ' .. vim.fn.fnamemodify(output, ':h'))
-- Reload buffer with output file (helps during writing annotations) local output_path = H.full_path(output) for _, buf_id in ipairs(vim.api.nvim_list_bufs()) do local buf_path = H.full_path(vim.api.nvim_buf_get_name(buf_id)) if buf_path == output_path then vim.api.nvim_buf_call(buf_id, function() vim.cmd('noautocmd silent edit | set ft=help') end) end end
-- Notify local msg = ('Help file %s is successfully generated.'):format(vim.inspect(output)) vim.notify(msg, vim.log.levels.INFO) end, --minidoc_replace_end },
-- Path (relative to current directory) to script which handles project -- specific help file generation (like custom input files, hooks, etc.). script_path = 'scripts/minidoc.lua',
-- Whether to disable showing non-error feedback silent = false,}--minidoc_afterlines_end
-- Module data ================================================================--- Table with information about current state of auto-generation------ It is reset at the beginning and end of `MiniDoc.generate()`.------ At least these keys are supported:--- - {aliases} - table with keys being alias name and values - alias--- description and single string (using `\n` to separate lines).--- - {eval_section} - input section of `@eval` section hook. Can be used for--- information about current block, etc.--- - {toc} - array with table of contents entries. Each entry is a whole--- `@toc_entry` section.MiniDoc.current = { aliases = {}, toc = {} }
--- Default hooks------ This is default value of `MiniDoc.config.hooks`. Use it if only a little--- tweak is needed.------ Some more insight about their behavior:--- - Default inference of documented object metadata (tag and object signature--- at the moment) is done in `block_pre`. Inference is based on string--- pattern matching, so can lead to false results, although works in most--- cases. It intentionally works only if first line after block has no--- indentation and contains all necessary information to determine if--- inference should happen.--- - Hooks for sections describing some "variable-like" object (`@class`,--- `@field`, `@param`) automatically enclose first word in `{}`.--- - Hooks for sections which supposed to have "type-like" data (`@field`,--- `@param`, `@return`, `@type`) automatically enclose FIRST FOUND type-like--- word and its neighbor characters in `(<type>)` (expect false positives).--- Algorithm is far from being 100% correct, but seems to work with present--- allowed type annotation. For allowed types see--- https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#types-and-type--- or, better yet, look in source code of this module.--- - Automated creation of table of contents (TOC) is done in the following way:--- - Put section with `@toc_entry` id in the annotation block. Section's--- lines will be registered as TOC entry.--- - Put `@toc` section where you want to insert rendered table of--- contents. TOC entries will be inserted on the left, references for--- their respective tag section (only first, if present) on the right.--- Render is done in default `doc` hook (because it should be done after--- processing all files).--- - The `write_post` hook executes some actions convenient for iterative--- annotations writing:--- - Generate `:helptags` for directory containing output file.--- - Silently reload buffer containing output file (if such exists).--- - Display notification message about result.MiniDoc.default_hooks = MiniDoc.config.hooks
-- Module functionality =======================================================--- Generate help file------ # Algorithm ~------ - Main parameters for help generation are an array of input file paths and--- path to output help file.--- - Parse all inputs:--- - For each file, lines are processed top to bottom in order to create an--- array of documentation blocks. Each line is tested whether it is an--- annotation by applying `MiniDoc.config.annotation_extractor`: if--- anything is extracted, it is considered to be an annotation. Annotation--- line goes to "current block" after removing extracted annotation--- indicator, otherwise - to afterlines of "current block".--- - Each block's annotation lines are processed top to bottom. If line had--- captured section id, it is a first line of "current section" (first--- block lines are allowed to not specify section id; by default it is--- `@text`). All subsequent lines without captured section id go into--- "current section".--- - Apply structure hooks (they should modify its input in place, which is--- possible due to "table nature" of all inputs):--- - Each block is processed by `MiniDoc.config.hooks.block_pre`. This is a--- designated step for auto-generation of sections from described--- annotation subject (like sections with id `@tag`, `@type`).--- - Each section is processed by `MiniDoc.config.hooks.section_pre`.--- - Each section is processed by corresponding--- `MiniDoc.config.hooks.sections` function (table key equals to section--- id). This is a step where most of formatting should happen (like--- wrap first word of `@param` section with `{` and `}`, append empty--- line to section, etc.).--- - Each section is processed by `MiniDoc.config.hooks.section_post`.--- - Each block is processed by `MiniDoc.config.hooks.block_post`. This is--- a step for processing block after formatting is done (like add first--- line with `----` delimiter).--- - Each file is processed by `MiniDoc.config.hooks.file`. This is a step--- for adding any file-related data (like add first line with `====`--- delimiter).--- - Doc is processed by `MiniDoc.config.hooks.doc`. This is a step for--- adding any helpfile-related data (maybe like table of contents).--- - Collect all strings from sections in depth-first fashion (equivalent to--- nested "for all files -> for all blocks -> for all sections -> for all--- strings -> add string to output"). Strings can have `\n` character--- indicating start of new line.--- - Modify collected strings with `MiniDoc.config.write_pre`. Takes strings--- from previous step as input and should return array of strings.--- - Write modified strings to output file.--- - Execute `MiniDoc.config.write_post` hook. This is useful for showing some--- feedback and making actions involving newly updated help file (like--- generate tags, etc.).------ # Project specific script ~------ If all arguments have default `nil` values, first there is an attempt to--- source project specific script. This is basically a--- `luafile <MiniDoc.config.script_path>` with current Lua runtime while caching--- and restoring current `MiniDoc.config`. Its successful execution stops any--- further generation actions while error means proceeding generation as if no--- script was found.------ Typical script content might include definition of custom hooks, input and--- output files with eventual call to `require('mini.doc').generate()` (with--- or without arguments).------@param input table|nil Array of file paths which will be processed in supplied--- order. Default: all `.lua` files from current directory following by all--- such files in these subdirectories: `lua/`, `after/`, `colors/`. Note:--- any `init.lua` file is placed before other files from the same directory.---@param output string|nil Path for output help file. Default:--- `doc/<current-directory>.txt` (designed to be used for generating help--- file for plugin).---@param config table|nil Configuration overriding parts of |MiniDoc.config|.------@return table Document structure which was generated and used for output--- help file. In case `MiniDoc.config.script_path` was successfully used,--- this is a return from the latest call of this function.MiniDoc.generate = function(input, output, config) -- Try sourcing project specific script first local success = H.execute_project_script(input, output, config) if success then return H.generate_recent_output end
input = input or H.default_input() output = output or H.default_output() config = H.get_config(config)
-- Prepare table for current information MiniDoc.current = {}
-- Parse input files local doc = H.new_struct('doc', { input = input, output = output, config = config }) for _, path in ipairs(input) do local lines = H.file_read(path) local block_arr = H.lines_to_block_arr(lines, config) local file = H.as_struct(block_arr, 'file', { path = path })
doc:insert(file) end
-- Apply hooks H.apply_structure_hooks(doc, config.hooks)
-- Gather string lines in depth-first fashion local help_lines = H.collect_strings(doc)
-- Execute pre-write hook help_lines = config.hooks.write_pre(help_lines) if not H.is_array_of(help_lines, H.is_string) then H.error('Output of `write_pre` should be array of strings.') end
-- Write helpfile H.file_write(output, help_lines)
-- Execute post-write hook config.hooks.write_post(doc)
-- Clear current information MiniDoc.current = {}
-- Stash output to allow returning value even when called from script H.generate_recent_output = doc
return docend
--- Convert afterlines to code------ This function is designed to be used together with `@eval` section to--- automate documentation of certain values (notably default values of a--- table). It processes afterlines based on certain directives and makes--- output look like a Lua code block.------ Most common usage is by adding the following section in your annotation: >------ ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)--- <--- # Directives ~------ Directives are special comments that are processed using Lua string pattern--- capabilities (so beware of false positives). Each directive should be put--- on its separate line. Supported directives:--- - `--minidoc_afterlines_end` denotes a line at afterlines end. Only all--- lines before it will be considered as afterlines. Useful if there is--- extra code in afterlines which shouldn't be used.--- - `--minidoc_replace_start <replacement>` and `--minidoc_replace_end`--- denote lines between them which should be replaced with `<replacement>`.--- Useful for manually changing what should be placed in output like in case--- of replacing function body with something else.------ Here is an example. Suppose having these afterlines: >lua------ --minidoc_replace_start {--- M.config = {--- --minidoc_replace_end--- param_one = 1,--- --minidoc_replace_start param_fun = --<function>--- param_fun = function(x)--- return x + 1--- end--- --minidoc_replace_end--- }--- --minidoc_afterlines_end------ return M--- <--- After adding `@eval` section those will be formatted as: >------ {--- param_one = 1,--- param_fun = --<function>--- }--- <---@param struct table Block or section structure which after lines will be--- converted to code.------@return string|nil Single string (using `\n` to separate lines) describing--- afterlines as Lua code block in help file. If `nil`, input is not valid.MiniDoc.afterlines_to_code = function(struct) if not (type(struct) == 'table' and (struct.type == 'section' or struct.type == 'block')) then vim.notify('Input to `MiniDoc.afterlines_to_code()` should be either section or block.', vim.log.levels.WARN) return end
if struct.type == 'section' then struct = struct.parent end local src = table.concat(struct.info.afterlines, '\n')
-- Process directives -- Try to extract afterlines src = src:match('^(.-)\n%s*%-%-minidoc_afterlines_end') or src
-- Make replacements src = src:gsub('%-%-minidoc_replace_start ?(.-)\n.-%-%-minidoc_replace_end', '%1')
-- Convert to a standalone code. NOTE: indent is needed because of how `>` -- and `<` work (any line starting in column 1 stops code block). src = H.ensure_indent(src, 2) return '>lua\n' .. src .. '\n<'end
-- Helper data ================================================================-- Module default configH.default_config = vim.deepcopy(MiniDoc.config)
-- Alias registry. Keys are alias name, values - single string of alias-- description with '\n' separating output lines.H.alias_registry = {}
--stylua: ignore startH.pattern_sets = { -- Patterns for working with afterlines. At the moment deliberately crafted -- to work only on first line without indent.
-- Determine if line is a function definition. Captures function name and -- arguments. For reference see '2.5.9 – Function Definitions' in Lua manual. afterline_fundef = { '^function%s+(%S-)(%b())', -- Regular definition '^local%s+function%s+(%S-)(%b())', -- Local definition '^(%S+)%s*=%s*function(%b())', -- Regular assignment '^local%s+(%S+)%s*=%s*function(%b())', -- Local assignment },
-- Determine if line is a general assignment afterline_assign = { '^(%S-)%s*=', -- General assignment '^local%s+(%S-)%s*=', -- Local assignment },
-- Patterns to work with type descriptions -- (see https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#types-and-type) types = { '%b()', -- Allow union type '%b[]', '%b{}', 'table%b<>', 'fun%b():%s*%b()', 'fun%b():%s*%b[]', 'fun%b():%s*%b{}', 'fun%b():%s*table%b<>', 'fun%b():%s*%S+', 'fun%b()', 'nil', 'any', 'boolean', 'string', 'number', 'integer', 'function', 'table', 'thread', 'userdata', 'lightuserdata', '%.%.%.', '[%a][%w_%.]*', -- Allow any class as a type },}--stylua: ignore end
-- Helper functionality =======================================================-- Settings -------------------------------------------------------------------H.setup_config = function(config) H.check_type('config', config, 'table', true) config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {})
H.check_type('annotation_extractor', config.annotation_extractor, 'function') H.check_type('default_section_id', config.default_section_id, 'string') H.check_type('hooks', config.hooks, 'table')
H.check_type('hooks.block_pre', config.hooks.block_pre, 'function') H.check_type('hooks.section_pre', config.hooks.section_pre, 'function')
H.check_type('hooks.sections', config.hooks.sections, 'table') H.check_type('hooks.sections.@alias', config.hooks.sections['@alias'], 'function') H.check_type('hooks.sections.@class', config.hooks.sections['@class'], 'function') H.check_type('hooks.sections.@diagnostic', config.hooks.sections['@diagnostic'], 'function') H.check_type('hooks.sections.@eval', config.hooks.sections['@eval'], 'function') H.check_type('hooks.sections.@field', config.hooks.sections['@field'], 'function') H.check_type('hooks.sections.@overload', config.hooks.sections['@overload'], 'function') H.check_type('hooks.sections.@param', config.hooks.sections['@param'], 'function') H.check_type('hooks.sections.@private', config.hooks.sections['@private'], 'function') H.check_type('hooks.sections.@return', config.hooks.sections['@return'], 'function') H.check_type('hooks.sections.@seealso', config.hooks.sections['@seealso'], 'function') H.check_type('hooks.sections.@signature', config.hooks.sections['@signature'], 'function') H.check_type('hooks.sections.@tag', config.hooks.sections['@tag'], 'function') H.check_type('hooks.sections.@text', config.hooks.sections['@text'], 'function') H.check_type('hooks.sections.@toc', config.hooks.sections['@toc'], 'function') H.check_type('hooks.sections.@toc_entry', config.hooks.sections['@toc_entry'], 'function') H.check_type('hooks.sections.@type', config.hooks.sections['@type'], 'function') H.check_type('hooks.sections.@usage', config.hooks.sections['@usage'], 'function')
H.check_type('hooks.section_post', config.hooks.section_post, 'function') H.check_type('hooks.block_post', config.hooks.block_post, 'function') H.check_type('hooks.file', config.hooks.file, 'function') H.check_type('hooks.doc', config.hooks.doc, 'function') H.check_type('hooks.write_pre', config.hooks.write_pre, 'function') H.check_type('hooks.write_post', config.hooks.write_post, 'function')
H.check_type('script_path', config.script_path, 'string') H.check_type('silent', config.silent, 'boolean')
return configend
H.apply_config = function(config) MiniDoc.config = config end
H.get_config = function(config) return vim.tbl_deep_extend('force', MiniDoc.config, vim.b.minidoc_config or {}, config or {})end
-- Work with project specific script ==========================================H.execute_project_script = function(input, output, config) -- Don't process script if there are more than one active `generate` calls if H.generate_is_active then return end
-- Don't process script if at least one argument is not default if not (input == nil and output == nil and config == nil) then return end
-- Store information local global_config_cache = vim.deepcopy(MiniDoc.config) local local_config_cache = vim.b.minidoc_config
-- Pass information to a possible `generate()` call inside script H.generate_is_active = true H.generate_recent_output = nil
-- Execute script local success = pcall(vim.cmd, 'luafile ' .. H.get_config(config).script_path)
-- Restore information MiniDoc.config = global_config_cache vim.b.minidoc_config = local_config_cache H.generate_is_active = nil
return successend
-- Default documentation targets ----------------------------------------------H.default_input = function() -- Search in current and recursively in other directories for Lua files local res = {} for _, dir in ipairs({ '.', 'lua', 'after', 'colors' }) do local glob = (dir == '.' and '' or '**/') .. '*.lua' local files = vim.fn.globpath(dir, glob, false, true)
-- Use full paths files = vim.tbl_map(function(x) return vim.fn.fnamemodify(x, ':p') end, files)
-- Ensure consistent order table.sort(files, function(a, b) local a_dir, b_dir = vim.fn.fnamemodify(a, ':h'), vim.fn.fnamemodify(b, ':h')
-- Put 'init.lua' first among files from same directory if a_dir == b_dir then local a_basename, b_basename = vim.fn.fnamemodify(a, ':t'), vim.fn.fnamemodify(b, ':t') if a_basename == 'init.lua' then return true end if b_basename == 'init.lua' then return false end return a_basename < b_basename end
return a_dir < b_dir end) table.insert(res, files) end
return H.tbl_flatten(res)end
H.default_output = function() local cur_dir = vim.fn.fnamemodify(vim.loop.cwd(), ':t:r') return ('doc/%s.txt'):format(cur_dir)end
-- Parsing --------------------------------------------------------------------H.lines_to_block_arr = function(lines, config) local matched_prev, matched_cur
local res = {} local block_raw = { annotation = {}, section_id = {}, afterlines = {}, line_begin = 1 }
for i, l in ipairs(lines) do local from, to, section_id = config.annotation_extractor(l) matched_prev, matched_cur = matched_cur, from ~= nil
if matched_cur then if not matched_prev then -- Finish current block block_raw.line_end = i - 1 table.insert(res, H.raw_block_to_block(block_raw, config))
-- Start new block block_raw = { annotation = {}, section_id = {}, afterlines = {}, line_begin = i } end
-- Add annotation line without matched annotation pattern table.insert(block_raw.annotation, ('%s%s'):format(l:sub(0, from - 1), l:sub(to + 1)))
-- Add section id (it is empty string in case of no section id capture) table.insert(block_raw.section_id, section_id or '') else -- Add afterline table.insert(block_raw.afterlines, l) end end block_raw.line_end = #lines table.insert(res, H.raw_block_to_block(block_raw, config))
return resend
-- Raw block structure is an intermediate step added for convenience. It is-- a table with the following keys:-- - `annotation` - lines (after removing matched annotation pattern) that were-- parsed as annotation.-- - `section_id` - array with length equal to `annotation` length with strings-- captured as section id. Empty string of no section id was captured.-- - Everything else is used as block info (like `afterlines`, etc.).H.raw_block_to_block = function(block_raw, config) if #block_raw.annotation == 0 and #block_raw.afterlines == 0 then return nil end
local block = H.new_struct('block', { afterlines = block_raw.afterlines, line_begin = block_raw.line_begin, line_end = block_raw.line_end, }) local block_begin = block.info.line_begin
-- Parse raw block annotation lines from top to bottom. New section starts -- when section id is detected in that line. local section_cur = H.new_struct('section', { id = config.default_section_id, line_begin = block_begin })
for i, annotation_line in ipairs(block_raw.annotation) do local id = block_raw.section_id[i] if id ~= '' then -- Finish current section if #section_cur > 0 then section_cur.info.line_end = block_begin + i - 2 block:insert(section_cur) end
-- Start new section section_cur = H.new_struct('section', { id = id, line_begin = block_begin + i - 1 }) end
section_cur:insert(annotation_line) end
if #section_cur > 0 then section_cur.info.line_end = block_begin + #block_raw.annotation - 1 block:insert(section_cur) end
return blockend
-- Hooks ----------------------------------------------------------------------H.apply_structure_hooks = function(doc, hooks) for _, file in ipairs(doc) do for _, block in ipairs(file) do hooks.block_pre(block)
for _, section in ipairs(block) do -- NOTE: Section can be empty if previous hook used `clear_lines()` on -- the whole block (like default `@private`). if #section > 0 then hooks.section_pre(section)
local hook = hooks.sections[section.info.id] if hook ~= nil then hook(section) end
hooks.section_post(section) end end
hooks.block_post(block) end
hooks.file(file) end
hooks.doc(doc)end
H.alias_register = function(s) if #s == 0 then return end
-- Remove first word (with bits of surrounding whitespace) while capturing it local alias_name s[1] = s[1]:gsub('%s*(%S+) ?', function(x) alias_name = x return '' end, 1) if alias_name == nil then return end
MiniDoc.current.aliases = MiniDoc.current.aliases or {} MiniDoc.current.aliases[alias_name] = table.concat(s, '\n')end
H.alias_replace = function(s) if MiniDoc.current.aliases == nil then return end
local s_type = s.info.id local has_special_first_word = s_type == '@param' or s_type == '@field' or s_type == '@class' local has_special_type = s_type == '@tag' or s_type == '@toc_entry' for alias_name, alias_desc in pairs(MiniDoc.current.aliases) do -- Escape special characters. This is done here and not while registering -- alias to allow user to refer to aliases by its original name. local name_escaped = vim.pesc(alias_name) local desc_is_union = alias_desc:find('|') ~= nil for i, _ in ipairs(s) do -- Try to be accurate in which matches to replace. This avoids cases like -- `@alias aaa AAA` with `aaaBBB->AAABBB` replacements or replacing -- inside special places (like parameter/field/tag names, etc.) s[i] = s[i]:gsub('(.?)(' .. name_escaped .. ')(.?)', function(before, match, after) local before_is_empty, after_is_empty = before == '', after == '' local before_is_space, after_is_space = before:find('%s') == 1, after:find('%s') == 1 -- Allow match to be preceded/followed by special characters that can -- be used inside EmmyLua/LuaCATS annotations. -- Source: https://luals.github.io/wiki/annotations/#documenting-types local before_is_special, after_is_special = before:find('[|,%[%(<:]') == 1, after:find('[|,%[%])>}%?]') == 1
local is_fixed_name = i == 1 and has_special_first_word and before_is_empty local before_is_valid = before_is_empty or before_is_space or before_is_special local after_is_valid = after_is_empty or after_is_space or after_is_special local is_valid = before_is_valid and after_is_valid if not is_valid or is_fixed_name or has_special_type then return before .. match .. after end
local should_enclose = desc_is_union and (before_is_special or after_is_special) return before .. (should_enclose and ('(' .. alias_desc .. ')') or alias_desc) .. after end) end endend
H.toc_register = function(s) MiniDoc.current.toc = MiniDoc.current.toc or {} table.insert(MiniDoc.current.toc, s)end
H.toc_insert = function(s) if MiniDoc.current.toc == nil then return end
-- Render table of contents local toc_lines = {} for _, toc_entry in ipairs(MiniDoc.current.toc) do local _, tag_section = toc_entry.parent:has_descendant( function(x) return type(x) == 'table' and x.type == 'section' and x.info.id == '@tag' end ) tag_section = tag_section or {}
local lines = {} for i = 1, math.max(#toc_entry, #tag_section) do local left = toc_entry[i] or '' -- Use tag reference instead of tag enclosure local right = vim.trim((tag_section[i] or ''):gsub('%*', '|')) -- Add helper line of dots in first entry (without new trailing space) local filler = right == '' and '' or ' ' if i == 1 then -- Ensure parts are padded for proper conceal filler, left, right = '.', (left:gsub('(%S)$', '%1 ')), (right:gsub('^(%S)', ' %1')) end -- Make padding of 2 spaces at both left and right local n_filler = math.max(74 - H.visual_text_width(left) - H.visual_text_width(right), 3) table.insert(lines, (' %s%s%s'):format(left, filler:rep(n_filler), right)) end
table.insert(toc_lines, lines)
-- Don't show `toc_entry` lines in output toc_entry:clear_lines() end
for _, l in ipairs(H.tbl_flatten(toc_lines)) do s:insert(l) endend
H.add_section_heading = function(s, heading) -- Add heading s:insert(1, ('%s ~'):format(heading))end
H.mark_optional = function(s) -- Treat question mark at end of first word as "optional" indicator. See: -- https://github.com/sumneko/lua-language-server/wiki/EmmyLua-Annotations#optional-params s[1] = s[1]:gsub('^(%s-%S-)%?', '%1 `(optional)`', 1)end
H.enclose_var_name = function(s) s[1] = s[1]:gsub('(%S+)', '{%1}', 1) end
---@param init number Start of searching for first "type-like" string. It is--- needed to not detect type early. Like in `@param a_function function`.---@privateH.enclose_type = function(s, init) if #s == 0 or s.type ~= 'section' then return end init = init or 1
local type_pattern_set = H.pattern_sets['types'] local type_pattern = H.find_pattern_with_first_match(s[1], type_pattern_set, init) if type_pattern == nil then return end
-- Find range representing type. It can be a match for type pattern (plain, -- array `[]`, or optional `?`), possibly in a union (`|`). local from, to = s[1]:find(type_pattern, init) for _ = 1, s[1]:len() do if s[1]:sub(to + 1, to + 2) == '[]' then to = to + 2 end if s[1]:sub(to + 1, to + 1) == '?' then to = to + 1 end
local new_to = s[1]:sub(to + 1):match('^%s*|%s*()') if new_to == nil then break end to = to + new_to - 1 local next_type_pattern = H.find_pattern_with_first_match(s[1], type_pattern_set, to + 1) if next_type_pattern == nil then break end to = s[1]:match(next_type_pattern .. '()', to + 1) - 1 end
-- Avoid replacing match before `init` and avoid unnecessary () enclosing local avoid_brackets = s[1]:sub(from, to):find('^%b()$') ~= nil local left = avoid_brackets and '`' or '`(' local right = avoid_brackets and '`' or ')`'
s[1] = s[1]:sub(1, from - 1) .. left .. s[1]:sub(from, to) .. right .. s[1]:sub(to + 1)end
-- Infer data from afterlines -------------------------------------------------H.infer_header = function(b) local has_signature = b:has_descendant( function(x) return type(x) == 'table' and x.type == 'section' and x.info.id == '@signature' end ) local has_tag = b:has_descendant( function(x) return type(x) == 'table' and x.type == 'section' and x.info.id == '@tag' end )
if has_signature and has_tag then return end
local l_all = table.concat(b.info.afterlines, ' ') local tag, signature
-- Try function definition local fun_pattern = H.find_pattern_with_first_match(l_all, H.pattern_sets['afterline_fundef']) if fun_pattern ~= nil then local fun_name, fun_args = l_all:match(fun_pattern) tag = tag or (fun_name .. '()') signature = signature or (fun_name .. fun_args) end
-- Try general assignment local assign_pattern = H.find_pattern_with_first_match(l_all, H.pattern_sets['afterline_assign']) if assign_pattern ~= nil then local obj_name = l_all:match(assign_pattern) tag = tag or obj_name signature = signature or obj_name end
if tag ~= nil then -- First insert signature (so that it will appear after tag section) if not has_signature then b:insert(1, H.as_struct({ signature }, 'section', { id = '@signature' })) end
-- Insert tag if not has_tag then b:insert(1, H.as_struct({ tag }, 'section', { id = '@tag' })) end endend
H.format_signature = function(line) -- Try capture function signature local name, args = line:match('(%S-)(%b())') -- Otherwise pick first word name = name or line:match('(%S+)')
if not name then return '' end
-- Tidy arguments if args and args ~= '()' then local arg_parts = vim.split(args:sub(2, -2), ',') local arg_list = {} for _, a in ipairs(arg_parts) do -- Enclose argument in `{}` while controlling whitespace table.insert(arg_list, ('{%s}'):format(vim.trim(a))) end args = ('(%s)'):format(table.concat(arg_list, ', ')) end
return ('`%s`%s'):format(name, args or '')end
-- Work with structures --------------------------------------------------------- ConstructorH.new_struct = function(struct_type, info) local output = { info = info or {}, type = struct_type, }
output.insert = function(self, index, child) -- Allow both `x:insert(child)` and `x:insert(1, child)` if child == nil then child, index = index, #self + 1 end
if type(child) == 'table' then child.parent = self child.parent_index = index end
table.insert(self, index, child)
H.sync_parent_index(self) end
output.remove = function(self, index) index = index or #self table.remove(self, index)
H.sync_parent_index(self) end
output.has_descendant = function(self, predicate) local bool_res, descendant = false, nil H.apply_recursively(function(x) if not bool_res and predicate(x) then bool_res = true descendant = x end end, self) return bool_res, descendant end
output.has_lines = function(self) return self:has_descendant(function(x) return type(x) == 'string' end) end
output.clear_lines = function(self) for i, x in ipairs(self) do if type(x) == 'string' then self[i] = nil else x:clear_lines() end end end
return outputend
H.sync_parent_index = function(x) for i, _ in ipairs(x) do if type(x[i]) == 'table' then x[i].parent_index = i end end return xend
-- Converter (this ensures that children have proper parent-related data)H.as_struct = function(array, struct_type, info) -- Make default info `info` for cases when structure is created manually local default_info = ({ section = { id = '@text', line_begin = -1, line_end = -1 }, block = { afterlines = {}, line_begin = -1, line_end = -1 }, file = { path = '' }, doc = { input = {}, output = '', config = H.get_config() }, })[struct_type] info = vim.tbl_deep_extend('force', default_info, info or {})
local res = H.new_struct(struct_type, info) for _, x in ipairs(array) do res:insert(x) end return resend
-- Work with text -------------------------------------------------------------H.ensure_indent = function(text, n_indent_target) local lines = vim.split(text, '\n') local n_indent, n_indent_cur = math.huge, math.huge
-- Find number of characters in indent for _, l in ipairs(lines) do -- Update lines indent: minimum of all indents except empty lines if n_indent > 0 then _, n_indent_cur = l:find('^%s*') -- Condition "current n-indent equals line length" detects empty line if (n_indent_cur < n_indent) and (n_indent_cur < l:len()) then n_indent = n_indent_cur end end end
-- Ensure indent local indent = string.rep(' ', n_indent_target) for i, l in ipairs(lines) do if l ~= '' then lines[i] = indent .. l:sub(n_indent + 1) end end
return table.concat(lines, '\n')end
H.align_text = function(text, width, direction) if type(text) ~= 'string' then return end text = vim.trim(text) width = width or 78 direction = direction or 'left'
-- Don't do anything if aligning left or line is a whitespace if direction == 'left' or text:find('^%s*$') then return text end
local n_left = math.max(0, 78 - H.visual_text_width(text)) if direction == 'center' then n_left = math.floor(0.5 * n_left) end
return (' '):rep(n_left) .. textend
H.visual_text_width = function(text) -- Ignore concealed characters (usually "invisible" in 'help' filetype) local _, n_concealed_chars = text:gsub('([*|`])', '%1') return vim.fn.strdisplaywidth(text) - n_concealed_charsend
H.find_pattern_with_first_match = function(text, pattern_set, init) local min_start, first_pat = math.huge, nil for _, pat in ipairs(pattern_set) do local from = text:find(pat, init) if from ~= nil and from < min_start then min_start, first_pat = from, pat end end return first_patend
-- Utilities ------------------------------------------------------------------H.error = function(msg) error('(mini.doc) ' .. msg, 0) end
H.check_type = function(name, val, ref, allow_nil) if type(val) == ref or (ref == 'callable' and vim.is_callable(val)) or (allow_nil and val == nil) then return end H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))end
H.apply_recursively = function(f, x) f(x)
if type(x) == 'table' then for _, t in ipairs(x) do H.apply_recursively(f, t) end endend
H.collect_strings = function(x) local res = {} H.apply_recursively(function(y) if type(y) == 'string' then -- Allow `\n` in strings table.insert(res, vim.split(y, '\n')) end end, x) -- Flatten to only have strings and not table of strings (from `vim.split`) return H.tbl_flatten(res)end
H.file_read = function(path) local file = assert(io.open(path)) local contents = file:read('*all') file:close()
return vim.split(contents, '\n')end
H.file_write = function(path, lines) -- Ensure target directory exists local dir = vim.fn.fnamemodify(path, ':h') vim.fn.mkdir(dir, 'p')
-- Write to file vim.fn.writefile(lines, path, 'b')end
H.full_path = function(path) return vim.fn.resolve(vim.fn.fnamemodify(path, ':p')) end
H.is_array_of = function(x, predicate) if not H.islist(x) then return false end for _, v in ipairs(x) do if not predicate(v) then return false end end return trueend
H.is_string = function(x) return type(x) == 'string' end
-- TODO: Remove after compatibility with Neovim=0.9 is droppedH.islist = vim.fn.has('nvim-0.10') == 1 and vim.islist or vim.tbl_islistH.tbl_flatten = vim.fn.has('nvim-0.10') == 1 and function(x) return vim.iter(x):flatten(math.huge):totable() end or vim.tbl_flatten
return MiniDoc