Hoogle

From HaskellWiki
Revision as of 00:19, 8 October 2006 by DonStewart (talk | contribs) (category)
Jump to navigation Jump to search

To use hoogle go to http://haskell.org/hoogle. Hoogle is a Haskell API search engine, written by Neil Mitchell. It allows you to search by either name, or by approximate type signature.

How to use Hoogle

This section details how to use the Hoogle program, it is more than just a command line tool or a website.

Integrating Hoogle and GHCi

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

Using Hoogle From Vim

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

Using Hoogle from Emacs

(This requires you have Hoogle installed locally.)

Never to be outdone, here's a quick tip for using Hoogle from Emacs in case anyone hadn't already spotted it:

M-! runs the command shell-command

It's as simple as M-! hoogle whatever RET. If you really want to save the six keystrokes it takes to type 'hoogle' (and lets face it, which Emacsians don't?), try something like: 

(defun hoogle (arg)
  "Query hoogle via the shell with ARG."
  (interactive "sHoogle query: ")
  (let ((b (get-buffer-create "*Hoogle output*")))
    (shell-command (concat "hoogle " arg) b)
    (with-current-buffer b 
      (toggle-read-only)
      (set-buffer-modified-p nil))))
(global-set-key (kbd "C-c h") 'hoogle)

Change the shortcut to suit your needs. DavidHouse 15:57, 24 July 2006 (UTC)

Using Hoogle via a Firefox keyword

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

Now you can type h map directly into the location bar and you'll jump directly to the Hoogle search results page.

Hoogle databases

A Hoogle database has a list of functions and their types, they are plain text files. There are several approaches for generating Hoogle databases. Hoogle databases have the property that combining the files will still produce a valid database. In general there should be no reason for a user to create a Hoogle database.

Haddock

The HEAD version of Haddock has a --hoogle flag which will generate a hoogle database. This is the prefered method of generating databases. The HEAD version of Cabal now supports haddock --hoogle, which is the easiest method of documenting a large library.

hadhtml

First make Haddock documentation for your system, then run hadhtml on the directory containing the HTML. The Hoogle database distribute with Hoogle was generated with hadhtml.

hihoo

This approach uses the .hi files generated by GHC, so has the potential for being most accurate, but is currently unsupported and does not work in lots of cases.

Road Map

These are the future tasks, including fixing the remaining /Bugs.

Admin

  • get XHoogle in the repo
  • Move the bugs into the ndmitchell bug tracker

Short Term

i.e. before Hoogle3 goes public

  • Fix parse errors, ) ->, ) ->@ , func :: With Type
  • Regression tests for hoogle
  • You cannot search for certain keywords, i.e. @, because it is not a recognised lex symbol
  • Add comment characters, --, {- and -} to the list of symbols.
  • Put back more detailed information about the Prelude functions, see LibraryDocumentation.
  • Prelude.Either :: data Either a b -- the :: is entirely wrong
    • Prelude.Either data Either a b -- website
    • data Prelude.Either a b -- command line

Medium Term

  • Parameterise out by package, i.e. split off OpenGL
  • Compile with Yhc and distribute
  • Write GTK front end
  • Multiword search? power set
  • Dehack the Score program
  • Multiparameter type classes

Long Term

Hoogle Suggest

  • People often type to, instead of ->
  • Numeric literals
  • Concepts? tuple, random, monads etc.
  • Wrongly suggests capitals for t1 etc.
  • Kind errors, Maybe -> Bool, suggest Maybe a -> Bool
  • Return hits for module names ("Data" should return at least the module Data, probably known submodules as well)
  • People sometimes make typographical errors. Use a levenshtein distance edit on searches that have no result, to try to guess approximate answers by name (a la lambdabot's editing correction, here: http://www.cse.unsw.edu.au/~dons/code/lambdabot/Lib/Util.hs)

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

Hoogle depends on Haskell Source eXtensions.

The Source Code

darcs get http://www.cs.york.ac.uk/fp/darcs/hoogle

Haddock generated documentation, Darcsweb of 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. Some projects could be easily embarked upon are profiling, writing test frameworks and new front ends. Contact me if you have thoughts on doing something to Hoogle.

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.

Acknowledgements

The code is all © Neil Mitchell 2004-2006. 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:

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.

Retrieved from "https://wiki.haskell.org/index.php?title=Hoogle&oldid=6642"