command_kit 0.1.0.rc1 → 0.2.2

data/lib/command_kit/package_manager.rb

@@ -0,0 +1,200 @@
+require 'command_kit/os'
+require 'command_kit/os/linux'
+require 'command_kit/env/path'
+require 'command_kit/sudo'
+
+module CommandKit
+  #
+  # Allows installing packages using the system's package manager.
+  #
+  # Supports the following package managers:
+  #
+  # * Linux
+  #   * Debian / Ubuntu
+  #     * `apt`
+  #   * RedHat / Fedora
+  #     * `dnf`
+  #     * `yum`
+  #   * Arch
+  #     * `pacman`
+  #   * SUSE / OpenSUSE
+  #     * `zypper`
+  # * macOS
+  #   * `brew`
+  #   * `port`
+  # * FreeBSD
+  #   * `pkg`
+  # * OpenBSD
+  #   * `pkg_add`
+  #
+  # ## Examples
+  #
+  #     unless install_packages("nmap")
+  #       print_error "failed to install nmap"
+  #       exit -1
+  #     end
+  #
+  # ### Installing multiple packages
+  #
+  #     install_packages apt: ["libxml2-dev", ...],
+  #                      dnf: ["libxml2-devel", ...],
+  #                      brew: ["libxml2", ...],
+  #                      ...
+  #
+  # @since 0.2.0
+  #
+  module PackageManager
+    include OS
+    include OS::Linux
+    include Env::Path
+    include Sudo
+
+    # The detected package manager.
+    #
+    # @return [:apt, :dnf, :yum, :zypper, :pacman, :brew, :pkg, :pkg_add, nil]
+    attr_reader :package_manager
+
+    #
+    # Initializes the command and determines which open command to use.
+    #
+    # @param [:apt, :dnf, :yum, :zypper, :pacman, :brew, :pkg, :pkg_add, nil] package_manager
+    #   The explicit package manager to use. If `nil`, the package manager will
+    #   be detected.
+    #
+    def initialize(package_manager: nil, **kwargs)
+      super(**kwargs)
+
+      @package_manager = package_manager || begin
+        if macos?
+          if    command_installed?('brew') then :brew
+          elsif command_installed?('port') then :port
+          end
+        elsif linux?
+          if redhat_linux?
+            if    command_installed?('dnf') then :dnf
+            elsif command_installed?('yum') then :yum
+            end
+          elsif debian_linux?
+            :apt if command_installed?('apt')
+          elsif suse_linux?
+            :zypper if command_installed?('zypper')
+          elsif arch_linux?
+            :pacman if command_installed?('pacman')
+          end
+        elsif freebsd?
+          :pkg if command_installed?('pkg')
+        elsif openbsd?
+          :pkg_add if command_installed?('pkg_add')
+        end
+      end
+    end
+
+    #
+    # Installs the packages using the system's package manager.
+    #
+    # @param [Array<String>, String] packages
+    #   A list of package name(s) to install.
+    #
+    # @param [Boolean] yes
+    #   Assume yes for all user prompts.
+    #
+    # @param [Array<String>, String] apt
+    #   List of `apt` specific package names.
+    #
+    # @param [Array<String>, String] brew
+    #   List of `brew` specific package names.
+    #
+    # @param [Array<String>, String] dnf
+    #   List of `dnf` specific package names.
+    #
+    # @param [Array<String>, String] pacman
+    #   List of `pacman` specific package names.
+    #
+    # @param [Array<String>, String] pkg
+    #   List of `pkg` specific package names.
+    #
+    # @param [Array<String>, String] pkg_add
+    #   List of `pkg_add` specific package names.
+    #
+    # @param [Array<String>, String] port
+    #   List of `port` specific package names.
+    #
+    # @param [Array<String>, String] yum
+    #   List of `yum` specific package names.
+    #
+    # @param [Array<String>, String] zypper
+    #   List of `zypper` specific package names.
+    #
+    # @return [Boolean, nil]
+    #   Specifies whether the packages were successfully installed or not.
+    #   If the package manager command could not be determined, `nil` is
+    #   returned.
+    #
+    # @example Install a package
+    #   install_packages "nmap", ...
+    #
+    # @example Install a list of packages per package-manager
+    #   install_packages apt: ["libxml2-dev", ...],
+    #                    dnf: ["libxml2-devel", ...],
+    #                    brew: ["libxml2", ...],
+    #                    ...
+    #
+    def install_packages(*packages, yes: false,
+                                    apt: nil,
+                                    brew: nil,
+                                    dnf: nil,
+                                    pacman: nil,
+                                    pkg: nil,
+                                    pkg_add: nil,
+                                    port: nil,
+                                    yum: nil,
+                                    zypper: nil)
+      specific_package_names = case @package_manager
+                               when :apt     then apt
+                               when :brew    then brew
+                               when :dnf     then dnf
+                               when :pacman  then pacman
+                               when :pkg     then pkg
+                               when :pkg_add then pkg_add
+                               when :port    then port
+                               when :yum     then yum
+                               when :zypper  then zypper
+                               end
+      packages += Array(specific_package_names)
+
+      case @package_manager
+      when :apt
+        args = []
+        args << '-y' if yes
+
+        sudo('apt','install',*args,*packages)
+      when :brew
+        system('brew','install',*packages)
+      when :dnf, :yum
+        args = []
+        args << '-y' if yes
+
+        sudo(@package_manager.to_s,'install',*args,*packages)
+      when :pacman
+        missing_packages = `pacman -T #{Shellwords.shelljoin(packages)}`.split
+
+        if missing_packages.empty?
+          return true
+        end
+
+        sudo('pacman','-S',*missing_packages)
+      when :pkg
+        args = []
+        args << '-y' if yes
+
+        sudo('pkg','install',*args,*packages)
+      when :pkg_add
+        sudo('pkg_add',*packages)
+      when :port
+        sudo('port','install',*packages)
+      when :zypper
+        sudo('zypper','-n','in','-l',*packages)
+      end
+    end
+  end
+end

data/lib/command_kit/pager.rb

@@ -5,6 +5,8 @@ require 'command_kit/env/path'
 require 'command_kit/stdio'
 require 'command_kit/terminal'
 
+require 'shellwords'
+
 module CommandKit
   #
   # Allows opening a pager, such as `less` or `more`.
@@ -50,13 +52,15 @@ module CommandKit
     #   Keyword arguments.
     #
     # @note
-    #   Respects the `PAGER` env variable, or attemps to find `less` or
+    #   Respects the `PAGER` env variable, or attempts to find `less` or
     #   `more` by searching the `PATH` env variable.
     #
+    # @api public
+    #
     def initialize(**kwargs)
       super(**kwargs)
 
-      @pager = env.fetch('PAGER') do
+      @pager_command = env.fetch('PAGER') do
         PAGERS.find do |command|
           bin = command.split(' ',2).first
 
@@ -74,15 +78,32 @@ module CommandKit
     # @yieldparam [IO]
     #   The IO pipe to the pager.
     #
+    # @example
+    #   pager do |io|
+    #     io.puts "Hello world"
+    #     # ...
+    #   end
+    #
+    # @example Piping a command into the pager:
+    #   IO.peopn(["ping", ip]) do |ping|
+    #     pager do |io|
+    #       ping.each_line do |line|
+    #         io.write line
+    #       end
+    #     end
+    #   end
+    #
+    # @api public
+    #
     def pager
-      if !stdout.tty? || @pager.nil?
+      if !stdout.tty? || @pager_command.nil?
         # fallback to stdout if the process does not have a terminal or we could
         # not find a suitable pager command.
         yield stdout
         return
       end
 
-      io  = IO.popen(@pager,'w')
+      io  = IO.popen(@pager_command,'w')
       pid = io.pid
 
       begin
@@ -105,6 +126,14 @@ module CommandKit
     # @param [Array<String>, #to_s] data
     #   The data to print.
     #
+    # @example
+    #   print_or_page(data)
+    #
+    # @example Print or pages the contents of a file:
+    #   print_or_page(File.read(file))
+    #
+    # @api public
+    #
     def print_or_page(data)
       line_count = case data
                    when Array  then data.length
@@ -117,5 +146,45 @@ module CommandKit
         stdout.puts(data)
       end
     end
+
+    #
+    # Pipes a command into the pager.
+    #
+    # @param [#to_s] command
+    #   The program or command to run.
+    #
+    # @param [Array<#to_s>] arguments
+    #   Additional arguments for the program.
+    #
+    # @return [Boolean]
+    #   Indicates whether the command exited successfully or not.
+    #
+    # @note
+    #   If multiple arguments are given, they will be shell-escaped and executed
+    #   as a single command.
+    #   If a single command is given, it will not be shell-escaped to allow
+    #   executing compound shell commands.
+    #
+    # @example Pipe a single command into the pager:
+    #   run_in_pager 'find', '.', '-name', '*.md'
+    # 
+    # @example Pipe a compound command into the pager:
+    #   run_in_pager "wc -l /path/to/wordlists/*.txt | sort -n"
+    #
+    # @api public
+    #
+    # @since 0.2.0
+    #
+    def pipe_to_pager(command,*arguments)
+      if @pager_command
+        unless arguments.empty?
+          command = Shellwords.shelljoin([command, *arguments])
+        end
+
+        system("#{command} | #{@pager_command}")
+      else
+        system(command.to_s,*arguments.map(&:to_s))
+      end
+    end
   end
 end

data/lib/command_kit/printing/indent.rb

@@ -20,7 +20,7 @@ module CommandKit
     #
     module Indent
       #
-      # Initializes the indententation level to zero.
+      # Initializes the indentation level to zero.
       #
       def initialize(**kwargs)
         @indent = 0
@@ -40,14 +40,35 @@ module CommandKit
       #   increased.
       #
       # @return [Integer]
-      #   If no block is given, the indententation level will be returned.
+      #   If no block is given, the indentation level will be returned.
+      #
+      # @example
+      #   puts "values:"
+      #   indent do
+      #     values.each do |key,value|
+      #       puts "#{key}: #{value}"
+      #     end
+      #   end
+      #
+      # @example
+      #   puts "Code:"
+      #   puts
+      #   puts "```"
+      #   indent(4) do
+      #     code.each_line do |line|
+      #       puts line
+      #     end
+      #   end
+      #   puts "```"
+      #
+      # @api public
       #
       def indent(n=2)
         if block_given?
+          original_indent = @indent
+
           begin
-            original_indent = @indent
             @indent += n
-
             yield
           ensure
             @indent = original_indent
@@ -63,6 +84,8 @@ module CommandKit
       # @param [Array<String>] lines
       #   The lines to indent and print.
       #
+      # @api public
+      #
       def puts(*lines)
         if (@indent > 0 && !lines.empty?)
           padding = " " * @indent

data/lib/command_kit/printing.rb

@@ -9,14 +9,37 @@ module CommandKit
   module Printing
     include Stdio
 
+    # Platform independent new-line constant
+    #
+    # @return [String]
+    #
+    # @api public
+    EOL = $/
+
     #
     # Prints the error message to {Stdio#stderr stderr}.
     #
     # @param [String] message
     #   The error message.
     #
+    # @example
+    #   print_error "error: invalid input"
+    #   # error: invalid input
+    #
+    # @example When CommandKit::CommandName is included:
+    #   print_error "invalid input"
+    #   # foo: invalid input
+    #
+    # @api public
+    #
     def print_error(message)
-      stderr.puts message
+      if respond_to?(:command_name)
+        # if #command_name is available, prefix all error messages with it
+        stderr.puts "#{command_name}: #{message}"
+      else
+        # if #command_name is not available, just print the error message as-is
+        stderr.puts message
+      end
     end
 
     #
@@ -25,6 +48,17 @@ module CommandKit
     # @param [Exception] error
     #   The error to print.
     #
+    # @example
+    #   begin
+    #     # ...
+    #   rescue => error
+    #     print_error "Error encountered"
+    #     print_exception(error)
+    #     exit(1)
+    #   end
+    #
+    # @api public
+    #
     def print_exception(error)
       print_error error.full_message(highlight: stderr.tty?)
     end

data/lib/command_kit/program_name.rb

@@ -3,6 +3,9 @@ module CommandKit
   # Retrieves the current program name (`$PROGRAM_NAME`).
   #
   module ProgramName
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether
@@ -42,6 +45,8 @@ module CommandKit
       #   The `$PROGRAM_NAME` or `nil` if the `$PROGRAM_NAME` is `-e`, `irb`,
       #   or `rspec`.
       #
+      # @api semipublic
+      #
       def program_name
         $PROGRAM_NAME unless IGNORED_PROGRAM_NAMES.include?($PROGRAM_NAME)
       end
@@ -50,6 +55,8 @@ module CommandKit
     #
     # @see ClassMethods#program_name
     #
+    # @api public
+    #
     def program_name
       self.class.program_name
     end

data/lib/command_kit/stdio.rb

@@ -34,6 +34,8 @@ module CommandKit
     # @param [IO] stderr
     #   The stderr error output stream. Defaults to `$stderr`.
     #
+    # @api public
+    #
     def initialize(stdin: nil, stdout: nil, stderr: nil, **kwargs)
       @stdin  = stdin
       @stdout = stdout
@@ -48,6 +50,8 @@ module CommandKit
     # @return [$stdin, IO]
     #   The initialized `@stdin` value or `$stdin`.
     #
+    # @api public
+    #
     def stdin
       @stdin || $stdin
     end
@@ -58,6 +62,8 @@ module CommandKit
     # @return [$stdout, IO]
     #   The initialized `@stdout` value or `$stdout`.
     #
+    # @api public
+    #
     def stdout
       @stdout || $stdout
     end
@@ -68,6 +74,8 @@ module CommandKit
     # @return [$stderr, IO]
     #   The initialized `@stderr` value or `$stderr`.
     #
+    # @api public
+    #
     def stderr
       @stderr || $stderr
     end
@@ -75,6 +83,8 @@ module CommandKit
     #
     # Calls `stdin.gets`.
     #
+    # @api public
+    #
     def gets(*arguments)
       stdin.gets(*arguments)
     end
@@ -82,6 +92,8 @@ module CommandKit
     #
     # Calls `stdin.readline`.
     #
+    # @api public
+    #
     def readline(*arguments)
       stdin.readline(*arguments)
     end
@@ -89,6 +101,8 @@ module CommandKit
     #
     # Calls `stdin.readlines`.
     #
+    # @api public
+    #
     def readlines(*arguments)
       stdin.readlines(*arguments)
     end
@@ -99,6 +113,8 @@ module CommandKit
     #
     # Calls `stdout.putc`.
     #
+    # @api public
+    #
     def putc(*arguments)
       stdout.putc(*arguments)
     end
@@ -106,6 +122,8 @@ module CommandKit
     #
     # Calls `stdout.puts`.
     #
+    # @api public
+    #
     def puts(*arguments)
       stdout.puts(*arguments)
     end
@@ -113,6 +131,8 @@ module CommandKit
     #
     # Calls `stdout.print`.
     #
+    # @api public
+    #
     def print(*arguments)
       stdout.print(*arguments)
     end
@@ -120,6 +140,8 @@ module CommandKit
     #
     # Calls `stdout.printf`.
     #
+    # @api public
+    #
     def printf(*arguments)
       stdout.printf(*arguments)
     end
@@ -130,6 +152,8 @@ module CommandKit
     # @param [String, nil] message
     #   The optional abort message.
     #
+    # @api public
+    #
     def abort(message=nil)
       stderr.puts(message) if message
       exit(1)

data/lib/command_kit/sudo.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'command_kit/os'
+
+module CommandKit
+  #
+  # Allows running commands with `sudo`.
+  #
+  # @since 0.2.0
+  #
+  module Sudo
+    include OS
+
+    #
+    # Runs the command under sudo, if the user isn't already root.
+    #
+    # @param [String] command
+    #   The command to execute.
+    #
+    # @param [Array<String>] arguments
+    #   Additional arguments for the command.
+    #
+    # @return [Boolean, nil]
+    #   Specifies whether the command was successfully ran or not.
+    #
+    # @api public
+    #
+    def sudo(command,*arguments)
+      if windows?
+        system('runas','/user:administrator',command,*arguments)
+      else
+        if Process.uid == 0
+          system(command,*arguments)
+        else
+          system('sudo',command,*arguments)
+        end
+      end
+    end
+  end
+end

data/lib/command_kit/terminal.rb

@@ -41,6 +41,8 @@ module CommandKit
     #   If the `$COLUMNS` env variable is set, and is non-zero, it will be
     #   returned by {#terminal_width}.
     #
+    # @api public
+    #
     def initialize(**kwargs)
       super(**kwargs)
 
@@ -63,10 +65,17 @@ module CommandKit
     # @return [Boolean]
     #   Specifies whether {Stdio#stdout stdout} is connected to a terminal.
     #
+    # @api public
+    #
     def terminal?
       IO.respond_to?(:console) && stdout.tty?
     end
 
+    #
+    # @since 0.2.0
+    #
+    alias tty? terminal?
+
     #
     # Returns the terminal object, if {Stdio#stdout stdout} is connected to a
     # terminal.
@@ -81,6 +90,8 @@ module CommandKit
     #
     # @see https://rubydoc.info/gems/io-console/IO
     #
+    # @api semipublic
+    #
     def terminal
       IO.console if terminal?
     end
@@ -95,6 +106,8 @@ module CommandKit
     #   terminal_height
     #   # => 22
     #
+    # @api public
+    #
     def terminal_height
       if (terminal = self.terminal)
         terminal.winsize[0]
@@ -113,6 +126,8 @@ module CommandKit
     #   terminal_width
     #   # => 91
     #
+    # @api public
+    #
     def terminal_width
       if (terminal = self.terminal)
         terminal.winsize[1]
@@ -131,6 +146,8 @@ module CommandKit
     #   terminal_size
     #   # => [23, 91]
     #
+    # @api public
+    #
     def terminal_size
       if (terminal = self.terminal)
         terminal.winsize

data/lib/command_kit/usage.rb

@@ -15,6 +15,9 @@ module CommandKit
     include CommandName
     include Help
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether {Usage}
@@ -50,6 +53,11 @@ module CommandKit
       # @return [String, Array<String>]
       #   The class'es or superclass'es usage string(s).
       #
+      # @example
+      #   usage "[options] ARG1 ARG2 [ARG3 ...]"
+      #
+      # @api public
+      #
       def usage(new_usage=nil)
         if new_usage
           @usage = new_usage
@@ -65,6 +73,8 @@ module CommandKit
     #
     # @return [Array<String>, String, nil]
     #
+    # @api public
+    #
     def usage
       case (usage = self.class.usage)
       when Array
@@ -77,6 +87,8 @@ module CommandKit
     #
     # Prints the `usage: ...` output.
     #
+    # @api semipublic
+    #
     def help_usage
       case (usage = self.usage)
       when Array
@@ -95,6 +107,8 @@ module CommandKit
     #
     # @see #help_usage
     #
+    # @api public
+    #
     def help
       help_usage
     end