feat(capture): have headline in templates take a string or a function that returns a string. (#1133)

Co-authored-by: Alec Stewart <alec-stewart@pm.me>

Author: alecStewart1

docs/configuration.org

@@ -916,9 +916,10 @@ Templates have the following fields:
 - =target= (=string?=) --- name of the file to which the capture content
   will be added. If the target is not specified, the content will be
   added to the [[#org_default_notes_file][org_default_notes_file]] file
-- =headline= (=string?=) --- title of the headline after which the
-  capture content will be added. If no headline is specified, the
-  content will be appended to the end of the file
+- =headline= (=string|fun():string?=) --- title of the headline after which the
+  capture content will be added. If a function is provided, it will be called during
+  refile and must return the headline title as string. If no headline is specified,
+  the content will be appended to the end of the file
 - =datetree (boolean | { time_prompt?: boolean, reversed?: boolean, tree_type: 'day' | 'month' | 'week' | 'custom' })=
   Create a [[https://orgmode.org/manual/Template-elements.html#FOOT84][date tree]] with current day in the target file and put the capture content there.
   - =true= - Create ascending datetree (newer dates go to end) with the current date

lua/orgmode/capture/init.lua

@@ -587,9 +587,23 @@ function Capture:_get_refile_vars(capture_window)
 
   opts.destination_file = self.files:get(file)
   if opts.template.headline then
-    opts.destination_headline = opts.destination_file:find_headline_by_title(opts.template.headline)
+    local template_headline = opts.template.headline
+    if type(template_headline) == 'function' then
+      local ok, resolved_headline = pcall(template_headline)
+      if not ok then
+        utils.echo_error('Failed to resolve capture template headline')
+        return false
+      end
+      template_headline = resolved_headline
+    end
+    if type(template_headline) ~= 'string' then
+      utils.echo_error('Capture template headline function must return a string')
+      return false
+    end
+
+    opts.destination_headline = opts.destination_file:find_headline_by_title(template_headline)
     if not opts.destination_headline then
-      utils.echo_error(('Refile headline "%s" does not exist in "%s"'):format(opts.template.headline, file))
+      utils.echo_error(('Refile headline "%s" does not exist in "%s"'):format(template_headline, file))
       return false
     end
   end

lua/orgmode/capture/template/init.lua

@@ -83,7 +83,7 @@ local expansions = {
 ---@field template? string|string[]
 ---@field target? string
 ---@field datetree? OrgCaptureTemplateDatetree
----@field headline? string
+---@field headline? string|fun():string
 ---@field regexp? string
 ---@field properties? OrgCaptureTemplateProperties
 ---@field subtemplates? table<string, OrgCaptureTemplate>
@@ -102,7 +102,7 @@ function Template:new(opts)
   vim.validate('template', opts.template, { 'string', 'table' }, true)
   vim.validate('target', opts.target, 'string', true)
   vim.validate('regexp', opts.regexp, 'string', true)
-  vim.validate('headline', opts.headline, 'string', true)
+  vim.validate('headline', opts.headline, { 'string', 'function' }, true)
   vim.validate('properties', opts.properties, 'table', true)
   vim.validate('subtemplates', opts.subtemplates, 'table', true)
   vim.validate('datetree', opts.datetree, { 'boolean', 'table' }, true)

tests/plenary/capture/capture_spec.lua

@@ -380,4 +380,44 @@ describe('Capture', function()
       '* barbar',
     }, vim.api.nvim_buf_get_lines(0, 0, -1, false))
   end)
+
+  it('resolves function headline in template', function()
+    local destination_file = helpers.create_file({
+      '* dynamic title',
+      '* barbar',
+    })
+
+    local capture_file = helpers.create_file({ '* baz' })
+    local item = capture_file:get_headlines()[1]
+    local template = Template:new({
+      target = destination_file.filename,
+      headline = function()
+        return 'dynamic title'
+      end,
+    })
+    local capture_window = CaptureWindow:new({ template = template })
+    ---@diagnostic disable-next-line: invisible
+    capture_window._bufnr = capture_file:bufnr()
+
+    ---@diagnostic disable-next-line: invisible
+    local opts = org.capture:_get_refile_vars(capture_window)
+    assert.are.same(destination_file.filename, opts.destination_file.filename)
+    assert.are.same('dynamic title', opts.destination_headline:get_title())
+
+    ---@diagnostic disable-next-line: invisible
+    org.capture:_refile_from_capture_buffer({
+      destination_file = destination_file,
+      source_file = capture_file,
+      source_headline = item,
+      destination_headline = opts.destination_headline,
+      template = template,
+      capture_window = capture_window,
+    })
+    vim.cmd('edit ' .. vim.fn.fnameescape(destination_file.filename))
+    assert.are.same({
+      '* dynamic title',
+      '** baz',
+      '* barbar',
+    }, vim.api.nvim_buf_get_lines(0, 0, -1, false))
+  end)
 end)