;;; 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

(set-buffer-multibyte t)

(setf (point) (point-min))

(when (search-forward-regexp "^$" nil t)

(buffer-substring (1+ (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