Polyfill

This gem is no longer supported. I'd recommend exploring ruby-next as a replacement.

Polyfill implements newer Ruby features into older versions. If the Ruby version already supports the polyfill then calling it does nothing. This is designed to allow gem maintainers to use newer methods and gain their 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.

• Installation
• Goals
• Usage
  • Polyfill
  • Polyfill.get
• Implementation Table
  • 2.6
  • 2.5
  • 2.4
  • 2.3
  • 2.2

Installation

Add it to your Gemfile:

gem 'polyfill', '~> 1.9'

Or install it manually:

$ gem install polyfill

This project uses Semantic Versioning.

Goals

1. Features should ideally mimic the true behavior (quirks, 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

Polyfill

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 ".".

using Polyfill(
  Array: %w[#concat],
  Dir: %w[.empty?],
  Hash: %w[#compact! #transform_values]
)

If you want all of the methods for a particular object you can use :all in place of the array.

using Polyfill(Numeric: :all)

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.

using Polyfill(version: '2.3', Numeric: :all)

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.

using Polyfill(native: true, Numeric: :all)

Polyfill.get

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 include (or extend or prepend) in a polyfill with Polyfill.get.

class Foo
  include Comparable
  include Polyfill.get(:Comparable, :all)
end

To use specific methods you can pass an array of symbols in place of :all.

class Foo
  include Comparable
  include Polyfill.get(:Comparable, %i[clamp])
end

Like before, the 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.

class Foo
  include Comparable
  include Polyfill.get(:Comparable, :all, version: '2.3')
end

Implementation Table

✓ = Implemented, ✗ = Not Implemented, P = Partially Implemented

Partial implemented features will be explained in the "Changes" section of the table. The explanation will follow "Differences:".

2.6

2.5

Attempting to modify frozen objects now throws FrozenError instead of RuntimeError. Methods where this change occurred are not listed below even though they have techically changed. FrozenError is a subclass of RuntimeError so it is safe to continue rescuing RuntimeError if needed.

2.4

2.3

2.2

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/AaronLasseigne/polyfill. Please read the contributing file prior to pull requests.

Credits

Polyfill is licensed under the MIT License.