qb 0.3.25 → 0.4.0

data/lib/qb/options/option.rb

@@ -1,131 +1,309 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# ========================================================================
+
+# Deps
+# ------------------------------------------------------------------------
+
+# Need {Module#concerning}
+require 'active_support/core_ext/module/concerning'
+
+# Project / Package
+# ------------------------------------------------------------------------
+
+# Need additional {QB::Options::Types} for option type loading
+require_relative './types'
+
+# Need {OptionParserConcern} to handle fucking {OptionParser} :(
+require_relative './option/option_parser_concern'
+
+
+# Refinements
+# ========================================================================
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+require 'nrser/refinements/sugar'
+using NRSER::Sugar
+
+
+# Definitions
+# ========================================================================
+
 module QB
-  class Options
-    class Option
-      EXAMPLES_KEYS = ['examples', 'example']
+class Options
+class Option
+  
+  # Constants
+  # ========================================================================
+  
+  EXAMPLES_KEYS = ['examples', 'example']
+  
+  
+  # Mixins
+  # ============================================================================
+  
+  include NRSER::Log::Mixin
+  
+  include OptionParserConcern
+  
+  
+  # Attributes
+  # ========================================================================
+  
+  # the role that this option is for
+  attr_reader :role
+  
+  # array of strings representing how this option was included
+  # empty for top-level options
+  attr_reader :include_path
+  
+  # the name of the option in the qb metadata, equal to #meta['name']
+  attr_reader :meta_name
+  
+  # the name that this option will be available in the cli as
+  attr_reader :cli_name
+  
+  # the name that the value will be passed to ansible as
+  attr_reader :var_name
+  
+  # the value of the option, or `nil` if we never assign one
+  attr_accessor :value
+  
+  
+  # TODO document `type` attribute.
+  # 
+  # @return [attr_type]
+  #     
+  attr_reader :type
+  
+  
+  # Construction
+  # ======================================================================
+  
+  def initialize role, meta, include_path
+    @role = role
+    @meta = meta.with_indifferent_access
+    @include_path = include_path
+    
+    @meta_name = meta.fetch 'name'
+    
+    @cli_name = if @include_path.empty?
+      QB::Options.cli_ize_name @meta_name
+    else
+      QB::Options.cli_ize_name "#{ @include_path.join('-') }-#{ @meta_name }"
+    end
+    
+    @var_name = if meta[:var_name]
+      # prefer an explicit, exact variable name if provided
+      meta[:var_name]
+    elsif role.var_prefix
+      QB::Options.var_ize_name "#{ role.var_prefix }_#{ meta_name }"
+    else
+      QB::Options.var_ize_name meta_name
+    end
+    
+    # Will be set when we find it out!
+    @value = nil
+    
+    # Initialize `@type` var
+    init_type!
+  end
+  
+  
+  protected
+  # ========================================================================
+    
+    # Initialize `@type` to the {NRSER::Types::Type} loaded from the option
+    # meta's `type` value.
+    # 
+    # @protected
+    # 
+    # @return [nil]
+    # 
+    def init_type!
+      type_meta = meta[:type]
       
-      # the role that this option is for
-      # attr_reader :role
-      
-      # the entry from the qb metadata for this option
-      attr_reader :meta
-      
-      # array of strings representing how this option was included
-      # empty for top-level options
-      attr_reader :include_path
-      
-      # the name of the option in the qb metadata, equal to #meta['name']
-      attr_reader :meta_name
-      
-      # the name that this option will be available in the cli as
-      attr_reader :cli_name
-      
-      # the name that the value will be passed to ansible as
-      attr_reader :var_name
-      
-      # the value of the option, or `nil` if we never assign one
-      attr_accessor :value
+      if type_meta.nil?
+        raise QB::Role::MetadataError.new \
+          "Option", meta_name, "for role", role.name, "missing `type`",
+          role_meta_path: role.meta_path,
+          option_meta: meta
+      end
       
-      def initialize role, meta, include_path
-        # @role = WeakRef.new role
-        @meta = meta
-        @include_path = include_path
+      if  t.non_empty_str === type_meta &&
+          type_meta.include?( '::' )
         
-        @meta_name = meta.fetch 'name'
+        const = type_meta.safe_constantize
         
-        @cli_name = if @include_path.empty?
-          Options.cli_ize_name @meta_name
-        else
-          Options.cli_ize_name "#{ @include_path.join('-') }-#{ @meta_name }"
+        if  const &&
+            const.is_a?( Class ) &&
+            ( const < NRSER::Types::Type ||
+              const < NRSER::Props )
+          @type = const
+          return
         end
         
-        @var_name = if @meta['var_name']
-          # prefer an explicit, exact variable name if provided
-          @meta['var_name']
-        elsif role.var_prefix
-          Options.var_ize_name "#{ role.var_prefix }_#{ @meta_name }"
-        else
-          Options.var_ize_name @meta_name
-        end
-        
-        @value = nil
-      end
-      
-      # if the option is required in the cli
-      def required?
-        !!meta_or(['required', 'require'], false)
       end
       
-      # if we should save the option value in .qb-options.yml
-      def save?
-        !!meta_or('save', true)
-      end
-      
-      def description
-        value = meta_or 'description',
-          "set the #{ @var_name } role variable"
+      message = t.match type_meta,
+        t.non_empty_str, ->( str ) {
+          NRSER::Message.new str
+        },
         
-        line_break = "\n" + "\t" * 5
+        t.pair( value: (t.hash_ | t.array) ), ->( hash_pair ) {
+          name, params = hash_pair.first
           
-        if @meta['type'].is_a?(Hash) && @meta['type'].key?('one_of')
-          value += " options:" + 
-            "#{ line_break }#{ @meta['type']['one_of'].join(line_break) }"
-        end
-        
-        value
-      end
-      
-      def boolean?
-        (
-          meta['type'].is_a?(String) &&
-          ['boolean', 'bool'].include?(meta['type'].downcase)
-        )
-      end
-      
-      def usage
-        if boolean?
-          "--[no-]#{ cli_name }"
-        else
-          "--#{ cli_name }=#{ meta_name.upcase }"
-        end
-      end
-      
-      # test if the option has any examples.
-      # 
-      # @return [Boolean]
-      # 
-      def has_examples?
-        EXAMPLES_KEYS.any? {|key| meta.key? key}
-      end
-      
-      # get an array of examples for the option. returns `[]` if no examples
-      # are defined.
-      # 
-      # @return [Array<String>]
-      # 
-      def examples
-        value = meta_or EXAMPLES_KEYS, []
-        
-        if value.is_a? String then [value] else value end
-      end
+          NRSER::Message.from( name, params ).symbolize_options
+        }
       
-      
-      private
-      
-      # get the value at the first found of the keys or the default.
-      # 
-      # `nil` (`null` in yaml files) are treated like they're not there at
-      # all. you need to use `false` if you want to tell QB not to do something.
-      # 
-      def meta_or keys, default
-        keys = [keys] if keys.is_a? String
-        keys.each do |key|
-          if meta.key?(key) && !meta[key].nil?
-            return meta[key]
+      @type = [
+        QB::Options::Types,
+        t,
+      ].find_map { |mod|
+        if mod.respond_to? message.symbol
+          begin
+            type = message.send_to mod
+          rescue Exception => error
+            logger.warn "Type factory failed",
+              { message: message },
+              error
+            
+            nil
+          else
+            type if type.is_a?( t::Type )
           end
         end
-        default
+      }
+      
+      if @type.nil?
+        raise QB::Role::MetadataError.new \
+          "Unable to find type factory for", type_meta,
+          role_meta_path: role.meta_path,
+          option_meta: meta,
+          message: message
       end
       
-    end # Option
-  end # Options
-end # QB
+    end # #init_type!
+    
+  public # end protected *****************************************************
+  
+  
+  # Instance Methods
+  # ========================================================================
+  
+  def meta *keys, type: t.any, default: nil
+    return @meta if keys.empty?
+    
+    keys.each do |key|
+      return type.check!( @meta[key] ) unless @meta[key].nil?
+    end
+    
+    type.check! default
+  end
+  
+  
+  def meta? *keys
+    keys.any? { |key| @meta.key? key }
+  end
+  
+  
+  def value_data
+    if value.respond_to? :to_data
+      value.to_data
+    else
+      value
+    end
+  end
+  
+  
+  # Is the option is required in the CLI?
+  # 
+  # @return [Boolean]
+  # 
+  def required?
+    meta :required, :require, type: t.bool, default: false
+  end
+  
+  
+  # Should we save the option value in `./.qb-options.yml`?
+  # 
+  # @return [Boolean]
+  # 
+  def save?
+    meta :save, type: t.bool, default: true
+  end
+  
+  
+  # Description of the option.
+  # 
+  # @return [String]
+  # 
+  def description
+    meta(
+      :description,
+      default: "Set the #{ @var_name } role variable"
+    ).to_s
+  end
+  
+  
+  def boolean?
+    type == t.bool
+  end
+  
+  
+  def usage
+    if boolean?
+      "--[no-]#{ cli_name }"
+    else
+      "--#{ cli_name }=#{ meta_name.upcase }"
+    end
+  end
+  
+  
+  # test if the option has any examples.
+  # 
+  # @return [Boolean]
+  # 
+  def has_examples?
+    meta? *EXAMPLES_KEYS
+  end
+  
+  # get an array of examples for the option. returns `[]` if no examples
+  # are defined.
+  # 
+  # @return [Array<String>]
+  # 
+  def examples
+    Array meta( *EXAMPLES_KEYS, type: (t.nil | t.str | t.array( t.str )) )
+  end
+  
+  
+  # Does the option accept `false` as value?
+  # 
+  # If it does, and is not a boolean option, we also accept a `--no-<name>`
+  # option format to set the value to `false`.
+  # 
+  # This is useful to explicitly tell QB "no, I don't want this", since we
+  # treat `nil`/`null` as the same as absent, which will cause a
+  # default value to be used (if available).
+  # 
+  # This feature does not apply to {#boolean?} options themselves, only options
+  # that accept other values (though this method will of course return `true`
+  # for {#boolean?} options, since they do accept `false`).
+  # 
+  # @return [Boolean]
+  # 
+  def accept_false?
+    return true if meta[:accept_false]
+    
+    return false if type.is_a?( Class ) && type < NRSER::Props
+    
+    type.test?( false )
+  end
+  
+  
+end; end; end # class QB::Options::Option

data/lib/qb/options/option/option_parser_concern.rb

@@ -0,0 +1,228 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Requirements
+# =======================================================================
+
+# Deps
+# -----------------------------------------------------------------------
+
+# Need {ActiveSupport::Concern} duh
+require 'active_support/concern'
+
+
+# Project / Package
+# -----------------------------------------------------------------------
+
+require 'qb/util'
+
+# Refinements
+# =======================================================================
+
+require 'nrser/refinements/types'
+using NRSER::Types
+
+require 'nrser/refinements/sugar'
+using NRSER::Sugar
+
+
+# Definitions
+# =======================================================================
+
+module  QB
+class   Options
+class   Option
+module  OptionParserConcern
+  
+  extend ActiveSupport::Concern
+  extend ::MethodDecorators
+  
+  include NRSER::Log::Mixin
+  
+  class TypeAcceptable
+    def self.name
+      if self == TypeAcceptable
+        "TypeAcceptable"
+      else
+        "TypeAcceptable<#{ type }>"
+      end
+    end
+    
+    singleton_class.send :alias_method, :to_s, :name
+    singleton_class.send :alias_method, :inspect, :name
+    
+    def self.type
+      @type
+    end
+    
+    def self.parse string
+      type.from_s string
+    end
+  end
+  
+  
+  def option_parser_spacer
+    ' '
+  end
+  
+  
+  def option_parser_type_acceptable
+    acceptable = Class.new TypeAcceptable
+    acceptable.instance_variable_set :@type, self.type
+    acceptable
+  end
+  
+  
+  def option_parser_value_name
+    meta_name.upcase
+  end
+  
+  
+  +QB::Util::Decorators::EnumFor
+  def option_parser_format_multiline string, &block
+    lines = string.lines.to_a
+    
+    lines.map do |line|
+      yield case line
+      when "\n"
+        # Need a space for {OptionParser} to respect it
+        option_parser_spacer + line
+      when /\A\s*\-\ /
+        line.sub '-', '*'
+      else
+        line
+      end
+    end
+    
+    yield option_parser_spacer if lines.length > 1
+  end
+  
+  
+  +QB::Util::Decorators::EnumFor
+  def option_parser_description &block
+    option_parser_format_multiline description, &block
+  end
+  
+  
+  +QB::Util::Decorators::EnumFor
+  def option_parser_bool_args included:, &block
+    # Don't use short names when included (for now)
+    if !included && meta[:short]
+      yield "-#{ meta[:short] }"
+    end
+    
+    yield "--[no-]#{ cli_name }"
+  end
+  
+  
+  +QB::Util::Decorators::EnumFor
+  def option_parser_non_bool_args included:, &block
+    # don't use short names when included (for now)
+    if !included && meta[:short]
+      yield "-#{ meta[:short] } #{ option_parser_value_name }"
+    end
+    
+    # We allow options to also accept
+    if accept_false?
+      yield "--[no-]#{ cli_name }=#{ option_parser_value_name }"
+    else
+      yield "--#{ cli_name }=#{ option_parser_value_name }"
+    end
+    
+    yield option_parser_type_acceptable
+  end
+  
+  
+  +QB::Util::Decorators::EnumFor
+  def option_parser_default &block
+    ans_src_default = role.defaults[var_name]
+    
+    # If we don't have shit in the role default Ansible source file, nothing
+    # to do here
+    return if ans_src_default.nil?
+    
+    if boolean?
+      yield "DEFAULT: --#{ ans_src_default ? '' : 'no-' }#{ cli_name }"
+    else
+      # This is just the Ansible "source code", which is shitty and ugly
+      # for anything that's not a literal, but it at least gives you something
+      # to see
+      option_parser_format_multiline "DEFAULT: #{ ans_src_default }", &block
+    end
+  end
+  
+  
+  +QB::Util::Decorators::EnumFor
+  def option_parser_examples &block
+    return unless has_examples?
+    
+    yield 'Examples:'
+    
+    examples.each_with_index do |example, index|
+      lines = example.lines.to_a
+      
+      yield ((index + 1).to_s + '.').ljust(4) + lines.first.chomp
+      
+      lines[1..-1].each do |line|
+        yield " ".ljust(4) + line.chomp
+      end
+    end
+  end
+  
+  
+  +QB::Util::Decorators::EnumFor
+  def option_parser_type &block
+    option_parser_format_multiline "TYPE: #{ type }", &block
+  end
+  
+  
+  +QB::Util::Decorators::EnumFor
+  def option_parser_args included:, &block
+    if boolean?
+      option_parser_bool_args included: included, &block
+    else
+      option_parser_non_bool_args included: included, &block
+    end
+    
+    option_parser_description &block
+    
+    yield "REQUIRED." if required?
+    
+    option_parser_type &block
+    
+    option_parser_default &block
+    
+    option_parser_examples &block
+    
+    yield option_parser_spacer
+    
+  end
+  
+  
+  def option_parser_add option_parser, included:
+    args = option_parser_args( included: included ).to_a
+    
+    args.find do |arg|
+      if arg.is_a?( Class )
+        option_parser.accept( arg ) do |value|
+          arg.parse value
+        end
+        
+        true
+      end
+    end
+    
+    logger.trace "Adding option to {OptionParser}",
+      option_meta_name: meta_name,
+      args: args
+    
+    option_parser.on( *args ) do |value|
+      logger.debug "Setting option value",
+        option_meta_name: meta_name,
+        value: value
+      
+      self.value = value
+    end
+  end
+  
+end; end; end; end # module QB::Options::Option::OptionParserConcern