aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--XMonad/Actions/Search.hs58
1 files changed, 47 insertions, 11 deletions
diff --git a/XMonad/Actions/Search.hs b/XMonad/Actions/Search.hs
index d09c490..b3e0651 100644
--- a/XMonad/Actions/Search.hs
+++ b/XMonad/Actions/Search.hs
@@ -16,6 +16,7 @@
module XMonad.Actions.Search ( -- * Usage
-- $usage
search,
+ simpleEngine,
promptSearch,
selectSearch,
@@ -35,6 +36,26 @@ import XMonad.Prompt.Shell (getShellCompl)
import XMonad.Util.Run (safeSpawn)
import XMonad.Util.XSelection (getSelection)
+{- $usage
+
+ This module is intended to allow easy access to databases on the Internet
+ through XMonad's interface. The idea is that one wants to run a search but the
+ query string and the browser to use must come from somewhere. There are two
+ places the query string can come from - the user can type it into a prompt
+ which pops up, or the query could be available already in the X Windows
+ copy/paste buffer (perhaps you just highlighted the string of interest).
+
+ Thus, there are two main functions: 'promptSearch', and 'selectSearch'
+ (implemented using the more primitive 'search'). To each of these is passed an
+ engine function; this is a function that knows how to search a particular
+ site.
+ For example, the 'google' function knows how to search Google, and so on. You pass
+ promptSearch and selectSearch the engine you want, the browser you want, and
+ anything special they might need; this whole line is then bound to a key of
+ you choosing in your xmonad.hs. For specific examples, see each function.
+ This module is easily extended to new sites by using 'simpleEngine'.
+-}
+
-- A customized prompt.
data Search = Search
instance XPrompt Search where
@@ -71,31 +92,46 @@ type SearchEngine = String -> String
search :: MonadIO m => Browser -> SearchEngine -> String -> m ()
search browser site query = safeSpawn browser $ site query
--- | Given a base URL, create the SearchEngine that escapes the query and
--- appends it to the base
+{- | Given a base URL, create the SearchEngine that escapes the query and
+ appends it to the base. You can easily define a new engine locally using simpleEngine
+ without needing to modify Search.hs:
+
+ > newEngine = simpleEngine "http://site.com/search="
+
+ The important thing is that the site has a interface which accepts the query
+ string as part of the URL. Alas, the exact URL to feed simpleEngine varies
+ from site to site, often considerably. Generally, examining the resultant URL
+ of a search will allow you to reverse-engineer it if you can't find the
+ necessary URL already described in other projects such as Surfraw. -}
simpleEngine :: String -> SearchEngine
simpleEngine site query = site ++ escape query
-- The engines
-amazon, google, imdb, wayback, wikipedia, hoogle :: SearchEngine
+amazon, google, hoogle, imdb, wayback, wikipedia :: SearchEngine
amazon = simpleEngine "http://www.amazon.com/exec/obidos/external-search?index=all&keyword="
google = simpleEngine "http://www.google.com/search?num=100&q="
+hoogle = simpleEngine "http://www.haskell.org/hoogle/?q="
imdb = simpleEngine "http://www.imdb.com/Find?select=all&for="
wikipedia = simpleEngine "https://secure.wikimedia.org/wikipedia/en/wiki/Special:Search?go=Go&search="
wayback = simpleEngine "http://web.archive.org/"
{- This doesn't seem to work, but nevertheless, it seems to be the official
method at <http://web.archive.org/collections/web/advanced.html> to get the
latest backup. -}
-hoogle = simpleEngine "http://www.haskell.org/hoogle/?q="
--- | Like 'search', but in this case, the string is not specified but grabbed
--- from the user's response to a prompt.
+{- | Like 'search', but in this case, the string is not specified but grabbed
+ from the user's response to a prompt. Example:
+
+ > , ((modm, xK_g ), promptSearch greenXPConfig "firefox" google)
+
+-}
promptSearch :: XPConfig -> Browser -> SearchEngine -> X ()
promptSearch config browser site = mkXPrompt Search config (getShellCompl []) $ search browser site
--- | Like search, but for use with the X selection; it grabs the selection,
--- passes it to a given searchEngine and opens it in a browser. The various
--- *Selection functions specialize this to a particular search engine to make
--- things easier.
+{- | Like search, but for use with the X selection; it grabs the selection,
+ passes it to a given searchEngine and opens it in the given browser. Example:
+
+> , ((modm .|. shiftMask, xK_g ), selectSearch "firefox" google)
+
+-}
selectSearch :: MonadIO m => Browser -> SearchEngine -> m ()
-selectSearch browser searchEngine = search browser searchEngine =<< getSelection
+selectSearch browser searchEngine = search browser searchEngine =<< getSelection \ No newline at end of file