Merge branch 'gitpushjoe-main' into main

Author: gitpushjoe

core/config.lua

@@ -75,7 +75,7 @@ Config.__name = "Config"
 Config.errors = {
 
 	--- @param list table
-	--- @return string
+	--- @return string errmsg
 	missing_item_in_note_schema_list = function(list, idx)
 		return "Missing "
 			.. (#list <= 1 and "open-tag" or "close-tag")
@@ -84,7 +84,7 @@ Config.errors = {
 			.. "]."
 	end,
 
-	--- @return string
+	--- @return string errmsg
 	root_reserved = function()
 		return "Cannot use "
 			.. "ROOT"
@@ -98,7 +98,8 @@ Config.errors = {
 }
 
 --- @param config_table PartialConfigTable
---- @return Config?, string?
+--- @return Config? config
+--- @return string? errmsg
 function Config:new(config_table)
 	self = {}
 	--- @cast self Config

core/context.lua

@@ -90,7 +90,8 @@ Context.errors = {
 ---@param text_stream Stream
 ---@param preserve boolean
 ---@param ansi_enabled boolean
----@return Context?, string?
+---@return Context? ctx
+---@return string? errmsg
 function Context:new(
 	config,
 	src_path,

core/fold.lua

@@ -14,21 +14,21 @@ M.__name = "fold"
 M.errors = {
 
 	---@param section Section?
-	---@return string
+	---@return string errmsg
 	unterminated_section = function(section)
 		return "Unterminated section: " .. (tostring(section) or "nil")
 	end,
 
 	---@param line number
-	---@return string
+	---@return string errmsg
 	inconsistent_indent = function(line)
 		return "Inconsistent indent on line " .. line
 	end,
 
 	---@param retry_count number
 	---@param section Section?
 	---@param is_local boolean?
-	---@return string
+	---@return string errmsg
 	maximum_retry_count = function(retry_count, section, is_local)
 		return "Maximum "
 			.. (is_local and "local " or "")
@@ -39,7 +39,7 @@ M.errors = {
 	end,
 
 	---@param path Path
-	---@return string
+	---@return string errmsg
 	path_should_not_be_directory = function(path)
 		return "`config.resolve_path` returned directory-type Path ("
 			.. path:escaped()
@@ -48,14 +48,14 @@ M.errors = {
 
 	---@param path string
 	---@param section Section?
-	---@return string
+	---@return string errmsg
 	cannot_write = function(path, section)
 		return "Cannot write to path " .. path .. "\n" .. tostring(section)
 	end,
 
 	---@param command string
 	---@param err string?
-	---@return string
+	---@return string errmsg
 	command_failed = function(command, err)
 		return "Failed to execute command: "
 			.. command
@@ -64,14 +64,15 @@ M.errors = {
 	end,
 
 	---@param path string
-	---@return string
+	---@return string errmsg
 	expected_file_to_be_writable = function(path)
 		return "Expected file " .. tostring(path) .. " to be writable"
 	end,
 }
 
 ---@param ctx Context
----@return Section?, string?
+---@return Section? section
+---@return string? errmsg
 M.parse = function(ctx)
 	local curr_section, err = Section:new(
 		0,
@@ -111,8 +112,13 @@ M.parse = function(ctx)
 		line = string.sub(line, indent_chars + 1)
 
 		for note_idx, note_type in ipairs(note_schema) do
-			local prefix = note_type[2]
-			if str.starts_with(line, prefix) then
+			local open_tag = note_type[2]
+			local do_not_open_only_close = line == open_tag
+				and curr_section
+				and open_tag == curr_section:close_tag()
+			if
+				str.starts_with(line, open_tag) and not do_not_open_only_close
+			then
 				local new_section
 				new_section, err = Section:new(
 					id,
@@ -134,10 +140,14 @@ M.parse = function(ctx)
 			end
 		end
 		-- TODO(gitpushjoe): maybe still check if a suffix for another note type slipped through?
+		local do_not_close_only_open = line == curr_section:open_tag()
+			and line == curr_section:close_tag()
+			and curr_section.start_line == i
 		if
 			curr_section
-			and curr_section.type[1] ~= "ROOT"
+			and not curr_section:is_root()
 			and str.ends_with(line, curr_section:close_tag())
+			and not do_not_close_only_open
 		then
 			curr_section.end_line = i
 			curr_section = curr_section.parent
@@ -151,13 +161,14 @@ end
 
 ---@param section_root Section
 ---@param ctx Context
----@return nil, string?
+---@return nil
+---@return string? errmsg
 M.prepare = function(section_root, ctx)
 	---@type { [string]: Section }
 	local created_files = {}
 
 	local _, err = traverse.preorder(section_root, function(section)
-		if section.type[1] == "ROOT" then
+		if section:is_root() then
 			section.path = ctx.dest_path
 			return
 		end
@@ -210,7 +221,7 @@ M.prepare = function(section_root, ctx)
 	end
 
 	_, err = traverse.postorder(section_root, function(section)
-		if section.type[1] == "ROOT" then
+		if section:is_root() then
 			section.lines = ctx.lines
 			return
 		end
@@ -256,7 +267,8 @@ end
 ---@param section_root Section
 ---@param ctx Context
 ---@param is_dry_run boolean?
----@return Plan?, string?
+---@return Plan? plan
+---@return string? errmsg
 M.execute = function(section_root, ctx, is_dry_run)
 	is_dry_run = is_dry_run or false
 	local io = ctx.io
@@ -299,7 +311,7 @@ M.execute = function(section_root, ctx, is_dry_run)
 	---@param lines string[]
 	---@param path Path
 	---@param is_overwrite boolean?
-	---@return string?
+	---@return string? errmsg
 	local function write(handle, lines, path, is_overwrite)
 		is_overwrite = is_overwrite or false
 		created_or_modified_paths[tostring(path)] = 1
@@ -316,7 +328,7 @@ M.execute = function(section_root, ctx, is_dry_run)
 	end
 
 	---@param directory Path
-	---@return string?
+	---@return string? errmsg
 	local function mkdir(directory)
 		created_or_modified_paths[tostring(directory)] = 1
 		if not is_dry_run then
@@ -350,7 +362,7 @@ M.execute = function(section_root, ctx, is_dry_run)
 		end
 
 		while true do
-			if section.type[1] == "ROOT" then
+			if section:is_root() then
 				is_overwrite = ctx.src_path == ctx.dest_path
 				break
 			end
@@ -379,7 +391,7 @@ M.execute = function(section_root, ctx, is_dry_run)
 			full_path = tostring(section.path) or ""
 		end
 
-		if section.type[1] == "ROOT" and ctx.preserve then
+		if section:is_root() and ctx.preserve then
 			return
 		end
 

core/parser.lua

@@ -1,6 +1,6 @@
 local validate = require("core.validate")
 
----@alias Equivalences { [string]: EquivalenceClass|string|nil }
+---@alias Equivalences table<string, EquivalenceClass|string|nil>
 
 ---@class (exact) EquivalenceClass
 ---@field equivalences string[]

core/path.lua

@@ -35,7 +35,8 @@ end
 ---@param path string|string[]
 ---`allow_relative` IS INTENDED FOR INTERNAL USE ONLY.
 ---@param allow_relative boolean?
----@return Path?, string?
+---@return Path? path
+---@return string? errmsg
 function Path:new(path, allow_relative)
 	self = {}
 	setmetatable(self, Path)
@@ -137,7 +138,7 @@ end
 --- assert(path:pop_directory() == "baz")
 --- assert(path == Path:new("/foo/"))
 --- ```
---- @return string?
+--- @return string? errmsg
 function Path:pop_directory()
 	handle_is_void(self)
 	if #self.parts <= 2 then
@@ -200,7 +201,7 @@ end
 --- assert(path == Path:new("/foo/"))
 --- ```
 --- @param filename string
---- @return string
+--- @return string old_filename
 function Path:set_filename(filename)
 	handle_is_void(self)
 	if #self.parts < 1 then
@@ -252,7 +253,7 @@ end
 --- assert(Path:new("/foo/bar"):join("./baz") == Path:new("/foo/baz"))
 --- ```
 --- @param path string
---- @return Path?
+--- @return Path? new_path
 --- @return string? errmsg
 function Path:join(path)
 	local err = validate.types("Path:join", { { path, "string", "path" } })

core/section.lua

@@ -55,7 +55,8 @@ Section.ROOT = "ROOT"
 ---@param children Section[]
 ---@param parent Section?
 ---@param indent string?
----@return Section?, string?
+---@return Section? section
+---@return string? errmsg
 function Section:new(
 	id,
 	type,
@@ -205,7 +206,7 @@ function Section:type_name_is(name)
 	return name == self:type_name()
 end
 
----@return string?
+---@return string
 function Section:__tostring()
 	return "Section {"
 		.. '\n\ttype = {"'

core/validate.lua

@@ -9,7 +9,7 @@ M.RETVAL = "RETVAL"
 ---@param expected_type string
 ---@param actual string
 ---@overload fun(function_name: string, triplet: {[1]: any, [2]: string, [3]: string?}): string
----@return string
+---@return string errmsg
 M.invalid_type_error = function(function_name, arg_name, expected_type, actual)
 	arg_name = arg_name or M.RETVAL
 	if type(arg_name) == type({}) then
@@ -36,6 +36,7 @@ end
 ---@param expected_class table
 ---@param actual any
 ---@overload fun(function_name: string, triplet: {[1]: any, [2]: table, [3]: string?}): string
+---@return string
 M.invalid_instance_error = function(
 	function_name,
 	arg_name,
@@ -72,7 +73,7 @@ end
 
 ---@param function_name string
 ---@param data {[1]: any, [2]: string, [3]: string?}[]
----@return string?
+---@return string? errmsg
 M.types = function(function_name, data)
 	for _, item in ipairs(data) do
 		local elem = item[1]
@@ -105,7 +106,7 @@ end
 ---@param list any[]
 ---@param arg_name string
 ---@param expected_type string
----@return string?
+---@return string? errmsg
 M.types_in_list = function(function_name, list, arg_name, expected_type)
 	arg_name = arg_name or M.RETVAL
 	local err = M.types(function_name, { { list, "table", arg_name } })
@@ -131,7 +132,7 @@ end
 
 ---@param function_name string
 ---@param data {[1]: any, [2]: table, [3]: string?}[]
----@return string?
+---@return string? errmsg
 M.are_instances = function(function_name, data)
 	for _, item in ipairs(data) do
 		if not item[1] then

core/version.lua

@@ -0,0 +1 @@
+return "β0.1.0"

examples/bible/configs.lua

@@ -1,7 +1,7 @@
 local Path = require("core.path")
 local utils = require("core.utils")
 
----@type { [string]: PartialConfigTable }
+---@type table<string, PartialConfigTable>
 local configs = {
 
 	bible = {

examples/chess/configs.lua

@@ -1,6 +1,6 @@
 local Path = require("core.path")
 
----@type { [string]: PartialConfigTable }
+---@type table<string, PartialConfigTable>
 local configs = {
 
 	chess = {