parsers: allow arbitrary properties to be sent to parsers

This allows custom configuration of parsers for specific parse
operations.

Used internally to prevent the cache from being used when
calling the browse-directory function.

Author: CogentRedTester

docs/addons.md

@@ -115,8 +115,14 @@ Source can have the following values:
 | script-message | triggered by the `get-directory-contents` script-message                                                |
 | addon          | caused by an addon calling the `parse_directory` API function - note that addons can set a custom state |
 
-Note that all calls to any `parse` function during a specific parse request will be given the same parse_state table.
-This allows parsers to communicate with parsers of a lower priority using the `properties` table.
+The `properties` table is designed to be used to send options to parsers.
+It is recommended that addons nest their properties within a second table to avoid conflicts,
+for example the in-built cache parser checks the `properties.cache.use` field,
+and if set will either forcibly enable or bypass the cache for that particular parse.
+All calls to any `parse` function during a specific parse request will be given the same parse_state table.
+This allows parsers to communicate with parsers of a lower priority by modifying the table.
+
+Be aware that this is still an experimental feature, so any properties used by 1st party addons may change at any time.
 
 #### Coroutines
 
@@ -445,7 +451,7 @@ Adds the given extension to the default extension filter whitelist. Can only be
 
 #### `fb.browse_directory(directory: string, open_browser: bool = true): coroutine`
 
-Clears the cache and opens the given directory in the browser.
+Opens the given directory in the browser. The cache is never used.
 If the `open_browser` argument is truthy or `nil` then the browser will be opened
 if it is currently closed. If `open_browser` is `false` then the directory will
 be opened in the background.

modules/controls.lua

@@ -86,7 +86,7 @@ function controls.browse_directory(directory, open_browser)
     msg.verbose('recieved directory from script message: '..directory)
 
     directory = fb_utils.resolve_directory_mapping(directory)
-    local co = movement.goto_directory(directory)
+    local co = movement.goto_directory(directory, nil, nil, {cache={use=false}})
     if open_browser then controls.open() end
     return co
 end

modules/defs/parser.lua

@@ -25,16 +25,17 @@
 
 
 ---@alias ParseStateSource 'browser'|'loadlist'|'script-message'|'addon'|string
+---@alias ParseProperties table<string,any>
 
 ---The Parse State object passed to the can_parse and parse methods
 ---@class ParseStateFields
 ---@field source ParseStateSource
 ---@field directory string
 ---@field already_deferred boolean?
----@field properties table<string,any>
+---@field properties ParseProperties
 
 ---@class ParseState: ParseStateFields, ParseStateAPI
 
 ---@class ParseStateTemplate
 ---@field source ParseStateSource?
----@field properties table<string,any>?
+---@field properties ParseProperties?

modules/navigation/directory-movement.lua

@@ -83,8 +83,9 @@ end
 ---@param directory string
 ---@param moving_adjacent? number|false
 ---@param store_history? boolean default `true`
+---@param parse_properties? ParseProperties
 ---@return thread
-function directory_movement.goto_directory(directory, moving_adjacent, store_history)
+function directory_movement.goto_directory(directory, moving_adjacent, store_history, parse_properties)
     local current = g.state.list[g.state.selected]
     g.state.directory = directory
 
@@ -99,7 +100,7 @@ function directory_movement.goto_directory(directory, moving_adjacent, store_his
     if o.history_size > 0 and store_history == nil or store_history then
         directory_movement.append_history(directory)
     end
-    return scanning.rescan(moving_adjacent or false)
+    return scanning.rescan(moving_adjacent or false, nil, parse_properties)
 end
 
 ---Move the browser to a particular point in the browser history.

modules/navigation/scanning.lua

@@ -103,14 +103,15 @@ end
 ---Sends update requests to the different parsers.
 ---@async
 ---@param moving_adjacent? number|boolean
-local function update_list(moving_adjacent)
+---@param parse_properties? ParseProperties
+local function update_list(moving_adjacent, parse_properties)
     msg.verbose('opening directory: ' .. g.state.directory)
 
     g.state.selected = 1
     g.state.selection = {}
 
     local directory = g.state.directory
-    local list, opts = parse_directory(g.state.directory, { source = "browser" })
+    local list, opts = parse_directory(g.state.directory, { source = "browser", properties = parse_properties })
 
     --if the running coroutine isn't the one stored in the state variable, then the user
     --changed directories while the coroutine was paused, and this operation should be aborted
@@ -124,7 +125,7 @@ local function update_list(moving_adjacent)
     if not list then
         --opens the root instead
         msg.warn("could not read directory", g.state.directory, "redirecting to root")
-        list, opts = parse_directory("", { source = "browser" })
+        list, opts = parse_directory("", { source = "browser", properties = parse_properties })
 
         if not list then error(('fatal error - failed to read the root directory')) end
 
@@ -161,8 +162,9 @@ end
 ---rescans the folder and updates the list.
 ---@param moving_adjacent? number|boolean
 ---@param cb? function
+---@param parse_properties? ParseProperties
 ---@return thread # The coroutine for the triggered parse operation. May be aborted early if directory is in the cache.
-local function rescan(moving_adjacent, cb)
+local function rescan(moving_adjacent, cb, parse_properties)
     if moving_adjacent == nil then moving_adjacent = 0 end
 
     --we can only make assumptions about the directory label when moving from adjacent directories
@@ -177,7 +179,7 @@ local function rescan(moving_adjacent, cb)
     --pause execution for asynchronous operations
     ---@async
     local co = fb_utils.coroutine.queue(function()
-        update_list(moving_adjacent)
+        update_list(moving_adjacent, parse_properties)
         if g.state.empty_text == "~" then g.state.empty_text = "empty directory" end
 
         ass.update_ass()

modules/parsers/cache.lua

@@ -45,6 +45,12 @@ end
 local prev_directory = ''
 
 function cacheParser:can_parse(directory, parse_state)
+    -- allows the cache to be forcibly used or bypassed with the
+    -- cache/use parse property.
+    if parse_state.properties.cache and parse_state.properties.cache.use ~= nil then
+        return parse_state.properties.cache.use
+    end
+
     -- the script message is guaranteed to always bypass the cache
     if parse_state.source == 'script-message' then return false end
     if not fb.get_opt('cache') or directory == '' then return false end