HTML Entities for Ruby

About

HTMLEntities is a simple library to facilitate encoding and decoding of named (ý and so on) or numerical ({ or Ī) entities in HTML and XHTML documents.

The current release is version 4.0.0.

Changes since version 3.0.1

Now understands all the entities referred to in the XHTML 1.0 DTD (253 entities compared with 131 in version 3.0.1).
Calls to_s on parameters to play nicely with Rails 1.2.1.
Entity mapping data is now lazily loaded.
New instantiation-based interface (but legacy interface is preserved for compatibility).
Handles HTML4 as well as XHTML1 (the former lacks the ' entity).
Encodes basic entities numerically when :basic isn’t specified and :decimal or :hexadecimal is.
Performs a maximum of two gsub passes instead of three when encoding, which should be more efficient on long strings.

Usage

If you are running the examples below in irb, please make sure that you are running in a UTF-8 terminal and have set $KCODE to 'u' to enable the display of UTF-8 characters.

Decoding

require 'htmlentities'
coder = HTMLEntities.new
string = "&eacute;lan"
coder.decode(string) # => "élan"

Encoding

This is slightly more complicated, due to the various options. The encode method takes a variable number of parameters, which tell it which instructions to carry out.

require 'htmlentities'
coder = HTMLEntities.new
string = "<élan>"
coder.encode(string)               # => "&lt;élan&gt;"
coder.encode(string, :named)       # => "&lt;&eacute;lan&gt;"
coder.encode(string, :decimal)     # => "&#60;&#233;lan&#62;"
coder.encode(string, :hexadecimal) # => "&#x3c;&#xe9;lan&#x3e;"

Documentation

For more details, you can browse the rdoc-generated documentation online.

Getting it

HTMLEntities is available as a tarball or gem on its RubyForge files page.

You should also be able to install it using RubyGems:

gem install -r htmlentities

Licence

This code is free to use under the terms of the MIT licence. If that doesn’t suit you, and you’d like to negotiate a different licence for a specific use, just contact me—I’ll almost certainly permit it.

Contact

Comments are welcome. Send an email to pbattley@gmail.com.

Paul Battley, 15th March 2007