pakyow-support 0.11.3 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 0b9187d1b88df074e68ff932f8fe11dc9dcc004f
-  data.tar.gz: 80b3d17712390927a743c3ed0db621b89089cc69
+SHA256:
+  metadata.gz: 7f55f83e04891fdd69aaafe9d59ab21d250cd6fcdc37aa2fbfcb0a8eaad576be
+  data.tar.gz: 980a9b0005d1f5432b995974c3065c4ab2a9484d7ad42c0d7cb2f4b10a3e655d
 SHA512:
-  metadata.gz: 1ccdcd7d1049dab1831833765ea44cb76790b033660a47de5f2ff79bbe9dee409a11a577cf0a178673e4a522b942d086c937558d086923d472dc426b28e9ee11
-  data.tar.gz: a692eb81c1cb1b5b9488f7e90179c2b402df348ec4bc1495be0649959b384365ef525e06347b44e8990da6d08512e87e9cb342ae9bb0b2f4a5feb9459e8a99aa
+  metadata.gz: 6563a073ab30d40996accbae5e9aa5f8f4dcd6adb3a63b02dc38ffbd51a604aaccc0608d82edc7dd74571fd7b6c44b580c29c70dffc1171249cecabf9f9936f6
+  data.tar.gz: 30c696d99b2afa619298d7ea5bac825442f9578ed738c3180d4973f94058d0bf6033b3341cc5a476da2ec65071ddda0436b39bd40c32d2440d6c17649aa9de36

data/{pakyow-support/CHANGELOG.md → CHANGELOG.md}

@@ -1,3 +1,7 @@
+# 1.0.0
+
+  * ADDED `Hookable` module
+
 # 0.11.0
 
   * Moves everything into the Pakyow namespace

data/LICENSE

@@ -0,0 +1,4 @@
+Copyright (c) Metabahn, LLC
+
+Pakyow Support is an open-source project licensed under the terms of the LGPLv3 license.
+See <https://choosealicense.com/licenses/lgpl-3.0/> for license text.

data/{pakyow-support/README.md → README.md}

@@ -16,8 +16,7 @@ Source code can be downloaded as part of the Pakyow project on Github:
 
 # License
 
-Pakyow Support is released free and open-source under the [MIT
-License](http://opensource.org/licenses/MIT).
+Pakyow Support is free and open-source under the [LGPLv3 license](https://choosealicense.com/licenses/lgpl-3.0/).
 
 # Support
 

data/lib/pakyow/support/aargv.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "pakyow/support/core_refinements/array/ensurable"
+
+module Pakyow
+  module Support
+    class Aargv
+      using Refinements::Array::Ensurable
+
+      def self.normalize(args, opts)
+        Hash[opts.map { |opt_name, opt_types|
+          [opt_name, value_of_type(args, Array.ensure(opt_types))]
+        }.reject { |pair| pair[1].nil? }]
+      end
+
+      def self.value_of_type(values, types)
+        if match = values.find { |value| types.find { |type| value.is_a?(type) } }
+          values.delete(match)
+        else
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/bindable.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Support
+    # Makes an object bindable.
+    #
+    module Bindable
+      def include?(key)
+        respond_to?(key.to_s.to_sym)
+      end
+
+      def [](key)
+        if include?(key)
+          public_send(key.to_s.to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/class_state.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "pakyow/support/deep_dup"
+
+module Pakyow
+  module Support
+    module ClassState
+      using DeepDup
+
+      def class_state(name, default: nil, inheritable: false, getter: true)
+        ivar = :"@#{name}"
+        @__class_state[ivar] = {
+          default: default,
+          inheritable: inheritable
+        }
+
+        instance_variable_set(ivar, default.deep_dup)
+
+        if getter
+          define_singleton_method name do
+            instance_variable_get(ivar)
+          end
+        end
+      end
+
+      def self.extended(base)
+        unless base.instance_variable_defined?(:@__class_state)
+          base.instance_variable_set(:@__class_state, {})
+        end
+      end
+
+      def inherited(subclass)
+        subclass.instance_variable_set(:@__class_state, @__class_state.deep_dup)
+
+        @__class_state.each do |ivar, options|
+          if options[:inheritable]
+            subclass.instance_variable_set(ivar, instance_variable_get(ivar).deep_dup)
+          elsif @__class_state[ivar][:default]
+            subclass.instance_variable_set(ivar, @__class_state[ivar][:default].deep_dup)
+          else
+            subclass.instance_variable_set(ivar, nil)
+          end
+        end
+
+        super
+      end
+    end
+  end
+end

data/lib/pakyow/support/cli/runner.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "tty-command"
+require "tty-spinner"
+
+require "pakyow/support/cli/style"
+
+module Pakyow
+  module Support
+    # Runs a command, or block of code, with consistent command-line messaging.
+    #
+    module CLI
+      class Runner
+        SPINNER = :dots
+        FAILURE_MARK = "✕"
+        SUCCESS_MARK = "✓"
+        FAILURE_MESSAGE = "failed"
+        SUCCESS_MESSAGE = ""
+
+        def initialize(message:)
+          @spinner = TTY::Spinner.new(
+            Support::CLI.style.bold(":spinner #{message}"),
+            format: SPINNER,
+            success_mark: SUCCESS_MARK,
+            error_mark: FAILURE_MARK
+          )
+
+          @succeeded = @failed = false
+        end
+
+        # Runs a command or block of code. If a value for `command` is passed with
+        # the block, the result will be yielded to the block on success.
+        #
+        def run(*command)
+          @spinner.auto_spin
+
+          if command.empty? && block_given?
+            yield self
+            succeeded
+          else
+            result = TTY::Command.new(printer: :null, pty: true).run!(*command)
+
+            if result.failure?
+              failed(result.err)
+            else
+              succeeded
+
+              if block_given?
+                yield result
+              end
+            end
+          end
+        end
+
+        # Called when the command succeeds.
+        #
+        def succeeded(output = "")
+          unless completed?
+            @succeeded = true
+            @spinner.success(Support::CLI.style.green(SUCCESS_MESSAGE))
+            puts indent_output(output) unless output.empty?
+          end
+        end
+
+        # Called when the command fails.
+        #
+        def failed(output = "")
+          unless completed?
+            @failed = true
+            @spinner.error(Support::CLI.style.red(FAILURE_MESSAGE))
+            puts indent_output(output) unless output.empty?
+          end
+        end
+
+        # Returns `true` if the command has completed.
+        #
+        def completed?
+          succeeded? || failed?
+        end
+
+        # Returns `true` if the command has completed successfully.
+        #
+        def succeeded?
+          @succeeded == true
+        end
+
+        # Returns `true` if the command has completed unsuccessfully.
+        #
+        def failed?
+          @failed == true
+        end
+
+        private
+
+        ANSI_REGEX = /\x1B\[[0-9;]*[a-zA-Z]/
+
+        def indent_output(output)
+          output.split("\n").map { |line|
+            first_real_string = line.split(ANSI_REGEX).reject(&:empty?).first
+            line.sub(first_real_string.to_s, "   #{first_real_string}")
+          }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/cli/style.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "pastel"
+
+module Pakyow
+  module Support
+    module CLI
+      def self.style
+        @style ||= Pastel.new
+      end
+    end
+  end
+end

data/lib/pakyow/support/configurable/config.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "concurrent/hash"
+
+require "pakyow/support/deep_dup"
+require "pakyow/support/deep_freeze"
+
+require "pakyow/support/configurable/setting"
+
+module Pakyow
+  module Support
+    module Configurable
+      # @api private
+      class Config
+        using DeepDup
+
+        extend DeepFreeze
+        unfreezable :configurable
+
+        # @api private
+        attr_reader :__settings, :__defaults, :__groups
+
+        def initialize(configurable)
+          @configurable = configurable
+
+          @__settings = Concurrent::Hash.new
+          @__defaults = Concurrent::Hash.new
+          @__groups   = Concurrent::Hash.new
+        end
+
+        def initialize_copy(_)
+          @__defaults = @__defaults.deep_dup
+          @__settings = @__settings.deep_dup
+          @__groups   = @__groups.deep_dup
+
+          @__settings.each do |key, _|
+            define_setting_methods(key)
+          end
+
+          @__groups.each do |key, _|
+            define_group_methods(key)
+          end
+
+          super
+        end
+
+        def setting(name, default = default_omitted = true, &block)
+          tap do
+            name = name.to_sym
+            default = nil if default_omitted
+
+            unless @__settings.include?(name)
+              define_setting_methods(name)
+            end
+
+            @__settings[name] = Setting.new(default: default, configurable: @configurable, &block)
+          end
+        end
+
+        def defaults(environment, &block)
+          @__defaults[environment] = block
+        end
+
+        def configurable(group, &block)
+          group = group.to_sym
+          config = Config.new(@configurable)
+          config.instance_eval(&block)
+
+          unless @__groups.include?(group)
+            define_group_methods(group)
+          end
+
+          @__groups[group] = config
+        end
+
+        def configure_defaults!(configured_environment)
+          if defaults = @__defaults[configured_environment.to_s.to_sym]
+            instance_eval(&defaults)
+          end
+
+          @__groups.values.each do |group|
+            group.configure_defaults!(configured_environment)
+          end
+        end
+
+        def update_configurable(configurable)
+          @configurable = configurable
+
+          @__settings.values.each do |setting|
+            setting.update_configurable(configurable)
+          end
+
+          @__groups.values.each do |group|
+            group.update_configurable(configurable)
+          end
+        end
+
+        def to_h
+          hash = {}
+
+          @__settings.each_with_object(hash) { |(name, setting), h|
+            h[name] = setting.value
+          }
+
+          @__groups.each_with_object(hash) { |(name, group), h|
+            h[name] = group.to_h
+          }
+
+          hash
+        end
+
+        def eval(setting, context)
+          value = public_send(setting)
+          if value.is_a?(Proc)
+            context.instance_eval(&value)
+          else
+            value
+          end
+        end
+
+        private
+
+        def find_setting(name)
+          @__settings[name.to_sym]
+        end
+
+        def find_group(name)
+          @__groups[name.to_sym]
+        end
+
+        def define_setting_methods(name)
+          singleton_class.define_method name do |&block|
+            if block
+              find_setting(name).set(block)
+            else
+              find_setting(name).value
+            end
+          end
+
+          singleton_class.define_method :"#{name}=" do |value|
+            find_setting(name).set(value)
+          end
+        end
+
+        def define_group_methods(name)
+          singleton_class.define_method name do
+            find_group(name)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/configurable/setting.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "pakyow/support/deep_dup"
+require "pakyow/support/deep_freeze"
+
+module Pakyow
+  module Support
+    module Configurable
+      # @api private
+      class Setting
+        using DeepDup
+
+        extend DeepFreeze
+        unfreezable :configurable, :value
+
+        def initialize(default:, configurable:, &block)
+          @default, @block, @configurable = default, block, configurable
+        end
+
+        def initialize_copy(_)
+          @default = @default.deep_dup
+          super
+        end
+
+        def freeze
+          value
+          super
+        end
+
+        def set(value)
+          @value = value
+        end
+
+        def value
+          if instance_variable_defined?(:@value)
+            @value
+          else
+            @value = if @block
+              @configurable.instance_eval(&@block)
+            else
+              @default
+            end
+          end
+        end
+
+        def update_configurable(configurable)
+          @configurable = configurable
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/configurable.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "concurrent/hash"
+
+require "pakyow/support/class_state"
+
+require "pakyow/support/configurable/config"
+
+module Pakyow
+  module Support
+    # Makes an object configurable.
+    #
+    #   class ConfigurableObject
+    #     include Configurable
+    #
+    #     setting :foo, "default"
+    #     setting :bar
+    #
+    #     defaults :development do
+    #       setting :bar, "bar"
+    #     end
+    #   end
+    #
+    #   class ConfigurableSubclass < ConfigurableObject
+    #     configure :development do
+    #       config.foo = "development"
+    #     end
+    #
+    #     configure :production do
+    #       config.foo = "production"
+    #     end
+    #   end
+    #
+    #   instance = ConfigurableSubclass.new
+    #   instance.configure! :development
+    #
+    #   instance.config.foo
+    #   # => "development"
+    #   instance.config.bar
+    #   # => "bar"
+    #
+    module Configurable
+      # @api private
+      def self.included(base)
+        base.extend ClassState
+        base.class_state :__config, default: Config.new(base), inheritable: true
+        base.class_state :__config_environments, default: Concurrent::Hash.new, inheritable: true
+
+        base.prepend Initializer
+        base.include CommonMethods
+        base.extend  ClassMethods, CommonMethods
+      end
+
+      private def __config_environments
+        self.class.__config_environments
+      end
+
+      module Initializer
+        # @api private
+        def initialize(*)
+          @__config = self.class.__config.dup
+          @__config.update_configurable(self)
+          super
+        end
+      end
+
+      module ClassMethods
+        # Define configuration to be applied when configuring for an environment.
+        #
+        def configure(environment = :__global, &block)
+          @__config_environments[environment] = block
+        end
+
+        # @api private
+        def inherited(subclass)
+          super
+          subclass.config.update_configurable(subclass)
+        end
+      end
+
+      module CommonMethods
+        extend Forwardable
+        def_delegators :@__config, :setting, :defaults, :configurable
+
+        def config
+          @__config
+        end
+
+        # Configures the object for an environment.
+        #
+        def configure!(configured_environment = nil)
+          @__config.configure_defaults!(configured_environment)
+
+          [:__global, configured_environment].compact.map(&:to_sym).select { |environment|
+            __config_environments.key?(environment)
+          }.each do |environment|
+            instance_eval(&__config_environments[environment])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/core_refinements/array/ensurable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Support
+    module Refinements
+      module Array
+        module Ensurable
+          refine ::Array.singleton_class do
+            # Ensures that +object+ is an array, converting it if necessary. This
+            # was added to safely wrap hashes, because +Array(hash)+ converts
+            # into an array of key/value pairs.
+            #
+            def ensure(object)
+              if object.respond_to?(:to_ary)
+                object.to_ary
+              else
+                [object]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/core_refinements/method/introspection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Support
+    module Refinements
+      module Method
+        module Introspection
+          refine ::Method do
+            # Returns true if +argument_name+ is defined as a keyword argument.
+            #
+            def keyword_argument?(argument_name)
+              parameters.any? { |(parameter_type, parameter_name)|
+                (parameter_type == :key || parameter_type == :keyreq) && parameter_name == argument_name
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/core_refinements/proc/introspection.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Support
+    module Refinements
+      module Proc
+        module Introspection
+          refine ::Proc do
+            # Returns true if +argument_name+ is defined as a keyword argument.
+            #
+            def keyword_argument?(argument_name)
+              parameters.any? { |(parameter_type, parameter_name)|
+                (parameter_type == :key || parameter_type == :keyreq) && parameter_name == argument_name
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/support/core_refinements/string/normalization.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Support
+    module Refinements
+      module String
+        module Normalization
+          refine ::String.singleton_class do
+            # Normalizes a string into a predictable path.
+            #
+            #   String.normalize_path("foo//bar/")
+            #   # => "/foo/bar"
+            #
+            def normalize_path(path)
+              path = path.to_s
+
+              unless path.start_with?("/")
+                path = "/#{path}"
+              end
+
+              if path.include?("//")
+                path = path.to_s.gsub("//", "/")
+              end
+
+              unless path == "/"
+                path = path.chomp("/")
+              end
+
+              path
+            end
+
+            # Collapses a string into a version without tokens.
+            #
+            #   String.collapse_path("/foo/:bar/baz")
+            #   # => "/foo/baz"
+            def collapse_path(path)
+              if path == "/"
+                return path
+              end
+
+              path.to_s.split("/").keep_if { |part|
+                part[0] != ":"
+              }.join("/")
+            end
+          end
+        end
+      end
+    end
+  end
+end