Files

152 lines
6.6 KiB
Lua

-- AD Help
-- Manualen i spillet (brugerønske 20/10: "?" ud for hver ting man kan indstille + hele manualen med søgning).
-- help/help_<sprog>.xml bygges af tools/build_help.py ud fra docs/*.md: et <section> pr. afsnit og <alias> fra en
-- række/et trin i menuen til sit afsnit. Ren logik øverst (testes med luajit), indlæsning nederst.
ADHelp = {}
ADHelp.SEARCH_MAX = 30
ADHelp.SNIPPET_CHARS = 70
-- ---- ren logik ----
-- Menuens række -> hjælpe-id. data = rækkens rowData; ctx = {guideKind = "flow"|"field", direction = "out"|"in"}.
-- Guide-rækker: "<guide>.<række-id>"; Indstillinger: "set.<nøgle>"; Marksiloer: "fs.<art>". nil = ingen hjælp.
function ADHelp.rowId(data, ctx)
if type(data) ~= "table" then return nil end
local kind = data.kind
if kind == "guideRow" and data.row ~= nil and data.row.id ~= nil and ctx ~= nil and ctx.guideKind ~= nil then
return ctx.guideKind .. "." .. tostring(data.row.id)
end
if (kind == "setGlobal" or kind == "setBuilding" or kind == "setBarnOnly") and data.key ~= nil then return "set." .. data.key end
if kind == "lockTractor" then return "set.lockTractor" end
if kind == "settingsSection" then return "set.section" end
if type(kind) == "string" and kind:sub(1, 2) == "fs" then return "fs." .. kind end
return nil
end
-- Guidens trin -> hjælpe-id ("flowstep.rules")
function ADHelp.stepId(guideKind, step)
if guideKind == nil or step == nil then return nil end
return guideKind .. "step." .. tostring(step)
end
-- Findes der hjælp til id'et? Retningen først ("flowstep.rules.out"), så det generelle. -> alias | nil
function ADHelp.findAlias(data, id, direction)
if data == nil or id == nil then return nil end
if direction ~= nil and data.aliases[id .. "." .. direction] ~= nil then return data.aliases[id .. "." .. direction] end
return data.aliases[id]
end
-- Byteposition flyttet frem til starten af et utf-8-tegn (æ/ø/å er to bytes; et uddrag må ikke klippe dem over)
function ADHelp.charStart(text, position)
local index = math.max(1, position)
while index <= #text do
local byte = string.byte(text, index)
if byte < 0x80 or byte >= 0xC0 then break end
index = index + 1
end
return index
end
local function lower(text)
-- æ/ø/å skrives ens i søgeord og tekst (utf-8 byte-sekvenser), så kun ASCII-bogstaver foldes
return string.lower(tostring(text or ""))
end
-- Søgning i alle afsnit: alle ord skal stå i titel eller tekst; titeltræffere først. -> {{section, snippet}}
function ADHelp.search(sections, query, max)
local words = {}
for word in string.gmatch(lower(query), "%S+") do table.insert(words, word) end
if #words == 0 then return {} end
local titleHits, textHits = {}, {}
for _, section in ipairs(sections or {}) do
local title = lower(section.title)
local body = lower(table.concat(section.paragraphs or {}, " "))
local all, inTitle = true, true
for _, word in ipairs(words) do
local t = string.find(title, word, 1, true) ~= nil
if not t and string.find(body, word, 1, true) == nil then all = false break end
inTitle = inTitle and t
end
if all then
local snippet = ""
local full = table.concat(section.paragraphs or {}, " ")
local at = string.find(lower(full), words[1], 1, true)
if at ~= nil then
local from = ADHelp.charStart(full, at - 20)
local to = ADHelp.charStart(full, from + ADHelp.SNIPPET_CHARS + 1) - 1
snippet = (from > 1 and "…" or "") .. string.sub(full, from, to) .. (to < #full and "…" or "")
end
table.insert(inTitle and titleHits or textHits, {section = section, snippet = snippet})
end
end
local result = {}
for _, list in ipairs({titleHits, textHits}) do
for _, hit in ipairs(list) do
if #result < (max or ADHelp.SEARCH_MAX) then table.insert(result, hit) end
end
end
return result
end
-- Underafsnit (dybere niveau, lige efter afsnittet) -> liste af sektioner
function ADHelp.children(sections, index)
local parent = sections[index]
local list = {}
if parent == nil then return list end
for i = index + 1, #sections do
local section = sections[i]
if section.level <= parent.level then break end
if section.level == parent.level + 1 then table.insert(list, section) end
end
return list
end
-- ---- indlæsning ----
local loaded = nil -- {sections = {}, byId = {}, indexOf = {}, aliases = {}}
local function readParagraphs(xml, key)
local list = {}
xml:iterate(key .. ".p", function(_, pKey) table.insert(list, xml:getString(pKey) or "") end)
return list
end
-- Hjælpen på spillets sprog (dansk, ellers engelsk). Indlæses én gang.
function ADHelp.get()
if loaded ~= nil then return loaded end
loaded = {sections = {}, byId = {}, indexOf = {}, aliases = {}}
if XMLFile == nil or ADSmartPickup == nil or ADSmartPickup.dir == nil then return loaded end
local lang = (g_languageShort == "da") and "da" or "en"
local path = ADSmartPickup.dir .. "help/help_" .. lang .. ".xml"
if fileExists ~= nil and not fileExists(path) then path = ADSmartPickup.dir .. "help/help_en.xml" end
local xml = XMLFile.load("spuHelp", path)
if xml == nil then
Logging.warning("ADSmartPickup: hjælpen kunne ikke indlæses (%s)", tostring(path))
return loaded
end
local ok, err = pcall(function()
xml:iterate("help.section", function(_, key)
local section = {id = xml:getString(key .. "#id"), level = xml:getInt(key .. "#level") or 3,
title = xml:getString(key .. "#title") or "", paragraphs = readParagraphs(xml, key)}
table.insert(loaded.sections, section)
loaded.byId[section.id] = section
loaded.indexOf[section.id] = #loaded.sections
end)
xml:iterate("help.alias", function(_, key)
local id = xml:getString(key .. "#id")
if id ~= nil then
loaded.aliases[id] = {id = id, ref = xml:getString(key .. "#ref"), title = xml:getString(key .. "#title"),
paragraphs = readParagraphs(xml, key)}
end
end)
end)
xml:delete()
if not ok then
-- halvt indlæst hjælp er værre end ingen: tom, og en advarsel (review 20/10)
Logging.warning("ADSmartPickup: hjælpen fejlede under indlæsning: %s", tostring(err))
loaded = {sections = {}, byId = {}, indexOf = {}, aliases = {}}
end
return loaded
end