= Backports Library

Can't remember if you can use Array#sample? One of your client is stuck with Ruby 1.8.6 but you want to use a gem using some features of 1.8.7? This gem is for you!

The goal of 'backports' is to make it easier to write ruby code that runs across different versions of Ruby. All you need to bring any version of Ruby up to today's standards:

  require 'backports'
  
Actually, it's tomorrow's standard, since this will bring Ruby 1.8.6 or 1.8.7 up to date with the upcoming Ruby 1.8.8, as well as include many features of Ruby 1.9.1 and the upcoming Ruby 1.9.2!

+Note+: Although I am a Ruby committer, this gem is a personal project and is not endorsed by ruby-core.

== What's inside

Features in this gem:
1. Won't break older code
2. Pure Ruby (no C extensions)
3. Pass RubySpec[http://github.com/rubyspec/rubyspec]

Let's be a bit more precise about the breaking code business. It is of course entirely possible that code will break, for example some core methods are monkeypatched or if the code relies on a certain call raising an exception. Example: <tt>[42].sample rescue "dum example"</tt> will return <tt>"dum example"</tt> without this gem and <tt>42</tt> with it.

A real incompatibility is, for example, <tt>Module::instance_methods</tt> which returns strings in 1.8 and symbols in 1.9. No change can be made without the risk of breaking existing code. Such incompatibilities are left unchanged.

All features of 1.8.7 & 1.8.8 are backported (well, almost all, see the exception list bellow), and many of 1.9 are also.

Some generic and self-contained features of active-support are also included. By simple I mean that String#camelcase is there, but #pluralize isn't.

== Installation & compatibility

+backports+ is can be installed with:

  (sudo) gem install backports

To use:

  require 'rubygems'
  require 'backports'   # or a subset, see next section

Compatible with Ruby 1.8.6, 1.8.7, 1.9.1, JRuby and Rubinius, as well as the upcoming Ruby 1.8.8 and 1.9.2

= Complete List of backports

== Ruby 1.8.7

Complete Ruby 1.8.7 backporting (core language). Refer to the official list of changes[http://svn.ruby-lang.org/repos/ruby/branches/ruby_1_8_7/NEWS].

Only exceptions:
* String#gsub (the form returning an enumerator)
* GC.stress=  (not implemented)
* Array#choice (removed in 1.8.8, use Array#sample instead)

To include _only_ these backports, <tt>require "backports/1.8.7"</tt>

== Ruby 1.8.8

Complete Ruby 1.8.8 backporting (core language). In case you are wondering: no, it's not out yet :-). Refer to the official list of changes[http://svn.ruby-lang.org/repos/ruby/branches/ruby_1_8/NEWS].

Only exception:
* Enumerator#rewind (incompatible change, so won't be implemented)

To include _only_ these backports and those preceeding, <tt>require "backports/1.8.8"</tt>.

== Ruby 1.9.1

Additionally, the following Ruby 1.9 features have been backported:

* File
  * +binread+
  * +to_path+
  * All class methods accepting filenames will accept files or anything with a #to_path method.

* IO
  * +bin_read+

* Kernel
  * +require_relative+

* Object
  * +define_singleton_method+
  * +public_method+
  * +public_send+

* Proc
  * +yield+

* String
  * <tt>ascii_only?</tt>
  * +chr+
  * +clear+
  * +codepoints+, +each_codepoint+

+Enumerator+ can be accessed directly (instead of <tt>Enumerable::Enumerator</tt>)

To include _only_ these backports and those of the 1.8 line, <tt>require "backports/1.9.1"</tt>.

Moreover, a pretty good imitation of BasicObject is available,
but since it is only an imitation, it must be required explicitly:

  require 'backports/basic_object'

== Ruby 1.9.2

  Finally, some Ruby 1.9.2 features have been backported. As this version has not been feature frozen yet, changes are still possible.

* Enumerable
  * +flat_map+, +collect_concat+
  * +chunk+

* Object
  * <tt>respond_to_missing?</tt>

To include all Ruby backports but not those of Rails, <tt>require "backports/1.9.2"</tt>.

== Rails

Some generic methods from Rails methods have been copied:

* Enumerable
  * +sum+

* Hash
  * +symbolize_keys+, <tt>symbolize_keys!</tt>
  * +reverse_merge+, <tt>reverse_merge!</tt>

* Module
  * +alias_method_chain+

* Object
  * +try+
  * +returning+

* String
  * +camelize+, +underscore+
  * +dasherize+, +demodulize+
  * +constantize+

To include _only_ these Rails backports but not those of Ruby, <tt>require "backports/rails"</tt>.

== Libraries

Libraries have not been backported. I am aware of the following backport gems:

* Net::SMTP for Ruby 1.8.6: smtp_tls[http://seattlerb.rubyforge.org/smtp_tls/]

* Let me know of others...

= License

+backports+ is released under the terms of the MIT License, see the included LICENSE file.

Author::                 Marc-André Lafortune