vcdry 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 185f278d99a71c67953d1453a9b2c62ee2afac0c914d3a4c8793c5677396b232
+  data.tar.gz: 84290611068e8991a71164cdd11ca4d2e318ce364975905b1ece0c75e5a2dada
+SHA512:
+  metadata.gz: 95dd05bd5d0654374b46a99d43cb0029e9302a3b38a0d60e4278b64a2e0edb2e5dce528a91a0c732ab494fafa9e2cf287977960f31cc4d4411ec19947f80eb7b
+  data.tar.gz: c47f92e3d43e7b96f7901b37a4633d6a8e9a96a787e8fc9e2ad0d4d922d76bcfe532eb623059305b3c7c348f629e22bf580baafaba39cba3737927bf45a2b7c1

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [1.0.0] - 2023-04-16
+
+- Initial release

data/README.md

@@ -0,0 +1,305 @@
+# VCDry
+
+[![Test](https://github.com/wamonroe/vcdry/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/wamonroe/vcdry/actions/workflows/test.yml)
+
+Simple DSL designed with [View Components](https://viewcomponent.org) in mind to
+make defining and setting keyword arguments and instance variables easier.
+
+Before:
+
+```ruby
+class HeadingComponent < ApplicationComponent
+  def initialize(text:, tag: "h1", **options)
+    @text = text
+    @tag = tag
+    @options = options
+  end
+end
+```
+
+After:
+
+```ruby
+class HeadingComponent < ApplicationComponent
+  include VCDry::DSL
+
+  keyword :text
+  keyword :tag, default: "h1"
+  other_keywords :options
+end
+```
+
+## Table of Contents
+
+- [VCDry](#vcdry)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+  - [General Usage](#general-usage)
+    - [Overview](#overview)
+    - [keyword](#keyword)
+    - [other_keywords](#other_keywords)
+    - [strict_keywords](#strict_keywords)
+    - [remove_keyword](#remove_keyword)
+  - [Types](#types)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "vcdry"
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+## General Usage
+
+### Overview
+
+Include `VCDry::DSL` in your component.
+
+```ruby
+class ApplicationComponent < ViewComponent::Base
+  include VCDry::DSL
+end
+```
+
+Use the `keyword` method to define a keyword.
+
+```ruby
+class MyComponent < ApplicationComponent
+  keyword :name
+end
+```
+
+By default, specifying an unknown keyword results in an error.
+
+```ruby
+MyComponent.new(class: "mt-1")
+# unknown keyword: :class (VCDry::UnknownArgumentError)
+```
+
+To disable this behavior, specify `strick_keywords false`.
+
+```ruby
+class MyComponent < ApplicationComponent
+  strict_keywords false
+end
+```
+
+Or, to save those unknown keywords into a variable, use `other_keywords`.
+
+```ruby
+class MyComponent < ApplicationComponent
+  other_keywords :options
+end
+```
+
+Keywords specified on a parent component are inherited by a child component.
+
+```ruby
+class ApplicationComponent < ViewComponent::Base
+  include VCDry::DSL
+
+  other_keywords :options
+end
+
+class ParentComponent < ApplicationComponent
+  keyword :name
+end
+
+class ChildComponent < ParentComponent
+  keyword :age
+end
+
+ChildComponent.new(name: "Child", age: 7, class: "mt-1").instance_variables
+# => [:@name, :@age, :@options]
+```
+
+### keyword
+
+Define a keyword variable to read and store to an instance variable when
+instantiating a component.
+
+```ruby
+class MyComponent
+  keyword :name
+end
+```
+
+Specify a type to typecast the value specified.
+
+```ruby
+class MyComponent
+  keyword :name, :string
+end
+```
+
+You can use any of the built-in types or create your own as defined in
+[Types](#types). Additionally you can specify a proc to define
+your own one off type for a component.
+
+```ruby
+class MyComponent
+  keyword :name, ->(value) { "custom #{value}" }
+end
+```
+
+By default, keywords are required. To make a keyword optional, specify a default
+value using the `:default` or pass `optional: true`.
+
+```ruby
+class MyComponent
+  keyword :padding, :integer, optional: true
+  keyword :size, :symbol, default: :md
+end
+```
+
+When specifying a default, you can also pass the value as a proc to resolve the
+default value.
+
+```ruby
+class MyComponent
+  keyword :options, :hash, default: -> { Hash.new }
+end
+```
+
+You can instruct a keyword to only accept a predefined set of values by using
+the `:values` option.
+
+```ruby
+class MyComponent
+  keyword :size, :symbol, values: [:sm, :md, :lg]
+end
+```
+
+You can also instruct a keyword to accept an array of values by passing the
+`array: true` option.
+
+```ruby
+class MyComponent
+  keyword :author_ids, :string, array: true
+end
+```
+
+A child component can override the declaration of a keyword from a parent
+component.
+
+```ruby
+class MyOtherComponent < MyComponent
+  keyword :author_ids, :integer, array: true
+end
+```
+
+### other_keywords
+
+To gather all keywords not explicitly defined by the `keyword` method, use the
+`other_keywords` method.
+
+```ruby
+class MyComponent
+  keyword :name
+  other_keywords :options
+end
+```
+
+In the example above, the `:name` keyword would be stored in the variable
+`@name` while all other keywords specified would be stored in the variable
+`@options`.
+
+If you have a custom type defined that acts similarly to a `Hash` (like the
+[TagOptions::Hash](https://github.com/wamonroe/tag_options) gem), you can pass
+that in to the `other_keywords` declaration.
+
+```ruby
+class MyComponent
+  other_keywords :options, :tag_options
+end
+```
+
+**Note**: You must register a custom type using `VCDry::Types.add_type` as
+detailed in [Types](#types).
+
+### strict_keywords
+
+By default, if you specify a unknown keyword when instantiating a component an
+error will be raised. To silently discard the additional keywords, use the
+`strict_keywords false` declaration.
+
+```ruby
+class MyComponent
+  keyword :name
+  strict_keywords false
+end
+```
+
+To turn it back on for a component that inherits from parent component that
+turned off strict keywords, use the `strict_keywords true` declaration.
+
+```ruby
+class MyOtherComponent < MyComponent
+  strict_keywords true
+end
+```
+
+### remove_keyword
+
+To remove a keyword specified on a component that inherits from parent
+component, use the `remove_keyword` method.
+
+```ruby
+class MyOtherComponent < MyComponent
+  remove_keyword :name
+end
+```
+
+## Types
+
+The following types are built-in to `vcdry`.
+
+- boolean
+- datetime
+- hash
+- integer
+- string
+- symbol
+
+Additionally you can define custom, or override built-in, types by using
+`VCDry::Types.add_type`.
+
+```ruby
+# config/initializers/vcdry_types.rb
+VCDry::Types.add_type(:boolean, ->(value) { ActiveRecord::Type::Boolean.new.cast(value) })
+VCDry::Types.add_type(:custom_hash, ->(value) { CustomHash.new(value) })
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bin/rspec` to run the tests. You can also run:
+
+- `bin/console` for an interactive prompt that will allow you to experiment
+- `bin/rubocop` to run RuboCop to check the code style and formatting
+
+To build this gem on your local machine, run `bundle exec rake build`. 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/wamonroe/vcdry.
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).

data/Rakefile

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

data/lib/vcdry/config.rb

@@ -0,0 +1,83 @@
+require "active_support/core_ext/enumerable"
+
+require_relative "error"
+require_relative "types"
+
+module VCDry
+  class Config
+    NOT_DEFINED = Object.new.freeze
+
+    attr_reader :name
+
+    def initialize(name, type = nil, **options)
+      @name = name.to_sym
+      @type = (type.nil? || type.respond_to?(:call)) ? type : VCDry::Types[type]
+      @options = options
+    end
+
+    def array?
+      !!@options[:array]
+    end
+
+    def default?
+      @options.key?(:default)
+    end
+
+    def dup
+      self.class.new(@name, @type, **@options.dup)
+    end
+
+    def enum?
+      @options.key?(:values)
+    end
+
+    def enum_values
+      @enum_values ||= Array(@options[:values]).map do |value|
+        @type.nil? ? value : @type.call(value)
+      end
+    end
+
+    def default
+      value = @options.fetch(:default, NOT_DEFINED)
+      value = value.call if value.respond_to?(:call)
+      value
+    end
+
+    def instance_variable
+      "@#{name}"
+    end
+
+    def optional?
+      default? || !!@options[:optional]
+    end
+
+    def required?
+      !optional?
+    end
+
+    def type_cast(value)
+      array? ? type_cast_array(value) : type_cast_value(value)
+    end
+
+    private
+
+    def type_cast_array(values)
+      return if values == NOT_DEFINED
+
+      Array(values).map do |value|
+        type_cast_value(value)
+      end
+    end
+
+    def type_cast_value(value)
+      return if value == NOT_DEFINED
+      return value if @type.nil?
+
+      value = @type.call(value)
+      if enum? && enum_values.exclude?(value)
+        raise InvalidEnumValueError.new(name, enum_values)
+      end
+      value
+    end
+  end
+end

data/lib/vcdry/dsl.rb

@@ -0,0 +1,71 @@
+require "active_support/concern"
+require "active_support/core_ext/hash"
+require "active_support/core_ext/module/delegation"
+
+require_relative "error"
+require_relative "registry"
+
+module VCDry
+  module DSL
+    extend ActiveSupport::Concern
+
+    def initialize(**kwargs)
+      kwargs = kwargs.symbolize_keys
+      vcdry_parse_keywords(**kwargs)
+      vcdry_parse_unknown_keywords(**kwargs)
+    end
+
+    def vcdry_parse_keywords(**kwargs)
+      self.class.vcdry.keyword_configs.each do |config|
+        if config.required? && !kwargs.key?(config.name)
+          raise MissingRequiredKeywordError.new(config.name)
+        end
+
+        value = kwargs.fetch(config.name, config.default)
+        instance_variable_set(config.instance_variable, config.type_cast(value))
+      end
+    end
+
+    def vcdry_parse_unknown_keywords(**kwargs)
+      unknown_kwargs = kwargs.except(*self.class.vcdry.keywords)
+      raise UnknownArgumentError.new(*unknown_kwargs.keys) if self.class.vcdry.strict? && unknown_kwargs.present?
+      return unless self.class.vcdry.gather_unknown_keywords?
+
+      config = self.class.vcdry.other_keywords_config
+      instance_variable_set(config.instance_variable, config.type_cast(unknown_kwargs))
+    end
+
+    class_methods do
+      delegate :other_keywords, :remove_keyword, :strict_keywords, to: :vcdry
+
+      def inherited(subclass)
+        subclass.instance_variable_set(:@vcdry, @vcdry&.dup)
+      end
+
+      def keyword(name, type = nil, **options)
+        name = name.to_sym
+        config = vcdry.keyword(name, type, options)
+        vcutils_define_helper_methods(config)
+      end
+
+      def vcdry
+        @vcdry ||= Registry.new
+      end
+
+      def vcutils_define_helper_methods(config)
+        if config.enum?
+          config.enum_values.each do |value|
+            define_method "#{config.name}_#{value}?" do
+              instance_variable_get(config.instance_variable) == value
+            end
+          end
+        end
+        if config.optional?
+          define_method "#{config.name}?" do
+            instance_variable_get(config.instance_variable).present?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vcdry/error.rb

@@ -0,0 +1,33 @@
+module VCDry
+  class Error < StandardError; end
+
+  class InvalidEnumValueError < Error
+    def initialize(name, values)
+      super("value for #{name} must be one of '#{values.join("', '")}'")
+    end
+  end
+
+  class MissingRequiredKeywordError < Error
+    def initialize(name)
+      super("missing required keyword: :#{name}")
+    end
+  end
+
+  class ReservedNameError < Error
+    def initialize(name)
+      super("'#{name}' is used to gather unknown keywords")
+    end
+  end
+
+  class UnknownArgumentError < Error
+    def initialize(*names)
+      super("unknown keyword: :#{names.join(" :")}")
+    end
+  end
+
+  class UnknownTypeError < Error
+    def initialize(type)
+      super("unknown type: #{type}")
+    end
+  end
+end

data/lib/vcdry/registry.rb

@@ -0,0 +1,60 @@
+require_relative "config"
+require_relative "error"
+
+module VCDry
+  class Registry
+    attr_reader :other_keywords_config
+
+    def initialize
+      @keywords = {}
+      @other_keywords_config = nil
+      @strict = true
+    end
+
+    def dup
+      object = self.class.new
+      keywords = {}
+      @keywords.each do |name, config|
+        keywords[name] = config.dup
+      end
+      object.instance_variable_set(:@keywords, keywords)
+      object.instance_variable_set(:@other_keywords_config, @other_keywords_config&.dup)
+      object.instance_variable_set(:@strict, @strict)
+      object
+    end
+
+    def gather_unknown_keywords?
+      !@other_keywords_config.nil?
+    end
+
+    def keyword(name, type, options = {})
+      raise ReservedNameError.new(name) if @other_keywords_config&.name == name.to_sym
+
+      @keywords[name] = Config.new(name, type, **options)
+    end
+
+    def keyword_configs
+      @keywords.values
+    end
+
+    def keywords
+      @keywords.keys
+    end
+
+    def other_keywords(name, type: :hash)
+      @other_keywords_config = Config.new(name, type)
+    end
+
+    def strict?
+      !gather_unknown_keywords? && @strict
+    end
+
+    def strict_keywords(value)
+      @strict = !!value
+    end
+
+    def remove_keyword(name)
+      @keywords.delete(name)
+    end
+  end
+end

data/lib/vcdry/types.rb

@@ -0,0 +1,40 @@
+require "active_support/core_ext/module/delegation"
+
+module VCDry
+  module Types
+    class << self
+      delegate :add_type, :remove_type, :[], to: :registry
+
+      private
+
+      def registry
+        @registry ||= TypeRegistry.new
+      end
+    end
+
+    class TypeRegistry
+      def initialize
+        @types = {
+          boolean: ->(value) { !!value },
+          datetime: ->(value) { value.to_datetime },
+          hash: ->(value) { value.to_h },
+          integer: ->(value) { value.to_i },
+          string: ->(value) { value.to_s },
+          symbol: ->(value) { value.to_s.to_sym }
+        }
+      end
+
+      def add_type(name, method)
+        raise TypeError, "method must respond to #call" unless method.respond_to?(:call)
+
+        @types[name] = method
+      end
+
+      def [](name)
+        @types.fetch(name)
+      rescue KeyError
+        raise UnknownTypeError.new(name)
+      end
+    end
+  end
+end

data/lib/vcdry/version.rb

@@ -0,0 +1,3 @@
+module VCDry
+  VERSION = "1.0.0"
+end

data/lib/vcdry.rb

@@ -0,0 +1,9 @@
+require_relative "vcdry/dsl"
+require_relative "vcdry/error"
+require_relative "vcdry/config"
+require_relative "vcdry/registry"
+require_relative "vcdry/types"
+require_relative "vcdry/version"
+
+module VCDry
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: vcdry
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Alex Monroe
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-04-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: view_component
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.35'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.35'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: DSL for declaring keyword parameters on ViewComponents.
+email:
+- alex@monroepost.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/vcdry.rb
+- lib/vcdry/config.rb
+- lib/vcdry/dsl.rb
+- lib/vcdry/error.rb
+- lib/vcdry/registry.rb
+- lib/vcdry/types.rb
+- lib/vcdry/version.rb
+homepage: https://github.com/wamonroe/vcdry
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/wamonroe/vcdry
+  source_code_uri: https://github.com/wamonroe/vcdry
+  changelog_uri: https://github.com/wamonroe/vcdry/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: DSL for declaring keyword parameters on ViewComponents.
+test_files: []