ffd9ffc537
This ensures that the status is evaluated in the buffer where help was invoked, rather than in the helm buffer.
391 lines
16 KiB
EmacsLisp
391 lines
16 KiB
EmacsLisp
;;; helm-spacemacs-help.el --- Spacemacs layer exploration with `helm'.
|
|
|
|
;; Author: Sylvain Benner <sylvain.benner@gmail.com>
|
|
;; Keywords: helm, spacemacs
|
|
;; Version: 0.1
|
|
;; Package-Requires: ((helm "1.5"))
|
|
|
|
;; This file is free software; you can redistribute it and/or modify
|
|
;; it under the terms of the GNU General Public License as published by
|
|
;; the Free Software Foundation; either version 3, or (at your option)
|
|
;; any later version.
|
|
|
|
;; This file is distributed in the hope that it will be useful,
|
|
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
;; GNU General Public License for more details.
|
|
|
|
;; You should have received a copy of the GNU General Public License
|
|
;; along with GNU Emacs; see the file COPYING. If not, write to
|
|
;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
|
|
;; Boston, MA 02110-1301, USA.
|
|
|
|
;;; Commentary:
|
|
;; This package adds a convenient way to discover Spacemacs configuration
|
|
;; layers thanks to helm.
|
|
|
|
;;; Code:
|
|
|
|
(require 'cl)
|
|
(require 'ht)
|
|
(require 'helm)
|
|
(require 'helm-command)
|
|
(require 'helm-org)
|
|
(require 'core-configuration-layer)
|
|
|
|
(defvar helm-spacemacs-help-all-layers nil
|
|
"Alist of all configuration layers.")
|
|
|
|
(defvar helm-spacemacs-help-all-packages nil
|
|
"Hash table of all packages in all layers.")
|
|
|
|
;;;###autoload
|
|
(define-minor-mode helm-spacemacs-help-mode
|
|
"Layers discovery with helm interface."
|
|
:group 'spacemacs
|
|
:global t)
|
|
|
|
(defun helm-spacemacs-help//init (&optional arg)
|
|
(when (or arg (null helm-spacemacs-help-all-packages))
|
|
(mapc (lambda (layer) (push (configuration-layer/make-layer layer)
|
|
helm-spacemacs-help-all-layers))
|
|
(configuration-layer/get-layers-list))
|
|
(let (configuration-layer--packages)
|
|
(configuration-layer/get-packages helm-spacemacs-help-all-layers)
|
|
(setq helm-spacemacs-help-all-packages configuration-layer--packages))))
|
|
|
|
;;;###autoload
|
|
(defun helm-spacemacs-help (arg)
|
|
"Layers discovery with helm interface."
|
|
(interactive "P")
|
|
(helm-spacemacs-help-mode)
|
|
(helm-spacemacs-help//init arg)
|
|
(helm :buffer "*helm: spacemacs*"
|
|
:sources `(,(helm-spacemacs-help//documentation-source)
|
|
,(helm-spacemacs-help//layer-source)
|
|
,(helm-spacemacs-help//package-source)
|
|
,(helm-spacemacs-help//dotspacemacs-source)
|
|
,(helm-spacemacs-help//toggle-source)
|
|
,(helm-spacemacs-help//faq-source))))
|
|
|
|
;;;###autoload
|
|
(defun helm-spacemacs-help-dotspacemacs ()
|
|
"Helm session to search for dotfile variables."
|
|
(interactive)
|
|
(helm-spacemacs-help-mode)
|
|
(helm :buffer "*helm: spacemacs*"
|
|
:sources `(,(helm-spacemacs-help//dotspacemacs-source))))
|
|
|
|
;;;###autoload
|
|
(defun helm-spacemacs-help-layers ()
|
|
"Helm session to search for layers."
|
|
(interactive)
|
|
(helm-spacemacs-help-mode)
|
|
(helm :buffer "*helm: spacemacs*"
|
|
:sources `(,(helm-spacemacs-help//layer-source))))
|
|
|
|
;;;###autoload
|
|
(defun helm-spacemacs-help-packages (arg)
|
|
"Helm session to search for packages."
|
|
(interactive "P")
|
|
(helm-spacemacs-help-mode)
|
|
(helm-spacemacs-help//init arg)
|
|
(helm :buffer "*helm: spacemacs*"
|
|
:sources `(,(helm-spacemacs-help//package-source))))
|
|
|
|
;;;###autoload
|
|
(defun helm-spacemacs-help-docs ()
|
|
"Helm session to search for documentation."
|
|
(interactive)
|
|
(helm-spacemacs-help-mode)
|
|
(helm :buffer "*helm: spacemacs*"
|
|
:sources `(,(helm-spacemacs-help//documentation-source))))
|
|
|
|
;;;###autoload
|
|
(defun helm-spacemacs-help-toggles ()
|
|
"Helm session to search for toggles."
|
|
(interactive)
|
|
(helm-spacemacs-help-mode)
|
|
(helm :buffer "*helm: spacemacs*"
|
|
:sources `(,(helm-spacemacs-help//toggle-source))))
|
|
|
|
;;;###autoload
|
|
(defun helm-spacemacs-help-faq ()
|
|
"Helm session to search for the FAQ."
|
|
(interactive)
|
|
(helm-spacemacs-help-mode)
|
|
(helm :buffer "*helm: spacemacs*"
|
|
:sources `(,(helm-spacemacs-help//faq-source))))
|
|
|
|
(defun helm-spacemacs-help//documentation-source ()
|
|
"Construct the helm source for the documentation section."
|
|
(helm-build-sync-source "Spacemacs Documentation"
|
|
:candidates #'helm-spacemacs-help//documentation-candidates
|
|
:persistent-action #'helm-spacemacs-help//documentation-action-open-file
|
|
:keymap helm-map
|
|
:action (helm-make-actions
|
|
"Open Documentation" #'helm-spacemacs-help//documentation-action-open-file)))
|
|
|
|
(defun helm-spacemacs-help//documentation-candidates ()
|
|
(let (result file-extension)
|
|
(dolist (filename (directory-files spacemacs-docs-directory))
|
|
(setq file-extension (file-name-extension filename))
|
|
(when (or (equal file-extension "md")
|
|
(equal file-extension "org"))
|
|
(push filename result)))
|
|
|
|
;; CONTRIBUTING.org is a special case as it should be at the root of the
|
|
;; repository to be linked as the contributing guide on Github.
|
|
(push "CONTRIBUTING.org" result)
|
|
|
|
;; delete DOCUMENTATION.org to make it the first guide
|
|
(delete "DOCUMENTATION.org" result)
|
|
(push "DOCUMENTATION.org" result)
|
|
|
|
;; give each document an appropriate title
|
|
(mapcar (lambda (r)
|
|
(cond
|
|
((string-equal r "CONTRIBUTING.org")
|
|
`("How to contribute to Spacemacs" . ,r))
|
|
((string-equal r "CONVENTIONS.org")
|
|
`("Spacemacs conventions" . ,r))
|
|
((string-equal r "DOCUMENTATION.org")
|
|
`("Spacemacs documentation" . ,r))
|
|
((string-equal r "FAQ.org")
|
|
`("Spacemacs FAQ" . ,r))
|
|
((string-equal r "LAYERS.org")
|
|
`("Tips on writing layers for Spacemacs" . ,r))
|
|
((string-equal r "QUICK_START.org")
|
|
`("Quick start guide for Spacemacs" . ,r))
|
|
((string-equal r "VIMUSERS.org")
|
|
`("Vim users migration guide" . ,r))
|
|
(t
|
|
`(,r . ,r))))
|
|
result)))
|
|
|
|
(defun helm-spacemacs-help//documentation-action-open-file (candidate)
|
|
"Open documentation FILE."
|
|
(let ((file (if (string= candidate "CONTRIBUTING.org")
|
|
;; CONTRIBUTING.org is a special case as it should be at the
|
|
;; root of the repository to be linked as the contributing
|
|
;; guide on Github.
|
|
(concat user-emacs-directory candidate)
|
|
(concat spacemacs-docs-directory candidate))))
|
|
(cond ((and (equal (file-name-extension file) "md")
|
|
(not helm-current-prefix-arg))
|
|
(condition-case-unless-debug nil
|
|
(with-current-buffer (find-file-noselect file)
|
|
(gh-md-render-buffer)
|
|
(kill-this-buffer))
|
|
;; if anything fails, fall back to simply open file
|
|
(find-file file)))
|
|
((equal (file-name-extension file) "org")
|
|
(spacemacs/view-org-file file "^" 'all))
|
|
(t
|
|
(find-file file)))))
|
|
|
|
(defun helm-spacemacs-help//layer-source ()
|
|
"Construct the helm source for the layer section."
|
|
`((name . "Layers")
|
|
(candidates . ,(sort (configuration-layer/get-layers-list) 'string<))
|
|
(candidate-number-limit)
|
|
(keymap . ,helm-spacemacs-help--layer-map)
|
|
(action . (("Open README.org"
|
|
. helm-spacemacs-help//layer-action-open-readme)
|
|
("Open packages.el"
|
|
. helm-spacemacs-help//layer-action-open-packages)
|
|
("Install Layer"
|
|
. helm-spacemacs-help//layer-action-install-layer)
|
|
("Open README.org (for editing)"
|
|
. helm-spacemacs-help//layer-action-open-readme-edit)))))
|
|
|
|
(defvar helm-spacemacs-help--layer-map
|
|
(let ((map (make-sparse-keymap)))
|
|
(set-keymap-parent map helm-map)
|
|
(define-key map (kbd "<S-return>") '(lambda () (interactive)
|
|
;; Add Layer
|
|
(helm-select-nth-action 3)))
|
|
map)
|
|
"Keymap for Spacemacs Layers sources")
|
|
|
|
(defun helm-spacemacs-help//package-source ()
|
|
"Construct the helm source for the packages."
|
|
`((name . "Packages")
|
|
(candidates . ,(helm-spacemacs-help//package-candidates))
|
|
(candidate-number-limit)
|
|
(action . (("Go to init function"
|
|
. helm-spacemacs-help//package-action-goto-init-func)
|
|
("Describe"
|
|
. helm-spacemacs-help//package-action-decribe)))))
|
|
|
|
(defun helm-spacemacs-help//package-candidates ()
|
|
"Return the sorted candidates for package source."
|
|
(let (result)
|
|
(dolist (pkg helm-spacemacs-help-all-packages)
|
|
(push (format "%s (%S layer)"
|
|
(propertize (symbol-name (oref pkg :name))
|
|
'face 'font-lock-type-face)
|
|
(oref pkg :owner))
|
|
result))
|
|
(sort result 'string<)))
|
|
|
|
(defun helm-spacemacs-help//toggle-source ()
|
|
"Construct the helm source for the toggles."
|
|
(let ((candidates (helm-spacemacs-help//toggle-candidates)))
|
|
(helm-build-sync-source "Toggles"
|
|
:candidates candidates
|
|
:persistent-action #'helm-spacemacs-help//toggle
|
|
:keymap helm-map
|
|
:action (helm-make-actions "Toggle" #'helm-spacemacs-help//toggle))))
|
|
|
|
(defun helm-spacemacs-help//toggle-candidates ()
|
|
"Return the sorted candidates for toggle source."
|
|
(let (result)
|
|
(dolist (toggle spacemacs-toggles)
|
|
(let* ((toggle-symbol (symbol-name (car toggle)))
|
|
(toggle-status (funcall (plist-get (cdr toggle) :predicate)))
|
|
(toggle-name (capitalize (replace-regexp-in-string "-" " " toggle-symbol)))
|
|
(toggle-doc (format "(%s) %s: %s"
|
|
(if toggle-status "+" "-")
|
|
toggle-name
|
|
(propertize
|
|
(or (plist-get (cdr toggle) :documentation) "")
|
|
'face 'font-lock-doc-face))))
|
|
(when (plist-member (cdr toggle) :evil-leader)
|
|
(let ((key (key-description
|
|
(kbd (concat dotspacemacs-leader-key " "
|
|
(plist-get (cdr toggle) :evil-leader))))))
|
|
(setq toggle-doc
|
|
(format "%s (%s)"
|
|
toggle-doc
|
|
(propertize key 'face 'helm-M-x-key)))))
|
|
(if (plist-member (cdr toggle) :documentation)
|
|
(push `(,toggle-doc . ,toggle-symbol) result)
|
|
(push `(,toggle-name . ,toggle-symbol) result))))
|
|
(setq result (cl-sort result 'string< :key 'car))
|
|
result))
|
|
|
|
(defun helm-spacemacs-help//dotspacemacs-source ()
|
|
`((name . "Dotfile")
|
|
(candidates . ,(helm-spacemacs-help//dotspacemacs-candidates))
|
|
(candidate-number-limit)
|
|
(action . (("Go to variable" . helm-spacemacs-help//go-to-dotfile-variable)))))
|
|
|
|
(defun helm-spacemacs-help//dotspacemacs-candidates ()
|
|
"Return the sorted candidates for all the dospacemacs variables."
|
|
(sort (dotspacemacs/get-variable-string-list) 'string<))
|
|
|
|
(defun helm-spacemacs-help//layer-action-open-file (file candidate &optional edit)
|
|
"Open FILE of the passed CANDIDATE. If EDIT is false, open in view mode."
|
|
(let ((path (if (and (equalp file "README.org") (equalp candidate "spacemacs"))
|
|
;; Readme for spacemacs is in the project root
|
|
(ht-get configuration-layer-paths (intern candidate))
|
|
(file-name-as-directory
|
|
(concat (ht-get configuration-layer-paths
|
|
(intern candidate))
|
|
candidate)))))
|
|
(if (and (equal (file-name-extension file) "org")
|
|
(not helm-current-prefix-arg))
|
|
(if edit
|
|
(find-file (concat path file))
|
|
(spacemacs/view-org-file (concat path file) "^" 'all))
|
|
(find-file (concat path file)))))
|
|
|
|
(defun helm-spacemacs-help//layer-action-open-readme (candidate)
|
|
"Open the `README.org' file of the passed CANDIDATE for reading."
|
|
(helm-spacemacs-help//layer-action-open-file "README.org" candidate))
|
|
|
|
(defun helm-spacemacs-help//layer-action-install-layer (candidate-layer)
|
|
"Add CANDIDATE-LAYER to dotspacemacs file and reloads configuration"
|
|
(when (dotspacemacs/add-layer (intern candidate-layer))
|
|
(dotspacemacs/sync-configuration-layers)))
|
|
|
|
(defun helm-spacemacs-help//layer-action-open-readme-edit (candidate)
|
|
"Open the `README.org' file of the passed CANDIDATE for editing."
|
|
(helm-spacemacs-help//layer-action-open-file "README.org" candidate t))
|
|
|
|
(defun helm-spacemacs-help//layer-action-open-packages (candidate)
|
|
"Open the `packages.el' file of the passed CANDIDATE."
|
|
(helm-spacemacs-help//layer-action-open-file "packages.el" candidate))
|
|
|
|
(defun helm-spacemacs-help//package-action-decribe (candidate)
|
|
"Describe the passed package using Spacemacs describe function."
|
|
(save-match-data
|
|
(string-match "^\\(.+\\)\s(\\(.+\\) layer)$" candidate)
|
|
(let* ((package (match-string 1 candidate)))
|
|
(configuration-layer/describe-package (intern package)))))
|
|
|
|
(defun helm-spacemacs-help//package-action-goto-init-func (candidate)
|
|
"Open the file `packages.el' and go to the init function."
|
|
(save-match-data
|
|
(string-match "^\\(.+\\)\s(\\(.+\\) layer)$" candidate)
|
|
;; (string-match "^(\\(.+\\))\s\\(.+\\):\s\\(.+\\)$" candidate)
|
|
(let* ((package (match-string 1 candidate))
|
|
(layer (match-string 2 candidate))
|
|
(path (file-name-as-directory
|
|
(concat (ht-get configuration-layer-paths (intern layer))
|
|
layer)))
|
|
(filename (concat path "packages.el")))
|
|
(find-file filename)
|
|
(goto-char (point-min))
|
|
(re-search-forward (format "init-%s" package))
|
|
(beginning-of-line))))
|
|
|
|
(defun helm-spacemacs-help//toggle (candidate)
|
|
"Toggle candidate."
|
|
(let ((toggle (assq (intern candidate) spacemacs-toggles)))
|
|
(when toggle
|
|
(funcall (plist-get (cdr toggle) :function)))))
|
|
|
|
(defun helm-spacemacs-help//go-to-dotfile-variable (candidate)
|
|
"Go to candidate in the dotfile."
|
|
(find-file dotspacemacs-filepath)
|
|
(goto-char (point-min))
|
|
;; try to exclude comments
|
|
(re-search-forward (format "^[a-z\s\\(\\-]*%s" candidate))
|
|
(beginning-of-line))
|
|
|
|
(defvar helm-spacemacs-help--faq-filename
|
|
(concat spacemacs-docs-directory "FAQ.org")
|
|
"Location of the FAQ file.")
|
|
|
|
(defun helm-spacemacs-help//faq-source ()
|
|
"Construct the helm source for the FAQ."
|
|
`((name . "FAQ")
|
|
(candidates . ,(helm-spacemacs-help//faq-candidates))
|
|
(candidate-number-limit)
|
|
(action . (("Go to question" . helm-spacemacs-help//faq-goto-marker)))))
|
|
|
|
(defun helm-spacemacs-help//faq-candidate (cand)
|
|
(let ((str (substring-no-properties (car cand))))
|
|
(when (string-match "\\`.*/\\([^/]*\\)/\\(.*\\)\\'" str)
|
|
(cons (concat (propertize
|
|
(match-string 1 str)
|
|
'face 'font-lock-type-face)
|
|
": " (match-string 2 str))
|
|
(cdr cand)))))
|
|
|
|
(defun helm-spacemacs-help//faq-candidates ()
|
|
(let* ((helm-org-format-outline-path nil)
|
|
(cands (helm-org-get-candidates (list helm-spacemacs-help--faq-filename)))
|
|
section result)
|
|
(dolist (c cands)
|
|
(let ((str (substring-no-properties (car c))))
|
|
(when (string-match "\\`\\* \\(.*\\)\\'" str)
|
|
(setq section (match-string 1 str)))
|
|
(when (string-match "\\`\\*\\* \\(.*\\)\\'" str)
|
|
(push (cons (concat (propertize section 'face 'font-lock-type-face)
|
|
": " (match-string 1 str))
|
|
(cdr c))
|
|
result))))
|
|
result))
|
|
|
|
(defun helm-spacemacs-help//faq-goto-marker (marker)
|
|
(find-file helm-spacemacs-help--faq-filename)
|
|
(goto-char marker)
|
|
(org-show-context)
|
|
(org-show-entry))
|
|
|
|
(provide 'helm-spacemacs-help)
|
|
|
|
;;; helm-spacemacs-help.el ends here
|