contours 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4045b6e13180f9b89bda47ed3c389c467e804368f4d9bd48acd2b1a5ef0c0255
+  data.tar.gz: 8ceb930137c7479306379051a523c7baa49f9a7466e57d97e060f70f8b5b869d
+SHA512:
+  metadata.gz: 4012d37792abdf2073efb3fffa0773424b8680721fabffd0552b6f3630774ca41041f5240bb27e2acff38b45bbee3c464a4ad821448efb9715aac7cdf1b7fdee
+  data.tar.gz: c214234c537c604499cc781e8e9e17d9a9504c191d19417a3142b2319aa7ffe2da9ea38245f867a061d2dc4b1e2bd6360997e081bee863b98f08a60c35157c29

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 SOFware LLC
+
+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,67 @@
+# Contours
+
+Contours provids objects for building configuration.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add contours
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install contours
+
+## Usage
+
+Build a configuration object by creating a class that inherits from `Contours::BlendedHash` and define the configuration attributes.
+
+Specify a list of keys that should be blended into the configuration object by setting the `@blended_keys` variable on the class.
+
+```ruby
+class Configuration < Contours::BlendedHash
+  @blended_keys = %i[class data]
+end
+```
+
+Create a new object using `init`
+
+```ruby
+config = Configuration.init({class: "test", data: [1, 2, 3]})
+```
+
+The `config` object will be able to be merged with other configuration objects.
+
+```ruby
+config.merge(Configuration.init({class: "overwrite", data: [4, 5, 6]}))
+
+config.to_h # => {class: "overwrite", data: [1, 2, 3, 4, 5, 6]}
+```
+
+You can specify a custom way to blend the values for the `@blended_keys`
+
+```ruby
+class Configuration < Contours::BlendedHash
+  @blended_keys = %i[class data]
+
+  blend(:class, with: StructuredString)
+
+  blend :data do |existing, new_value|
+    existing.sum(new_value.sum)
+  end
+end
+
+config.merge(Configuration.init({class: "overwrite", data: [4, 5, 6]}))
+
+config.to_h # => {class: "test overwrite", data: 21}
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` 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 the created tag, 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/SOFware/contours.

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.warning = true
+  t.test_files = FileList["test/**/test_*.rb"]
+end
+
+task default: :test

data/lib/contours/blended_hash.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Contours
+  # BlendedHash is a utility class that allows you to merge two hashes.
+  # It may be used to specify how to combine values that are specified
+  # more than once. For example, if you have a BlendedHash like this:
+  #
+  #   class CssConfig < BlendedHash
+  #     @blended_keys = %i[class]
+  #     def blend_class(original, extras)
+  #       [original, extras].flatten.compact.uniq.join(" ")
+  #     end
+  #   end
+  #
+  #   CssConfig.new({class: "foo"})
+  #
+  # And you merge it with another hash like this:
+  #
+  #   CssConfig.new({class: "foo"}).merge({class: "bar"})
+  #
+  # The result will be:
+  #   {
+  #     class: "foo bar"
+  #   }
+  #
+  # See the source of this #{name} class for more details.
+  class BlendedHash < DelegateClass(Hash)
+    alias_method :to_hash, :__getobj__
+
+    # Ensure that the initial hash is a BlendedHash
+    def self.init(initial_hash)
+      if initial_hash.is_a?(BlendedHash)
+        initial_hash
+      else
+        new({}).merge(initial_hash)
+      end
+    end
+
+    # Define a method that will be used to blend the value of a key.
+    # The method name will be "blend_#{key}".
+    # If a block is given, it will be used as the implementation of the method.
+    # Otherwise, the default implementation will be used where the value of the
+    # with argument is expected to receive 'init' with the original value and
+    # then 'merge' with the extras value.
+    def self.blend(key, with: nil, &block)
+      if block
+        define_method("blend_#{key}", &block)
+      else
+        define_method("blend_#{key}") do |original, extras|
+          with.init(original).merge(extras)
+        end
+      end
+    end
+
+    # Recursively check for keys that are specified as blended and apply
+    # the blend method to them or execute the blend_#{key} method if it exists
+    # to set the new value.
+    def merge(overrides)
+      return self if overrides.nil? || overrides.empty?
+      self.class.new(overrides.each_with_object(to_hash.dup) do |(key, value), hash|
+        hash[key] = if blended_keys.include?(key)
+          if respond_to?("blend_#{key}")
+            send("blend_#{key}", hash[key], value)
+          else
+            blend(hash[key], value)
+          end
+        else
+          value
+        end
+        hash
+      end)
+    end
+
+    # Ensure that the return value of these methods is a BlendedHash
+    def [](...)
+      if super.is_a?(Hash)
+        self.class.init(super)
+      else
+        super
+      end
+    end
+
+    def fetch(...)
+      if super.is_a?(Hash)
+        self.class.init(super)
+      else
+        super
+      end
+    end
+
+    def dig(...)
+      if super.is_a?(Hash)
+        self.class.init(super)
+      else
+        super
+      end
+    end
+
+    # The keys that should be blended when merging two hashes.
+    # Specify this in subclasses to customize the behavior.
+    @blended_keys = []
+    class << self
+      attr_reader :blended_keys
+    end
+    def blended_keys = self.class.blended_keys
+
+    # Default implementation of the blend method. Override this in subclasses
+    # with a custom blend_#{key} method to customize the blending behavior for a
+    # specific key.
+    #
+
+    def blend(original, extra)
+      case original
+      when BlendedHash, Hash
+        self.class.init(original).merge(extra)
+      when Array
+        [original, extra].flatten.compact.uniq
+      else
+        extra
+      end
+    end
+  end
+end

data/lib/contours/structured_string.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Contours
+  # This class represents a string which has a particular order to its content.
+  # The intended use is for setting up CSS class values for HTML.
+  #
+  # An element may required that the first part of a class be a particular value
+  # and that the last part of a class be a particular value. For example, a
+  # field with an error might have a class like this:
+  #
+  #   "input my-special-class input-error"
+  #
+  # Setting that up with a StructuredString would look like this:
+  #
+  #   config = StructuredString.new("input").last("input-error")
+  #   config << "my-special-class"
+  #   config.to_s #=> "input my-special-class input-error"
+  #
+  class StructuredString < DelegateClass(String)
+    # Ensure that the argument string is a StructuredString
+    def self.init(base)
+      if base.is_a?(StructuredString)
+        base
+      else
+        new(base)
+      end
+    end
+
+    # Initialize with base string that is used to build the StructuredString
+    # Other values will be added to the string in the order they are added.
+    def initialize(base = "", separator: " ")
+      @base = [base]
+      @separator = separator
+      @first = []
+      @last = []
+      @other = []
+    end
+
+    # Add a value to the beginning of the string
+    def first(value)
+      @first << value.to_s
+      __setobj__ to_s
+      self
+    end
+
+    # Add a value to the end of the string
+    def last(value)
+      @last << value.to_s
+      __setobj__ to_s
+      self
+    end
+
+    # Add a value to the middle of the string
+    def <<(other)
+      @other << other.to_s
+      __setobj__ to_s
+      self
+    end
+
+    # Read a particular portion of the structured string or raise an error
+    def read(key)
+      case key
+      when :first
+        @first
+      when :base
+        @base
+      when :other
+        @other
+      when :last
+        @last
+      else
+        raise ArgumentError, "Unknown accessor: #{key.inspect}"
+      end
+    end
+
+    # Add a value to the string in a particular position
+    # The argument must be a string or a 2 element array
+    # If it is a 2 element array, the first element must be a string and the
+    # second element must the name of a method used to merge the string to the
+    # StructuredString.
+    #
+    # For example:
+    #
+    #   config = StructuredString.new("input")
+    #   config.merge("my-special-class")
+    #   config.merge(["input-error", :last])
+    #   config.to_s #=> "input my-special-class input-error"
+    #
+    def merge(data)
+      case data
+      in StructuredString
+        @first += data.read :first
+        @base += data.read :base
+        @other += data.read :other
+        @last += data.read :last
+      in [String, Symbol]
+        if method(data.last)&.arity == 1
+          send(data.last, data.first)
+        else
+          raise ArgumentError, %(Tried to use '#{data.last}' with "#{data.first}" but it doesn't take 1 argument)
+        end
+      in String
+        send(:<<, data)
+      else
+        raise ArgumentError, "Must be a string or a 2 element array got: #{data.inspect}"
+      end
+
+      self
+    end
+
+    # Return the string representation of the StructuredString
+    def to_s
+      [@first, @base, @other, @last]
+        .flatten
+        .compact
+        .map(&:to_s)
+        .reject(&:empty?)
+        .join(@separator)
+    end
+    alias_method :to_str, :to_s
+    alias_method :inspect, :to_s
+
+    def ==(other)
+      to_s == other.to_s
+    end
+  end
+end

data/lib/contours/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Contours
+  VERSION = "0.1.0"
+end

data/lib/contours.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "contours/version"
+require_relative "contours/blended_hash"
+require_relative "contours/structured_string"
+
+module Contours
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: contours
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jim Gay
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-10-10 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Provides objects with which you can define a configuration object
+  which can be customized by merging in other configuration objects.
+email:
+- jim@saturnflyer.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/contours.rb
+- lib/contours/blended_hash.rb
+- lib/contours/structured_string.rb
+- lib/contours/version.rb
+homepage: https://github.com/SOFware/contours
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/SOFware/contours
+  source_code_uri: https://github.com/SOFware/contours.git
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Support for building customizable configuration objects.
+test_files: []