Module:CSVReader

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

---
---Convert the specified CSV file on the wiki into a Lua table.
---
---The page must contain properly formatted CSV data and only the CSV data, without any explanation, wiki markup, or other content.
---
---@module CSVReader
local CSVReader = {}

--region Dependencies
-- none
--endregion



--region Private constants

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

local ERROR_PREFIX_TITLE_INVALID_NAME = "CSVReader 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 = "CSVReader 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 = "CSVReader 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 = "CSVReader 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 MINIMUM_LENGTH_THAT_SUGGESTS_VALID_CONTENT = 4

--endregion



--region Private member variables

-- Splits the lines of the CSV file on the commas.
-- Special handling made for one set of double quotations.
-- Someone better at coding than I am please generalize this to handle multiple quotations and nested quotations.
function CSVReader.commaSplit(text)
    local ret = {}
    local s, l = 1, string.len( text )
    while s do
    	local e, n = string.find( text, ',', s, true)
    	
    	--Deal with one possible double quote. If there are more or even nested quotes... then I don't know.
    	local qe, qn = string.find( text, '"', s, true)
    	if qe and e and qe < e then
    		local qqe, qqn = string.find( text, '"', qe+1, true)
    		e,n = string.find( text, ',', qqe+1, true)
    	end
    	
    	if not e then
    		ret[#ret+1] = string.sub ( text, s )
    		s = nil
    	else
    		ret[#ret+1] = e > s and string.sub( text, s, e - 1 ) or ''
    		s = e + 1
    	end
    end
    return ret
end

--endregion



--region Private methods
-- none
--endregion

--region Public methods

---Loads CSV data from the specified page on the wiki into a Lua table.
---@param wikiPageName string the title of the wiki page, including
---@return table
function CSVReader.convertCSVToLuaTable(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

	local decodedTable = {} -- Stores the table to return
	local CSVlines = mw.text.split(unparsedContent, '\n', true) -- split the CSV into separate lines.
	local headerNames = CSVReader.commaSplit(CSVlines[1]) -- get the names of each column from the first line.
	
	-- Most TI template files have a dataName column. Find this dataName column, if it exists. 
	local hasDataNameColumn = false
	local DataNameColumnIndex = 0
	for i, columnName in ipairs(headerNames) do
	    if columnName == 'dataName' then
	    	hasDataNameColumn = true
			DataNameColumnIndex = i
	    end
	end
	
	if hasDataNameColumn then
		for j, CSVline in ipairs(CSVlines) do -- Consider each CSV line one by one:
			if j > 1 then -- Skip the header line.
				-- Create a row with name set to the value in the dataName column.
				local rowDataName = CSVReader.commaSplit(CSVline)[DataNameColumnIndex]
				decodedTable[rowDataName] = {} 
				for i, cellData in ipairs(CSVReader.commaSplit(CSVline)) do
					-- Fill in the cell data for the row corresponding to the dataName and the column corresponding to headerNames[i].
					local columnName = headerNames[i]
					decodedTable[rowDataName][columnName] = cellData
				end
			end
		end
	else
		for j, CSVline in ipairs(CSVlines) do -- Consider each CSV line one by one:
			if j > 1 then -- Skip the header line.
				-- Create a row with index j - 1.
				decodedTable[j-1] = {} 
				for i, cellData in ipairs(CSVReader.commaSplit(CSVline)) do
					-- Fill in the cell data for the j-1-th row and the column corresponding to headerNames[i].
					decodedTable[j-1][headerNames[i]] = cellData 
				end
			end
		end
	end

    return decodedTable
end


---Loads CSV data from the specified page on the wiki into a wiki table.
---@param wikiPageName string the title of the wiki page, including
---@return table
function CSVReader.convertCSVToWikiTable(wikiPageName)
	local decodedTable = CSVReader.convertCSVToLuaTable(wikiPageName)
	local returnString = '{| class="wikitable sortable mw-collapsible mw-collapsed" style="text-align: center;\n|-\n'
	local headersNotDone = true
	for rowID, row in pairs(decodedTable) do
    	if headersNotDone then
    		for column, cellData in pairs(row) do
		    	returnString = returnString .. '! ' .. column .. '\n' 
		    end
		    returnString = returnString .. '|-\n'
		    headersNotDone = false
    	end
	    for column, cellData in pairs(row) do
	    	returnString = returnString .. '| ' .. cellData .. '\n' 
	    end
	    returnString = returnString .. '|-\n'
	end
	returnString = returnString .. '|}'
	return returnString
end

--endregion

return CSVReader