cliffy 0.6.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d9c2a9ac15921ff581a227eaa98bdbe1ac7285841f300dae47cb9e729bdd2f2
+  data.tar.gz: bf08815d09bae712f08f99365f5f9b2608ffe73fd9696fcadaa127c2856206bd
+SHA512:
+  metadata.gz: db28a47f16402d3cdf1a846d8077f72228964043936ef2684a3d6f8fd89f7c051fc13a682c8d08032fe1490bf75bc0e52616661efedba25f30a4e57bc2189c5a
+  data.tar.gz: 57e0dfde41e33c0e7cee5b61824e65562341fb12500db7aa7f3c8f525194264100ee37d59e2621e20f2135bf559826d9de6c0a20060cc6551c9e1d4e7a72693b

data/lib/cliffy/api.rb

@@ -0,0 +1,135 @@
+require 'set'
+require_relative 'internal/wrapper'
+
+module Cliffy
+  def self.run *commands, arguments: ARGV, help_points: []
+    service = Service.new commands, arguments, help_points, method(:abort), method(:puts)
+    service.run
+  end
+
+  class Service
+    def initialize commands, arguments, help_points, abort_method, puts_method
+      @commands = commands
+      @arguments = arguments
+      @help_points = help_points
+      @abort_method = abort_method
+      @puts_method = puts_method
+    end
+
+    def run
+      begin
+        validate_commands
+        if @arguments.empty?
+          show_usage
+        elsif @arguments.first == 'help'
+          show_help
+        else
+          run_command
+        end
+      rescue => e
+        @abort_method.call e.to_s
+      end
+      nil
+    end
+
+    private
+
+    # Run Methods
+
+    def validate_commands
+      command_names = Set.new
+      wrappers.each do |wrapper|
+        command_name = wrapper.command_name
+        if command_names.include? command_name
+          raise "Found more than one command called '#{command_name}'."
+        end
+        command_names << command_name
+        wrapper.validate
+      end
+    end
+
+    def show_usage
+      help_content = "Run `#{executable_name} help <command>` for help with a specific command."
+      help_content = [help_content] + @help_points unless @help_points.empty?
+      show_titles_and_contents(
+        'Usage' => "#{executable_name} <command> [arguments]",
+        'Commands' => wrappers.to_h { |wrapper| [wrapper.command_name, wrapper.command_description] },
+        'Help' => help_content
+      )
+    end
+
+    def show_help
+      if @arguments.count == 2
+        wrapper = wrappers.find { |wrapper| wrapper.command_name == @arguments[1] }
+        if wrapper
+          help_data = wrapper.generate_help_data executable_name
+          show_titles_and_contents help_data
+          return
+        end
+      end
+      raise invalid_arguments_message
+    end
+
+    def run_command
+      wrapper = wrappers.find { |wrapper| wrapper.command_name == @arguments.first }
+      if wrapper
+        wrapper.run @arguments[1...], executable_name
+      else
+        raise invalid_arguments_message
+      end
+    end
+
+    # Helpers
+
+    def wrappers
+      unless @wrappers
+        @wrappers = @commands.map { |command| Internal::Wrapper.new command }
+      end
+      @wrappers
+    end
+
+    def executable_name
+      @executable_name ||= File.basename $PROGRAM_NAME
+    end
+
+    def invalid_arguments_message
+      @invalid_arguments_message ||= "Invalid arguments. Run `#{executable_name}` for help."
+    end
+
+    def show_titles_and_contents titles_and_contents
+      key_padding = 0
+      titles_and_contents.each do |title, content|
+        next unless content.is_a? Hash
+        next unless content.count > 0
+        longest_key = content.keys.map(&:length).max
+        key_padding = longest_key if longest_key > key_padding
+      end
+      index_format = "    %-#{key_padding}s    %s"
+      lines = []
+      titles_and_contents.each do |title, content|
+        case content
+        when String then
+          next if content.length < 1
+          lines << "#{title}:"
+          lines << '    ' + content
+        when Array then
+          next if content.count < 1
+          lines << "#{title}:"
+          content.each do |line|
+            lines << '    - ' + line
+          end
+        when Hash then
+          next if content.count < 1
+          lines << "#{title}:"
+          content.each do |key, value|
+            line = sprintf index_format, key, value
+            lines << line
+          end
+        end
+        lines << ''
+      end
+      message = lines.join $/
+      @puts_method.call message
+    end
+  end
+end

data/lib/cliffy/internal/generate_help_data.rb

@@ -0,0 +1,53 @@
+module Cliffy
+  module Internal
+    def self.generate_help_data command, command_name, executable_name
+      usage_tokens = [executable_name, command_name]
+      parameter_names_and_descriptions = {}
+      options_and_descriptions = {}
+      
+      command.method(:run).parameters.each do |parameter|
+        symbol = parameter[1]
+        description = command.signature[symbol][:description]
+        symbol_name = parameter[1].to_s.gsub '_', '-'
+        case parameter.first
+        when :req
+          usage_tokens << "<#{symbol_name}>"
+          parameter_names_and_descriptions[symbol_name] = description
+        when :rest
+          usage_tokens << "<#{symbol_name}...>"
+          parameter_names_and_descriptions[symbol_name] = description
+        when :key
+          option = "--#{symbol_name}"
+          type = command.signature[symbol][:type]
+          case type
+          when :boolean
+            usage_tokens << "[#{option}]"
+          when :integer, :float, :string
+            usage_tokens << "[#{option} value]"
+          when Hash
+            sub_symbol_names = type.keys.map { |sub_symbol| sub_symbol.to_s.gsub '_', '-' }.join ' '
+            usage_tokens << "[#{option} #{sub_symbol_names}]"
+          end
+          
+          options_and_descriptions[option] = description
+        end
+      end
+
+      usage = usage_tokens.join ' '
+      titles_and_contents = {
+        'Description' => command.description,
+        'Usage' => usage
+      }
+      unless parameter_names_and_descriptions.empty?
+        titles_and_contents.merge! 'Parameters' => parameter_names_and_descriptions
+      end
+      unless options_and_descriptions.empty?
+        titles_and_contents.merge! 'Options' => options_and_descriptions
+      end
+      if command.respond_to? :notes
+        titles_and_contents.merge! 'Notes' => command.notes
+      end
+      titles_and_contents
+    end
+  end
+end

data/lib/cliffy/internal/run.rb

@@ -0,0 +1,155 @@
+require 'set'
+
+module Cliffy
+  module Internal
+    def self.run command, arguments, command_name, executable_name
+      unless command.respond_to? :signature
+        command.run
+        return
+      end
+
+      true_values = ['yes', 'true', '1']
+      false_values = ['no', 'false', '0']
+      invalid_arguments_message = "Invalid arguments. Run `#{executable_name} help #{command_name}` for help."
+      run_method = command.method :run
+      signature = command.signature
+      remaining_arguments = arguments.dup
+      keyword_parameters = {}
+
+      optional_symbols_and_data = signature.filter { |symbol, data| data[:kind] == :optional }
+      unless optional_symbols_and_data.empty?
+        options_and_symbols = optional_symbols_and_data.to_h do |symbol, data|
+          option_name = symbol.to_s.gsub '_', '-'
+          option = "--#{option_name}"
+          [option, symbol]
+        end
+        remaining_options = options_and_symbols.keys.to_set
+        options = optional_symbols_and_data.keys.map { |key| "--#{key.to_s.gsub '_', '-'}" }.to_set
+        queued_arguments = []
+        while ! remaining_arguments.empty?
+          argument = remaining_arguments.pop
+          if argument.start_with?('--') && remaining_options.include?(argument)
+            symbol = options_and_symbols[argument]
+            data_type = optional_symbols_and_data[symbol][:type]
+            value = nil
+            case data_type
+
+            when :boolean
+              if queued_arguments.empty?
+                value = true
+              end
+
+            when :integer, :float, :string
+              if queued_arguments.count == 1
+                queued_argument = queued_arguments.first
+                case data_type
+                when :integer
+                  value = Integer queued_argument, exception: false
+                when :float
+                  value = Float queued_argument, exception: false
+                when :string
+                  value = queued_argument
+                end
+              end
+      
+            when Hash
+              if queued_arguments.count == data_type.count
+                sub_symbols_and_values = {}
+                queued_arguments.zip(data_type).each do |queued_argument, sub_type|
+                  sub_value = nil
+                  case sub_type[1]
+                  when :boolean
+                    sub_value = true if true_values.include? argument
+                    sub_value = false if false_values.include? argument
+                  when :integer
+                    sub_value = Integer queued_argument, exception: false
+                  when :float
+                    sub_value = Float queued_argument, exception: false
+                  when :string
+                    sub_value = queued_argument
+                  end
+                  raise invalid_arguments_message if sub_value == nil
+                  sub_symbols_and_values[sub_type.first] = sub_value
+                end
+                value = sub_symbols_and_values
+              end
+      
+            end
+            raise invalid_arguments_message if value === nil
+            keyword_parameters[symbol] = value
+            remaining_options.delete argument
+            queued_arguments = []
+          else
+            queued_arguments.unshift argument
+          end
+        end
+        remaining_arguments = queued_arguments
+      end
+
+      strict_parsing = true
+      if command.respond_to?(:configuration) && command.configuration.include?(:strict_parsing)
+        strict_parsing = command.configuration[:strict_parsing]
+      end
+      if strict_parsing
+        if remaining_arguments.any? { |argument| argument.start_with? '--' }
+          raise invalid_arguments_message
+        end
+      end
+
+      required_parameters = []
+      run_method.parameters.each do |parameter|
+        next unless parameter.first == :req
+        data = signature[parameter[1]]
+        argument = remaining_arguments.shift
+        raise invalid_arguments_message if argument == nil
+        value = nil
+        case data[:type]
+        when :boolean
+          value = true if true_values.include? argument
+          value = false if false_values.include? argument
+        when :integer
+          value = Integer argument, exception: false
+        when :float
+          value = Float argument, exception: false
+        when :string
+          value = argument
+        end
+        raise invalid_arguments_message if value == nil
+        required_parameters << value
+      end
+
+      variadic_parameters = []
+      variadic_data = signature.values.find { |data| data[:kind] == :variadic }
+      if variadic_data
+        data_type = variadic_data[:type]
+        while ! remaining_arguments.empty?
+          argument = remaining_arguments.shift
+          value = nil
+          case data_type
+          when :boolean
+            value = true if true_values.include? argument
+            value = false if false_values.include? argument
+          when :integer
+            value = Integer argument, exception: false
+          when :float
+            value = Float argument, exception: false
+          when :string
+            value = argument
+          end
+          raise invalid_arguments_message if value == nil
+          variadic_parameters << value
+        end
+        variadic_count = variadic_parameters.count
+        minimum = variadic_data[:minimum]
+        raise invalid_arguments_message if minimum && variadic_parameters.count < minimum
+        maximum = variadic_data[:maximum]
+        raise invalid_arguments_message if maximum && variadic_parameters.count > maximum
+      else
+        raise invalid_arguments_message unless remaining_arguments.empty?
+      end
+
+      positional_parameters = required_parameters + variadic_parameters
+      command.run *positional_parameters, **keyword_parameters
+    end
+  end
+end

data/lib/cliffy/internal/validate.rb

@@ -0,0 +1,134 @@
+module Cliffy
+  module Internal
+    def self.validate command
+      prefix = "Error validating '#{command.class}' command:"
+      raise "#{prefix} No run method." unless command.respond_to? :run
+      raise "#{prefix} No description." unless command.respond_to? :description
+      description = command.description
+      unless description.is_a?(String) && ! description.empty? && description.lines.count == 1
+        raise "#{prefix} Invalid description."
+      end
+
+      if command.respond_to? :notes
+        notes = command.notes
+        raise "#{prefix} Notes is not an array." unless notes.is_a?(Array)
+        notes.each_with_index do |note, index|
+          unless note.is_a?(String) && ! note.empty? && note.lines.count == 1
+            raise "#{prefix} Invalid note at index #{index}."
+          end
+        end
+      end
+
+      parameters = command.method(:run).parameters
+      return if parameters.empty?
+
+      unless command.respond_to?(:signature) && command.signature.is_a?(Hash)
+        raise "#{prefix} Signature missing or not defined correctly."
+      end
+
+      command.signature.each do |symbol, data|
+        raise "#{prefix} signature key '#{symbol}' is not a symbol." unless symbol.is_a? Symbol
+        data_prefix = "#{prefix} Signature data for '#{symbol}'"
+        raise "#{data_prefix} is not a hash." unless data.is_a? Hash
+        raise "#{data_prefix} does not have a kind." unless data.include? :kind
+        raise "#{data_prefix} does not have a type." unless data.include? :type
+        raise "#{data_prefix} does not have a description." unless data.include? :description
+
+        data_kind = data[:kind]
+        data_type = data[:type]
+        data_description = data[:description]
+
+        case data_kind
+        when :required, :optional
+          valid_data_keys = [:kind, :description, :type]
+        when :variadic
+          valid_data_keys = [:kind, :description, :type, :minimum, :maximum]
+        else
+          raise "#{data_prefix} has an invalid kind."
+        end
+
+        unless data.keys.to_set.subset? valid_data_keys.to_set
+          raise "#{data_prefix} contains an unrecognized key."
+        end
+        unless data_description.is_a?(String) && ! data_description.empty? && data_description.lines.count == 1
+          raise "#{data_prefix} does not have a valid description."
+        end
+
+        primitives = [:string, :integer, :float, :boolean]
+        case data_kind
+        when :required, :variadic
+          unless primitives.include? data_type
+            raise "#{data_prefix} is of kind '#{data_kind}' and must have a valid primitive type."
+          end
+        when :optional
+          case data_type
+          when :string, :integer, :float, :boolean
+          when Hash
+            unless data_type.keys.all? { |key| key.is_a? Symbol }
+              raise "#{data_prefix} contains an invalid key in the value hash."
+            end
+            unless data_type.values.all? { |value| primitives.include? value }
+              raise "#{data_prefix} contains an invalid value in the value hash."
+            end
+          else
+            raise "#{data_prefix} is of kind 'optional' and must have a valid primitive or hash type."
+          end
+        end
+
+        if data_kind == :variadic
+          if data.include? :minimum
+            minimum = data[:minimum]
+            unless minimum.is_a?(Integer) && minimum >= 0
+              raise "#{data_prefix} has an invalid minimum value."
+            end
+          else
+            minimum = 0
+          end
+          if data.include? :maximum
+            maximum = data[:maximum]
+            unless maximum.is_a?(Integer) && maximum >= 0 && maximum > minimum
+              raise "#{data_prefix} has an invalid maximum value."
+            end
+          end
+        end
+      end
+
+      method_symbols = parameters.map { |parameter| parameter[1] }.to_set
+      signature_symbols = command.signature.keys.to_set
+      missing_method_symbols = signature_symbols - method_symbols
+      missing_signature_symbols = method_symbols - signature_symbols
+      unless missing_method_symbols.empty?
+        raise "#{prefix} Symbols missing from run method that are in signature: #{missing_method_symbols.join ', '}"
+      end
+      unless missing_signature_symbols.empty?
+        raise "#{prefix} Symbols missing from signature that are in run method: #{missing_signature_symbols.join ', '}"
+      end
+
+      found_req = false
+      found_rest = false
+      found_key = false
+      parameters.each do |parameter|
+        parameter_prefix = "#{prefix} '#{parameter[1]}'"
+        case parameter.first
+        when :req
+          kind = :required
+          found_req = true
+          raise "#{prefix} Required positional after variadic." if found_rest
+          raise "#{prefix} Required positional after required keyword." if found_key
+        when :rest
+          kind = :variadic
+          found_rest = true
+          raise "#{prefix} Variadic after required keyword." if found_key
+        when :key
+          kind = :optional
+          found_key = true
+        else
+          raise "#{parameter_prefix} is not a supported kind of method parameter."
+        end
+        unless command.signature[parameter[1]][:kind] == kind
+          raise "#{parameter_prefix} should have a kind of '#{kind}', in the signature."
+        end
+      end
+    end
+  end
+end

data/lib/cliffy/internal/wrapper.rb

@@ -0,0 +1,33 @@
+require_relative 'generate_help_data'
+require_relative 'run'
+require_relative 'validate'
+
+module Cliffy
+  module Internal
+    class Wrapper
+      def initialize command
+        @command = command
+      end
+
+      def command_name
+        @command_name ||= @command.class.to_s.split('::').last.gsub(/([A-Z][a-z]+)([A-Z][a-z]+)/, '\1-\2').downcase
+      end
+
+      def command_description
+        @command.description
+      end
+
+      def validate
+        Internal::validate @command
+      end
+
+      def generate_help_data executable_name
+        Internal::generate_help_data @command, command_name, executable_name
+      end
+
+      def run arguments, executable_name
+        Internal::run @command, arguments, command_name, executable_name
+      end
+    end
+  end
+end

data/lib/cliffy/version.rb

@@ -0,0 +1,3 @@
+module Cliffy
+  VERSION = '0.6.0'
+end

data/lib/cliffy.rb

@@ -0,0 +1,2 @@
+require_relative 'cliffy/version'
+require_relative 'cliffy/api'

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: cliffy
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: ruby
+authors:
+- Jared O'Connor
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-02-15 00:00:00.000000000 Z
+dependencies: []
+description: Cliffy is a command line interface framework for you.
+email:
+- jaredoconnor@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/cliffy.rb
+- lib/cliffy/api.rb
+- lib/cliffy/internal/generate_help_data.rb
+- lib/cliffy/internal/run.rb
+- lib/cliffy/internal/validate.rb
+- lib/cliffy/internal/wrapper.rb
+- lib/cliffy/version.rb
+homepage: https://github.com/jaredoconnor/cliffy
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jaredoconnor/cliffy
+  source_code_uri: https://github.com/jaredoconnor/cliffy
+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.3.3
+signing_key:
+specification_version: 4
+summary: Command Line Interface Framework For You
+test_files: []