presentability 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff4d9944824eaaa9ef6bc0d5e2b02879e83c481f2db9a39fe6c6ebc6f947dd7f
-  data.tar.gz: 4ccd0e65bdaae2504bf6edad1df4aab25698d5290b740028c5f5dc7c78732302
+  metadata.gz: 67ea66c2c975ecb5064c9ddb9c0be1a203b0e9e9944dfc3f3821f07e360fc726
+  data.tar.gz: c13fdaccf960dc87d3feaed73e2a22a96ad805aed83cadbadeeee9cc60e80e49
 SHA512:
-  metadata.gz: cae40ce72cd721000c47cff537ba2a2ac6635fc27205f79d81548471efda66b499c9aadd8eab97049a457dbd1c784e20ec5cd01805a57c511e1da808517c5ab8
-  data.tar.gz: 73ccbe66aeeed78447ae7cb91a0bb9cdbe95325d834e6fcfc6baaa4c96103cfb03efa4ef55f3718098ad021f211c17d5365f2e528b0dc5e846570ff6bec3407d
+  metadata.gz: 550a710c7ae589dfc6ebb1ed801508c8e2d347dbd37e1cdd19e3f3699b5b203ad38b7f2dc6a917e71d3e3dd3711e4eefe8c01594a1f4d92f10b120c4fe1e0a82
+  data.tar.gz: 07d9674d3ad188b6b19923153accddf6175bf61d238d79867b7237a34a10595e066e10f4d37cc702bbcca8b7dcf65fd7df75ad0eb2fa0c4557716be3a370090b

checksums.yaml.gz.sig

@@ -1,2 +1,4 @@
-��~�>����;O*:p����ݔ��ٰK ^[���>Y*ΫY�9��c�c���q�e+�!f��~;�Ib�*�,��,h���z��0j��p���d�U�H���+`��čZf���
�������YN��&8Y��k�a*;!`��I9(�T�/�+B�*�qj��Q���Ḯ�����X9��ό�Y&l@����H^��4�D�~�&��?H����C)�v����1G+_sA{�7X�|͓��
-�lO+�L.�2
+p�kV��V��H�Nl*�z�K3]<�[�>"��oNP��3O�-ф��ں<�W
��ȁ
î��~������O���������{��a�Z��	c���J�h�a)^\����/�JDMN�f׹9����
+/�;!��C
+���&9u���NI�	X��1l7�Po	�p�|�T��VI:��t}���E�
+��|	��I�_gfM��*B7�O�Dw���,��6�v���B?��Ro$��3&���

data/History.md

@@ -1,6 +1,13 @@
 # Release History for presentability
 
 ---
+## v0.4.0 [2023-02-02] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Add presentation aliases.
+
+
 ## v0.3.0 [2022-12-16] Michael Granger <ged@faeriemud.org>
 
 Improvements:

data/Presentability.md

@@ -0,0 +1,105 @@
+
+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

@@ -0,0 +1,109 @@
+
+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' }
+

data/lib/presentability/presenter.rb

@@ -1,43 +1,10 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 
 require 'loggability'
 
 require 'presentability' unless defined?( Presentability )
 
-#
-# A presenter (facade) base class.
-#
-# 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.
-#
-# ```ruby
-# class MyPresenter < Presentability::Presenter
-#   expose :name
-# end
-#
-# # Assuming `entity_object' has a "name" attribute...
-# presenter = MyPresenter.new( entity_object )
-# presenter.apply
-# # => { :name => "entity name" }
-# ```
-#
-# Setting up classes like this manually is one option, but Presentability also lets you
-# set them up as a collection, which is what further examples will assume for brevity:
-#
-# ```ruby
-# module MyPresenters
-#   extend Presentability
-#
-#   presenter_for( EntityObject ) do
-#     expose :name
-#   end
-#
-# end
-# ```
-#
+# :include: Presenter.md
 class Presentability::Presenter
 	extend Loggability
 
@@ -63,6 +30,7 @@ class Presentability::Presenter
 
 
 	##
+	# :singleton-method: exposures
 	# The Hash of exposures declared by this class
 	singleton_class.attr_accessor :exposures
 
@@ -80,6 +48,10 @@ class Presentability::Presenter
 			define_method( name, &method_body )
 		end
 
+		if (exposure_alias = options[:as]) && self.exposures.key?( exposure_alias )
+			raise ScriptError, "alias %p collides with another exposure" % [ exposure_alias ]
+		end
+
 		self.log.debug "Setting up exposure %p, options = %p" % [ name, options ]
 		self.exposures[ name ] = options
 	end
@@ -141,7 +113,8 @@ class Presentability::Presenter
 		self.class.exposures.each do |name, exposure_options|
 			next if self.skip_exposure?( name )
 			value = self.method( name ).call
-			result[ name.to_sym ] = value
+			key = exposure_options.key?( :as ) ? exposure_options[:as] : name
+			result[ key.to_sym ] = value
 		end
 
 		return result

data/lib/presentability.rb

@@ -1,78 +1,15 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 
 require 'loggability'
 
 
-# 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:
-#
-# ```ruby
-# 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:
-#
-# ```ruby
-# 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:
-#
-# ```ruby
-# acme_widget = Acme::Widget.new(
-#   sku: "FF-2237H455",
-#   name: "Throbbing Frobnulator",
-#   unit_price: 299,
-#   inventory_count: 301,
-#   wholesale_cost: 39
-# )
-# presenter = Acme::Presenters.present( acme_widget )
-# presenter.apply
-# # => { :sku => "FF-2237H455", :name => "Throbbing Frobnulator", :unit_price => 299 }
-# ```
-#
-#
+# :include: Presentability.md
 module Presentability
 	extend Loggability
 
 
 	# Package version
-	VERSION = '0.3.0'
+	VERSION = '0.4.0'
 
 
 	# Automatically load subordinate components
@@ -114,6 +51,7 @@ module Presentability
 	### Return an Array of all representations of the members of the
 	### +collection+ by applying a declared presentation.
 	def present_collection( collection, **options )
+		options = options.merge( in_collection: true )
 		return collection.map {|object| self.present(object, **options) }
 	end
 

data/spec/presentability/presenter_spec.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 
 require_relative '../spec_helper'
 
@@ -21,7 +20,7 @@ RSpec.describe( Presentability::Presenter ) do
 	end
 
 
-	describe "a concrete subclass" do
+	describe "concrete subclass" do
 
 		let( :subclass ) { Class.new(described_class) }
 

data/spec/presentability_spec.rb

@@ -1,5 +1,4 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 
 require_relative 'spec_helper'
 
@@ -55,7 +54,7 @@ RSpec.describe Presentability do
 	end
 
 
-	describe "an extended module" do
+	describe "when used to extend a module" do
 
 		let( :extended_module ) do
 			mod = Module.new
@@ -181,10 +180,38 @@ RSpec.describe Presentability do
 		end
 
 
+		it "can alias a field to a different name" do
+			extended_module.presenter_for( entity_class ) do
+				expose :foo, as: :bar
+			end
+
+			expect( extended_module.present(entity_instance) ).to eq({ bar: 1 })
+		end
+
+
+		it "doesn't error when aliasing a field to itself" do
+			extended_module.presenter_for( entity_class ) do
+				expose :foo, as: :foo
+				expose :bar, as: :floom
+			end
+
+			expect( extended_module.present(entity_instance) ).to eq({ foo: 1, floom: 'two' })
+		end
+
+
+		it "raises if an alias clobbers another field" do
+			expect {
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+					expose :bar, as: :foo
+				end
+			}.to raise_error( ScriptError, /alias :foo collides with another exposure/i )
+		end
+
 
-		describe "collection handling" do
+		describe "and used to present a collection" do
 
-			it "can present a collection" do
+			it "handles a homogeneous collection" do
 				extended_module.presenter_for( entity_class ) do
 					expose :foo
 					expose :bar
@@ -203,7 +230,7 @@ RSpec.describe Presentability do
 			end
 
 
-			it "can present a mixed collection" do
+			it "handles a hetergeneous collection" do
 				extended_module.presenter_for( entity_class ) do
 					expose :foo
 					expose :bar
@@ -260,6 +287,24 @@ RSpec.describe Presentability do
 				end
 			end
 
+
+			it "sets the :in_collection option to allow for eliding attributes" do
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+					expose :bar, unless: :in_collection
+					expose :baz
+				end
+
+				results = extended_module.present_collection( [entity_instance] )
+
+				expect( results.first ).to include( :foo, :baz )
+				expect( results.first ).not_to include( :bar )
+
+				result = extended_module.present( entity_instance )
+
+				expect( result ).to include( :foo, :bar, :baz )
+			end
+
 		end
 
 	end

data/spec/spec_helper.rb

@@ -1,7 +1,13 @@
 # -*- ruby -*-
-# frozen_string_literal: true
 
-require 'simplecov' if ENV['COVERAGE']
+if ENV['COVERAGE']
+	require 'simplecov'
+	SimpleCov.start do
+		add_filter 'spec/'
+		enable_coverage :branch
+		primary_coverage :branch
+	end
+end
 
 require 'rspec'
 require 'i18n'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presentability
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Michael Granger
@@ -10,9 +10,9 @@ bindir: bin
 cert_chain:
 - |
   -----BEGIN CERTIFICATE-----
-  MIID+DCCAmCgAwIBAgIBBDANBgkqhkiG9w0BAQsFADAiMSAwHgYDVQQDDBdnZWQv
-  REM9RmFlcmllTVVEL0RDPW9yZzAeFw0yMjAxMDcyMzU4MTRaFw0yMzAxMDcyMzU4
-  MTRaMCIxIDAeBgNVBAMMF2dlZC9EQz1GYWVyaWVNVUQvREM9b3JnMIIBojANBgkq
+  MIID+DCCAmCgAwIBAgIBBTANBgkqhkiG9w0BAQsFADAiMSAwHgYDVQQDDBdnZWQv
+  REM9RmFlcmllTVVEL0RDPW9yZzAeFw0yMzAxMTYxNzE2MDlaFw0yNDAxMTYxNzE2
+  MDlaMCIxIDAeBgNVBAMMF2dlZC9EQz1GYWVyaWVNVUQvREM9b3JnMIIBojANBgkq
   hkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAvyVhkRzvlEs0fe7145BYLfN6njX9ih5H
   L60U0p0euIurpv84op9CNKF9tx+1WKwyQvQP7qFGuZxkSUuWcP/sFhDXL1lWUuIl
   M4uHbGCRmOshDrF4dgnBeOvkHr1fIhPlJm5FO+Vew8tSQmlDsosxLUx+VB7DrVFO
@@ -23,17 +23,17 @@ cert_chain:
   ozilJg4aar2okb/RA6VS87o+d7g6LpDDMMQjH4G9OPnJENLdhu8KnPw/ivSVvQw7
   N2I4L/ZOIe2DIVuYH7aLHfjZDQv/mNgpAgMBAAGjOTA3MAkGA1UdEwQCMAAwCwYD
   VR0PBAQDAgSwMB0GA1UdDgQWBBRyjf55EbrHagiRLqt5YAd3yb8k4DANBgkqhkiG
-  9w0BAQsFAAOCAYEASrm1AbEoxACZ9WXJH3R5axV3U0CA4xaETlL2YT+2nOfVBMQ9
-  0ZlkPx6j4ghKJgAIi1TMfDM2JyPJsppQh8tiNccDjWc62UZRY/dq26cMqf/lcI+a
-  6YBuEYvzZfearwVs8tHnXtwYV3WSCoCOQaB+nq2lA1O+nkKNl41WOsVbNama5jx3
-  8cQtVSEEmZy6jIDJ8c5TmBJ7BQUDEUEWA/A3V42Xyctoj7DvUXWE0lP+X6ypAVSr
-  lFh3TS64D7NTvxkmg7natUoCvobl6kGl4yMaqE4YRTlfuzhpf91TSOntClqrAOsS
-  K1s56WndQj3IoBocdY9mQhDZLtLHofSkymoP8btBlj5SsN24TiF0VMSZlctSCYZg
-  GKyHim/MMlIfGOWsgfioq5jzwmql7W4CDubbb8Lkg70v+hN2E/MnNVAcNE3gyaGc
-  P5YP5BAbNW+gvd3QHRiWTTuhgHrdDnGdXg93N2M5KHn1ug8BtPLQwlcFwEpKnlLn
-  btEP+7EplFuoiMfd
+  9w0BAQsFAAOCAYEARYCeUVBWARNKqF0cvNnLJvFf4hdW2+Rtc7NfC5jQvX9a1oom
+  sfVvS96eER/9cbrphu+vc59EELw4zT+RY3/IesnoE7CaX6zIOFmSmG7K61OHsSLR
+  KqMygcWwyuPXT2JG7JsGHuxbzgaRWe29HbSjBbLYxiMH8Zxh4tKutxzKF7jb0Ggq
+  KAf9MH5LwG8IHVIfV5drT14PvgR3tcvmrn1timPyJl+eZ3LNnm9ofOCweuZCq1cy
+  4Q8LV3vP2Cofy9q+az3DHdaUGlmMiZZZqKixDr1KSS9nvh0ZrKMOUL1sWj/IaxrQ
+  RV3y6td14q49t+xnbj00hPlbW7uE2nLJLt2NAoXiE1Nonndz1seB2c6HL79W9fps
+  E/O12pQjCp/aPUZMt8/8tKW31RIy/KP8XO6OTJNWA8A/oNEI0g5p/LmmEtJKWYr1
+  WmEdESlpWhzFECctefIF2lsN9vaOuof57RM77t2otrtcscDtNarIqjZsIyqtDvtL
+  DttITiit0Vwz7bY0
   -----END CERTIFICATE-----
-date: 2022-12-16 00:00:00.000000000 Z
+date: 2023-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -102,6 +102,8 @@ extra_rdoc_files: []
 files:
 - History.md
 - LICENSE.txt
+- Presentability.md
+- Presenter.md
 - README.md
 - lib/presentability.rb
 - lib/presentability/presenter.rb
@@ -132,7 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
 summary: Facade-based presenters with minimal assumptions.