presentability 0.1.0.pre.20220808082516 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 804aef5ae0367b75c4182c98315ad2791419fde213551ea9a5d9e860849b3e44
-  data.tar.gz: be7e218aafbbeb7f743d612da6498ab0b8a841594ca704fe342c2df2751bf1ec
+  metadata.gz: c0b10ef3f8fba6959cfd51db2efee95b4df669863b1ef433656da03573d61f07
+  data.tar.gz: beefa821c8f69d2038a992d4064b08429202100a6a9b139bc4427247f31f47c1
 SHA512:
-  metadata.gz: e461283d2b5c43af73319f41277b870b57372329a3194c2b37609a4a537493dfe12bf59be44d9da83a491957eb7f965430e0c670697d1058abb43cd30d4c2564
-  data.tar.gz: ba92018b64fe673aa858d1fc47381d43c11a0f5fe27bb640a9a44bf5f9f194fc2791f0faad3358fb44b9334dfe587bb9a49f461ad8fed6c11eb8d4cf96920635
+  metadata.gz: 5b2974973651bc54624dbca03bd89d841dd4aab00dcdc72f38ada1a40bb626b7096d78c2fd917b31c45af99d5771d0d935ce751da473ec8ef93e9dff2b01876d
+  data.tar.gz: 874444891db074bd26600f61bdacea937b75553616e541c6b50f0c69f0e888c2c5f437895da5d4bb5df5ca0dec849f73848f27230076e8883aec1ef30378393b

checksums.yaml.gz.sig

@@ -0,0 +1,2 @@
+:���Ҥ��7F�1/ІY��Ӝv�5�&�i����
�F�(���Z�2&�QY���^���x�E��d}�æi��@�!o]�Hǖ(�ö�������"0*��!��P�H�ʸ˃ዎ��J������5��}���?ҮJ��"7HA�g}����JO�A�����$�?<(���!N|�F{0i#��0�qٍ,�I�%�_�AՆ,M�Jϥ��l튞3�%6	uwCXm
+�We�>��7�8��ڽ�D�˄�rcWϲ̱clO��\h���E�7�ܓ���"uq�p�gL����SN>*�<�S�Z��zT8�i�x�`�d�{��ܓH-�2����;UE�8z��b�r>vR�rda��IT�#��N����`�H/

data/History.md

@@ -1,4 +1,8 @@
-## v0.0.1 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+# Release History for presentability
+
+---
+
+## 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,68 @@
 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
+# 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.1.0'
 
 
 	# Automatically load subordinate components
@@ -49,6 +104,10 @@ module Presentability
 	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.tar.gz.sig

@@ -0,0 +1,4 @@
+�s�k��z�u]%��0v�^9��S9��o%��Ǘ��=	�l;�D+Ke��遽Dv�M��z$����H�"���-7��>��K�
+�!���PI��(B���>2N2����!�H�b|L�;_�L3q/�I��3���ӓ��Z����>�"�D�L5�����^��3��6ޑ#g�*}i5�����B}���gr�W“����|4`}ym#˖D��yU��O��r��S�c�޴V��>@37a������X@뽧�}����J���
+n�f
+�d���;yX

metadata

@@ -1,14 +1,39 @@
 --- !ruby/object:Gem::Specification
 name: presentability
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.20220808082516
+  version: 0.1.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-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loggability
@@ -73,11 +98,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 +114,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: