presentability 0.4.0 → 0.6.0

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/presenter_spec.rb

@@ -9,7 +9,18 @@ require 'presentability/presenter'
 RSpec.describe( Presentability::Presenter ) do
 
 	let( :presenter_subject ) do
-		OpenStruct.new( country: 'Philippines', export: 'Copper', flower: 'Sampaguita' )
+		OpenStruct.new(
+			country: 'Philippines',
+			export: 'Copper',
+			flower: 'Sampaguita',
+			cities: ['Quezon City', 'Cagayan de Oro', 'Roxas']
+		)
+	end
+
+	let( :presenters ) do
+		mod = Module.new
+		mod.extend( Presentability )
+		return mod
 	end
 
 
@@ -27,7 +38,7 @@ RSpec.describe( Presentability::Presenter ) do
 
 		it "can be created with just a subject" do
 			presenter = subclass.new( presenter_subject )
-			expect( presenter.apply ).to eq( {} )
+			expect( presenter.apply(presenters) ).to eq( {} )
 		end
 
 
@@ -35,7 +46,7 @@ RSpec.describe( Presentability::Presenter ) do
 			subclass.expose( :country )
 			presenter = subclass.new( presenter_subject )
 
-			expect( presenter.apply ).to eq({ country: 'Philippines' })
+			expect( presenter.apply(presenters) ).to eq({ country: 'Philippines' })
 		end
 
 
@@ -47,9 +58,9 @@ RSpec.describe( Presentability::Presenter ) do
 			financial_presenter = subclass.new( presenter_subject, financial: true )
 			cultural_presenter = subclass.new( presenter_subject, financial: false )
 
-			expect( financial_presenter.apply ).
+			expect( financial_presenter.apply(presenters) ).
 				to eq({ country: 'Philippines', export: 'Copper' })
-			expect( cultural_presenter.apply ).
+			expect( cultural_presenter.apply(presenters) ).
 				to eq({ country: 'Philippines', flower: 'Sampaguita' })
 		end
 
@@ -86,6 +97,14 @@ RSpec.describe( Presentability::Presenter ) do
 		end
 
 
+		it "can expose an attribute as a collection" do
+			subclass.expose( :country )
+			subclass.expose_collection( :cities )
+
+			expect( subclass.exposures[:cities] ).to include( unless: :in_collection )
+		end
+
+
 		it "has useful #inspect output" do
 			presenter = subclass.new( presenter_subject )
 			expect( presenter.inspect ).to match( /Presentability::Presenter\S+ for /i )

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
@@ -43,6 +39,21 @@ RSpec.describe Presentability do
 		end
 	end
 
+	let( :complex_entity_class ) do
+		Class.new do
+			set_temporary_name 'Acme::Pair (Testing Class)'
+
+			def initialize( user:, entity:, overridden: false, locked: true )
+				@user = user
+				@entity = entity
+				@overridden = overridden
+				@locked = locked
+			end
+
+			attr_accessor :user, :entity, :overridden, :locked
+		end
+	end
+
 	let( :entity_instance ) { entity_class.new }
 	let( :other_entity_instance ) do
 		other_entity_class.new(
@@ -52,6 +63,9 @@ RSpec.describe Presentability do
 			Faker::Internet.password
 		)
 	end
+	let( :complex_entity_instance ) do
+		complex_entity_class.new( user: other_entity_instance, entity: entity_instance )
+	end
 
 
 	describe "when used to extend a module" do
@@ -73,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
@@ -162,10 +176,146 @@ RSpec.describe Presentability do
 		end
 
 
+		it "doesn't try to present objects with no instance variables by default" do
+			object = 'a string'
+			expect( extended_module.present(object) ).to be( object )
+
+			object = 8
+			expect( extended_module.present(object) ).to be( object )
+
+			object = :a_symbol
+			expect( extended_module.present(object) ).to be( object )
+
+			object = Time.now
+			expect( extended_module.present(object) ).to be( object )
+
+			object = %[an array of strings]
+			expect( extended_module.present(object) ).to be( object )
+
+			object = Object.new
+			expect( extended_module.present(object) ).to be( object )
+		end
+
+
+		it "allows presenters to be defined for objects with no instance variables" do
+			extended_module.presenter_for( Time ) do
+				expose :sec
+				expose :usec
+			end
+
+			object = Time.at( 1699287281.336554 )
+
+			expect( extended_module.present(object) ).to eq({
+				sec: object.sec,
+				usec: object.usec
+			})
+		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
 
 
@@ -230,7 +380,7 @@ RSpec.describe Presentability do
 			end
 
 
-			it "handles a hetergeneous collection" do
+			it "handles a heterogeneous collection" do
 				extended_module.presenter_for( entity_class ) do
 					expose :foo
 					expose :bar
@@ -307,6 +457,43 @@ RSpec.describe Presentability do
 
 		end
 
+
+		describe "and used to present a complex object" do
+
+			it "uses registered presenters for sub-objects" do
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+					expose :bar
+				end
+				extended_module.presenter_for( other_entity_class ) do
+					expose :firstname
+					expose :lastname
+					expose :email
+				end
+				extended_module.presenter_for( complex_entity_class ) do
+					expose :user
+					expose :entity
+					expose :locked
+				end
+
+				result = extended_module.present( complex_entity_instance )
+
+				expect( result ).to eq({
+					user: {
+						firstname: other_entity_instance.firstname,
+						lastname: other_entity_instance.lastname,
+						email: other_entity_instance.email,
+					},
+					entity: {
+						foo: entity_instance.foo,
+						bar: entity_instance.bar
+					},
+					locked: complex_entity_instance.locked,
+				})
+			end
+
+		end
+
 	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.4.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-02-02 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.6
+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>
-
-
-