local default_long_help = DEFAULT_HELP_TEMPLATE:format(

entry_name, ('='):rep(#entry_name))

return {

help_source=help_source,

short_help='No help available.',

long_help=default_long_help,

tags={},

source_timestamp=kwargs.source_timestamp or 0,

source_path=kwargs.source_path}

opts = opts or {}

local lines, tags = {}, ''

local first_line_is_short_help = opts.first_line_is_short_help

local begin_marker_found,header_found = not opts.begin_marker,opts.no_header

local tags_found, short_help_found = false, opts.skip_short_help

local in_tags, in_short_help = false, false

for line in iterator do

line = dfhack.utf2df(line)

if not short_help_found and first_line_is_short_help then

line = line:trim()

local _,_,text = line:find('^'..first_line_is_short_help..'%s*(.*)')

if not text then

-- if no first-line short help found, fall back to getting the

-- first sentence of the help text.

first_line_is_short_help = false

else

if not text:endswith('.') then

text = text .. '.'

end

entry.short_help = text

short_help_found = true

goto continue

end

end

if not begin_marker_found then

local _, endpos = line:find(opts.begin_marker, 1, true)

if endpos == #line then

begin_marker_found = true

end

goto continue

end

if opts.end_marker then

local _, endpos = line:find(opts.end_marker, 1, true)

if endpos == #line then

break

end

end

if not header_found and line:find('%w') then

header_found = true

elseif in_tags then

if #line == 0 then

in_tags = false

else

tags = tags .. line

end

elseif not tags_found and line:find('^[*]*Tags:[*]*') then

_,_,tags = line:trim():find('[*]*Tags:[*]* *(.*)')

in_tags, tags_found = true, true

elseif not short_help_found and

line:find('^%s*%w') and not line:find('^%w+:') then

if in_short_help then

entry.short_help = entry.short_help .. ' ' .. line

else

entry.short_help = line:trim()

end

local sentence_end = entry.short_help:find('.', 1, true)

if sentence_end then

entry.short_help = entry.short_help:sub(1, sentence_end)

short_help_found = true

else

in_short_help = true

end

end

table.insert(lines, line)

::continue::

end

entry.tags = {}

for _,tag in ipairs(tags:split('[ ,|]+')) do

if #tag > 0 and tag_index[tag] then

entry.tags[tag] = true

end

end

if #lines > 0 then

entry.long_help = table.concat(lines, '\n')

end

local source_path = get_rendered_path(entry_name)

local source_timestamp = dfhack.filesystem.mtime(source_path)

if old_entry and old_entry.help_source == HELP_SOURCES.RENDERED and

old_entry.source_timestamp >= source_timestamp then

-- we already have the latest info

return old_entry

end

kwargs.source_path, kwargs.source_timestamp = source_path, source_timestamp

local entry = make_default_entry(entry_name, HELP_SOURCES.RENDERED, kwargs)

local ok, lines = pcall(io.lines, source_path)

if not ok then

return entry

end

update_entry(entry, lines)

return entry

if old_entry and old_entry.source == HELP_SOURCES.PLUGIN then

-- we can't tell when a plugin is reloaded, so we can either choose to

-- always refresh or never refresh. let's go with never for now for

-- performance.

return old_entry

end

local entry = make_default_entry(entry_name, HELP_SOURCES.PLUGIN, kwargs)

local long_help = dfhack.internal.getCommandHelp(entry_name)

if long_help and #long_help:trim() > 0 then

update_entry(entry, long_help:trim():gmatch('[^\n]*'), {no_header=true})

end

return entry

local source_path = kwargs.source_path

local source_timestamp = dfhack.filesystem.mtime(source_path)

if old_entry and old_entry.source == HELP_SOURCES.SCRIPT and

old_entry.source_path == source_path and

old_entry.source_timestamp >= source_timestamp then

-- we already have the latest info

return old_entry

end

kwargs.source_timestamp, kwargs.entry_type = source_timestamp

local entry = make_default_entry(entry_name, HELP_SOURCES.SCRIPT, kwargs)

local ok, lines = pcall(io.lines, source_path)

if not ok then

return entry

end

update_entry(entry, lines,

{begin_marker=SCRIPT_DOC_BEGIN,

end_marker=SCRIPT_DOC_END,

first_line_is_short_help='%-%-'})

return entry

if entrydb[entry_name] then

-- already in db (e.g. from a higher-priority script dir); skip

return

end

entrydb[entry_name] = {

entry_types=kwargs.entry_types,

short_help=kwargs.short_help,

text_entry=text_entry

}

if entry_name ~= text_entry then

return

end

local text_entry, old_entry = nil, old_db[entry_name]

if help_source == HELP_SOURCES.RENDERED then

text_entry = make_rendered_entry(old_entry, entry_name, kwargs)

elseif help_source == HELP_SOURCES.PLUGIN then

text_entry = make_plugin_entry(old_entry, entry_name, kwargs)

elseif help_source == HELP_SOURCES.SCRIPT then

text_entry = make_script_entry(old_entry, entry_name, kwargs)

elseif help_source == HELP_SOURCES.STUB then

text_entry = make_default_entry(entry_name, HELP_SOURCES.STUB, kwargs)

else

error('unhandled help source: ' .. help_source)

end

textdb[entry_name] = text_entry

local entry_types = {[ENTRY_TYPES.BUILTIN]=true, [ENTRY_TYPES.COMMAND]=true}

for builtin,canonical in pairs(BUILTINS) do

if canonical == true then canonical = builtin end

update_db(old_db, builtin, canonical,

has_rendered_help(canonical) and

HELP_SOURCES.RENDERED or HELP_SOURCES.STUB,

{entry_types=entry_types})

end

-- easter egg: replace underline for 'die' help with tombstones

textdb.die.long_help = textdb.die.long_help:gsub('=', string.char(239))

local plugin_names = dfhack.internal.listPlugins()

for _,plugin in ipairs(plugin_names) do

local commands = dfhack.internal.listCommands(plugin)

local includes_plugin = false

for _,command in ipairs(commands) do

local kwargs = {entry_types={[ENTRY_TYPES.COMMAND]=true}}

if command == plugin then

kwargs.entry_types[ENTRY_TYPES.PLUGIN]=true

includes_plugin = true

end

kwargs.short_help = dfhack.internal.getCommandDescription(command)

update_db(old_db, command, plugin,

has_rendered_help(plugin) and

HELP_SOURCES.RENDERED or HELP_SOURCES.PLUGIN,

kwargs)

end

if not includes_plugin then

update_db(old_db, plugin, plugin,

has_rendered_help(plugin) and

HELP_SOURCES.RENDERED or HELP_SOURCES.STUB,

{entry_types={[ENTRY_TYPES.PLUGIN]=true}})

end

end

local entry_types = {[ENTRY_TYPES.COMMAND]=true}

for _,script_path in ipairs(dfhack.internal.getScriptPaths()) do

local files = dfhack.filesystem.listdir_recursive(

script_path, nil, false)

if not files then goto skip_path end

for _,f in ipairs(files) do

if f.isdir or

not f.path:endswith('.lua') or

f.path:startswith('test/') or

f.path:startswith('internal/') then

goto continue

end

local dot_index = f.path:find('%.[^.]*$')

local entry_name = f.path:sub(1, dot_index - 1)

local source_path = script_path .. '/' .. f.path

update_db(old_db, entry_name, entry_name,

has_rendered_help(entry_name) and

HELP_SOURCES.RENDERED or HELP_SOURCES.SCRIPT,

{entry_types=entry_types, source_path=source_path})

::continue::

end

::skip_path::

end

local tag, desc, in_desc = nil, nil, false

local ok, lines = pcall(io.lines, TAG_DEFINITIONS)

if not ok then return end

for line in lines do

if in_desc then

line = line:trim()

if #line == 0 then

in_desc = false

goto continue

end

desc = desc .. ' ' .. line

tag_index[tag].description = desc

else

_,_,tag,desc = line:find('^%* (%w+)[^:]*: (.+)')

if not tag then goto continue end

tag_index[tag] = {description=desc}

in_desc = true

end

::continue::

end

for entry_name,entry in pairs(entrydb) do

for tag in pairs(textdb[entry.text_entry].tags) do

-- ignore unknown tags

if tag_index[tag] then

table.insert(tag_index[tag], entry_name)

end

end

end

if not needs_refresh then return end

needs_refresh = false

local old_db = textdb

textdb, entrydb, tag_index = {}, {}, {}

initialize_tags()

scan_builtins(old_db)

scan_plugins(old_db)

scan_scripts(old_db)

index_tags()

if is_tag('armok') then

dfhack.internal.setArmokTools(get_tag_data('armok'))

end

local blocks = {}

for line in text:gmatch('[^\n]*') do

local _,indent = line:find('^ *')

table.insert(blocks, {line=line:trim(), indent=indent})

end

return blocks

local wrapped = line:wrap(width - indent)

if indent == 0 then return wrapped end

local padding = (' '):rep(indent)

local indented_lines = {}

for line in wrapped:gmatch('[^\n]*') do

table.insert(indented_lines, padding .. line)

end

return table.concat(indented_lines, '\n')

local formatted_blocks = {}

for _,block in ipairs(parse_blocks(text)) do

table.insert(formatted_blocks,

format_block(block.line, block.indent, width))

end

return table.concat(formatted_blocks, '\n')

if not l or #l == 0 then return nil end

if type(l) == 'string' then

return {l}

end

return l

if not str or #str == 0 then

return false

end

for _,s in ipairs(normalize_string_list(str)) do

if not dict[s] then

return false

end

end

return true

ensure_db()

if not entrydb[entry_name] then

error(('helpdb entry not found: "%s"'):format(entry_name))

end

return entrydb[entry_name][property] or

textdb[entrydb[entry_name].text_entry][property]

local list = {}

for item in pairs(set) do

table.insert(list, item)

end

table.sort(list)

return list

ensure_db()

if not tag_index[tag] then

error(('helpdb tag not found: "%s"'):format(tag))

end

return tag_index[tag]

local parts = str:split('/')

local chunks = {}

for i=1,#parts do

chunks[#parts - i + 1] = parts[i]

end

return chunks

local a = chunk_for_sorting(a)

local b = chunk_for_sorting(b)

local i = 1

while a[i] do

if not b[i] then

return true

end

if a[i] ~= b[i] then

return a[i] < b[i]

end

i = i + 1

end

return false

if filter.tag then

local matched = false

local tags = get_db_property(entry_name, 'tags')

for _,tag in ipairs(filter.tag) do

if tags[tag] then

matched = true

break

end

end

if not matched then

return false

end

end

if filter.entry_type then

local matched = false

local etypes = get_db_property(entry_name, 'entry_types')

for _,etype in ipairs(filter.entry_type) do

if etypes[etype] then

matched = true

break

end

end

if not matched then

return false

end

end

if filter.str then

local matched = false

for _,str in ipairs(filter.str) do

if entry_name:find(str, 1, true) then

matched = true

break

end

end

if not matched then

return false

end

end

return true

for _,filter in ipairs(filters) do

if not matches(entry_name, filter) then

return false

end

end

return true

if not f then return nil end

local filter = {}

filter.str = normalize_string_list(f.str)

filter.tag = normalize_string_list(f.tag)

filter.entry_type = normalize_string_list(f.entry_type)

if not filter.str and not filter.tag and not filter.entry_type then

return nil

end

return filter

if not fs then return nil end

local filter_list = {}

for _,f in ipairs(#fs > 0 and fs or {fs}) do

table.insert(filter_list, normalize_filter_map(f))

end

if #filter_list == 0 then return nil end

return filter_list

ensure_db()

include = normalize_filter_list(include)

exclude = normalize_filter_list(exclude)

local entries = {}

for entry in pairs(entrydb) do

if (not include or matches_all(entry, include)) and

(not exclude or not matches_all(entry, exclude)) then

table.insert(entries, entry)

end

end

table.sort(entries, sort_by_basename)

return entries

ensure_db()

if not entrydb[entry] then

dfhack.printerr(('No help entry found for "%s"'):format(entry))

return

end

print(get_entry_long_help(entry))

col2text = col2text:wrap(COL2WIDTH)

local wrapped_col2 = {}

for line in col2text:gmatch('[^'..NEWLINE..']*') do

table.insert(wrapped_col2, line)

end

local col2_start_line = 1

if #col1text > COL1WIDTH then

print(col1text)

else

print(('%-'..COL1WIDTH..'s %s'):format(col1text, wrapped_col2[1]))

col2_start_line = 2

end

for i=col2_start_line,#wrapped_col2 do

print(('%'..COL1WIDTH..'s %s'):format(' ', wrapped_col2[i]))

end

local entries = search_entries(include, exclude)

for _,entry in ipairs(entries) do

local short_help = get_entry_short_help(entry)

if not skip_tags then

local tags = set_to_sorted_list(get_entry_tags(entry))

if #tags > 0 then

local taglist = table.concat(tags, ', ')

short_help = short_help .. NEWLINE .. 'tags: ' .. taglist

end

end

print_columns(entry, short_help)

end

if #entries == 0 then

print('No matches.')

end

local include = {entry_type={ENTRY_TYPES.COMMAND}}

if is_tag(filter_str) then

include.tag = filter_str

else

include.str = filter_str

end

local excludes = {}

if exclude_strs and #exclude_strs > 0 then

table.insert(excludes, {str=argparse.stringList(exclude_strs)})

end

if not show_dev_commands then

local dev_tags = {'dev', 'unavailable'}

if filter_str ~= 'armok' and dfhack.getMortalMode() then

table.insert(dev_tags, 'armok')

end

table.insert(excludes, {tag=dev_tags})

end

list_entries(skip_tags, include, excludes)

local tags = get_tags()

for _,tag in ipairs(tags) do

print_columns(tag, get_tag_data(tag).description)

end

if tag and #tag > 0 and not is_tag(tag) then

dfhack.printerr(('unrecognized tag: "%s"'):format(tag))

end

if not is_tag(tag) then

list_tags()

return

end

local skip_tags = true

local include = {entry_type={ENTRY_TYPES.COMMAND}, tag=tag}

local excludes = {tag={}}

if tag ~= 'unavailable' then

table.insert(excludes.tag, 'unavailable')

end

if tag ~= 'armok' and dfhack.getMortalMode() then

table.insert(excludes.tag, 'armok')

end

list_entries(skip_tags, include, excludes)