[[FerretToc]]

= Welcome to Ferret =

Ferret is a high-performance, full-featured text search engine library written
for Ruby. It is inspired by 
[http://lucene.apache.org/ Apache Lucene] Java project.

= Latest News =

  === >> Sunday April 20, 6:30pm ===

  Apologies to everyone who has been following along with the development in the subversion repository. We've recently moved development to [http://github.com/dbalmain/ferret/tree/master github] and I've been having some trouble keeping everything in sync. I never worked out exactly what the problem was but it may have had something to do with conflicting version of git that I've been using. Anyway, everything seems to be working now and you should be able to read the full history of commits in the [http://ferret.davebalmain.com/trac/timeline timeline] rather than just the git merge messages that were occasionally appearing before.

  === >> Thursday April 17, 8:00am ===

  You can now check the coverage reports from gcov [http://ferret.davebalmain.com/gcov_results.html here].

  === >> Thursday November 29, 9:00am ===

  Ferret 0.11.6 released. This is a bug fix release to remove a problem with term vectors that was introduced in Ferret 0.11.5. This bug was affecting highlighting when combined with the Standard analyzer or any other analyzer which removes stop words. It is highly recommended you upgrade to this release. Windows users, however, needn't worry as this bug does not affect them. There will be no 0.11.6 win32 gem.

  '''Note:''' You will need to rebuild your index if it was built with or modified by version 0.11.5. Indexes built with earlier 0.11.* versions should be fine.

= Ferret Documentation =

Buy the print edition of the Ferret book now!

[[Amazon]]

Or you can download the [http://www.oreilly.com/catalog/9780596527853/index.html PDF] from O'Reilly. There is also a [http://www.oreilly.fr/catalogue/2354020694 French version] translated by [http://www.linkedin.com/in/ahfeel Jérémie Bordier]

{{{
#!html
<a title="Ferret Shortcut" href="http://www.oreilly.com/catalog/9780596527853/index.html"><img src="/9780596527853_cat.gif" style="float:left;margin-right:20px;"/></a>
<a title="French Translation of Ferret Shortcut" href="http://www.oreilly.fr/catalogue/2354020694"><img src="/ferret.fr.jpg" /></a>
}}}

=== Synopsis ===

  With the introduction of Ferret, Ruby users now have one of the fastest and most flexible search libraries available. And it's surprisingly easy to use.

  This Short Cut will show you how to quickly get up and running with Ferret. You'll learn how to index different document types such as PDF, Microsoft Word, and HTML, as well as how to deal with foreign languages and different character encodings. This document describes the Ferret Query Language in detail along with the object-oriented approach to building queries.

  You will also be introduced to sorting, filtering, and highlighting your search results, with an explanation of exactly how you need to set up your index to perform these tasks. You will also learn how to optimize a Ferret index for lightning fast indexing and split-second query results. 

= If you like Ferret, please help us out =

{{{
#!html
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="image" src="https://www.paypal.com/en_US/i/btn/x-click-but21.gif" border="0" name="submit" alt="Make payments with PayPal - it's fast, free and secure!">
<img alt="" border="0" src="https://www.paypal.com/en_AU/i/scr/pixel.gif" width="1" height="1">
<input type="hidden" name="encrypted" value="-----BEGIN PKCS7-----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-----END PKCS7-----
">
</form>
}}}
Donations of any amount will be greatly appreciated and help to keep Ferret development moving forward. If you have any questions, check out the [wiki:DonationsFAQ]. See FerretDonors for a list of donors.

== Requirements ==

  * Ruby 1.8
  * C compiler and Make to build the extension. gcc is preferred on *nix systems, VC6 on windows.

== Download ==

You can get the stable version at [http://rubyforge.org/frs/?group_id=1028&release_id=3198 RubyForge].
You can get the latest version of Ferret using [wiki:DownloadCurrent subversion].

== Installation ==

=== Gem Install ===

If you have [http://rubyforge.org/projects/rubygems/ RubyGems] installed, 
installing Ferret is simple and safe. You can easily remove it if you don't like it.

{{{
  gem install ferret
}}}

== Usage ==

You can read the [http://ferret.davebalmain.com/api/files/TUTORIAL.html tutorial] for a 
quick introduction to using ferret.

You should also check out the book [http://www.lucenebook.com/ "Lucene In Action"]. 
It's about Apache Lucene so it'll help if you know Java but everything in there should be
translatable to Ruby. If you need help, visit the mailing list. Your questions will be answered.

== Logos ==

[[Image(http://ferret.davebalmain.com/logo.png)]]

[[Image(http://ferret.davebalmain.com/ferret_badge.png)]]

Other logos including the original logos by Jan Prill can be found on the FerretLogos page.

== Performance ==

Ferret is now faster than Apache Lucene (even when it is compiled using gcj). How much faster? Try it for yourself and add your benchmark results.

UserAddedBenchmarks

== Authors ==

['''Dave Balmain'''] Port to Ruby

['''The Apache Software Foundation (Doug Cutting and friends)'''] [http://lucene.apache.org Original Apache Lucene]

== License ==

Ferret is available under an MIT-style license.