rb-optionsresolver 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 64f1580fdc0be144d8b75ac0083dbf605879cd91d32424cfc48aa0b0a548203e
+  data.tar.gz: 224c3d263123c0c571ccf360081b6dbce951ae2ff9d2fd5bec1caa009de37977
+SHA512:
+  metadata.gz: 3da84da48bf6f4372e0d9e918d44495ed0b11e49a7c9bc9f84f1a56156cbeb904b1840da178f8d0a06a6eb71c2d018b23dc894ef98cbcaa6e41b3f1f8b5fe58e
+  data.tar.gz: 2be3435849f85b0a826ec0f2777dbf0e4a1ac53b62c181ca5926a1772955b4513b3ed183acab90bdddd675307bd0e8ae50451a7a5e23302ce41d9de8fc701f89

data/.gitignore

@@ -0,0 +1,2 @@
+/Gemfile.lock
+/*.gem

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 NamNV609
+
+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,381 @@
+# Rb OptionsResolver - Symfony OptionsResolver for Ruby
+
+> The Rb OptionsResolver library is Symfony OptionsResolver for Ruby. It allows you to create an options system with required options, defaults, validation (type, value), normalization and more.
+
+## Installation
+
+```
+$ gem install rb-optionsresolver
+```
+
+## Usage
+
+To use OptionsResolver:
+
+```ruby
+require "rb-optionsresolver"
+```
+
+Imagine you have a `Mailer` class which has four options: `host`, `username`, `password` and `port`:
+
+```ruby
+class Mailer
+  def initialize options
+    @options = options
+  end
+end
+```
+
+When accessing the `@options`, you need to add a lot of boilerplate code to check which options are set:
+
+```ruby
+class Mailer
+  # ...
+
+  def send_mail from, to
+    mail = ...
+    mail.set_host @options[:host] ? @options[:host] : "smtp.example.com"
+    mail.set_username @options[:username] ? @options[:username] : "user"
+    mail.set_password @options[:password] ? @options[:password] : "pa$$word"
+    mail.set_port @options[:port] ? @options[:port] : 25
+
+    # ...
+  end
+end
+```
+
+This boilerplate is hard to read and repetitive. Also, the default values of the options are buried in the business logic of your code. Use code below to fix that:
+
+```ruby
+class Mailer
+  def initialize options
+    default_options = {
+      host: "smtp.example.com",
+      username: "user"
+    }
+
+    @options = [*default_options, *options].to_h
+  end
+end
+```
+
+Now all four options are guaranteed to be set. But what happens if the user of the `Mailer` class makes a mistake?
+
+```ruby
+mailer_opts = {
+  usernme: "johndoe" # usernme misspelled (instead of username)
+}
+mailer = Mailer.new mailer_opts
+```
+
+No error will be shown. In the best case, the bug will appear during testing, but the developer will spend time looking for the problem. In the worst case, the bug might not appear until it's deployed to the live system.
+
+Fortunately, the `OptionsResolver` class helps you to fix this problem:
+
+```ruby
+class Mailer
+  def initialize options
+    resolver = OptionsResolver.new
+    resolver.set_defaults({
+      host: "smtp.example.com",
+      username: "user",
+      password: "pa$$word",
+      port: 25
+    })
+
+    @options = resolver.resolve options
+  end
+end
+```
+
+Like before, all options will be guaranteed to be set. Additionally, an `UndefinedOptions` is thrown if an unknown option is passed:
+
+```ruby
+mailer_opts = {usernme: "johndoe"}
+mailer = Mailer.new mailer_opts
+
+# The option "usernme" does not exist.
+# Know options are: "host", "username", "password", "port" (UndefinedOptions)
+```
+
+The rest of your code can access the values of the options without boilerplate code:
+
+```ruby
+class Mailer
+  # ...
+
+  def send_mail from, to
+    mail = ...
+
+    mail.set_host @options[:host]
+    mail.set_username @options[:username]
+    mail.set_password @options[:password]
+    mail.set_port @options[:port]
+  end
+end
+```
+
+### Required Options
+
+If an option must be set by the caller, pass that option to `set_required()`. For example, to make the `host` option required, you can do:
+
+```ruby
+class Mailer
+  def initialize options
+    resolver = OptionsResolver.new
+    resolver.set_required "host"
+
+    @options = resolver.resolve options
+  end
+end
+```
+
+If you omit a required option, a `MissingOptions` will be thrown:
+
+```ruby
+mailer = Mailer.new
+
+#  The required options "host" is missing. (MissingOptions)
+```
+
+The `set_required()` method accepts a single name or an array of option names if you have more than one required option:
+
+```ruby
+class Mailer
+  # ...
+  resolver.set_required %w(host username password)
+end
+```
+
+Use `is_required?()` to find out if an option is required. You can use `get_required_options()` to retrieve the names of all required options:
+
+```
+required_options = resolver.get_required_options()
+```
+
+If you want to check whether a required option is still missing from the default options, you can use `is_missing?()`. The difference between this and `is_required?()` is that this method will return false if a required option has already been set:
+
+```ruby
+# ...
+resolver.is_required? "host" # true
+resolver.is_missing? "host" # true
+resolver.set_default "host", "smtp.example.com"
+resolver.is_required? "host" # true
+resolver.is_missing? "host" # false
+```
+
+The method `get_missing_options()` lets you access the names of all missing options.
+
+### Type Validation
+
+You can run additional checks on the options to make sure they were passed correctly. To validate the types of the options, call `set_allowed_types()`:
+
+```ruby
+# ...
+# specify one allowed type
+resolver.set_allowed_types "port", "int"
+```
+
+> **TODO**: Specify multiple allowed types and can pass fully qualified class names.
+
+You can pass any type for which an:
+
+* `integer` (`int`)
+* `string` (`str`)
+* `array` (`arr`)
+* `boolean` (`bool`)
+* `float`
+* `hash`
+* `symbol` (`sym`)
+* `range`
+* `regexp`
+* `proc`
+
+If you pass an invalid option now, an `InvalidOptions` is thrown:
+
+```ruby
+mailer_opts = {
+  port: "465"
+}
+mailer = Mailer.new mailer_opts
+
+#  The option "port" with "465" is expected to be of type "int" (InvalidOptions)
+```
+
+> **TODO**: In sub-classes, you can use `add_allowed_types()` to add additional allowed types without erasing the ones already set.
+
+### Value Validation
+
+Some options can only take one of a fixed list of predefined values. For example, suppose the `Mailer` class has a `transport` option which can be one of `sendmail`, `mail` and `smtp`. Use the method `set_allowed_values()` to verify that the passed option contains one of these values:
+
+```ruby
+class Mailer
+  # ...
+  resolver.set_default("transport", "sendmail")
+    .set_allowed_values("transport", %w(sendmail mail smtp))
+end
+```
+
+If you pass an invalid transport, an `InvalidOptions` is thrown:
+
+```ruby
+mailer_opts = {
+  transport: "send-mail"
+}
+mailer = Mailer.new mailer_opts
+
+# The option "transport" with value "send-mail" is invalid.
+# Accepted values are "sendmail", "mail", "smtp" (RuntimeError)
+```
+
+For options with more complicated validation schemes, pass a proc (or lambda) which returns `true` for acceptable values and `false` for invalid values:
+
+```ruby
+# ...
+resolver.set_allowed_values "transport", Proc.new{|transport|
+  # return true or false
+  %w(sendmail mail smtp).include? transport
+}
+```
+
+> **TODO**: In sub-classes, you can use `add_allowed_values()` to add additional allowed values without erasing the ones already set.
+
+### Option Normalization
+
+
+Sometimes, option values need to be normalized before you can use them. For instance, assume that the `host` should always start with `http://`. To do that, you can write normalizers. Normalizers are executed after validating an option. You can configure a normalizer by calling `set_normailizer()`:
+
+```ruby
+# ...
+resolver.set_normailizer "host", lambda{|options, host|
+  host = "http://#{host}" unless /^https?\:\/\//.match? host
+  host
+}
+```
+
+The normalizer receives the actual `host` and returns the normalized form. You see that the proc (or lambda) also takes an `options` parameter. This is useful if you need to use other options during normalization:
+
+```ruby
+# ...
+.set_normalizer("host", Proc.new{|options, host|
+  unless /^https?\:\/\//.match? host
+    if options["encryption"] == "ssl"
+      host = "https://#{host}"
+    else
+      host = "http://#{host}"
+    end
+  end
+
+  host
+})
+```
+
+### Default Values that Depend on another Option
+
+Suppose you want to set the default value of the `port` option based on the encryption chosen by the user of the `Mailer` class. More precisely, you want to set the port to `465` if SSL is used and to `25` otherwise.
+
+You can implement this feature by passing a proc (or lambda) as the default value of the `port` option. The proc (or lambda) receives the options as argument. Based on these options, you can return the desired default value:
+
+```ruby
+# ...
+resolver.set_default("encryption", nil)
+  .set_default("port", lambda{|options, _| options["encryption"] == "ssl" ? 465 :25})
+```
+
+> The argument of the callable must be type hinted as `options`. Otherwise, the callable itself is considered as the default value of the option.
+
+> The proc (or lambda) is only executed if the `port` option isn't set by the user or overwritten in a sub-class.
+
+A previously set default value can be accessed by adding a second argument to the proc (or lambda):
+
+```ruby
+resolver.set_defaults({
+  encryption: nil,
+  host: "example.org"
+}).set_default("host", Proc.new{|options, previous_host_value|
+  options["encryption"] == "ssl" ? "secure.example.org" : previous_host_value
+})
+```
+
+As seen in the example, this feature is mostly useful if you want to reuse the default values set in parent classes in sub-classes.
+
+### Options without Default Values
+
+In some cases, it is useful to define an option without setting a default value. This is useful if you need to know whether or not the user _actually_ set an option or not. For example, if you set the default value for an option, it's not possible to know whether the user passed this value or if it simply comes from the default:
+
+```ruby
+class Mailer
+  def initialize options
+    resolver = OptionsResolver.new
+    resolver.set_default("port", 25)
+
+    @options = resolver.resolve options
+  end
+
+  def send_mail from, to
+    # Is this the default value or did the caller of the class really
+    # set the port to 25?
+
+    if @options["port"] == 25
+      # ...
+    end
+  end
+end
+```
+
+You can use `set_defined()` to define an option without setting a default value. Then the option will only be included in the resolved options if it was actually passed to `resolve()`:
+
+```ruby
+class Mailer
+  def initialize options
+    resolver = OptionsResolver.new
+    resolver.set_defined "port"
+
+    @options = resolver.resolve options
+  end
+
+  def send_mail from = nil, to = nil
+    if @options["port"]
+      puts "Set!"
+    else
+      puts "Not set"
+    end
+  end
+end
+
+mailer_opts = {}
+mailer = Mailer.new mailer_opts
+mailer.send_mail
+# => Not set!
+
+mailer_opts = {port: 25}
+mailer = Mailer.new mailer_opts
+mailer.send_mail
+# => Set!
+```
+
+You can also pass an array of option names if you want to define multiple options in one go:
+
+```ruby
+resolver.set_defined %w(port encryption)
+```
+
+The methods `is_defined?()` and `get_defined_options()` let you find out which options are defined:
+
+```ruby
+# ...
+if resolver.is_defined? "host"
+  # One of the following was called:
+  # resolver.set_default "host", ...
+  # resolver.set_required "host"
+  # resolver.set_defined "host"
+end
+
+defined_options = resolver.get_defined_options
+```
+
+That's it! You now have all the tools and knowledge needed to easily process options in your code.
+
+# Credits
+
+Original documentation for PHP: [https://symfony.com/doc/3.4/components/options_resolver.html](https://symfony.com/doc/3.4/components/options_resolver.html)

data/lib/optionsresolver/exceptions/invalid_options.rb

@@ -0,0 +1,5 @@
+class InvalidOptions < StandardError
+  def initialize msg
+    super
+  end
+end

data/lib/optionsresolver/exceptions/invalid_parameter.rb

@@ -0,0 +1,5 @@
+class InvalidParameter < StandardError
+  def initialize msg = "Default values is invalid object"
+    super
+  end
+end

data/lib/optionsresolver/exceptions/missing_options.rb

@@ -0,0 +1,5 @@
+class MissingOptions < StandardError
+  def initialize msg
+    super
+  end
+end

data/lib/optionsresolver/exceptions/undefined_options.rb

@@ -0,0 +1,5 @@
+class UndefinedOptions < StandardError
+  def initialize msg
+    super
+  end
+end

data/lib/optionsresolver/optionsresolver.rb

@@ -0,0 +1,242 @@
+require "optionsresolver/exceptions/invalid_parameter"
+require "optionsresolver/exceptions/undefined_options"
+require "optionsresolver/exceptions/missing_options"
+require "optionsresolver/exceptions/invalid_options"
+require "optionsresolver/utils/hash_ext"
+
+class OptionsResolver
+  def initialize
+    @defined_options = []
+    @required_options = []
+    @default_values = {}
+    @allowed_types = {}
+    @allowed_values = {}
+    @normalizers = {}
+    @previous_default_values = {}
+  end
+
+  def set_defined defined_keys
+    if defined_keys.is_a?(Array)
+      @defined_options.concat defined_keys
+    else
+      @defined_options.push defined_keys
+    end
+
+    self
+  end
+
+  def get_defined_options
+    @defined_options
+  end
+
+  def is_defined? option_key
+    @defined_options.include? option_key
+  end
+
+  def set_required required_keys
+    if required_keys.is_a?(Array)
+      @required_options.concat required_keys
+      @defined_options.concat required_keys
+    else
+      @required_options.push required_keys
+      @defined_options.push required_keys
+    end
+
+    self
+  end
+
+  def get_required_options
+    @required_options
+  end
+
+  def is_required? option_key
+    @required_options.include? option_key
+  end
+
+  def is_missing? option_key
+    !@default_values.include? option_key
+  end
+
+  def get_missing_options
+    @required_options.map do |required_key|
+      next if @default_values.include?(required_key)
+      required_key
+    end.compact
+  end
+
+  def set_default option_key, default_value
+    @previous_default_values[option_key] = @default_values[option_key] if
+      @default_values.include? option_key
+
+    @default_values[option_key] = default_value
+    self.set_defined option_key
+
+    self
+  end
+
+  def set_defaults option_default_values
+    raise InvalidParameter unless option_default_values.is_a? Hash
+
+    option_default_values.each do |opt_key, opt_value|
+      opt_key = opt_key.to_s
+
+      self.set_default(opt_key, opt_value).set_defined opt_key
+    end
+
+    self
+  end
+
+  def get_default_values option_key = nil
+    return @default_values unless option_key
+
+    @default_values[option_key]
+  end
+
+  def set_allowed_types option_key, option_value_types
+    @allowed_types[option_key] = option_value_types
+
+    self
+  end
+
+  def get_allowed_types option_key = nil
+    return @allowed_types unless option_key
+
+    @allowed_types[option_key]
+  end
+
+  def set_allowed_values option_key, option_allowed_value
+    @allowed_values[option_key] = option_allowed_value
+
+    self
+  end
+
+  def get_allowed_values option_key = nil
+    return @allowed_values unless option_key
+
+    @allowed_values
+  end
+
+  def set_normalizer option_key, normalizer_value
+    @normalizers[option_key] = normalizer_value
+
+    self
+  end
+
+  def resolve data_object
+    raise InvalidParameter unless data_object.is_a? Hash
+
+    # Unique @defined_options
+    @defined_options.uniq!
+    # Stringify hash keys
+    data_object = data_object.stringify_keys
+    # Check undefined options
+    check_undefined_options data_object.keys
+    # Set default values
+    data_object = set_options_default data_object
+    # Check missing required options
+    check_missing_required_options data_object
+    # Check invalid options type
+    check_invalid_options_type data_object
+    # Check invalid options value
+    check_invalid_options_value data_object
+    # Normalizer options value
+    data_object = normalizer_options_value data_object
+
+    data_object
+  end
+
+  private
+  def check_undefined_options option_keys
+    know_options_str = "\"#{@defined_options.join("\", \"")}\""
+
+    option_keys.each do |opt_key|
+      raise UndefinedOptions, "The option \"#{opt_key}\" does not exist. Know options are: #{know_options_str}" unless
+        @defined_options.include? opt_key.to_s
+    end
+  end
+
+  def set_options_default data_object
+    @default_values.each do |option_key, default_value|
+      next unless data_object[option_key].nil?
+
+      previous_default_value = @previous_default_values[option_key]
+      data_object[option_key] = default_value.is_a?(Proc) ? default_value.call(data_object, previous_default_value) : default_value
+    end
+
+    data_object
+  end
+
+  def check_missing_required_options data_object
+    @required_options.each do |required_key|
+      next if data_object[required_key.to_s]
+
+      raise MissingOptions, "The required options \"#{required_key}\" is missing."
+    end
+  end
+
+  def check_invalid_options_type data_object
+    @allowed_types.each do |option_key, allowed_type|
+      option_key = option_key.to_s
+      option_value = data_object[option_key]
+
+      case allowed_type.downcase
+      when "int", "integer"
+        throw_invalid_options_exception option_key, option_value, "int" unless option_value.is_a? Integer
+      when "str", "string"
+        throw_invalid_options_exception option_key, option_value, "str" unless option_value.is_a? String
+      when "arr", "array"
+        throw_invalid_options_exception option_key, option_value, "array" unless option_value.is_a? Array
+      when "bool", "boolean"
+        throw_invalid_options_exception option_key, option_value, "boolean" unless [true, false].include? option_value
+      when "float"
+        throw_invalid_options_exception option_key, option_value, "float" unless option_value.is_a? Float
+      when "hash"
+        throw_invalid_options_exception option_key, option_value, "hash" unless option_value.is_a? Hash
+      when "sym", "symbol"
+        throw_invalid_options_exception option_key, option_value, "symbol" unless option_value.is_a? Symbol
+      when "range"
+        throw_invalid_options_exception option_key, option_value, "range" unless option_value.is_a? Range
+      when "regexp"
+        throw_invalid_options_exception option_key, option_value, "regexp" unless option_value.is_a? Regexp
+      when "proc"
+        throw_invalid_options_exception option_key, option_value, "proc" unless option_value.is_a? Proc
+      end
+    end
+  end
+
+  def check_invalid_options_value data_object
+    @allowed_values.each do |option_key, allowed_value|
+      option_key = option_key.to_s
+      option_value = data_object[option_key]
+      is_valid_value = true
+      accepted_value_msg = ""
+
+      if allowed_value.is_a? Array
+        is_valid_value = allowed_value.include? option_value
+        accepted_value_msg = " Accepted values are \"#{allowed_value.join("\", \"")}\""
+      elsif allowed_value.is_a? Proc
+        is_valid_value = allowed_value.call option_value
+      else
+        is_valid_value = (option_value == allowed_value)
+      end
+
+      raise "The option \"#{option_key}\" with value \"#{option_value}\" is invalid.#{accepted_value_msg}" unless is_valid_value
+    end
+  end
+
+  def normalizer_options_value data_object
+    @normalizers.each do |option_key, normalizer_method|
+      raise InvalidParameter "Normalizer for key \"#{option_key}\" has invalid method." unless normalizer_method.is_a? Proc
+
+      option_value = data_object[option_key]
+      data_object[option_key] = normalizer_method.call data_object, option_value
+    end
+
+    data_object
+  end
+
+  def throw_invalid_options_exception key, val, expected_type
+    msg = "The option \"#{key}\" with \"#{val}\" is expected to be of type \"#{expected_type}\""
+    raise InvalidOptions, msg
+  end
+end

data/lib/optionsresolver/utils/hash_ext.rb

@@ -0,0 +1,9 @@
+class Hash
+  def stringify_keys
+    Hash[self.map{|key, val| [key.to_s, val]}]
+  end
+
+  def symbolize_keys
+    Hash[self.map{|key, val| [key.to_sym, val]}]
+  end
+end

data/lib/rb-optionsresolver.rb

@@ -0,0 +1 @@
+require "optionsresolver/optionsresolver"

data/rb-optionsresolver.gemspec

@@ -0,0 +1,12 @@
+Gem::Specification.new do |spec|
+  spec.name = "rb-optionsresolver"
+  spec.version = "0.0.1"
+  spec.authors = ["NamNV609"]
+  spec.email = ["namnv609@gmail.com"]
+  spec.description = "Ruby library like Symfony OptionsResolver"
+  spec.summary = "Allows to create an options system with required options, defaults, validation (type, value), normalization and more."
+  spec.license = "MIT"
+  spec.homepage = "https://github.com/namnv609/rb-optionsresolver"
+  spec.files = `git ls-files`.split($/)
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: rb-optionsresolver
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- NamNV609
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-07-05 00:00:00.000000000 Z
+dependencies: []
+description: Ruby library like Symfony OptionsResolver
+email:
+- namnv609@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- lib/optionsresolver/exceptions/invalid_options.rb
+- lib/optionsresolver/exceptions/invalid_parameter.rb
+- lib/optionsresolver/exceptions/missing_options.rb
+- lib/optionsresolver/exceptions/undefined_options.rb
+- lib/optionsresolver/optionsresolver.rb
+- lib/optionsresolver/utils/hash_ext.rb
+- lib/rb-optionsresolver.rb
+- rb-optionsresolver.gemspec
+homepage: https://github.com/namnv609/rb-optionsresolver
+licenses:
+- MIT
+metadata: {}
+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: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Allows to create an options system with required options, defaults, validation
+  (type, value), normalization and more.
+test_files: []