README.md in polyfill-0.6.0 vs README.md in polyfill-0.7.0
- old
+ new
@@ -8,19 +8,18 @@
advantages while retaining backwards compatibility. It can also be used for
code that would like newer features but is not completely ready to upgrade
Ruby versions. The polyfills are built using refinements so there is **no
monkey patching** that may cause issues outside of your use.
-Right now the only update is from 2.3 to 2.4 however the goal is to go all the way back to 2.0 (when refinements were introduced). Additionally, core methods are being focused on but stdlib will eventually be added.
-
- [Caveat Emptor](#caveat-emptor)
- [Installation](#installation)
- [Goals](#goals)
- [Usage](#usage)
- [Implementation Table](#implementation-table)
- - [2.3 to 2.4](#23-to-24)
- - [2.2 to 2.3](#22-to-23)
+ - [2.4](#24)
+ - [2.3](#23)
+ - [2.2](#22)
## Caveat Emptor
Not all features can be perfectly implemented. This is a best effort
implementation but it's best to always test thoroughly across versions.
@@ -32,11 +31,11 @@
## Installation
Add it to your Gemfile:
```ruby
-gem 'polyfill', '0.6.0'
+gem 'polyfill', '0.7.0'
```
Or install it manually:
```sh
@@ -45,71 +44,76 @@
This project uses [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
## Goals
-1. Features should ideally mimic the true behavior (including bugs).
+1. Features should ideally mimic the true behavior (including bugs, error messages, etc).
2. Features should not significantly burden the runtime.
3. Keep everything modular so users can be specific or broad in their usage.
## Usage
-To use all updates:
+With the `Polyfill` method, you can polyfill methods for one or more Ruby
+objects. Each object is passed as a key. The value is an array of strings
+containing the methods you would like to polyfill. Instance methods need to
+start with '#' and class methods need to start with '.'.
```ruby
-using Polyfill
-```
-
-To specify methods from a particular object use it's class name and pass an
-array of strings containing the methods you'd like to use. Instance methods
-need to start with "#" and class methods need to start with ".".
-
-```ruby
using Polyfill(
Array: %w[#concat],
Dir: %w[.empty?],
- Hash: %w[#compact! #transform_values],
+ Hash: %w[#compact! #transform_values]
)
```
-If you want all of the methods for a particular class you can use `:all`.
+If you want all of the methods for a particular object you can use `:all` in
+place of the array.
```ruby
using Polyfill(Numeric: :all)
```
-Updates can be stopped at a specific version by pass it via `:version`. The
-version selected must be formatted as "MAJOR.MINOR".
+Polyfills can be halted at a maximum version with the `:version` option. The
+version must be a string with the major and minor version only.
```ruby
using Polyfill(version: '2.3', Numeric: :all)
```
-Methods can be included in the same way. Prior to Ruby 2.4, refinements did
-not work on modules. In order to get methods you'll need to include them after
-the module. Calling `using` on a module will add it to all core Ruby classes
-that include it. The methods will only be included if they are needed by the
-Ruby version running the code.
+When you add a method it will not be available in all of the ways a normal
+method is. For example, you can't call `send` on a refined method prior to
+Ruby 2.4. To gain back some of this support you can set `native: true`.
+This currently adds support for `respond_to?`, `__send__`, and `send`.
```ruby
+using Polyfill(native: true, Numeric: :all)
+```
+
+Prior to Ruby 2.4, refinements do not work on Modules. When using a polyfill
+on a module it will instead refine the core classes that use the module. If
+you're building your own class, it will not receive the polyfill. Instead,
+you can add the polyfill by using `include`.
+
+```ruby
class Foo
include Comparable
- include Polyfill(Comparable: %w[#clamp])
+ include Polyfill(Comparable: :all)
end
```
## Implementation Table
-### 2.3 to 2.4
+### 2.4
| Object | Method | Implemented | Notes |
| ---------------- | ------------------------ | ----------- | ----- |
| Array | #concat | Yes |
| | #max | No | This method already existed but was inherited from `Enumerable`. It was optimized on `Array` so redefining `Enumerable#max` no longer affects this.
| | #min | No | This method already existed but was inherited from `Enumerable`. It was optimized on `Array` so redefining `Enumerable#min` no longer affects this.
| | #pack | No |
| | #sum | Yes |
+| BasicObject | #__send__ | No |
| Binding | #irb | No |
| Comparable | #clamp | Yes |
| CSV | #new | No |
| Dir | .empty? | Yes |
| Enumerable | #chunk | Yes |
@@ -139,10 +143,11 @@
| | #readline | Yes |
| | #readlines | Yes |
| | .readlines | Yes |
| IPAddr | #== | Yes |
| | #<=> | Yes |
+| Kernel | #send | No |
| Logger | #new | No |
| MatchData | #named_captures | Yes |
| | #values_at | Yes |
| Module | #refine | No |
| | .used_modules | No |
@@ -195,18 +200,19 @@
| | #downcase! | No |
| | #match | Yes |
| | #match? | Yes |
| | #swapcase | No |
| | #swapcase! | No |
+| | #to_proc | No |
| | #upcase | No |
| | #upcase! | No |
| Thread | #report\_on\_exception | No |
| | .report\_on\_exception | No |
| TracePoint | #callee_id | No |
| Warning | #warn | No |
-### 2.2 to 2.3
+### 2.3
| Object | Method | Implemented | Notes |
| ----------------------- | ------------------------ | ----------- | ----- |
| ARGF | #read_nonblock | No |
| Array | #bsearch_index | No |
@@ -240,11 +246,11 @@
| | #to_proc | Partial | Works in every respect but returns a `lambda` instead of a `proc`. Returning a `proc` may be an error in MRI's implementation. See: https://bugs.ruby-lang.org/issues/12671
| IO | #advise | No |
| | #close | No |
| | #each_codepoint | No |
| | #wait_readable | No |
-| Kernel | #loop | No |
+| Kernel | #loop | Yes |
| Logger | #level= | No |
| | #reopen | No |
| Module | #define_method | No |
| | #deprecate_constant | No |
| NameError | #receiver | No |
@@ -276,9 +282,82 @@
| TCPServer | #accept_nonblock | No |
| Thread | #name | No |
| | #name= | No |
| UNIXServer | #accept_nonblock | No |
| Vector | #round | No |
+
+### 2.2
+
+| Object | Method | Implemented | Notes |
+| ---------- | --------------------------------------- | ----------- | ----- |
+| Binding | #local_variables | No |
+| | #receiver | No |
+| Dir | #fileno | No |
+| Enumerable | #max | No |
+| | #max_by | No |
+| | #min | No |
+| | #min_by | No |
+| | #slice_after | Yes |
+| | #slice_when | No |
+| Etc | .confstr | No |
+| | .sysconf | No |
+| | .nprocessors | No |
+| | .uname | No |
+| Float | #next_float | No |
+| | #prev_float | No |
+| File | .birthtime | No |
+| | #birthtime | No |
+| | .find | No |
+| | #find | No |
+| File::Stat | #birthtime | No |
+| GC | .latest_gc_info | No |
+| | .stat | No |
+| IO | #each_codepoint | No |
+| | #nonblock_read | No |
+| | #nonblock_write | No |
+| | #pathconf | No |
+| Kernel | #itself | Yes |
+| | #throw | No |
+| Math | .atan2 | No |
+| | .log | No |
+| Matrix | #+@ | No |
+| | #-@ | No |
+| | #adjugate | No |
+| | #cofactor | No |
+| | #first_minor | No |
+| | .hstack | No |
+| | #hstack | No |
+| | #laplace_expansion | No |
+| | .vstack | No |
+| | #vstack | No |
+| Method | #curry | No |
+| | #super_method | No |
+| ObjectSpace | .memsize_of | No |
+| Pathname | #/ | No |
+| | #birthtime | No |
+| | #find | No |
+| Prime | .prime? | No |
+| Process | .spawn | No |
+| String | #unicode_normalize | No |
+| | #unicode_normalize! | No |
+| | #unicode_normalized? | No |
+| Time | .httpdate | No |
+| | .parse | No |
+| | .rfc2822 | No |
+| | .strptime | No |
+| | .xmlschema | No |
+| TSort | .each_strongly_connected_component | No |
+| | .each_strongly_connected_component_from | No |
+| | .tsort_each | No |
+| Vector | #+@ | No |
+| | #-@ | No |
+| | #angle_with | No |
+| | .basis | No |
+| | #cross | No |
+| | #cross_product | No |
+| | #dot | No |
+| | .independent? | No |
+| | #independent? | No |
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/AaronLasseigne/polyfill.
Please read the [contributing file](CONTRIBUTING.md) prior to pull requests.