feat(attach): add ability to open attachments

This adds functions that correspond to these Emacs functions:

- `org-attach-reveal`
- `org-attach-reveal-in-emacs`
- `org-attach-open`
- `org-attach-open-in-emacs`

Author: broken-pen

docs/configuration.org

@@ -1245,6 +1245,16 @@ is copied due to the [[https://orgmode.org/manual/Attachment-defaults-and-dispat
 symlink itself. The default is to treat the symlink transparently as
 a directory.
 
+*** org_attach_visit_command
+:PROPERTIES:
+:CUSTOM_ID: org_attach_visit_command
+:END:
+- Type: =string|fun(path: string)=
+- Default: ='edit'=
+
+Command or function used to open a directory. The default opens NetRW if it
+is available.
+
 *** org_attach_use_inheritance
 :PROPERTIES:
 :CUSTOM_ID: org_attach_use_inheritance

lua/orgmode/attach/core.lua

@@ -401,4 +401,47 @@ function AttachCore:attach_new(node, name, opts)
   end)
 end
 
+---Open the attachments directory via `vim.ui.open()`.
+---
+---@param attach_dir string the directory to open
+---@return vim.SystemObj
+function AttachCore:reveal(attach_dir)
+  return assert(vim.ui.open(attach_dir))
+end
+
+---Open the attachments directory via `org_attach_visit_command`.
+---
+---@param attach_dir string the directory to open
+---@return nil
+function AttachCore:reveal_nvim(attach_dir)
+  local command = config.org_attach_visit_command or 'edit'
+  if type(command) == 'string' then
+    vim.cmd[command](attach_dir)
+  else
+    command(attach_dir)
+  end
+end
+
+---Open an attached file via `vim.ui.open()`.
+---
+---@param node OrgAttachNode
+---@param name string name of the file to open
+---@return vim.SystemObj
+function AttachCore:open(name, node)
+  local attach_dir = self:get_dir(node)
+  local path = vim.fs.joinpath(attach_dir, name)
+  return assert(vim.ui.open(path))
+end
+
+---Open an attached file via `:edit`.
+---
+---@param node OrgAttachNode
+---@param name string name of the file to open
+---@return nil
+function AttachCore:open_in_vim(name, node)
+  local attach_dir = self:get_dir(node)
+  local path = vim.fs.joinpath(attach_dir, name)
+  vim.cmd.edit(path)
+end
+
 return AttachCore

lua/orgmode/attach/init.lua

@@ -78,6 +78,35 @@ function Attach:prompt()
       return self:attach_new()
     end,
   })
+  menu:add_separator({ length = #menu.title })
+  menu:add_option({
+    label = 'Open an attachment externally.',
+    key = 'o',
+    action = function()
+      return self:open()
+    end,
+  })
+  menu:add_option({
+    label = 'Open an attachment in vim.',
+    key = 'O',
+    action = function()
+      return self:open_in_vim()
+    end,
+  })
+  menu:add_option({
+    label = 'Open the attachment directory externally.',
+    key = 'f',
+    action = function()
+      return self:reveal()
+    end,
+  })
+  menu:add_option({
+    label = 'Open the attachment directory in vim.',
+    key = 'F',
+    action = function()
+      return self:reveal_nvim()
+    end,
+  })
   menu:add_option({
     label = 'Set specific attachment directory for this task.',
     key = 's',
@@ -243,6 +272,8 @@ end
 
 ---@class orgmode.attach.attach.Options
 ---@inlinedoc
+---@field visit_dir? boolean if true, visit the directory subsequently using
+---                          `org_attach_visit_command`
 ---@field method? OrgAttachMethod The method via which to attach `file`;
 ---                               default is taken from `org_attach_method`
 ---@field node? OrgAttachNode
@@ -254,6 +285,7 @@ end
 ---@return string|nil attachment_name
 function Attach:attach(file, opts)
   local node = opts and opts.node or self.core:get_current_node()
+  local visit_dir = opts and opts.visit_dir or false
   local method = opts and opts.method or config.org_attach_method
   return Promise
     .resolve(file or Input.open('File to keep as an attachment: ', '', 'file'))
@@ -274,6 +306,10 @@ function Attach:attach(file, opts)
     :next(function(attachment_name)
       if attachment_name then
         utils.echo_info(('File %s is now an attachment'):format(attachment_name))
+        if visit_dir then
+          local attach_dir = self.core:get_dir(node)
+          self.core:reveal_nvim(attach_dir)
+        end
       end
       return attachment_name
     end)
@@ -282,6 +318,8 @@ end
 
 ---@class orgmode.attach.attach_buffer.Options
 ---@inlinedoc
+---@field visit_dir? boolean if true, visit the directory subsequently using
+---                          `org_attach_visit_command`
 ---@field node? OrgAttachNode
 
 ---Attach buffer's contents to current outline node.
@@ -293,6 +331,7 @@ end
 ---@return string|nil attachment_name
 function Attach:attach_buffer(buffer, opts)
   local node = opts and opts.node or self.core:get_current_node()
+  local visit_dir = opts and opts.visit_dir or false
   return Promise
     .resolve(buffer and ui.get_bufnr_verbose(buffer) or ui.select_buffer())
     ---@param bufnr? integer
@@ -321,6 +360,7 @@ end
 ---@return string|nil attachment_name
 function Attach:attach_many(files, opts)
   local node = opts and opts.node or self.core:get_current_node()
+  local visit_dir = opts and opts.visit_dir or false
   local method = opts and opts.method or config.org_attach_method
 
   return self.core
@@ -339,6 +379,10 @@ function Attach:attach_many(files, opts)
             and { { ('failed to attach %d file%s'):format(res.failures, plural(res.failures)), 'ErrorMsg' } }
           or nil
         utils.echo_info(msg, extra)
+        if res.successes > 0 and visit_dir then
+          local attach_dir = self.core:get_dir(node)
+          self.core:reveal_nvim(attach_dir)
+        end
       end
       return nil
     end)
@@ -422,4 +466,68 @@ function Attach:attach_lns(node)
   return self:attach(nil, { method = 'lns', node = node })
 end
 
+---Open the attachments directory via `vim.ui.open()`.
+---
+---@param attach_dir? string the directory to open
+---@return nil
+function Attach:reveal(attach_dir)
+  attach_dir = attach_dir or self:get_dir_or_create()
+  local res = self.core:reveal(attach_dir):wait()
+  if res.code ~= 0 then
+    error(('exit code %d for opening: %s'):format(res.code, attach_dir))
+  end
+end
+
+---Open the attachments directory via `org_attach_visit_command`.
+---
+---@param attach_dir? string the directory to open
+---@return nil
+function Attach:reveal_nvim(attach_dir)
+  attach_dir = attach_dir or self:get_dir_or_create()
+  return self.core:reveal_nvim(attach_dir)
+end
+
+---Open an attached file via `vim.ui.open()`.
+---
+---@param name? string name of the file to open
+---@param node? OrgAttachNode
+---@return nil
+function Attach:open(name, node)
+  node = node or self.core:get_current_node()
+  local attach_dir = self.core:get_dir(node)
+  ---@type vim.SystemObj?
+  local obj = Promise.resolve(name or ui.select_attachment('Open', attach_dir))
+    :next(function(chosen_name)
+      if not chosen_name then
+        return
+      end
+      return self.core:open(chosen_name, node)
+    end)
+    :wait(MAX_TIMEOUT)
+  if obj then
+    local res = obj:wait()
+    if res.code ~= 0 then
+      error(('exit code %d for command: %s'):format(res.code, obj.cmd))
+    end
+  end
+end
+
+---Open an attached file via `:edit`.
+---
+---@param name? string name of the file to open
+---@param node? OrgAttachNode
+---@return nil
+function Attach:open_in_vim(name, node)
+  node = node or self.core:get_current_node()
+  local attach_dir = self.core:get_dir(node)
+  return Promise.resolve(name or ui.select_attachment('Open', attach_dir))
+    :next(function(chosen_name)
+      if not chosen_name then
+        return
+      end
+      self.core:open_in_vim(chosen_name, node)
+    end)
+    :wait(MAX_TIMEOUT)
+end
+
 return Attach

lua/orgmode/attach/ui.lua

@@ -1,5 +1,6 @@
 local Input = require('orgmode.ui.input')
 local Promise = require('orgmode.utils.promise')
+local fileops = require('orgmode.attach.fileops')
 local utils = require('orgmode.utils')
 
 local M = {}
@@ -65,6 +66,113 @@ function M.ask_new_method()
   end)
 end
 
+---Helper for `make_completion()`.
+---
+---@param directory string
+---@param show_hidden? boolean
+---@return string[] file_names
+local function list_files(directory, show_hidden)
+  ---@param path string
+  ---@return string ftype
+  local function resolve_links(path)
+    local target = vim.uv.fs_realpath(path)
+    local stat = target and vim.uv.fs_stat(target)
+    return stat and stat.type or 'file'
+  end
+  local filter = show_hidden and function()
+    return true
+  end or function(name)
+    return not vim.startswith(name, '.') and not vim.endswith(name, '~')
+  end
+  local dirs = {}
+  local files = {}
+  fileops
+    .iterdir(directory)
+    :filter(filter)
+    :map(
+      ---@param name string
+      ---@param ftype string
+      ---@return string name
+      ---@return string ftype
+      function(name, ftype)
+        if ftype == 'link' then
+          ftype = resolve_links(vim.fs.joinpath(directory, name))
+        end
+        ---@diagnostic disable-next-line: redundant-return-value
+        return name, ftype
+      end
+    )
+    ---@param name string
+    ---@param ftype string
+    :each(function(name, ftype)
+      if ftype == 'directory' then
+        dirs[#dirs + 1] = name .. '/'
+      else
+        files[#files + 1] = name
+      end
+    end)
+  -- Ensure that directories are sorted before files.
+  table.sort(dirs)
+  table.sort(files)
+  return vim.list_extend(dirs, files)
+end
+
+---Return a completion function for attachments.
+---
+---@param root string the attachment directory
+---@param fuzzy? boolean if true, use `matchfuzzy()`
+---@return fun(arglead: string): string[]
+function M.make_completion(root, fuzzy)
+  ---@type fun(candidates:string[],basename:string[]):string[]
+  local matcher
+  if fuzzy then
+    matcher = function(candidates, basename)
+      -- Only call matchfuzzy() if it won't break.
+      if basename:len() <= 256 then
+        return vim.fn.matchfuzzy(candidates, basename)
+      end
+      return candidates
+    end
+  else
+    matcher = function(candidates, basename)
+      local pattern = '^' .. vim.pesc(basename)
+      return vim.tbl_filter(function(candidate)
+        return candidate:find(pattern) ~= nil
+      end, candidates)
+    end
+  end
+  ---@param arglead string
+  ---@return string[]
+  return function(arglead)
+    local dirname = vim.fs.dirname(arglead)
+    local searchdir = vim.fs.normalize(vim.fs.joinpath(root, dirname))
+    local basename = vim.fs.basename(arglead)
+    local show_hidden = vim.startswith(basename, '.')
+    local candidates = list_files(searchdir, show_hidden)
+    if basename ~= '' then
+      candidates = matcher(candidates, basename)
+    end
+    -- Don't prefix `./` to the paths.
+    if dirname ~= '.' then
+      candidates = vim.tbl_map(function(name)
+        return vim.fs.joinpath(dirname, name)
+      end, candidates)
+    end
+    return candidates
+  end
+end
+
+---Dialog that has user select an existing attachment file.
+---
+---Returns nil if the user cancels with `<Esc>`.
+---
+---@param action string
+---@param attach_dir string
+---@return OrgPromise<string> attach_file
+function M.select_attachment(action, attach_dir)
+  return Input.open(action .. ' attachment: ', '', M.make_completion(attach_dir, true))
+end
+
 ---Like `vim.fn.bufnr()`, but error instead of returning `-1`.
 ---
 ---@param buf integer | string

lua/orgmode/config/_meta.lua

@@ -255,6 +255,7 @@
 ---@field org_babel_default_header_args? table<string, string> Default header args for org-babel blocks: Default: { [':tangle'] = 'no', [':noweb'] = 'no' }
 ---@field org_attach_preferred_new_method 'id' | 'dir' | 'ask' | false If true, create attachments directory when necessary according to the given method. Default: 'id'
 ---@field org_attach_method 'mv' | 'cp' | 'ln' | 'lns' Default method of attacahing files. Default: 'cp'
+---@field org_attach_visit_command string | fun(dir: string) Command or Lua function used to open a directory. Default: 'edit'
 ---@field org_attach_use_inheritance 'always' | 'selective' | 'never' Determines whether headlines inherit the attachments directory of their parents. Default: 'selective'
 ---@field org_attach_id_to_path_function_list (string | fun(id: string): (string|nil))[] List of functions used to derive the attachments directory from an ID property.
 ---@field org_attach_sync_delete_empty_dir 'always' | 'ask' | 'never' Determines whether to delete empty directories when using `org.attach.sync()`. Default: 'ask'

lua/orgmode/config/defaults.lua

@@ -85,6 +85,7 @@ local DefaultConfig = {
   org_attach_preferred_new_method = 'id',
   org_attach_method = 'cp',
   org_attach_copy_directory_create_symlink = false,
+  org_attach_visit_command = 'edit',
   org_attach_use_inheritance = 'selective',
   org_attach_id_to_path_function_list = {
     'uuid_folder_format',