opto 1.4.0

data/lib/opto/resolver.rb

@@ -0,0 +1,65 @@
+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
+  # Base for resolvers.
+  #
+  # Resolvers are scripts that can retrieve or generate a value for an option.
+  # Such resolvers are for example Env, which can try to find the value for
+  # the option from an environment variable. An example of generators is
+  # RandomString, which can generate random strings of defined length.
+  class Resolver
+
+    using Opto::Extension::SnakeCase unless RUBY_VERSION < '2.1'
+
+    attr_accessor :hint
+    attr_accessor :option
+
+    class << self
+      # Find a resolver using an origin_name definition, such as :env or :file
+      # @param [Symbol, String] origin
+      def for(origin)
+        raise NameError, "Unknown resolver: #{origin}" unless resolvers[origin]
+        resolvers[origin]
+      end
+
+      def inherited(where)
+        resolvers[where.origin] = where
+      end
+
+      def resolvers
+        @resolvers ||= {}
+      end
+
+      def origin
+        name.to_s.split('::').last.snakecase.to_sym
+      end
+    end
+
+    # Initialize an instance of a resolver.
+    # @param hint A "hint" for the resolver, for example. the environment variable name or a set of rules for generators.
+    # @param [Opto::Option] option The option parent of this resolver instance
+    # @return [Opto::Resolver]
+    def initialize(hint = nil, option = nil)
+      @hint = hint
+      @option = option
+    end
+
+    # This is a "base" class, you're supposed to inherit from this in your resolver and define a #resolve method.
+    def resolve
+      raise RuntimeError, "#{self.class}.resolve not defined"
+    end
+
+    # The origin "tag" of this resolver, for example: 'random_string' or 'env'
+    def origin
+      self.class.origin
+    end
+  end
+end
+
+Dir[File.expand_path('../resolvers/*.rb', __FILE__)].each {|file| require file}

data/lib/opto/resolvers/default.rb

@@ -0,0 +1,10 @@
+module Opto
+  module Resolvers
+    # Resolve a value through the default value defined during option initialization
+    class Default < Opto::Resolver
+      def resolve
+        hint.default
+      end
+    end
+  end
+end

data/lib/opto/resolvers/environment_variable.rb

@@ -0,0 +1,25 @@
+module Opto
+  module Resolvers
+    # Find a value using Environment.
+    #
+    # Hint should be a name of environment variable, such as 'HOME'
+    #
+    # Numbers will be converted to fixnums, "true" and "false" will be converted to booleans.
+    class Env < Opto::Resolver
+
+      def resolve
+        raise ArgumentError, "Environment variable name not set" if hint.nil?
+        val = ENV[hint.to_s]
+        return nil if val.nil?
+        case val
+        when /\A\d+\z/ then val.to_i
+        when /\Atrue\z/ then true
+        when /\Afalse\z/ then false
+        when /\A(?:null|nil)\z/ then nil
+        else val
+        end
+      end
+    end
+  end
+end
+

data/lib/opto/resolvers/file_content.rb

@@ -0,0 +1,32 @@
+module Opto
+  module Resolvers
+    # Read the value from a file, path defined in hint.
+    class File < Opto::Resolver
+
+      def ignore_errors?
+        return false unless hint.kind_of?(Hash) && (hint['ignore_errors'] || hint[:ignore_errors])
+      end
+
+      def file_path
+        if hint.kind_of?(String)
+          hint
+        elsif hint.kind_of?(Hash) && (hint['path'] || hint[:path])
+          hint['path'] || hint[:path]
+        else
+          raise ArgumentError, "File path not set"
+        end
+      end
+
+      def resolve
+        if ignore_errors?
+          file_path
+          ::File.read(file_path) rescue nil
+        else
+          ::File.read(file_path)
+        end
+      end
+    end
+  end
+end
+
+

data/lib/opto/resolvers/random_number.rb

@@ -0,0 +1,35 @@
+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
+  module Resolvers
+    # Geneerate a new random number. Requires :min and :max in hint to define range.
+    class RandomNumber < Opto::Resolver
+
+      using Opto::Extension::HashStringOrSymbolKey unless RUBY_VERSION < '2.1'
+
+      def resolve
+        raise ArgumentError, "Range not set" if hint.nil?
+
+        unless hint.kind_of?(Hash)
+          raise TypeError, "Range invalid, define min: and max: using hash syntax"
+        end
+
+        unless hint[:min]
+          raise ArgumentError, "Range definition missing :min"
+        end
+
+        unless hint[:max]
+          raise ArgumentError, "Range definition missing :max"
+        end
+
+        rand(hint[:min]..hint[:max])
+      end
+    end
+  end
+end

data/lib/opto/resolvers/random_string.rb

@@ -0,0 +1,84 @@
+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
+  module Resolvers
+    # Generates a random string.
+    #
+    # Requires at least  :length. 
+    # Also accepts :charset which can be one of: 
+    # - numbers (0-9), 
+    # - letters (a-z + A-Z), 
+    # - downcase (a-z), 
+    # - upcase (A-Z),
+    # - alphanumeric (0-9 + a-z + A-Z), 
+    # - hex (0-9 + a-f), 
+    # - hex_upcase (0-9 + A-F), 
+    # - base64 (base64 charset (length has to be divisible by four when using base64)),
+    #-  ascii_printable (all printable ascii chars)
+    # - or a set of characters, for example:
+    #   { length: 8, charset: '01' }  Will generate something like:  01001100
+    class RandomString < Opto::Resolver
+
+      using Opto::Extension::HashStringOrSymbolKey unless RUBY_VERSION < '2.1'
+
+      def charset(name)
+        case name.to_s
+        when 'numbers'
+          (0..9).map(&:to_s)
+        when /\A\d+\-\d+\z/, /\A[a-z]\-[a-z]\z/
+          from, to = name.split('-')
+          (from..to).map(&:to_s)
+        when 'letters'
+          charset('upcase') + charset('downcase')
+        when 'downcase'
+          ('a'..'z').to_a
+        when 'upcase'
+          ('A'..'Z').to_a
+        when 'alphanumeric'
+          charset('letters') + charset('numbers')
+        when 'hex'
+          charset('numbers') + ('a'..'f').to_a
+        when 'hex_upcase'
+          charset('numbers') + ('A'..'F').to_a
+        when 'base64'
+          charset('alphanumeric') + ['+', '/']
+        when 'ascii_printable'
+          (33..126).map {|ord| ord.chr}
+        else
+          name.to_s.split('')
+        end
+      end
+
+      def resolve
+        if hint.kind_of?(Hash) 
+          if hint[:length].nil?
+            raise ArgumentError, "Invalid settings for random string. Required: length, optional: charset. Charsets : numbers, letters, alphanumeric, hex, base64, ascii_printable and X-Y range."
+          end
+        elsif (hint.kind_of?(String) && hint.to_i > 0) || hint.kind_of?(Fixnum)
+          self.hint = { length: hint.to_i }
+        else
+          raise ArgumentError, "Missing settings for random string."
+        end
+
+        if hint[:charset].to_s == 'base64' && hint[:length] % 4 != 0
+          raise ArgumentError, "Length must be divisible by 4 when using base64"
+        end
+
+        chars = charset(hint[:charset] || 'alphanumeric')
+        (1..hint[:length].to_i).each_with_object('') do |_, str|
+          str << chars.sample
+        end
+      end
+    end
+  end
+end
+
+
+
+

data/lib/opto/resolvers/random_uuid.rb

@@ -0,0 +1,15 @@
+require 'securerandom'
+
+module Opto
+  module Resolvers
+    # Generates a UUID, such as "b379de07-3324-44b1-a5f3-8617ed1b41ea"
+    class RandomUuid < Opto::Resolver
+      def resolve
+        SecureRandom.uuid
+      end
+    end
+  end
+end
+
+
+

data/lib/opto/setter.rb

@@ -0,0 +1,66 @@
+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
+  # Base for Setters.
+  #
+  # Resolvers are scripts that can retrieve or generate a value for an option.
+  # Such resolvers are for example Env, which can try to find the value for
+  # the option from an environment variable. An example of generators is
+  # RandomString, which can generate random strings of defined length.
+  class Setter
+
+    using Opto::Extension::SnakeCase unless RUBY_VERSION < '2.1'
+
+    attr_accessor :hint
+    attr_accessor :option
+
+    class << self
+      # Find a setter using a target_name definition, such as :env or :file
+      # @param [Symbol, String] target
+      def for(target)
+        raise NameError, "Unknown setter: #{target}" unless targets[target]
+        targets[target]
+      end
+
+      def inherited(where)
+        targets[where.target] = where
+      end
+
+      def targets
+        @targets ||= {}
+      end
+
+      def target
+        name.to_s.split('::').last.snakecase.to_sym
+      end
+    end
+
+    # Initialize an instance of a setter.
+    # @param hint A "hint" for the setter, for example. the environment variable name
+    # @param [Opto::Option] option The option parent of this resolver instance
+    # @return [Opto::Resolver]
+    def initialize(hint = nil, option = nil)
+      @hint = hint
+      @option = option
+    end
+
+    # This is a "base" class, you're supposed to inherit from this in your setter and define a #set method.
+    def set(value)
+      raise RuntimeError, "#{self.class}.set not defined"
+    end
+
+    # The target "tag" of this resolver, for example: 'file' or 'env'
+    def target
+      self.class.target
+    end
+  end
+end
+
+Dir[File.expand_path('../setters/*.rb', __FILE__)].each {|file| require file}
+

data/lib/opto/setters/environment_variable.rb

@@ -0,0 +1,40 @@
+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
+  module Setters
+    # Set a value to environment.
+    #
+    # Hint should be a name of environment variable, such as 'HOME'
+    #
+    # Everything will be converted to strings unless hint is a hash with :options. (also include :name in that case)
+    class Env < Opto::Setter
+
+      using Opto::Extension::HashStringOrSymbolKey unless RUBY_VERSION < '2.1'
+
+      attr_accessor :env_name, :dont_stringify
+
+      def normalize_hint
+        raise ArgumentError, "Environment variable name not set" if hint.nil?
+        if hint.kind_of?(Hash)
+          raise ArgumentError, "Environment variable name not set" unless hint[:name]
+          @env_name = hint[:name].to_s
+        else
+          @env_name = hint.to_s
+        end
+      end
+
+      def set(value)
+        normalize_hint
+        ENV[env_name] = value.to_s
+      end
+    end
+  end
+end
+
+

data/lib/opto/type.rb

@@ -0,0 +1,148 @@
+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
+  # Defines a type handler. Used as a base from which to inherit in the type handlers.
+  class Type
+    GLOBAL_OPTIONS = {
+      required: true
+    }
+
+    attr_accessor :options
+
+    unless RUBY_VERSION < '2.1'
+      using Opto::Extension::SnakeCase
+      using Opto::Extension::HashStringOrSymbolKey
+    end
+
+    class << self
+      def inherited(where)
+        types[where.type] = where
+      end
+
+      def types
+        @types ||= {}
+      end
+
+      def type
+        name.to_s.split('::').last.snakecase.to_sym
+      end
+
+      # Find a type handler for :type_name, for example: Opto::Type.for(:string)
+      # @param [String,Symbol] type_name
+      def for(type_name)
+        raise NameError, "No handler for type #{type_name}" unless types[type_name]
+        types[type_name]
+      end
+
+      def validators
+        @validators ||= []
+      end
+
+      # Define a validator:
+      # @example
+      #   class Foo < Opto::Type
+      #     validator :is_foo do |value|
+      #       unless value == 'foo'
+      #         "Foo is not foo."
+      #        end
+      #     end
+      #   end
+      def validator(name, &block)
+        raise TypeError, "Block required" unless block_given?
+        define_method("validate_#{name}", &block)
+        validators << "validate_#{name}".to_sym
+        # RUBY_VERSION >= 2.1 would allow validators << define_method("validate_#{name}", block)
+      end
+
+      def sanitizers
+        @sanitizers ||= []
+      end
+
+      # Define a sanitizer. Can be used to for example convert strings to integers
+      # or to remove whitespace, etc.
+      #
+      # @example
+      #   class Foo < Opto::Type
+      #     sanitizer :add_suffix |value|
+      #       value.to_s + "-1"
+      #     end
+      #   end
+      def sanitizer(name, &block)
+        raise TypeError, "Block required" unless block_given?
+        define_method("sanitize_#{name}", &block)
+        sanitizers << "sanitize_#{name}".to_sym
+      end
+    end
+
+    # The default :in validator, returns an error unless the
+    # value is not one of listed in the :in definition of the option,
+    # @example
+    #   Opto::Option.new(name: 'foo', type: 'string', in: ['dog', 'cat']) (only "dog" or "cat" allowed as value)
+    validator :in do |value|
+      return true unless options[:in]
+      options[:in].each do |val|
+        return true if value === val
+      end
+      "Value #{value} not in #{options[:in].join(', ')}"
+    end
+
+    def initialize(options = {})
+      @options = Type::GLOBAL_OPTIONS.merge(self.class.const_defined?(:OPTIONS) ? self.class.const_get(:OPTIONS) : {}).merge(options)
+    end
+
+    def type
+      self.class.type
+    end
+
+    def required?
+      !!options[:required]
+    end
+
+    def sanitize(value)
+      new_value = value
+      self.class.sanitizers.each do |sanitizer|
+        begin
+          new_value = self.send(sanitizer, new_value)
+        rescue StandardError => ex
+          raise ex, "Sanitizer #{sanitizer} : #{ex.message}"
+        end
+      end
+      new_value
+    end
+
+    def errors
+      @errors ||= {}
+    end
+
+    def valid?(value)
+      validate(value)
+      errors.empty?
+    end
+
+    def validate(value)
+      errors.clear
+      if value.nil?
+        errors[:presence] = "Required value missing" if required? 
+      else
+        (Type.validators + self.class.validators).each do |validator|
+          begin
+            result = self.send(validator, value)
+          rescue StandardError => ex
+            raise ex, "Validator #{validator} : #{ex.message}"
+          end
+          unless result.kind_of?(NilClass) || result.kind_of?(TrueClass)
+            errors[validator] = result
+          end
+        end
+      end
+    end
+  end
+end
+
+Dir[File.expand_path('../types/*.rb', __FILE__)].each {|file| require file}