;; cheat.el
;; Time-stamp: <2007-08-22 10:00:04 sjs>
;;
;; Copyright (c) 2007 Sami Samhuri <sami.samhuri@gmail.com>
;;
;; See http://sami.samhuri.net/2007/08/10/cheat-from-emacs for updates.
;;
;; License
;;
;; This program 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 2
;; of the License, or (at your option) any later version.
;;
;; This program 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 this program; if not, write to the Free Software
;; Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
;;
;;
;; Provide a handy interface to cheat.
;; See http://cheat.errtheblog.com for details on cheat itself.
;;
;; sjs 2007.08.21
;; * Cache the list of cheat sheets, update it once a day (configurable).
;; * Strictly complete cheat sheet names.
(defvar *cheat-host* "cheat.errtheblog.com")
(defvar *cheat-port* "80")
(defvar *cheat-uri* (concat *cheat-host* ":" *cheat-port*))
(defvar *cheat-directory* "~/.cheat")
(defvar *cheat-sheets-cache-file* (concat *cheat-directory* "/sheets"))
(defvar *cheat-last-sheet* nil
"Name of the most recently viewed cheat sheet.")
(defvar *cheat-sheet-history* nil
"List of the most recently viewed cheat sheets.")
(defconst +seconds-per-day+ 86400)
(defvar *cheat-cache-ttl* +seconds-per-day+
"The minimum age of a stale cache file, in seconds.")
;;; interactive functions
(defun cheat (name &optional silent)
"Show the specified cheat sheet.
If SILENT is non-nil then do not print any output, but return it
as a string instead."
(interactive (list (cheat-read-sheet-name)))
(if silent
(cheat-command-silent name)
(cheat-command name)))
(defun cheat-sheets ()
"List all cheat sheets."
(interactive)
(cheat-command "sheets"))
(defun cheat-recent ()
"Show recently added cheat sheets."
(interactive)
(cheat-command "recent"))
(defun cheat-clear-cache ()
"Clear the local cheat cache, located in ~/.cheat."
(interactive)
(cheat-command "--clear-cache")
(make-directory *cheat-directory*))
(defun cheat-versions (name)
"Version history of the specified cheat sheet."
(interactive (list (cheat-read-sheet-name)))
(cheat-command name "--versions"))
(defun cheat-diff (name version)
"Show the diff between the given version and the current version of the named
cheat.
If VERSION is of the form m:n then show the diff between versions m and n."
(interactive (list (cheat-read-sheet-name)
(read-string "Cheat version(s): ")))
(cheat-command name "--diff" version))
(defun cheat-add-current-buffer (name)
"Add a new cheat with the specified name and the current buffer as the body."
(interactive "sCheat name: \n")
(post-cheat name (buffer-string) t)
(if (interactive-p)
(print (concat "Cheat added (" name ")"))))
(defun cheat-edit (name)
"Fetch the named cheat and open a buffer containing its body.
The cheat can be saved with `cheat-save-current-buffer'."
(interactive (list (cheat-read-sheet-name)))
(cheat-clear-cache name) ; make sure we're working with the latest version
(switch-to-buffer (get-buffer-create (cheat->buffer name)))
(insert (cheat-body name))
(if (interactive-p)
(print "Run `cheat-save-current-buffer' when you're done editing.")))
(defun cheat-save-current-buffer ()
"Save the current buffer using the buffer name for the title and the contents
as the body."
(interactive)
(let ((name (buffer->cheat (buffer-name (current-buffer)))))
(post-cheat name (buffer-string))
;; TODO check for errors and kill the buffer on success
(if (interactive-p)
(print (concat "Cheat saved (" name ")")))
(cheat-clear-cache name)
(cheat name)))
;;; helpers
;; this is from rails-lib.el in the emacs-rails package
(defun string-join (separator strings)
"Join all STRINGS using SEPARATOR."
(mapconcat 'identity strings separator))
(defun blank (thing)
"Return T if THING is nil or an empty string, otherwise nil."
(or (null thing)
(and (stringp thing)
(= 0 (length thing)))))
(defun cheat-command (&rest rest)
"Run the cheat command with the given arguments, display the output."
(interactive "sArguments for cheat: \n")
(shell-command (concat "cheat " (string-join " " rest))))
(defun cheat-command-to-string (&rest rest)
"Run the cheat command with the given arguments and return the output as a
string. Display nothing."
(shell-command-to-string (concat "cheat " (string-join " " rest))))
(defalias 'cheat-command-silent 'cheat-command-to-string)
(defun cheat-read-sheet-name (&optional prompt)
"Get the name of an existing cheat sheet, prompting with completion and
history.
The name of the sheet read is stored in *cheat-last-sheet* unless it was blank."
(let* ((default (when (blank prompt) *cheat-last-sheet*))
(prompt (or prompt
(if (not (blank default))
(concat "Cheat name (default: " default "): ")
"Cheat name: ")))
(name (completing-read prompt
(cheat-sheets-list t)
nil
t
nil
'*cheat-sheet-history*
default)))
(when (not (blank name))
(setq *cheat-last-sheet* name))
name))
(defun cheat-sheets-list (&optional fetch-if-missing-or-stale)
"Get a list of all cheat sheets.
Return the cached list in *cheat-sheets-cache-file* if it's
readable and `cheat-cache-stale-p' returns nil.
When there is no cache or a stale cache, and
FETCH-IF-MISSING-OR-STALE is non-nil, cache the list and then
return it.
Otherwise return nil."
(cond ((and (file-readable-p *cheat-sheets-cache-file*)
(not (cheat-cache-stale-p)))
(save-excursion
(let* ((buffer (find-file *cheat-sheets-cache-file*))
(sheets (split-string (buffer-string))))
(kill-buffer buffer)
sheets)))
(fetch-if-missing-or-stale
(cheat-cache-list)
(cheat-sheets-list))
(t nil)))
(defun cheat-fetch-list ()
"Fetch a fresh list of all cheat sheets."
(nthcdr 3 (split-string (cheat-command-to-string "sheets"))))
(defun cheat-cache-list ()
"Cache the list of cheat sheets in *cheat-sheets-cache-file*. Return the
list."
(when (not (file-exists-p *cheat-directory*))
(make-directory *cheat-directory*))
(save-excursion
(let ((buffer (find-file *cheat-sheets-cache-file*))
(sheets (cheat-fetch-list)))
(insert (string-join "\n" sheets))
(basic-save-buffer)
(kill-buffer buffer)
sheets)))
(defun cheat-cache-stale-p ()
"Non-nil if the cache in *cheat-sheets-cache-file* is more than
*cheat-cache-ttl* seconds old.q
If the cache file does not exist then it is considered stale.
Also see `cheat-cache-sheets'."
(or (null (file-exists-p *cheat-sheets-cache-file*))
(let* ((now (float-time (current-time)))
(last-mod (float-time (sixth (file-attributes
*cheat-sheets-cache-file*))))
(age (- now last-mod)))
(> age *cheat-cache-ttl*))))
(defun cheat-body (name)
"Call out to Ruby to load the YAML and return just the body."
(shell-command-to-string
(concat "ruby -ryaml -e '"
"puts YAML.load_file(File.expand_path(\"~/.cheat/"
name ".yml\")).to_a[0][-1]'")))
(defun url-http-post (url args)
"Send ARGS to URL as a POST request."
(let ((url-request-method "POST")
(url-request-extra-headers
'(("Content-Type" . "application/x-www-form-urlencoded")))
(url-request-data
(concat (mapconcat (lambda (arg)
(concat (url-hexify-string (car arg))
"="
(url-hexify-string (cdr arg))))
args
"&")
"\r\n")))
;; `kill-url-buffer' to discard the result
;; `switch-to-url-buffer' to view the results (debugging).
(url-retrieve url 'kill-url-buffer)))
(defun kill-url-buffer (status)
"Kill the buffer returned by `url-retrieve'."
(kill-buffer (current-buffer)))
(defun switch-to-url-buffer (status)
"Switch to the buffer returned by `url-retreive'.
The buffer contains the raw HTTP response sent by the server."
(switch-to-buffer (current-buffer)))
(defun post-cheat (title body &optional new)
(let ((uri (concat "http://" *cheat-uri* "/w/" (if new "" title))))
(url-http-post uri `(("sheet_title" . ,title)
("sheet_body" . ,body)
("from_gem" . "1")))))
(defun buffer->cheat (name)
(substring name 7 (- (length name) 1)))
(defun cheat->buffer (name)
(concat "*cheat-" name "*"))
(provide 'cheat)
