# # RubyGems is the Ruby standard for publishing and managing third party # libraries. # # For user documentation, see: # # * `gem help` and `gem help [command]` # * [RubyGems User Guide](https://guides.rubygems.org/) # * [Frequently Asked Questions](https://guides.rubygems.org/faqs) # # # For gem developer documentation see: # # * [Creating Gems](https://guides.rubygems.org/make-your-own-gem) # * Gem::Specification # * Gem::Version for version dependency notes # # # Further RubyGems documentation can be found at: # # * [RubyGems Guides](https://guides.rubygems.org) # * [RubyGems API](https://www.rubydoc.info/github/rubygems/rubygems) (also # available from `gem server`) # # # ## RubyGems Plugins # # RubyGems will load plugins in the latest version of each installed gem or # $LOAD_PATH. Plugins must be named 'rubygems_plugin' (.rb, .so, etc) and # placed at the root of your gem's #require_path. Plugins are installed at a # special location and loaded on boot. # # For an example plugin, see the [Graph gem](https://github.com/seattlerb/graph) # which adds a `gem graph` command. # # ## RubyGems Defaults, Packaging # # RubyGems defaults are stored in lib/rubygems/defaults.rb. If you're packaging # RubyGems or implementing Ruby you can change RubyGems' defaults. # # For RubyGems packagers, provide lib/rubygems/defaults/operating_system.rb and # override any defaults from lib/rubygems/defaults.rb. # # For Ruby implementers, provide lib/rubygems/defaults/#{RUBY_ENGINE}.rb and # override any defaults from lib/rubygems/defaults.rb. # # If you need RubyGems to perform extra work on install or uninstall, your # defaults override file can set pre/post install and uninstall hooks. See # Gem::pre_install, Gem::pre_uninstall, Gem::post_install, Gem::post_uninstall. # # ## Bugs # # You can submit bugs to the [RubyGems bug # tracker](https://github.com/rubygems/rubygems/issues) on GitHub # # ## Credits # # RubyGems is currently maintained by Eric Hodel. # # RubyGems was originally developed at RubyConf 2003 by: # # * Rich Kilmer -- rich(at)infoether.com # * Chad Fowler -- chad(at)chadfowler.com # * David Black -- dblack(at)wobblini.net # * Paul Brannan -- paul(at)atdesk.com # * Jim Weirich -- jim(at)weirichhouse.org # # # Contributors: # # * Gavin Sinclair -- gsinclair(at)soyabean.com.au # * George Marrows -- george.marrows(at)ntlworld.com # * Dick Davies -- rasputnik(at)hellooperator.net # * Mauricio Fernandez -- batsman.geo(at)yahoo.com # * Simon Strandgaard -- neoneye(at)adslhome.dk # * Dave Glasser -- glasser(at)mit.edu # * Paul Duncan -- pabs(at)pablotron.org # * Ville Aine -- vaine(at)cs.helsinki.fi # * Eric Hodel -- drbrain(at)segment7.net # * Daniel Berger -- djberg96(at)gmail.com # * Phil Hagelberg -- technomancy(at)gmail.com # * Ryan Davis -- ryand-ruby(at)zenspider.com # * Evan Phoenix -- evan(at)fallingsnow.net # * Steve Klabnik -- steve(at)steveklabnik.com # # # (If your name is missing, PLEASE let us know!) # # ## License # # See [LICENSE.txt](rdoc-ref:lib/rubygems/LICENSE.txt) for permissions. # # Thanks! # # -The RubyGems Team # module Gem interface _HashLike[K, V] def each_pair: () { ([ K, V ]) -> untyped } -> self end DEFAULT_HOST: String GEM_DEP_FILES: Array[String] # # When https://bugs.ruby-lang.org/issues/17259 is available, there is no need to # override Kernel#warn # KERNEL_WARN_IGNORES_INTERNAL_ENTRIES: bool LOADED_SPECS_MUTEX: Thread::Mutex # # Location of Marshal quick gemspecs on remote repositories # MARSHAL_SPEC_DIR: String # # Exception classes used in a Gem.read_binary `rescue` statement # READ_BINARY_ERRORS: Array[Class] # # Subdirectories in a gem repository for default gems # REPOSITORY_DEFAULT_GEM_SUBDIRECTORIES: Array[String] # # Subdirectories in a gem repository # REPOSITORY_SUBDIRECTORIES: Array[String] RUBYGEMS_DIR: String # # Taint support is deprecated in Ruby 2.7. This allows switching ".untaint" to # ".tap(&Gem::UNTAINT)", to avoid deprecation warnings in Ruby 2.7. # UNTAINT: Proc VERSION: String # # An Array of Regexps that match windows Ruby platforms. # WIN_PATTERNS: Array[Regexp] # # Exception classes used in Gem.write_binary `rescue` statement # WRITE_BINARY_ERRORS: Array[Class] # # The number of paths in the +$LOAD_PATH+ from activated gems. Used to # prioritize `-I` and `ENV['RUBYLIB']` entries during `require`. # def self.activated_gem_paths: () -> Integer # # Add a list of paths to the $LOAD_PATH at the proper place. # def self.add_to_load_path: (*String paths) -> Array[String] # # Find the full path to the executable for gem `name`. If the `exec_name` is # not given, an exception will be raised, otherwise the specified executable's # path is returned. `requirements` allows you to specify specific gem versions. # def self.bin_path: (String name, String exec_name, ?Array[Requirement] requirements) -> String # # The mode needed to read a file as straight binary. # def self.binary_mode: () -> String # # The path where gem executables are to be installed. # def self.bindir: (?String install_dir) -> String # # The path to standard location of the user's cache directory. # def self.cache_home: () -> String # # Clear default gem related variables. It is for test # def self.clear_default_specs: () -> void # # Reset the `dir` and `path` values. The next time `dir` or `path` is # requested, the values will be calculated from scratch. This is mainly used by # the unit tests to provide test isolation. # def self.clear_paths: () -> void # # The path to standard location of the user's .gemrc file. # def self.config_file: () -> String # # The path to standard location of the user's configuration directory. # def self.config_home: () -> String # # The standard configuration object for gems. # def self.configuration: () -> ConfigFile # # Use the given configuration object (which implements the ConfigFile protocol) # as the standard configuration object. # def self.configuration=: (ConfigFile config) -> ConfigFile # # The path to standard location of the user's data directory. # def self.data_home: () -> String # # The default directory for binaries # def self.default_bindir: () -> String # # The default signing certificate chain path # def self.default_cert_path: () -> String # # Default home directory path to be used if an alternate value is not specified # in the environment # def self.default_dir: () -> String # # Deduce Ruby's --program-prefix and --program-suffix from its install name # def self.default_exec_format: () -> String # # Returns binary extensions dir for specified RubyGems base dir or nil if such # directory cannot be determined. # # By default, the binary extensions are located side by side with their Ruby # counterparts, therefore nil is returned # def self.default_ext_dir_for: (String base_dir) -> String? # # The default signing key path # def self.default_key_path: () -> String # # Default gem load path # def self.default_path: () -> Array[String] # # Paths where RubyGems' .rb files and bin files are installed # def self.default_rubygems_dirs: () -> Array[String]? # # An Array of the default sources that come with RubyGems # def self.default_sources: () -> Array[String] # # Default spec directory path to be used if an alternate value is not specified # in the environment # def self.default_spec_cache_dir: () -> String # # Path to specification files of default gems. # def self.default_specifications_dir: () -> String # # A Zlib::Deflate.deflate wrapper # def self.deflate: (String data) -> String # # The path where gems are to be installed. # def self.dir: () -> String # # RubyGems distributors (like operating system package managers) can disable # RubyGems update by setting this to error message printed to end-users on gem # update --system instead of actual update. # def self.disable_system_update_message: () -> String? # # RubyGems distributors (like operating system package managers) can disable # RubyGems update by setting this to error message printed to end-users on gem # update --system instead of actual update. # def self.disable_system_update_message=: (String?) -> String? # # Adds a post-installs hook that will be passed a Gem::DependencyInstaller and a # list of installed specifications when Gem::DependencyInstaller#install is # complete # def self.done_installing: () { (DependencyInstaller, Array[Specification]) -> untyped } -> Array[Proc] # # The list of hooks to be run after Gem::DependencyInstaller installs a set of # gems # def self.done_installing_hooks: () -> Array[Proc?] # # Quietly ensure the Gem directory `dir` contains all the proper subdirectories # for handling default gems. If we can't create a directory due to a permission # problem, then we will silently continue. # # If `mode` is given, missing directories are created with this mode. # # World-writable directories will never be created. # def self.ensure_default_gem_subdirectories: (?String dir, ?Integer | String mode) -> Array[String] # # Quietly ensure the Gem directory `dir` contains all the proper subdirectories. # If we can't create a directory due to a permission problem, then we will # silently continue. # # If `mode` is given, missing directories are created with this mode. # # World-writable directories will never be created. # def self.ensure_gem_subdirectories: (?String dir, ?Integer | String mode) -> Array[String] # # def self.env_requirement: (String gem_name) -> Requirement # # Finds the user's config file # def self.find_config_file: () -> String # # Returns a list of paths matching `glob` that can be used by a gem to pick up # features from other gems. For example: # # Gem.find_files('rdoc/discover').each do |path| load path end # # if `check_load_path` is true (the default), then find_files also searches # $LOAD_PATH for files as well as gems. # # Note that find_files will return all files even if they are from different # versions of the same gem. See also find_latest_files # def self.find_files: (String glob, ?boolish check_load_path) -> Array[String] # # Returns a list of paths matching `glob` from the latest gems that can be used # by a gem to pick up features from other gems. For example: # # Gem.find_latest_files('rdoc/discover').each do |path| load path end # # if `check_load_path` is true (the default), then find_latest_files also # searches $LOAD_PATH for files as well as gems. # # Unlike find_files, find_latest_files will return only files from the latest # version of a gem. # def self.find_latest_files: (String glob, ?boolish check_load_path) -> Array[String] # # Find a Gem::Specification of default gem from `path` # def self.find_unresolved_default_spec: (String path) -> Specification? # # def self.finish_resolve: (?RequestSet request_set) -> void # # GemDependencyAPI object, which is set when .use_gemdeps is called. This # contains all the information from the Gemfile. # def self.gemdeps: () -> RequestSet::GemDependencyAPI? # # Get the default RubyGems API host. This is normally `https://rubygems.org`. # def self.host: () -> String # # Set the default RubyGems API host. # def self.host=: (String host) -> String # # Top level install helper method. Allows you to install gems interactively: # # % irb # >> Gem.install "minitest" # Fetching: minitest-5.14.0.gem (100%) # => [#] # def self.install: (String name, ?Gem::Requirement version, *DependencyInstaller::options options) -> Array[Specification] # # Is this a java platform? # def self.java_platform?: () -> bool # # Returns the latest release version of RubyGems. # def self.latest_rubygems_version: () -> Version # # Returns the latest release-version specification for the gem `name`. # def self.latest_spec_for: (String name) -> Specification? # # Returns the version of the latest release-version of gem `name` # def self.latest_version_for: (String name) -> Version? # # Find all 'rubygems_plugin' files in $LOAD_PATH and load them # def self.load_env_plugins: () -> Array[String] # # The index to insert activated gem paths into the $LOAD_PATH. The activated # gem's paths are inserted before site lib directory by default. # def self.load_path_insert_index: () -> Integer # # Find rubygems plugin files in the standard location and load them # def self.load_plugins: () -> Array[String] # # Loads YAML, preferring Psych # def self.load_yaml: () -> bool? # # Hash of loaded Gem::Specification keyed by name # def self.loaded_specs: () -> Hash[String, BasicSpecification] # # The file name and line number of the caller of the caller of this method. # # `depth` is how many layers up the call stack it should go. # # e.g., # # def a; Gem.location_of_caller; end a #=> ["x.rb", 2] # (it'll vary depending # on file name and line number) # # def b; c; end def c; Gem.location_of_caller(2); end b #=> ["x.rb", 6] # # (it'll vary depending on file name and line number) # def self.location_of_caller: (?Integer depth) -> [ String, Integer ] # # The version of the Marshal format for your Ruby. # def self.marshal_version: () -> String # # def self.needs: () { (RequestSet) -> void } -> void # # Default options for gem commands for Ruby packagers. # # The options here should be structured as an array of string "gem" command # names as keys and a string of the default options as values. # # Example: # # def self.operating_system_defaults # { # 'install' => '--no-rdoc --no-ri --env-shebang', # 'update' => '--no-rdoc --no-ri --env-shebang' # } # # end # def self.operating_system_defaults: () -> Hash[String, String] # # def self.path: () -> Array[String] # # How String Gem paths should be split. Overridable for esoteric platforms. # def self.path_separator: () -> String # # Retrieve the PathSupport object that RubyGems uses to lookup files. # def self.paths: () -> PathSupport # # Initialize the filesystem paths to use from `env`. `env` is a hash-like object # (typically ENV) that is queried for 'GEM_HOME', 'GEM_PATH', and # 'GEM_SPEC_CACHE' Keys for the `env` hash should be Strings, and values of the # hash should be Strings or `nil`. # def self.paths=: (_HashLike[String, String?] env) -> Array[String] # # Default options for gem commands for Ruby implementers. # # The options here should be structured as an array of string "gem" command # names as keys and a string of the default options as values. # # Example: # # def self.platform_defaults # { # 'install' => '--no-rdoc --no-ri --env-shebang', # 'update' => '--no-rdoc --no-ri --env-shebang' # } # # end # def self.platform_defaults: () -> Hash[String, String] # # Array of platforms this RubyGems supports. # def self.platforms: () -> Array[String | Platform] # # Set array of platforms this RubyGems supports (primarily for testing). # def self.platforms=: (Array[String | Platform] platforms) -> Array[String | Platform] # # Glob pattern for require-able plugin suffixes. # def self.plugin_suffix_pattern: () -> String # # Regexp for require-able plugin suffixes. # def self.plugin_suffix_regexp: () -> Regexp # # The path were rubygems plugins are to be installed. # def self.plugindir: (?String install_dir) -> String # # Adds a post-build hook that will be passed an Gem::Installer instance when # Gem::Installer#install is called. The hook is called after the gem has been # extracted and extensions have been built but before the executables or gemspec # has been written. If the hook returns `false` then the gem's files will be # removed and the install will be aborted. # def self.post_build: () { (Installer) -> untyped } -> Array[Proc] # # The list of hooks to be run after Gem::Installer#install extracts files and # builds extensions # def self.post_build_hooks: () -> Array[Proc] # # Adds a post-install hook that will be passed an Gem::Installer instance when # Gem::Installer#install is called # def self.post_install: () { (Installer) -> untyped } -> Array[Proc] # # The list of hooks to be run after Gem::Installer#install completes # installation # def self.post_install_hooks: () -> Array[Proc] # # Adds a hook that will get run after Gem::Specification.reset is run. # def self.post_reset: () { () -> untyped } -> Array[Proc] # # The list of hooks to be run after Gem::Specification.reset is run. # def self.post_reset_hooks: () -> Array[Proc?] # # Adds a post-uninstall hook that will be passed a Gem::Uninstaller instance and # the spec that was uninstalled when Gem::Uninstaller#uninstall is called # def self.post_uninstall: () { (Uninstaller) -> untyped } -> Array[Proc] # # The list of hooks to be run after Gem::Uninstaller#uninstall completes # installation # def self.post_uninstall_hooks: () -> Array[Proc?] # # Adds a pre-install hook that will be passed an Gem::Installer instance when # Gem::Installer#install is called. If the hook returns `false` then the # install will be aborted. # def self.pre_install: () { (Installer) -> untyped } -> Array[Proc] # # The list of hooks to be run before Gem::Installer#install does any work # def self.pre_install_hooks: () -> Array[Proc?] # # Adds a hook that will get run before Gem::Specification.reset is run. # def self.pre_reset: () { () -> untyped } -> Array[Proc] # # The list of hooks to be run before Gem::Specification.reset is run. # def self.pre_reset_hooks: () -> Array[Proc?] # # Adds a pre-uninstall hook that will be passed an Gem::Uninstaller instance and # the spec that will be uninstalled when Gem::Uninstaller#uninstall is called # def self.pre_uninstall: () { (Uninstaller) -> untyped } -> Array[Proc] # # The list of hooks to be run before Gem::Uninstaller#uninstall does any work # def self.pre_uninstall_hooks: () -> Array[Proc?] # # The directory prefix this RubyGems was installed at. If your prefix is in a # standard location (ie, rubygems is installed where you'd expect it to be), # then prefix returns nil. # def self.prefix: () -> String? # # Safely read a file in binary mode on all platforms. # def self.read_binary: (String path) -> String # # Refresh available gems from disk. # def self.refresh: () -> Array[Proc] # # Register a Gem::Specification for default gem. # # Two formats for the specification are supported: # # * MRI 2.0 style, where spec.files contains unprefixed require names. The # spec's filenames will be registered as-is. # * New style, where spec.files contains files prefixed with paths from # spec.require_paths. The prefixes are stripped before registering the # spec's filenames. Unprefixed files are omitted. # def self.register_default_spec: (Specification spec) -> Array[String] # # The path to the running Ruby interpreter. # def self.ruby: () -> String # # Returns a String containing the API compatibility version of Ruby # def self.ruby_api_version: () -> String # # def self.ruby_engine: () -> String # # A Gem::Version for the currently running Ruby. # def self.ruby_version: () -> Version # # A Gem::Version for the currently running RubyGems # def self.rubygems_version: () -> Version # # Returns the value of Gem.source_date_epoch_string, as a Time object. # # This is used throughout RubyGems for enabling reproducible builds. # def self.source_date_epoch: () -> Time # # If the SOURCE_DATE_EPOCH environment variable is set, returns it's value. # Otherwise, returns the time that `Gem.source_date_epoch_string` was first # called in the same format as SOURCE_DATE_EPOCH. # # NOTE(@duckinator): The implementation is a tad weird because we want to: # 1. Make builds reproducible by default, by having this function always # return the same result during a given run. # 2. Allow changing ENV['SOURCE_DATE_EPOCH'] at runtime, since multiple # tests that set this variable will be run in a single process. # # If you simplify this function and a lot of tests fail, that is likely due to # #2 above. # # Details on SOURCE_DATE_EPOCH: # https://reproducible-builds.org/specs/source-date-epoch/ # def self.source_date_epoch_string: () -> String # # Returns an Array of sources to fetch remote gems from. Uses default_sources if # the sources list is empty. # def self.sources: () -> SourceList # # Need to be able to set the sources without calling Gem.sources.replace since # that would cause an infinite loop. # # DOC: This comment is not documentation about the method itself, it's more of a # code comment about the implementation. # def self.sources=: (SourceList? new_sources) -> SourceList? # # def self.spec_cache_dir: () -> String # # Glob pattern for require-able path suffixes. # def self.suffix_pattern: () -> String # # Regexp for require-able path suffixes. # def self.suffix_regexp: () -> Regexp # # Suffixes for require-able paths. # def self.suffixes: () -> Array[String] # # Prints the amount of time the supplied block takes to run using the debug UI # output. # def self.time: [T] (String msg, ?Integer width, ?boolish display) { () -> T } -> T # # Try to activate a gem containing `path`. Returns true if activation succeeded # or wasn't needed because it was already activated. Returns false if it can't # find the path in a gem. # def self.try_activate: (String path) -> bool # # Lazily loads DefaultUserInteraction and returns the default UI. # def self.ui: () -> StreamUI # # Looks for a gem dependency file at `path` and activates the gems in the file # if found. If the file is not found an ArgumentError is raised. # # If `path` is not given the RUBYGEMS_GEMDEPS environment variable is used, but # if no file is found no exception is raised. # # If '-' is given for `path` RubyGems searches up from the current working # directory for gem dependency files (gem.deps.rb, Gemfile, Isolate) and # activates the gems in the first one found. # # You can run this automatically when rubygems starts. To enable, set the # `RUBYGEMS_GEMDEPS` environment variable to either the path of your gem # dependencies file or "-" to auto-discover in parent directories. # # NOTE: Enabling automatic discovery on multiuser systems can lead to execution # of arbitrary code when used from directories outside your control. # def self.use_gemdeps: (?String path) -> void # # Use the `home` and `paths` values for Gem.dir and Gem.path. Used mainly by # the unit tests to provide environment isolation. # def self.use_paths: (String home, *String paths) -> Hash[String, String] # # Path for gems in the user's home directory # def self.user_dir: () -> String # # The home directory for the user. # def self.user_home: () -> String # # Is this a windows platform? # def self.win_platform?: () -> bool # # Safely write a file in binary mode on all platforms. # def self.write_binary: (String path, String data) -> Integer end