refactor: big restructuring of the plugin

- decouple org file and headline search
- clearer dependency structure
- access orgmode only through one wrapper module
- use telescope concepts in module names
- unify initialization of a picker

Author: seflue

lua/telescope-orgmode/actions.lua

@@ -0,0 +1,111 @@
+local finders = require('telescope-orgmode.finders')
+local org = require('telescope-orgmode.org')
+
+local actions = require('telescope.actions')
+local action_state = require('telescope.actions.state')
+local state = require('telescope.state')
+
+local M = {}
+
+function M.toggle_headlines_orgfiles(opts)
+  return function(prompt_bufnr)
+    local status = state.get_status(prompt_bufnr)
+
+    -- _ot_ is used as our plugin-specific namespace in the action status
+    -- (ot - orgmode telescope)
+    --
+    -- FIXME: the state get's sometimes nil when the initalization has already been run
+    -- In this case, a toggle is "dropped" (keypress does not change the state).
+    -- Can we avoid that by initializing the state in the higher order function?
+    -- Idea: We can try to do it as before, but pass the prompt_bufnr with the opts.
+    if status._ot_state == nil then
+      -- uninitialized state - initialize with orgfiles
+      -- Because when this function is called the first time, it is triggered
+      -- by the users and we search over headlines by default, we set the state
+      -- for the first toggle already here.
+      status._ot_state = { current = opts.states[2], next = opts.states[1] }
+    else
+      status._ot_state.current, status._ot_state.next = status._ot_state.next, status._ot_state.current
+    end
+
+    if status._ot_state.current == 'headlines' then
+      M._find_headlines(opts, prompt_bufnr)
+    elseif status._ot_state.current == 'orgfiles' then
+      M._find_orgfiles(opts, prompt_bufnr)
+    else
+      -- this should not happen
+      error(string.format('Invalid state %s', status._ot_state.current))
+    end
+  end
+end
+
+function M.search_headlines(opts)
+  return function(prompt_bufnr)
+    M._find_headlines(opts, prompt_bufnr)
+  end
+end
+
+function M.search_orgfiles(opts)
+  return function(prompt_bufnr)
+    M._find_orgfiles(opts, prompt_bufnr)
+  end
+end
+
+function M.refile(closest_headline)
+  return function(prompt_bufnr)
+    local entry = action_state.get_selected_entry()
+    actions.close(prompt_bufnr)
+
+    -- Refile to the file by default
+    local destination = entry.value.file
+
+    -- Refile to a specific heading if is set
+    if entry.value.headline then
+      destination = entry.value.headline
+    end
+
+    return org.refile({
+      source = closest_headline,
+      destination = destination,
+    })
+  end
+end
+
+function M.insert(_)
+  return function(prompt_bufnr)
+    actions.close(prompt_bufnr)
+
+    ---@type MatchEntry
+    local entry = action_state.get_selected_entry()
+
+    -- Link to the filename by default
+    local destination = entry.value.file.filename
+
+    -- Link to a specific heading if is set
+    if entry.value.headline then
+      destination = 'file:' .. entry.value.file.filename .. '::*' .. entry.value.headline.title
+    end
+
+    org.insert_link(destination)
+    return true
+  end
+end
+
+function M._find_headlines(opts, prompt_bufnr)
+  local headlines = finders.headlines(opts)
+  M._update_picker(headlines, opts.prompt_titles.headlines, prompt_bufnr)
+end
+
+function M._find_orgfiles(opts, prompt_bufnr)
+  local orgfiles = finders.orgfiles(opts)
+  M._update_picker(orgfiles, opts.prompt_titles.orgfiles, prompt_bufnr)
+end
+
+function M._update_picker(results, title, prompt_bufnr)
+  local current_picker = action_state.get_current_picker(prompt_bufnr)
+
+  current_picker.layout.prompt.border:change_title(title)
+  current_picker:refresh(results)
+end
+
+return M

lua/telescope-orgmode/config.lua

@@ -8,4 +8,14 @@ function M.setup(ext_opts)
   M.opts = vim.tbl_extend('force', M.opts, ext_opts or {})
 end
 
+function M.init_opts(opts, prompt_titles)
+  opts = vim.tbl_extend('force', M.opts, opts or {})
+  opts.prompt_titles = prompt_titles
+  opts.states = {}
+  for state, _ in pairs(prompt_titles) do
+    table.insert(opts.states, state)
+  end
+  return opts
+end
+
 return M

lua/telescope-orgmode/entry_maker/headlines.lua

@@ -0,0 +1,79 @@
+require('telescope-orgmode.typehints')
+local org = require('telescope-orgmode.org')
+local entry_display = require('telescope.pickers.entry_display')
+
+---@class OrgHeadlineEntry
+---@field file OrgApiFile
+---@field filename string
+---@field headline OrgApiHeadline
+
+---@param file_results { file: OrgApiFile, filename: string }[]
+---@return OrgHeadlineEntry[]
+local function index_headlines(file_results, opts)
+  local results = {}
+  for _, file_entry in ipairs(file_results) do
+    for _, headline in ipairs(file_entry.file.headlines) do
+      local allowed_depth = opts.max_depth == nil or headline.level <= opts.max_depth
+      local allowed_archive = opts.archived or not headline.is_archived
+      if allowed_depth and allowed_archive then
+        local entry = {
+          file = file_entry.file,
+          filename = file_entry.filename,
+          headline = headline,
+          title = nil,
+        }
+        table.insert(results, entry)
+      end
+    end
+  end
+
+  return results
+end
+
+local M = {}
+---Fetches entrys from OrgApi and extracts the relevant information
+---@param opts any
+---@return OrgHeadlineEntry[]
+M.get_entries = function(opts)
+  return index_headlines(org.load_files(opts), opts)
+end
+
+---Entry-Maker for Telescope
+---@param opts any
+---@return fun(entry: OrgHeadlineEntry):MatchEntry
+M.make_entry = function(opts)
+  local displayer = entry_display.create({
+    separator = ' ',
+    items = {
+      { width = vim.F.if_nil(opts.location_width, 20) },
+      { remaining = true },
+    },
+  })
+
+  ---@param entry MatchEntry
+  local function make_display(entry)
+    return displayer({ entry.location, entry.tags .. ' ' .. entry.line })
+  end
+
+  return function(entry)
+    local headline = entry.headline
+    local lnum = headline.position.start_line
+    local location = string.format('%s:%i', vim.fn.fnamemodify(entry.filename, ':t'), lnum)
+    local line = string.format('%s %s', string.rep('*', headline.level), headline.title)
+    local tags = table.concat(headline.all_tags, ':')
+    local ordinal = tags .. ' ' .. line .. ' ' .. location
+
+    return {
+      value = entry,
+      ordinal = ordinal,
+      filename = entry.filename,
+      lnum = lnum,
+      display = make_display,
+      location = location,
+      line = line,
+      tags = tags,
+    }
+  end
+end
+
+return M

lua/telescope-orgmode/entry_maker/orgfiles.lua

@@ -0,0 +1,71 @@
+require('telescope-orgmode.typehints')
+local org = require('telescope-orgmode.org')
+local entry_display = require('telescope.pickers.entry_display')
+
+local M = {}
+
+---@class OrgFileEntry
+---@field file OrgApiFile
+---@field filename string
+---@field title string?
+
+---@param file_results { file: OrgApiFile, filename: string }[]
+---@return OrgFileEntry[]
+local function index_orgfiles(file_results)
+  local results = {}
+  for _, file_entry in ipairs(file_results) do
+    local entry = {
+      file = file_entry.file,
+      filename = file_entry.filename,
+      -- not beautiful to access a private property, but this is the only way to get the title
+      ---@diagnostic disable-next-line: invisible, undefined-field
+      title = file_entry.file._file:get_directive('TITLE') or nil,
+      headline = nil,
+    }
+    table.insert(results, entry)
+  end
+  return results
+end
+
+---Fetches entrys from OrgApi and extracts the relevant information
+---@param opts any
+---@return OrgFileEntry[]
+M.get_entries = function(opts)
+  return index_orgfiles(org.load_files(opts))
+end
+
+---Entry-Maker for Telescope
+---@return fun(entry: OrgFileEntry):MatchEntry
+M.make_entry = function()
+  local orgfile_displayer = entry_display.create({
+    separator = ' ',
+    items = {
+      { remaining = true },
+    },
+  })
+
+  ---@param entry MatchEntry
+  local function make_display(entry)
+    return orgfile_displayer({ entry.line })
+  end
+
+  return function(entry)
+    local lnum = nil
+    local location = vim.fn.fnamemodify(entry.filename, ':t')
+    local line = entry.title or location
+    local tags = ''
+    local ordinal = line
+
+    return {
+      value = entry,
+      ordinal = ordinal,
+      filename = entry.filename,
+      lnum = lnum,
+      display = make_display,
+      location = location,
+      line = line,
+      tags = tags,
+    }
+  end
+end
+return M

lua/telescope-orgmode/finders.lua

@@ -0,0 +1,22 @@
+local headlines = require('telescope-orgmode.entry_maker.headlines')
+local orgfiles = require('telescope-orgmode.entry_maker.orgfiles')
+
+local finders = require('telescope.finders')
+
+local M = {}
+
+function M.headlines(opts)
+  return finders.new_table({
+    results = headlines.get_entries(opts),
+    entry_maker = opts.entry_maker or headlines.make_entry(opts),
+  })
+end
+
+function M.orgfiles(opts)
+  return finders.new_table({
+    results = orgfiles.get_entries(opts),
+    entry_maker = opts.entry_maker or orgfiles.make_entry(),
+  })
+end
+
+return M

lua/telescope-orgmode/init.lua

@@ -1,6 +1,6 @@
 return {
   setup = require('telescope-orgmode.config').setup,
-  refile_heading = require('telescope-orgmode.refile_heading'),
-  search_headings = require('telescope-orgmode.search_headings'),
-  insert_link = require('telescope-orgmode.insert_link'),
+  refile_heading = require('telescope-orgmode.picker.refile_heading'),
+  search_headings = require('telescope-orgmode.picker.search_headings'),
+  insert_link = require('telescope-orgmode.picker.insert_link'),
 }