ronin-core 0.1.0.beta1

data/lib/ronin/core/cli/command_shell/command.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/cli/shell'
+
+module Ronin
+  module Core
+    module CLI
+      class CommandShell < Shell
+        class Command
+
+          # The command's name.
+          #
+          # @return [Symbol]
+          attr_reader :name
+
+          # The command's method name.
+          #
+          # @return [Symbol]
+          attr_reader :method_name
+
+          # The usage string for the command's arguments.
+          #
+          # @return [String, nil]
+          attr_reader :usage
+
+          # Possible tab completion values for the command's arguments.
+          #
+          # @return [Array<String>, Symbol, nil]
+          attr_reader :completions
+
+          # The command's one-line summary.
+          #
+          # @return [String]
+          attr_reader :summary
+
+          # The command's multi-line help output.
+          #
+          # @return [String]
+          attr_reader :help
+
+          #
+          # Initializes a command value object.
+          #
+          # @param [Symbol] name
+          #   The name of the command.
+          #
+          # @param [Symbol] method_name
+          #   The command's method name. Defaults to the name argument.
+          #
+          # @param [String, nil] usage
+          #   The usage string for the command's arguments.
+          #
+          # @param [Array<String>, Symbol, nil] completions
+          #   Potential tab completion values, or a method name, to complete
+          #   the command's arguments.
+          #
+          # @param [String] summary
+          #   A single line summary for the command.
+          #
+          # @param [String] help
+          #   Multi-line help information for the command.
+          #
+          def initialize(name, method_name: name,
+                               usage: nil,
+                               completions: nil,
+                               summary: ,
+                               help: summary)
+            @name        = name
+            @method_name = method_name
+            @usage       = usage
+            @summary     = summary
+            @help        = help
+            @completions = completions
+          end
+
+          #
+          # Converts the command to a String.
+          #
+          # @return [String]
+          #   The command name and the optional usage.
+          #
+          def to_s
+            if @usage
+              "#{@name} #{@usage}"
+            else
+              @name.to_s
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/cli/command_shell.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/cli/shell'
+require 'ronin/core/cli/command_shell/command'
+
+require 'shellwords'
+
+module Ronin
+  module Core
+    module CLI
+      #
+      # Base class for all custom command shells.
+      #
+      # ## Example
+      #
+      #     class HTTPShell < Ronin::Core::CLI::Shell
+      #     
+      #       shell_name 'http'
+      #     
+      #       command :get, usage: 'PATH [HEADERS...]',
+      #                     summary: 'Sends a GET request'
+      #       def get(path,*headers)
+      #         # ...
+      #       end
+      #
+      #       command :post, usage: 'PATH DATA [HEADERS...]',
+      #                      summary: 'Sends a POST request'
+      #       def post(path,data,*headers)
+      #         # ...
+      #       end
+      #     
+      #     end
+      #     
+      #     HTTPShell.start
+      #     # http> get /foo
+      #
+      # @api semipublic
+      #
+      class CommandShell < Shell
+
+        #
+        # The registered shell commands.
+        #
+        # @return [Hash{String => CommandShell::Command}]
+        #   The registered shell commands.
+        #
+        def self.commands
+          @commands ||= if superclass <= CommandShell
+                          superclass.commands.dup
+                        else
+                          {}
+                        end
+        end
+
+        #
+        # Registers a shell command.
+        #
+        # @param [Symbol] name
+        #   The name of the shell command.
+        #
+        # @param [Symbol] method_name
+        #   Optional method name to use. Defaults to the name argument.
+        #
+        # @param [String, nil] usage
+        #   A usage string indicating the shell command's options/arguments.
+        #
+        # @param [Array<String>, Symbol, nil] completions
+        #   The possible tab completion values, or a method name, to complete
+        #   the command's arguments.
+        #
+        # @param [String] summary
+        #   A one-line summary of the shell command.
+        #
+        # @param [String] help
+        #   Multi-line help output for the shell command.
+        #
+        def self.command(name, method_name: name,
+                               usage: nil,
+                               completions: nil,
+                               summary: ,
+                               help: summary)
+          commands[name.to_s] = Command.new(name, method_name: method_name,
+                                                  usage:       usage,
+                                                  completions: completions,
+                                                  summary:     summary,
+                                                  help:        help.strip)
+        end
+
+        #
+        # Parses a line of input.
+        #
+        # @param [String] line
+        #   A line of input.
+        #
+        # @return [String, Array<String>]
+        #   The command name and any additional arguments.
+        #
+        def self.parse_command(line)
+          Shellwords.shellsplit(line)
+        end
+
+        #
+        # The partially input being tab completed.
+        #
+        # @param [String] word
+        #   The partial input being tab completed.
+        #
+        # @param [String] preposing
+        #   The optional command name that preceeds the argument that's being
+        #   tab completed.
+        #
+        # @return [Array<String>, nil]
+        #   The possible completion values.
+        #
+        # @raise [NotImplementedError]
+        #   The command defined a completion method name but the command shell
+        #   does not define the complete method name.
+        #
+        def complete(word,preposing)
+          if preposing.empty?
+            self.class.commands.keys.select { |name| name.start_with?(word) }
+          else
+            name = preposing.split(/\s+/,2).first
+
+            if (command = self.class.commands[name])
+              completions = case command.completions
+                            when Array then command.completions
+                            when Symbol
+                              unless respond_to?(command.completions)
+                                raise(NotImplementedError,"#{self.class}##{command.completions} was not defined")
+                              end
+
+                              send(command.completions,word,preposing)
+                            end
+
+              if completions
+                completions.select { |arg| arg.start_with?(word) }
+              end
+            end
+          end
+        end
+
+        #
+        # Executes a command.
+        #
+        # @param [String] command
+        #   The command to execute.
+        #
+        # @return [Boolean]
+        #   Indicates whether the command was successfully executed.
+        #
+        def exec(command)
+          call(*self.class.parse_command(command))
+        end
+
+        #
+        # Invokes the command with the matching name.
+        #
+        # @param [String] name
+        #   The command name.
+        #
+        # @param [Array<String>] args
+        #   Additional arguments for the command.
+        #
+        # @return [Boolean]
+        #   Indicates whether the command was successfully executed.
+        #
+        # @raise [NotImplementedError]
+        #   The method for the command was not defined.
+        #
+        def call(name,*args)
+          unless (command = self.class.commands[name])
+            return command_missing(name,*args)
+          end
+
+          method_name = command.method_name
+
+          unless respond_to?(method_name,false)
+            raise(NotImplementedError,"#{self.class}##{method_name} was not defined for the #{name.inspect} command")
+          end
+
+          unless method_arity_check(method_name,args)
+            return false
+          end
+
+          begin
+            send(method_name,*args)
+          rescue => error
+            print_exception(error)
+            print_error "an unhandled exception occurred in the #{name} command"
+            return false
+          end
+
+          return true
+        end
+
+        #
+        # Default method that is called when an unknown command is called.
+        #
+        # @param [String] name
+        #
+        # @param [Array<String>] args
+        #
+        def command_missing(name,*args)
+          command_not_found(name)
+          return false
+        end
+
+        #
+        # Prints an error message when an unknown command is given.
+        #
+        # @param [String] name
+        #
+        def command_not_found(name)
+          print_error "unknown command: #{name}"
+        end
+
+        command :help, usage:   '[COMMAND]',
+                       summary: 'Prints the list of commands or additional help'
+
+        #
+        # Prints all commands or help information for the given command.
+        #
+        # @param [String, nil] command
+        #   Optional command name to print help information for.
+        #
+        def help(command=nil)
+          if command then help_command(command)
+          else            help_commands
+          end
+        end
+
+        private
+
+        #
+        # Prints a list of all registered commands.
+        #
+        def help_commands
+          command_table = self.class.commands.map do |name,command|
+            [command.to_s, command.summary]
+          end
+
+          max_command_string = command_table.map { |command_string,summary|
+            command_string.length
+          }.max
+
+          command_table.each  do |command_string,summary|
+            puts "  #{command_string.ljust(max_command_string)}\t#{summary}"
+          end
+        end
+
+        #
+        # Prints help information about a specific command.
+        #
+        # @param [String] name
+        #   The given command name.
+        #
+        def help_command(name)
+          unless (command = self.class.commands[name])
+            print_error "help: unknown command: #{name}"
+            return
+          end
+
+          puts "usage: #{command}"
+
+          if command.help
+            puts
+            puts command.help
+          end
+        end
+
+        #
+        # Calculates the minimum and maximum number of arguments for a given
+        # command method.
+        #
+        # @param [String] name
+        #   The method name.
+        #
+        # @return [(Integer, Integer)]
+        #   The minimum and maximum number of arguments for the method.
+        #
+        def minimum_maximum_args(name)
+          minimum = maximum = 0
+
+          method(name).parameters.each do |(type,arg)|
+            case type
+            when :req 
+              minimum += 1
+              maximum += 1
+            when :opt  then maximum += 1
+            when :rest then maximum = Float::INFINITY
+            end
+          end
+
+          return minimum, maximum
+        end
+
+        #
+        # Performs an arity check between the method's number of arguments and
+        # the number of arguments given.
+        #
+        # @param [String] name
+        #   The method name to lookup.
+        #
+        # @param [Array<String>] args
+        #   The given arguments.
+        #
+        # @return [Boolean]
+        #   Indicates whether the method can accept the given number of
+        #   arguments.
+        #
+        def method_arity_check(name,args)
+          minimum_args, maximum_args = minimum_maximum_args(name)
+
+          if args.length > maximum_args
+            print_error "#{name}: too many arguments given"
+            return false
+          elsif args.length < minimum_args
+            print_error "#{name}: too few arguments given"
+            return false
+          end
+
+          return true
+        end
+
+      end
+    end
+  end
+end

data/lib/ronin/core/cli/generator/options/author.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+require 'ronin/core/git'
+
+module Ronin
+  module Core
+    module CLI
+      module Generator
+        module Options
+          #
+          # Adds the `-a,--author NAME` and `-e,--author-email EMAIL` options
+          # for the generator command.
+          #
+          module Author
+
+            #
+            # The default author name.
+            #
+            # @return [String, nil]
+            #
+            def self.default_name
+              Core::Git.user_name || ENV['USERNAME']
+            end
+
+            #
+            # The default author email.
+            #
+            # @return [String, nil]
+            #
+            def self.default_email
+              Core::Git.user_email
+            end
+
+            #
+            # Defines the `-a,--author NAME` and `-e,--author-email EMAIL`
+            # options.
+            #
+            # @param [Class<Comand>] command
+            #   The command class including {Author}.
+            #
+            def self.included(command)
+              command.option :author, short: '-a',
+                                      value: {
+                                        type:    String,
+                                        usage:   'NAME',
+                                        default: ->{ default_name }
+                                      },
+                                      desc: 'The name of the author' do |author|
+                                        @author_name = author
+                                      end
+
+              command.option :author_email, short: '-e',
+                                            value: {
+                                              type:    String,
+                                              usage:   'EMAIL',
+                                              default: ->{ default_email }
+                                            },
+                                            desc: 'The email address of the author' do |email|
+                                              @author_email = email
+                                            end
+            end
+
+            # The author name.
+            #
+            # @return [String]
+            attr_reader :author_name
+
+            # The author email.
+            #
+            # @return [String]
+            attr_reader :author_email
+
+            #
+            # Initializes {#author_name} and {#author_email}.
+            #
+            # @param [Hash{Symbol => Object}] kwargs
+            #   Additional keyword arguments.
+            #
+            def initialize(**kwargs)
+              super(**kwargs)
+
+              @author_name  = Author.default_name
+              @author_email = Author.default_email
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/cli/generator/options/description.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Core
+    module CLI
+      module Generator
+        module Options
+          #
+          # Adds the `-D,--description TEXT` option to the generator command.
+          #
+          module Description
+            #
+            # Defines the `-D,--description TEXT` option.
+            #
+            # @param [Class<Comand>] command
+            #   The command class including {Description}.
+            #
+            def self.included(command)
+              command.option :description, short: '-D',
+                                           value: {
+                                             type: String,
+                                             usage: 'TEXT'
+                                           },
+                                           desc: 'A longer description' do |text|
+                                             @description = text
+                                           end
+            end
+
+            # The description text to output.
+            #
+            # @return [String, nil]
+            attr_reader :description
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ronin/core/cli/generator/options/reference.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+#
+# Copyright (c) 2021-2022 Hal Brodigan (postmodern.mod3 at gmail.com)
+#
+# ronin-core is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# ronin-core is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with ronin-core.  If not, see <https://www.gnu.org/licenses/>.
+#
+
+module Ronin
+  module Core
+    module CLI
+      module Generator
+        module Options
+          #
+          # Adds the `-R,--reference URL` option to the generator command.
+          #
+          module Reference
+            def self.included(command)
+              command.option :reference, short: '-R',
+                                         value: {
+                                           type: String,
+                                           usage: 'URL'
+                                         },
+                                         desc: 'Adds a reference URL' do |url|
+                                           @references << url
+                                         end
+            end
+
+            # The reference URLs to output.
+            #
+            # @return [Array<String>]
+            attr_reader :references
+
+            #
+            # Initializes {#references}.
+            #
+            # @param [Hash{Symbol => Object}] kwargs
+            #   Additional keyword arguments.
+            #
+            def initialize(**kwargs)
+              super(**kwargs)
+
+              @references = []
+            end
+          end
+        end
+      end
+    end
+  end
+end