README.md in pbbuilder-0.18.0 vs README.md in pbbuilder-0.19.0
- old
+ new
@@ -1,33 +1,30 @@
# Pbbuilder
-PBBuilder generates [Protobuf](https://developers.google.com/protocol-buffers) Messages with a simple DSL similar to [JBuilder](https://rubygems.org/gems/jbuilder) gem.
+PBBuilder generates [Protobuf](https://developers.google.com/protocol-buffers) Messages with a simple DSL similar to the [JBuilder](https://rubygems.org/gems/jbuilder) gem.
-At least Rails 6.1 is required.
+At least Rails 6.1 is required and rails 7.1 is currently not supported.
+There currently is a regression in ActionView (the part of Rails which renders) that forces rendered objects into strings, but for Pbbuilder we need the raw objects.
+This is only present in Rails 7.1, and a fix is released in Rails 7.2. https://github.com/rails/rails/pull/51023
-> [!WARNING]
-> There currently is a regression in ActionView (the part of Rails which renders) that forces rendered objects into strings. This is only present
-> in Rails 7.1, and is fixed in Rails. However, a 7.1 gem containing the fix hasn't been released yet. For the moment you should refrain
-> from using pbbuilder and rails-twirp with Rails 7.1 and wait for the next version to be released.
-
## Compatibility with jBuilder
We don't aim to have 100% compitability and coverage with jbuilder gem, but we closely follow jbuilder's API design to maintain familiarity.
| | Jbuilder | Pbbuilder |
|---|---|---|
-| set! | ✅ | ✅ |
-| cache! | ✅ | ✅ |
-| cache_if! | ✅ | ✅ |
+| set! | ✅ | ✅ |
+| cache! | ✅ | ✅ |
+| cache_if! | ✅ | ✅ |
| cache_root! | ✅| |
| fragment cache | ✅| ✅ |
| extract! | ✅ | ✅ |
| merge! | ✅ | ✅ |
| child! | ✅ | |
| array! | ✅ | |
| .call | ✅ | |
-Due to protobuf message implementation, there is absolutely no need to implement support for `deep_format_keys!`, `key_format!`, `key_format`, `deep_format_keys`, `ignore_nil!`, `ignore_nil!`, `nil`. So those would never be added.
+Due to the protobuf message implementation, there is absolutely no need to implement support for `deep_format_keys!`, `key_format!`, `key_format`, `deep_format_keys`, `ignore_nil!`, `ignore_nil!`, `nil`. So those would never be added.
## Usage
The main difference is that it can use introspection to figure out what kind of protobuf message it needs to create.
This is an example `.proto` message.
@@ -59,11 +56,11 @@
pb.id account.id
pb.phone_number account.phone_number
pb.tag account.tag
```
-could be rewritten to a shorter version with a use of `extract!`.
+can be rewritten to a shorter version with the use of `extract!`.
```
pb.extract! account, :id, :phone_number, :tag
```
### Partials
@@ -78,11 +75,11 @@
```
pb.account partial: "account", account: @account
```
-Here is way to use partials with collection while passing a variable to it
+Here is a way to use partials with a collection while passing a variable to it
```
pb.accounts @accounts, partial: "account", as: account
```
@@ -94,20 +91,20 @@
```ruby
pb.friends "racers/racer", as: :racer, collection: @racers
```
-And there are other ways, that don't use Collection Renderer (not very effective probably)
+And there are other ways, that don't use CollectionRenderer
```ruby
pb.partial! @racer, racer: Racer.new(123, "Chris Harris", friends)
```
```ruby
pb.friends @friends, partial: "racers/racer", as: :racer
```
### Caching
-it uses Rails.cache and works like caching in HTML templates:
+It uses Rails.cache and works like caching in HTML templates:
```
pb.cache! "cache-key", expires_in: 10.minutes do
pb.name @person.name
end
@@ -119,11 +116,11 @@
pb.cache_if! !admin?, "cache-key", expires_in: 10.minutes do
pb.name @person.name
end
```
-Fragment caching currently works through ActionView::CollectionRenderer and can be used only with the following syntax:
+Fragment caching currently works through ActionView::CollectionRenderer and can only be used with the following syntax:
```ruby
pb.friends partial: "racers/racer", as: :racer, collection: @racers, cached: true
```
@@ -149,13 +146,17 @@
```
## Development
When debugging, make sure to prepend `::Kernel` to any calls such as `puts` as otherwise the code will think you're trying to add another attribute into protobuf object.
-In case, you're looking to use breakpoints for debugging purposes - it's better to use `pry`. Just make sure to [change pbbuilder superclass from `ProxyObject/BasicObject` to `Object`](lib/pbbuilder/pbbuilder.rb).
+In case you're looking to use breakpoints (for debugging purposes via `binding.pry` for instance), let Pbbuilder inherit from `Object` instead of `BasicObject`]
+Seen in:
+[Pbbuilder](lib/pbbuilder/pbbuilder.rb)
+[Errors](lib/pbbuilder/errors.rb)
## Testing
-Running `bundle exec appraisal rake test` locally will run entire testsuit with all version of rails. To run tests only for certain rails version do the following `bundle exec appraisal rails-7-0 rake test`
+Running `bundle exec appraisal rake test` locally will run the entire testsuit with all versions of rails.
+To run tests only for a certain rails version do the following `bundle exec appraisal rails-7-0 rake test`
To run only one tests from file - use `m` utility. Like this:
`bundle exec appraisal rails-7-0 m test/pbbuilder_template_test.rb:182`
## Contributing