README.md in gem_bench-2.0.3 vs README.md in gem_bench-2.0.4
- old
+ new
@@ -96,18 +96,17 @@
🕵️♀️ Static Gemfile and installed gem library source code analysis.
Regex search through all of a project's source code, including installed Bundler dependencies.
🛟 Trim down app load times, such as on Heroku, by finding and keeping your worst players on the bench.
-| Project | GemBench |
-|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| gem name | [gem_bench](https://rubygems.org/gems/gem_bench) |
-| code triage | [](https://www.codetriage.com/pboling/gem_bench) |
-| homepage | [on Github.com][homepage] |
-| documentation | [on Rdoc.info][documentation] |
-| expert support | [](https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github) |
-| `...` 💖 | [![Liberapay Patrons][⛳liberapay-img]][⛳liberapay] [![Sponsor Me][🖇sponsor-img]][🖇sponsor] [![Follow Me on LinkedIn][🖇linkedin-img]][🖇linkedin] [![Find Me on WellFound:][✌️wellfound-img]][✌️wellfound] [![Find Me on CrunchBase][💲crunchbase-img]][💲crunchbase] [![My LinkTree][🌳linktree-img]][🌳linktree] [![Follow Me on Ruby.Social][🐘ruby-mast-img]][🐘ruby-mast] [![Tweet @ Peter][🐦tweet-img]][🐦tweet] [💻][coderme] [🌏][aboutme] |
+| Primary Namespace | `GemBench` |
+|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| gem name | [gem_bench](https://rubygems.org/gems/gem_bench) |
+| code triage | [](https://www.codetriage.com/pboling/gem_bench) |
+| documentation | [on Github.com][homepage], [on Rdoc.info][documentation] |
+| expert support | [](https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github) |
+| `...` 💖 | [![Liberapay Patrons][⛳liberapay-img]][⛳liberapay] [![Sponsor Me][🖇sponsor-img]][🖇sponsor] [![Follow Me on LinkedIn][🖇linkedin-img]][🖇linkedin] [![Find Me on WellFound:][✌️wellfound-img]][✌️wellfound] [![Find Me on CrunchBase][💲crunchbase-img]][💲crunchbase] [![My LinkTree][🌳linktree-img]][🌳linktree] [![Follow Me on Ruby.Social][🐘ruby-mast-img]][🐘ruby-mast] [![Tweet @ Peter][🐦tweet-img]][🐦tweet] [💻][coderme] [🌏][aboutme] |
<!-- 7️⃣ spread 💖 -->
[🐦tweet-img]: https://img.shields.io/twitter/follow/galtzo.svg?style=social&label=Follow%20%40galtzo
[🐦tweet]: http://twitter.com/galtzo
[🚎blog]: http://www.railsbling.com/tags/gem_bench/
@@ -161,10 +160,45 @@
```ruby
require "gem_bench/jersey"
```
+#### Usage
+
+If the original gem defines multiple top-level namespaces,
+they can all be renamed by providing more key value pairs in `trades`.
+If the original gem monkey patches other libraries,
+that behavior can't be isolated, so YMMV.
+
+NOTE: Non-top-level namespaces do not need to be renamed,
+as they are isolated within their parent namespace.
+
+#### Example
+
For a real example, see: https://github.com/panorama-ed/memo_wise/pull/339
+
+#### Naming: Why `doff_and_don`?
+
+> Wouldn't "copy_gem" make sense?
+
+Actually copy is an overloaded term, which creates confusion in this use case.
+This method Generates a temp directory, and creates a copy of a gem within it.
+Re-namespaces the copy according to the `trades` configuration.
+Then requires each file of the "copied gem", resulting
+in a loaded gem that will not have namespace
+collisions when loaded alongside the original-namespaced gem.
+Note that "copied gem" in the previous sentence is ambiguous without the supporting context.
+The "copied gem" can mean either the original, or the "copy", which is why this gem refers to
+a "doffed gem" (the original) and a "donned gem" (the copy).
+
+Also because `Jersey`. Duh...
+
+#### Advanced Usage
+
+If a block is provided the contents of each file will be yielded to the block,
+after all namespace substitutions from `trades` are complete, but before the contents
+are written to the donned (re-namespaced) gem. The return value of the block will be
+written to the file in this scenario.
### New for 2.0.0 - Dropped Support for Ruby 2.0, 2.1, 2.2
- Required Ruby is now 2.3+
- `VERSION` is now namespaced at `GemBench::Version::VERSION` and is enhanced by `version_gem`.