Module: YARD::LinkStdlib::RubyVersion

Defined in:
lib/yard/link_stdlib/ruby_version.rb

Overview

Handling which version of Ruby to link against.

Constant Summary collapse

MINIMUM_SUPPORTED =

Support for 2.2.X ended March 28, 2017. 2.3 is scheduled to go March 2019.

www.ruby-lang.org/en/news/2018/06/20/support-of-ruby-2-2-has-ended/

Returns:

  • (Gem::Version) 
Gem::Version.new '2.3.0'
LATEST_STABLE =

As of 2018.09.23, the latest stable release

Returns:

  • (Gem::Version) 
Gem::Version.new '2.5.1'
CURRENT_RUNTIME =

Whatever version we’re running here and now.

Returns:

  • (Gem::Version) 
Gem::Version.new RUBY_VERSION
DEFAULT_FALLBACK_MODE =

If no-one tells us different then use the minimum supported Ruby version.

Returns:

  • (Symbol) 
:minimum_supported

Class Method Summary collapse

Class Method Details

.fallback ⇒ Gem::Version

Used as last-resort to pick a version of Ruby to link against, after looking for a user-provided value and trying min_required.

Simply selects between

  1. MINIMUM_SUPPORTED

  2. LATEST_STABLE

  3. CURRENT_RUNTIME

Depending on fallback_mode.

Returns:

  • (Gem::Version) —

    Fallback Ruby version to use.



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/yard/link_stdlib/ruby_version.rb', line 153

def self.fallback
  case fallback_mode
  when :minimum_supported
    MINIMUM_SUPPORTED
  when :latest_stable
    LATEST_STABLE
  when :current_runtime
    CURRENT_RUNTIME
  else
    raise RuntimeError,
      "Bad value #{ fallback_mode.inspect } at " +
      "{YARD::LinkStdlib::RubyVersion.fallback_mode}, " +
      "expected :minimum_supported, :latest_stable or :current_runtime"
  end
end

.fallback_mode ⇒ :minimum_supported, ...

Gets the fallback mode. Uses DEFAULT_FALLBACK_MODE if one was never set.

More details available in fallback_mode= and fallback.

Returns:

  • (:minimum_supported, :latest_stable, :current_runtime) —

    The value that was just set.



134
135
136
 
# File 'lib/yard/link_stdlib/ruby_version.rb', line 134

def self.fallback_mode
  @fallback_mode || DEFAULT_FALLBACK_MODE
end

.fallback_mode=(value) ⇒ :minimum_supported, ...

Set the fallback mode that is used to pick a version of Ruby to link against when no value is provided by the developer and we couldn’t figure one out we were happy with from the gemspec.

Parameters:

Returns:

  • (:minimum_supported, :latest_stable, :current_runtime) —

    The value that was just set.



114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/yard/link_stdlib/ruby_version.rb', line 114

def self.fallback_mode= value
  unless [  :minimum_supported,
            :latest_stable,
            :current_runtime ].include? value
    raise ArgumentError,
      "Fallback-mode must be one of :minimum_supported, :latest_stable, " +
      "or :current_runtime; found #{ value.inspect }"
  end

  @fallback_mode = value
end

.get ⇒ Gem::Version

Get what version of Ruby is set to link to.

Returns:

  • (Gem::Version) —

    Returns the actual in`stance var reference, but it’s frozen, so it should be reasonably OK.



78
79
80
 
# File 'lib/yard/link_stdlib/ruby_version.rb', line 78

def self.get
  @ruby_version || min_required || fallback
end

.min_required ⇒ nil, Gem::Version

Try to get the minimum required Ruby version from the gemspec (the Gem::Specification#required_ruby_version attribute).

Returns:

  • (nil) —

    If we

    1. didn’t find any Gem::Specification#required_ruby_version values, or

    2. couldn’t figure a reasonable version out given what we found.

      This method uses a very simple approach, on the hypothesis that almost all real-world configurations will be really simple, and that it’s more practical for the few that for some reason have some baffling requirement config to just explicitly specify what Ruby version they want to use.

  • (Gem::Version) —

    If we successfully determined a minimum required Ruby version that seems to make some sense to link to.



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
 
# File 'lib/yard/link_stdlib/ruby_version.rb', line 190

def self.min_required
  # Load gemspecs in this dir that have required Ruby versions. There should
  # probably only ever be one, but what they hell this is just as easy as
  # any other handling I thought of off the top of my head...
  specs = Dir[ './*.gemspec' ].
    map { |path|  Gem::Specification.load path }.
    select { |spec|
      spec.required_ruby_version && !spec.required_ruby_version.none?
    }

  # If we didn't find anything useful just assume the gem supports the oldest
  # supported Ruby version and link to that
  return nil if specs.empty?

  # Map to their {Gem::Requirement} instances
  reqs = specs.map &:required_ruby_version

  req_arrays = reqs.
    map( &:requirements ).  # => Array<Array<Array<(String, Gem::Version)>>>
    flatten( 1 ).           # => Array<Array<(String, Gem::Version)>>
    select { |(restriction, version)|
      # We only look at exact `=`, and the "greater-than" ones where we can
      # potentially use the version (with `>` for instance we need to know 
      # if another patch version exists *after* it so we know what to bump
      # it too, and I ain't gonna deal with that tonight)
      case restriction
      when '=', '>=', '~>'
        true
      end
    }.                      # => Array<Array<(String, Gem::Version)>>
    map( &:last ).          # => Array<Gem::Version>
    sort. # So we have min first
    # Then find the first one that satisfies all the {Gem::Requirements},
    # or `nil` if none do
    find { |version| reqs.all? { |req| req.satisfied_by? version } }

end

.minor(version = self.get) ⇒ Gem::Version

ruby_version rounded-off to the minor version (patch set to ‘0`).

[docs.ruby-lang.org](docs.ruby-lang.org) only serves docs for major and minor releases, not patches (‘2.3.0`, `2.4.0`, `2.5.0`, etc.).

Examples:

YARD::LinkStdlib.ruby_version = '2.5.1'
YARD::LinkStdlib.ruby_minor_version #=> '2.5.0'

Returns:

  • (Gem::Version) 


94
95
96
97
 
# File 'lib/yard/link_stdlib/ruby_version.rb', line 94

def self.minor version = self.get
  Gem::Version.new \
    ( version.segments[0..1] + [0] ).map( &:to_s ).join( '.' )
end

.set(version) ⇒ Gem::Version

Set what version of Ruby to link to.

Parameters:

  • version (#to_s) —

    Something that’s string representation is the version you want to set.

    Note that Gem::Version works fine here ‘cause it’s string rep is the version string, effectively meaning a frozen copy of it is stored.

Returns:

  • (Gem::Version) —

    The newly set value. Is frozen.



67
68
69
 
# File 'lib/yard/link_stdlib/ruby_version.rb', line 67

def self.set version
  @ruby_version = Gem::Version.new version
end