Api/v1.7.0

README.md

@@ -46,7 +46,7 @@ The following keybinds are set by default
 |-------------|----------------------------------|-------------------------------------------------------------------------------|
 | MENU        | browse-files                     | toggles the browser                                                           |
 | Ctrl+o      | open-browser                     | opens the browser                                                             |
-| Alt+o       | browse-directory/get-user-input  | opens a dialogue box to type in a directory - requires [mpv-user-input](#mpv-user-input) |
+| Alt+o       | browse-directory/get-user-input  | opens a dialogue box to type in a directory - requires [mpv-user-input](#mpv-user-input) when mpv < v0.38 |
 
 The following dynamic keybinds are only set while the browser is open:
 
@@ -174,4 +174,7 @@ See [#55](https://github.com/CogentRedTester/mpv-file-browser/issues/55) for mor
 
 mpv-user-input is a script that provides an API to request text input from the user over the OSD.
 It was built using `console.lua` as a base, so supports almost all the same text input commands.
-If `user-input.lua` is loaded by mpv, and `user-input-module` is in the `~~/script-modules/` directory, then using `Alt+o` will open an input box that can be used to directly enter directories for file-browser to open.
+If `user-input.lua` is loaded by mpv, and `user-input-module` is in the `~~/script-modules/` directory,
+then using `Alt+o` will open an input box that can be used to directly enter directories for file-browser to open.
+
+Mpv v0.38 added the `mp.input` module, which means `mpv-user-input` is no-longer necessary from that version onwards.

addons/apache-browser.lua

@@ -22,7 +22,7 @@ end
 
 local apache = {
     priority = 80,
-    version = "1.1.0"
+    api_version = "1.1.0"
 }
 
 function apache:can_parse(name)

addons/favourites.lua

@@ -17,7 +17,7 @@ end
 
 local favourites = nil
 local favs = {
-    version = "1.4.0",
+    api_version = "1.4.0",
     priority = 30,
     cursor = 1
 }

addons/find.lua

@@ -16,7 +16,7 @@ local input_loaded, input = pcall(require, "mp.input")
 local user_input_loaded, user_input = pcall(require, "user-input-module")
 
 local find = {
-    version = "1.3.0"
+    api_version = "1.3.0"
 }
 local latest_coroutine = nil
 local global_fb_state = getmetatable(fb.get_state()).__original

addons/ftp-browser.lua

@@ -9,7 +9,7 @@ local fb = require 'file-browser'
 
 local ftp = {
     priority = 100,
-    version = "1.1.0"
+    api_version = "1.1.0"
 }
 
 function ftp:can_parse(directory)

addons/home-label.lua

@@ -9,7 +9,7 @@ local home = fb.fix_path(mp.command_native({"expand-path", "~/"}), true)
 
 local home_label = {
     priority = 100,
-    version = "1.0.0"
+    api_version = "1.0.0"
 }
 
 function home_label:can_parse(directory)

addons/last-open-directory.lua

@@ -0,0 +1,56 @@
+--[[
+    An addon for mpv-file-browser which stores the last opened directory and
+    sets it as the opened directory the next time mpv is opened.
+
+    Available at: https://github.com/CogentRedTester/mpv-file-browser/tree/master/addons
+]]--
+
+local mp = require 'mp'
+local msg = require 'mp.msg'
+
+local fb = require 'file-browser'
+
+local state_file = mp.command_native({'expand-path', '~~state/last_opened_directory'})
+msg.verbose('using', state_file)
+
+local function write_directory(directory)
+    local file = io.open(state_file, 'w+')
+
+    if not file then return msg.error('could not open', state_file, 'for writing') end
+
+    directory = directory or fb.get_directory()
+    msg.verbose('writing', directory, 'to', state_file)
+    file:write(directory)
+    file:close()
+end
+
+
+local addon = {
+    api_version = '1.7.0',
+    priority = 0,
+}
+
+function addon:setup()
+    local file = io.open(state_file, "r")
+    if not file then
+        return msg.error('failed to open', state_file, 'for reading')
+    end
+
+    local dir = file:read("*a")
+    msg.verbose('setting default directory to', dir)
+    fb.browse_directory(dir, false)
+    file:close()
+end
+
+function addon:can_parse(dir, parse_state)
+    if parse_state.source == 'browser' then write_directory(dir) end
+    return false
+end
+
+function addon:parse()
+    return nil
+end
+
+mp.register_event('shutdown', function() write_directory() end)
+
+return addon

addons/ls.lua

@@ -11,7 +11,7 @@ local fb = require "file-browser"
 
 local ls = {
     priority = 109,
-    version = "1.1.0",
+    api_version = "1.1.0",
     name = "ls",
     keybind_name = "file"
 }

addons/m3u-browser.lua

@@ -12,7 +12,7 @@ local rf = require "read-file"
 
 local m3u = {
     priority = 100,
-    version = "1.0.0",
+    api_version = "1.0.0",
     name = "m3u"
 }
 

addons/powershell.lua

@@ -16,7 +16,7 @@ local fb = require "file-browser"
 
 local wn = {
     priority = 109,
-    version = "1.1.0",
+    api_version = "1.1.0",
     name = "powershell",
     keybind_name = "file"
 }

addons/root.lua

@@ -48,7 +48,7 @@ local function setup()
 end
 
 return {
-    version = '1.4.0',
+    api_version = '1.4.0',
     setup = setup,
     priority = -1000,
 }

addons/url-decode.lua

@@ -4,7 +4,7 @@
 
 local urldecode = {
     priority = 5,
-    version = "1.0.0"
+    api_version = "1.0.0"
 }
 
 --decodes a URL address

addons/windir.lua

@@ -34,7 +34,7 @@ end
 
 local dir = {
     priority = 109,
-    version = "1.1.0",
+    api_version = "1.1.0",
     name = "cmd-dir",
     keybind_name = "file"
 }

addons/winroot.lua

@@ -46,7 +46,7 @@ local keybind = {
 }
 
 return {
-    version = '1.4.0',
+    api_version = '1.4.0',
     setup = import_drives,
     keybinds = { keybind }
 }

docs/addons.md

@@ -1,4 +1,4 @@
-# How to Write an Addon - API v1.6.0
+# How to Write an Addon - API v1.7.0
 
 Addons provide ways for file-browser to parse non-native directory structures. This document describes how one can create their own custom addon.
 
@@ -17,7 +17,7 @@ version of the API. It follows [semantic versioning](https://semver.org/) conven
 A parser sets its version string with the `version` field, as seen [below](#overview).
 
 Any change that breaks backwards compatability will cause the major version number to increase.
-A parser MUST have the same version number as the API, otherwise an error message will be printed and the parser will
+A parser MUST have the same major version number as the API, otherwise an error message will be printed and the parser will
 not be loaded.
 
 A minor version number denotes a change to the API that is backwards compatible. This includes additional API functions,
@@ -36,7 +36,7 @@ Each addon must return either a single parser table, or an array of parser table
 | key       | type   | arguments                 | returns                | description                                                                                                  |
 |-----------|--------|---------------------------|------------------------|--------------------------------------------------------------------------------------------------------------|
 | priority  | number | -                         | -                      | a number to determine what order parsers are tested - see [here](#priority-suggestions) for suggested values |
-| version   | string | -                         | -                      | the API version the parser is using - see [API Version](#api-version)                                        |
+| api_version| string | -                         | -                      | the API version the parser is using - see [API Version](#api-version)                                        |
 | can_parse | method | string, parse_state_table | boolean                | returns whether or not the given path is compatible with the parser                                          |
 | parse     | method | string, parse_state_table | list_table, opts_table | returns an array of item_tables, and a table of options to control how file_browser handles the list         |
 
@@ -56,7 +56,7 @@ Here is an extremely simple example of an addon creating a parser table and retu
 
 ```lua
 local parser = {
-    version = '1.0.0',
+    api_version = '1.0.0',
     priority = 100,
     name = "example"        -- this parser will have the id 'example' or 'example_#' if there are duplicates
 }
@@ -443,11 +443,14 @@ The current API version in use by file-browser.
 
 Adds the given extension to the default extension filter whitelist. Can only be run inside the `setup()` method.
 
-#### `fb.browse_directory(directory: string): void`
+#### `fb.browse_directory(directory: string, open_browser: bool = true): coroutine`
 
-Clears the cache and opens the given directory in the browser. If the browser is closed then it will be opened.
-This function is non-blocking, it is possible that the function will return before the directory has finished
-being scanned.
+Clears the cache and opens the given directory in the browser.
+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.
+Returns the coroutine of the upcoming parse operation. The parse is queued and run when the script thread next goes idle,
+allowing one to store this value and use it to identify the triggered parse operation.
 
 This is the equivalent of calling the `browse-directory` script-message.
 
@@ -636,9 +639,16 @@ Returns the success boolean returned by `coroutine.resume`, but drops all other
 
 Runs the given function in a new coroutine, passing through any additional arguments.
 
-#### `fb.rescan(): void`
+#### `fb.coroutine.queue(fn: function, ...): coroutine`
+
+Runs the given function in a coroutine when the script next goes idle, passing through
+any additional arguments. The (not yet started) coroutine is returned by the function.
+
+#### `fb.rescan(): coroutine`
 
 Rescans the current directory. Equivalent to Ctrl+r without the cache refresh for higher level directories.
+Returns the coroutine of the upcoming parse operation. The parse is queued and run when the script thread next goes idle,
+allowing one to store this value and use it to identify the triggered parse operation.
 
 #### `fb.redraw(): void`
 
@@ -671,7 +681,7 @@ local fb = require "file-browser"
 local home = fb.fix_path(mp.command_native({"expand-path", "~/"}), true)
 
 local home_label = {
-    version = '1.0.0',
+    api_version = '1.0.0',
     priority = 100
 }
 
@@ -707,6 +717,42 @@ Both keys and values are copied. If `depth` is undefined then it defaults to `ma
 Additionally, the original table is stored in the `__original` field of the copy's metatable.
 The copy behaviour of the metatable itself is subject to change, but currently it is not copied.
 
+#### `fb.evaluate_string(str: string, chunkname?: string, env?: table, defaults?: bool = true): unknown`
+
+Loads `str` as a chunk of Lua statement(s) and runs them, returning the result.
+Errors are propagated to the caller. `chunkname` is used
+for debug output and error messages.
+
+Each chunk has a separate global environment table that inherits
+from the main global table. This means new globals can be created safely,
+but the default globals can still be accessed. As such, this method
+cannot and should not be used for security or sandboxing.
+
+A custom environment table can be provided with the `env` argument.
+Inheritance from the global table is disabled if `defaults` is `false`.
+
+Examples:
+
+```lua
+fb.evaluate_string('return 5 + 5')          -- 10
+fb.evaluate_string('x = 20 ; return x * x') -- 400
+
+local code = [[
+local arr = {1, 2, 3, 4}
+table.insert(arr, x)
+return unpack(arr)
+]]
+fb.evaluate_string(code, 'test3', {x = 5})      -- 1, 2, 3, 4, 5
+fb.evaluate_string(code, 'test4', nil, false)   -- Lua error: [string "test4"]:2: attempt to index global 'table' (a nil value)
+
+```
+
+In an expression the `mp`, `mp.msg`, and `mp.utils` modules are available as `mp`, `msg`, and `utils` respectively.
+Additionally, in mpv v0.38+ the `mp.input` module is available as `input`.
+This addon API is available as `fb` and if [mpv-user-input](https://github.com/CogentRedTester/mpv-user-input)
+is installed then user-input will be available in `user_input`.
+These modules are all unavailable if `defaults` is `false`.
+
 #### `fb.filter(list: list_table): list_table`
 
 Iterates through the given list and removes items that don't pass the user set filters

docs/custom-keybinds.md

@@ -20,6 +20,7 @@ Keybinds are declared in the `~~/script-opts/file-browser-keybinds.json` file, t
 | delay         | no       | `0`        | time to wait between sending repeated multi commands                                       |
 | concat-string | no       | `' '` (space) | string to insert between items when concatenating multi commands                        |
 | passthrough   | no       | -          | force or ban passthrough behaviour - see [passthrough](#passthrough-keybinds)              |
+| api_version   | no       | -          | tie the keybind to a particular [addon API version](./addons.md#api-version), printing warnings and throwing errors if the keybind is used with wrong versions |
 
 Example:
 
@@ -175,8 +176,10 @@ To avoid conflicts custom keybinds use the format: `file_browser/dynamic/custom/
 Expressions are used to evaluate Lua code into a string that can be used for commands.
 These behave similarly to those used for [`profile-cond`](https://mpv.io/manual/master/#conditional-auto-profiles)
 values. In an expression the `mp`, `mp.msg`, and `mp.utils` modules are available as `mp`, `msg`, and `utils` respectively.
-Additionally the file-browser [addon API](addons/addons.md#the-api) is available as `fb` and if [mpv-user-input](https://github.com/CogentRedTester/mpv-user-input)
-is installed then user-input API will be available in `input`.
+Additionally, in mpv v0.38+ the `mp.input` module is available as `input`.
+
+The file-browser [addon API](addons/addons.md#the-api) is available as `fb` and if [mpv-user-input](https://github.com/CogentRedTester/mpv-user-input)
+is installed then user-input API will be available in `user_input`.
 
 This example only runs the keybind if the browser is in the Windows C drive or if
 the selected item is a matroska file:
@@ -301,9 +304,9 @@ rename items in file-browser:
 {
     "key": "KP1",
     "command": ["script-message", "run-statement",
-                    "assert(input, 'install mpv-user-input!')",
+                    "assert(user_input, 'install mpv-user-input!')",
 
-                    "local line, err = input.get_user_input_co({",
+                    "local line, err = user_input.get_user_input_co({",
                                             "id = 'rename-file',",
                                             "source = 'custom-keybind',",
                                             "request_text = 'rename file:',",

main.lua

@@ -11,15 +11,17 @@
 local mp = require 'mp'
 
 local o = require 'modules.options'
+
+-- setting the package paths
+package.path = mp.command_native({"expand-path", o.module_directory}).."/?.lua;"..package.path
+
 local addons = require 'modules.addons'
 local keybinds = require 'modules.keybinds'
 local setup = require 'modules.setup'
 local controls = require 'modules.controls'
 local observers = require 'modules.observers'
 local script_messages = require 'modules.script-messages'
 
--- setting the package paths
-package.path = mp.command_native({"expand-path", o.module_directory}).."/?.lua;"..package.path
 local input_loaded, input = pcall(require, "mp.input")
 local user_input_loaded, user_input = pcall(require, "user-input-module")