characterize 0.0.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 00e40cca8ad8624b4a6ab85ab521ecdb08f2f689
-  data.tar.gz: c791593bc4a01b224dfc37ee944417239b6e10a7
+SHA256:
+  metadata.gz: 44adb5a2de872bd288490c12dc5bc43863d8ab0805358a0d984c7fd442e2d0db
+  data.tar.gz: e2920b0dbf3c1b1ae06ee952db5ae73efced32699df8de0ec50ec95b18a1dc5d
 SHA512:
-  metadata.gz: e690b1251155f2cab4e14ae3a021efa95f68a99ad5ec2881032f7a3b774091b1eecdc45e1beb0ae6760d04a363781165ea6c683e72c68f117a6e824da2a5edf0
-  data.tar.gz: f1613c4bd503315e41676a77daa47fe76a32c0a4fc460cb79d973000dc58df6d33a972f78a3c9e1b6ba555fe01ff01fdf9f210758c04b92f98f2255d371bc797
+  metadata.gz: c5174f5ca1a9c641154b31af30a4ccee7ed5904bc111131c886626f0820ef7e63d72f1b8c1deb81a8d3fffa371e627188f0dfd486abe721bd2596e63805b4673
+  data.tar.gz: 160eefc0e291f6706bafc9c57fd6a61f99986a0c11322e3ec682048e0d8447365fe3c27dcbdb9b242a78abd0a9ec4253e44666d3ca660f0c032f7230741277a7

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 'Jim Gay'
+Copyright (c) 2014-2022 'Jim Gay'
 
 MIT License
 

data/README.md

@@ -1,6 +1,11 @@
 # Characterize
 
-Make your models behave in special ways.
+Make your models behave in special ways without wrapping them.
+
+Characterize is built on top of [Casting](https://github.com/saturnflyer/casting) and makes it easy to get going in Rails.
+
+[![Code Climate](https://codeclimate.com/github/saturnflyer/characterize.png)](https://codeclimate.com/github/saturnflyer/characterize)
+[![Gem Version](https://badge.fury.io/rb/characterize.png)](http://badge.fury.io/rb/characterize)
 
 ## Usage
 
@@ -13,6 +18,12 @@ class UsersController < ApplicationController
 end
 # the above sets a helper_method of 'user' and loads UserCharacter
 
+module UserCharacter
+  def special_behavior_available_in_the_view
+     # ...
+  end
+end
+
 class UsersController < ApplicationController
   def show
     characterize(user, display_module)
@@ -38,6 +49,83 @@ module StandardUser
 end
 ```
 
+Set special modules to be used for different actions:
+
+```ruby
+class UsersController < ApplicationController
+  characterize :user, show: [SpecialStuff, StandardStuff],
+                      edit: [EditingCharacter],
+                      default: [StandardStuff]
+
+  def show
+  end
+end
+```
+
+By default Characterize will look for modules that match the name of your object. So `characterize :user` would apply a `UserCharacter` module (and will blow up if it can't find it.) Or you can override it with the above configuration.
+
+You can also use it to characterize collections:
+
+```ruby
+class WidgetsController < ApplicationController
+  characterize_each :widgets, index: [SuperWidgetCharacter]
+
+  def index
+  end
+end
+```
+
+This will create a `widgets` helper method that will return a collection object where enumerable methods will cast the object as the provided modules.
+
+By default these methods will assume a loading method for your records but you can override this:
+
+```ruby
+class UsersController < ApplicationController
+  characterize :user # creates a `load_user` method
+  characterize :user, load_with: :get_a_user
+
+  def get_a_user
+    UserRepository.get(params[:user_id])
+  end
+end
+```
+
+## Altering the Settings
+
+### Module names
+
+Characterize will automatically look for modules using the "Character" suffix in it's name. But you can change this if you like.
+
+Just create an initializer which will change the setting when your Rails application boots:
+
+```ruby
+Characterize.module_suffix = 'Details'
+```
+
+With the above change, using `characterize :user` in your controller, it will attempt to load `UserDetails` instead of `UserCharacter`. This will apply for your *entire* application; if you only want to override the suffix in some places, just specify the module you want in your controller.
+
+### Creating your own standard features
+
+By default Characterize has some helpful features built in. You can use them like this:
+
+```ruby
+class UsersController < ApplicationController
+  characterize :user, show: [SpecialStuff].concat(Characterize.standard_features)
+
+  def show
+  end
+end
+```
+
+That will load the built-in features from Characterize. But you can change what is considered "standard" in your application.
+
+Set the `standard_features` option in your initializer to whatever you want:
+
+```ruby
+original_features = Characterize.standard_features
+Characterize.standard_features = [MyAwesomeStuff, ExtraDoodads].concat(original_features)
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -48,6 +136,10 @@ And then execute:
 
     $ bundle
 
+And finally
+
+    $ rails g characterize:install
+
 Or install it yourself as:
 
     $ gem install characterize

data/Rakefile

@@ -1,17 +1,18 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
-require 'rake/testtask'
+require "rake/testtask"
+require "reissue/gem"
+
+Reissue::Task.create :reissue do |task|
+  task.version_file = "lib/characterize/version.rb"
+  task.fragment = :git
+end
 
 Rake::TestTask.new do |t|
-  t.libs << 'test'
-  t.test_files = FileList['test/*_test.rb']
+  t.libs << "test"
+  t.test_files = FileList["test/*_test.rb"]
   t.ruby_opts = ["-w"]
   t.verbose = true
 end
 
-task :setup_db do |task|
-  system("cd test/internal && RAILS_ENV=test bundle exec rake db:reset")
-end
-Rake::Task[:test].enhance [:setup_db]
-
-task :default => :test
+task default: :test

data/lib/characterize/collection.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module Characterize
+  class Collection
+    extend Forwardable
+
+    class << self
+      def registry
+        @registry ||= {}
+      end
+
+      # Register a collection class to manage the given type
+      def register(klass, type)
+        registry[type] = klass
+      end
+
+      # Return an object handling the collection's type
+      #
+      # This will select the first matching class from which the collection's
+      # class inherits.
+      #
+      def for(collection, *behaviors)
+        klass = registry.find { |key, _value|
+          collection.class < key
+        }&.last || self
+        klass.new(collection, *behaviors)
+      end
+
+      def safe_command(*classes, receiver:)
+        standard = [:object_id, :__send__] +
+          Enumerator.instance_methods(false) +
+          Enumerable.instance_methods(false)
+
+        classes.each do |klass|
+          names = klass.instance_methods - standard - instance_methods(false)
+          command names => :collection
+        end
+      end
+    end
+
+    include Casting::Enum
+    def initialize(collection, *behaviors)
+      @behaviors = behaviors
+      reset_collection(collection)
+    end
+    attr :casted_enum, :collection, :behaviors
+
+    delegated_methods = (Enumerator.instance_methods(false) + Enumerable.instance_methods(false)).uniq - [:object_id, :inspect]
+    def_delegators :casted_enum, *delegated_methods
+
+    def inspect
+      %(#<#{self.class} #{object_id}>)
+    end
+
+    private
+
+    def reset_collection(collection)
+      @casted_enum = enum(collection, *behaviors)
+      @collection = collection
+    end
+  end
+end
+require "characterize/relation_collection"

data/lib/characterize/controller.rb

@@ -1,67 +1,122 @@
-require 'characterize/feature_controls'
+# frozen_string_literal: true
+
+require "characterize/feature_set"
 
 module Characterize
   module Controller
     def self.included(klass)
       klass.extend(::Characterize::ControllerMacros)
+      klass.helper_method(:characterize)
     end
-    
+
     private
 
+    # Apply character modules to the given object.
+    # This will use either the provided modules or if none are provided, the
+    # configured characters for the current controller action.
     def characterize(obj, *mods)
-      obj.__set_view__(view_context).cast_as(*mods)
+      object_name = obj.class.name.to_s.underscore
+      features = (!mods.empty?) ? mods : characters_for_action(object_name, action_name)
+      obj.__set_characterize_view__(view_context).cast_as(*features)
       obj
     end
 
     def characters_for_action(object_name, action_name)
-      if self.respond_to?("#{object_name}_#{action_name}_characters") && action_methods.include?(action_name.to_s)
-        Array(self.send("#{object_name}_#{action_name}_characters"))
-      else
-        self.send("default_#{object_name}_characters")
-      end
-    end
-
-    def self.view_features
-      [::Characterize::FeatureControls]
+      self.class.characterize_features.dig(object_name, action_name)
     end
   end
-  
+
   module ControllerMacros
-    
+    def self.attach_module(klass, name, &block)
+      mod = Module.new(&block)
+      klass.const_set(name, mod)
+      klass.include mod
+
+      mod
+    end
+
+    def characterize_features
+      @characterize_features ||= FeatureSet.new
+    end
+
     private
-    
-    def characterize(*options)
-      object_name = options.shift
-      actions_hash = options.last
-
-      object_constant_name = object_name.to_s.gsub(/(?:^|_)([a-z])/){ $1.upcase }.gsub('/','::')
-      default_characters = actions_hash.delete(:default) || ["::#{object_constant_name}Character"]
-
-      mod = Module.new
-      mod.module_eval %{
-        def #{object_name}
-          return @#{object_name} if defined?(@#{object_name})
-          @#{object_name} = characterize(load_#{object_name}, *characters_for_action(:#{object_name}, action_name))
-        end
-
-        def load_#{object_name}
-          #{object_constant_name}.find(params[:id])
-        end
-
-        def default_#{object_name}_characters
-          [#{default_characters.map(&:to_s).join(', ')}]
-        end
-      }
-      actions_hash.each_pair do |action_name, characters|
-        mod.module_eval %{
-          def #{object_name}_#{action_name}_characters
-            [#{characters.map(&:to_s).join(', ')}]
+
+    # Generate methods that will load and cast your object with the specified behaviors
+    def characterize(object_name, load_with: "load_#{object_name}", **actions_hash, &block)
+      characterize_features.add(object_name, **actions_hash)
+
+      mod = ControllerMacros.attach_module(
+        self,
+        "#{object_name.to_s.classify}ControllerMethods",
+        &block
+      )
+
+      unless method_defined?(load_with)
+        # def load_user
+        #   User.find(params[:id])
+        # end
+        mod.module_eval <<~MOD, __FILE__, __LINE__ + 1
+          def #{load_with}
+            #{object_name.to_s.classify}.find(params[:id])
+          end
+        MOD
+      end
+
+      unless method_defined?(object_name)
+        # def user
+        #   return @user if instance_variable_defined?(@user) && !@user.nil?
+        #
+        #   @user = characterize(load_user, *characters_for_action(:user, action_name))
+        # end
+        mod.module_eval <<~MOD, __FILE__, __LINE__ + 1
+          def #{object_name}
+            return @#{object_name} if defined?(@#{object_name})
+
+            @#{object_name} = characterize(#{load_with}, *characters_for_action(__method__, action_name))
           end
-        }
+        MOD
       end
-      self.const_set(object_constant_name + 'ControllerMethods', mod)
-      include mod
-      self.send(:helper_method, object_name)
+
+      send(:helper_method, object_name)
+    end
+
+    def characterize_each(name, load_with: "load_#{name}", **actions_hash, &block)
+      characterize_features.add(name, **actions_hash)
+
+      constant_name = name.to_s.singularize.classify
+      mod = ControllerMacros.attach_module(
+        self,
+        "#{constant_name}CollectionControllerMethods",
+        &block
+      )
+
+      unless method_defined?(load_with)
+        # def load_users
+        #   User.all
+        # end
+        mod.module_eval <<~MOD, __FILE__, __LINE__ + 1
+          def #{load_with}
+            #{constant_name}.all
+          end
+        MOD
+      end
+
+      unless method_defined?(name)
+        # def users
+        #   return @users if @users.is_a?(Characterize::Collection)
+        #
+        #   @users = Characterize::Collection.for(load_users, *characters_for_action(:users, action_name))
+        # end
+        mod.module_eval <<~MOD, __FILE__, __LINE__ + 1
+          def #{name}
+            return @#{name} if !@#{name}.nil? && @#{name}.is_a?(Characterize::Collection)
+
+            @#{name} = Characterize::Collection.for(#{load_with}, *characters_for_action(__method__, action_name))
+          end
+        MOD
+      end
+
+      send(:helper_method, name)
     end
   end
-end
+end

data/lib/characterize/feature_controls.rb

@@ -1,13 +1,12 @@
 module Characterize
   module FeatureControls
-    
     # Enumerate a collection with the given modules and block casting
     # each object with the modules and uncasting the object afterward.
     #
     # Examples:
     #
     #   def each_favorite(&block)
-    #     each_with_feature(favorites, FavoriteMod, &block)
+    #     each_with_features(favorites, FavoriteMod, &block)
     #   end
     #
     #   <%- user.each_favorite do |favorite| %>
@@ -15,69 +14,92 @@ module Characterize
     #   <%- end -%>
     #
     def each_with_features(collection, *mods, &block)
-      collection.lazy.each do |obj|
-        obj.cast_as(*mods)
-        block.call(obj)
-        obj.uncast(mods.size)
-      end
+      Casting::Enum.enum(collection, *mods).each(&block)
     end
-    
+
     # Conditionally render content for the object.
     #
     # Pass in a method name for content and either of:
     #  1. options for Rails' content_tag
     #  2. a block to render
     #
+    # The value of the method call will be yielded to the block
+    #
     # Examples:
     #
     #   <%= user.with(:favorites, :p, class: 'favorites-details') %>
-    #   <%- user.with(:favorites) do %>
+    #   <%- user.with(:favorites) do |favorites| %>
     #     <p class="favorites-details">
-    #       My Favorite Things: <%= user.favorites.join(', ') %>
+    #       My Favorite Things: <%= favorites.join(', ') %>
     #     </p>
     #   <%- end -%>
+    #   <%= user.with(:favorites, :p, class: "whatever", without: "Oops! No favorites!")
     #
-    def with(method_name, *tag_name_or_options)
-      value = self.public_send(method_name)
-      if with_conditions(method_name, value)
-        if block_given?
-          yield
+    def with(method_name, tag_name = nil, **options, &block)
+      without_option = options.delete(:without)
+      method_value = public_send(method_name)
+
+      display_value = method_value.then do |method_value|
+        if with_conditions(method_name, method_value)
+          method_value
         else
-          tag_name, options = *tag_name_or_options
-          view.content_tag(tag_name, value, options)
+          without_option
         end
+      end
+
+      capture_content = block || ->(_method_value = nil) do
+        __view__.concat(__view__.content_tag(tag_name, display_value, options))
+      end
+
+      if block
+        __view__.capture { capture_content.call(method_value) }
       else
-        without_option = tag_name_or_options.last.fetch(:without){ '' }
-        if without_option.respond_to?(:call)
-          without(method_name, &without_option)
-        else
-          view.concat(without_option)
-        end
+        __view__.capture { capture_content.call }
       end
     end
-    
+
     # Conditionally render content for the object when the attribute is NOT present.
     #
     # Pass in a method name and a block to render.
     #
+    # The value of the method call will be yielded to the block
+    #
     # Examples:
     #
-    #   <%- user.without(:favorites) do %>
+    #   <%- user.without(:favorites) do |favorites| %>
     #     <p class="favorites-details none">
-    #       There are no favorites here.
+    #       There are no favorites here. You had <%= favorites %>
     #     </p>
     #   <%- end -%>
+    #   <% user.without(:favorites, :p, value: 'No favorites!')
+    #   <% user.without(:favorites, :p, value: "You should have favorites", with: "You DO have favorites!")
     #
-    def without(method_name, &block)
-      value = self.public_send(method_name)
-      if !with_conditions(method_name, value)
-        yield
+    def without(method_name, tag_name = nil, value: nil, **options, &block)
+      with_option = options.delete(:with)
+      method_value = public_send(method_name)
+
+      display_value = method_value.then do |method_value|
+        if with_conditions(method_name, method_value)
+          with_option
+        else
+          value
+        end
+      end
+
+      capture_content = (block || ->(_method_value = nil) do
+        __view__.concat(__view__.content_tag(tag_name, display_value, options))
+      end)
+
+      if block
+        __view__.capture { capture_content.call(method_value) }
+      else
+        __view__.capture { capture_content.call }
       end
     end
-    
+
     # Used to override behavior of with for the case of special attributes
-    def with_conditions(method_name, computed_value)
-      !computed_value.nil? && computed_value != '' && computed_value != false
+    def with_conditions(_method_name, computed_value)
+      !computed_value.nil? && computed_value != "" && computed_value != false
     end
   end
-end
+end

data/lib/characterize/feature_set.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "characterize/object_set"
+
+module Characterize
+  class FeatureSet
+    def initialize
+      @object_rules = {}
+    end
+
+    def add(object_name, **actions_hash)
+      @object_rules[object_name] = ObjectSet.new(object_name, **actions_hash)
+    end
+
+    def dig(*args)
+      @object_rules.dig(*args)
+    end
+  end
+end

data/lib/characterize/object_set.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Characterize
+  class ObjectSet
+    def initialize(object_name, **hash)
+      @object_name = object_name
+      @hash = hash
+    end
+    attr :object_name
+
+    def dig(action_name, *_ignored)
+      if @hash.key?(action_name.to_sym)
+        Array(defaults + action_characters(action_name)).compact
+      else
+        defaults
+      end
+    end
+
+    def object_class_name
+      @object_name.to_s.classify
+    end
+
+    def object_character_name
+      "#{object_class_name}#{Characterize.module_suffix}"
+    end
+
+    def object_character
+      return @object_character if defined?(@object_character)
+      @object_character = begin
+        Object.const_get(object_character_name)
+      rescue
+        nil
+      end
+    end
+
+    def defaults
+      Array(
+        Characterize.standard_features + @hash.fetch(:default, []) + [object_character]
+      ).flatten.compact.uniq
+    end
+
+    def action_object_character_name(action_name)
+      "#{action_name.to_s.classify}#{object_character_name}"
+    end
+
+    def action_character(action_name)
+      Object.const_get(action_object_character_name(action_name))
+    rescue
+      nil
+    end
+
+    def action_characters(action_name)
+      Array(@hash.fetch(action_name.to_sym, [action_character(action_name)])).compact
+    end
+  end
+end

data/lib/characterize/railtie.rb

@@ -1,25 +1,23 @@
-require "rails"
 module Characterize
   class Railtie < ::Rails::Railtie
-
     config.after_initialize do |app|
-      app.config.paths.add 'app/characters', eager_load: true
+      app.config.paths.add "app/characters", eager_load: true
     end
 
     if defined?(ActiveRecord)
-      initializer 'characterize.active_record' do |app|
+      initializer "characterize.active_record" do |app|
         ActiveRecord::Base.send(:include, Characterize)
       end
     end
 
     if defined?(Mongoid)
-      initializer 'characterize.mongoid' do |app|
+      initializer "characterize.mongoid" do |app|
         Mongoid::Document.send(:include, Characterize)
       end
     end
 
-    initializer 'characterize.action_controller' do |app|
+    initializer "characterize.action_controller" do |app|
       ActionController::Base.send(:include, Characterize::Controller)
     end
   end
-end
+end

data/lib/characterize/relation_collection.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "direction"
+
+module Characterize
+  class RelationCollection < Collection
+    Collection.register(self, ActiveRecord::Relation)
+    extend Direction
+
+    # Defined before safe_command/query so these names are excluded from the
+    # auto-generated delegators (see Collection.safe_command) rather than
+    # redefining them.
+    def not(...)
+      reset_collection collection.where.not(...)
+      self
+    end
+
+    def limit(...)
+      reset_collection collection.limit(...)
+      self
+    end
+
+    def offset(...)
+      reset_collection collection.offset(...)
+      self
+    end
+
+    safe_command ActiveRecord::QueryMethods, receiver: :collection
+    query ActiveRecord::Calculations.instance_methods => :collection
+  end
+end

data/lib/characterize/version.rb

@@ -1,3 +1,3 @@
 module Characterize
-  VERSION = "0.0.2"
+  VERSION = "0.2.0"
 end