command_kit 0.1.0.pre1 → 0.2.0

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

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
-require 'command_kit/stdio'
 require 'command_kit/env'
 require 'command_kit/env/path'
+require 'command_kit/stdio'
+require 'command_kit/terminal'
+
+require 'shellwords'
 
 module CommandKit
   #
@@ -16,6 +19,7 @@ module CommandKit
   #
   #       def run
   #         pager do |io|
+  #           io.puts "This goes into the pager screen"
   #         end
   #       end
   #
@@ -33,9 +37,10 @@ module CommandKit
   # * [tty-pager](https://github.com/piotrmurach/tty-pager#readme)
   #
   module Pager
-    include Stdio
     include Env
     include Env::Path
+    include Stdio
+    include Terminal
 
     # Common pager commands.
     PAGERS = ['less -r', 'more -r']
@@ -43,14 +48,19 @@ module CommandKit
     #
     # Initializes the pager.
     #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   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
 
@@ -68,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?
-        # fallback to stdout if the process does not have a console or we could
+      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
@@ -93,23 +120,71 @@ module CommandKit
     end
 
     #
-    # Pages the data if it's longer the console's height, otherwise prints the
+    # Pages the data if it's longer the terminal's height, otherwise prints the
     # data to {Stdio#stdout stdout}.
     #
     # @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
                    else             data.to_s.each_line.count
                    end
 
-      if line_count > console_height
+      if line_count > terminal_height
         pager { |io| io.puts(data) }
       else
         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,7 +40,28 @@ 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?
@@ -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,12 +9,24 @@ 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"
+    #
+    # @api public
+    #
     def print_error(message)
       stderr.puts message
     end
@@ -25,6 +37,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