presentability 0.1.0.pre.20220807214309 → 0.1.0.pre.20220808082516

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9cb368623de9f8e87b526b7ec806fb7469230df1afc2092d1e83c5c00a134140
-  data.tar.gz: a2db6a19a38d9bea3113807df66eea6f5a4ba198647291f8c2269cf5c09e2182
+  metadata.gz: 804aef5ae0367b75c4182c98315ad2791419fde213551ea9a5d9e860849b3e44
+  data.tar.gz: be7e218aafbbeb7f743d612da6498ab0b8a841594ca704fe342c2df2751bf1ec
 SHA512:
-  metadata.gz: f4a042bd7a2abdb74182c429ab3889a2a9e50765f67676be07c2697a22156e364b48c3e182c9260515c96e99d73b585b4893a332720e63333187a66c976110cc
-  data.tar.gz: dd0e2b57e05dc7f1c568ada5e6d5c94dac338f176c233a0d4b1509d9c455bc6d07a1274cfda2b7fe48cb30b4619e9ef6c21f34dc8f76781718c2ed6d5b110ab5
+  metadata.gz: e461283d2b5c43af73319f41277b870b57372329a3194c2b37609a4a537493dfe12bf59be44d9da83a491957eb7f965430e0c670697d1058abb43cd30d4c2564
+  data.tar.gz: ba92018b64fe673aa858d1fc47381d43c11a0f5fe27bb640a9a44bf5f9f194fc2791f0faad3358fb44b9334dfe587bb9a49f461ad8fed6c11eb8d4cf96920635

data/lib/presentability/presenter.rb

@@ -37,7 +37,7 @@ class Presentability::Presenter
 
 	### Set up an exposure that will delegate to the attribute of the subject with
 	### the given +name+.
-	def self::expose( name, options={} )
+	def self::expose( name, **options )
 		options = DEFAULT_EXPOSURE_OPTIONS.merge( options )
 
 		self.log.debug "Setting up exposure %p %p" % [ name, options ]
@@ -46,8 +46,9 @@ class Presentability::Presenter
 
 
 	### Create a new Presenter for the given +subject+.
-	def initialize( subject )
+	def initialize( subject, options={} )
 		@subject = subject
+		@options = options
 	end
 
 
@@ -60,6 +61,10 @@ class Presentability::Presenter
 	# building the representation.
 	attr_reader :subject
 
+	##
+	# The presentation options
+	attr_reader :options
+
 
 	### Return a new instance of whatever object type will be used to represent the
 	### subject.
@@ -72,13 +77,57 @@ class Presentability::Presenter
 	def apply
 		result = self.empty_representation
 
-		self.class.exposures.each do |name, opts|
-			# :TODO: #public_send instead?
-			value = self.subject.send( name )
+		self.class.exposures.each do |name, exposure_options|
+			next if self.skip_exposure?( name )
+
+			value = self.expose_via_delegation( name, exposure_options ) ||
+				self.expose_via_presenter_method( name, exposure_options ) or
+				raise NoMethodError, "can't expose %p -- no such attribute exists" % [name]
+
 			result[ name.to_sym ] = value
 		end
 
 		return result
 	end
 
-end # class Presentability::Presenter
+
+	### Returns +true+ if the exposure with the specified +name+ should be skipped
+	### for the current #subject and #options.
+	def skip_exposure?( name )
+		exposure_options = self.class.exposures[ name ] or return true
+
+		return (exposure_options[:if] && !self.options[ exposure_options[:if] ]) ||
+			(exposure_options[:unless] && self.options[ exposure_options[:unless] ])
+	end
+
+
+	### Attempt to expose the attribute with the given +name+ via delegation to the
+	### subject's method of the same name. Returns +nil+ if no such method exists.
+	def expose_via_delegation( name, options={} )
+		self.log.debug "Trying to expose %p via delegation to %p" % [ name, self.subject ]
+
+		return nil unless self.subject.respond_to?( name )
+
+		return self.subject.send( name )
+	end
+
+
+	### Attempt to expose the attribute with the given +name+ via a method on the presenter
+	### of the same name. Returns +nil+ if no such method exists.
+	def expose_via_presenter_method( name, options={} )
+		self.log.debug "Trying to expose %p via presenter method" % [ name ]
+
+		return nil unless self.respond_to?( name )
+
+		meth = self.method( name )
+		return meth.call
+	end
+
+
+	### Return a human-readable representation of the object suitable for debugging.
+	def inspect
+		return "#<Presentability::Presenter:%#0x for %p>" % [ self.object_id / 2, self.subject ]
+	end
+
+end # class Presentability::Presenter
+

data/lib/presentability.rb

@@ -33,15 +33,17 @@ module Presentability
 	### Set up a presentation for the given +entity_class+.
 	def presenter_for( entity_class, &block )
 		presenter_class = Class.new( Presentability::Presenter )
-		presenter_class.instance_eval( &block )
+		presenter_class.module_eval( &block )
 
 		self.presenters[ entity_class ] = presenter_class
 	end
 
 
 	### Return a representation of the +object+ by applying a declared presentation.
-	def present( object )
-		representation = self.present_by_class( object )
+	def present( object, **options )
+		representation = self.present_by_class( object, **options ) ||
+			self.present_by_classname( object, **options ) or
+			raise NoMethodError, "no presenter found for %p" % [ object ]
 
 		return representation
 	end
@@ -49,9 +51,20 @@ module Presentability
 
 	### Return a representation of the +object+ by applying a presenter declared for its
 	### class. Returns +nil+ if no such presenter exists.
-	def present_by_class( object )
+	def present_by_class( object, **presentation_options )
 		presenter_class = self.presenters[ object.class ] or return nil
-		presenter = presenter_class.new( object )
+		presenter = presenter_class.new( object, **presentation_options )
+
+		return presenter.apply
+	end
+
+
+	### Return a representation of the +object+ by applying a presenter declared for its
+	### class name. Returns +nil+ if no such presenter exists.
+	def present_by_classname( object, **presentation_options )
+		classname = object.class.name or return nil
+		presenter_class = self.presenters[ classname ] or return nil
+		presenter = presenter_class.new( object, **presentation_options )
 
 		return presenter.apply
 	end

data/spec/presentability/presenter_spec.rb

@@ -0,0 +1,98 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require_relative '../spec_helper'
+
+require 'ostruct'
+require 'presentability/presenter'
+
+
+RSpec.describe( Presentability::Presenter ) do
+
+	let( :presenter_subject ) do
+		OpenStruct.new( country: 'Philippines', export: 'Copper', flower: 'Sampaguita' )
+	end
+
+
+	it "can't be instantiated directly" do
+		expect {
+			described_class.new( presenter_subject )
+		}.to raise_error( NoMethodError, /private method `new'/i )
+	end
+
+
+	describe "a concrete subclass" do
+
+		let( :subclass ) { Class.new(described_class) }
+
+
+		it "can be created with just a subject" do
+			presenter = subclass.new( presenter_subject )
+			expect( presenter.apply ).to eq( {} )
+		end
+
+
+		it "can expose an attribute" do
+			subclass.expose( :country )
+			presenter = subclass.new( presenter_subject )
+
+			expect( presenter.apply ).to eq({ country: 'Philippines' })
+		end
+
+
+		it "can expose attributes conditionally" do
+			subclass.expose( :country )
+			subclass.expose( :export, if: :financial )
+			subclass.expose( :flower, unless: :financial )
+
+			financial_presenter = subclass.new( presenter_subject, financial: true )
+			cultural_presenter = subclass.new( presenter_subject, financial: false )
+
+			expect( financial_presenter.apply ).
+				to eq({ country: 'Philippines', export: 'Copper' })
+			expect( cultural_presenter.apply ).
+				to eq({ country: 'Philippines', flower: 'Sampaguita' })
+		end
+
+
+		it "doesn't skip exposures that are unconditional" do
+			subclass.expose( :country )
+
+			presenter = subclass.new( presenter_subject )
+
+			expect( presenter.skip_exposure?(:country) ).to be_falsey
+		end
+
+
+		it "skips exposures whose conditions are unmet" do
+			subclass.expose( :country )
+			subclass.expose( :export, if: :financial )
+			subclass.expose( :flower, unless: :financial )
+
+			presenter = subclass.new( presenter_subject, financial: true )
+
+			expect( presenter.skip_exposure?(:export) ).to be_falsey
+			expect( presenter.skip_exposure?(:flower) ).to be_truthy
+		end
+
+
+		it "skips exposures that don't exist" do
+			subclass.expose( :country )
+			subclass.expose( :export, if: :financial )
+			subclass.expose( :flower, unless: :financial )
+
+			presenter = subclass.new( presenter_subject )
+
+			expect( presenter.skip_exposure?(:bus_schedule) ).to be_truthy
+		end
+
+
+		it "has useful #inspect output" do
+			presenter = subclass.new( presenter_subject )
+			expect( presenter.inspect ).to match( /Presentability::Presenter\S+ for /i )
+		end
+
+	end
+
+end
+

data/spec/presentability_spec.rb

@@ -11,6 +11,10 @@ RSpec.describe Presentability do
 
 	let( :entity_class ) do
 		Class.new do
+			def self::name
+				return 'Acme::Entity'
+			end
+
 			def initialize
 				@foo = 1
 				@bar = 'two'
@@ -26,22 +30,79 @@ RSpec.describe Presentability do
 
 	describe "an extended module" do
 
-		subject do
+		let( :extended_module ) do
 			mod = Module.new
 			mod.extend( described_class )
 		end
 
 
 		it "can define a presenter for an explicit class" do
-			subject.presenter_for( entity_class ) do
+			extended_module.presenter_for( entity_class ) do
+				expose :foo
+				expose :bar
+			end
+
+			expect( extended_module.present(entity_instance) ).to eq({ foo: 1, bar: 'two' })
+		end
+
+
+		it "can define a presenter for a class name" do
+			extended_module.presenter_for( 'Acme::Entity' ) do
 				expose :foo
 				expose :bar
 			end
 
-			expect( subject.present(entity_instance) ).to eq({ foo: 1, bar: 'two' })
+			expect( extended_module.present(entity_instance) ).to eq({ foo: 1, bar: 'two' })
 		end
 
 
+		it "can effect more complex exposures be declaring presenter methods" do
+			extended_module.presenter_for( entity_class ) do
+				expose :foo
+				expose :bar
+				expose :id
+
+				def id
+					self.subject.object_id
+				end
+			end
+
+			expect( extended_module.present(entity_instance) ).
+				to eq({ foo: 1, bar: 'two', id: entity_instance.object_id })
+		end
+
+
+		it "can be made conditional on an option being set" do
+			extended_module.presenter_for( entity_class ) do
+				expose :foo
+				expose :bar, if: :include_bar
+			end
+
+			result1 = extended_module.present( entity_instance )
+			result2 = extended_module.present( entity_instance, include_bar: true )
+
+			expect( result1 ).to eq({ foo: 1 })
+			expect( result2 ).to eq({ foo: 1, bar: 'two' })
+		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 )
+		end
+
+
+		it "errors usefully if asked to expose an attribute that doesn't exist" do
+			extended_module.presenter_for( entity_class ) do
+				expose :id
+			end
+
+			expect {
+				extended_module.present( entity_instance )
+			}.to raise_error( NoMethodError, /can't expose :id -- no such attribute exists/i )
+		end
+
 	end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: presentability
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.20220807214309
+  version: 0.1.0.pre.20220808082516
 platform: ruby
 authors:
 - Michael Granger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-07 00:00:00.000000000 Z
+date: 2022-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.19'
+- !ruby/object:Gem::Dependency
+  name: rdoc-generator-fivefish
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 description: Facade-based presenters with minimal assumptions. This library contains
   utilities for setting up presenters for data classes for things like web services,
   logging output, etc.
@@ -52,6 +66,7 @@ files:
 - README.md
 - lib/presentability.rb
 - lib/presentability/presenter.rb
+- spec/presentability/presenter_spec.rb
 - spec/presentability_spec.rb
 - spec/spec_helper.rb
 homepage: https://hg.sr.ht/~ged/Presentability