branch: elpa/engine-mode
commit 7b0872e29703532733136425b28221591074c369
Author: Harry Schwartz <he...@harryrschwartz.com>
Commit: Harry Schwartz <he...@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)
