directive 0.22.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1edf4b07fc8b982911d978b267df2c336f4b0dba62dad286c80ae44a3b280215
+  data.tar.gz: 7c1ae7fb109c9ff8261a6f8fda3b4fd15c7eda5682243fe8500ef0a7e75dc9b5
+SHA512:
+  metadata.gz: a907b40c95e58500e348cec77ebf864d2e3896ee13edcbe162c01d2b109964db5e056017f3abc9196b5e107c55f9dc374e2753d9e6e32749907a715ebc455ad1
+  data.tar.gz: 6cd58b199249b11d00fe6b052d01ac0de6b74f8d879043364b8d2ac9cfce948fdb29d016e6ba27106bc27574d848e3d7572e3386f8e48afb33e8435639b72f1c

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Allen Rettberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,39 @@
+# Directive
+
+Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/directive`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+TODO: Delete this and the text above, and describe your gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'directive'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install directive
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/directive.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/directive.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative "directive/config_builder"
+require_relative "directive/config_delegation"
+require_relative "directive/config_object"
+require_relative "directive/evaluator"
+require_relative "directive/reader"
+
+# NOTE: This is still a pre-release feature! Use at your own risk - it may change before being released.
+#
+# A utility for creating read-only gem configuration singletons.
+#
+# Usage:
+#   # In your gem:
+#   module SomeGem
+#     module Configuration
+#       extend Directive
+#
+#       configuration_options do
+#         option :some_config_option
+#         option :some_option_with_a_default, default: "I probably know what's best"
+#
+#         nested :whats_behind do
+#           option :door_one, default: "It's a goat"
+#           option :door_two, default: "Another goat"
+#           option :door_three, default: "It's a car!"
+#         end
+#       end
+#     end
+#   end
+#
+#   # Then, in the application using the gem:
+#   SomeGem::Configuration.configure do |config|
+#     config.some_config_option = 12345
+#     config.some_option_with_a_default = "Nope, you really don't"
+#
+#     config.whats_behind do |nested|
+#       nested.door_one = "It's a boat!"
+#       nested.door_three = "The teletubbies on repeat 😱"
+#     end
+#   end
+#
+#   # Then, back in your gem code:
+#   puts Configuration.config.some_config_option
+#   => 12345
+#   puts Configuration.config.whats_behind.door_one
+#   => "It's a boat!"
+#
+#   # Or, if you want to select dynamically:
+#   doors = %i[door_one door_two door_three]
+#   Configuration.config.config_eval(whats_behind, doors.sample).read
+#   => "The teletubbies on repeat 😱"
+module Directive
+  delegate :configure, :config_eval, to: :_config_builder
+
+  # @return [Directive::ConfigReader] A read-only object containing configuration options set inside {#configure}
+  def config
+    _config_builder.reader
+  end
+
+  # Run a callback before the configure block is evaluated.
+  #
+  # Note: if configure is called multiple times for your gem, this block will get run each time!
+  #
+  def before_configure(&block)
+    _config_builder_class.set_callback(:configure, :before, &block)
+  end
+
+  # Run a callback after the configure block is evaluated.
+  #
+  # Note: if configure is called multiple times for your gem, this block will get run each time!
+  #
+  def after_configure(&block)
+    _config_builder_class.set_callback(:configure, :after, &block)
+  end
+
+  private
+
+  def configuration_options(&block)
+    _config_builder.instance_exec(&block)
+  end
+
+  def _config_builder
+    @_config_builder ||= _config_builder_class.new
+  end
+
+  def _config_builder_class
+    @_config_builder_class ||= Class.new(ConfigBuilder).tap do |klass|
+      const_set(:ConfigBuilder, klass)
+    end
+  end
+end

data/lib/directive/config_builder.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "technologic"
+require "active_support/callbacks"
+
+require_relative "config_builder/double_configure"
+
+module Directive
+  class ConfigBuilder
+    include ActiveSupport::Callbacks
+    define_callbacks :configure
+
+    # This concern uses the configure callback, so it needs to be included after the callback is defined
+    include DoubleConfigure
+
+    delegate :config_eval, to: :reader
+
+    def reader
+      @reader ||= Reader.new(configuration)
+    end
+
+    def configure
+      run_callbacks :configure do
+        mutex.synchronize do
+          yield configuration
+        end
+      end
+    end
+
+    # NOTE: options must be set up before {#configure} is called
+    def option(*args, &block)
+      config_class.__send__(:option, *args, &block)
+    end
+
+    def nested(*args, &block)
+      config_class.__send__(:nested, *args, &block)
+    end
+
+    private
+
+    attr_writer :configure_called
+
+    def configuration
+      config_class.instance
+    end
+
+    def config_class
+      @config_class ||= Class.new(ConfigObject)
+    end
+
+    def mutex
+      @mutex = Mutex.new
+    end
+  end
+end

data/lib/directive/config_builder/double_configure.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "technologic"
+
+module Directive
+  module DoubleConfigure
+    extend ActiveSupport::Concern
+
+    include Technologic
+
+    included do
+      set_callback :configure, :after, :warn_on_multiple_configure_calls
+    end
+
+    private
+
+    def configure_called?
+      @configure_called
+    end
+
+    def warn_on_multiple_configure_calls
+      unless configure_called?
+        @configure_called = true
+        return
+      end
+
+      puts <<~WARNING
+        #{self.class._configurable_module_name}.configure has been called more than once, which can lead to unexpected consequences.
+        For the most predictable behavior, configure should only be called once.
+      WARNING
+    end
+
+    module ClassMethods
+      def _configurable_module_name
+        name.gsub("::#{name.demodulize}", "")
+      end
+    end
+  end
+end

data/lib/directive/config_delegation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Directive
+  module ConfigDelegation
+    extend ActiveSupport::Concern
+
+    DEFAULT_CONFIGURATION_MODULE_NAME = "Configuration"
+
+    module ClassMethods
+      delegate :config, :configure, to: :_configuration_module
+
+      private
+
+      # Sets up delegation from a top-level class to a nested Configuration module.
+      #
+      # @example
+      #   class SomeClass
+      #     include Spicerack::Configurable::ConfigDelegation
+      #
+      #     delegates_to_configuration
+      #   end
+      #
+      #   module SomeClass::Configuration
+      #     include Spicerack::Configurable
+      #   end
+      #
+      #   SomeClass.config
+      #   => returns SomeClass::Configuration.config
+      #   SomeClass.configure do { |config| # config is the yielded config object from SomeClass::Configuration.configure }
+      #
+      # @param config_class [Spicerack::Configurable] A module that extends Spicerack::Configurable. Defaults to the module +YourGem::Configuration+
+      def delegates_to_configuration(config_class = nil)
+        @_configuration_module = config_class || "#{self}::#{DEFAULT_CONFIGURATION_MODULE_NAME}".constantize
+      end
+
+      def _configuration_module
+        raise NoMethodError, "Configuration not set up for #{self}. Did you forget to call delegates_to_configuration?" if @_configuration_module.nil?
+
+        @_configuration_module
+      end
+    end
+  end
+end

data/lib/directive/config_object.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Directive
+  class ConfigObject < Spicerack::InputObject
+    include Singleton
+    include ActiveModel::AttributeAssignment
+
+    alias_method :assign, :assign_attributes
+
+    RESERVED_WORDS = %i[config_eval].freeze
+
+    class_attribute :_nested_options, instance_writer: false, default: []
+    class_attribute :_nested_builders, instance_writer: false, default: {}
+
+    class << self
+      private
+
+      def option(name, *)
+        _ensure_safe_option_name(name)
+
+        super
+      end
+
+      def nested(namespace, &block)
+        _ensure_safe_option_name(namespace)
+
+        nested_config_builder_for(namespace).tap do |builder|
+          builder.instance_exec(&block)
+
+          _nested_options << namespace.to_sym
+          define_method(namespace) do |&nested_configure_block|
+            builder.__send__(:configuration).tap do |nested_config|
+              nested_configure_block.call(nested_config) if nested_configure_block.respond_to?(:call)
+            end
+          end
+        end
+      end
+
+      def nested_config_builder_for(namespace)
+        _nested_builders[namespace.to_sym] ||= ConfigBuilder.new
+      end
+
+      def _ensure_safe_option_name(name)
+        raise ArgumentError, "#{name.inspect} is reserved and cannot be used at a config option" if name.to_sym.in? RESERVED_WORDS
+        raise ArgumentError, "#{name.inspect} is already in use" if _nested_options.include?(name.to_sym)
+
+        puts "Warning: the config option #{name} is already defined" if _options.include?(name.to_sym) # rubocop:disable Rails/Output
+      end
+
+      def inherited(base)
+        base._nested_options = _nested_options.dup
+        base._nested_builders = _nested_builders.dup
+        super
+      end
+    end
+
+    def inspect
+      "#<#{self.class.superclass} #{super}>"
+    end
+  end
+end

data/lib/directive/evaluator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Directive
+  class Evaluator
+    # @param path [Array<Symbol, String>] A message path for the desired config
+    # @param configuration [Spicerack::Configurable::Reader]
+    def initialize(path, configuration)
+      @path = path
+      @configuration = configuration
+    end
+
+    def read
+      path.inject(configuration, &:public_send)
+    end
+
+    private
+
+    attr_reader :path, :configuration
+  end
+end

data/lib/directive/reader.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Directive
+  class Reader
+    include Tablesalt::StringableObject
+
+    def initialize(config)
+      @config = config
+    end
+
+    def config_eval(*path)
+      Evaluator.new(path, self)
+    end
+
+    private
+
+    attr_reader :config
+
+    def method_missing(method_name, *)
+      name = method_name.to_sym
+
+      return mutex.synchronize { config.public_send(name) } if config._options.map(&:to_sym).include?(name)
+      return config._nested_builders[name].reader if config._nested_builders.key?(name)
+
+      super
+    end
+
+    def respond_to_missing?(method_name, *)
+      name = method_name.to_sym
+
+      config._options.map(&:to_sym).include?(name) ||
+        config._nested_builders.key?(name) ||
+        super
+    end
+
+    def mutex
+      @mutex ||= Mutex.new
+    end
+
+    def stringable_attributes
+      config._options + config._nested_options
+    end
+  end
+end

data/lib/directive/spec_helper.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "spec_helper/matchers"
+require_relative "spec_helper/dsl"
+
+RSpec.configure do |config|
+  config.include(Directive::SpecHelper::Matchers::Global)
+  config.include(Directive::SpecHelper::Matchers::Configuration, type: :configuration)
+  config.include(Directive::SpecHelper::DSL, type: :configuration)
+end

data/lib/directive/spec_helper/dsl.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "matchers"
+
+module Directive
+  module SpecHelper
+    module DSL
+      def nested_config_option(config_name, &block)
+        in_nested_config_stack(config_name) do |nested_stack|
+          describe(config_name.to_s, caller: caller) do
+            subject { nested_config }
+
+            let(:parent_config) { parent_config_for_nested(nested_stack) }
+            let(:nested_config) { parent_config.public_send(nested_stack.last) }
+
+            it "defines nested config object #{config_name}" do
+              expect(parent_config).to respond_to config_name
+              expect(parent_config._nested_options).to include config_name.to_sym
+              expect(parent_config.public_send(config_name)).to be_a Spicerack::Configurable::ConfigObject
+            end
+
+            instance_eval(&block)
+          end
+        end
+      end
+
+      def self.included(base)
+        base.extend DSL
+        super
+      end
+
+      private
+
+      def parent_config_for_nested(nested_stack)
+        @parent_config ||= {}
+
+        @parent_config[nested_stack] ||= described_class.
+          __send__(:_config_builder).
+          __send__(:configuration).
+          yield_self do |config|
+            nested_stack[0..-2].inject(config) do |conf, nested_name|
+              conf.public_send(nested_name)
+            end
+          end
+      end
+
+      def in_nested_config_stack(name)
+        _nested_config_stack << name.to_sym
+
+        yield _nested_config_stack.dup
+
+        _nested_config_stack.pop
+      end
+
+      def _nested_config_stack
+        Thread.current[:nested_config_stack] ||= []
+      end
+    end
+  end
+end

data/lib/directive/spec_helper/matchers.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Directive
+  module SpecHelper
+    module Matchers
+      module Configuration
+        extend ::RSpec::Matchers::DSL
+      end
+
+      module Global
+        extend ::RSpec::Matchers::DSL
+      end
+    end
+  end
+end
+
+require_relative "matchers/configuration/define_config_option"
+require_relative "matchers/global/delegate_config_to"

data/lib/directive/spec_helper/matchers/configuration/define_config_option.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Directive
+  module SpecHelper
+    module Matchers
+      module Configuration
+        # RSpec matcher to test options of a Configurable class
+        #
+        #     class ExampleConfiguration
+        #       include Spicerack::Configurable
+        #
+        #       option :foo
+        #       option :bar, default: :baz
+        #     end
+        #
+        #     RSpec.describe ExampleConfiguration, type: :configuration do
+        #       subject { described_class.new }
+        #
+        #       it { is_expected.to define_config_option :foo }
+        #       it { is_expected.to define_config_option :bar, default: :baz }
+        #     end
+        define :define_config_option do |option, default: nil|
+          description { "define config option #{option.inspect}" }
+          failure_message { "expected #{@obj} to define config option #{option.inspect} with default #{default.inspect}" }
+
+          match do |obj|
+            @obj = obj
+
+            if obj.is_a? Spicerack::Configurable::ConfigObject
+              expect(obj).to define_option option, default: default
+            else
+              expect(obj).to respond_to :config
+              expect(obj.config.instance_variable_get(:@config)).to be_present
+              expect(obj.config.instance_variable_get(:@config)).to define_option option, default: default
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/directive/spec_helper/matchers/global/delegate_config_to.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Directive
+  module SpecHelper
+    module Matchers
+      module Global
+        # RSpec matcher to test options of a Configurable class
+        #
+        #     module MyGem
+        #       include Spicerack::Configurable::ConfigDelegation
+        #       delegates_to_configuration
+        #
+        #       class MyGem::Configuration
+        #         include Spicerack::Configurable
+        #         ...
+        #       end
+        #     end
+        #
+        #     RSpec.describe ExampleConfiguration, type: :configuration do
+        #       subject { described_class }
+        #
+        #       it { is_expected.to delegate_config_to MyGem::Configuration }
+        #     end
+        define :delegate_config_to do |config_module|
+          attr_reader :obj, :config_module
+
+          description { "delegates configuration methods to #{config_module}" }
+
+          failure_message { "expected #{target} to delegate configuration methods to #{config_module}" }
+          failure_message_when_negated { "expected #{target} not to delegate configuration methods to #{config_module}" }
+
+          match_unless_raises do |obj|
+            @obj = obj
+            @config_module = config_module
+
+            stub_configuration_methods
+
+            expect(target.config).to eq config_return_value
+            expect(target.configure).to eq configure_return_value
+          end
+
+          def target
+            obj.is_a?(Module) ? obj : obj.class
+          end
+
+          def stub_configuration_methods
+            allow(config_module).to receive(:config).and_return(config_return_value)
+            allow(config_module).to receive(:configure).and_return(configure_return_value)
+          end
+
+          def config_return_value
+            @config_return_value ||= double
+          end
+
+          def configure_return_value
+            @configure_return_value ||= double
+          end
+        end
+      end
+    end
+  end
+end

data/lib/directive/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Directive
+  # This constant is managed by spicerack
+  VERSION = "0.22.0"
+end

metadata

@@ -0,0 +1,179 @@
+--- !ruby/object:Gem::Specification
+name: directive
+version: !ruby/object:Gem::Version
+  version: 0.22.0
+platform: ruby
+authors:
+- Allen Rettberg
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.1
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.8'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0
+- !ruby/object:Gem::Dependency
+  name: pry-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.4
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.4
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: shoulda-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 4.0.1
+description: An easy, self-documenting gem configuration framework
+email:
+- allen.rettberg@freshly.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/directive.rb
+- lib/directive/config_builder.rb
+- lib/directive/config_builder/double_configure.rb
+- lib/directive/config_delegation.rb
+- lib/directive/config_object.rb
+- lib/directive/evaluator.rb
+- lib/directive/reader.rb
+- lib/directive/spec_helper.rb
+- lib/directive/spec_helper/dsl.rb
+- lib/directive/spec_helper/matchers.rb
+- lib/directive/spec_helper/matchers/configuration/define_config_option.rb
+- lib/directive/spec_helper/matchers/global/delegate_config_to.rb
+- lib/directive/version.rb
+homepage: https://github.com/Freshly/spicerack/tree/master/directive
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Freshly/spicerack/tree/master/directive
+  source_code_uri: https://github.com/Freshly/spicerack/blob/master/directive
+  changelog_uri: https://github.com/Freshly/spicerack/blob/master/directive/CHANGELOG.md
+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: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Gem configuration made simple
+test_files: []