[nongnu] elpa/engine-mode 7b0872e297 23/71: Provide a hook to transform the search term

[ELPA Syncer]

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

    Provide a hook to transform the search term
    
    Sometimes, for a given engine, we want to apply a function to a search
    term before it's interpolated into the URL. This commit provides a
    `term-transformation-hook` keyword argument in `defengine` that takes a
    function and ensures that it'll be invoked, with the raw term as its
    argument, every time the engine is evaluated.
    
    For example, suppose we want to ensure that search terms are encoded as
    latin-1. We could pass in an anonymous function:
    
    (defengine duckduckgo
      "https://duckduckgo.com/?q=%s";
      :term-transformation-hook (lambda (term) (encode-coding-string term 
latin-1)))
    
    Thanks to @patxoca for the suggestion and preliminary implementation!
---
 README.md      | 27 +++++++++++++++++++++++++++
 engine-mode.el | 21 +++++++++++++++++----
 2 files changed, 44 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 5bc61fa3b4..f93b68c69c 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,32 @@ keyword argument:
   :docstring "Search the Comprehensive TeX Archive Network (ctan.org)")
 ```
 
+## Modifying the search term before sending it
+
+An engine might want to transform a search term in some way before it
+interpolates the term into the URL. Maybe the term should have a
+different encoding, or be capitalized differently, or, uh, be passed
+through [ROT13]. Whatever the reason, you can apply a custom
+transformation to a search term by passing a function to `defengine`
+through the `:term-transformation-hook` keyword argument.
+
+For example, to UPCASE all of your DuckDuckGo searches:
+
+```emacs
+(defengine duckduckgo
+  "https://duckduckgo.com/?q=%s";
+  :term-transformation-hook 'upcase)
+```
+
+Or, to ensure that all your queries are encoded as latin-1:
+
+```emacs
+(defengine diec2
+  "dlc.iec.cat/results.asp?txtEntrada=%s"
+  :term-transformation-hook (lambda (term) (encode-coding-string term latin-1))
+  :keybinding "c")
+```
+
 ## Importing keyword searches from other browsers
 
 Since many browsers save keyword searches using the same format as
@@ -149,4 +175,5 @@ the `:keybinding` keyword to the generated engine 
definitions).
 ```
 
 [the talk @hrs gave at EmacsNYC]: https://www.youtube.com/watch?v=MBhJBMYfWUo
+[ROT13]: https://en.wikipedia.org/wiki/ROT13
 [import from Chrome on OS X]: 
https://gist.github.com/sshaw/9b635eabde582ebec442
diff --git a/engine-mode.el b/engine-mode.el
index 662eb2b866..e5830bfdc0 100644
--- a/engine-mode.el
+++ b/engine-mode.el
@@ -97,18 +97,31 @@
     `(define-key engine-mode-map (kbd ,(engine/scope-keybinding keybinding))
        (quote ,(engine/function-name engine-name)))))
 
-(cl-defmacro defengine (engine-name search-engine-url &key keybinding 
docstring)
+(cl-defmacro defengine (engine-name search-engine-url &key keybinding 
docstring (term-transformation-hook 'identity))
   "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 keyword argument `keybinding' is a string describing
-the key to bind the new function.
 The optional keyword argument `docstring' assigns a docstring to
 the generated function. A reasonably sensible docstring will be
 generated if a custom one isn't provided.
 
+The optional keyword argument `term-transformation-hook' is a
+function that will be applied to the search term before it's
+substituted into `search-engine-url'. For example, if we wanted
+to always upcase our search terms, we might use:
+
+(defengine duckduckgo
+  \"https://duckduckgo.com/?q=%s\";
+  :term-transformation-hook 'upcase)
+
+In this case, searching for \"foobar\" will hit the url
+\"https://duckduckgo.com/?q=FOOBAR\";.
+
+The optional 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 /'.
 
@@ -128,7 +141,7 @@ Hitting \"C-c / w\" will be bound to the newly-defined
        ,(or docstring (engine/docstring engine-name))
        (interactive
         (list (engine/get-query ,(symbol-name engine-name))))
-       (engine/execute-search ,search-engine-url search-term))
+       (engine/execute-search ,search-engine-url (,term-transformation-hook 
search-term)))
      ,(engine/bind-key engine-name keybinding)))
 
 (provide 'engine-mode)