cheat.sh/share/emacs.txt

;;; cheat-sh.el --- Interact with cheat.sh  -*- lexical-binding: t -*-
;; Copyright 2017 by Dave Pearson <davep@davep.org>

;; Author: Dave Pearson <davep@davep.org>
;; Version: 1.7
;; Keywords: docs, help
;; URL: https://github.com/davep/cheat-sh.el
;; Package-Requires: ((emacs "24"))

;; cheat-sh.el is free software distributed under the terms of the GNU
;; General Public Licence, version 2 or (at your option) any later version.
;; For details see the file COPYING.

;;; Commentary:
;;
;; cheat-sh.el provides a simple Emacs interface for looking things up on
;; cheat.sh.

;;; Code:

(require 'url-vars)

(defgroup cheat-sh nil
  "Interact with cheat.sh."
  :group 'docs)

(defface cheat-sh-section
  '((t :inherit (bold font-lock-doc-face)))
  "Face used on sections in a cheat-sh output window."
  :group 'cheat-sh)

(defface cheat-sh-caption
  '((t :inherit (bold font-lock-function-name-face)))
  "Face used on captions in the cheat-sh output window."
  :group 'cheat-sh)

(defcustom cheat-sh-list-timeout (* 60 60 4)
  "Seconds to wait before deciding the cached sheet list is \"stale\"."
  :type 'integer
  :group 'cheat-sh)

(defconst cheat-sh-url "http://cheat.sh/%s?T"
  "URL for cheat.sh.")

(defconst cheat-sh-user-agent "cheat-sh.el (curl)"
  "User agent to send to cheat.sh.

Note that \"curl\" should ideally be included in the user agent
string because of the way cheat.sh works.

cheat.sh looks for a specific set of clients in the user
agent (see https://goo.gl/8gh95X for this) to decide if it should
deliver plain text rather than HTML. cheat-sh.el requires plain
text.")

(defun cheat-sh-get (thing)
  "Get THING from cheat.sh."
  (let* ((url-request-extra-headers `(("User-Agent" . ,cheat-sh-user-agent)))
         (buffer (url-retrieve-synchronously (format cheat-sh-url (url-hexify-string thing)) t t)))
    (when buffer
      (with-current-buffer buffer
        (setf (point) (point-min))
        (when (search-forward-regexp "^$" nil t)
          (buffer-substring (point) (point-max)))))))

(defvar cheat-sh-sheet-list nil
  "List of all available sheets.")

(defvar cheat-sh-sheet-list-acquired nil
  "The time when variable `cheat-sh-sheet-list' was populated.")

(defun cheat-sh-sheet-list-cache ()
  "Return the list of sheets.

The list is cached in memory, and is considered \"stale\" and is
refreshed after `cheat-sh-list-timeout' seconds."
  (when (and cheat-sh-sheet-list-acquired
             (> (- (time-to-seconds) cheat-sh-sheet-list-acquired) cheat-sh-list-timeout))
    (setq cheat-sh-sheet-list nil))
  (or cheat-sh-sheet-list
      (let ((list (cheat-sh-get ":list")))
        (when list
          (setq cheat-sh-sheet-list-acquired (time-to-seconds))
          (setq cheat-sh-sheet-list (split-string list "\n"))))))

(defun cheat-sh-read (prompt)
  "Read input from the user, showing PROMPT to prompt them.

This function is used by some `interactive' functions in
cheat-sh.el to get the item to look up. It provides completion
based of the sheets that are available on cheat.sh."
  (completing-read prompt (cheat-sh-sheet-list-cache)))

(defun cheat-sh-decorate-all (buffer regexp face)
  "Decorate BUFFER, finding REGEXP and setting face to FACE."
  (with-current-buffer buffer
    (save-excursion
      (setf (point) (point-min))
      (while (search-forward-regexp regexp nil t)
        (replace-match (propertize (match-string 1) 'font-lock-face face) nil t)))))

(defun cheat-sh-decorate-results (buffer)
  "Decorate BUFFER with properties to highlight results."
  ;; "[Search section]"
  (cheat-sh-decorate-all buffer "^\\(\\[.*\\]\\)$"        'cheat-sh-section)
  ;; "# Result caption"
  (cheat-sh-decorate-all buffer "^\\(#.*\\)$"             'cheat-sh-caption)
  ;; "cheat-sh help caption:"
  (cheat-sh-decorate-all buffer "^\\([^[:space:]].*:\\)$" 'cheat-sh-caption))

;;;###autoload
(defun cheat-sh (thing)
  "Look up THING on cheat.sh and display the result."
  (interactive (list (cheat-sh-read "Lookup: ")))
  (let ((result (cheat-sh-get thing)))
    (if result
        (with-help-window "*cheat.sh*"
          (princ result)
          (cheat-sh-decorate-results standard-output))
      (error "Can't find anything for %s on cheat.sh" thing))))

;;;###autoload
(defun cheat-sh-region (start end)
  "Look up the text between START and END on cheat.sh."
  (interactive "r")
  (deactivate-mark)
  (cheat-sh (buffer-substring-no-properties start end)))

;;;###autoload
(defun cheat-sh-maybe-region ()
  "If region is active lookup content of region, otherwise prompt."
  (interactive)
  (call-interactively (if mark-active #'cheat-sh-region #'cheat-sh)))

;;;###autoload
(defun cheat-sh-help ()
  "Get help on using cheat.sh."
  (interactive)
  (cheat-sh ":help"))

;;;###autoload
(defun cheat-sh-list (thing)
  "Get a list of topics available on cheat.sh.

Either gets a topic list for subject THING, or simply gets a list
of all available topics on cheat.sh if THING is supplied as an
empty string."
  (interactive (list (cheat-sh-read "List sheets for: ")))
  (cheat-sh (format "%s/:list" thing)))

;;;###autoload
(defun cheat-sh-search (thing)
  "Search for THING on cheat.sh and display the result."
  (interactive "sSearch: ")
  (cheat-sh (concat "~" thing)))

;;;###autoload
(defun cheat-sh-search-topic (topic thing)
  "Search TOPIC for THING on cheat.sh and display the result."
  (interactive
   (list (cheat-sh-read "Topic: ")
         (read-string "Search: ")))
  (cheat-sh (concat topic "/~" thing)))

(provide 'cheat-sh)

;;; cheat-sh.el ends here