feat(attach): add attachment links

This provides functionality provided by the following functions in the
Emacs implementation:

- `org-attach-file-list`
- `org-attach-expand`
- `org-attach-follow`
- `org-attach-complete-link`

Author: broken-pen

docs/configuration.org

@@ -1207,16 +1207,31 @@ is available.
 
 Attachment inheritance for the outline.
 
-Enabling inheritance implies that running =attach= inside a node without
-attachments will operate on the first parent headline that has an
-attachment.
+Enabling inheritance implies two things:
+1. Attachment links will look through all parent headlines until they find
+   the linked attachment.
+2. Running =attach= inside a node without attachments will operate on the
+   first parent headline that has an attachment.
 
 Possible values are:
 
 - =always= - inherit attachments
 - =selective= - respect [[#org_use_property_inheritance][org_use_property_inheritance]] for the properties =DIR= and =ID=
 - =never= - don't inherit attachments
 
+*** org_attach_store_link_p
+:PROPERTIES:
+:CUSTOM_ID: org_attach_store_link_p
+:END:
+- Type: ='attached' | 'file' | 'original' | false=
+- Default: ='attached'=
+
+If not =false=, store a link with [[#org_store_link][org_store_link]] when attaching a file.
+
+- =attach= - store a =[[attachment:name]]= link
+- =file= - store a =[[file:attach_dir/name]]= link
+- =original= - store a =[[file:original/location]]= link
+
 *** org_attach_id_to_path_function_list
 :PROPERTIES:
 :CUSTOM_ID: org_attach_id_to_path_function_list
@@ -2944,6 +2959,14 @@ the =DIR= property. See also [[#org_attach_id_dir][org_attach_id_dir]],
 [[#org_attach_id_to_path_function_list][org_attach_id_to_path_function_list]] and [[#org_attach_use_inheritance][org_attach_use_inheritance]] on how
 to further customize the attachments directory.
 
+Attachment links are supported. A link like =[[attachment:file.txt]]=
+looks up =file.txt= in the current node's attachments directory and opens
+it. Attaching a file stores a link to the attachment. See
+[[#org_attach_store_link_p][org_attach_store_link_p]] on how to configure this behavior.
+
+The only missing feature is expansion of attachment links before exporting
+a file with [[#org_export][org_exporting]].
+
 ** User interface
 :PROPERTIES:
 :CUSTOM_ID: user-interface

lua/orgmode/attach/core.lua

@@ -6,13 +6,15 @@ local utils = require('orgmode.utils')
 
 ---@class OrgAttachCore
 ---@field files OrgFiles
+---@field links OrgLinks
 local AttachCore = {}
 AttachCore.__index = AttachCore
 
----@param opts {files:OrgFiles}
+---@param opts {files:OrgFiles, links:OrgLinks}
 function AttachCore.new(opts)
   local data = {
     files = opts and opts.files,
+    links = opts and opts.links,
   }
   return setmetatable(data, AttachCore)
 end
@@ -288,6 +290,8 @@ function AttachCore:attach(node, file, opts)
         return nil
       end
       node:add_auto_tag()
+      local link = self.links:store_link_to_attachment({ attach_dir = attach_dir, original = file })
+      vim.fn.setreg(vim.v.register, link)
       return basename
     end)
   end)
@@ -314,6 +318,14 @@ function AttachCore:attach_buffer(node, bufnr, opts)
     local data = table.concat(vim.api.nvim_buf_get_lines(bufnr, 0, -1, false), '\n')
     return utils.writefile(attach_file, data, { excl = true }):next(function()
       node:add_auto_tag()
+      -- Ignore all errors here, this is just to determine whether we can store
+      -- a link to `bufname`.
+      local bufname_exists = vim.uv.fs_stat(bufname)
+      local link = self.links:store_link_to_attachment({
+        attach_dir = attach_dir,
+        original = bufname_exists and bufname or attach_file,
+      })
+      vim.fn.setreg(vim.v.register, link)
       return basename
     end)
   end)
@@ -341,7 +353,10 @@ function AttachCore:attach_many(node, files, opts)
       .mapSeries(function(to_be_attached)
         local basename = basename_safe(to_be_attached)
         local attach_file = vim.fs.joinpath(attach_dir, basename)
-        return attach(to_be_attached, attach_file)
+        return attach(to_be_attached, attach_file):next(function(success)
+          self.links:store_link_to_attachment({ attach_dir = attach_dir, original = to_be_attached })
+          return success
+        end)
       end, files)
       ---@param successes boolean[]
       :next(function(successes)

lua/orgmode/attach/init.lua

@@ -14,9 +14,10 @@ local MAX_TIMEOUT = 2 ^ 31
 local Attach = {}
 Attach.__index = Attach
 
----@param opts {files:OrgFiles}
+---@param opts {files:OrgFiles, links:OrgLinks}
 function Attach:new(opts)
   local data = setmetatable({ core = Core.new(opts) }, self)
+  data.core.links:add_type(require('orgmode.org.links.types.attachment'):new({ attach = data }))
   return data
 end
 

lua/orgmode/config/_meta.lua

@@ -245,6 +245,7 @@
 ---@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_store_link_p 'original' | 'file' | 'attached' | false If true, attaching a file stores a link to it. Default: 'attached'
 ---@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'
 ---@field win_split_mode? 'horizontal' | 'vertical' | 'auto' | 'float' | string[] How to open agenda and capture windows. Default: 'horizontal'

lua/orgmode/config/defaults.lua

@@ -78,6 +78,7 @@ local DefaultConfig = {
   org_attach_copy_directory_create_symlink = false,
   org_attach_visit_command = 'edit',
   org_attach_use_inheritance = 'selective',
+  org_attach_store_link_p = 'attached',
   org_attach_id_to_path_function_list = {
     'uuid_folder_format',
     'ts_folder_format',

lua/orgmode/init.lua

@@ -59,7 +59,7 @@ function Org:init()
     })
     :load_sync(true, 20000)
   self.links = require('orgmode.org.links'):new({ files = self.files })
-  self.attach = require('orgmode.attach'):new({ files = self.files })
+  self.attach = require('orgmode.attach'):new({ files = self.files, links = self.links })
   self.agenda = require('orgmode.agenda'):new({
     files = self.files,
     highlighter = self.highlighter,

lua/orgmode/org/links/init.lua

@@ -76,8 +76,11 @@ function OrgLinks:autocomplete(link)
 end
 
 ---@param headline OrgHeadline
+---@return string url
 function OrgLinks:store_link_to_headline(headline)
-  self.stored_links[self:get_link_to_headline(headline)] = headline:get_title()
+  local url = self:get_link_to_headline(headline)
+  self.stored_links[url] = headline:get_title()
+  return url
 end
 
 ---@param headline OrgHeadline
@@ -110,6 +113,41 @@ function OrgLinks:get_link_to_file(file)
   return ('file:%s::*%s'):format(file.filename, title)
 end
 
+---@param params {attach_dir: string, original: string}
+---@return string | nil url
+function OrgLinks:store_link_to_attachment(params)
+  local url = self:get_link_to_attachment(params)
+  if url then
+    self.stored_links[url] = vim.fs.basename(params.original)
+  end
+  return url
+end
+
+---@param params {attach_dir: string, original: string}
+---@return string | nil url
+function OrgLinks:get_link_to_attachment(params)
+  vim.validate({
+    attach_dir = { params.attach_dir, 'string' },
+    original = { params.original, 'string' },
+  })
+  local basename = vim.fs.basename(params.original)
+  local choice = config.org_attach_store_link_p
+  if choice == 'attached' then
+    return string.format('attachment:%s', basename)
+  elseif choice == 'file' then
+    local attach_file = vim.fs.joinpath(params.attach_dir, basename)
+    return string.format('file:%s', attach_file)
+  elseif choice == 'original' then
+    -- Sanity check: `original` might be a URL. Check for that and return it
+    -- unmodified if yes.
+    if params.original:match('^[A-Za-z]+://') then
+      return params.original
+    end
+    return string.format('file:%s', params.original)
+  end
+  return nil
+end
+
 ---@param link_location string
 function OrgLinks:insert_link(link_location, desc)
   local selected_link = OrgHyperlink:new(link_location)

lua/orgmode/org/links/types/attachment.lua

@@ -0,0 +1,57 @@
+---@class OrgLinkAttachment:OrgLinkType
+---@field private attach OrgAttach
+local OrgLinkAttachment = {}
+OrgLinkAttachment.__index = OrgLinkAttachment
+
+---@param opts { attach: OrgAttach }
+function OrgLinkAttachment:new(opts)
+  local this = setmetatable({
+    attach = opts.attach,
+  }, OrgLinkAttachment)
+  return this
+end
+
+---@return string
+function OrgLinkAttachment:get_name()
+  return 'attachment'
+end
+
+---@param link string
+---@return boolean
+function OrgLinkAttachment:follow(link)
+  local opts = self:_parse(link)
+  if not opts then
+    return false
+  end
+  self.attach:open(opts.basename, opts.node)
+  return true
+end
+
+---@param link string
+---@return string[]
+function OrgLinkAttachment:autocomplete(link)
+  local opts = self:_parse(link)
+  if not opts then
+    return {}
+  end
+  local complete = self.attach:make_completion({ node = opts.node })
+  return vim.tbl_map(function(name)
+    return 'attachment:' .. name
+  end, complete(opts.basename))
+end
+
+---@private
+---@param link string
+---@return { node: OrgAttachNode, basename: string } | nil
+function OrgLinkAttachment:_parse(link)
+  local basename = link:match('^attachment:(.+)$')
+  if not basename then
+    return nil
+  end
+  return {
+    node = self.attach:get_current_node(),
+    basename = basename,
+  }
+end
+
+return OrgLinkAttachment