This section describes Hoogle searches, and the flags available from the Hoogle command line tool. The information applies only to Hoogle 4, the next version of Hoogle, and is still being fleshed out.

1.1 Searches

Before explaining the syntax of searches, we first give a list of example searches with their meaning:

"map" Search for the text "map"

"con map" Search for the text "map" and the text "con"

"a -> a" Search for the type "a -> a"

":: a -> a" Search for the type "a -> a"

"a" Search for the text "a"

":: a" Search for the type "a"

"id :: a -> a" Search for the text "id" and the type "a -> a"

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 it contains a combination of text and symbols, 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.

1.1.1 Command Line Search Flags

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

--version Print out version information

--help Show help on the command line flags

--include=dir Specify which directories are searched for necessary files, defaults to "." and the data directory configured with Cabal.

--count=int Maximum number of results to print, defaults to showing all results

--start=int 1-based index of first result to print, defaults to 1

--info Show extended information for the first results

1.2 Database Creation

Hoogle has both binary databases (extension .hoo) and textual databases (extension .txt). Textual database files are a list of functions and their types, along with information about type synonyms, instances etc. The textual database files can be generated by Haddock with the --hoogle flag. Support for this is now in Cabal with runhaskell Setup haddock --hoogle.

1.2.1 Converting text databases to binary databases

A text database can be converted to a binary database with the command hoogle --convert=file.txt. Any package dependencies should be specified with +package or --data=package.hoo, and will require the binary databases for those packages. The output file can be controlled with --output=file.hoo.

1.2.2 Merging binary databases

Multiple binary databases can be merged with hoogle --merge=file1.hoo --merge=file2.hoo. As before, --output=default.hoo can be specified.

Right-click on the text input box and click "Add a Keyword for this Search..."

Give it a nice short keyword like "h".

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

2.2 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:

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.

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

3 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.

3.1 The Source Code

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.

4 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.

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)

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.