Raised by Gem::Validator when something is not right in a gem.
Raised by Gem::WebauthnListener when an error occurs during security device verification.
Raised by Resolver when a dependency requests a gem for which there is no spec.
Gem::PathSupport facilitates the GEM_HOME and GEM_PATH environment settings to the rest of RubyGems.
The Specification class contains the information for a gem. Typically defined in a .gemspec file or a Rakefile, and looks like this:
Gem::Specification.new do |s| s.name = 'example' s.version = '0.1.0' s.licenses = ['MIT'] s.summary = "This is an example!" s.description = "Much longer explanation of the example!" s.authors = ["Ruby Coder"] s.email = 'rubycoder@example.com' s.files = ["lib/example.rb"] s.homepage = 'https://rubygems.org/gems/example' s.metadata = { "source_code_uri" => "https://github.com/example/example" } end
Starting in RubyGems 2.0, a Specification can hold arbitrary metadata. See metadata for restrictions on the format and size of metadata items you may add to a specification.
Gem::StubSpecification reads the stub: line from the gemspec. This prevents us having to eval the entire gemspec in order to find out certain information.
Validator performs various gem file and gem database validation
Searches code for a syntax error
There are three main phases in the algorithm:
Sanitize/format input source
Search for invalid blocks
Format invalid blocks into something meaninful
This class handles the part.
The bulk of the heavy lifting is done in:
- CodeFrontier (Holds information for generating blocks and determining if we can stop searching) - ParseBlocksFromLine (Creates blocks into the frontier) - BlockExpand (Expands existing blocks to search more code)
## Syntax error detection
When the frontier holds the syntax error, we can stop searching
search = CodeSearch.new(<<~EOM) def dog def lol end EOM search.call search.invalid_blocks.map(&:to_s) # => # => ["def lol\n"]
Converts a SyntaxError message to a path
Handles the case where the filename has a colon in it such as on a windows file system: github.com/ruby/syntax_suggest/issues/111
Example:
message = "/tmp/scratch:2:in `require_relative': /private/tmp/bad.rb:1: syntax error, unexpected `end' (SyntaxError)" puts PathnameFromMessage.new(message).call.name # => "/tmp/scratch.rb"
RFC6068, the mailto URL scheme.
Raised when a mathematical function is evaluated outside of its domain of definition.
For example, since cos returns values in the range -1..1, its inverse function acos is only defined on that interval:
Math.acos(42)
produces:
Math::DomainError: Numerical argument is out of domain - "acos"
A Process::Status contains information about a system process.
Thread-local variable $? is initially nil. Some methods assign to it a Process::Status object that represents a system process (either running or terminated):
`ruby -e "exit 99"` stat = $? # => #<Process::Status: pid 1262862 exit 99> stat.class # => Process::Status stat.to_i # => 25344 stat.stopped? # => false stat.exited? # => true stat.exitstatus # => 99
This is not an existing class, but documentation of the interface that Scheduler object should comply to in order to be used as argument to Fiber.scheduler and handle non-blocking fibers. See also the “Non-blocking fibers” section in Fiber class docs for explanations of some concepts.
Scheduler’s behavior and usage are expected to be as follows:
When the execution in the non-blocking Fiber reaches some blocking operation (like sleep, wait for a process, or a non-ready I/O), it calls some of the scheduler’s hook methods, listed below.
Scheduler somehow registers what the current fiber is waiting on, and yields control to other fibers with Fiber.yield (so the fiber would be suspended while expecting its wait to end, and other fibers in the same thread can perform)
At the end of the current thread execution, the scheduler’s method scheduler_close is called
The scheduler runs into a wait loop, checking all the blocked fibers (which it has registered on hook calls) and resuming them when the awaited resource is ready (e.g. I/O ready or sleep time elapsed).
This way concurrent execution will be achieved transparently for every individual Fiber’s code.
Scheduler implementations are provided by gems, like Async.
Hook methods are:
io_wait, io_read, io_write, io_pread, io_pwrite, and io_select, io_close
(the list is expanded as Ruby developers make more methods having non-blocking calls)
When not specified otherwise, the hook implementations are mandatory: if they are not implemented, the methods trying to call hook will fail. To provide backward compatibility, in the future hooks will be optional (if they are not implemented, due to the scheduler being created for the older Ruby version, the code which needs this hook will not fail, and will just behave in a blocking fashion).
It is also strongly recommended that the scheduler implements the fiber method, which is delegated to by Fiber.schedule.
Sample toy implementation of the scheduler can be found in Ruby’s code, in test/fiber/scheduler.rb
An ObjectSpace::WeakMap is a key-value map that holds weak references to its keys and values, so they can be garbage-collected when there are no more references left.
Keys in the map are compared by identity.
m = ObjectSpace::WeekMap.new key1 = "foo" val1 = Object.new m[key1] = val1 key2 = "foo" val2 = Object.new m[key2] = val2 m[key1] #=> #<Object:0x0...> m[key2] #=> #<Object:0x0...> val1 = nil # remove the other reference to value GC.start m[key1] #=> nil m.keys #=> ["bar"] key2 = nil # remove the other reference to key GC.start m[key2] #=> nil m.keys #=> []
(Note that GC.start is used here only for demonstrational purposes and might not always lead to demonstrated results.)
See also ObjectSpace::WeakKeyMap map class, which compares keys by value, and holds weak references only to the keys.
An ObjectSpace::WeakKeyMap is a key-value map that holds weak references to its keys, so they can be garbage collected when there is no more references.
Unlike ObjectSpace::WeakMap:
references to values are strong, so they aren’t garbage collected while they are in the map;
keys are compared by value (using Object#eql?), not by identity;
only garbage-collectable objects can be used as keys.
map = ObjectSpace::WeakKeyMap.new val = Time.new(2023, 12, 7) key = "name" map[key] = val # Value is fetched by equality: the instance of string "name" is # different here, but it is equal to the key map["name"] #=> 2023-12-07 00:00:00 +0200 val = nil GC.start # There is no more references to `val`, yet the pair isn't # garbage-collected. map["name"] #=> 2023-12-07 00:00:00 +0200 key = nil GC.start # There is no more references to `key`, key and value are # garbage-collected. map["name"] #=> nil
(Note that GC.start is used here only for demonstrational purposes and might not always lead to demonstrated results.)
The collection is especially useful for implementing caches of lightweight value objects, so that only one copy of each value representation would be stored in memory, but the copies that aren’t used would be garbage-collected.
CACHE = ObjectSpace::WeakKeyMap def make_value(**) val = ValueObject.new(**) if (existing = @cache.getkey(val)) # if the object with this value exists, we return it existing else # otherwise, put it in the cache @cache[val] = true val end end
This will result in make_value returning the same object for same set of attributes always, but the values that aren’t needed anymore woudn’t be sitting in the cache forever.
Commands will be placed in this namespace
Provides 3 methods for declaring when something is going away.
+deprecate(name, repl, year, month)+:
Indicate something may be removed on/after a certain date.
+rubygems_deprecate(name, replacement=:none)+:
Indicate something will be removed in the next major RubyGems version, and (optionally) a replacement for it.
rubygems_deprecate_command:
Indicate a RubyGems command (in +lib/rubygems/commands/*.rb+) will be removed in the next RubyGems version.
Also provides skip_during for temporarily turning off deprecation warnings. This is intended to be used in the test suite, so deprecation warnings don’t cause test failures if you need to make sure stderr is otherwise empty.
Example usage of deprecate and rubygems_deprecate:
class Legacy def self.some_class_method # ... end def some_instance_method # ... end def some_old_method # ... end extend Gem::Deprecate deprecate :some_instance_method, "X.z", 2011, 4 rubygems_deprecate :some_old_method, "Modern#some_new_method" class << self extend Gem::Deprecate deprecate :some_class_method, :none, 2011, 4 end end
Example usage of rubygems_deprecate_command:
class Gem::Commands::QueryCommand < Gem::Command extend Gem::Deprecate rubygems_deprecate_command # ... end
Example usage of skip_during:
class TestSomething < Gem::Testcase def test_some_thing_with_deprecations Gem::Deprecate.skip_during do actual_stdout, actual_stderr = capture_output do Gem.something_deprecated end assert_empty actual_stdout assert_equal(expected, actual_stderr) end end end
Mixin methods for install and update options for Gem::Commands