{"id":17228629,"url":"https://github.com/njonsson/autoloaded","last_synced_at":"2025-05-08T21:10:19.822Z","repository":{"id":22356777,"uuid":"25692807","full_name":"njonsson/autoloaded","owner":"njonsson","description":"Eliminates the drudgery of handcrafting an `autoload` statement for each Ruby source code file in your project","archived":false,"fork":false,"pushed_at":"2024-04-06T07:49:58.000Z","size":162,"stargazers_count":50,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-08T21:09:55.167Z","etag":null,"topics":["api","fluid","metaprogramming","ruby","rubygem"],"latest_commit_sha":null,"homepage":"https://njonsson.github.io/autoloaded","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/njonsson.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","contributing":null,"funding":null,"license":"License.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-10-24T14:40:31.000Z","updated_at":"2022-03-14T00:02:12.000Z","dependencies_parsed_at":"2024-06-20T00:16:18.484Z","dependency_job_id":"065a1f08-8525-4ad7-a563-f32b45932b66","html_url":"https://github.com/njonsson/autoloaded","commit_stats":{"total_commits":129,"total_committers":4,"mean_commits":32.25,"dds":0.03100775193798455,"last_synced_commit":"ab3484cb330882b197dbf32736146fb20d6ab916"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njonsson%2Fautoloaded","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njonsson%2Fautoloaded/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njonsson%2Fautoloaded/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/njonsson%2Fautoloaded/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/njonsson","download_url":"https://codeload.github.com/njonsson/autoloaded/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253149615,"owners_count":21861739,"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":["api","fluid","metaprogramming","ruby","rubygem"],"created_at":"2024-10-15T04:44:38.770Z","updated_at":"2025-05-08T21:10:19.767Z","avatar_url":"https://github.com/njonsson.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Autoloaded graphic]][spider-gear-image]\n\n# Autoloaded\n\n[![Travis CI build status]      ][Travis-CI-build-status]\n[![Code Climate quality report] ][Code-Climate-report]\n[![Code Climate coverage report]][Code-Climate-report]\n\n[![Inch CI build status]        ][Inch-CI-build-status]\n[![RubyGems release]            ][RubyGems-release]\n\nIf you like the [*Module#autoload*][Ruby-Core-Module-autoload] feature of the\nRuby Core library, you may have wished for *Autoloaded*. It eliminates the\ndrudgery of handcrafting an `autoload` statement for each Ruby source code file\nin your project. It also avoids the limitations of rigid convention-driven\nfacilities such as those provided by the [ActiveSupport][ActiveSupport-Autoload]\nRubyGem.\n\n*Autoloaded* assumes, but does not enforce, `CamelCase`-to-`snake_case`\ncorrespondence between the names of constants and source files. You can combine\nconventions, even putting multiple autoloaded constants in a single source file.\n\n## Installation\n\nInstall [the RubyGem][RubyGems-release].\n\n    $ gem install autoloaded\n\nUse *Autoloaded* in your RubyGem project by making it a runtime dependency.\n\n```ruby\n# my_awesome_gem.gemspec\n\nGem::Specification.new do |spec|\n  # ...\n  spec.add_dependency 'autoloaded', '~\u003e 2'\n  # ...\nend\n```\n\nOr you may want to make *Autoloaded* a dependency of your project by using\n[Bundler][Bundler].\n\n```ruby\n# Gemfile\n\nsource 'https://rubygems.org'\n\ngem 'autoloaded', '~\u003e 2'\n```\n\n## Usage\n\nSuppose you have the following source files.\n\n    lib/\n    ├─ my_awesome_gem/\n    │  ├─ db/\n    │  │  ├─ MicroSoft.rb\n    │  │  ├─ SELF-DESTRUCT!.rb\n    │  │  ├─ mysql.rb\n    │  │  ├─ oracle.rb\n    │  │  └─ postgre_sql.rb\n    │  ├─ db.rb\n    │  └─ version.rb\n    └─ my_awesome_gem.rb\n\n### The *Autoloaded.module* or *Autoloaded.class* method\n\nThe *Autoloaded.module* and *Autoloaded.class* method calls below invoke\n[*Module#autoload*][Ruby-Core-Module-autoload] for each source file in the\ncalling module’s corresponding directory. Note that these methods must receive a\nblock, even if it’s an empty block.\n\nThe file paths used are abbreviated, if possible, using a directory of the Ruby\nload path (`$:`). They are also rendered without their *.rb* extension.\n\n```ruby\n# lib/my_awesome_gem.rb\nmodule MyAwesomeGem\n\n  Autoloaded.module { }\n\n  # The above is the equivalent of:\n  #\n  # autoload :Db,      'my_awesome_gem/db'\n  # autoload :Version, 'my_awesome_gem/version'\n\nend\n\n# lib/my_awesome_gem/db.rb\nmodule MyAwesomeGem\n\n  class DB\n\n    # The 'class' and 'module' methods are aliases -- use either one.\n    Autoloaded.class { }\n\n    # The above is the equivalent of:\n    #\n    # autoload :MicroSoft,      'my_awesome_gem/db/MicroSoft'\n    # autoload :SELF_DESTRUCT_, 'my_awesome_gem/db/SELF-DESTRUCT!'\n    # autoload :Mysql,          'my_awesome_gem/db/mysql'\n    # autoload :Oracle,         'my_awesome_gem/db/oracle'\n    # autoload :PostgreSql,     'my_awesome_gem/db/postgre_sql'\n\n  end\n\nend\n```\n\nThe code above is succinct, but it’s not exactly correct. The constants\n`MyAwesomeGem::DB`, `MyAwesomeGem::DB::MySQL`, and others are not set up to\nautoload properly because they are misspelled (case-sensitively speaking).\n\n```ruby\nMyAwesomeGem.autoload?          :DB  # =\u003e nil\nMyAwesomeGem.const_defined?     :DB  # =\u003e false\nMyAwesomeGem.constants.include? :DB  # =\u003e false\n\nMyAwesomeGem::DB  # Raises NameError because lib/my_awesome_gem/db.rb does not\n                  # get autoloaded!\n\nMyAwesomeGem.autoload?          :Db  # =\u003e 'my_awesome_gem/db' (a lie!)\nMyAwesomeGem.const_defined?     :Db  # =\u003e true (a lie!)\nMyAwesomeGem.constants.include? :Db  # =\u003e true (a lie!)\n\nMyAwesomeGem::Db  # Raises NameError because lib/my_awesome_gem/db.rb defines\n                  # MyAwesomeGem::DB, not MyAwesomeGem::Db!\n\n#################################################################################\n\nrequire 'my_awesome_gem/db'\n\nMyAwesomeGem::DB.autoload?          :MySQL  # =\u003e nil\nMyAwesomeGem::DB.const_defined?     :MySQL  # =\u003e false\nMyAwesomeGem::DB.constants.include? :MySQL  # =\u003e false\n\nMyAwesomeGem::DB::MySQL  # Raises NameError because\n                         # lib/my_awesome_gem/db/mysql.rb does not get\n                         # autoloaded!\n\nMyAwesomeGem::DB.autoload?          :Mysql  # =\u003e 'my_awesome_gem/db/mysql' (a lie!)\nMyAwesomeGem::DB.const_defined?     :Mysql  # =\u003e true (a lie!)\nMyAwesomeGem::DB.constants.include? :Mysql  # =\u003e true (a lie!)\n\nMyAwesomeGem::DB::Mysql  # Raises NameError because\n                         # lib/my_awesome_gem/db/mysql.rb defines\n                         # MyAwesomeGem::DB::MySQL, not MyAwesomeGem::DB::Mysql!\n```\n\n### The `with` specification\n\n*Autoloaded* needs hints from you concerning unpredictable spellings,\nstylization, and organization of constant names and/or source file names. You can\nspecify `with` as:\n\n* A symbol or array of symbols representing constants to autoload\n* A hash of symbols and strings representing constants and the source filename(s)\n  from which to autoload them\n* A combination of the above\n\nA symbol provided to `with` signifies the name of a constant, and a string\nsignifies the name of a source file.\n\nSpecifying `with` does not filter the source files; it maps the source files to\ndifferent constants, or tweaks the names of constants.\n\nYou can specify `with` multiple times, and its effects are cumulative.\n\n```ruby\n# lib/my_awesome_gem.rb\nmodule MyAwesomeGem\n\n  Autoloaded.module do |autoloading|\n    autoloading.with :DB, :VERSION\n    # Or:\n    # autoloading.with :DB\n    # autoloading.with :VERSION\n    # Or:\n    # autoloading.with DB: 'db', VERSION: 'version'\n    # Or:\n    # autoloading.with DB:      'db'\n    # autoloading.with VERSION: 'version'\n    # Or:\n    # autoloading.with 'db' =\u003e :DB, 'version' =\u003e :VERSION\n    # Or:\n    # autoloading.with 'db'      =\u003e :DB\n    # autoloading.with 'version' =\u003e :VERSION\n  end\n\n  # The above is the equivalent of:\n  #\n  # autoload :DB,      'my_awesome_gem/db'\n  # autoload :VERSION, 'my_awesome_gem/version'\n\nend\n\n# lib/my_awesome_gem/db.rb\nmodule MyAwesomeGem\n\n  class DB\n\n    Autoloaded.class do |autoloading|\n      autoloading.with :MySQL, :PostgreSQL, [:Access, :SQLServer] =\u003e 'MicroSoft'\n      # Or:\n      # autoloading.with :MySQL,\n      #                  :PostgreSQL,\n      #                  Access:    'MicroSoft',\n      #                  SQLServer: 'MicroSoft'\n      # Or:\n      # autoloading.with :MySQL,\n      #                  :PostgreSQL,\n      #                  'MicroSoft' =\u003e [:Access, :SQLServer]\n      # Or:\n      # autoloading.with :MySQL,\n      #                  :PostgreSQL,\n      #                  'MicroSoft' =\u003e :Access,\n      #                  'MicroSoft' =\u003e :SQLServer\n      # Or ...\n    end\n\n    # The above is the equivalent of:\n    #\n    # autoload :Access,         'my_awesome_gem/db/MicroSoft'\n    # autoload :SQLServer,      'my_awesome_gem/db/MicroSoft'\n    # autoload :SELF_DESTRUCT_, 'my_awesome_gem/db/SELF-DESTRUCT!'\n    # autoload :MySQL,          'my_awesome_gem/db/mysql'\n    # autoload :Oracle,         'my_awesome_gem/db/oracle'\n    # autoload :PostgreSQL,     'my_awesome_gem/db/postgre_sql'\n\n  end\n\nend\n```\n\nNow you’re autoloading all the constants you want to be autoloading.\n\n```ruby\nMyAwesomeGem.autoload?          :DB  # =\u003e 'my_awesome_gem/db'\nMyAwesomeGem.const_defined?     :DB  # =\u003e true\nMyAwesomeGem.constants.include? :DB  # =\u003e true\n\nMyAwesomeGem::DB  # =\u003e MyAwesomeGem::DB\n\nMyAwesomeGem.autoload?          :Db  # =\u003e nil\nMyAwesomeGem.const_defined?     :Db  # =\u003e false\nMyAwesomeGem.constants.include? :Db  # =\u003e false\n\nMyAwesomeGem::Db  # Raises NameError as expected.\n\n#################################################################################\n\nMyAwesomeGem::DB.autoload?          :MySQL  # =\u003e 'my_awesome_gem/db/mysql'\nMyAwesomeGem::DB.const_defined?     :MySQL  # =\u003e true\nMyAwesomeGem::DB.constants.include? :MySQL  # =\u003e true\n\nMyAwesomeGem::DB::MySQL  # =\u003e MyAwesomeGem::DB::MySQL\n\nMyAwesomeGem::DB.autoload?          :Mysql  # =\u003e nil\nMyAwesomeGem::DB.const_defined?     :Mysql  # =\u003e false\nMyAwesomeGem::DB.constants.include? :Mysql  # =\u003e false\n\nMyAwesomeGem::DB::Mysql  # Raises NameError as expected.\n```\n\n### The `except` and `only` specifications\n\nWhat about source files you **don’t** want to be autoloaded?\n\n```ruby\nMyAwesomeGem::DB::SELF_DESTRUCT_  # Loading this file does something bad, so\n                                  # let's not.\n```\n\nIf you really want to avoid loading *lib/my_awesome_gem/db/SELF-DESTRUCT!.rb*, so\nmuch so that you don’t want an `autoload` statement made for it, specify\n`except`.\n\n```ruby\n# lib/my_awesome_gem/db.rb\n\nmodule MyAwesomeGem\n\n  class DB\n\n    Autoloaded.class do |autoloading|\n      autoloading.with :MySQL, :PostgreSQL, [:Access, :SQLServer] =\u003e 'MicroSoft'\n\n      autoloading.except 'SELF-DESTRUCT!'\n      # Or:\n      # autoloading.except :SELF_DESTRUCT_\n      # Or ...\n    end\n\n    # The above is the equivalent of:\n    #\n    # autoload :Access,     'my_awesome_gem/db/MicroSoft'\n    # autoload :SQLServer,  'my_awesome_gem/db/MicroSoft'\n    # autoload :MySQL,      'my_awesome_gem/db/mysql'\n    # autoload :Oracle,     'my_awesome_gem/db/oracle'\n    # autoload :PostgreSQL, 'my_awesome_gem/db/postgre_sql'\n\n  end\n\nend\n```\n\n```ruby\nMyAwesomeGem::DB.autoload?          :SELF_DESTRUCT_  # =\u003e nil\nMyAwesomeGem::DB.const_defined?     :SELF_DESTRUCT_  # =\u003e false\nMyAwesomeGem::DB.constants.include? :SELF_DESTRUCT_  # =\u003e false\n\nMyAwesomeGem::DB::SELF_DESTRUCT_  # Raises NameError as expected.\n```\n\nYou can specify `except` as:\n\n* A symbol or array of symbols representing constants to avoid autoloading\n* A string or array of strings representing source filenames to avoid autoloading\n* A hash of symbols and/or strings representing constants and/or source filenames\n  to avoid autoloading\n* A combination of the above\n\nThe `only` specification is like `except` but it has the opposite effect, namely,\nthat **only** specified constants and/or source files will be autoloaded.\n\nYou can specify `only` as:\n\n* A symbol or array of symbols representing constants to autoload\n* A string or array of strings representing source filenames to autoload\n* A hash of symbols and/or strings representing constants and the source\n  filename(s) from which to autoload them\n* A combination of the above\n\nA symbol provided to `except` or `only` signifies the name of a constant, and a\nstring signifies the name of a source file.\n\nYou can specify `except` and `only` multiple times, and their effects are\ncumulative.\n\n### The `from` specification\n\nIt’s recommended that you call *Autoloaded.module* or *Autoloaded.class* from\nwithin the source file where your module or class is defined. This practice\nallows *Autoloaded* to assume that the source files to be autoloaded are in a\ndirectory of the same name (and in the same location) as the module’s defining\nsource file.\n\nThere are circumstances, however, in which you cannot rely on the computed\ndirectory for autoloading. Perhaps the directory has a different name from the\nmodule’s defining source file. Or perhaps you are autoloading a library that you\ndidn’t author. In these situations you can specify `from` with the path from\nwhich source files should be autoloaded.\n\n```ruby\n# somewhere_else.rb\n\nmodule MyAwesomeGem\n\n  Autoloaded.module do |autoloading|\n    # The following code is not actually very useful since the installed location\n    # of a RubyGem varies with the operating system and user preferences. How to\n    # compute the path properly is outside the scope of this readme and is left\n    # as an exercise for the reader.\n    autoloading.from '/absolute/path/to/my_awesome_gem'\n  end\n\nend\n```\n\nA path provided to `from` cannot be relative; it must start with the filesystem\nroot.\n\nIf you specify `from` multiple times in an *Autoloaded* block, only the last one\ntakes effect.\n\n### The *Autoloaded.warn* method\n\nThere are two circumstances under which *Autoloaded* by default will write\nwarnings to stderr:\n\n* Overriding an established autoload\n* Establishing an autoload for a defined constant\n\nYou can silence these warnings by passing `false` to *Autoloaded.warn*.  (Passing\n`true` turns warnings on if they are off.)\n\n```ruby\n# lib/my_awesome_gem/db.rb\n\nmodule MyAwesomeGem\n\n  class DB\n\n    Autoloaded.warn false  # Turn off Autoloaded warnings.\n\n    autoload :SQLServer, 'my_awesome_gem/db/MicroSoft'\n\n    class Oracle; end\n\n    Autoloaded.class { }  # This duplicates the 'autoload' statement and class\n                          # definition above, but no Autoloaded warnings will be\n                          # displayed.\n\n    Autoloaded.warn true  # Turn on Autoloaded warnings again.\n\n  end\n\nend\n```\n\nUse the block form if you want to ensure warnings get toggled on or off for a\nseries of statements.\n\n```ruby\n# lib/my_awesome_gem/db.rb\n\nmodule MyAwesomeGem\n\n  class DB\n\n    autoload :SQLServer, 'my_awesome_gem/db/MicroSoft'\n\n    class Oracle; end\n\n    Autoloaded.warn false do\n      Autoloaded.class { }  # This duplicates the 'autoload' statement and class\n                            # definition above, but no Autoloaded warnings will\n                            # be displayed.\n    end\n\n    # Autoloaded warnings are turned on again automatically.\n\n  end\n\nend\n```\n\n### How to debug autoloading\n\nThe *Autoloaded.module* or *Autoloaded.class* method returns an ordered list of\narguments it has passed to `autoload`.\n\n```ruby\n# lib/my_awesome_gem/db.rb\n\nmodule MyAwesomeGem\n\n  class DB\n\n    results = Autoloaded.class do |autoloading|\n      autoloading.with   :MySQL,\n                         :PostgreSQL,\n                         [:Access, :SQLServer] =\u003e 'MicroSoft'\n      autoloading.except 'SELF-DESTRUCT!'\n    end\n    STDOUT.puts results.inspect  # See output below.\n\n  end\n\nend\n\n# [[:Access,     'my_awesome_gem/db/MicroSoft'  ],\n#  [:SQLServer,  'my_awesome_gem/db/MicroSoft'  ],\n#  [:MySQL,      'my_awesome_gem/db/mysql'      ],\n#  [:Oracle,     'my_awesome_gem/db/oracle'     ],\n#  [:PostgreSQL, 'my_awesome_gem/db/postgre_sql']]\n```\n\nYou can also hook [*Module#autoload*][Ruby-Core-Module-autoload] and\n[*Kernel#autoload*][Ruby-Core-Kernel-autoload] via monkeypatching or other means\nin order to see what’s happening.\n\n### Source filenames are relative to the `from` specification\n\nYou may have noticed that source filenames in the above examples are not\nabsolute. They are relative to the *Autoloaded* block’s `from` specification\n(which I recommend that you allow to be computed for you —\n[see above](#the-from-specification)).\n\n### Recursive autoloading not supported\n\n*Autoloaded* does not perform deep autoloading of nested namespaces and\ndirectories. This is by design.\n\n## Contributing\n\n1. [Fork][fork-Autoloaded] the official repository.\n2. Create your feature branch: `git checkout -b my-new-feature`.\n3. Commit your changes: `git commit -am 'Add some feature'`.\n4. Push to the branch: `git push origin my-new-feature`.\n5. [Create][compare-Autoloaded-branches] a new pull request.\n\nDevelopment\n-----------\n\nAfter cloning the repository, `bin/setup` to install dependencies. Then `rake` to\nrun the tests. You can also `bin/console` to get an interactive prompt that will\nallow you to experiment.\n\nTo install this gem onto your local machine, `bundle exec rake install`. To\nrelease a new version, update the version number in *lib/autoloaded/version.rb*,\nand then `bundle exec rake release`, which will create a Git tag for the version,\npush Git commits and tags, and push the *.gem* file to\n[RubyGems.org](RubyGems-release).\n\n## License\n\nReleased under the [MIT License][MIT-License].\n\n[Autoloaded graphic]:           https://farm5.staticflickr.com/4134/4941065976_54737fe145.jpg\n[Travis CI build status]:       https://app.travis-ci.com/njonsson/autoloaded.svg?branch=main\n[Code Climate quality report]:  https://codeclimate.com/github/njonsson/autoloaded/badges/gpa.svg\n[Code Climate coverage report]: https://codeclimate.com/github/njonsson/autoloaded/badges/coverage.svg\n[Inch CI build status]:         https://www.inch-ci.org/github/njonsson/autoloaded.svg?branch=master\n[RubyGems release]:             https://badge.fury.io/rb/autoloaded.svg\n\n[spider-gear-image]:           https://www.flickr.com/photos/dongkwan/4941065976               \"spider gear image by Ernesto Andrade\"\n[Travis-CI-build-status]:      https://app.travis-ci.com/github/njonsson/autoloaded            \"Travis CI build status for Autoloaded\"\n[Code-Climate-report]:         https://codeclimate.com/github/njonsson/autoloaded              \"Code Climate report for Autoloaded\"\n[Inch-CI-build-status]:        https://www.inch-ci.org/github/njonsson/autoloaded              \"Inch CI build status for Autoloaded\"\n[RubyGems-release]:            https://rubygems.org/gems/autoloaded                            \"RubyGems release of Autoloaded\"\n[Ruby-Core-Module-autoload]:   https://ruby-doc.org/core/Module.html#method-i-autoload         \"‘Module#autoload’ method in the Ruby Core Library\"\n[ActiveSupport-Autoload]:      https://api.rubyonrails.org/classes/ActiveSupport/Autoload.html \"‘ActiveSupport::Autoload’ module in the Rails API\"\n[Bundler]:                     https://bundler.io/\n[Ruby-Core-Kernel-autoload]:   https://ruby-doc.org/core/Kernel.html#method-i-autoload         \"‘Kernel#autoload’ method in the Ruby Core Library\"\n[fork-Autoloaded]:             https://github.com/njonsson/autoloaded/fork                     \"Fork the official repository of Autoloaded\"\n[compare-Autoloaded-branches]: https://github.com/njonsson/autoloaded/compare                  \"Compare branches of Autoloaded repositories\"\n[MIT-License]:                 https://github.com/njonsson/autoloaded/blob/master/License.md   \"MIT License claim for Autoloaded\"\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjonsson%2Fautoloaded","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnjonsson%2Fautoloaded","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnjonsson%2Fautoloaded/lists"}