docs(luaCats): type annotations

Author: BirdeeHub

Makefile

@@ -42,12 +42,16 @@ test: $(SRC)/src/* $(TESTDIR)/*
 	$(check_so_was_built)
 	$(LUA) "$(TESTDIR)/run_tests.lua" -- "$(TESTDIR)" "$(DESTDIR)"
 
-install:
+install: $(SRC)/meta.lua
 ifdef LIBDIR
 	$(check_so_was_built)
 	@mkdir -p "$(LIBDIR)";
 	cp "$(DESTDIR)/tomlua.so" "$(LIBDIR)/";
 	@echo "Installed to $(LIBDIR)";
+ifdef LUADIR
+	@mkdir -p "$(LUADIR)/tomlua";
+	cp "$(SRC)/meta.lua" "$(LUADIR)/tomlua/";
+endif
 else
 	@echo "LIBDIR not set, skipping install"
 endif

meta.lua

@@ -0,0 +1,70 @@
+---@meta
+error("Cannot import a meta module")
+
+---@class Tomlua.DateTable
+---@field toml_type TomlType|TomlTypeNum -- one of tomlua.types, e.g., OFFSET_DATETIME
+---@field year integer                   -- 1979, 3333, etc.
+---@field month integer                  -- 1–12
+---@field day integer                    -- 1–31
+---@field hour integer                   -- 0–23
+---@field minute integer                 -- 0–59
+---@field second integer                 -- 0–59, leap second 60 optional
+---@field fractional integer             -- 0–999999 (microsecond precision optional)
+---@field offset_hour integer            -- UTC offset hours, e.g., -7
+---@field offset_minute integer          -- UTC offset minutes, usually 0, can be 30/45
+
+---@alias Tomlua.Date Tomlua.DateTable | userdata
+
+---@class TomluaOptions
+---@field fancy_tables? boolean
+---@field int_keys? boolean
+---@field fancy_dates? boolean
+---@field multi_strings? boolean
+---@field mark_inline? boolean
+---@field overflow_errors? boolean
+---@field underflow_errors? boolean
+
+---@alias TomlType
+---| "UNTYPED"
+---| "STRING"
+---| "STRING_MULTI"
+---| "INTEGER"
+---| "FLOAT"
+---| "BOOL"
+---| "ARRAY"
+---| "TABLE"
+---| "ARRAY_INLINE"
+---| "TABLE_INLINE"
+---| "LOCAL_DATE"
+---| "LOCAL_TIME"
+---| "LOCAL_DATETIME"
+---| "OFFSET_DATETIME"
+
+---@alias TomlTypeNum
+---| 0
+---| 1
+---| 2
+---| 3
+---| 4
+---| 5
+---| 6
+---| 7
+---| 8
+---| 9
+---| 10
+---| 11
+---| 12
+---| 13
+
+---@class Tomlua.main
+---@field opts TomluaOptions
+---@field types table<TomlType, TomlTypeNum>
+---@field decode fun(str:string):(any, string?): table?, string? -- returns result?, err?
+---@field encode fun(val:any):(string, string?): string?, string? -- returns result?, err?
+---@field type fun(val:any):TomlType
+---@field type_of fun(val:any):TomlTypeNum
+---@field typename fun(typ:TomlTypeNum):TomlType
+---@field str_2_mul fun(s:string):userdata -- can call tostring on the result to get it back, written as multiline string by encode.
+---@field new_date fun(src:string|number|Tomlua.DateTable|Tomlua.Date?):Tomlua.Date
+
+---@alias Tomlua Tomlua.main | fun(opts?:TomluaOptions):Tomlua

tests/scratch.lua

@@ -1,5 +1,6 @@
 package.cpath = "./lib/?.so;" .. package.cpath
 local inspect = require('inspect')
+---@type Tomlua
 local tomlua = require("tomlua")
 
 print(inspect(tomlua))
@@ -100,7 +101,7 @@ print(date < date2) -- false
 print("date1", date)
 
 print(date.toml_type)
-print(tomlua.typename(tomlua.type(date)))
+print(tomlua.typename(tomlua.type_of(date)))
 date.toml_type = "LOCAL_TIME"
 print(date.toml_type)
 print(date)