idn

== LibIDN Ruby Bindings

Version 0.0.2

Ruby Bindings for the GNU LibIDN library, an implementation of the Stringprep, Punycode and IDNA specifications defined by the IETF Internationalized Domain Names (IDN) working group.

Included are the most important parts of the Stringprep, Punycode and IDNA APIs like performing Stringprep processings, encoding to and decoding from Punycode strings and converting entire domain names to and from the ACE encoded form.

The latest version of the LibIDN Ruby Bindings project and its documentation can always be found at

• http://rubyforge.org/projects/idn

See the CHANGES file for detailed information on the changes of every released version.

=== Requirements

• GNU LibIDN[http://www.gnu.org/software/libidn/] Library

• Rake[http://rubyforge.org/projects/rake] to run the tests and generate the documentation

• RubyGems[http://docs.rubygems.org/] to produce a Gem package

=== Installation

You can easily install the LibIDN Ruby Bindings by following one of the ways outlined below:

==== Automatic installation and management with RubyGems

Simply invoke the standard RubyGems commands (install, update, ...), for example:

% gem install --remote --test idn

or if the GNU LibIDN library can only be found in a non-standard location

% gem install --remote --test idn --
--with-idn-dir=/path/to/non/standard/location

or in an even more complex setup

% gem install --remote --test idn --
--with-idn-lib=/path/to/non/standard/location/lib
--with-idn-include=/path/to/non/standard/location/include

==== Semi-automatic installation with Rake

If you are not able to or don't want to use RubyGems you can simply download the latest release and install it with the help of Rake:

% tar -xvzf idn-x.x.x.tar.gz % cd idn-x.x.x

% rake install

or if the GNU LibIDN library can only be found in a non-standard location

% rake install IDN_DIR=/path/to/non/standard/location

You can also run the tests or generate the documentation; just call Rake with the '--tasks' parameter to get an overview of the available tasks:

% rake --tasks

==== Manual installation with extconf.rb

If you are not able to or don't want to use even Rake then you will have to do a little bit more work by yourself:

% tar -xvzf idn-x.x.x.tar.gz % cd idn-x.x.x/ext

% ruby extconf.rb

or if the GNU LibIDN library can only be found in a non-standard location

% ruby extconf.rb
--with-idn-dir=/path/to/non/standard/location

or in an even more complex setup

% ruby extconf.rb
--with-idn-lib=/path/to/non/standard/location/lib
--with-idn-include=/path/to/non/standard/location/include

and finally

% make % sudo make install

=== Documentation

The complete documentation is available online at

• http://idn.rubyforge.org/docs

See also the section on 'Semi-automatic installation with Rake' above for some details on how to generate the documentation by yourself.

==== Example usage

require 'idn' include IDN

puts 'Idna.toUnicode: ' + Idna.toUnicode('xn--rksmrgs-5wao1o.josefsson.org') puts 'Punycode.decode: ' + Punycode.decode('egbpdaj6bu4bxfgehfvwxn') puts 'Stringprep.with_profile: ' + Stringprep.with_profile('FOO', 'Nameprep')

=== References

[GNU LibIDN] An implementation of the Stringprep, Punycode and IDNA specifications defined by the IETF Internationalized Domain Names (IDN) working group, used for internationalized domain names. The package is available under the GNU Lesser General Public License.

• http://www.gnu.org/software/libidn

[RFC3454] P. Hoffman, M. Blanchet, "Preparation of Internationalized Strings ('stringprep')", IETF RFC3454, December 2002.

• http://www.ietf.org/rfc/rfc3454.txt

[RFC3490] P. Faltstrom, P. Hoffman, A. Costello, "Internationalizing Domain Names in Applications (IDNA)", IETF RFC3490, March 2003.

• http://www.ietf.org/rfc/rfc3490.txt

[RFC3491] P. Hoffman, M. Blanchet, "Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)", IETF RFC3491, March 2003.

• http://www.ietf.org/rfc/rfc3491.txt

[RFC3492] A. Costello, "Punycode: A Bootstring encoding of Unicode for Internationalized Domain Names in Applications (IDNA)", IETF RFC3492, March 2003.

• http://www.ietf.org/rfc/rfc3492.txt

=== Questions, comments, patches?

If you have any questions, comments or feature requests or if you want to submit a bug report or provide a patch, then have a look at the project website at

• http://rubyforge.org/projects/idn

For other information, feel free to ask on the idn-discuss at rubyforge.org mailing list.

=== Copyright & License

Copyright (c) 2005-2006 Erik Abele. All rights reserved.

This documentation and the software itself are licensed under the Apache License, Version 2.0 (the "License").

Some portions of the software come with separate copyright notices and are subject to additional license terms. Please see the file called LICENSE for further details on these subcomponents of the software.

You may also obtain a copy of the License at

• http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.