@rafaelfranca suggested in f7c7bcd9 that code examples should display
the result after `# =>` and not after `#=>`.
This commit replaces *all* the occurrences of `#=>` in the code documentation
(mostly added by me 😭) with the suggested `# =>`.
Stems from [Google group discussion](https://groups.google.com/forum/#!topic/rubyonrails-core/jSPbP-TNLb0).
Currently `AS::TimeWithZone` has two methods to add an interval to a time:
`+(other)` and `since(other)` ([docs](http://edgeapi.rubyonrails.org/classes/ActiveSupport/TimeWithZone.html)).
The two methods are "pretty much" equivalent in every case:
1. When adding any interval to an `AS::TimeWithZone` representing a `Time`:
```ruby
t = Time.now.in_time_zone #=> Thu, 04 Dec 2014 18:56:28 EST -05:00
t + 1 == t.since(1) #=> true
t + 1.day == t.since(1.day) #=> true
t + 1.month == t.since(1.month) #=> true
```
2. When adding any interval to an `AS::TimeWithZone` representing a `Date`:
```ruby
d = Date.today.in_time_zone #=> Thu, 04 Dec 2014 00:00:00 EST -05:00
d + 1 == d.since(1) #=> true
d + 1.day == d.since(1.day) #=> true
d + 1.month == d.since(1.month) #=> true
```
3. When adding any interval to an `AS::TimeWithZone` representing a `DateTime`:
```ruby
dt = DateTime.now.in_time_zone #=> Thu, 04 Dec 2014 18:57:28 EST -05:00
dt + 1 == dt.since(1) #=> true
dt + 1.day == dt.since(1.day) #=> true
dt + 1.month == dt.since(1.month) #=> false
```
As you can see, the only case in which they differ is when the interval added
to a `DateTime` is in a format like `1.month`.
However, this usage of "since" is explicitly discouraged by the
[documentation of `DateTime#since`](https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/date_time/calculations.rb#L86L88):
> Returns a new DateTime representing the time a number of seconds since the instance time.
> Do not use this method in combination with x.months, use months_since instead!
And indeed, following this recommendation the correct result is returned:
```ruby
dt + 1.month == dt.months_since 1 #=> true
```
Therefore, my proposal is to remove the method definition of `TimeWithZone#since`
and instead replace it with a simple `alias_method :since, :+`.
The rationale is that the only case where they differ is a case that is
explicitly discouraged as "wrong".
In my opinion, having two methods named `since` and `+` and having to figure
out exactly what the difference is makes the codebase more confusing.
However, I understand this PR is "subjective", so if you feel like it's better
to ignore this, feel free to close the PR.
Thanks!
`define_callbacks` from `ActiveSupport::Callbacks` accepts the
`:skip_after_callbacks_if_terminated` option since #4866 but the option
is not tested anywhere.
This commit adds tests and fixes documentation for the option, making it clear
that halting a callback chain only stops following `before_` and `around_`
callbacks by default.
[ci skip]
As confirmed by @lleger (the author of `verified`) [in this comment](https://github.com/rails/rails/pull/17727#issuecomment-65488743):
> Actually, it no longer returns false explicitly (bc8cc56), so I guess the CHANGELOG isn't totally accurate. It returns nil instead (but the functionality isn't practically different).
Some `require 'openssl'` statements were surrounded by `rescue` blocks to deal with Ruby versions that did not support `OpenSSL::Digest::SHA1` or `OpenSSL::PKCS5`.
[As @jeremy explains](a6a0904fcb (commitcomment-8826666)) in the original commit:
> If jruby didn't have jruby-openssl gem, the require wouldn't work. Not sure whether either of these are still relevant today.
According to the [release notes for JRuby 1.7.13](http://www.jruby.org/2014/06/24/jruby-1-7-13.html):
> jruby-openssl 0.9.5 bundled
which means the above `rescue` block is not needed anymore.
All the Ruby versions supported by the current version of Rails provide those OpenSSL libraries, so Travis CI should also be happy by removing the `rescue` blocks.
---
Just to confirm, with JRuby:
$ ruby --version #=> jruby 1.7.16.1 (1.9.3p392) 2014-10-28 4e93f31 on Java HotSpot(TM) 64-Bit Server VM 1.8.0_20-b26 +jit [darwin-x86_64]
$ irb
irb(main):001:0> require 'openssl' #=> true
irb(main):002:0> OpenSSL::Digest::SHA1 #=> OpenSSL::Digest::SHA1
irb(main):003:0> OpenSSL::PKCS5 # => OpenSSL::PKCS5
And with Ruby 2.1:
$ ruby --version #=> ruby 2.1.2p95 (2014-05-08 revision 45877) [x86_64-darwin13.0]
$ irb
irb(main):001:0> require 'openssl' #=> true
irb(main):002:0> OpenSSL::Digest::SHA1 #=> OpenSSL::Digest::SHA1
irb(main):003:0> OpenSSL::PKCS5 #=> OpenSSL::PKCS5
This is the project guideline and the reasons are:
* That follows standard Ruby semantics.
* Allows the implementation to avoid artificial code like !! or something ? true : false
* You do not need to rely on the exact type of 3rd party code. For
example, if your method returns str.end_with?('foo') you do not need to
make sure end_with? returns a singleton. Your predicate just propagates
predicate semantics up regardless of what end_with? returns.
This commit adds a `#verified` method to
`ActiveSupport::MessageVerifier` which will return either `false` when
it encounters an error or the message. `#verify` continues to raise an
`InvalidSignature` exception on error.
This commit also adds a convenience boolean method on `MessageVerifier`
as a way to check if a message is valid without performing the
decoding.
It should be part of the documented public API, since we have an entire
section of the guides dedicated to it. Documented in a way that
addresses the concerns which kept it undocumented in the past.
