diff options
| -rw-r--r-- | README.org | 2 | ||||
| -rw-r--r-- | trident-mode.el | 174 |
2 files changed, 170 insertions, 6 deletions
@@ -5,8 +5,6 @@ This is an [[http://www.gnu.org/software/emacs/][Emacs]] minor mode and collecti to create an environment for hacking Parenscript which fits as naturally as possible into the Lisp style of interactive development. -Note that this is very young code and there are certain to be serious problems. - There's at least one other project with related goals, [[https://github.com/3b/slime-proxy][slime-proxy]], though at the time of writing it's unclear whether it's still being actively developed. diff --git a/trident-mode.el b/trident-mode.el index 6f1dc44..9ddedca 100644 --- a/trident-mode.el +++ b/trident-mode.el @@ -3,7 +3,8 @@ ;; This is free and unencumbered software released into the public domain. ;; Author: John Mastro <john.b.mastro@gmail.com> -;; Version: 0.0.1 +;; URL: https://github.com/johnmastro/trident-mode.el +;; Version: 0.9.1 ;; Keywords: languages, lisp, processes, tools ;; Package-Requires: ((slime "2013-05-26") (skewer-mode "1.5.0") (dash "1.0.3")) @@ -14,10 +15,175 @@ ;; is to create an environment for hacking Parenscript which fits as naturally ;; as possible into the Lisp style of interactive development. -;; See https://github.com/johnmastro/trident-mode.el for additional information. +;; ** Installation -;; Note that this is very young code and there are certain to be serious -;; problems. +;; Trident has both Common Lisp and Emacs dependencies. + +;; - Common Lisp dependencies +;; - Your preferred Common Lisp implementation +;; - Parenscript + +;; You almost certainly want to use Quicklisp to install Parenscript. + +;; - Emacs dependencies +;; - SLIME +;; - Skewer +;; - dash.el + +;; My recommendation is to install SLIME via the Quicklisp SLIME Helper and the +;; others, including Trident itself, through Emacs's package.el infrastructure. + +;; ** Setup + +;; To enable trident-mode in a SLIME buffer: M-x trident-mode. + +;; To have lisp-mode, slime-mode, and trident-mode all enable automatically for +;; any file with an extension of ".paren": + +;; (add-to-list 'auto-mode-alist (cons "\\.paren\\'" 'lisp-mode)) +;; (add-hook 'lisp-mode-hook +;; #'(lambda () +;; (when (and buffer-file-name +;; (string-match-p "\\.paren\\>" buffer-file-name)) +;; (unless (slime-connected-p) +;; (save-excursion (slime))) +;; (trident-mode +1)))) + +;; Parenscript must be loaded in your Common Lisp image, and you'll probably +;; also want to import its symbols: + +;; (ql:quickload :parenscript) +;; (use-package :parenscript) + +;; With the above taken care of it's time to skewer the browser. See Skewer's +;; README for detailed information on the multiple ways you can connect to a +;; site - including sites on servers you don't control. + +;; The fastest way to simply try things out is to run M-x run-skewer. Skewer +;; will load an empty page in your browser and connect to it. You can +;; immediately begin using Trident's evaluation commands (described below); to +;; additionally open a JavaScript REPL you can run M-x skewer-repl. + +;; ** Commands + +;; *** Code expansion commands + +;; These commands generate JavaScript from the Parenscript code and display it +;; but don't send it to the browser for evaluation: + +;; - trident-expand-sexp +;; - trident-expand-last-expression +;; - trident-expand-defun +;; - trident-expand-region +;; - trident-expand-buffer +;; - trident-expand-dwim + +;; From within an expansion buffer you can press e to send the JavaScript to +;; the browser, w to copy it to the kill ring, s to save it to a file (you'll +;; be prompted for the destination) or q to dismiss the buffer. The copy +;; command, w, acts on the region if it's active or the entire buffer +;; otherwise. + +;; Additionally, you can use M-x trident-compile-buffer-to-file to expand the +;; current buffer and save the generated code directly to a file. + +;; *** Code evaluation commands + +;; These commands first compile the Parenscript code to JavaScript and then +;; immediately send to it the browser to be evaluated: + +;; - trident-eval-sexp +;; - trident-eval-last-expression +;; - trident-eval-defun +;; - trident-eval-region +;; - trident-eval-buffer +;; - trident-eval-dwim + +;; ** Key bindings + +;; The traditional set of code evaluation key bindings is a poor fit for +;; Trident,since they would shadow SLIME's equivalent commands and that's +;; probably not what you want. That leaves us without a clear convention to +;; follow, so by default we don't establish any key bindings at all. However, +;; the function trident-add-keys-with-prefix will add two-key key bindings for +;; all commands behind a prefix of your choice. + +;; For example: (trident-add-keys-with-prefix "C-c C-e"). The key sequence for +;; trident-eval-region is "e r", so it's now bound to "C-c" "C-e er" + +;; The full list of key bindings trident-add-keys-with-prefix will establish +;; is: + +;; - "e RET" -- trident-eval-sexp +;; - "e e" -- trident-eval-last-expression +;; - "e d" -- trident-eval-defun +;; - "e r" -- trident-eval-region +;; - "e b" -- trident-eval-buffer +;; - "e SPC" -- trident-eval-dwim +;; - "x RET" -- trident-expand-sexp +;; - "x e" -- trident-expand-last-expression +;; - "x d" -- trident-expand-defun +;; - "x r" -- trident-expand-region +;; - "x b" -- trident-expand-buffer +;; - "x SPC" -- trident-expand-dwim + +;; Evaluation commands begin with an "e", expansion commands with "x". The +;; second letter is generally mnemonic but not always. The -sexp commands use +;; RET in correspondence to slime-expand-1, and the -dwim commands use the +;; space bar because it's easy and comfortable to hit. + +;; Please consider these keys provisional, and let me know if you have any +;; ideas for improving the arrangement. + +;; If you really want to shadow SLIME's key bindings in buffers where +;; trident-mode is active you could do something like this: + +;; (defun steal-slime-keys-for-trident! () +;; ;; Don't affect all SLIME buffers, just where invoked +;; (make-local-variable 'slime-mode-map) +;; (let ((map slime-mode-map)) +;; (define-key map (kbd "C-x C-e") nil) +;; (define-key map (kbd "C-c C-r") nil) +;; (define-key map (kbd "C-M-x") nil) +;; (define-key map (kbd "C-c C-k") nil) +;; (define-key map (kbd "C-c C-m") nil)) +;; (let ((map trident-mode-map)) +;; (define-key map (kbd "C-x C-e") 'trident-eval-last-expression) +;; (define-key map (kbd "C-c C-r") 'trident-eval-region) +;; (define-key map (kbd "C-M-x") 'trident-eval-defun) +;; (define-key map (kbd "C-c C-k") 'trident-eval-buffer) +;; (define-key map (kbd "C-c C-m") 'trident-expand-sexp))) +;; +;; (add-hook 'trident-mode-hook 'steal-slime-keys-for-trident!) + +;; ** Other amenities + +;; slime-selector is a great feature and Trident can optionally integrate with +;; it. If you call trident-add-slime-selector-methods, two entries related to +;; trident-mode will be added. One, invoked with p, will take you to the most +;; recently visited buffer where trident-mode is active (excluding buffers +;; which are already visible). The other, on P, will take you to a scratch +;; buffer with trident-mode enabled, creating the buffer if necessary. + +;; Speaking of the scratch buffer, the trident-scratch command will take you +;; straight there. + +;; ** Still do be done + +;; - Test against a wider array of code. Are there problems with quoting? +;; - Better documentation. +;; - Look into adding a REPL. +;; - See if more integration with SLIME is possible. +;; - Command(s) for compiling to a file. +;; - Similar support for CL-WHO and/or CSS-LITE? +;; - Get to know ELPA and packaging. +;; - Add support for Customize. + +;; ** Contributing + +;; Contributions are very welcome. Since I've just started working on this and +;; don't have everything figured out yet, please first contact me on GitHub or +;; send me an email so we can talk before you start working on something. ;;; Code: |