opto 1.4.0

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "opto"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/opto.rb

@@ -0,0 +1,51 @@
+require "opto/version"
+require 'opto/extensions/snake_case'
+require 'opto/extensions/hash_string_or_symbol_key'
+
+if RUBY_VERSION < '2.1'
+  using Opto::Extension::SnakeCase
+  using Opto::Extension::HashStringOrSymbolKey
+end
+
+require "opto/option"
+require "opto/group"
+
+require 'yaml'
+
+# An option parser/validator/resolver
+#
+module Opto
+  # Initialize a new Opto::Option (when input is hash) or an Opto::Group (when input is an array of hashes)
+  def self.new(opts)
+    case opts
+    when Hash
+      if opts.has_key?('name') || opts.has_key?(:name)
+        Option.new(opts)
+      else
+        Group.new(opts)
+      end
+    when Array
+      if opts.all? {|o| o.kind_of?(Hash) }
+        Group.new(opts)
+      else
+        raise TypeError, "Invalid input, an option hash or an array of option hashes required"
+      end
+    else
+      raise TypeError, "Invalid input, an option hash or an array of option hashes required"
+    end
+  end
+
+  # Read an option (or option group) from a YAML file
+  # @param [String] path_to_file
+  # @param [String,Symbol] a key in the hash representation of the file, such as :variables to read the options from (instead of using the root)
+  # @example
+  #   Opto.read('/tmp/foo.yml', :options)
+  def self.read(yaml_path, key=nil)
+    opts = YAML.load(File.read(yaml_path))
+    new(key.nil? ? opts : opts[key])
+  end
+
+  singleton_class.send(:alias_method, :load, :read)
+
+end
+

data/lib/opto/extensions/hash_string_or_symbol_key.rb

@@ -0,0 +1,18 @@
+module Opto
+  module Extension
+    # Refines Hash so that [] and delete work with :symbol or 'string' keys
+    module HashStringOrSymbolKey
+      refine Hash do
+        def [](key)
+          return nil if key.nil?
+          super(key.to_s) || super(key.to_sym)
+        end
+
+        def delete(key)
+          return nil if key.nil?
+          super(key) || super(key.to_s) || super(key.to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/opto/extensions/snake_case.rb

@@ -0,0 +1,22 @@
+module Opto
+  module Extension
+    # Refines String to have .snakecase method that turns
+    # StringLikeThis into a string_like_this
+    module SnakeCase
+      refine String do
+        def snakecase
+          gsub(/::/, '/')
+          gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+          gsub(/([a-z\d])([A-Z])/,'\1_\2').
+          tr('-', '_').
+          gsub(/\s/, '_').
+          gsub(/__+/, '_').
+          downcase
+        end
+
+        alias_method :underscore, :snakecase
+        alias_method :snakeize, :snakecase
+      end
+    end
+  end
+end

data/lib/opto/group.rb

@@ -0,0 +1,112 @@
+require 'opto/extensions/snake_case'
+require 'opto/extensions/hash_string_or_symbol_key'
+
+if RUBY_VERSION < '2.1'
+  using Opto::Extension::SnakeCase
+  using Opto::Extension::HashStringOrSymbolKey
+end
+
+module Opto
+  # A group of Opto::Option instances. Members of Groups can see their relatives
+  # and their values. Such as `option.value_of('another_option')`
+  #
+  # Most Array instance methods are delegated, such as .map, .each, .find etc.
+  class Group
+
+    using Opto::Extension::HashStringOrSymbolKey unless RUBY_VERSION < '2.1'
+
+    attr_reader :options, :defaults
+
+    extend Forwardable
+
+    # Initialize a new Option Group. You can also pass in :defaults.
+    #
+    # @param [Array<Hash,Opto::Option>,Hash,NilClass] opts An array of Option definition hashes or Option objects or a hash like { var_name: { opts } }.
+    # @return [Opto::Group]
+    def initialize(*options)
+      if options.size > 0
+        if options.last.kind_of?(Hash) && options.last[:defaults]
+          @defaults = options.pop[:defaults]
+        end
+        @options =
+          case options.first
+          when NilClass
+            []
+          when Hash
+            options.first.map {|k,v| Option.new({name: k.to_s, group: self}.merge(v))}
+          when Array
+            options.first.map {|opt| opt.kind_of?(Opto::Option) ? opt : Option.new(opt.merge(group: self)) }
+          else
+            raise TypeError, "Invalid type #{options.first.class} for Opto::Group.new"
+          end
+      else
+        @options = []
+      end
+
+    end
+
+    # Are all options valid? (Option value passes validation)
+    # @return [Boolean]
+    def valid?
+      options.all? {|o| o.valid? }
+    end
+
+    # Collect validation errors from members
+    # @return [Hash] { option_name => { validator_name => "Too short" } }
+    def errors
+      Hash[*options_with_errors.flat_map {|o| [o.name, o.errors] }]
+    end
+
+    # Enumerate over all the options that are not valid
+    # @return [Array]
+    def options_with_errors
+      options.reject(&:valid?)
+    end
+
+    # Convert Group to an Array of Hashes (by calling .to_h on each member)
+    # @return [Array<Hash>]
+    def to_a(with_errors: false, with_value: false)
+      options.map {|opt| opt.to_h(with_errors: with_errors, with_value: with_value) }
+    end
+
+    # Convert a Group to a hash that has { option_name => option_value }
+    # @return [Hash]
+    def to_h(values_only: false, with_values: false, with_errors: false)
+      if values_only
+        Hash[*options.flat_map {|opt| [opt.name, opt.value]}]
+      else
+        Hash[*options.flat_map {|opt| [opt.name, opt.to_h(with_value: with_values, with_errors: with_errors).reject {|k,_| k==:name}]}]
+      end
+    end
+
+    # Runs outputters for all valid non-skipped options
+    def run
+      options.reject(&:skip?).select(&:valid?).each(&:output)
+    end
+
+    # Initialize a new Option to this group. Takes the same arguments as Opto::Option
+    # @param [Hash] option_definition
+    # @return [Opto::Option]
+    def build_option(args={})
+      options << Option.new(args.merge(group: self))
+      options.last
+    end
+
+    # Find a member by name
+    # @param [String] option_name
+    # @return [Opto::Option]
+    def option(option_name)
+      options.find { |opt| opt.name == option_name }
+    end
+
+    # Get a value of a member by option name
+    # @param [String] option_name
+    # @return [option_value, NilClass]
+    def value_of(option_name)
+      opt = option(option_name)
+      opt.nil? ? nil : opt.value
+    end
+
+    def_delegators :@options, *(Array.instance_methods - [:__send__, :object_id, :to_h, :to_a, :is_a?, :kind_of?, :instance_of?])
+  end
+end

data/lib/opto/option.rb

@@ -0,0 +1,298 @@
+require_relative 'type'
+require_relative 'resolver'
+require_relative 'setter'
+require_relative 'extensions/snake_case'
+require_relative 'extensions/hash_string_or_symbol_key'
+
+if RUBY_VERSION < '2.1'
+  using Opto::Extension::SnakeCase
+  using Opto::Extension::HashStringOrSymbolKey
+end
+
+module Opto
+  # What is an option? It's like a variable that has a value, which can be validated or 
+  # manipulated on creation. The value can be resolved from a number of origins, such as
+  # an environment variable or random string generator.
+  class Option
+
+    unless RUBY_VERSION < '2.1'
+      using Opto::Extension::SnakeCase
+      using Opto::Extension::HashStringOrSymbolKey
+    end
+
+    attr_accessor :type
+    attr_accessor :name
+    attr_accessor :label
+    attr_accessor :description
+    attr_accessor :required
+    attr_accessor :default
+    attr_reader   :from
+    attr_reader   :to
+    attr_reader   :group
+    attr_reader   :skip_if
+    attr_reader   :only_if
+    attr_reader   :initial_value
+    attr_reader   :type_options
+
+    # Initialize an instance of Opto::Option
+    # @param [Hash] options
+    #   @option [String] :name Option name
+    #   @option [String,Symbol] :type Option type, such as :integer, :string, :boolean, :enum
+    #   @option [String] :label A label for this field, to be used in for example an interactive prompt
+    #   @option [String] :description Same as label, but more detailed
+    #   @option [*] :default Default value for option
+    #   @option [String,Symbol,Array<String,Symbol,Hash>,Hash] :from Resolver origins
+    #   @option [String,Symbol,Array<String,Symbol,Hash>,Hash] :to Setter targets
+    #   @option [String,Symbol,Array<String,Symbol,Hash>,Hash] :skip_if Conditionals that define if this option should be skipped
+    #   @option [String,Symbol,Array<String,Symbol,Hash>,Hash] :only_if Conditionals that define if this option should be included
+    #   @option [Opto::Group] :group Parent group reference
+    #   @option [...] Type definition options, such as { min_length: 3, strip: true }
+    #
+    # @example Create an option
+    #   Opto::Option.new(
+    #     name: 'cat_name',
+    #     type: 'string',
+    #     label: 'Name of your Cat',
+    #     required: true,
+    #     description: 'Enter a name for your cat',
+    #     from:
+    #       env: 'CAT_NAME'
+    #     only_if: 
+    #       pet: 'cat'
+    #     min_length: 2
+    #     max_length: 20
+    #   )
+    #
+    # @example Create a random string
+    #   Opto::Option.new(
+    #     name: 'random_string',
+    #     type: :string,
+    #     from:
+    #       random_string:
+    #         length: 20
+    #         charset: ascii_printable
+    #   )
+    def initialize(options = {})
+      opts           = options.dup
+
+      @group         = opts.delete(:group)
+      if @group && @group.defaults
+        opts = @group.defaults.reject{|k,_| [:from, :to].include?(k)}.merge(opts)
+      end
+
+      @name          = opts.delete(:name).to_s
+
+      type           = opts.delete(:type)
+      @type          = type.to_s.snakecase unless type.nil?
+
+      @label         = opts.delete(:label) || @name
+      @description   = opts.delete(:description)
+      @default       = opts.delete(:default)
+      val            = opts.delete(:value)
+      @skip_if       = opts.delete(:skip_if)
+      @only_if       = opts.delete(:only_if)
+      @skip_lambdas  = normalize_ifs(@skip_if)
+      @only_lambdas  = normalize_ifs(@only_if)
+      @from          = { default: self }.merge(normalize_from_to(opts.delete(:from)))
+      @to            = normalize_from_to(opts.delete(:to))
+      @type_options  = opts
+
+      set_initial(val) if val
+      deep_merge_defaults
+    end
+
+    def deep_merge_defaults
+      return nil unless group && group.defaults
+      if group.defaults[:from]
+        normalize_from_to(group.defaults[:from]).each do |k,v|
+          from[k] ||= v
+        end
+      end
+      if group.defaults[:to]
+        normalize_from_to(group.defaults[:to]).each do |k,v|
+          to[k] ||= v
+        end
+      end
+    end
+
+    # Hash representation of Opto::Option. Can be passed back to Opto::Option.new
+    # @param [Boolean] with_errors Include possible validation errors hash
+    # @param [Boolean] with_value Include current value
+    # @return [Hash]
+    def to_h(with_errors: false, with_value: true)
+      hash = {
+        name: name,
+        label: label,
+        type: type,
+        description: description,
+        default: default,
+        from: from.reject { |k,_| k == :default},
+        to: to
+      }.merge(type_options).reject { |_,v| v.nil? }
+      hash[:skip_if] = skip_if if skip_if
+      hash[:only_if] = only_if if only_if
+      hash[:errors]  = errors  if with_errors
+      hash[:value]   = value   if with_value
+      hash
+    end
+
+    # Set option value. Also aliased as #value=
+    # @param value
+    def set(value)
+      @value = handler.sanitize(value)
+      validate
+      @value
+    end
+
+    alias_method :value=, :set
+
+    # Returns true if this field should not be processed because of the conditionals
+    # @return [Boolean]
+    def skip?
+      return true if     @skip_lambdas.any? { |s| s.call(self) }
+      return true unless @only_lambdas.all? { |s| s.call(self) }
+      false
+    end
+
+    # Get a value of another Opto::Group member
+    # @param [String] option_name
+    def value_of(option_name)
+      group.nil? ? nil : group.value_of(option_name)
+    end
+
+    # Run validators
+    # @raise [TypeError, ArgumentError]
+    def validate
+      handler.validate(@value)
+    rescue StandardError => ex
+      raise ex, "Validation for #{name} : #{ex.message}"
+    end
+
+    # Access the Opto::Type handler for this option
+    # @return [Opto::Type]
+    def handler
+      @handler ||= Type.for(type).new(type_options)
+    end
+
+    # The value of this option. Will try to run resolvers.
+    # @return option_value
+    def value
+      return @value unless @value.nil?
+      return nil if skip?
+      set(resolve)
+      @value
+    end
+
+    # Accessor to defined resolvers for this option.
+    # @return [Array<Opto::Resolver>]
+    def resolvers
+      @resolvers ||= from.map { |origin, hint| Resolver.for(origin).new(hint, self) }
+    end
+
+    def setters
+      @setters ||= to.map { |target, hint| Setter.for(target).new(hint, self) }
+    end
+
+    # True if this field is defined as required: true
+    # @return [Boolean]
+    def required?
+      handler.required?
+    end
+
+    # Run resolvers
+    # @raise [TypeError, ArgumentError]
+    def resolve
+      resolvers.each do |resolver|
+        begin
+          resolver.respond_to?(:before) && resolver.before(self)
+          result = resolver.resolve
+          resolver.respond_to?(:after) && resolver.after(self)
+        rescue StandardError => ex
+          raise ex, "Resolver '#{resolver.origin}' for '#{name}' : #{ex.message}"
+        end
+        if result
+          @origin = resolver.origin
+          return result
+        end
+      end
+      nil
+    end
+
+    # Run setters
+    def output
+      setters.each do |setter|
+        begin
+          setter.respond_to?(:before) && setter.before(self)
+          setter.set(value)
+          setter.respond_to?(:after)  && setter.after(self)
+        rescue StandardError => ex
+          raise ex, "Setter '#{setter.target}' for '#{name}' : #{ex.message}"
+        end
+      end
+    end
+
+    # True if value is valid
+    # @return [Boolean]
+    def valid?
+      return true if skip?
+      handler.valid?(value)
+    end
+
+    # Validation errors
+    # @return [Hash]
+    def errors
+      handler.errors
+    end
+
+    def normalize_ifs(ifs)
+      case ifs
+      when NilClass
+        []
+      when Array
+        ifs.map do |iff|
+          lambda { |opt| !opt.value_of(iff).nil? }
+        end
+      when Hash
+        ifs.each_with_object([]) do |(k, v), arr|
+          arr << lambda { |opt| opt.value_of(k.to_s) == v }
+        end
+      when String, Symbol
+        [lambda { |opt| !opt.value_of(ifs.to_s).nil? }]
+      else
+        raise TypeError, "Invalid syntax for if"
+      end
+    end
+
+    def normalize_from_to(inputs)
+      case inputs
+      when Array
+        case inputs.first
+        when String, Symbol
+          inputs.each_with_object({}) { |o, hash| hash[o.to_s.snakecase.to_sym] = name }
+        when Hash
+          inputs.each_with_object({}) { |o, hash| o.each { |k,v| hash[k.to_s.snakecase.to_sym] = v } }
+        when NilClass
+          {}
+        else
+          raise TypeError, "Invalid format #{inputs.inspect}"
+        end
+      when Hash
+        inputs.each_with_object({}) { |(k, v), hash| hash[k.to_s.snakecase.to_sym] = v }
+      when String, Symbol
+        { inputs.to_s.snakecase.to_sym => name }
+      when NilClass
+        {}
+      else
+        raise TypeError, "Invalid format #{inputs.inspect}"
+      end
+    end
+
+    private
+
+    def set_initial(value)
+      return nil if value.nil?
+      @origin = :initial
+      set(value)
+    end
+  end
+end