search-query

Define web search engines for EWW
git clone https://git.git.jamzattack.xyz/search-query
Log | Files | Refs | LICENSE

README.org (2817B)

      1 #+title: Search-query.el -- Define web search engines for EWW
      2 #+author: Jamie Beardslee
      3 #+email: jdb@jamzattack.xyz
      4 
      5 This library provides a macro to define search engines consistently
      6 and easily.  It also provides a few of such search engines that I use
      7 regularly.
      8 
      9 * Installation
     10 
     11 ** package.el
     12 
     13 Download search-query.el, and use =M-x package-install-file RET
     14 path/to/search-query.el=.
     15 
     16 ** straight.el
     17 
     18 Use the following recipe:
     19 
     20 #+begin_src emacs-lisp
     21   (search-query :type git
     22 		:flavor melpa
     23 		:repo "https://git.jamzattack.xyz/search-query")
     24 #+end_src
     25 
     26 ** Manual installation
     27 
     28 1. Download search-query.el
     29 2. Stick it in [[help:load-path][load-path]]
     30 3. Update autoloads
     31 4. (optionally) byte-compile it
     32 
     33 * Defining a search engine
     34 
     35 The macro [[help:search-query-create][search-query-create]] defines a new search engine.
     36 
     37 ** A simple example
     38 
     39 In the simplest case, it requires three arguments -- ~name~,
     40 ~format-string~, and ~docstring~.
     41 
     42 For example, the definition of [[help:search-archwiki][search-archwiki]]:
     43 
     44 #+begin_src emacs-lisp
     45   (search-query-create archwiki
     46     "https://wiki.archlinux.org/index.php?search=%s"
     47     "Search Arch wiki for QUERY.")
     48 #+end_src
     49 
     50 This expands to:
     51 
     52 #+begin_src emacs-lisp
     53   (defun search-archwiki (query)
     54     "Search Arch wiki for QUERY."
     55     (interactive "sArchwiki: ")
     56     (search-query-eww
     57      (url-encode-url
     58       (format "https://wiki.archlinux.org/index.php?search=%s" query))
     59      "*eww archwiki*"))
     60 #+end_src
     61 
     62 ** More complicated search engines
     63 
     64 For more complicated searches, keyword arguments are supported:
     65 
     66 | :args        | the arguments of the function to be defined        |
     67 | :format-args | the arguments for the format string                |
     68 | :interactive | the interactive spec of the function to be defined |
     69 
     70 See [[help:search-wikipedia][search-wikipedia]] as an example, which has an optional language
     71 argument:
     72 
     73 #+begin_src emacs-lisp
     74   (search-query-create wikipedia
     75     "https://%s.wikipedia.org/wiki/Special:Search?search=%s"
     76     "Search wikipedia for QUERY.
     77   With prefix arg, prompt for LANGUAGE."
     78     :args (query &optional lang)
     79     :format-args ((or lang "en") query)
     80     :interactive (list (read-string "Wikipedia: ")
     81 		       (when current-prefix-arg
     82 			 (read-string "Language: "))))
     83 #+end_src
     84 
     85 This expands to:
     86 
     87 #+begin_src emacs-lisp
     88   (defun search-wikipedia (query &optional lang)
     89     "Search wikipedia for QUERY.
     90   With prefix arg, prompt for LANGUAGE."
     91     (interactive (list
     92 		  (read-string "Wikipedia: ")
     93 		  (when current-prefix-arg
     94 		    (read-string "Language: "))))
     95     (search-query-eww
     96      (url-encode-url
     97       (format "https://%s.wikipedia.org/wiki/Special:Search?search=%s"
     98 	      (or lang "en")
     99 	      query))
    100      "*eww wikipedia*"))
    101 #+end_src
    102 
    103 Here, all three additional keyword arguments are used.
    104 
    105 * License
    106 
    107 GPL3+