[nongnu] elpa/engine-mode 2ddc5ec627 20/71: Switch engine keybinding to be a keyword argument

[ELPA Syncer]

branch: elpa/engine-mode
commit 2ddc5ec62726e446c15197628e0f8e5cdf8016f1
Author: Harry Schwartz <hello@harryrschwartz.com>
Commit: Harry Schwartz <hello@harryrschwartz.com>

    Switch engine keybinding to be a keyword argument
    
    Previously, the key to which an engine was bound was an *optional*
    argument, so we'd say something like:
    
    (defengine duckduckgo
      "https://duckduckgo.com/?q=%s";
      "d")
    
    This commit makes it a *keyword* argument. We'll now have to say:
    
    (defengine duckduckgo
      "https://duckduckgo.com/?q=%s";
      :keybinding "d")
    
    BE FOREWARNED: This is a breaking change! However, we're now able to add
    additional optional keyword arguments to defengine. We've had requests
    for features like:
    
    * Specifying engine-specific browsers
    * Override docstrings on a per-engine basis
    * Specify character encoding for a particular engine
    
    This should make adding per-engine features much easier.
---
 README.md      | 13 ++++++++-----
 engine-mode.el | 12 ++++++------
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 8876e33ebc..6867c4e7ba 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ prefixed with `engine/keymap-prefix` (which defaults to "C-c 
/"):
 ```emacs
 (defengine duckduckgo
   "https://duckduckgo.com/?q=%s";
-  "d")
+  :keybinding "d")
 ```
 
 `C-c / d` is now bound to the new function `engine/search-duckduckgo`!
@@ -80,7 +80,10 @@ Since many browsers save keyword searches using the same 
format as
 engine-mode (that is, by using `%s` in a url to indicate a search
 term), it's not too hard to import them into Emacs.
 
-@sshaw has written a script to [import from Chrome on OS X].
+@sshaw has written a script to [import from Chrome on OS X], but it's
+based on an older version of `engine-mode`, so the resulting file may
+need a bit of manual cleaning-up (specifically, you may need to add
+the `:keybinding` keyword to the generated engine definitions).
 
 ## Engine examples
 
@@ -90,14 +93,14 @@ term), it's not too hard to import them into Emacs.
 
 (defengine duckduckgo
   "https://duckduckgo.com/?q=%s";
-  "d")
+  :keybinding "d")
 
 (defengine github
   "https://github.com/search?ref=simplesearch&q=%s";)
 
 (defengine google
   "http://www.google.com/search?ie=utf-8&oe=utf-8&q=%s";
-  "g")
+  :keybinding "g")
 
 (defengine google-images
   
"http://www.google.com/images?hl=en&source=hp&biw=1440&bih=795&gbv=2&aq=f&aqi=&aql=&oq=&q=%s";)
@@ -119,7 +122,7 @@ term), it's not too hard to import them into Emacs.
 
 (defengine wikipedia
   "http://www.wikipedia.org/search-redirect.php?language=en&go=Go&search=%s";
-  "w")
+  :keybinding "w")
 
 (defengine wiktionary
   
"https://www.wikipedia.org/search-redirect.php?family=wiktionary&language=en&go=Go&search=%s";)
diff --git a/engine-mode.el b/engine-mode.el
index 99d6b31e98..0c753e598f 100644
--- a/engine-mode.el
+++ b/engine-mode.el
@@ -1,7 +1,7 @@
 ;;; engine-mode.el --- Define and query search engines from within Emacs.
 
 ;; Author: Harry R. Schwartz <hello@harryrschwartz.com>
-;; Version: 2015.02.07
+;; Version: 2015.05.02
 ;; URL: https://github.com/hrs/engine-mode/engine-mode.el
 
 ;; This file is NOT part of GNU Emacs.
@@ -27,7 +27,7 @@
 
 ;; (defengine duckduckgo
 ;;   "https://duckduckgo.com/?q=%s";
-;;   "d")
+;;   :keybinding "d")
 
 ;; `C-c / d' is now bound to the new function
 ;; engine/search-duckduckgo'! Nifty.
@@ -97,14 +97,14 @@
     `(define-key engine-mode-map (kbd ,(engine/scope-keybinding keybinding))
        (quote ,(engine/function-name engine-name)))))
 
-(defmacro defengine (engine-name search-engine-url &optional keybinding)
+(cl-defmacro defengine (engine-name search-engine-url &key keybinding)
   "Define a custom search engine.
 
 `engine-name' is a symbol naming the engine.
 `search-engine-url' is the url to be queried, with a \"%s\"
 standing in for the search term.
-The optional value `keybinding' is a string describing the key to
-bind the new function.
+The keyword argument `keybinding' is a string describing the key
+to bind the new function.
 
 Keybindings are prefixed by the `engine/keymap-prefix', which
 defaults to `C-c /'.
@@ -113,7 +113,7 @@ For example, to search Wikipedia, use:
 
   (defengine wikipedia
     
\"http://www.wikipedia.org/search-redirect.php?language=en&go=Go&search=%s\";
-    \"w\")
+    :keybinding \"w\")
 
 Hitting \"C-c / w\" will be bound to the newly-defined
 `engine/search-wikipedia' function."