feat: manualen i spillet — (?)-hjælp pr. række, Hjælp-knap, indhold og søgning
This commit is contained in:
@@ -0,0 +1,151 @@
|
||||
-- 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
|
||||
Reference in New Issue
Block a user