Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mrjones2014/dash.nvim
🏃💨 Search Dash.app from your Neovim fuzzy finder. Built with Rust 🦀 and Lua
https://github.com/mrjones2014/dash.nvim
dash dash-integration documentation fzf fzf-lua hacktoberfest lua luajit neovim neovim-lua neovim-plugin nvim nvim-plugin nvim-telescope rust snap telescope vim-snap
Last synced: 13 days ago
JSON representation
🏃💨 Search Dash.app from your Neovim fuzzy finder. Built with Rust 🦀 and Lua
- Host: GitHub
- URL: https://github.com/mrjones2014/dash.nvim
- Owner: mrjones2014
- License: mpl-2.0
- Archived: true
- Created: 2021-09-23T13:19:14.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2022-08-30T00:29:47.000Z (about 2 years ago)
- Last Synced: 2024-08-01T19:57:08.576Z (3 months ago)
- Topics: dash, dash-integration, documentation, fzf, fzf-lua, hacktoberfest, lua, luajit, neovim, neovim-lua, neovim-plugin, nvim, nvim-plugin, nvim-telescope, rust, snap, telescope, vim-snap
- Language: Rust
- Homepage:
- Size: 185 MB
- Stars: 233
- Watchers: 5
- Forks: 16
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Dash.nvim is looking for a maintainer!
I don't use this plugin anymore and don't have time to maintain it. If you are interested in maintaining this repo, please open an issue or discussion!
 [](https://www.rust-lang.org) [](https://www.lua.org)
# Dash.nvim
Query [Dash.app](https://kapeli.com/dash) within Neovim with your fuzzy finder!
The theme used in the recording is [lighthaus.nvim](https://github.com/mrjones2014/lighthaus.nvim).
Note: Dash is a Mac-only app, so you'll only find this plugin useful on Mac.
## Install
This plugin must be loaded _after_ your fuzzy finder plugin of choice. Currently supported fuzzy finder plugins are:
- [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim)
- [fzf-lua](https://github.com/ibhagwan/fzf-lua)
- [snap](https://github.com/camspiers/snap)
After installing Dash.nvim, you must run `make install`. This can be done through a post-install hook with most plugin managers.
Packer:
```lua
use({
'mrjones2014/dash.nvim',
run = 'make install',
})
```
Paq:
```lua
require("paq")({
{ 'mrjones2014/dash.nvim', run = 'make install' };
})
```
Vim-Plug:
```VimL
Plug 'mrjones2014/dash.nvim', { 'do': 'make install' }
```
### Build From Source
If you prefer not to trust the binaries hosted in the repository, you can build from source. This requires installing
the latest stable Rust toolchain from [rustup.rs](https://rustup.rs). Once you have the Rust toolchain set up,
you can clone this repository, and run `make build-local install`. `make build-local` will auto-detect the host
machine's architecture and build for that target, and `make install` will copy the binaries into you Lua runtime
path. Once you've done this, you can install into Neovim by pointing your plugin manager to the local repository
path on disk instead of `mrjones2014/dash.nvim`.
## 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](#configuration)). The bang (`!`)
will search without this keyword filtering.
`:Dash [query]` will open the fuzzy finder, and if `[query]` is passed, it will pre-fill the prompt with `[query]`. This
is essentially an alias to `:lua require('dash').search(bang, [query])`.
`:DashWord` will open the fuzzy finder and pre-fill the prompt with the word under the cursor. This is essentially
an alias to `:lua require('dash').search(bang, )`.
The Lua function `require('dash').search()` will bind to the first supported fuzzy finder plugin it detects. Having multiple fuzzy finder
plugins installed will result in undefined behavior. You can use a specific fuzzy finder's provider directly via
`:lua require('dash.providers.telescope').dash({ bang = false, initial_text = '' })`, for example.
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 = '' })`.
If using Snap, you can also run `:lua require('dash.providers.snap').dash({ bang = false, initial_text = '' })`.
## Configuration
### Configuration Table Structure
```lua
{
-- 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/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
file_type_keywords = {
dashboard = false,
NvimTree = false,
TelescopePrompt = false,
terminal = false,
packer = false,
fzf = 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 config or would like a new file type added, please file an issue or submit a PR!
### With Telescope
```lua
require('telescope').setup({
extensions = {
dash = {
-- your config here
}
}
})
```
### With fzf-lua or Snap
```lua
require('dash').setup({
-- your config here
})
```
### Lua API
The public API consists of two main functions.
```lua
-- See src/lua_bindings/dash_config_binding.rs for available config keys
-- Also described in configuration section below
---@param config
require('dash').setup(config)
```
```lua
--- This will bind to the first fuzzy finder it finds to be available,
--- checked in order: telescope, fzf-lua
---@param bang boolean @bang searches without any filtering
---@param initial_text string @pre-fill text into the finder prompt
require('dash').search(bang, initial_text)
```
See [backend](#Backend) for documentation on the backend data provider.
## Backend
To build from source, you will need a Rust toolchain, which can be installed from [rustup.rs](https://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/lua_bindings/dash_config_binding.rs` or [configuration](#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:
```VimL
: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/lua_bindings/dash_config_binding.rs` or [configuration](#configuration) above
for configuration keys.
```lua
require('libdash_nvim').setup({
-- your custom configuration here
})
```
### `libdash_nvim.query` (function)
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!`)
```lua
local libdash = require('libdash_nvim')
local results = libdash.query({
search_text = 'match arms',
buffer_type = 'rust',
ignore_keywords = false
})
```
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
- `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 an extra key, `is_fallback = true`.
The table will look something like the following:
```lua
{
value = 'https://duckduckgo.com/?q=rust match arms',
ordinal = '1',
display = 'Search with DuckDuckGo: rust match arms',
keyword = 'rust',
query = 'rust:match arms',
is_fallback = true,
}
```
### `libdash_nvim.open_item` (function)
Takes an item returned from querying Dash via the `require('libdash_nvim').query` function and opens it in Dash.
```lua
local libdash = require('libdash_nvim')
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_url` (function)
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.
```lua
require('libdash_nvim').open_url('https://duckduckgo.com/?q=array.prototype.filter')
require('libdash_nvim').open_url('dash-workflow-callback://5')
```
---
## 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](https://rustup.rs).
### Developing Locally
The best way to develop and test locally is to install the plugin from a locally cloned repository.
If you're using Packer, you can just do:
```lua
use({
'~/git/dash.nvim', -- or whatever your local path is
run = 'make install',
})
```
Otherwise you can add it manually via:
```lua
vim.opt.runtimepath:append('~/git/dash.nvim') -- or whatever your local path is
```
There is also a `make dev` task which will set the `$DASH_NVIM_DEV` environment variable and open `nvim` for you.
When the `$DASH_NVIM_DEV` environment variable is set, there will be an extra command available, `:DashDevReload`.
This will reload Telescope, fzf-lua, and Snap (whichever ones you have installed), as well as the `dash` and `libdash_nvim`
Lua modules.
To recompile the Rust backend for your machine's CPU architecture and install the module, run `make build-local install`.
`make build-local` will auto-detect your machine's architecture and build for that target, and `make install` will copy
the compiled binaries into your Lua runtime path.
### Running Tests
You can run all tests (both Rust and Lua) with `make test`.
#### Lua Tests
This uses [busted](https://github.com/Olivine-Labs/busted), [luassert](https://github.com/Olivine-Labs/luassert) (both through
[plenary.nvim](https://github.com/nvim-lua/plenary.nvim)) and [matcher_combinators](https://github.com/m00qek/matcher_combinators.lua) 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)](https://eradman.com/entrproject/) installed, you can run the tests in watch mode
using `make watch`.
#### 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 with `luacheck` and `stylua`. Only
presentation-layer code (such as providers 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](https://github.com/rust-analyzer/rust-analyzer),
and linted using [clippy](https://github.com/rust-lang/rust-clippy), which can be run via `make lint-rust`.