模組:Conversion rule extractor

模块文档[查看] [编辑] [历史] [清除缓存]

本模块用于提取指定页面的字词转换规则（包括手动规则和公共转换组规则），并根据需要筛选出能在特定目标页面或标题上匹配使用的规则，最终以不同格式输出。

子模块

• Module:Conversion_rule_extractor/Extractor – 用于提取规则
• Module:Conversion_rule_extractor/Matcher – 用于匹配规则

函数

getRules

获取指定来源页面的所有内容转换规则（手动+公共组），并筛选出能在目标页面内容中匹配到的规则。

调用方式： {{#invoke:Conversion_rule_extractor|getRules|from=来源页面|to=目标页面|flag=输出格式}}

参数：

• from 或匿名参数 1: (必须) 字符串，规则来源页面的标题。
• to: (可选) 字符串，用于匹配规则的目标页面标题。默认为调用模块的当前页面。
• flag: (可选) 字符串，指定输出规则的旗标。
  • H (默认): 输出为-{H|规则;}-格式。
  • raw: 直接输出规则文本，每条规则占一行。
  • 其他值 (如 A, D): 输出为-{值|规则;}-格式。

返回值： 字符串，格式化后的、能在目标页面匹配到的内容转换规则。如果来源页不存在或无匹配规则，返回空字符串。如果缺少 from 参数，返回错误提示信息。

getTitleRule

获取应用于指定来源页面标题的转换规则。

• 如果来源页面有显式的标题 (T) 规则，则使用该规则。
• 如果没有显式标题规则，则尝试将来源页面的所有内容规则与其标题文本进行匹配，使用匹配到的规则。

调用方式： {{#invoke:Conversion_rule_extractor|getTitleRule|from=来源页面|flag=输出格式|type=输出类型}}

参数：

• from 或匿名参数 1: (必须) 字符串，规则来源页面的标题。
• flag: (可选) 字符串，指定输出规则的旗标（当type不为context时生效）。
  • H (默认): 输出为-{H|规则;}-格式。
  • raw: 直接输出规则文本，每条规则占一行。
  • 其他值: 输出为-{值|规则;}-格式。如果规则来源于内容规则匹配，即使指定flag='T'，也会强制使用H。
• type: (可选) 字符串，指定输出类型。
  • context: (特殊模式) 如果存在显式T规则，输出为-{T规则;}-。如果不存在显式T规则，但有内容规则匹配标题，输出为-{H|匹配的内容规则;}-原始标题。
  • 其他值或省略: 按flag参数指定的格式输出规则本身。

返回值： 字符串，格式化后的标题转换规则或带规则的标题文本。如果来源页不存在或无适用规则，返回空字符串。如果缺少from参数或来源页不存在，返回错误提示信息。

参见

• {{NoteTA-lite}}

上述文档嵌入自Module:Conversion rule extractor/doc。 (编辑 | 历史)
编者可以在本模块的沙盒 (创建 | 镜像)和测试样例 (创建)页面进行实验。
本模块的子页面。

local p = {}
local TPV = require('Module:Template parameter value')
local Arguments = require('Module:Arguments') -- 用于模板入口点
local mw_text = require('mw.text') -- 用于分割和裁剪

-- 以下模板的重定向检索于2025-05-03
local NOTE_TA_TEMPLATES = {
    'NoteTA', 'TA', 'NoteAT', 'NoteTA/default', 'NOTETA', 'Note TA', 'Noteta', 'NoteTa', 'NoteTA/lua', '全文字词转换',
    'NoteTA-lite', 'TA-lite', 'TAL', 'TAl'
}

local MAX_LOCAL_RULES = 30 -- 本地规则查找上限
local MAX_GROUP_RULES = 30 -- 公共转换组查找上限

--[[--------------------------< 辅助函数 - CGroup 处理 >--------------------------]]

-- 安全地加载 CGroup 模块数据
local function loadCGroupData(groupName)
    local moduleTitleStr = 'Module:CGroup/' .. groupName
    local success, data
    local titleObj = mw.title.new(moduleTitleStr)
    if titleObj and titleObj.exists then
        success, data = pcall(mw.loadData, moduleTitleStr)
        if success and type(data) == 'table' then
            return data
        else
            return nil
        end
    end
    return nil
end

-- 从加载的 CGroup 数据中提取规则
local function extractRulesFromCGroupData(data)
    local rules = {}
    if data and data.content and type(data.content) == 'table' then
        for _, item in ipairs(data.content) do
            if type(item) == 'table' and item.type == 'item' and type(item.rule) == 'string' and item.rule ~= '' then
                table.insert(rules, item.rule)
            end
        end
    end
    return rules
end

--[[--------------------------< 辅助函数 - 规则解析与过滤 >--------------------------]]

-- 从单个规则字符串中提取所有可能的源文本 (用于匹配)
-- 例如 "zh-cn:电脑; zh-tw:電腦 => computer" 返回 {"电脑", "電腦"}
-- 例如 "zh-hans:软件; zh-hk:軟件;" 返回 {"软件", "軟件"}
local function extractSourceTerms(ruleString)
    local sources = {}
    local rulePart = ruleString
    -- 检查是否有 => 分隔符
    local arrowPos = string.find(rulePart, '=>', 1, true)
    if arrowPos then
        rulePart = mw_text.trim(string.sub(rulePart, 1, arrowPos - 1))
    end

    -- 按 ; 分割规则
    for segment in mw_text.gsplit(rulePart, ';') do
        segment = mw_text.trim(segment)
        if segment ~= '' then
            local term
            -- 检查是否有 : 分隔符 (如 zh-cn:xxx)
            local colonPos = string.find(segment, ':', 1, true)
            if colonPos then
                -- 取第一个冒号后面的部分
                term = mw_text.trim(string.sub(segment, colonPos + 1))
            else
                -- 没有冒号，整个段落是源文本 (如 A=>B 中的 A)
                term = segment
            end
            if term ~= '' then
                table.insert(sources, term)
            end
        end
    end
    return sources
end

-- 过滤 CGroup 规则列表，只保留至少一个源文本在目标文本中出现的规则
local function filterGroupRulesByText(groupRules, textToMatch)
    if not textToMatch or textToMatch == '' or not groupRules or #groupRules == 0 then
        return {}
    end
    local filteredRules = {}
    for _, ruleString in ipairs(groupRules) do
        local sourceTerms = extractSourceTerms(ruleString)
        local matched = false
        for _, term in ipairs(sourceTerms) do
            -- 使用简单的字符串查找 (plain find)
            if string.find(textToMatch, term, 1, true) then
                matched = true
                break -- 找到一个匹配就足够包含此规则
            end
        end
        if matched then
            table.insert(filteredRules, ruleString)
        end
    end
    return filteredRules
end

--[[--------------------------< 辅助函数 - 格式化输出 >--------------------------]]

-- 将规则列表格式化为最终输出字符串
local function formatRules(rules, flag)
    if not rules or #rules == 0 then
        return ''
    end

    flag = (type(flag) == 'string' and flag ~= '') and flag or 'H' -- 默认 flag 为 'H'

    if flag == 'raw' then
        -- 直接连接，用换行符分隔
        return table.concat(rules, "\n")
    else
        -- 对每个规则应用 -{[flag]|...}- 包装
        local wrapped_rules = {}
        for _, rule in ipairs(rules) do
            -- 不需要手动移除末尾分号，转换器能处理
            table.insert(wrapped_rules, "-{" .. flag .. "|" .. rule .. "}-")
        end
        -- 将包装好的规则块连接起来
        return table.concat(wrapped_rules, "")
    end
end


--[[--------------------------< 核心获取函数 >--------------------------]]

--[[
-- @description 内部函数，获取原始规则数据
-- @param pageTitleString string 页面标题字符串
-- @return table|nil 包含原始规则的表或 nil
--]]
function p._internal_fetchAllRules(pageTitleString)
    -- (此函数与上一版本基本相同，确保 ['local'] 的使用)
    local allRules = {
        title = nil,
        ['local'] = {},
        groups = {} -- { {name=..., rules={...}}, ... }
    }
    local foundTemplate = false
    local titleObj = mw.title.new(pageTitleString)
    if not titleObj then
         -- 如果标题无效，则无法继续
         mw.log('ConversionRuleExtractor: Invalid page title provided: ' .. pageTitleString)
         return nil
    end

    -- 1. 获取标题规则 (T)
    local success_t, titleRule = TPV.getParameter(pageTitleString, NOTE_TA_TEMPLATES, 'T')
    if success_t and titleRule and titleRule ~= '' then
        allRules.title = titleRule
        foundTemplate = true
    end

    -- 2. 获取本地规则 (1..MAX_LOCAL_RULES)
    for i = 1, MAX_LOCAL_RULES do
        local paramName = tostring(i)
        local success_l, localRule = TPV.getParameter(pageTitleString, NOTE_TA_TEMPLATES, paramName)
        if success_l and localRule and localRule ~= '' then
            table.insert(allRules['local'], localRule)
            foundTemplate = true
        elseif not success_l and localRule == "No valid template found" and not foundTemplate then
            -- 提前退出：如果连第一个本地规则都因“未找到模板”而失败，且之前没找到T，则模板不存在
             if i == 1 then return nil end
             -- 否则，可能是参数用完了，继续检查G组
             break -- 优化：假设本地规则是连续的
        end
    end

    -- 3. 获取组规则 (G1..MAX_GROUP_RULES)
    local rawGroupRules = {} -- 临时存储所有组的规则 { "G1 rule1", "G1 rule2", "G2 rule1", ... }
    for i = 1, MAX_GROUP_RULES do
        local paramName = 'G' .. i
        local success_g, groupName = TPV.getParameter(pageTitleString, NOTE_TA_TEMPLATES, paramName)
        if success_g and groupName and groupName ~= '' then
            foundTemplate = true
            local groupData = loadCGroupData(groupName)
            if groupData then
                 local rulesFromGroup = extractRulesFromCGroupData(groupData)
                 if #rulesFromGroup > 0 then
                    -- 存储组名和规则，供 getFullTextRules 使用
                     table.insert(allRules.groups, { name = groupName, rules = rulesFromGroup })
                 end
            end
        elseif not success_g and groupName == "No valid template found" and not foundTemplate then
             -- 提前退出：如果连第一个组规则都因“未找到模板”而失败，且之前未找到T或本地规则
             if i == 1 then return nil end
             break -- 优化：假设G规则是连续的
        end
    end

    if foundTemplate then
        return allRules
    else
        return nil -- 页面上没有找到任何 NoteTA 模板或有效参数
    end
end


--[[--------------------------< 公开函数 >--------------------------]]

--[[
-- @description 获取全文转换规则（本地 + 所有组规则）并格式化输出
-- @param pageTitle string|mw.title 页面标题
-- @param flag string|nil 输出格式标志 ('H', 'raw', 'A', etc.)
-- @return string 格式化后的规则字符串，或空字符串
--]]
function p.getFullTextRules(pageTitle, flag)
    local pageTitleString
    if type(pageTitle) == 'string' then
        pageTitleString = pageTitle
    elseif type(pageTitle) == 'userdata' and getmetatable(pageTitle) == 'mw.title' then
         pageTitleString = pageTitle.fullText
    else
        -- error("无效的 pageTitle 类型。", 2) -- 改为返回空字符串
        return ''
    end

    local allRulesData = p._internal_fetchAllRules(pageTitleString)
    if not allRulesData then
        return ''
    end

    local combinedRules = {}
    -- 添加本地规则
    if allRulesData['local'] then
        for _, rule in ipairs(allRulesData['local']) do table.insert(combinedRules, rule) end
    end
    -- 添加所有公共转换组规则
    if allRulesData.groups then
        for _, groupInfo in ipairs(allRulesData.groups) do
            if groupInfo.rules then
                for _, rule in ipairs(groupInfo.rules) do table.insert(combinedRules, rule) end
            end
        end
    end

    return formatRules(combinedRules, flag)
end

--[[
-- @description 获取标题转换规则（T 或 本地 + 匹配的组规则）并格式化或应用
-- @param pageTitle string|mw.title 页面标题
-- @param flag string|nil 输出格式标志 ('H', 'raw', 'A', etc.)
-- @param type string|nil 'context' 表示应用规则，否则忽略
-- @param frame table The frame object (必需当 type='context')
-- @return string 格式化/应用后的字符串，或空字符串
--]]
function p.getTitleRules(pageTitle, flag, type, frame)
    local pageTitleString
    local titleObj
    if type(pageTitle) == 'string' then
        pageTitleString = pageTitle
        titleObj = mw.title.new(pageTitleString)
    elseif type(pageTitle) == 'userdata' and getmetatable(pageTitle) == 'mw.title' then
         pageTitleString = pageTitle.fullText
         titleObj = pageTitle
    else
        return '' -- 无效输入
    end

    if not titleObj then return '' end -- 标题无效

    local titleText = titleObj:getText() -- 获取用于匹配的原始标题文本

    local allRulesData = p._internal_fetchAllRules(pageTitleString)
    if not allRulesData then
        return (type == 'context') and titleText or '' -- context模式下返回原标题，否则空
    end

    -- 处理 type = 'context'
    if type == 'context' then
        if not frame then
           return '<span class="error">错误：type=\'context\' 需要 frame 对象。</span>'
        end
        -- 如果存在 T 规则，优先使用 T 规则
        if allRulesData.title and allRulesData.title ~= '' then
            -- T规则直接定义了标题的显示方式
            local rule_wikitext = "-{T|" .. allRulesData.title .. "}-"
            -- T规则本身就是结果，不需要附加原标题
            return frame:preprocess(rule_wikitext)
        else
            -- 没有 T 规则，组合本地规则和匹配的组规则
            local applicableRules = {}
            -- 添加本地规则
            if allRulesData['local'] then
                for _, rule in ipairs(allRulesData['local']) do table.insert(applicableRules, rule) end
            end
            -- 提取所有组规则进行过滤
            local allGroupRules = {}
            if allRulesData.groups then
                for _, groupInfo in ipairs(allRulesData.groups) do
                    if groupInfo.rules then
                        for _, rule in ipairs(groupInfo.rules) do table.insert(allGroupRules, rule) end
                    end
                end
            end
            -- 过滤组规则
            local filteredGroupRules = filterGroupRulesByText(allGroupRules, titleText)
            for _, rule in ipairs(filteredGroupRules) do table.insert(applicableRules, rule) end

            if #applicableRules == 0 then
                return titleText -- 没有适用的规则，返回原始标题
            else
                -- 将所有适用的规则（本地+过滤后的组）格式化为 H 规则
                local rules_wikitext = formatRules(applicableRules, 'H')
                -- 将规则应用到原始标题文本前
                return frame:preprocess(rules_wikitext .. titleText)
            end
        end
    else
        -- 处理格式化输出 (非 context)
        local combinedRules = {}
        -- T 规则优先，但这里是格式化规则本身，T 和其他规则可以并存
        if allRulesData.title and allRulesData.title ~= '' then
             -- 注意：T规则理论上不应与其他规则混用在一个-{}-块内，但按要求格式化
             -- 实际上，T规则通常单独处理。但如果flag不是raw，这里会按flag包装它
             table.insert(combinedRules, allRulesData.title)
        end
         -- 添加本地规则
        if allRulesData['local'] then
            for _, rule in ipairs(allRulesData['local']) do table.insert(combinedRules, rule) end
        end
        -- 提取所有组规则进行过滤
        local allGroupRules = {}
        if allRulesData.groups then
            for _, groupInfo in ipairs(allRulesData.groups) do
                if groupInfo.rules then
                    for _, rule in ipairs(groupInfo.rules) do table.insert(allGroupRules, rule) end
                end
            end
        end
        -- 过滤组规则
        local filteredGroupRules = filterGroupRulesByText(allGroupRules, titleText)
        for _, rule in ipairs(filteredGroupRules) do table.insert(combinedRules, rule) end

        return formatRules(combinedRules, flag)
    end
end


--[[--------------------------< 模板入口点 >--------------------------]]

-- {{#invoke:ConversionRuleExtractor|getFullText|页面标题|flag=标志}}
function p.getFullText(frame)
    local args = Arguments.getArgs(frame)
    local page = args[1] or args.page
    local flag = args.flag or 'H' -- flag 默认为 H

    if not page or page == '' then
        return '<span class="error">错误：必须提供页面标题。</span>'
    end

    local result = p.getFullTextRules(page, flag)
    -- 如果结果为空，可以考虑返回一个提示信息，或者就是空字符串
    -- return result == '' and "''（未找到适用的全文规则）''" or result
    return result
end

-- {{#invoke:ConversionRuleExtractor|getTitle|页面标题|flag=标志|type=context}}
function p.getTitle(frame)
    local args = Arguments.getArgs(frame)
    local page = args[1] or args.page
    local flag = args.flag -- 不设默认值，由 getTitleRules 处理
    local type = args.type

    if not page or page == '' then
        return '<span class="error">错误：必须提供页面标题。</span>'
    end

    local result = p.getTitleRules(page, flag, type, frame) -- 传递 frame
    -- return result == '' and "''（未找到适用的标题规则）''" or result
     -- 如果是 context 模式且无规则，getTitleRules 已返回原标题，无需特殊处理空字符串
    return result
end

return p