feat: trash support for linux and mac (#165)

* wip: skeleton code for trash adapter

* refactor: split trash implementation for mac and linux

* fix: ensure we create the .Trash/$uid dir

* feat: code complete linux trash implementation

* doc: write up trash features

* feat: code complete mac trash implementation

* cleanup: remove previous, terrible, undocumented trash feature

* fix: always disabled trash

* feat: show original path of trashed files

* doc: add a note about calling actions directly

* fix: bugs in trash implementation

* fix: schedule_wrap in mac trash

* doc: fix typo and line wrapping

* fix: parsing of arguments to :Oil command

* doc: small documentation tweaks

* doc: fix awkward wording in the toggle_trash action

* fix: warning on Windows when delete_to_trash = true

* feat: :Oil --trash can open specific trash directories

* fix: show all trash files in device root

* fix: trash mtime should be sortable

* fix: shorten_path handles optional trailing slash

* refactor: overhaul the UI

* fix: keep trash original path vtext from stacking

* refactor: replace disable_changes with an error filter

* fix: shorten path names in home directory relative to root

* doc: small README format changes

* cleanup: remove unnecessary preserve_undo logic

* test: add a functional test for the freedesktop trash adapter

* test: more functional tests for trash

* fix: schedule a callback to avoid main loop error

* refactor: clean up mutator logic

* doc: some comments and type annotations

lua/oil/mutator/parser.lua

@@ -142,11 +142,18 @@ M.parse_line = function(adapter, line, column_defs)
   return { data = ret, entry = entry, ranges = ranges }
 end
 
+---@class (exact) oil.ParseError
+---@field lnum integer
+---@field col integer
+---@field message string
+
 ---@param bufnr integer
----@return oil.Diff[]
----@return table[] Parsing errors
+---@return oil.Diff[] diffs
+---@return oil.ParseError[] errors Parsing errors
 M.parse = function(bufnr)
+  ---@type oil.Diff[]
   local diffs = {}
+  ---@type oil.ParseError[]
   local errors = {}
   local bufname = vim.api.nvim_buf_get_name(bufnr)
   local adapter = util.get_adapter(bufnr)
@@ -158,11 +165,14 @@ M.parse = function(bufnr)
     })
     return diffs, errors
   end
-  local scheme, path = util.parse_url(bufname)
-  local parent_url = scheme .. path
-  local column_defs = columns.get_supported_columns(adapter)
-  local children = cache.list_url(parent_url)
+
   local lines = vim.api.nvim_buf_get_lines(bufnr, 0, -1, true)
+  local scheme, path = util.parse_url(bufname)
+  local column_defs = columns.get_supported_columns(adapter)
+  local parent_url = scheme .. path
+  local children = cache.list_url(parent_url)
+  -- map from name to entry ID for all entries previously in the buffer
+  ---@type table<string, integer>
   local original_entries = {}
   for _, child in pairs(children) do
     local name = child[FIELD_NAME]
@@ -184,6 +194,7 @@ M.parse = function(bufnr)
   end
   for i, line in ipairs(lines) do
     if line:match("^/%d+") then
+      -- Parse the line for an existing entry
       local result, err = M.parse_line(adapter, line, column_defs)
       if not result or err then
         table.insert(errors, {
@@ -256,6 +267,7 @@ M.parse = function(bufnr)
         end
       end
     else
+      -- Parse a new entry
       local name, isdir = parsedir(vim.trim(line))
       if vim.startswith(name, "/") then
         table.insert(errors, {