presentability 0.1.0.pre.20220807214309

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9cb368623de9f8e87b526b7ec806fb7469230df1afc2092d1e83c5c00a134140
+  data.tar.gz: a2db6a19a38d9bea3113807df66eea6f5a4ba198647291f8c2269cf5c09e2182
+SHA512:
+  metadata.gz: f4a042bd7a2abdb74182c429ab3889a2a9e50765f67676be07c2697a22156e364b48c3e182c9260515c96e99d73b585b4893a332720e63333187a66c976110cc
+  data.tar.gz: dd0e2b57e05dc7f1c568ada5e6d5c94dac338f176c233a0d4b1509d9c455bc6d07a1274cfda2b7fe48cb30b4619e9ef6c21f34dc8f76781718c2ed6d5b110ab5

data/History.md

@@ -0,0 +1,4 @@
+## v0.0.1 [YYYY-MM-DD] Michael Granger <ged@FaerieMUD.org>
+
+Initial release.
+

data/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2022, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,124 @@
+# Presentability
+
+home
+: https://hg.sr.ht/~ged/Presentability
+
+code
+: https://hg.sr.ht/~ged/Presentability
+
+github
+: https://github.com/ged/presentability
+
+docs
+: https://deveiate.org/code/presentability
+
+
+## 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.
+
+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
+
+    # lib/acme/presenters.rb
+    module Acme::Presenters
+      extend Presentability
+      
+      presenter_for Acme::Widget do
+        expose :sku
+        expose :name
+        expose :unit_price
+      end
+    end
+
+    # lib/acme/service.rb
+    class Acme::Service < Some::Webservice::Framework
+    
+      on '/api/widgets/<sku>' do |sku|
+        widget = Acme::Widget.lookup( sku )
+        content_type 'application/json'
+        representation = Acme::Presenters.present( widget )
+        return representation.to_json
+      end
+    
+    end
+
+Note that Presentability doesn't do any encoding for you, or infer anything, or
+require that you alter your data classes. It's just a collection of Facades for
+your data objects that return a limited representation of their subjects.
+
+More details can be found in the docs for the Presentability module, and in
+Presentability::Presenter.
+
+
+## Prerequisites
+
+* Ruby
+
+
+## Installation
+
+    $ gem install presentability
+
+
+## Contributing
+
+You can check out the current development source with Mercurial via its
+[project page](http://bitbucket.org/ged/presentability). Or if you prefer Git, via
+[its Github mirror](https://github.com/ged/presentability).
+
+After checking out the source and changing into the resulting directory, run:
+
+    $ gem install -Ng
+    $ rake setup
+
+This will install dependencies, and do any other necessary setup for development.
+
+
+## Authors
+
+- Michael Granger <ged@faeriemud.org>
+
+
+## License
+
+Copyright (c) 2022, Michael Granger
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the author/s, nor the names of the project's
+  contributors may be used to endorse or promote products derived from this
+  software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+

data/lib/presentability/presenter.rb

@@ -0,0 +1,84 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+require 'presentability' unless defined?( Presentability )
+
+
+class Presentability::Presenter
+	extend Loggability
+
+
+	# The exposure options used by every exposure unless overridden
+	DEFAULT_EXPOSURE_OPTIONS = {}.freeze
+
+
+	# Loggability API; use Presentability's logger
+	log_to :presentability
+
+
+	# This is an abstract class; disallow instantiation
+	private_class_method :new
+
+
+	### Enable instantiation by subclasses.
+	def self::inherited( subclass )
+		super
+		subclass.public_class_method( :new )
+		subclass.exposures = {}
+	end
+
+
+	##
+	# The Hash of exposures declared by this class
+	singleton_class.attr_accessor :exposures
+
+
+	### Set up an exposure that will delegate to the attribute of the subject with
+	### the given +name+.
+	def self::expose( name, options={} )
+		options = DEFAULT_EXPOSURE_OPTIONS.merge( options )
+
+		self.log.debug "Setting up exposure %p %p" % [ name, options ]
+		self.exposures[ name ] = options
+	end
+
+
+	### Create a new Presenter for the given +subject+.
+	def initialize( subject )
+		@subject = subject
+	end
+
+
+	######
+	public
+	######
+
+	##
+	# The subject of the presenter, the object that is delegated to when
+	# building the representation.
+	attr_reader :subject
+
+
+	### 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
+
+		self.class.exposures.each do |name, opts|
+			# :TODO: #public_send instead?
+			value = self.subject.send( name )
+			result[ name.to_sym ] = value
+		end
+
+		return result
+	end
+
+end # class Presentability::Presenter

data/lib/presentability.rb

@@ -0,0 +1,60 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'loggability'
+
+
+# Facade-based presenters with minimal assumptions.
+module Presentability
+	extend Loggability
+
+
+	# Package version
+	VERSION = '0.0.1'
+
+
+	# Automatically load subordinate components
+	autoload :Presenter, 'presentability/presenter'
+
+
+	# Create a logger used by all Presentability modules
+	log_as :presentability
+
+
+	### Extension hook -- decorate the including +mod+.
+	def self::extended( mod )
+		super
+		mod.singleton_class.attr_accessor :presenters
+		mod.presenters = {}
+	end
+
+
+
+	### 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 )
+
+		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 )
+
+		return representation
+	end
+
+
+	### 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 )
+		presenter_class = self.presenters[ object.class ] or return nil
+		presenter = presenter_class.new( object )
+
+		return presenter.apply
+	end
+
+end # module Presentability
+

data/spec/presentability_spec.rb

@@ -0,0 +1,48 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require_relative 'spec_helper'
+
+require 'rspec'
+require 'presentability'
+
+
+RSpec.describe Presentability do
+
+	let( :entity_class ) do
+		Class.new do
+			def initialize
+				@foo = 1
+				@bar = 'two'
+				@baz = :three
+			end
+
+			attr_accessor :foo, :bar, :baz
+		end
+	end
+
+	let( :entity_instance ) { entity_class.new }
+
+
+	describe "an extended module" do
+
+		subject 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
+				expose :foo
+				expose :bar
+			end
+
+			expect( subject.present(entity_instance) ).to eq({ foo: 1, bar: 'two' })
+		end
+
+
+	end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,30 @@
+# -*- ruby -*-
+# frozen_string_literal: true
+
+require 'simplecov' if ENV['COVERAGE']
+
+require 'rspec'
+
+require 'loggability/spechelpers'
+
+
+### Mock with RSpec
+RSpec.configure do |config|
+	config.mock_with( :rspec ) do |mock|
+		mock.syntax = :expect
+	end
+
+	config.disable_monkey_patching!
+	config.example_status_persistence_file_path = "spec/.status"
+	config.filter_run :focus
+	config.filter_run_when_matching :focus
+	config.order = :random
+	config.profile_examples = 5
+	config.run_all_when_everything_filtered = true
+	config.shared_context_metadata_behavior = :apply_to_host_groups
+	# config.warnings = true
+
+	config.include( Loggability::SpecHelpers )
+end
+
+

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: presentability
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.20220807214309
+platform: ruby
+authors:
+- Michael Granger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-08-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: loggability
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: rake-deveiate
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+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.
+email:
+- ged@faeriemud.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- History.md
+- LICENSE.txt
+- README.md
+- lib/presentability.rb
+- lib/presentability/presenter.rb
+- spec/presentability_spec.rb
+- spec/spec_helper.rb
+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
+  source_uri: https://hg.sr.ht/~ged/Presentability
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Facade-based presenters with minimal assumptions.
+test_files: []