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

Changes since version 4.0.0

Now works with Ruby 1.9.1 and JRuby 1.3.1.
Reverted lazy loading of entity mappings as this is not thread-safe.
Finally removed the deprecated String#encode_entities and #decode_entities methods.
Added :expanded charset: about 1000 SGML entities.

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 htmlentities

The current source code can be found on GitHub as threedaymonk/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