presentability 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1802a45773fa3f0e4662926ae1067ae729e81b88201437f7e4bf9705ceac5ec
-  data.tar.gz: c0dedfb32ced019e2105b4434816610598f5f7b560ffab7353144955b9f4a9f3
+  metadata.gz: a47d99629c4294cef8b308ac17e98f5be3967d9c2663caab2ab633c81d512d2e
+  data.tar.gz: 0c325f17f38543a9a7420a9e1ecf727140ecfdc449853ea434f7643343b710e3
 SHA512:
-  metadata.gz: c3c3eb84c0c800517b515defb1b8717f1f940d4c582cb63baf5f7689df9aeb47d63a956f997ba64238301f1db88447cffff972a23faa3fad0026b37b3a0b872b
-  data.tar.gz: 9305b383f0f617186e27411fd153a0aa65b430ae96264c70bc3cc6b9ba99e4d9da77a4e817a9cb2e0870be2c057ed17249a6fad5c1fdd4985edb94b3b4232d3e
+  metadata.gz: e5a49d7d49f0b9f0bc780097620394ecd8d96d62722e746bd34bb9834ba080b767d01527f2417bfb8b8e85c8cda6522621c6b9e0184b0791361343c2fb7b6461
+  data.tar.gz: dbc38700dccecb3e48c18525a836a6b5f2115e6fae5c662e2df7f325e54cd68b82d1940178ab98be41a89fda98a97dc502a18c6038cbd39c2c2e86a5d45890d5

data/GettingStarted.md

@@ -0,0 +1,234 @@
+# Presentability - Getting Started
+
+To set up your own presentation layer, there are three steps:
+
+- Set up a Module as a presenter collection.
+- Declare one or more _presenters_ within the collection.
+- Use the collection to present entities from a service or other limited interface.
+
+For the purposes of this document, we'll pretend we're responsible for creating a JSON web service for Acme Widgets, Inc. We've declared all of our company's code inside the `Acme` namespace. We're using a generic Sinatra-like web framework that lets you declare endpoints like so:
+
+```ruby
+get '/status_check' do |parameters|
+    return { status: 'success' }.to_json
+end
+```
+
+
+## Create a Presenter Collection
+
+A _presenter collection_ is just a Module somewhere within your namespace that one can use to access the declared presenters. You designate it as a presenter collection simply by `extend`ing `Presentability`.
+
+We'll declare ours under `Acme` and call it `Presenters`:
+
+```ruby
+require 'presentability'
+
+require 'acme'
+
+module Acme::Presenters
+    extend Presentability
+
+    # Presenters will be declared here
+
+end # module Acme::Presenters
+```
+
+Since we haven't declared any presenters, the collection isn't really all that useful yet, so let's declare some.
+
+
+## Declare Presenters
+
+A _presenter_ is an object that is responsible for constructing a _representation_ of another object. There are a number of reasons to use a presenter:
+
+- Security: avoid exposing sensitive data from your domain objects to the public, e.g., passwords, internal prices, numeric IDs, etc.
+- Transform: normalize and flatten complex objects to some standard form, e.g., convert `Time` object timestamps to RFC 2822 form.
+- Consistency: change your model layer independently of your service's entities, e.g., adding a new column to a model doesn't automatically expose it in the service layer.
+
+The _representation_ is just a simple object that serves as an intermediate form for the transformed object until it is ultimately encoded. The default _representation_ is an empty `Hash`, but you can customize it to suit your needs.
+
+To declare a presenter, we'll call the `presenter_for` method on the presenter collection module, and then call `expose` or `expose_collection` for each attribute that should be exposed.
+
+The first argument to `presenter_for` is the type of object the presenter is for, which can be specified in a couple of different ways. The easiest is to just pass in the class itself. The domain class the Acme service is built around is the Widget, so let's declare a presenter for it:
+
+```ruby
+require 'acme/widget'
+
+module Acme::Presenters
+    extend Presentability
+
+    presenter_for Acme::Widget do
+        expose :name
+    end
+
+end # module Acme::Presenters
+```
+
+To present an object, call `.present` on the collection module with the object to be presented, and it will return a representation that is a `Hash` with a single `:name` key-value pair:
+
+```ruby
+widget = Acme::Widget.where( name: 'The Red One' )
+Acme::Presenters.present( widget )
+# => { name: "The Red One" }
+```
+
+If we want to add a `sku` field to all widgets served by our service, we just add another exposure:
+
+```ruby
+expose :sku
+```
+
+```ruby
+widget = Acme::Widget.where( name: 'The Red One' )
+Acme::Presenters.present( widget )
+# => { name: "The Red One", sku: 'DGG-17044-0822' }
+```
+
+### Overriding Exposures
+
+Sometime you want to alter the value that appears for a particular field. Say, for example, that the SKU that we exposed in our Widget presenter has an internal-only suffix in the form: `-xxxx` that we'd like to avoid exposing in a public-facing service. We can accomplish this by adding a block to it that alters the field from the model. Inside this block, the original object can be accessed via the `subject` method, so we can call the original `#sku` method and truncate it:
+
+```ruby
+expose :sku do
+    original = self.subject.sku
+    return original.sub(/-\d{4}/, '')
+end
+```
+
+Now the last part of the SKU will be removed in the representation:
+
+```ruby
+widget = Acme::Widget.where( name: 'The Red One' )
+Acme::Presenters.present( widget )
+# => { name: "The Red One", sku: 'DGG-17044' }
+```
+
+### Exposure Options
+
+You can also pass zero or more options as a keyword Hash when presenting:
+
+```ruby
+Acme::Presenters.present( widget, internal: true )
+```
+
+There are a few ways options can be used out of the box:
+
+#### Exposure Aliases
+
+Sometimes you want the field in the representation to have a different name than the method on the model object:
+
+```ruby
+presenter_for Acme::Company do
+    expose :id
+    expose :legal_entity, as: :name
+    expose :icon_url, as: :icon
+end
+```
+
+In the representation, the `#legal_entity` method will be called on the `Company` being presented and the return value associated with the `:name` key, and the same for `#icon_url` and `:icon`:
+
+```ruby
+{ id: 4, name: "John's Small Grapes", icon: "grapes-100.png" }
+```
+
+#### Conditional Exposure
+
+You can make an exposure conditional on an option being passed or not:
+
+```ruby
+# Don't include the price if presented with `public: true` option set
+expose :price, unless: :public
+
+# Only include the settings if presented with `detailed: true` option set
+expose :settings, if: :detailed
+```
+
+#### Collection Exposure
+
+A common use-case for conditional presentations is when you want an entity in a collection to be a less-detailed version. E.g.,
+
+```ruby
+presenter_for Acme::User do
+    expose :id
+    expose :username
+    expose :email
+
+    expose :settings, unless: :in_collection
+end
+```
+
+You can pass `in_collection: true` when you're presenting, but you can also use the `present_collection` convenience method which sets it for you:
+
+```ruby
+users = Acme::User.where( :activated ).limit( 20 )
+Acme::Presenters.present_collection( users )
+# => [{ id: 1, username: 'fran', email: 'fran@example.com'}, ...]
+```
+
+#### Custom Options
+
+You also have access to the presenter options (via the `#options` method) in a overridden exposure block. With this you can build your own presentation logic:
+
+```ruby
+presenter_for Acme::Widget do
+    expose :name
+    expose :sku
+
+    expose :scancode do
+        self.subject.make_scancode( self.options[:scantype] )
+    end
+end
+
+# In your service:
+widget = Acme::Widget[5]
+Acme::Presenters.present( widget, scantype: :qr )
+# { name: "Duck Quackers", sku: 'HBG-121-0424', scancode: '<qrcode data>'}
+```
+
+
+## Declare Serializers
+
+Oftentimes your model objects include values which are themselves not inherently serializable to your representation format. To help with this, you can also declare a "serializer" for one or more classes in your collection using the `.serializer_for` method:
+
+```ruby
+require 'time' # for Time#rfc2822
+
+module Acme::Presenters
+    extend Presentability
+
+    serializer_for :IPAddr, :to_s
+    serializer_for Time, :rfc2822
+    serializer_for Set, :to_a
+
+end # module Acme::Presenters
+```
+
+Now when one of your models includes any of the given types, the corresponding method will be called on it and the result used as the value instead.
+
+## Use the Roda Plugin
+
+If you're using the excellent [Roda](https://roda.jeremyevans.net/) web framework, `Presentability` includes a plugin for using it in your Roda application. To enable it, in your app just `require` your collection and enable the plugin. That will enable you to use `#present` and `#present_collection` in your routes:
+
+```ruby
+require 'roda'
+require 'acme/presenters'
+
+class Acme::WebService < Roda
+
+    plugin :presenters, collection: Acme::Presenters
+    plugin :json
+
+    route do |r|
+        r.on "users" do
+            r.is do
+                # GET /users
+                r.get do
+                    users = Acme::User.where( :activated )
+                    present_collection( users.all )
+                end
+            end
+        end
+    end
+end # class Acme::WebService
+```
+

data/History.md

@@ -1,6 +1,16 @@
 # Release History for presentability
 
 ---
+
+## v0.6.0 [2024-04-29] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Added custom serialization, and better collection handling
+- Added a Roda plugin
+- Improved documentation
+
+
 ## v0.5.0 [2023-11-06] Michael Granger <ged@faeriemud.org>
 
 Improvements:

data/README.md

@@ -56,6 +56,8 @@ your data objects that return a limited representation of their subjects.
 More details can be found in the docs for the Presentability module, and in
 Presentability::Presenter.
 
+See GettingStarted to get started with your own presenters.
+
 
 ## Prerequisites
 
@@ -88,7 +90,7 @@ This will install dependencies, and do any other necessary setup for development
 
 ## License
 
-Copyright (c) 2022, Michael Granger
+Copyright (c) 2022-2024, Michael Granger
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

data/lib/presentability/presenter.rb

@@ -4,7 +4,119 @@ require 'loggability'
 
 require 'presentability' unless defined?( Presentability )
 
-# :include: Presenter.md
+#
+# A presenter (facade) base class.
+#
+#
+# ### Declaring Presenters
+#
+# When you declare a presenter in a Presentability collection, the result is a
+# subclass of Presentability::Presenter. The main way of defining a Presenter's
+# functionality is via the ::expose method, which marks an attribute of the underlying
+# entity object (the "subject") for exposure.
+#
+#     class MyPresenter < Presentability::Presenter
+#       expose :name
+#     end
+#
+#     # Assuming `entity_object' has a "name" attribute...
+#     presenter = MyPresenter.new( entity_object )
+#     presenter.apply
+#     # => { :name => "entity name" }
+#
+#
+# ### Presenter Collections
+#
+# Setting up classes manually like this is one option, but Presentability also lets you
+# set them up as a collection, which is what further examples will assume for brevity:
+#
+#     module MyPresenters
+#       extend Presentability
+#
+#       presenter_for( EntityObject ) do
+#         expose :name
+#       end
+#
+#     end
+#
+#
+# ### Complex Exposures
+#
+# Sometimes you want to do more than just use the presented entity's values as-is.
+# There are a number of ways to do this.
+#
+# The first of these is to provide a block when exposing an attribute. The subject
+# of the presenter is available to the block via the `subject` method:
+#
+#     require 'time'
+#
+#     presenter_for( LogEvent ) do
+#       # Turn Time objects into RFC2822-formatted time strings
+#       expose :timestamp do
+#         self.subject.timestamp.rfc2822
+#       end
+#
+#     end
+#
+# You can also declare the exposure using a regular method with the same name:
+#
+#     require 'time'
+#
+#     presenter_for( LogEvent ) do
+#       # Turn Time objects into RFC2822-formatted time strings
+#       expose :timestamp
+#
+#       def timestamp
+#         return self.subject.timestamp.rfc2822
+#       end
+#
+#     end
+#
+# This can be used to add presence checks:
+#
+#     require 'time'
+#
+#     presenter_for( LogEvent ) do
+#       # Require that presented entities have an `id` attribute
+#       expose :id do
+#         id = self.subject.id or raise "no `id' for %p" % [ self.subject ]
+#         raise "`id' for %p is blank!" % [ self.subject ] if id.blank?
+#
+#         return id
+#       end
+#     end
+#
+# or conditional exposures:
+#
+#     presenter_for( Acme::Product ) do
+#
+#       # Truncate the long description if presented as part of a collection
+#       expose :detailed_description do
+#         desc = self.subject.detailed_description
+#         if self.options[:in_collection]
+#           return desc[0..15] + '...'
+#         else
+#           return desc
+#         end
+#       end
+#
+#     end
+#
+#
+# ### Exposure Aliases
+#
+# If you want to expose a field but use a different name in the resulting data
+# structure, you can use the `:as` option in the exposure declaration:
+#
+#     presenter_for( LogEvent ) do
+#       expose :timestamp, as: :created_at
+#     end
+#
+#     presenter = MyPresenter.new( log_event )
+#     presenter.apply
+#     # => { :created_at => '2023-02-01 12:34:02.155365 -0800' }
+#
+#
 class Presentability::Presenter
 	extend Loggability
 
@@ -120,9 +232,9 @@ class Presentability::Presenter
 
 		self.class.exposures.each do |name, exposure_options|
 			next if self.skip_exposure?( name )
+			self.log.debug "Presenting %p" % [ name ]
 			value = self.method( name ).call
-			value = presenters.present( value, **exposure_options ) unless
-				value.is_a?( result.class )
+			value = presenters.present( value, **exposure_options )
 			key = exposure_options.key?( :as ) ? exposure_options[:as] : name
 			result[ key.to_sym ] = value
 		end

data/lib/presentability.rb

@@ -3,14 +3,118 @@
 require 'loggability'
 
 
-# :include: Presentability.md
+#
+# Facade-based presenter toolkit with minimal assumptions.
+#
+# ## Basic Usage
+#
+# Basic usage of Presentability requires two steps: declaring presenters and
+# then using them.
+#
+# ### Declaring Presenters
+#
+# Presenters are just regular Ruby classes with some convenience methods for
+# declaring exposures, but in a lot of cases you'll want to declare them all in
+# one place. Presentability offers a mixin that implements a simple DSL for
+# declaring presenters and their associations to entity classes, intended to be
+# used in a container module:
+#
+#     require 'presentability'
+#
+#     module Acme::Presenters
+#       extend Presentability
+#
+#       presenter_for( Acme::Widget ) do
+#           expose :sku
+#           expose :name
+#           expose :unit_price
+#       end
+#
+#     end
+#
+# The block of `presenter_for` is evaluated in the context of a new Presenter
+# class, so refer to that documentation for what's possible there.
+#
+# Sometimes you can't (or don't want to) have to load the entity class to
+# declare a presenter for it, so you can also declare it using the class's name:
+#
+#     presenter_for( 'Acme::Widget' ) do
+#         expose :sku
+#         expose :name
+#         expose :unit_price
+#     end
+#
+#
+# ### Using Presenters
+#
+# You use presenters by instantiating them with the object they are a facade for
+# (the "subject"), and then applying it:
+#
+#     acme_widget = Acme::Widget.new(
+#         sku: "FF-2237H455",
+#         name: "Throbbing Frobnulator",
+#         unit_price: 299,
+#         inventory_count: 301,
+#         wholesale_cost: 39
+#     )
+#     presentation = Acme::Presenters.present( acme_widget )
+#     # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299 }
+#
+# If you want to present a collection of objects as a collection, you can apply
+# presenters to the collection instead:
+#
+#     widgets_in_stock = Acme::Widget.where { inventory_count > 0 }
+#     collection_presentation = Acme::Presenters.present_collection( widgets_in_stock )
+#     # => [ {:sku => "FF-2237H455", [...]}, {:sku => "FF-2237H460", [...]}, [...] ]
+#
+# The collection can be anything that is `Enumerable`.
+#
+#
+# ### Presentation Options
+#
+# Sometimes you want a bit more flexibility in what you present, allowing a single
+# uniform presenter to be used in multiple use cases. To facilitate this, you can pass
+# an options keyword hash to `#present`:
+#
+#     presenter_for( 'Acme::Widget' ) do
+#         expose :sku
+#         expose :name
+#         expose :unit_price
+#
+#         # Only expose the wholesale cost if presented via an internal API
+#         expose :wholesale_cost, if: :internal_api
+#     end
+#
+#     acme_widget = Acme::Widget.new(
+#         sku: "FF-2237H455",
+#         name: "Throbbing Frobnulator",
+#         unit_price: 299,
+#         inventory_count: 301,
+#         wholesale_cost: 39
+#     )
+#
+#     # External API remains unchanged:
+#     presentation = Acme::Presenters.present( acme_widget )
+#     # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299 }
+#
+#     # But when run from an internal service:
+#     internal_presentation = Acme::Presenters.present( acme_widget, internal_api: true )
+#     # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299,
+#     #      :wholesale_cost => 39 }
+#
+# There are some options that are set for you:
+#
+# <dl>
+# <td><code>:in_collection</code></td>
+# <dd>Set if the current object is being presented as part of a collection.</dd>
+# </dl>
+#
 module Presentability
 	extend Loggability
 
 
 	# Package version
-	VERSION = '0.5.0'
-
+	VERSION = '0.6.0'
 
 	# Automatically load subordinate components
 	autoload :Presenter, 'presentability/presenter'
@@ -20,15 +124,29 @@ module Presentability
 	log_as :presentability
 
 
+	#
+	# Hooks
+	#
+
 	### Extension hook -- decorate the including +mod+.
 	def self::extended( mod )
 		super
 		mod.singleton_class.attr_accessor :presenters
+		mod.singleton_class.attr_accessor :serializers
+
 		mod.presenters = {}
+		mod.serializers = {
+			Array => mod.method( :serialize_array ),
+			Hash => mod.method( :serialize_hash ),
+		}
 	end
 
 
 
+	#
+	# DSL Methods
+	#
+
 	### Set up a presentation for the given +entity_class+.
 	def presenter_for( entity_class, &block )
 		presenter_class = Class.new( Presentability::Presenter )
@@ -38,16 +156,28 @@ module Presentability
 	end
 
 
+	### Set up a rule for how to serialize objects of the given +type+ if there is
+	### no presenter declared for it.
+	def serializer_for( type, method )
+		self.serializers[ type ] = method
+	end
+
+
+	#
+	# Presentation Methods
+	#
+
 	### Return a representation of the +object+ by applying a declared presentation.
 	def present( object, **options )
 		representation = self.present_by_class( object, **options ) ||
-			self.present_by_classname( object, **options )
+			self.present_by_classname( object, **options ) ||
+			self.serialize( object, **options )
 
 		unless representation
 			if object.instance_variables.empty?
 				return object
 			else
-				raise NoMethodError, "no presenter found for %p" % [ object ]
+				raise NoMethodError, "no presenter found for %p" % [ object ], caller( 1 )
 			end
 		end
 
@@ -63,6 +193,37 @@ module Presentability
 	end
 
 
+	### Serialize the specified +object+ if a serializer has been declared for it
+	### and return the scalar result.
+	def serialize( object, ** )
+		serializer = self.serializers[ object.class ] ||
+			self.serializers[ object.class.name ] or
+			return nil
+		serializer_proc = serializer.to_proc
+
+		return serializer_proc.call( object )
+	end
+
+
+	### Default serializer for an Array; returns a new array of presented objects.
+	def serialize_array( object )
+		return object.map do |member|
+			self.present( member, in_collection: true )
+		end
+	end
+
+
+	### Default serializer for a Hash; returns a new Hash of presented keys and values.
+	def serialize_hash( object )
+		return object.each_with_object( {} ) do |(key, val), newhash|
+			p_key = self.present( key, in_collection: true )
+			p_val = self.present( val, in_collection: true )
+
+			newhash[ p_key ] = p_val
+		end
+	end
+
+
 	#########
 	protected
 	#########

data/lib/roda/plugins/presenters.rb

@@ -0,0 +1,57 @@
+# -*- ruby -*-
+
+require 'presentability'
+
+require 'roda/roda_plugins' unless defined?( Roda::RodaPlugins )
+
+
+module Roda::RodaPlugins::Presenters
+
+	# Default options
+	OPTS = {}.freeze
+
+
+	### Add presenter variables to the given +app+.
+	def self::configure( app, opts=OPTS, &block )
+		collection = opts[:collection] || Module.new
+		app.singleton_class.attr_accessor :presenter_collection
+		app.presenter_collection = collection
+	end
+
+
+	module ClassMethods
+
+		### Inheritance hook -- give +subclass+es their own presenters ivar.
+		def inherited( subclass )
+			super
+			subclass.presenter_collection = self.presenter_collection.clone
+		end
+
+
+	end # module ClassMethods
+
+
+	module InstanceMethods
+
+		### Find the presenter for the given +object+ and apply it with the given
+		### +options+. Raises an exception if no presenter can be found.
+		def present( object, **options )
+			mod = self.class.presenter_collection
+			return mod.present( object, **options )
+		end
+
+
+		### Find the presenter for the given +object+ and apply it with the given
+		### +options+. Raises an exception if no presenter can be found.
+		def present_collection( object, **options )
+			mod = self.class.presenter_collection
+			return mod.present_collection( object, **options )
+		end
+
+	end
+
+
+	Roda::RodaPlugins.register_plugin( :presenters, self )
+
+end # module Roda::RodaPlugins::Presenters
+

data/spec/presentability_spec.rb

@@ -11,9 +11,7 @@ RSpec.describe Presentability do
 
 	let( :entity_class ) do
 		Class.new do
-			def self::name
-				return 'Acme::Entity'
-			end
+			set_temporary_name 'Acme::Entity (Testing Class)'
 
 			def initialize( foo: 1, bar: 'two', baz: :three )
 				@foo = foo
@@ -27,9 +25,7 @@ RSpec.describe Presentability do
 
 	let( :other_entity_class ) do
 		Class.new do
-			def self::name
-				return 'Acme::User'
-			end
+			set_temporary_name 'Acme::User (Testing Class)'
 
 			def initialize( firstname, lastname, email, password )
 				@firstname = firstname
@@ -45,9 +41,7 @@ RSpec.describe Presentability do
 
 	let( :complex_entity_class ) do
 		Class.new do
-			def self::name
-				return 'Acme::Pair'
-			end
+			set_temporary_name 'Acme::Pair (Testing Class)'
 
 			def initialize( user:, entity:, overridden: false, locked: true )
 				@user = user
@@ -93,7 +87,7 @@ RSpec.describe Presentability do
 
 
 		it "can define a presenter for a class name" do
-			extended_module.presenter_for( 'Acme::Entity' ) do
+			extended_module.presenter_for( entity_class.name ) do
 				expose :foo
 				expose :bar
 			end
@@ -218,10 +212,110 @@ RSpec.describe Presentability do
 		end
 
 
+		describe 'serialization' do
+
+			it "presents each element for Arrays by default" do
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+				end
+
+				array = 5.times.map { entity_class.new }
+
+				result = extended_module.present( array )
+
+				expect( result ).to eq( [{foo: 1}] * 5 )
+			end
+
+
+			it "presents each value for Hashes by default" do
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+				end
+
+				hash = { user1: entity_instance(), user2: entity_instance() }
+
+				result = extended_module.present( hash )
+
+				expect( result ).to eq({
+					user1: {foo: 1}, user2: {foo: 1}
+				})
+			end
+
+
+			it "presents each key for Hashes by default too" do
+				extended_module.presenter_for( entity_class ) do
+					expose :id do
+						self.subject.object_id
+					end
+				end
+
+				key1 = entity_instance()
+				key2 = entity_instance()
+				hash = { key1 => 'user1', key2 => 'user2' }
+
+				result = extended_module.present( hash )
+
+				expect( result ).to eq({
+					{id: key1.object_id} => 'user1',
+					{id: key2.object_id} => 'user2'
+				})
+			end
+
+
+			it "automatically sets :in_collection for sub-Arrays" do
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+					expose :bar, unless: :in_collection
+					expose :baz
+				end
+
+				results = extended_module.present( [entity_instance] )
+
+				expect( results.first ).to include( :foo, :baz )
+				expect( results.first ).not_to include( :bar )
+			end
+
+
+			it "automatically sets :in_collection for sub-Hashes" do
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+					expose :bar, unless: :in_collection
+					expose :baz
+				end
+
+				results = extended_module.present( {result: entity_instance} )
+
+				expect( results[:result] ).to include( :foo, :baz )
+				expect( results[:result] ).not_to include( :bar )
+			end
+
+
+			it "can be defined by class for objects that have a simple presentation" do
+				extended_module.serializer_for( IPAddr, :to_s )
+
+				object = IPAddr.new( '127.0.0.1/24' )
+
+				expect( extended_module.present(object) ).to eq( '127.0.0.0' )
+			end
+
+
+			it "can be defined by class name for objects that have a simple presentation" do
+				extended_module.serializer_for( 'IPAddr', :to_s )
+
+				object = IPAddr.new( '127.0.0.1/24' )
+
+				expect( extended_module.present(object) ).to eq( '127.0.0.0' )
+			end
+
+		end
+
+
 		it "errors usefully if asked to present an object it knows nothing about" do
 			expect {
 				extended_module.present( entity_instance )
-			}.to raise_error( NoMethodError, /no presenter found/i )
+			}.to raise_error( NoMethodError, /no presenter found/i ) do |err|
+				expect( err.backtrace.first ).to match( /#{Regexp.escape(__FILE__)}/ )
+			end
 		end
 
 

data/spec/roda/plugins/presenters_spec.rb

@@ -0,0 +1,71 @@
+# -*- ruby -*-
+
+require_relative '../../spec_helper'
+
+require 'roda'
+require 'roda/plugins/presenters'
+
+
+RSpec.describe( Roda::RodaPlugins::Presenters ) do
+
+	let( :app ) { Class.new(Roda) }
+
+	let( :entity_class ) do
+		Class.new do
+			def self::name
+				return 'Acme::Entity'
+			end
+
+			def initialize( foo: 1, bar: 'two', baz: :three )
+				@foo = foo
+				@bar = bar
+				@baz = baz
+			end
+
+			attr_accessor :foo, :bar, :baz
+		end
+	end
+
+
+	it "adds an anonymous presenter collection to including apps" do
+		app.plugin( described_class )
+
+		expect( app.presenter_collection ).to be_a( Module )
+	end
+
+
+	it "clones the presenter collection for subclasses" do
+		app.plugin( described_class )
+		subapp = Class.new( app )
+
+		expect( subapp.presenter_collection ).to be_a( Module )
+		expect( app.presenter_collection ).to_not be( subapp.presenter_collection )
+	end
+
+
+	it "allows an existing presenter collection module to be added to including apps" do
+		collection = Module.new
+		app.plugin( described_class, collection: collection )
+
+		expect( app.presenter_collection ).to be( collection )
+	end
+
+
+	it "allows the use of presenters in application routes" do
+		collection = Module.new
+		collection.extend( Presentability )
+		collection.presenter_for( entity_class ) do
+			expose :foo
+			expose :bar
+		end
+		app.plugin( described_class, collection: collection )
+
+		app_instance = app.new( {} )
+
+		result = app_instance.present( entity_class.new )
+		expect( result ).to be_a( Hash ).and( include(:foo, :bar) )
+		expect( result ).to_not include( :baz )
+	end
+
+end
+

data/spec/spec_helper.rb

@@ -18,6 +18,15 @@ I18n.reload!
 
 require 'loggability/spechelpers'
 
+if !Module.respond_to?( :set_temporary_name )
+
+	Module.class_eval {
+		def set_temporary_name( tempname )
+			define_singleton_method( :name ) { tempname }
+		end
+	}
+
+end
 
 ### Mock with RSpec
 RSpec.configure do |config|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presentability
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Michael Granger
@@ -10,9 +10,9 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIID+DCCAmCgAwIBAgIBBTANBgkqhkiG9w0BAQsFADAiMSAwHgYDVQQDDBdnZWQv
-  REM9RmFlcmllTVVEL0RDPW9yZzAeFw0yMzAxMTYxNzE2MDlaFw0yNDAxMTYxNzE2
-  MDlaMCIxIDAeBgNVBAMMF2dlZC9EQz1GYWVyaWVNVUQvREM9b3JnMIIBojANBgkq
+  MIID+DCCAmCgAwIBAgIBBjANBgkqhkiG9w0BAQsFADAiMSAwHgYDVQQDDBdnZWQv
+  REM9RmFlcmllTVVEL0RDPW9yZzAeFw0yNDAxMjkyMzI5MjJaFw0yNTAxMjgyMzI5
+  MjJaMCIxIDAeBgNVBAMMF2dlZC9EQz1GYWVyaWVNVUQvREM9b3JnMIIBojANBgkq
   hkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAvyVhkRzvlEs0fe7145BYLfN6njX9ih5H
   L60U0p0euIurpv84op9CNKF9tx+1WKwyQvQP7qFGuZxkSUuWcP/sFhDXL1lWUuIl
   M4uHbGCRmOshDrF4dgnBeOvkHr1fIhPlJm5FO+Vew8tSQmlDsosxLUx+VB7DrVFO
@@ -23,17 +23,17 @@ cert_chain:
   ozilJg4aar2okb/RA6VS87o+d7g6LpDDMMQjH4G9OPnJENLdhu8KnPw/ivSVvQw7
   N2I4L/ZOIe2DIVuYH7aLHfjZDQv/mNgpAgMBAAGjOTA3MAkGA1UdEwQCMAAwCwYD
   VR0PBAQDAgSwMB0GA1UdDgQWBBRyjf55EbrHagiRLqt5YAd3yb8k4DANBgkqhkiG
-  9w0BAQsFAAOCAYEARYCeUVBWARNKqF0cvNnLJvFf4hdW2+Rtc7NfC5jQvX9a1oom
-  sfVvS96eER/9cbrphu+vc59EELw4zT+RY3/IesnoE7CaX6zIOFmSmG7K61OHsSLR
-  KqMygcWwyuPXT2JG7JsGHuxbzgaRWe29HbSjBbLYxiMH8Zxh4tKutxzKF7jb0Ggq
-  KAf9MH5LwG8IHVIfV5drT14PvgR3tcvmrn1timPyJl+eZ3LNnm9ofOCweuZCq1cy
-  4Q8LV3vP2Cofy9q+az3DHdaUGlmMiZZZqKixDr1KSS9nvh0ZrKMOUL1sWj/IaxrQ
-  RV3y6td14q49t+xnbj00hPlbW7uE2nLJLt2NAoXiE1Nonndz1seB2c6HL79W9fps
-  E/O12pQjCp/aPUZMt8/8tKW31RIy/KP8XO6OTJNWA8A/oNEI0g5p/LmmEtJKWYr1
-  WmEdESlpWhzFECctefIF2lsN9vaOuof57RM77t2otrtcscDtNarIqjZsIyqtDvtL
-  DttITiit0Vwz7bY0
+  9w0BAQsFAAOCAYEATLX50LXGjumlF+AtWyDLRS5kKavyMRiyx2LbLBUYgJFBka2u
+  mQYapo5k4+oFgsChEGvAdukTjYJSj9GxLvgDT9mZTTtudOg1WSyUTuIuzlVVgps5
+  4XJ6WBo8IuEn4IBJ2s5FTkvEx8GKpOIa6nwEOrk2Qujx1Tk/ChQxR0sMwCbur/c1
+  y6rI18potiGD3ZNf1tFTeyQ9q1wQWn9sn2It047X5jypuJcYrQ95W8Tq6eI4W5CG
+  NkW6ib/vmrgzNmNsZ0IALjOoeQK9lxQ/a9WpNokaZinmtvysGCVonH67BUJI7Udt
+  usImdLjDpkOVaJSrUsHgnI8iq2F5qYKj2K3No+fTHTPNF4c9KtmvBb0uFxI4JSoY
+  F/9VtnYr7sx/akZGuCfcG7WwTnx1iasrQIwjwDG9YRbPDNnffTN50agKxgxmP6JB
+  gHMt4zxJlML5nLwM/RX6nhR8LXJrm5eTdXMw9JG8ZbBnTHdipBOnYvUXMgAA904m
+  nO/om6m3bLHIgJaE
   -----END CERTIFICATE-----
-date: 2023-11-06 00:00:00.000000000 Z
+date: 2024-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -63,6 +63,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: roda
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.79'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.79'
 - !ruby/object:Gem::Dependency
   name: rake-deveiate
   requirement: !ruby/object:Gem::Requirement
@@ -100,15 +114,16 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- GettingStarted.md
 - History.md
 - LICENSE.txt
-- Presentability.md
-- Presenter.md
 - README.md
 - lib/presentability.rb
 - lib/presentability/presenter.rb
+- lib/roda/plugins/presenters.rb
 - spec/presentability/presenter_spec.rb
 - spec/presentability_spec.rb
+- spec/roda/plugins/presenters_spec.rb
 - spec/spec_helper.rb
 homepage: https://hg.sr.ht/~ged/Presentability
 licenses:
@@ -134,7 +149,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.21
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Facade-based presenters with minimal assumptions.

data/Presentability.md

@@ -1,105 +0,0 @@
-
-Facade-based presenter toolkit with minimal assumptions.
-
-## Basic Usage
-
-Basic usage of Presentability requires two steps: declaring presenters and
-then using them.
-
-### Declaring Presenters
-
-Presenters are just regular Ruby classes with some convenience methods for
-declaring exposures, but in a lot of cases you'll want to declare them all in
-one place. Presentability offers a mixin that implements a simple DSL for
-declaring presenters and their associations to entity classes, intended to be
-used in a container module:
-
-    require 'presentability'
-
-    module Acme::Presenters
-      extend Presentability
-  
-      presenter_for( Acme::Widget ) do
-      	expose :sku
-      	expose :name
-      	expose :unit_price
-      end
-  
-    end
-
-The block of `presenter_for` is evaluated in the context of a new Presenter
-class, so refer to that documentation for what's possible there.
-
-Sometimes you can't (or don't want to) have to load the entity class to
-declare a presenter for it, so you can also declare it using the class's name:
-
-    presenter_for( 'Acme::Widget' ) do
-      expose :sku
-      expose :name
-      expose :unit_price
-    end
-
-
-### Using Presenters
-
-You use presenters by instantiating them with the object they are a facade for
-(the "subject"), and then applying it:
-
-    acme_widget = Acme::Widget.new(
-      sku: "FF-2237H455",
-      name: "Throbbing Frobnulator",
-      unit_price: 299,
-      inventory_count: 301,
-      wholesale_cost: 39
-    )
-    presentation = Acme::Presenters.present( acme_widget )
-    # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299 }
-
-If you want to present a collection of objects as a collection, you can apply presenters to the collection instead:
-
-    widgets_in_stock = Acme::Widget.where { inventory_count > 0 }
-    collection_presentation = Acme::Presenters.present_collection( widgets_in_stock )
-    # => [ {:sku => "FF-2237H455", [...]}, {:sku => "FF-2237H460", [...]}, [...] ]
-
-The collection can be anything that is `Enumerable`.
-
-
-### Presentation Options
-
-Sometimes you want a bit more flexibility in what you present, allowing a single uniform presenter to be used in multiple use cases. To facilitate this, you can pass an options keyword hash to `#present`:
-
-    presenter_for( 'Acme::Widget' ) do
-      expose :sku
-      expose :name
-      expose :unit_price
-      
-      # Only expose the wholesale cost if presented via an internal API
-      expose :wholesale_cost, if: :internal_api
-    end
-
-    acme_widget = Acme::Widget.new(
-      sku: "FF-2237H455",
-      name: "Throbbing Frobnulator",
-      unit_price: 299,
-      inventory_count: 301,
-      wholesale_cost: 39
-    )
-    
-    # External API remains unchanged:
-    presentation = Acme::Presenters.present( acme_widget )
-    # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299 }
-
-    # But when run from an internal service:
-    internal_presentation = Acme::Presenters.present( acme_widget, internal_api: true )
-    # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299,
-    #      :wholesale_cost => 39 }
-
-There are some options that are set for you:
-
-<dl>
-<td><code>:in_collection</code></td>
-<dd>Set if the current object is being presented as part of a collection.</dd>
-</dl>
-
-
-

data/Presenter.md

@@ -1,109 +0,0 @@
-
-A presenter (facade) base class.
-
-
-### Declaring Presenters
-
-When you declare a presenter in a Presentability collection, the result is a
-subclass of Presentability::Presenter. The main way of defining a Presenter's
-functionality is via the ::expose method, which marks an attribute of the underlying
-entity object (the "subject") for exposure.
-
-    class MyPresenter < Presentability::Presenter
-      expose :name
-    end
-    
-    # Assuming `entity_object' has a "name" attribute...
-    presenter = MyPresenter.new( entity_object )
-    presenter.apply
-    # => { :name => "entity name" }
-
-
-### Presenter Collections
-
-Setting up classes manually like this is one option, but Presentability also lets you
-set them up as a collection, which is what further examples will assume for brevity:
-
-    module MyPresenters
-      extend Presentability
-    
-      presenter_for( EntityObject ) do
-        expose :name
-      end
-    
-    end
-
-
-### Complex Exposures
-
-Sometimes you want to do more than just use the presented entity's values as-is. There are a number of ways to do this.
-
-The first of these is to provide a block when exposing an attribute. The subject of the presenter is available to the block via the `subject` method:
-
-    require 'time'
-  
-    presenter_for( LogEvent ) do
-      # Turn Time objects into RFC2822-formatted time strings
-      expose :timestamp do
-        self.subject.timestamp.rfc2822
-      end
-  
-    end
-
-You can also declare the exposure using a regular method with the same name:
-
-    require 'time'
-  
-    presenter_for( LogEvent ) do
-      # Turn Time objects into RFC2822-formatted time strings
-      expose :timestamp
-
-      def timestamp
-        return self.subject.timestamp.rfc2822
-      end
-  
-    end
-
-This can be used to add presence checks:
-
-    require 'time'
-  
-    presenter_for( LogEvent ) do
-      # Require that presented entities have an `id` attribute
-      expose :id do
-        id = self.subject.id or raise "no `id' for %p" % [ self.subject ]
-        raise "`id' for %p is blank!" % [ self.subject ] if id.blank?
-
-        return id
-      end
-    end
-
-or conditional exposures:
-
-    presenter_for( Acme::Product ) do
-    
-      # Truncate the long description if presented as part of a collection
-      expose :detailed_description do
-        desc = self.subject.detailed_description
-        if self.options[:in_collection]
-          return desc[0..15] + '...'
-        else
-          return desc
-        end
-      end
-    
-    end
-
-
-### Exposure Aliases
-
-If you want to expose a field but use a different name in the resulting data structure, you can use the `:as` option in the exposure declaration:
-
-    presenter_for( LogEvent ) do
-      expose :timestamp, as: :created_at
-    end
-
-    presenter = MyPresenter.new( log_event )
-    presenter.apply
-    # => { :created_at => '2023-02-01 12:34:02.155365 -0800' }
-