command_kit 0.1.0.pre1 → 0.2.0

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

@@ -0,0 +1,159 @@
+require 'command_kit/stdio'
+require 'command_kit/env'
+
+begin
+  require 'io/console'
+rescue LoadError
+end
+
+module CommandKit
+  #
+  # Provides direct access to the terminal.
+  #
+  # ## Environment Variables
+  #
+  # * `LINES` - The explicit number of lines or rows the console should have.
+  # * `COLUMNS` - The explicit number of columns the console should have.
+  #
+  # @see https://rubydoc.info/gems/io-console/IO
+  #
+  module Terminal
+    include Stdio
+    include Env
+
+    # The default terminal height to fallback to.
+    DEFAULT_TERMINAL_HEIGHT = 25
+
+    # The default terminal width to fallback to.
+    DEFAULT_TERMINAL_WIDTH = 80
+
+    #
+    # Initializes any terminal settings.
+    #
+    # @param [Hash{Symbol => Object}] kwargs
+    #   Additional keyword arguments.
+    #
+    # @note
+    #   If the `$LINES` env variable is set, and is non-zero, it will be
+    #   returned by {#terminal_height}.
+    #
+    # @note
+    #   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)
+
+      @terminal_height = if (lines = env['LINES'])
+                           lines.to_i
+                         else
+                           DEFAULT_TERMINAL_HEIGHT
+                         end
+
+      @terminal_width  = if (columns = env['COLUMNS'])
+                           columns.to_i
+                         else
+                           DEFAULT_TERMINAL_WIDTH
+                         end
+    end
+
+    #
+    # Determines if program is running in a terminal.
+    #
+    # @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.
+    #
+    # @return [IO, nil]
+    #   The IO objects or `nil` if {Stdio#stdout stdout} is not connected to a
+    #   terminal.
+    #
+    # @example
+    #   terminal
+    #   # => #<File:/dev/tty>
+    #
+    # @see https://rubydoc.info/gems/io-console/IO
+    #
+    # @api semipublic
+    #
+    def terminal
+      IO.console if terminal?
+    end
+
+    #
+    # Returns the terminal's height in number of lines.
+    #
+    # @return [Integer]
+    #   The terminal's height in number of lines.
+    #
+    # @example
+    #   terminal_height
+    #   # => 22
+    #
+    # @api public
+    #
+    def terminal_height
+      if (terminal = self.terminal)
+        terminal.winsize[0]
+      else
+        @terminal_height
+      end
+    end
+
+    #
+    # Returns the terminal's width in number of lines.
+    #
+    # @return [Integer]
+    #   The terminal's width in number of columns.
+    #
+    # @example
+    #   terminal_width
+    #   # => 91
+    #
+    # @api public
+    #
+    def terminal_width
+      if (terminal = self.terminal)
+        terminal.winsize[1]
+      else
+        @terminal_width
+      end
+    end
+
+    #
+    # The terminal height (lines) and width (columns).
+    #
+    # @return [(Integer, Integer)]
+    #   Returns the height and width of the terminal.
+    #
+    # @example
+    #   terminal_size
+    #   # => [23, 91]
+    #
+    # @api public
+    #
+    def terminal_size
+      if (terminal = self.terminal)
+        terminal.winsize
+      else
+        [@terminal_height, @terminal_width]
+      end
+    end
+  end
+end

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

data/lib/command_kit/version.rb

@@ -1,4 +1,4 @@
 module CommandKit
   # command_kit version
-  VERSION = "0.1.0.pre1"
+  VERSION = "0.2.0"
 end

data/lib/command_kit/xdg.rb

@@ -24,6 +24,9 @@ module CommandKit
     include CommandName
     include Env::Home
 
+    #
+    # @api private
+    #
     module ModuleMethods
       #
       # Extends {ClassMethods} or {ModuleMethods}, depending on whether {XDG} is
@@ -45,6 +48,9 @@ module CommandKit
 
     extend ModuleMethods
 
+    #
+    # Class-level methods.
+    #
     module ClassMethods
       #
       # Gets or sets the XDG sub-directory name used by the command.
@@ -58,11 +64,17 @@ module CommandKit
       #   {CommandName::ClassMethods#command_name} if no {#xdg_namespace} has
       #   been defined.
       #
+      # @api public
+      #
       def xdg_namespace(new_namespace=nil)
         if new_namespace
           @xdg_namespace = new_namespace.to_s
         else
-          @xdg_namespace || (superclass.xdg_namespace if superclass.kind_of?(ClassMethods)) || command_name
+          @xdg_namespace || if superclass.kind_of?(ClassMethods)
+                              superclass.xdg_namespace
+                            else
+                              command_name
+                            end
         end
       end
     end
@@ -70,16 +82,22 @@ module CommandKit
     # The `~/.config/<xdg_namespace>` directory.
     #
     # @return [String]
+    #
+    # @api public
     attr_reader :config_dir
 
     # The `~/.local/share/<xdg_namespace>` directory.
     #
     # @return [String]
+    #
+    # @api public
     attr_reader :local_share_dir
 
     # The `~/.cache/<xdg_namespace>` directory.
     #
     # @return [String]
+    #
+    # @api public
     attr_reader :cache_dir
 
     #
@@ -131,6 +149,8 @@ module CommandKit
     #
     # @see ClassMethods#xdg_namespace
     #
+    # @api semipublic
+    #
     def xdg_namespace
       self.class.xdg_namespace
     end