{"id":22753186,"url":"https://github.com/nebulab/prependers","last_synced_at":"2025-04-14T15:14:29.957Z","repository":{"id":56888696,"uuid":"188730480","full_name":"nebulab/prependers","owner":"nebulab","description":"Easily and cleanly extend third-party code.","archived":false,"fork":false,"pushed_at":"2023-01-10T19:55:21.000Z","size":54,"stargazers_count":27,"open_issues_count":4,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-14T15:14:25.403Z","etag":null,"topics":["extension","overriding","prepend","rails","ruby","vendor"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nebulab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.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":"2019-05-26T20:52:03.000Z","updated_at":"2023-06-15T10:02:22.000Z","dependencies_parsed_at":"2023-02-08T19:55:11.586Z","dependency_job_id":null,"html_url":"https://github.com/nebulab/prependers","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fprependers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fprependers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fprependers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nebulab%2Fprependers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nebulab","download_url":"https://codeload.github.com/nebulab/prependers/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248904637,"owners_count":21180835,"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":["extension","overriding","prepend","rails","ruby","vendor"],"created_at":"2024-12-11T06:09:29.064Z","updated_at":"2025-04-14T15:14:29.924Z","avatar_url":"https://github.com/nebulab.png","language":"Ruby","readme":"# Prependers\n\n[![CircleCI](https://circleci.com/gh/nebulab/prependers.svg?style=svg)](https://circleci.com/gh/nebulab/prependers)\n\nPrependers are a way to easily and cleanly extend third-party code via `Module#prepend`.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'prependers'\n```\n\nAnd then execute:\n\n```console\n$ bundle\n```\n\nOr install it yourself as:\n\n```console\n$ gem install prependers\n```\n\n## Usage\n\nTo define a prepender manually, simply include the `Prependers::Prepender[]` module. For instance,\nif you have installed an `animals` gem and you want to extend the `Animals::Dog` class, you can\ndefine a module like the following:\n\n```ruby\nmodule Animals::Dog::AddBarking\n  include Prependers::Prepender[]\n\n  def bark\n    puts 'Woof!'\n  end\nend\n\nAnimals::Dog.new.bark # =\u003e 'Woof!'\n```\n\n### Extending class methods\n\nIf you want to extend a module's class methods, you can define a `ClassMethods` module in your\nprepender:\n\n```ruby\nmodule Animals::Dog::AddFamily\n  include Prependers::Prepender[]\n\n  module ClassMethods\n    def family\n      puts 'Canids'\n    end\n  end\nend\n\nAnimals::Dog.family # =\u003e 'Canids'\n```\n\nAs you can see, the `ClassMethods` module has automagically been `prepend`ed to `Animals::Dog`'s\nsingleton class.\n\n### Using a namespace\n\nIt can be useful to have a prefix namespace for your prependers. That way, you don't have to worry\nabout accidentally overriding any vendor modules. This is actually the recommended way to define\nyour prependers.\n\nYou can accomplish this by passing the `:namespace` option when including `Prependers::Prepender`:\n\n```ruby\nmodule MyApp\n  module Animals\n    module Dog\n      module AddBarking\n        include Prependers::Prepender[namespace: MyApp]\n\n        def bark\n          puts 'Woof!'\n        end\n      end\n    end\n  end\nend\n```\n\n### Verifying original sources\n\nOne issue you may run into when extending third-party code is that, when the original implementation\nis updated, it's not always obvious whether you have to update any of your extensions.\n\nPrependers make this a bit easier with the concept of original source verification: you can compute\na SHA1 hash of the original implementation, store it along with your prepender, and then verify it\nagainst the current hash when your application loads. If the original source changes, you get an\nerror asking you to ensure your prepender is still relevant.\n\nTo use original source verification in your prependers, pass the `:verify` option:\n\n```ruby\nmodule Animals::Dog::AddBarking\n  include Prependers::Prepender[verify: nil]\n\n  # ...\nend\n```\n\nWhen you load your application now, you will get an error with instructions on how to set the proper\nhash:\n\n```\nPrependers::OutdatedPrependerError:\n  You have not defined an original hash for Animals::Dog in Animals::Dog::AddBarking.\n\n  You can define the hash by updating your include statement as follows:\n\n      include Prependers::Prepender[verify: 'f7175533215c39f3f3328aa5829ac6b1bb168218']\n```\n\nAt this point, you should update your prepender with the correct hash:\n\n```ruby\nmodule Animals::Dog::AddBarking\n  include Prependers::Prepender[verify: 'f7175533215c39f3f3328aa5829ac6b1bb168218']\n\n  # ...\nend\n```\n\nNow, when the underlying implementation of `Animals::Dog` changes because of a dependency update or\nother reasons, Prependers will raise an error such as the following:\n\n```\nPrependers::OutdatedPrependerError:\n  The stored hash for Animals::Dog in Animals::Dog::AddBarking is\n  f7175533215c39f3f3328aa5829ac6b1bb168218, but the current hash is\n  2f05682e4f46b509c23a8418d9427a9eeaa8a79e instead.\n\n  This most likely means that the original source has changed.\n\n  Check that your prepender is still valid, then update the stored hash:\n\n      include Prependers::Prepender[verify: '2f05682e4f46b509c23a8418d9427a9eeaa8a79e']\n```\n\nOriginal source verification also works when a module is defined in multiple locations. \n\n*NOTE: Due to limitations in Ruby's API, it is not possible to use source verification with modules\nthat don't define any methods. Prependers will raise an error if you try to do this.*\n\n### Autoloading prependers\n\nIf you don't want to include `Prependers::Prepender[]`, you can also autoload prependers from a\npath, they will be loaded in alphabetical order.\n\nHere's the previous example, but with autoloading:\n\n```ruby\n# app/prependers/animals/dog/add_barking.rb\nmodule Animals::Dog::AddBarking\n  def bark\n    puts 'Woof!'\n  end\nend\n\n# somewhere in your initialization code\nPrependers.load_paths(File.expand_path('app/prependers'))\n```\n\nNote that, in order for autoprepending to work, the paths of your prependers must match the names\nof the prependers you defined.\n\nYou can pass multiple arguments to `#load_paths`, which is useful if you have subdirectories in\n`app/prependers`:\n\n```ruby\nPrependers.load_paths(\n  File.expand_path('app/prependers/controllers'),\n  File.expand_path('app/prependers/models'),\n  # ...\n)\n```\n\nYou can pass the `:namespace` option to `#load_paths` to have it forwarded to all prependers:\n\n```ruby\nPrependers.load_paths(\n  File.expand_path('app/prependers/controllers'),\n  File.expand_path('app/prependers/models'),\n  namespace: Acme,\n)\n```\n\n### Integrating with Rails\n\nTo use prependers in your Rails app, simply create them under `app/prependers/models`,\n`app/prependers/controllers` etc. and add the following to your `config/application.rb`:\n\n```ruby\nPrependers.setup_for_rails\n```\n\n`#setup_for_rails` accepts the same options as `#load_paths`.\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run\nthe tests. You can also run `bin/console` for an interactive prompt that will allow you to\nexperiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new\nversion, update the version number in `version.rb`, and then run `bundle exec rake release`, which\nwill create a git tag for the version, push git commits and tags, and push the `.gem` file to\n[rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/nebulab/prependers.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnebulab%2Fprependers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnebulab%2Fprependers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnebulab%2Fprependers/lists"}