Module:WikitextProcessor

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

-- Module:WikitextProcessor
-- Generalized content processor for wikitext formatting and frontend display,  regardless of source (JSON, XML, database, user input, etc.)
-- Features: Error handling; Three wiki link patterns: [[Page]], [[Page|text]], [[#anchor|text]]; Placeholder replacement with $VARIABLE$ syntax; Content normalization and whitespace cleanup

local p = {}

-- Dependencies
local ErrorHandling = require('Module:ErrorHandling')

-- Constants for performance
local CONTEXT_NAME = 'wikitextProcessor'
local ERROR_MESSAGES = {
    urlFailed = 'URL generation failed for wiki link',
    encodeFailed = 'Text encoding failed for wiki link',
    formatFailed = 'HTML formatting failed for wiki link'
}

-- Clean error handling
local function handleError(errorContext, operation, fallbackValue)
    if errorContext then
        ErrorHandling.addStatus(errorContext, CONTEXT_NAME, ERROR_MESSAGES[operation] or ERROR_MESSAGES.urlFailed, nil)
    end
    return fallbackValue
end

-- Constants as upvalues for performance
local WIKI_LINK_PATTERNS = {
    -- Pattern 1: [[Page Name]] -> HTML page links
    {
        pattern = '%[%[([^#|%]]+)%]%]',
        processor = function(pageName, errorContext)
            local spacesReplaced = (pageName:gsub(' ', '_'))
            local success, pageUrl = pcall(function()
                return tostring(mw.uri.fullUrl(spacesReplaced))
            end)
            if not success then
                return handleError(errorContext, 'urlFailed', '[[' .. pageName .. ']]')
            end
            
            local pageNameStr = type(pageName) == "string" and pageName or tostring(pageName)
            success, pageNameStr = pcall(mw.text.encode, pageNameStr)
            if not success then
                return handleError(errorContext, 'encodeFailed', '[[' .. pageName .. ']]')
            end
            
            success, pageUrl = pcall(string.format, '<a href="%s">%s</a>', pageUrl, pageNameStr)
            if not success then
                return handleError(errorContext, 'formatFailed', '[[' .. pageName .. ']]')
            end
            
            return pageUrl
        end
    },
    
    -- Pattern 2: [[Page|text]] -> HTML page links with custom text
    {
        pattern = '%[%[([^#|%]]+)|([^%]]+)%]%]',
        processor = function(pageName, text, errorContext)
            local success, pageUrl = pcall(function()
                return tostring(mw.uri.fullUrl((pageName:gsub(' ', '_'))))
            end)
            if not success then
                return handleError(errorContext, 'urlFailed', '[[' .. pageName .. '|' .. text .. ']]')
            end
            
            local textStr = type(text) == "string" and text or tostring(text)
            success, textStr = pcall(mw.text.encode, textStr)
            if not success then
                return handleError(errorContext, 'encodeFailed', '[[' .. pageName .. '|' .. text .. ']]')
            end
            
            success, pageUrl = pcall(string.format, '<a href="%s">%s</a>', pageUrl, textStr)
            if not success then
                return handleError(errorContext, 'formatFailed', '[[' .. pageName .. '|' .. text .. ']]')
            end
            
            return pageUrl
        end
    },
    
    -- Pattern 3: [[#anchor|text]] -> HTML anchor links
    {
        pattern = '%[%[#([^|%]]+)|([^%]]+)%]%]',
        processor = function(anchor, text, errorContext)
            local success, encodedAnchor = pcall(mw.uri.anchorEncode, anchor)
            if not success then
                return handleError(errorContext, 'urlFailed', '[[#' .. anchor .. '|' .. text .. ']]')
            end
            
            local textStr = type(text) == "string" and text or tostring(text)
            success, textStr = pcall(mw.text.encode, textStr)
            if not success then
                return handleError(errorContext, 'encodeFailed', '[[#' .. anchor .. '|' .. text .. ']]')
            end
            
            success, encodedAnchor = pcall(string.format, '<a href="#%s">%s</a>', encodedAnchor, textStr)
            if not success then
                return handleError(errorContext, 'formatFailed', '[[#' .. anchor .. '|' .. text .. ']]')
            end
            
            return encodedAnchor
        end
    }
}

-- Normalizes content string by cleaning up whitespace
function p.normalizeContentString(content)
    if not content or content == "" then
        return content
    end
    
    -- Apply string normalization exactly like the original T-Campaign code
    return content:gsub("%s+", " "):gsub("^%s+", ""):gsub("%s+$", "")
end

-- Replaces placeholder patterns ($VARIABLE$) with actual values
function p.replacePlaceholders(content, placeholderMap, errorContext)
    if not content then
        return content
    end
    
    -- DEFENSIVE: Input validation with detailed logging
    if not placeholderMap or type(placeholderMap) ~= "table" then
        if errorContext then
            ErrorHandling.addStatus(errorContext, CONTEXT_NAME, 'Invalid placeholder map', 'Type: ' .. type(placeholderMap))
        end
        return content
    end
    
    -- DEFENSIVE: Validate critical placeholders with detailed logging
    local validPlaceholders = {}
    local invalidPlaceholders = {}
    
    for key, value in pairs(placeholderMap) do
        if value and type(value) == "string" and value ~= "" then
            validPlaceholders[key] = value
            if errorContext then
                ErrorHandling.addStatus(errorContext, CONTEXT_NAME, 'Valid placeholder received', 'Key: ' .. key .. ', Value: "' .. value .. '"')
            end
        else
            invalidPlaceholders[key] = tostring(value)
            if errorContext then
                ErrorHandling.addStatus(errorContext, CONTEXT_NAME, 'Invalid placeholder detected', 'Key: ' .. key .. ', Value: "' .. tostring(value) .. '", Type: ' .. type(value))
            end
        end
    end
    
    local result = content
    
    -- Apply placeholder replacement exactly like the original T-Campaign code
    for key, value in pairs(validPlaceholders) do
        local beforeReplace = result
        result = result:gsub("%$" .. key .. "%$", value)
        
        -- Log successful replacements
        if beforeReplace ~= result and errorContext then
            ErrorHandling.addStatus(errorContext, CONTEXT_NAME, 'Placeholder replaced successfully', 'Key: ' .. key .. ', Replacements made')
        end
    end
    
    -- Clean up any remaining unfilled placeholders (TemplateStarter's removeEmptyPlaceholders logic)
    local beforeCleanup = result
    result = result:gsub("%$[A-Z_]+%$", "")
    result = result:gsub("%s+", " "):gsub("^%s+", ""):gsub("%s+$", "")
    
    -- Log cleanup if any unfilled placeholders were removed
    if beforeCleanup ~= result and errorContext then
        ErrorHandling.addStatus(errorContext, CONTEXT_NAME, 'Unfilled placeholders cleaned up', 'Content normalized')
    end
    
    return result
end

-- Processes wiki links in content and converts them to HTML
function p.processWikiLinksToHTML(content, errorContext)
    if not content or content == "" then
        return content
    end
    
    -- UNIFIED PIPELINE: Process ALL wiki links with custom patterns (no frame:preprocess)
    local originalContent = content
    local result = content
    
    -- Process each wiki link pattern in sequence exactly like the original T-Campaign code
    for _, patternInfo in ipairs(WIKI_LINK_PATTERNS) do
        result = result:gsub(patternInfo.pattern, function(...)
            return patternInfo.processor(..., errorContext)
        end)
    end
    
    return result
end

-- Main entry point: Processes JSON content with wikitext formatting for frontend display
-- @param content The content string to process
-- @param placeholders Optional table of placeholder values for $VARIABLE$ replacement
-- @param errorContext Optional error context for error reporting
-- @return Processed content ready for frontend display
function p.processContentForFrontend(content, placeholders, errorContext)
    if not content or content == "" then
        return content
    end
    
    -- Step 1: Normalize content string
    local processedContent = p.normalizeContentString(content)
    
    -- Step 2: Replace placeholders if provided
    if placeholders then
        processedContent = p.replacePlaceholders(processedContent, placeholders)
    end
    
    -- Step 3: Process wiki links to HTML
    processedContent = p.processWikiLinksToHTML(processedContent, errorContext)
    
    return processedContent
end

return p