2020-04-10 09:27:53 +00:00
|
|
|
--- Provides an API to read help files.
|
|
|
|
--
|
|
|
|
-- @module help
|
|
|
|
|
2019-07-27 10:34:36 +00:00
|
|
|
local expect = dofile("rom/modules/main/cc/expect.lua").expect
|
2017-05-01 13:32:39 +00:00
|
|
|
|
|
|
|
local sPath = "/rom/help"
|
|
|
|
|
2020-04-10 09:27:53 +00:00
|
|
|
--- Returns a colon-separated list of directories where help files are searched
|
|
|
|
-- for. All directories are absolute.
|
|
|
|
--
|
|
|
|
-- @treturn string The current help search path, separated by colons.
|
|
|
|
-- @see help.setPath
|
2017-05-01 13:32:39 +00:00
|
|
|
function path()
|
2018-12-17 17:22:15 +00:00
|
|
|
return sPath
|
2017-05-01 13:32:39 +00:00
|
|
|
end
|
|
|
|
|
2020-04-10 09:27:53 +00:00
|
|
|
--- Sets the colon-seperated list of directories where help files are searched
|
|
|
|
-- for to `newPath`
|
|
|
|
--
|
|
|
|
-- @tparam string newPath The new path to use.
|
|
|
|
-- @usage help.setPath( "/disk/help/" )
|
|
|
|
-- @usage help.setPath( help.path() .. ":/myfolder/help/" )
|
|
|
|
-- @see help.path
|
2020-04-18 09:09:40 +00:00
|
|
|
function setPath(_sPath)
|
2019-05-30 18:36:28 +00:00
|
|
|
expect(1, _sPath, "string")
|
2018-12-17 17:22:15 +00:00
|
|
|
sPath = _sPath
|
2017-05-01 13:32:39 +00:00
|
|
|
end
|
|
|
|
|
2020-04-10 09:27:53 +00:00
|
|
|
--- Returns the location of the help file for the given topic.
|
|
|
|
--
|
|
|
|
-- @tparam string topic The topic to find
|
|
|
|
-- @treturn string|nil The path to the given topic's help file, or `nil` if it
|
|
|
|
-- cannot be found.
|
2020-11-12 19:40:18 +00:00
|
|
|
-- @usage help.lookup("disk")
|
2020-04-18 09:09:40 +00:00
|
|
|
function lookup(_sTopic)
|
2019-05-30 18:36:28 +00:00
|
|
|
expect(1, _sTopic, "string")
|
|
|
|
-- Look on the path variable
|
2017-05-01 13:32:39 +00:00
|
|
|
for sPath in string.gmatch(sPath, "[^:]+") do
|
2020-04-18 09:09:40 +00:00
|
|
|
sPath = fs.combine(sPath, _sTopic)
|
|
|
|
if fs.exists(sPath) and not fs.isDir(sPath) then
|
2018-12-17 17:22:15 +00:00
|
|
|
return sPath
|
2020-04-18 09:09:40 +00:00
|
|
|
elseif fs.exists(sPath .. ".txt") and not fs.isDir(sPath .. ".txt") then
|
2019-12-07 10:33:47 +00:00
|
|
|
return sPath .. ".txt"
|
2018-12-17 17:22:15 +00:00
|
|
|
end
|
2017-05-01 13:32:39 +00:00
|
|
|
end
|
2018-12-17 17:22:15 +00:00
|
|
|
|
|
|
|
-- Not found
|
|
|
|
return nil
|
2017-05-01 13:32:39 +00:00
|
|
|
end
|
|
|
|
|
2020-04-10 09:27:53 +00:00
|
|
|
--- Returns a list of topics that can be looked up and/or displayed.
|
|
|
|
--
|
|
|
|
-- @treturn table A list of topics in alphabetical order.
|
2020-11-12 19:40:18 +00:00
|
|
|
-- @usage help.topics()
|
2017-05-01 13:32:39 +00:00
|
|
|
function topics()
|
|
|
|
-- Add index
|
2018-12-17 17:22:15 +00:00
|
|
|
local tItems = {
|
2020-04-18 09:09:40 +00:00
|
|
|
["index"] = true,
|
2018-12-17 17:22:15 +00:00
|
|
|
}
|
|
|
|
|
|
|
|
-- Add topics from the path
|
2017-05-01 13:32:39 +00:00
|
|
|
for sPath in string.gmatch(sPath, "[^:]+") do
|
2020-04-18 09:09:40 +00:00
|
|
|
if fs.isDir(sPath) then
|
|
|
|
local tList = fs.list(sPath)
|
|
|
|
for _, sFile in pairs(tList) do
|
|
|
|
if string.sub(sFile, 1, 1) ~= "." then
|
|
|
|
if not fs.isDir(fs.combine(sPath, sFile)) then
|
2017-05-20 10:20:27 +00:00
|
|
|
if #sFile > 4 and sFile:sub(-4) == ".txt" then
|
2019-12-07 10:33:47 +00:00
|
|
|
sFile = sFile:sub(1, -5)
|
2017-05-20 10:20:27 +00:00
|
|
|
end
|
2020-04-18 09:09:40 +00:00
|
|
|
tItems[sFile] = true
|
2018-12-17 17:22:15 +00:00
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
2017-05-01 13:32:39 +00:00
|
|
|
|
2018-12-17 17:22:15 +00:00
|
|
|
-- Sort and return
|
|
|
|
local tItemList = {}
|
2020-04-18 09:09:40 +00:00
|
|
|
for sItem in pairs(tItems) do
|
|
|
|
table.insert(tItemList, sItem)
|
2018-12-17 17:22:15 +00:00
|
|
|
end
|
2020-04-18 09:09:40 +00:00
|
|
|
table.sort(tItemList)
|
2018-12-17 17:22:15 +00:00
|
|
|
return tItemList
|
2017-05-01 13:32:39 +00:00
|
|
|
end
|
|
|
|
|
2020-04-10 09:27:53 +00:00
|
|
|
--- Returns a list of topic endings that match the prefix. Can be used with
|
|
|
|
-- `read` to allow input of a help topic.
|
|
|
|
--
|
|
|
|
-- @tparam string prefix The prefix to match
|
|
|
|
-- @treturn table A list of matching topics.
|
2020-04-18 09:09:40 +00:00
|
|
|
function completeTopic(sText)
|
2019-05-30 18:36:28 +00:00
|
|
|
expect(1, sText, "string")
|
2017-05-01 13:32:39 +00:00
|
|
|
local tTopics = topics()
|
|
|
|
local tResults = {}
|
2019-12-07 10:33:47 +00:00
|
|
|
for n = 1, #tTopics do
|
2017-05-01 13:32:39 +00:00
|
|
|
local sTopic = tTopics[n]
|
2020-04-18 09:09:40 +00:00
|
|
|
if #sTopic > #sText and string.sub(sTopic, 1, #sText) == sText then
|
|
|
|
table.insert(tResults, string.sub(sTopic, #sText + 1))
|
2017-05-01 13:32:39 +00:00
|
|
|
end
|
|
|
|
end
|
2018-12-17 17:22:15 +00:00
|
|
|
return tResults
|
2017-05-01 13:32:39 +00:00
|
|
|
end
|