├── .gitignore ├── misc └── helm-dash.gif ├── .travis.yml ├── helm-dash.el └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | /.cask -------------------------------------------------------------------------------- /misc/helm-dash.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/dash-docs-el/helm-dash/HEAD/misc/helm-dash.gif -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: generic 2 | before_install: 3 | - curl -fsSkL https://gist.github.com/rejeep/ebcd57c3af83b049833b/raw > x.sh && source ./x.sh 4 | - evm install $EVM_EMACS --use --skip 5 | - emacs --version 6 | # Fix cask (See https://github.com/cask/cask/issues/399#issuecomment-331640427) 7 | - perl -ibak -lape 's{#!/usr/bin/env python}{#!/usr/bin/python}' "$(which cask)" 8 | - cask exec emacs --version 9 | - cask install 10 | env: 11 | - EVM_EMACS=emacs-24.4-travis 12 | - EVM_EMACS=emacs-24.5-travis 13 | - EVM_EMACS=emacs-25.1-travis 14 | - EVM_EMACS=emacs-25.2-travis 15 | - EVM_EMACS=emacs-25.3-travis 16 | script: 17 | - make test 18 | -------------------------------------------------------------------------------- /helm-dash.el: -------------------------------------------------------------------------------- 1 | ;;; helm-dash.el --- Offline documentation browser for +150 APIs using Dash docsets. -*- lexical-binding: t; -*- 2 | ;; Copyright (C) 2013-2014 Raimon Grau 3 | ;; Copyright (C) 2013-2014 Toni Reina 4 | 5 | ;; Author: Raimon Grau 6 | ;; Toni Reina 7 | ;; Bryan Gilbert 8 | ;; 9 | ;; URL: https://github.com/dash-docs-el/helm-dash 10 | ;; Version: 1.3.0 11 | ;; Package-Requires: ((emacs "24.4") (dash-docs "1.4.0") (helm "1.9.2") (cl-lib "0.5")) 12 | ;; Keywords: docs 13 | 14 | ;; This program is free software; you can redistribute it and/or modify 15 | ;; it under the terms of the GNU General Public License as published by 16 | ;; the Free Software Foundation, either version 3 of the License, or 17 | ;; (at your option) any later version. 18 | 19 | ;; This program is distributed in the hope that it will be useful, 20 | ;; but WITHOUT ANY WARRANTY; without even the implied warranty of 21 | ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 22 | ;; GNU General Public License for more details. 23 | 24 | ;; You should have received a copy of the GNU General Public License 25 | ;; along with this program. If not, see . 26 | ;; 27 | ;;; Commentary: 28 | ;; 29 | ;; Clone the functionality of dash using helm foundation. Browse 30 | ;; documentation via dash docsets. 31 | ;; 32 | ;; M-x helm-dash 33 | ;; M-x helm-dash-at-point 34 | ;; 35 | ;; More info in the project site https://github.com/areina/helm-dash 36 | ;; 37 | ;;; Code: 38 | 39 | (eval-when-compile (require 'cl)) 40 | (require 'dash-docs) 41 | (require 'helm) 42 | (require 'helm-multi-match) 43 | 44 | ;;; Customize 45 | 46 | (defgroup helm-dash nil 47 | "Search Dash docsets using helm." 48 | :prefix "helm-dash-" 49 | :group 'applications) 50 | 51 | 52 | (defvaralias 'helm-dash-docsets-path 'dash-docs-docsets-path) 53 | (defvaralias 'helm-dash-docsets-url 'dash-docs-docsets-url) 54 | (defvaralias 'helm-dash-min-length 'dash-docs-min-length) 55 | (defvaralias 'helm-dash-candidate-format 'dash-docs-candidate-format) 56 | (defvaralias 'helm-dash-enable-debugging 'dash-docs-enable-debugging) 57 | (defvaralias 'helm-dash-browser-func 'dash-docs-browser-func) 58 | (defvaralias 'helm-dash-common-docsets 'dash-docs-common-docsets) 59 | (defvaralias 'helm-dash-ignored-docsets 'dash-docs-ignored-docsets) 60 | 61 | (defalias 'helm-dash--candidate 'dash-docs--candidate) 62 | (defalias 'helm-dash--run-query 'dash-docs--run-query) 63 | (defalias 'helm-dash-actions 'dash-docs-actions) 64 | (defalias 'helm-dash-activate-docset 'dash-docs-activate-docset) 65 | (defalias 'helm-dash-create-buffer-connections 'dash-docs-create-buffer-connections) 66 | (defalias 'helm-dash-create-common-connections 'dash-docs-create-common-connections) 67 | (defalias 'helm-dash-deactivate-docset 'dash-docs-deactivate-docset) 68 | (defalias 'helm-dash-initialize-debugging-buffer 'dash-docs-initialize-debugging-buffer) 69 | (defalias 'helm-dash-install-docset 'dash-docs-install-docset) 70 | (defalias 'helm-dash-install-docset-from-file 'dash-docs-install-docset-from-file) 71 | (defalias 'helm-dash-installed-docsets 'dash-docs-installed-docsets) 72 | (defalias 'helm-dash-install-user-docset 'dash-docs-install-user-docset) 73 | (defalias 'helm-dash-maybe-narrow-docsets 'dash-docs-maybe-narrow-docsets) 74 | (defalias 'helm-dash-reset-connections 'dash-docs-reset-connections) 75 | 76 | (defvar helm-dash-history-input nil) 77 | 78 | (defun helm-dash-search () 79 | "Iterates every `helm-dash-connections' looking for the `helm-pattern'." 80 | (let ((connections (helm-dash-maybe-narrow-docsets helm-pattern))) 81 | (cl-loop for docset in connections 82 | append (cl-loop for row in (helm-dash--run-query docset helm-pattern) 83 | collect (helm-dash--candidate docset row))))) 84 | 85 | (make-obsolete #'helm-dash-search nil "1.3.0") 86 | 87 | (defun helm-dash--build-source (docset) 88 | "Build a Helm source for DOCSET." 89 | (lexical-let ((docset docset)) 90 | (helm-build-sync-source (car docset) 91 | :action-transformer #'helm-dash-actions 92 | :candidates (lambda () 93 | (cl-loop for row in (helm-dash--run-query docset helm-pattern) 94 | collect (helm-dash--candidate docset row))) 95 | :volatile t 96 | :persistent-help "View doc" 97 | :requires-pattern helm-dash-min-length))) 98 | 99 | (defun helm-dash--sources-narrowed-docsets () 100 | "Return a list of Helm sources for narrowed docsets. 101 | 102 | Narrowed docsets are those returned by 103 | `helm-dash-maybe-narrow-docsets'." 104 | (let ((connections (helm-dash-maybe-narrow-docsets helm-pattern))) 105 | (cl-loop for docset in connections 106 | append (list (helm-dash--build-source docset))))) 107 | 108 | ;;; Autoloads 109 | 110 | ;;;###autoload 111 | (defun helm-dash (&optional input-pattern) 112 | "Bring up a `helm-dash' search interface. 113 | If INPUT-PATTERN is non-nil, use it as an initial input in helm search." 114 | (interactive) 115 | (helm-dash-initialize-debugging-buffer) 116 | (helm-dash-create-common-connections) 117 | (helm-dash-create-buffer-connections) 118 | (helm :sources (helm-dash--sources-narrowed-docsets) 119 | :buffer "*helm-dash*" 120 | :prompt "Doc for: " 121 | :history 'helm-dash-history-input 122 | :input input-pattern 123 | :helm-candidate-number-limit 1000)) 124 | 125 | ;;;###autoload 126 | (defun helm-dash-at-point () 127 | "Bring up a `helm-dash' search interface with symbol at point." 128 | (interactive) 129 | (helm-dash 130 | (substring-no-properties (or (thing-at-point 'symbol) "")))) 131 | 132 | (provide 'helm-dash) 133 | 134 | ;;; helm-dash.el ends here 135 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Helm Dash 2 | 3 | [![Build Status](https://api.travis-ci.org/areina/helm-dash.svg?branch=master)](http://travis-ci.org/areina/helm-dash) 4 | [![Coverage Status](https://img.shields.io/coveralls/areina/helm-dash.svg)](https://coveralls.io/r/areina/helm-dash?branch=master) 5 | [![MELPA](http://melpa.org/packages/helm-dash-badge.svg)](http://melpa.org/#/helm-dash) 6 | [![MELPA Stable](http://stable.melpa.org/packages/helm-dash-badge.svg)](http://stable.melpa.org/#/helm-dash) 7 | [![Tag Version](https://img.shields.io/github/tag/areina/helm-dash.svg)](https://github.com/areina/helm-dash/tags) 8 | [![License](http://img.shields.io/:license-gpl3-blue.svg)](http://www.gnu.org/licenses/gpl-3.0.html) 9 | 10 | ## What's it 11 | 12 | This package uses [Dash](http://www.kapeli.com/dash) docsets inside 13 | emacs to browse documentation. Here's an 14 | [article](http://puntoblogspot.blogspot.com.es/2014/01/ann-helm-dash-documentation-browser-for.html) 15 | explaining the basic usage of it. 16 | 17 | It doesn't require Dash app. 18 | 19 | ![](https://raw.github.com/areina/helm-dash/master/misc/helm-dash.gif) 20 | 21 | ## What's not 22 | 23 | If you're looking for dash.el, the list library, please go to 24 | [dash.el](http://www.github.com/magnars/dash.el) 25 | 26 | 27 | ## Requirements 28 | 29 | - [helm](https://github.com/emacs-helm/helm) 30 | - sqlite3 31 | 32 | ## Installation 33 | 34 | It's available on [MELPA](https://melpa.org). 35 | 36 | Now, it's possible to choose between install the stable or development version 37 | of helm-dash. [Here](https://github.com/milkypostman/melpa#stable-packages) 38 | there is an explanation about stable packages and MELPA and 39 | [here](https://github.com/areina/helm-dash/tags) a list of our tags. 40 | 41 | `m-x package-install helm-dash RET` 42 | 43 | 44 | ## Installing docsets 45 | 46 | Helm-dash uses the same docsets as [Dash](http://www.kapeli.com/dash). 47 | You can install them with `m-x helm-dash-install-docset` for the 48 | official docsets or `m-x helm-dash-install-user-docset` for user 49 | contributed docsets (experimental). 50 | 51 | To install a docset from a file in your drive you can use `m-x 52 | helm-dash-install-docset-from-file'. That function takes as input 53 | a `tgz` file that you obtained, starting from a folder named `.docset`, with the command: 55 | 56 | `tar --exclude='.DS_Store' -cvzf .tgz .docset` 57 | 58 | as explained [here](https://kapeli.com/docsets#dashdocsetfeed). 59 | 60 | ## Usage 61 | 62 | `m-x helm-dash RET` will run helm with your active docsets 63 | loaded. Typing substrings of what you search will find-as-you-type. 64 | 65 | - The search starts from 3 chars. 66 | - Install new docsets with m-x helm-dash-install-docset 67 | - After installing a new docset, add the name of the docset to 68 | `helm-dash-common-docsets' or in 'helm-dash-docsets' (which is ment 69 | to be buffer local) 70 | 71 | `m-x helm-dash-at-point RET` is like helm-dash, but it will prefill 72 | the search input with the symbol at point. 73 | 74 | The command `helm-dash-reset-connections` will clear the connections 75 | to all sqlite db's. Use it in case of errors when adding new docsets. 76 | The next call to `helm-dash` will recreate them. 77 | 78 | ## Variables to customize 79 | 80 | `helm-dash-docsets-path` is the prefix for your docsets. Defaults to ~/.docsets 81 | 82 | `helm-dash-min-length` tells helm-dash from which length to start 83 | searching. Defaults to 3. 84 | 85 | `helm-dash-browser-func` is a function to encapsulate the way to browse 86 | Dash' docsets. Defaults to browse-url. For example, if you want to use eww to 87 | browse your docsets, you can do: `(setq helm-dash-browser-func 'eww)`. 88 | 89 | When `helm-dash-enable-debugging` is non-nil stderr from sqlite queries is 90 | captured and displayed in a buffer. The default value is `t`. Setting this 91 | to `nil` may speed up queries on some machines (capturing stderr requires 92 | the creation and deletion of a temporary file for each query). 93 | 94 | 95 | ## Sets of Docsets 96 | 97 | ### Common docsets 98 | 99 | `helm-dash-common-docsets' is a list that should contain the docsets 100 | to be active always. In all buffers. 101 | 102 | ### Buffer local docsets 103 | 104 | Different subsets of docsets can be activated depending on the 105 | buffer. For the moment (it may change in the future) we decided it's a 106 | plain local variable you should setup for every different 107 | filetype. This way you can also do fancier things like project-wise 108 | docsets sets. 109 | 110 | ``` elisp 111 | (defun go-doc () 112 | (interactive) 113 | (setq-local dash-docs-docsets '("Go"))) 114 | 115 | (add-hook 'go-mode-hook 'go-doc) 116 | ``` 117 | 118 | ### Only one docset 119 | 120 | To narrow the search to just one docset, type its name in the 121 | beginning of the search followed by a space. If the docset contains 122 | spaces, no problemo, we handle it :D. 123 | 124 | ## FAQ 125 | 126 | - Does it work in osX? 127 | 128 | sqlite queries. Provisionally, we're executing shell-commands directly. Our 129 | idea is come back to use [esqlite](http://www.github.com/mhayashi1120/Emacs-esqlite) 130 | when some issues will be fixed. 131 | 132 | helm-dash has been tested only in linux. We've been notified that it 133 | doesn't work in Mac, so we ask for elisp hackers who own something 134 | that runs Mac OSX if they could take a look at it. 135 | 136 | Hints: It looks like something with 'end of line' differences. The 137 | suspicious are 138 | [esqlite](http://www.github.com/mhayashi1120/Emacs-esqlite) (which 139 | helm-dash requires) or 140 | [pcsv](http://www.github.com/mhayashi1120/Emacs-pcsv) (which esqlite 141 | requires) 142 | 143 | - I'm using mac osx and pages open but not in the correct anchor 144 | 145 | [bug on **mac osx**'s browse-url](https://github.com/areina/helm-dash/issues/36) 146 | which can't open urls with #. If you find this issue, and want to 147 | debug, great, otherwise, you can use eww or w3 or w3m which will work 148 | just fine 149 | 150 | - I get nil for every search I do 151 | 152 | make sure you don't have sqlite3 .mode column but .mode list (the default). check your .sqliterc 153 | 154 | - When selecting an item in helm-dash, no browser lookup occurs with firefox >= 38.0.and emacs >= 24.4 155 | 156 | try: 157 | ``` 158 | (setq browse-url-browser-function 'browse-url-generic 159 | browse-url-generic-program "/path/to/firefox") 160 | (setq helm-dash-browser-func 'browse-url-generic) 161 | ``` 162 | 163 | 164 | ## Contribution 165 | 166 | We ♥ feedback, issues or pull requests. Feel free to contribute in helm-dash. 167 | 168 | We're trying to add tests to the project, if you send a PR please consider add 169 | new or update the existing ones. 170 | 171 | Install [Cask](https://github.com/cask/cask) if you haven't already, then: 172 | 173 | $ cd /path/to/helm-dash 174 | $ cask 175 | 176 | Run all tests with: 177 | 178 | $ make 179 | 180 | 181 | ## Authors 182 | 183 | - Toni Reina 184 | - Raimon Grau 185 | --------------------------------------------------------------------------------