Module:JsonUtils

Documentation for this module may be created at Module:JsonUtils/doc

---
--- Uses mw.text.jsonDecode to convert a named wiki page into a Lua table.
---
--- The page must contain properly formatted JSON data and only the JSON data, without any explanation, wiki markup, or other content.
---
--- The table returned may have missing fields where they would otherwise be expected if the JSON data contained nil values for those fields.
---
---@module JsonUtils
local JsonUtils = {}



--region Private constants

local ERROR_MESSAGE_PARAMETER_MISSING = "JsonUtils requires as its parameter that you provide the name of a page on the wiki that contains valid JSON data. Call the main function with a parameter that is the name of the desired page, like this:\n  `JsonUtils.main('Template:Data_json`)`"

local ERROR_PREFIX_TITLE_INVALID_NAME = "JsonUtils failed to create a Mediawiki title object with the page name you provided. Double-check that the page name you provided is a properly formatted string and valid page title: "
local ERROR_PREFIX_TITLE_PAGE_DOES_NOT_EXIST = "JsonUtils checked the page name you provided, and the page does not exist. Double-check that the page name you provided is correct: "

local ERROR_PREFIX_CONTENT_NOT_FOUND = "JsonUtils did not find content on the page whose name you provided. Double check that the page exists and that it contains content: "
local ERROR_PREFIX_CONTENT_NOT_LONG_ENOUGH = "JsonUtils found content on the page whose name you provided, but it is too short to be useful. Double-check that you provided the correct name, and that there is content on the page: "

local ERROR_PREFIX_JSON_DATA_NOT_USABLE = "JsonUtils loaded the content on the page, but parsing it as JSON data was not successful. Double-check that the page you provided contains properly formatted JSON data: "
local ERROR_PREFIX_JSON_NO_DATA = "JsonUtils loaded and parsed the content on the page you provided, but parsing it as JSON data yielded an empty table. Double-check that the page you provided contains more than one JSON record: "

local MINIMUM_LENGTH_THAT_SUGGESTS_VALID_CONTENT = 4

--endregion



--region Private methods
-- none
--endregion



--region Public methods

--- Loads JSON data from a wiki page into a Lua table.
---@param wikiPageName string the title of the wiki page, including
---@return table
function JsonUtils.main(wikiPageName)

    -- Verify the parameter.
    if not wikiPageName or "" == wikiPageName then
        error(ERROR_MESSAGE_PARAMETER_MISSING);
    end

    -- Verify that the name is valid and that the page exists.
    local titleObject = mw.title.new(wikiPageName)
    if not titleObject then
        error(ERROR_PREFIX_TITLE_INVALID_NAME .. wikiPageName .. ".")
    end
    if not titleObject.exists then
        error(ERROR_PREFIX_TITLE_PAGE_DOES_NOT_EXIST .. wikiPageName .. ".")
    end

    -- Verify that the page content can be loaded and that there is something there to use.
    local unparsedContent = titleObject:getContent()
    if not unparsedContent then
        error(ERROR_PREFIX_CONTENT_NOT_FOUND .. wikiPageName .. ".")
    end
    if #unparsedContent < MINIMUM_LENGTH_THAT_SUGGESTS_VALID_CONTENT then
        error(ERROR_PREFIX_CONTENT_NOT_LONG_ENOUGH .. wikiPageName .. ".")
    end

    -- Verify that the data is valid and useful JSON.
    local success, decodedTable = pcall(mw.text.jsonDecode, unparsedContent)
    if not success or not decodedTable then
        error(ERROR_PREFIX_JSON_DATA_NOT_USABLE .. wikiPageName .. ".")
    end
    if #decodedTable < 1 then
        error(ERROR_PREFIX_JSON_NO_DATA .. wikiPageName .. ".")
    end

    return decodedTable
end

--endregion

return JsonUtils