Hoogle

Hoogle is a Haskell API search engine, which allows you to search many standard Haskell libraries by either function name, or by approximate type signature.

• Online version: http://haskell.org/hoogle
• Hackage page: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/hoogle
• Darcs repository: http://code.haskell.org/hoogle
• Bug tracker: http://code.google.com/p/ndmitchell/issues/list
• Manual: This page.

Hoogle Use

Hoogle can be used in several ways:

• Online, with the web interface: http://haskell.org/hoogle
• In the Haskell IRC channel, using the Lambdabot plugin, @hoogle and @hoogle+
• With the command line version available on Hackage.

This section first describes the syntax for a Hoogle online search, then gives command line flags in groups of use.

Online Searches

Searches can be either textual (a list of words), or by type (a type signature) or both. A type search may optionally start with a "::" symbol. A search is considered a text search unless a function symbol (->) appears in it, or if it starts with (::). To search for both a type and a name, place a :: between them, for example "undefined :: a"

Searches can be restricted to a particular module with +Module.Name, or to avoid a module with -Module.Name. The command Module.Name.Foo is treated as +Module.Name Foo.

Searches can be restricted to a particular package with +packagename, or to avoid a package with -package. By default Hoogle will search a standard set of packages.

General Flags

Flags can be specified as --flag or /flag. Anything which is not a flag is counted as a search query. Because a console will treat -> as a redirection, you can do -hash to get the right character.

• --version Print out version information
• --help Show help message

Search Flags

   ,f (ArgDir Include) ["i","include"] [PCmdLine,PMultiple] "Include directories"
   ,f (ArgBool Color) ["c","color","col","colour"] [PCmdLine] "Show color output (default=false)"
   ,f (ArgPos  Start) ["s","start"] [PCmdLine,PWebArgs] "First result to show (default=1)"
   ,f (ArgPos  Count) ["n","count","length","len"] [PCmdLine,PWebArgs] "Number of results to show (default=all)"
   ,f (ArgNone Info) ["info"] [PCmdLine] "Display full information on an entry"

Database Maintenance Flags

   ,f (ArgFileIn Convert ["txt"]) ["convert"] [PCmdLine,PMultiple] "Convert a database"
   ,f (ArgFileOut Output) ["output"] [PCmdLine] "Output file for convert"

Developer Flags

   ,f (ArgNone Web) ["w","web"] [PCmdLine] "Run as though it was a CGI script"
   ,f (ArgNone Test) ["test"] [PCmdLine] "Run the regression tests"
   ,f (ArgStr  Dump) ["dump"] [PCmdLine] "Dump a database for debugging"
   ,f (ArgFileIn DataFile ["hoo"]) ["d","data"] [PCmdLine,PMultiple] "Database file"
   ,f (ArgNone Verbose) ["v","verbose"] [PCmdLine] "Display verbose information"
   ,f (ArgNone Debug) ["debug"] [PCmdLine] "Debugging only"
   ,f (ArgFileIn TestFile ["txt"]) ["testfile"] [PCmdLine,PMultiple] "Run tests from a file"
   ,f (ArgFileIn Rank ["txt"]) ["rank"] [PCmdLine,PMultiple] "Generate ranking scores"

Hoogle Integration Modes

Hoogle can be integrated with various programs, listed below. Most of these integration modes were contributed by users, and users are encouraged to add more programs to this list.

Firefox Integration

From the search bar: Go to the Hoogle website in Firefox and click on Firefox Plugin, top right hand corner. This will add a Hoogle entry to the search box in Firefox.

As a keyword search: You can set up Hoogle as a keyword search in Firefox. This means that you can type h map directly into the location bar and you'll jump directly to the Hoogle search results page.

1. Visit Hoogle's web interface: http://haskell.org/hoogle
2. Right-click on the text input box and click "Add a Keyword for this Search..."
3. Give it a nice short keyword like "h".

In the future some of these will be available for IE as well.

GHCi Integration

Ever feel like having access to hoogle whilst messing around in GHCi? It's relatively easy to integrate the two. I'm on linux, so I don't know how well the following will work if you're on windows.

First, you need to download and compile Hoogle. Then, we want to move hoogle to somewhere in your system's $PATH (open a terminal and type echo $PATH to see where this is). I suggest ~/bin, although you might want to go for /usr/bin or /usr/local/bin, etc.

Copy the Hoogle binary and hoogle.txt to the directory you chose. If you're using a version of hoogle pulled straight from darcs, you can ignore everything up until the 'Next, we need to integrate it into GHCi' bit. Otherwise:

There's a problem in that hoogle doesn't look for hoogle.txt in the system $PATH, it only looks in the current directory. This is a slight pain but is easily worked around: rename the hoogle binary to hoogle-bin, then create a new text file called 'hoogle' with the following contents:

#! /bin/bash
hoogle-bin -l /path/to/your/chosen/directory/hoogle.txt "$@"

chmod hoogle to make it executable (try chmod +x hoogle). Now you should be able to run hoogle requests from the shell. Try a few of the examples above.

Next, we need to integrate it into GHCi. We can execute shell commands with GHCi via :def. Load up GHCi, and type the following:

:def hoogle \x -> return $ ":!hoogle " ++ x

If this executes cleanly, you should be able to run hoogle commands from GHCi via :hoogle, i.e. :hoogle map or :hoogle "(a -> b) -> [a] -> [b]". Be careful: you need the extra quotes when hoogling types, at least on my system. :ho works as an abbreviation of :hoogle (just :h clashes with :help).

Finally, we want to make this persist across GHCi sessions. GHCi loads a file called ~/.ghci before running, so simply stick the above :def in that file and all should work.

Contributed by DavidHouse

Vim Integration

Hoogle can be called from Vim via the lambdabot vim scripts.

• Download and build Lambdabot, which will also build a Hoogle.
• Install the scripts/vim programs into your path

Then, to invoke hoogle from vim, passing the current buffer line or region as input:

!!bot hoogle

For example, if the buffer contains the line:

map

Running !!bot hoogle will replace that with:

Prelude.map :: (a -> b) -> [a] -> [b]
Data.IntMap.map :: (a -> b) -> IntMap a -> IntMap b
Data.IntSet.map :: (Int -> Int) -> IntSet -> IntSet

If the buffer contains:

(a,b) -> b

Running !!bot hoogle will replace that with:

Prelude.snd :: (a, b) -> b
Prelude.uncurry :: (a -> b -> c) -> (a, b) -> c
Prelude.fst :: (a, b) -> a

Emacs Integration

haskell-mode from versions 2.4 onwards have the function haskell-hoogle, which will hoogle the identifier at point. Setup:

(require 'haskell-mode)
(define-key haskell-mode-map "\C-ch" 'haskell-hoogle)
;(setq haskell-hoogle-command "hoogle")

You will need a web browser configured for best results. Here's an example setup for Safari:

(setq browse-url-browser-function 'browse-url-safari)
(defun browse-url-safari (url &optional new-window)
 "Open URL in a new Safari window."
 (interactive (browse-url-interactive-arg "URL: "))
 (unless
     (string= ""
              (shell-command-to-string
               (concat "open -a Safari " url)))
   (message "Starting Safari...")
   (start-process (concat "open -a Safari " url) nil "open -a Safari " url)
   (message "Starting Safari... done")))

Alternately, you can build the command-line hoogle (darcs repo below) and uncomment the third line above, then results will appear in a buffer.

Developers

This work is licensed under the GPL version 2.0. By submitting any patches to Hoogle you agree to license them under the BSD license, or to assign copyright to Neil Mitchell who will include them under the GPL (either one, your choice). This is so I can relicense Hoogle under the BSD at a later date if that proves beneficial to the Haskell community.

The work is intended to be helpful, open and free. If the license doesn't meet your needs then talk to me.

The Source Code

$ darcs get http://code.haskell.org/hoogle/

Contributions are most welcome. Hoogle is written in Haskell 98 + Heirarchical Modules, I do not wish to change this. Other than that, I'm pretty flexible about most aspects of Hoogle. The bug tracker has many outstanding tasks, but please contact me if you have thoughts on doing something major to Hoogle, so I can give some advice.

Theoretical Foundations

A lot of related work was done by Rittri [1] and Runciman [2] in the late 80's. Since then Di Cosmo [3] has produced a book on type isomorphisms, which is also related. Unfortunately the implementations that accompanied the earlier works were for functional languages that have since become less popular, and to my knowledge no existing functional programming language has a tool such as Hoogle.

There is also a presentation on Hoogle that I gave, which has some details of the theory.

1. Mikael Rittri, Using Types as Search Keys in Function Libraries. Proceedings of the fourth international conference on Functional programming languages and computer architecture: 174-183, June 1989. (http://portal.acm.org/citation.cfm?id=99384)
2. Colin Runciman and Ian Toyn, Retrieving reusable software components by polymorphic type. Journal of Functional Programming 1 (2): 191-211, April 1991. (http://portal.acm.org/citation.cfm?id=99383)
3. Roberto Di Cosmo. Isomorphisms of types: from lambda-calculus to information retrieval and language design. Birkhauser, 1995. ISBN-0-8176-3763-X (http://www.pps.jussieu.fr/~dicosmo/Publications/ISObook.html)

Similar Tools

I didn't know of any similar tools before starting development, and no other tool has really influenced this tool (except the first on this list). The follow are provided for comparison.

• Google - Google rock!
• Hayoo - Similar to Hoogle, but with less focus on type search
• Krugle - Search code, no Haskell :(

Acknowledgements

The code is all © Neil Mitchell 2004-2008. The initial version was done in my own time, and further refinement and reimplementation was done as part of my PhD. Various people gave lots of useful ideas, including my supervisor Colin Runciman, and various members of the Plasma group. In addition the following people have also contributed some code or significant debugging work:

• Thomas "Bob" Davie
• Don Stewart
• Thomas Jäger
• Gaal Yahas
• Mike Dodds
• Niklas Broberg
• Esa Ilari Vuokko
• Udo Stenzel
• Henk-Jan van Tuyl
• Gwern Branwen
• Tillmann Rendel
• David Waern

In previous versions, all the data was taken from Zvon's Haskell Guide. Thanks to their open and friendly policy of allowing the data to be reused, this project became possible. More recent versions use the Hierarchical Libraries as distributed with GHC, and databases generated by Haddock.