Skip to content

Commit 6a308c0

Browse files
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.
1 parent 9046d2e commit 6a308c0

File tree

6 files changed

+29
-13
lines changed

6 files changed

+29
-13
lines changed

docs/addons.md

+9-3
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,14 @@ Source can have the following values:
115115
| script-message | triggered by the `get-directory-contents` script-message |
116116
| addon | caused by an addon calling the `parse_directory` API function - note that addons can set a custom state |
117117

118-
Note that all calls to any `parse` function during a specific parse request will be given the same parse_state table.
119-
This allows parsers to communicate with parsers of a lower priority using the `properties` table.
118+
The `properties` table is designed to be used to send options to parsers.
119+
It is recommended that addons nest their properties within a second table to avoid conflicts,
120+
for example the in-built cache parser checks the `properties.cache.use` field,
121+
and if set will either forcibly enable or bypass the cache for that particular parse.
122+
All calls to any `parse` function during a specific parse request will be given the same parse_state table.
123+
This allows parsers to communicate with parsers of a lower priority by modifying the table.
124+
125+
Be aware that this is still an experimental feature, so any properties used by 1st party addons may change at any time.
120126

121127
#### Coroutines
122128

@@ -445,7 +451,7 @@ Adds the given extension to the default extension filter whitelist. Can only be
445451

446452
#### `fb.browse_directory(directory: string, open_browser: bool = true): coroutine`
447453

448-
Clears the cache and opens the given directory in the browser.
454+
Opens the given directory in the browser. The cache is never used.
449455
If the `open_browser` argument is truthy or `nil` then the browser will be opened
450456
if it is currently closed. If `open_browser` is `false` then the directory will
451457
be opened in the background.

modules/controls.lua

+1-1
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ function controls.browse_directory(directory, open_browser)
8686
msg.verbose('recieved directory from script message: '..directory)
8787

8888
directory = fb_utils.resolve_directory_mapping(directory)
89-
local co = movement.goto_directory(directory)
89+
local co = movement.goto_directory(directory, nil, nil, {cache={use=false}})
9090
if open_browser then controls.open() end
9191
return co
9292
end

modules/defs/parser.lua

+3-2
Original file line numberDiff line numberDiff line change
@@ -25,16 +25,17 @@
2525

2626

2727
---@alias ParseStateSource 'browser'|'loadlist'|'script-message'|'addon'|string
28+
---@alias ParseProperties table<string,any>
2829

2930
---The Parse State object passed to the can_parse and parse methods
3031
---@class ParseStateFields
3132
---@field source ParseStateSource
3233
---@field directory string
3334
---@field already_deferred boolean?
34-
---@field properties table<string,any>
35+
---@field properties ParseProperties
3536

3637
---@class ParseState: ParseStateFields, ParseStateAPI
3738

3839
---@class ParseStateTemplate
3940
---@field source ParseStateSource?
40-
---@field properties table<string,any>?
41+
---@field properties ParseProperties?

modules/navigation/directory-movement.lua

+3-2
Original file line numberDiff line numberDiff line change
@@ -83,8 +83,9 @@ end
8383
---@param directory string
8484
---@param moving_adjacent? number|false
8585
---@param store_history? boolean default `true`
86+
---@param parse_properties? ParseProperties
8687
---@return thread
87-
function directory_movement.goto_directory(directory, moving_adjacent, store_history)
88+
function directory_movement.goto_directory(directory, moving_adjacent, store_history, parse_properties)
8889
local current = g.state.list[g.state.selected]
8990
g.state.directory = directory
9091

@@ -99,7 +100,7 @@ function directory_movement.goto_directory(directory, moving_adjacent, store_his
99100
if o.history_size > 0 and store_history == nil or store_history then
100101
directory_movement.append_history(directory)
101102
end
102-
return scanning.rescan(moving_adjacent or false)
103+
return scanning.rescan(moving_adjacent or false, nil, parse_properties)
103104
end
104105

105106
---Move the browser to a particular point in the browser history.

modules/navigation/scanning.lua

+7-5
Original file line numberDiff line numberDiff line change
@@ -103,14 +103,15 @@ end
103103
---Sends update requests to the different parsers.
104104
---@async
105105
---@param moving_adjacent? number|boolean
106-
local function update_list(moving_adjacent)
106+
---@param parse_properties? ParseProperties
107+
local function update_list(moving_adjacent, parse_properties)
107108
msg.verbose('opening directory: ' .. g.state.directory)
108109

109110
g.state.selected = 1
110111
g.state.selection = {}
111112

112113
local directory = g.state.directory
113-
local list, opts = parse_directory(g.state.directory, { source = "browser" })
114+
local list, opts = parse_directory(g.state.directory, { source = "browser", properties = parse_properties })
114115

115116
--if the running coroutine isn't the one stored in the state variable, then the user
116117
--changed directories while the coroutine was paused, and this operation should be aborted
@@ -124,7 +125,7 @@ local function update_list(moving_adjacent)
124125
if not list then
125126
--opens the root instead
126127
msg.warn("could not read directory", g.state.directory, "redirecting to root")
127-
list, opts = parse_directory("", { source = "browser" })
128+
list, opts = parse_directory("", { source = "browser", properties = parse_properties })
128129

129130
if not list then error(('fatal error - failed to read the root directory')) end
130131

@@ -161,8 +162,9 @@ end
161162
---rescans the folder and updates the list.
162163
---@param moving_adjacent? number|boolean
163164
---@param cb? function
165+
---@param parse_properties? ParseProperties
164166
---@return thread # The coroutine for the triggered parse operation. May be aborted early if directory is in the cache.
165-
local function rescan(moving_adjacent, cb)
167+
local function rescan(moving_adjacent, cb, parse_properties)
166168
if moving_adjacent == nil then moving_adjacent = 0 end
167169

168170
--we can only make assumptions about the directory label when moving from adjacent directories
@@ -177,7 +179,7 @@ local function rescan(moving_adjacent, cb)
177179
--pause execution for asynchronous operations
178180
---@async
179181
local co = fb_utils.coroutine.queue(function()
180-
update_list(moving_adjacent)
182+
update_list(moving_adjacent, parse_properties)
181183
if g.state.empty_text == "~" then g.state.empty_text = "empty directory" end
182184

183185
ass.update_ass()

modules/parsers/cache.lua

+6
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,12 @@ end
4545
local prev_directory = ''
4646

4747
function cacheParser:can_parse(directory, parse_state)
48+
-- allows the cache to be forcibly used or bypassed with the
49+
-- cache/use parse property.
50+
if parse_state.properties.cache and parse_state.properties.cache.use ~= nil then
51+
return parse_state.properties.cache.use
52+
end
53+
4854
-- the script message is guaranteed to always bypass the cache
4955
if parse_state.source == 'script-message' then return false end
5056
if not fb.get_opt('cache') or directory == '' then return false end

0 commit comments

Comments
 (0)