Dash.nvim
Query Dash.app within Neovim with a Telescope picker!
The theme used in the recording is lighthaus.nvim.
Note: Dash is a Mac-only app, so you'll only find this plugin useful on Mac.
Install
After installing Dash.nvim, you must run make install. This can be done through a post-install hook with most plugin managers.
Packer:
use({
'mrjones2014/dash.nvim',
requires = { 'nvim-telescope/telescope.nvim' },
run = 'make install',
disable = not vim.fn.has('macunix'),
})
Paq:
require("paq")({
'nvim-telescope/telescope.nvim';
{'mrjones2014/dash.nvim', run = 'make install'};
})
Vim-Plug:
Plug 'nvim-telescope/telescope.nvim'
Plug 'mrjones2014/dash.nvim', { 'do': 'make install' }
Usage
Run :h dash to see these docs in Neovim.
Editor Commands
This plugin has two editor commands, :Dash and :DashWord, each of which accept a bang (!). By default, it will search Dash.app with keywords based on config (see file_type_keywords in configuration). The bang (!) will search without this keyword filtering.
:Dash [query] will open the Telescope picker, and if [query] is passed, it will pre-fill the prompt with [query].
:DashWord will open the Telescope picker and pre-fill the prompt with the word under the cursor.
Configuration
dash.nvim can be configured in your Telescope config. Options and defaults are described below:
require('telescope').setup({
extensions = {
dash = {
-- configure path to Dash.app if installed somewhere other than /Applications/Dash.app
dash_app_path = '/Applications/Dash.app',
-- search engine to fall back to when Dash has no results, must be one of: 'ddg', 'duckduckgo', 'startpage', 'google'
search_engine = 'ddg',
-- debounce while typing, in milliseconds
debounce = 0,
-- 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
-- the values you pass for file_type_keywords are merged with the defaults
-- to disable filtering for all filetypes,
-- set file_type_keywords = false
file_type_keywords = {
dashboard = false,
NvimTree = false,
TelescopePrompt = false,
terminal = false,
packer = false,
-- a table of strings will search on multiple keywords
javascript = { 'javascript', 'nodejs' },
typescript = { 'typescript', 'javascript', 'nodejs' },
typescriptreact = { 'typescript', 'javascript', 'react' },
javascriptreact = { 'javascript', 'react' },
-- you can also do a string, for example,
-- sh = 'bash'
},
}
}
})
If you notice an issue with the default file_type_keywords or would like a new filetype added, please file an issue or submit a PR!
Lua API
The public API consists of two main functions.
-- See src/config.rs for available config keys
-- Also described in configuration section below
---@param config
require('dash').setup(config)
---@param bang boolean @bang searches without any filtering
---@param initial_text string @pre-fill text into the telescope picker
require('dash').search(bang, initial_text)
See backend for documentation on the backend data provider.
Backend
The binaries for the Rust backend can be found under bin/, compiled for Mac M1 and Intel architectures. To build from source, you will need a Rust toolchain, which can be installed from rustup.rs. Once this is installed, you should be able to build via make build. Then, make install will copy the correct binary into the lua/ directory so that it is added to Lua's runtimepath.
The Rust backend is exposed as a Lua module. To require the module, you will need to have the file libdash_nvim.so for your architecture (M1 or Intel) on your runtimepath, as well as the deps directory, which must be in the same directory as the libdash_nvim.so shared library file.
Constants
The Rust backend exports the following constants for use:
require('libdash_nvim').DASH_APP_BASE_PATH=> "/Applications/Dash.app"require('libdash_nvim).DASH_APP_CLI_PATH=> "/Contents/Resources/dashAlfredWorkflow"
libdash_nvim.config (table)
This table stores the internal configuration. You can access it via require('libdash_nvim').config. See src/config.rs or configuration above for configuration keys.
libdash_nvim.default_config (table)
This table stores the default configuration. You should not modify this table, treat it as read-only. This is mainly to help with merging your custom config with the default config, but can be useful for debugging purposes. For example:
:lua print(vim.inspect(require('libdash_nvim').default_config))
libdash_nvim.setup (function)
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 configuration above for configuration keys.
require('libdash_nvim').setup({
-- your custom configuration here
})
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!).
local libdash = require('libdash_nvim')
local results = libdash.query(
'match arms',
'rust',
false
)
The query method returns a table with the following properties:
value-- the number value of the item, to be used when selected. Running a query, then opening the URLdash-workflow-callback://[value]will open the selected item in Dash.appordinal-- a value to sort by, currently this is the same value asdisplaydisplay-- a display valuekeyword-- the keyword (if there was one) on the query that returned this resultquery-- the full query that returned this result
If no items are returned from querying Dash, it will return a single item with an extra key, is_fallback = true. The table will look something like the following:
{
value = 'https://duckduckgo.com/?q=array.prototype.filter',
ordinal = '1',
display = 'Search with DuckDuckGo: array.prototype.filter',
is_fallback = true,
}
libdash_nvim.open_item (function)
Takes the value property of an item returned from querying Dash and opens it in Dash.
require('libdash_nvim').open_item(1)
Note: if running multiple queries, simply opening dash-workflow-callback://[value] may not work directly. Opening the URL assumes that the value being opened was returned by the currently active query in Dash.app. You can work around this by just running the query again with only the query value from the selected item, then calling require('libdash_nvim).open with that item's value.
libdash_nvim.open_search_engine (function)
Utility method to open a search engine URL when the fallback item is selected.
require('libdash_nvim').open_search_engine('https://duckduckgo.com/?q=array.prototype.filter')
Contributing
Git Hooks
If you plan on changing Rust code, you will need to install the git hooks via make install-hooks. The git hooks require you have a Rust toolchain installed. You can install a Rust toolchain from rustup.rs.
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.
To run tests, run make test. This runs tests in Neovim with a minimal profile, 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.
Code Style
Use snake_case for everything. Ensure you use EmmyLua Annotations for any public-facing API, and optionally for non-public functions, if the function is non-trivial or the types are not obvious. Other than that, running luacheck and stylua should cover it.
![[Enhancement] dash.nvim is 300mb+ (i.e. very large for a nvim plugin)](https://avatars.githubusercontent.com/u/22454918?v=4)
1 Dec 24, 2021
34 Mar 18, 2023
655 Jul 13, 2023
4 Aug 5, 2022
66 Apr 9, 2023
690 Jun 29, 2023
9.3k Jan 5, 2023
3 Mar 30, 2024
39 May 6, 2024
272 Dec 30, 2022
4 Mar 5, 2023
189 Jun 23, 2023
2 Oct 6, 2022
5 Jun 28, 2022
21 Dec 22, 2022
986 Dec 29, 2022
2 Dec 25, 2021
369 Jan 2, 2023