= Backports Library {<img src="https://travis-ci.org/marcandre/backports.png?branch=master">}[https://travis-ci.org/marcandre/backports] {<img src="https://badge.fury.io/rb/backports.png" alt="Gem Version" />}[http://badge.fury.io/rb/backports] {<img alt='Click here to lend your support to: Ruby Backports and make a donation at www.pledgie.com !' src='http://www.pledgie.com/campaigns/19510.png?skin_name=chrome' border='0'}[http://www.pledgie.com/campaigns/19510]

* Yearning to use some of the new cool features in Ruby 2.0.0 while using 1.8.6?
* 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?
* Can't remember if you can use Array#sample or String#each_char on a friend's box?

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.

For example, if you want to use flat_map, even in Ruby implementations that don't include it, as well as the new bsearch method:

  require 'backports/1.9.2/enumerable/flat_map'
  require 'backports/2.0.0/array/bsearch'

This will enable Enumerable#flat_map and Array#bsearch, using the native versions if available or otherwise provide a pure Ruby version.

You can load many backports at once. For example, any version of Ruby up to today's standards:

  require 'backports'

This will bring in all the features of 1.8.7 and many features of Ruby 1.9.x and even Ruby 2.0.0 (for all versions of Ruby)!

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

== What's inside

Goals for backported features:
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, although you can require some of these changes in addition (see below)

All features of 1.8.7 are backported (well, almost all, see the exception list bellow), and many of the following versions up to 2.1

For historical reasons, 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. These will probably be removed in the future, so it's recommended to require those directly from active_support.

== Installation & compatibility

+backports+ is can be installed with:

  (sudo) gem install backports

To use:

  require 'rubygems'
  # For only specific backports:
  require 'backports/1.9.1/kernel/require_relative'
  require 'backports/2.0.0/enumerable/lazy'

  # For all backports up to a given version
  require 'backports/1.9.2' # All backports for Ruby 1.9.2 and below

  # Or for all backports
  require 'backports'

Note: about a dozen of backports have a dependency that will be also loaded. For example, the backport of Enumerable#flat_map uses flatten(1), so if required from Ruby 1.8.6 (where Array#flatten does not accept an argument), the backport for Ruby's 1.8.7 flatten with an argument will also be loaded.

With bundler, add to your Gemfile:

  gem 'backports', :require => false

Run <tt>bundle install</tt> and require the desired backports.

Compatible with Ruby 1.8.6, 1.8.7, 1.9.1, 1.9.2, 1.9.3, 2.0, 2.1, JRuby and Rubinius.

= Complete List of backports

== Ruby 2.1 backports

* Array
  * +to_h+
* Enumerable
  * +to_h+

== Ruby 2.0 backports

* Array
  * +bsearch+
* Enumerable
  * +lazy+
* Enumerator::Lazy
  * all methods
* Hash
  * <tt>default_proc=</tt> (with nil argument)
  * +to_h+
* nil.to_h
* Range
  * +bsearch+
* Struct
  * +to_h+

== Ruby 1.9.3 backports

* File
  * +NULL+
* IO
  * +advise+ (acts as a noop)
  * +write+, +binwrite+
* String
  * +byteslice+
  * +prepend+

== Ruby 1.9.2 backports

* Array
  * <tt>rotate, rotate!</tt>
  * <tt>keep_if, select!</tt>
  * +product+ (with block)
  * +repeated_combination+, +repeated_permutation+
  * <tt>sort_by!</tt>
  * <tt>uniq, uniq!</tt> (with block)

* Complex
  * +to_r+

* Dir
  * +home+

* Enumerable
  * +chunk+
  * +flat_map+, +collect_concat+
  * +join+
  * +slice_before+

* Float::INFINITY, NAN

* Hash
  * +keep_if+, <tt>select!</tt>

* Object
  * <tt>singleton_class</tt>

* Random (new class)

== Ruby 1.9.1 backports

Additionally, the following Ruby 1.9 features have been backported:
* Array
  * +try_convert+
  * +sample+

* Enumerable
  * +each_with_object+
  * +each_with_index+ (with arguments)

* Enumerator
  * +new+ (with block)

* File
  * +binread+
  * +to_path+
  * All class methods accepting filenames will accept files or anything with a <tt>#to_path</tt> method.
  * <tt>File.open</tt> accepts an options hash.

* Float
  * +round+

* Hash
  * +assoc+, +rassoc+
  * +key+
  * +try_convert+
  * <tt>default_proc=</tt>

* Integer
  * +magnitude+
  * +round+

* IO
  * +bin_read+
  * +try_convert+
  * +ungetbyte+
  * <tt>IO.open</tt> accepts an options hash.

* Kernel
  * +require_relative+

* Math
  * +log+ (with base)
  * +log2+

* Numeric
  * +round+

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

* Proc
  * +yield+
  * +lambda?+
  * +curry+
  * <tt>===</tt>

* Range
  * <tt>cover?</tt>

* Regexp
  * +try_convert+

* String
  * <tt>ascii_only?</tt>
  * +chr+
  * +clear+
  * +codepoints+, +each_codepoint+
  * +get_byte+, +set_byte+
  * +ord+
  * +try_convert+

+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.8.7

Complete Ruby 1.8.7 backporting (core language). Refer to the official list of changes[https://github.com/ruby/ruby/blob/ruby_1_8_7/NEWS]. That's about 130 backports!

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

== Libraries

Libraries are slowly being backported. You simply require them as usual, ideally (but not necessarily) after requiring backports.

  require "backports"
  require "prime"
  42.prime? # => false, even in Ruby 1.8.x

The following libraries are up to date with Ruby 1.9.3:

* Matrix
* Prime
* Set

The following library is to date with Ruby 2.0.0:

* OpenStruct (ostruct)

I am aware of the following backport gem, which probably won't make it into this gem:

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

== Forcing incompatibilities

Some backports would create incompatibilities in their current Ruby version but could be useful in some projects. It is possible to request such incompatible changes. Backports currently supports the following:

* Hash
  * +select+ (returns a Hash instead of an Array)

* Enumerable / Array
  * +map+ (returns an enumerator when called without a block)

* String
  * +length+, +size+ (for UTF-8 support)

These must be imported in addition to the backports gem, for example:

  require "backports/force/hash_select"
  {}.select{} # => {}, even in Ruby 1.8


== Thanks

Thanks for the bug reports and patches, in particular the repeat offenders:

* Arto Bendiken ( bendiken[http://github.com/bendiken] )
* Konstantin Haase ( rkh[https://github.com/rkh])
* Roger Pack ( rdp[http://github.com/rdp] )

The best way to submit a patch is to also submit a patch to RubySpec[https://github.com/rubyspec/rubyspec] and then a patch to backports that make it pass the spec. To test rubyspec:

    git submodule init && git submodule update # => pulls rubyspecs
    rake spec[array/bsearch]       # => tests Array#bsearch
    rake spec[array/*]             # => tests all backported Array methods
    rake spec  (or rake spec[*/*]) # => all rubyspecs for backported methods

Failures that are acceptable are added the to `tags` file.

= License

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

Author::                 Marc-André Lafortune