presentability 0.1.0.pre.20220808082516 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 804aef5ae0367b75c4182c98315ad2791419fde213551ea9a5d9e860849b3e44
-  data.tar.gz: be7e218aafbbeb7f743d612da6498ab0b8a841594ca704fe342c2df2751bf1ec
+  metadata.gz: f5b0aae4df8ff0ef130bbcc9704f2f44a9b109dee48cc530db6abdfd0733cbd4
+  data.tar.gz: d149966c13d352f89c2f437c8ed251d63520ec33287c920e8ff7c1cd43eeb0e4
 SHA512:
-  metadata.gz: e461283d2b5c43af73319f41277b870b57372329a3194c2b37609a4a537493dfe12bf59be44d9da83a491957eb7f965430e0c670697d1058abb43cd30d4c2564
-  data.tar.gz: ba92018b64fe673aa858d1fc47381d43c11a0f5fe27bb640a9a44bf5f9f194fc2791f0faad3358fb44b9334dfe587bb9a49f461ad8fed6c11eb8d4cf96920635
+  metadata.gz: 906172259081cb4c871975c6e8096bfcd7d8a2434903cc8bef9562b9b18c11af889ef1733372d46c94420008baf5821499d19e6708c75224abd962febabc0515
+  data.tar.gz: 5d2c5691ee59ba2526755a3a2eab49547d093fa1d2fbedad4163a78ea35b8acc4dc74d20f0e16a90d7b9af3cbedd9a043c68f3b402f8197ea40031984fc4773b

data/History.md

@@ -1,4 +1,15 @@
-## v0.0.1 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+# Release History for presentability
+
+---
+
+## v0.2.0 [2022-12-06] Michael Granger <ged@faeriemud.org>
+
+Improvements:
+
+- Add collection presentation.
+
+
+## v0.1.0 [2022-08-11] Michael Granger <ged@faeriemud.org>
 
 Initial release.
 

data/README.md

@@ -22,14 +22,9 @@ services, logging output, etc.
 It is intended to be dead-simple by default, returning a Hash containing
 only the attributes you have intentionally exposed from the subject.
 
-    # lib/acme/widget.rb
-    class Acme::Widget
-      attr_accessor :sku,
-        :name,
-        :unit_price,
-        :internal_cost,
-        :inventory_count
-    end
+The most basic usage looks something like this:
+
+    require 'presentatbility'
 
     # lib/acme/presenters.rb
     module Acme::Presenters
@@ -45,7 +40,7 @@ only the attributes you have intentionally exposed from the subject.
     # lib/acme/service.rb
     class Acme::Service < Some::Webservice::Framework
     
-      on '/api/widgets/<sku>' do |sku|
+      get '/api/widgets/<sku>' do |sku|
         widget = Acme::Widget.lookup( sku )
         content_type 'application/json'
         representation = Acme::Presenters.present( widget )

data/lib/presentability/presenter.rb

@@ -5,7 +5,39 @@ 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
+# ```
+#
 class Presentability::Presenter
 	extend Loggability
 
@@ -66,13 +98,6 @@ class Presentability::Presenter
 	attr_reader :options
 
 
-	### Return a new instance of whatever object type will be used to represent the
-	### subject.
-	def empty_representation
-		return {}
-	end
-
-
 	### Apply the exposures to the subject and return the result.
 	def apply
 		result = self.empty_representation
@@ -101,6 +126,23 @@ class Presentability::Presenter
 	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
+
+
+	#########
+	protected
+	#########
+
+	### Return a new instance of whatever object type will be used to represent the
+	### subject.
+	def empty_representation
+		return {}
+	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={} )
@@ -123,11 +165,5 @@ class Presentability::Presenter
 		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

@@ -4,13 +4,75 @@
 require 'loggability'
 
 
-# Facade-based presenters with minimal assumptions.
+# 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 }
+# ```
+#
+#
 module Presentability
 	extend Loggability
 
 
 	# Package version
-	VERSION = '0.0.1'
+	VERSION = '0.2.0'
 
 
 	# Automatically load subordinate components
@@ -49,6 +111,17 @@ module Presentability
 	end
 
 
+	### Return an Array of all representations of the members of the
+	### +collection+ by applying a declared presentation.
+	def present_collection( collection, **options )
+		return collection.map {|object| self.present(object, **options) }
+	end
+
+
+	#########
+	protected
+	#########
+
 	### 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, **presentation_options )

data/spec/presentability_spec.rb

@@ -3,6 +3,7 @@
 
 require_relative 'spec_helper'
 
+require 'faker'
 require 'rspec'
 require 'presentability'
 
@@ -15,17 +16,35 @@ RSpec.describe Presentability do
 				return 'Acme::Entity'
 			end
 
-			def initialize
-				@foo = 1
-				@bar = 'two'
-				@baz = :three
+			def initialize( foo: 1, bar: 'two', baz: :three )
+				@foo = foo
+				@bar = bar
+				@baz = baz
 			end
 
 			attr_accessor :foo, :bar, :baz
 		end
 	end
 
+	let( :other_entity_class ) do
+		Class.new do
+			def self::name
+				return 'Acme::User'
+			end
+
+			def initialize( firstname, lastname, email, password )
+				@firstname = firstname
+				@lastname = lastname
+				@email = email
+				@password = password
+			end
+
+			attr_accessor :firstname, :lastname, :email, :password
+		end
+	end
+
 	let( :entity_instance ) { entity_class.new }
+	let( :other_entity_instance ) { entity_class.new }
 
 
 	describe "an extended module" do
@@ -103,6 +122,87 @@ RSpec.describe Presentability do
 			}.to raise_error( NoMethodError, /can't expose :id -- no such attribute exists/i )
 		end
 
+
+		describe "collection handling" do
+
+			it "can present a collection" do
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+					expose :bar
+				end
+				collection = 5.times.map do
+					entity_class.new( foo: rand(100) )
+				end
+
+				results = extended_module.present_collection( collection )
+
+				expect( results ).to have_attributes( length: 5 )
+				results.each do |representation|
+					expect( representation ).to include( :foo, :bar )
+					expect( representation ).to_not include( :baz )
+				end
+			end
+
+
+			it "can present a mixed collection" 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
+
+				collection = 5.times.flat_map do
+					[
+						entity_class.new( foo: rand(100) ),
+						other_entity_class.new(
+							Faker::Name.first_name,
+							Faker::Name.last_name,
+							Faker::Internet.email,
+							Faker::Internet.password
+						)
+					]
+				end
+
+				results = extended_module.present_collection( collection )
+
+				expect( results ).to have_attributes( length: 10 )
+				results.each do |representation|
+					expect( representation ).to include( :foo, :bar ).
+						or( include(:firstname, :lastname, :email) )
+					expect( representation ).to_not include( :baz )
+					expect( representation ).to_not include( :password )
+				end
+			end
+
+
+			it "passes options to the individual presenters" do
+				extended_module.presenter_for( entity_class ) do
+					expose :foo
+					expose :bar, if: :include_bar
+				end
+				collection = 5.times.map do
+					entity_class.new( foo: rand(100) )
+				end
+
+				results = extended_module.present_collection( collection )
+				results.each do |representation|
+					expect( representation ).to include( :foo )
+					expect( representation ).to_not include( :bar, :baz )
+				end
+
+				results = extended_module.present_collection( collection, include_bar: true )
+				results.each do |representation|
+					expect( representation ).to include( :foo, :bar )
+					expect( representation ).to_not include( :baz )
+				end
+			end
+
+		end
+
 	end
 
 end

data/spec/spec_helper.rb

@@ -4,6 +4,11 @@
 require 'simplecov' if ENV['COVERAGE']
 
 require 'rspec'
+require 'i18n'
+require 'faker'
+
+Faker::Config.locale = 'en'
+I18n.reload!
 
 require 'loggability/spechelpers'
 

metadata

@@ -1,14 +1,39 @@
 --- !ruby/object:Gem::Specification
 name: presentability
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.20220808082516
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Granger
 autorequire:
 bindir: bin
-cert_chain: []
-date: 2022-08-08 00:00:00.000000000 Z
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIID+DCCAmCgAwIBAgIBBDANBgkqhkiG9w0BAQsFADAiMSAwHgYDVQQDDBdnZWQv
+  REM9RmFlcmllTVVEL0RDPW9yZzAeFw0yMjAxMDcyMzU4MTRaFw0yMzAxMDcyMzU4
+  MTRaMCIxIDAeBgNVBAMMF2dlZC9EQz1GYWVyaWVNVUQvREM9b3JnMIIBojANBgkq
+  hkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAvyVhkRzvlEs0fe7145BYLfN6njX9ih5H
+  L60U0p0euIurpv84op9CNKF9tx+1WKwyQvQP7qFGuZxkSUuWcP/sFhDXL1lWUuIl
+  M4uHbGCRmOshDrF4dgnBeOvkHr1fIhPlJm5FO+Vew8tSQmlDsosxLUx+VB7DrVFO
+  5PU2AEbf04GGSrmqADGWXeaslaoRdb1fu/0M5qfPTRn5V39sWD9umuDAF9qqil/x
+  Sl6phTvgBrG8GExHbNZpLARd3xrBYLEFsX7RvBn2UPfgsrtvpdXjsHGfpT3IPN+B
+  vQ66lts4alKC69TE5cuKasWBm+16A4aEe3XdZBRNmtOu/g81gvwA7fkJHKllJuaI
+  dXzdHqq+zbGZVSQ7pRYHYomD0IiDe1DbIouFnPWmagaBnGHwXkDT2bKKP+s2v21m
+  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
+  -----END CERTIFICATE-----
+date: 2022-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -24,6 +49,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rake-deveiate
   requirement: !ruby/object:Gem::Requirement
@@ -73,11 +112,11 @@ homepage: https://hg.sr.ht/~ged/Presentability
 licenses:
 - BSD-3-Clause
 metadata:
-  bug_tracker_uri: https://todo.sr.ht/~ged/Presentability
-  changelog_uri: https://deveiate.org/code/presentability/History_md.html
-  documentation_uri: https://deveiate.org/code/presentability
   homepage_uri: https://hg.sr.ht/~ged/Presentability
+  documentation_uri: https://deveiate.org/code/presentability
+  changelog_uri: https://deveiate.org/code/presentability/History_md.html
   source_uri: https://hg.sr.ht/~ged/Presentability
+  bug_tracker_uri: https://todo.sr.ht/~ged/Presentability
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -89,9 +128,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.3.7
 signing_key: