1# Hoogle [![Hackage version](https://img.shields.io/hackage/v/hoogle.svg?label=Hackage)](https://hackage.haskell.org/package/hoogle) [![Stackage version](https://www.stackage.org/package/hoogle/badge/nightly?label=Stackage)](https://www.stackage.org/package/hoogle) [![Build status](https://img.shields.io/github/workflow/status/ndmitchell/hoogle/ci/master.svg)](https://github.com/ndmitchell/hoogle/actions) 2 3Hoogle is a Haskell API search engine, which allows you to search many standard Haskell libraries by either function name, or by approximate type signature. The online version can be found at https://hoogle.haskell.org/ and searches [Stackage](https://www.stackage.org/). 4 5* **Online version:** https://hoogle.haskell.org/ 6* **Hackage page:** https://hackage.haskell.org/package/hoogle 7* **Source code:** https://github.com/ndmitchell/hoogle 8* **Bug tracker:** https://github.com/ndmitchell/hoogle/issues 9 10## Hoogle Use 11 12Hoogle can be used in several ways: 13 14* **Online**, with the web interface at https://hoogle.haskell.org/ 15* **In [IRC](https://wiki.haskell.org/IRC_channel)**, using the [Lambdabot](https://wiki.haskell.org/Lambdabot) plugin with `@hoogle` and `@hoogle+` 16* **From `emacs`**, by means of [`engine-mode`](https://github.com/hrs/engine-mode) 17* **[Installed locally](./docs/Install.md)**, with either a command line or in a browser 18* **[As a developer](./docs/API.md)**, through Haskell or JSON APIs. 19 20# Searches 21 22## Searching 23 24Here are some example searches: 25 26* `map` searches as text, finding `map`, `concatMap`, `mapM` 27* `con map` searches for the text "map" and "con" finding `concatMap`, but not `map` 28* `a -> a` searches by type, finding `id :: a -> a` 29* `a` searches for the text "a" 30* `:: a` searches for the type "a" 31* `id :: a -> a` searches for the text "id" and the type "a -> a" 32 33 34## Scope 35 36By default, searches look at the [Haskell Platform](https://www.haskell.org/platform/) and [Haskell keywords](https://wiki.haskell.org/Keywords). However, all [Stackage](https://stackage.org) packages are available to search. As some examples: 37 38* `mode +cmdargs` searches only the "cmdargs" package 39* `file -base` searches the Haskell Platform, excluding the "base" package 40* `mode +platform +cmdargs` searches both the Haskell Platform and the "cmdargs" package 41* `count +missingh` searches only the "MissingH" package - all packages are written in lower-case 42 43With the set of packages you are searching, you can also restrict the set of modules searched: 44 45* `file -System` excludes results from modules such as `System.IO`, `System.FilePath.Windows` and `Distribution.System` 46* `fold +Data.Map` finds results in the `Data.Map` module 47 48 49# Integration 50 51## Command Line Version 52 53To invoke Hoogle type: 54 55 $ hoogle "[a] -> [b]" 56 57Note the quotes, otherwise you will redirect the output to the file [b]. 58 59To ensure you have data files for the Hackage modules, you will first need to 60type: 61 62 $ hoogle generate 63 64Which will download and build Hoogle databases. 65 66## Command Line UI 67 68There is a terminal/curses based UI available through [`cabal install bhoogle`](https://hackage.haskell.org/package/bhoogle). 69 70## Chrome Integration 71 72**As a keyword search:** With a keyword search you can type `h map` directly into the location bar to perform a Hoogle search. Go to the [Hoogle website](https://hoogle.haskell.org/) in Chrome, right-click in the Hoogle search field and select "Add as a search engine...". Give it a keyword such as "h". 73 74## Firefox Integration 75 76**From the search bar:** Go to the [Hoogle website](https://hoogle.haskell.org/) in Firefox and click on the `⋯` symbol at the right of the URL bar, and select the "Add Search Engine" option. Click the hoogle logo at the bottom of the completion dropdown when searching to perform a Hoogle search. 77 78**As a keyword search:** With a keyword search you can type `h map` directly into the location bar to perform a Hoogle search. Go to the [Hoogle website](https://hoogle.haskell.org/) in Firefox, right-click in the Hoogle search field and select "Add a Keyword for this Search...". Given it a keyword such as "h". 79 80## Others 81 82* [Doc Browser](https://github.com/qwfy/doc-browser) 83 84### The Source Code 85 86 $ git clone https://github.com/ndmitchell/hoogle.git 87 88Contributions 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 [issue tracker](https://github.com/ndmitchell/hoogle/issues) has many outstanding tasks, but please contact me if you have thoughts on doing something major to Hoogle, so I can give some advice. 89 90# Background 91 92Hoogle work is licensed under the [BSD-3-Clause license](https://github.com/ndmitchell/hoogle/blob/master/docs/LICENSE). 93 94## Theoretical Foundations 95 96A 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. Unfortunately the implementations that accompanied the earlier works were for functional languages that have since become less popular. 97 981. [Mikael Rittri, Using Types as Search Keys in Function Libraries](https://doi.org/10.1145/99370.99384). Proceedings of the fourth international conference on Functional Programming languages and Computer Architecture: 174-183, June 1989. 992. [Colin Runciman and Ian Toyn, Retrieving reusable software components by polymorphic type](https://doi.org/10.1145/99370.99383). Journal of Functional Programming 1 (2): 191-211, April 1991. 1003. [Roberto Di Cosmo, Isomorphisms of types: from lambda-calculus to information retrieval and language design](https://doi.org/10.1145/270563.571468). Birkhauser, 1995. ISBN-0-8176-3763-X 101 102I have given several presentations on type searching all available from [my home page](https://ndmitchell.com/). 103 104## Project Structure 105 106The folders in the repository, and their meaning are: 107 108cbits - C implementation of the text search used by hoogle 109 110docs - documention on hoogle 111 112html - resources for hoogle's web front-end (html, css, javascript, images, etc.) 113 114misc - scripts, logos, sample data, etc. 115 116src - haskell source code 117 118## Similar Tools 119 120I was unaware of any similar tools before starting development, and no other tool has really influenced this tool (except the first on this list). Some related tools are: 121 122* [Google](https://www.google.com/), the leader in online search 123* [Hayoo](https://hackage.haskell.org/package/Hayoo), similar to Hoogle, but with less focus on type search 124* [Krugle](https://www.krugle.com/), search code, but no Haskell :( 125* [Cloogle](https://cloogle.org), for the [Clean](https://clean.cs.ru.nl/Clean) language 126 127 128## Acknowledgements 129 130All code is all © [Neil Mitchell](https://ndmitchell.com/), 2004-present. The initial version was done over my summer holiday, and further work was done during my PhD. During Summer 2008 I was funded to full-time on Hoogle by [Google Summer of Code](https://summerofcode.withgoogle.com/) with the [haskell.org](https://www.haskell.org/) mentoring organisation. Since then I have been working on Hoogle in my spare time. Various people have given lots of useful ideas, including my PhD supervisor [Colin Runciman](https://www-users.cs.york.ac.uk/~colin/), and various members of the [Plasma group](https://www.cs.york.ac.uk/plasma/wiki/). In addition, the following people have also contributed code or significant debugging work: 131 132* Thomas "Bob" Davie 133* Don Stewart 134* Thomas Jager 135* [Gaal Yahas](https://gaal.livejournal.com/) 136* Mike Dodds 137* Niklas Broberg 138* Esa Ilari Vuokko 139* Udo Stenzel 140* [Henk-Jan van Tuyl](https://github.com/HJvT) 141* Gwern Branwen 142* Tillmann Rendel 143* David Waern 144* Ganesh Sittampalam 145* Duncan Coutts 146* Peter Collingbourne 147* Andrea Vezzosi 148* Ian Lynagh 149* [Alfredo Di Napoli](http://www.alfredodinapoli.com) 150 151In previous versions, all the data was taken from [Zvon's Haskell Guide](http://www.zvon.org/other/haskell/Outputglobal/). 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. 152 153# Interesting links 154 155* https://atom.io/packages/haskell-hoogle 156* https://hackage.haskell.org/package/hoogle-index 157