{"id":22980995,"url":"https://github.com/rubyworks/loadable","last_synced_at":"2025-08-13T17:33:37.417Z","repository":{"id":998298,"uuid":"809550","full_name":"rubyworks/loadable","owner":"rubyworks","description":"Customize Ruby's load system easily with load wedges.","archived":false,"fork":false,"pushed_at":"2012-12-21T17:59:26.000Z","size":986,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-01T00:08:53.613Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://rubyworks.github.com/loadable","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"zhangwei1234/go-timer-wheel","license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubyworks.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-07-31T18:08:42.000Z","updated_at":"2013-12-15T02:41:38.000Z","dependencies_parsed_at":"2022-07-06T01:00:32.237Z","dependency_job_id":null,"html_url":"https://github.com/rubyworks/loadable","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Floadable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Floadable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Floadable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Floadable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubyworks","download_url":"https://codeload.github.com/rubyworks/loadable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229773540,"owners_count":18122031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-15T01:46:33.016Z","updated_at":"2024-12-15T01:46:33.461Z","avatar_url":"https://github.com/rubyworks.png","language":"Ruby","readme":"[Website](http://github.com/rubyworks/loadable) /\n[Report Issue](http://github.com/rubyworks/loadable/issues) /\n[Source Code](http://github.com/rubyworks/loadable)\n( [![Build Status](https://secure.travis-ci.org/rubyworks/loadable.png)](http://travis-ci.org/rubyworks/loadable) )\n\n# Loadable\n\n*Safely Customize Ruby's Load System*\n\n\u003cbr/\u003e\n\n## 1 Description\n\nThe Loadable gem provides a robust and convenient means of augmenting\nRuby's load system, namely the `load` and `require` methods. Rather than\nalias and override these methods, Loadable keeps a list of load hooks\n(also called *load wedges*) that control the routing of require and load calls.\n\nIn addition, the Loadable gem includes two pre-made load hooks that can be\nused to prevent name clashes between Ruby's standard library and gem packages\n(see INFRACTIONS.md for more on this). There is also a load hook for\ndevelopers to make vendored sub-projects loadable.\n\n\n## 2 Features\n\n* Safely augment Ruby's load system.\n* Prevent library name clashes.\n* Search load locations.\n\n\n## 3 Usage\n\n### 3.1 Installation\n\nInstalling via RubyGems follows the usual pattern.\n\n    gem install loadable\n\nTo automatically load both the Gem and Ruby hooks, and the entire Loadable\nsystem, add `loadable` to your RUBYOPT environment variable.\n\n    export RUBYOPT=\"-rloadable\"\n\nPlace this in your shell's configuration file, such as `~/.bashrc`. For csh \nsyntax (e.g. in `~/.cshrc`) use:\n\n    setenv RUBYOPT \"-rloadable\"\n\nIf you do not want the default setup you can `require 'loadable/system'` instead.\nThis will load in Loadable system, but only add an `OriginalLoader` to the\n`$LOADERS` list, leaving off the Ruby and Gem loaders.\n\n### 3.2 Custom Loaders\n\nLoadable was written initially to provide the specific capability of loading\nRuby standard libraries without potential interference from libraries\ninstalled via RubyGems (see INFRACTIONS.md). The code ultimately evolved\ninto a more generic tool, useful for writing any kind of plug-in load\nrouter. \n\nThe code for the Ruby hook serves as a good example of writing a load hook.\n(Note this is leaves out a few details of the real class for simplicity's sake.)\n\n    require 'rbconfig'\n    require 'loadable/mixin'\n\n    class Loadable::RubyLoader\n      include Loadable\n\n      LOCATIONS = ::RbConfig::CONFIG.values_at(\n        'rubylibdir', 'archdir', 'sitelibdir', 'sitearchdir'\n      )\n\n      def call(fname, options={})\n        return unless options[:from].to_s == 'ruby'\n        LOCATIONS.each do |loadpath|\n          if path = lookup(loadpath, fname, options)\n            return super(path, options)\n          end\n        end\n        raise_load_error(fname)\n      end\n\n      def each(options={}, \u0026block)\n        LOCATIONS.each do |loadpath|\n          traverse(loadpath, \u0026block)\n        end\n      end\n    end\n\nTo put this loader into action we simply need to register it with the Loadable \ndomain.\n\n    Loadable.register(Loadable::RubyLoader.new)\n\nUnder the hood, this simply appends the instance to the `$LOADERS` global variable.\n\nLoaders, also called load hooks or wedges, are easy to write as their interface\nis very simple. Any object that responds to #call, taking parameters of \n\u003ccode\u003e(fname, options={})\u003c/code\u003e, can be used as a load hook. A load hook\nshould also support `#each(options={}, \u0026block)` which is used to iterate over\nall requirable files a loader supports.\n\nThe `Loadable` mixin is just a convenience module that makes writing loaders\na bit easier. Load hooks can be written without it, however the mixin\nprovides a few methods that are often useful to any load hook. An example is\nthe `lookup` method used in the above example, which will search a\nload path in accordance with the Ruby's built-in require and load lookup\nprocedures, i.e. automatically trying default extensions like `.rb`.\n\nYou might wonder how the single method, `#call`, handles both load and require\noperations. The secret is in the `options` hash. If \u003ccode\u003eoptions[:load]\u003c/code\u003e\nresolves to true, then it is a *load* operation, otherwise it is a *require*\noperation. The `$LOADERS` global variable is iterated over in order.\nWhen `#load` or `#require` is called each hook is tried in turn. The return\nvalue of `#call` controls how this loop proceeds. If the return value is `true`\nthen the load was successful, and the loop can break. If it is `false` it means\nthe loading has already been handled and the loop can also break. But if the\nreturn value is `nil`, it means the hook does not apply and the loop should\ncontinue. If all hooks have been tried and all have returned `nil` then it\nfalls back to the original `#load` and `#require` calls, via an instance of\n`OriginalLoader` which should always be the last loader in the `$LOADERS` list.\n\n\n## 4 Built-in Loaders\n\nThe Loadable gem provides three special loaders out-of-the-box: the `RubyLoader`,\nthe `GemLoader` and the `VendorLoader`. The first two are probably not exactly\nwhat you think they are, going just by their names, so keep reading...\n\n### 4.1 RubyLoader\n\nThe Ruby hook makes it possible to load a Ruby standard library without\ninterference from installed gems or other package systems. It does this by \nchecking for a `:from` option passed to the require or load methods.\n\n    require 'ostruct', :from=\u003e'ruby'\n\nThis will load the `ostruct.rb` script from the Ruby standard library regardless\nof whether someone else dropped an `ostruct.rb` file in their project's `lib/`\ndirectory without understanding the potential consequences.\n\n### 4.2 GemLoader\n\nThe Gem hook is similar to the Ruby hook, in that it isolates the loading\nof a gem's files from other gems.\n\n    gem 'facets', '~\u003e2.8'\n\n    require 'string/margin', :from=\u003e'facets'\n\nWith this we can be sure that 'facets/string/margin' was loaded from the Facets\nlibrary regardless of whether some other gem has a 'facets/string/margin' file\nin its `lib/` directory. If no gem has this file, it will fallback to the \nremaining loaders. However, if we use the `:gem` options instead, it will \nraise a load error.\n\n    require 'string/does_not_exit', :gem=\u003e'facets'\n\nThe Gem hook also supports version constraints, so you do not have to use \n`gem()` method for one-off requires from a given gem.\n\n    require 'string/margin', :from=\u003e'facets', :version=\u003e'~\u003e2.8'\n\n### 4.3 VendorLoader\n\nThe Vendor hook is used to add vendored projects to the load system.\nThis is especially useful for development. Vendored projects can be added\nin two ways, by registering an instance of VendorLoader, e.g.\n\n    Loadable.register Loadable::VendorLoader.new('vendor/*')\n\nOr using the dedicated `Loadable.vendor(*dir)` method that Loadable provides\nto make this more convenient.\n\n    Loadable.vendor('vendor/*')\n\n\n## 5 Development\n\nSource code for Loadable is hosted by [GitHub](http://github.com/rubyworks/loadable).\n\nIf you come across any issues, we encourage you to fork the repository and \nsubmit a pull request with the fix. When submitting a pull request, it is best\nif the changes are organized into a new topic branch.\n\nIf you don't have time to code up patches yourself, please do not hesitate to\nsimply report the issue on the [issue tracker](http://github.com/rubyworks/loadable/issues).\n\n\n## 6 Copyrights\n\nLoadable if copyrighted open source software.\n\n    Copyright (c) 2010 Rubyworks\n\nLoad is distributed under the terms of the **BSD-2-Clause** license.\n\nSee LICENSE.txt file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyworks%2Floadable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubyworks%2Floadable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyworks%2Floadable/lists"}