ADS top
TITLE Rubyful Soup: "The brush has got entangled in it!"
META Description Rubyful Soup: an HTML parser for Ruby, optimized for screen-scraping.
STYLE ../BeautifulSoup/soup.css
ENDWITH </div>

<table width="100%">
<tr>
<td width="80%" valign="top">

<a href="download/RubyfulSoup.rb"><h1>Rubyful Soup</h1></a>

<p><i><b>Note:</b> Rubyful Soup is no longer being maintained. I recommend you use <a href="http://code.whytheluckystiff.net/hpricot/">hpricot</a> instead.</i></p>

<p>Rubyful Soup is a Ruby port of the hit Python HTML/XML parser <a
href="/software/BeautifulSoup/">Beautiful Soup</a>. It's designed to
be a useful quick-and-dirty parser for screen-scraping, along the same
lines as its parent:</p>

<ol>

<li>Rubyful Soup won't choke if you give it bad markup. It yields a
parse tree that makes approximately as much sense as your original
document. This is usually good enough to collect the data you need and
then run away.

<li>Rubyful Soup provides a few simple methods and Ruby-like idioms
for navigating and searching a parse tree: a toolkit for dissecting a
document and extracting what you need. You don't have to create a
custom parser for each application. It's more flexible and easier to
learn than XPath.

</ol>

<h2>Download</h2>

<p>The current version has the same functionality and robustness of
Beautiful Soup, and some things I haven't yet put into Beautiful Soup
(see below for a list of differences). It's packaged as the
<b>rubyful_soup</b> gem on rubyforge.org. You can install it with the
<i>gem install</i> command, or <a
href="http://rubyforge.org/frs/?group_id=1033">download it
manually</a>. If you download it manually, be sure to install the
<b>htmltools</b> gem first; that gem supplies the parser on which
Rubyful Soup depends.

<h2>Documentation</h2>

<p><a href="documentation.html">Get it here.</a></p>

<h2>Differences from Beautiful Soup</h2>

<h3>Good differences</h3>

<ul>

<li>In Rubyful Soup you can ignore all the arguments to the fetch
methods, and pass in a block instead. This lets you completely
customize the behavior of the fetch methods. This block will be called
on every <code>Tag</code> and <code>NavigableText</code> object
encountered by the iterator. The method should return true when it
encounters a match, and false otherwise. The method may abort the
iteration by <code>throw</code>ing <code>:stop_iteration</code>.

<p>For instance, these two pieces of code are identical:

<blockquote>
<code><pre>soup.find_all('a')
soup.find_all {|x| x.is_a? Tag and x.name == 'a' }</pre></code>
</blockquote>

<p>As are these:

<blockquote>
<code><pre>soup.find_text('Hello')
soup.find_text {|x| x == 'Hello' }</pre></code>
</blockquote>

</ul>

<h3>Bad differences</h3>

<ul>

<li>Rubyful Soup is relatively slower than Beautiful Soup. As of
1.0.4, however, it should never be unusably slow.

<li>The method and member names are slightly different, out of respect
for Ruby's naming conventions and reserved words.

<li>You can't call a Tag as though it were a method. Ruby doesn't seem
to support this. Not a big deal.

<li>Most of the features of Beautiful Soup 3.0 are not yet present in
Rubyful Soup. Some (the encoding autodetection) may not be present for
a long time.
</ul>

</td>

<td valign="top">
<img src="lg18.gif" height="150"><br />
<blockquote class="alice">
They were standing under a tree, each with an arm round the other's neck, and Alice knew which was which in a moment, because one of them had "DUM" embroidered on his collar, and the other "DEE".
</blockquote>
</td></tr></table>