File: README.rdoc

package info (click to toggle)
ruby-backports 3.11.1-2
  • links: PTS, VCS
  • area: main
  • in suites: buster, sid
  • size: 4,496 kB
  • sloc: ruby: 8,288; makefile: 25
file content (393 lines) | stat: -rw-r--r-- 10,743 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
= 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.

== Loading backports

=== Explicitly (recommended)

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.

=== By Module

To bring all the backports for a given Class/Module, you can specify only that Class:

    require 'backports/2.3.0/hash'

This will make sure that Hash responds to dig, fetch_values, <, <=, >, >= and to_proc

=== Up to a specific Ruby version

You can load all backports up to a specific version. For example, to bring any version of Ruby mostly up to Ruby 2.4.0's standards:

  require 'backports/2.4.0'

This will bring in all the features of 1.8.7 and many features of Ruby 1.9.x all the way up to Ruby 2.4.0 (for all versions of Ruby)!

While it is not recommended, you may `require 'backports/latest'` as a shortcut to the latest Ruby version supported. This is equivalent to the deprecated `require 'backports'`.

+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 ruby/spec[https://github.com/ruby/spec]

Let's be a bit more precise about the "breaking code" business. It is of course entirely possible that code will break. In particular, you may be distinguishing parameters with duck typing, but a builtin class may, in the future, be responding to a particular call. Here's [an exemple from Rails](https://github.com/rails/rails/blob/a4b55827721a5967299f3c1531afb3d6d81e4ac0/activerecord/lib/active_record/associations/association.rb#L155-L159) that is relying on the fact that Proc and Method respond to :to_proc and Hash isn't. That is, until Ruby 2.3... This old version of Rails therefore won't work on Ruby 2.3, or on older Rubies with that the `2.3.0/hash/to_proc` loaded...

For Ruby < 2.0, there are some real incompatibilities. 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).

== 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

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 itself, JRuby and Rubinius.

= Complete List of backports

== Ruby 2.5 backports

* Array
  * +append+, +prepend+
* Dir
  * +children+, +each_child+
* Enumerable
  * +any?+, +all?+, +none?+, +one?+ (with pattern argument)
* Hash
  * +slice+
  * +transform_keys+
* Integer
  * +sqrt+
  * +allbits?+, +anybits?+ and +nobits?+
* Kernel
  * +yield_self+
* Module
  * +attr+, +attr_accessor+, +attr_reader+, +attr_writer+ (now public)
  * +define_method+, +alias_method+, +undef_method+, +remove_method+ (now public)
* String
  * +delete_prefix+, +delete_prefix!+
  * +delete_suffix+, +delete_suffix!+
* Struct
  * +new+ (with <code>keyword_init: true</code>)

== Ruby 2.4 backports

* Comparable
  * +clamp+
* Enumerable
  * +sum+
  * +uniq+
* Hash
  * +compact+, +compact!+
  * +transform_values+, +transform_values!+
* Regexp
  * +match?+
* String
  * +match?+
* FalseClass, Fixnum, Float, NilClass, TrueClass
  * +dup+

== Ruby 2.3 backports

* Array
  * +bsearch_index+
  * +dig+
* Enumerable
  * +chunk_while+
  * +grep_v+
* Hash
  * +dig+
  * +fetch_values+
  * +to_proc+
  * <=, <, >=, >
* Numeric
  * +negative?+
  * +positive?+
* String
  * unary + and -
* Struct
  * +dig+

== Ruby 2.2 backports

* Enumerable
  * +slice_after+
  * +slice_when+
* Float
  * +prev_float+
  * +next_float+
* Kernel
  * +itself+
* Method
  * +curry+
  * +super_method+
* String
  * +unicode_normalize+
  * +unicode_normalize!+
  * +unicode_normalize?+

== Ruby 2.1 backports

* Array
  * +to_h+
* Bignum
  * +bit_length+
* Enumerable
  * +to_h+
* Fixnum
  * +bit_length+
* Module
  * +include+ (now public)

== 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)

*Note*: The methods of +Random+ can't be required individually; the class can only be required whole with <tt>require 'backports/1.9.2/random'</tt>.

== 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 after requiring 'backports/std_lib'. Requiring 'backports/std_lib' after the standard libraries is also supported.

  require "backports/std_lib"
  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/]

Requiring backports for a given version of Ruby will also load 'backports/std_lib'.

== 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 ruby/spec[https://github.com/ruby/spec] 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