diff --git a/doc/dash.txt b/doc/dash.txt index 8db9fe2..549601a 100644 --- a/doc/dash.txt +++ b/doc/dash.txt @@ -84,7 +84,10 @@ If using Telescope, you can also run `:Telescope dash search` or `:Telescope dash search_no_filter`. If using fzf-lua, you can also run `:FzfLua dash` or `:lua -require('fzf-lua').dash({ bang = false, initial_text = '' })`, for example. +require('fzf-lua').dash({ bang = false, initial_text = '' })`. + +If using Snap, you can also run `:lua require('dash.providers.snap').dash({ +bang = false, initial_text = '' })`. CONFIGURATION *dash-configuration* @@ -101,7 +104,7 @@ CONFIGURATION TABLE STRUCTURE ~ -- map filetype strings to the keywords you've configured for docsets in Dash -- setting to false will disable filtering by filetype for that filetype -- filetypes not included in this table will not filter the query by filetype - -- check src/config.rs to see all defaults + -- check src/lua_bindings/dash_config_binding.rs to see all defaults -- the values you pass for file_type_keywords are merged with the defaults -- to disable filtering for all filetypes, -- set file_type_keywords = false @@ -154,7 +157,7 @@ LUA API ~ The public API consists of two main functions. > - -- See src/config.rs for available config keys + -- See src/lua_bindings/dash_config_binding.rs for available config keys -- Also described in configuration section below ---@param config require('dash').setup(config) @@ -198,8 +201,8 @@ The Rust backend exports the following constants for use: `LIBDASH_NVIM.CONFIG` (TABLE) ~ This table stores the internal configuration. You can access it via -`require('libdash_nvim').config`. See `src/config.rs` or |dash-configuration| -above for configuration keys. +`require('libdash_nvim').config`. See `src/lua_bindings/dash_config_binding.rs` +or |dash-configuration| above for configuration keys. `LIBDASH_NVIM.DEFAULT_CONFIG` (TABLE) ~ @@ -217,7 +220,8 @@ example: This method is used to set the internal configuration of the backend. It takes a table, which will be **merged with the default configuration**. See -`src/config.rs` or |dash-configuration| above for configuration keys. +`src/lua_bindings/dash_config_binding.rs` or |dash-configuration| above for +configuration keys. > require('libdash_nvim').setup({ @@ -228,28 +232,36 @@ a table, which will be **merged with the default configuration**. See `LIBDASH_NVIM.QUERY` (FUNCTION) ~ -This method (`require('libdash_nivm').query`) takes 3 arguments: the search -text, the current buffer type, and a boolean indicating whether to disable -filetype filtering (e.g. command was run with bang, `:Dash!`). +This method takes a table as its argument. The table should have the following +keys: + + +- `search_text` - the search text entered by the user +- `buffer_type` - the current buffer type, this will be used to determine filter keywords from config +- `ignore_keywords` - disables filtering by keywords if true (e.g. if run with bang, `:Dash!` or `:DashWord!`) + > local libdash = require('libdash_nvim') - local results = libdash.query( - 'match arms', - 'rust', - false - ) + local results = libdash.query({ + search_text = 'match arms', + buffer_type = 'rust', + ignore_keywords = false + }) < -The `query` method returns a table with the following properties: +The `query` method returns a table list of tables (a Rust `Vec` +serialized to a Lua table, see `src/dash_item.rs`) with the following +properties: -- `value` – the number value of the item, to be used when selected. Running a query, then opening the URL `dash-workflow-callback://[value]` will open the selected item in Dash.app -- `ordinal` – a value to sort by, currently this is the same value as `display` -- `display` – a display value -- `keyword` – the keyword (if there was one) on the query that returned this result -- `query` – the full query that returned this result +- `value` - the number value of the item, to be used when selected +- `ordinal` - a value to sort by, currently this is the same value as `display` +- `display` - a display value +- `keyword` - the keyword (if there was one) on the query that returned this result +- `query` - the full query that returned this result +- `is_fallback` - indicates whether the item represents a search engine fallback and should be handled as such If no items are returned from querying Dash, it will return a single item with @@ -258,9 +270,11 @@ following: > { - value = 'https://duckduckgo.com/?q=array.prototype.filter', + value = 'https://duckduckgo.com/?q=rust match arms', ordinal = '1', - display = 'Search with DuckDuckGo: array.prototype.filter', + display = 'Search with DuckDuckGo: rust match arms', + keyword = 'rust', + query = 'rust:match arms', is_fallback = true, } < @@ -273,18 +287,26 @@ Takes an item returned from querying Dash via the > local libdash = require('libdash_nvim') - local results = libdash.query('match arms', 'rust', false) + local results = libdash.query({ + search_text = 'match arms', + buffer_type = 'rust', + ignore_keywords = false + }) local selected = results[1] require('libdash_nvim').open_item(selected) < -`LIBDASH_NVIM.OPEN_SEARCH_ENGINE` (FUNCTION) ~ +`LIBDASH_NVIM.OPEN_URL` (FUNCTION) ~ -Utility method to open a search engine URL when the fallback item is selected. +Simply takes a URL string and opens it in the default browser/handler for the +URL protocol. This is used for both opening the search engine fallback via an +HTTPS URL, as well as opening the selected `DashItem` in Dash.app via the +`dash-workflow-callback://` URL protocol. > - require('libdash_nvim').open_search_engine('https://duckduckgo.com/?q=array.prototype.filter') + require('libdash_nvim').open_url('https://duckduckgo.com/?q=array.prototype.filter') + require('libdash_nvim').open_url('dash-workflow-callback://5') < @@ -326,20 +348,38 @@ installed), as well as the `dash` and `libdash_nvim` Lua modules. RUNNING TESTS ~ -This uses busted , luassert - (both through plenary.nvim -) and matcher_combinators - to define tests in `spec/` -directory. These dependencies are required only to run tests, that’s why they -are installed as git submodules. +You can run all tests (both Rust and Lua) with `make test`. -To run tests, run `make test`. This runs tests in Neovim with a minimal + *dash-Lua-Tests* + +Lua Tests This uses busted + , + luassert + + (both through plenary.nvim + ) + and matcher_combinators + + to define tests in `spec/` directory. + These dependencies are required only to + run tests, that’s why they are + installed as git submodules. + + +To run Lua tests, run `make test-lua`. This runs tests in Neovim with a minimal profile, spec.vim <./spec/spec.vim>. This runs Neovim with only this plugin, and the testing dependencies. If you have entr(1) installed, you can run the tests in watch mode using `make watch`. + *dash-Rust-Tests* + +Rust Tests Rust tests use built-in Rust assertions + and test modules. To run Rust tests, run + `make test-rust`. + + CODE STYLE ~ Use `snake_case` for everything. All Lua code should be checked and formatted @@ -348,7 +388,9 @@ for various fuzzy finder plugins) should be in the Lua code, any core functionality most likely belongs in the Rust backend. All Rust code should be checked and formatted using rust-analyzer -. +, and linted using clippy +, which can be run via `make +lint-rust`. Generated by panvimdoc