pmgmt 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 3e30d7e78a8a61ae27c505f47f1821c2ee991ac91264abfed389651626823e9a
-  data.tar.gz: 151734accba09a0511a88d78380894de6c4af6fad2ad0613c701441eb89963de
+SHA1:
+  metadata.gz: 3e6afb20a3759c4c7975553ffb186bb641cb7b05
+  data.tar.gz: f0200e100d4de9902e24286d6cc4f78a05cf0270
 SHA512:
-  metadata.gz: 764187c3dcb66e45fd17b6e111d8230f06e4fa622f75690f9cf3a43639f75777392b1d8a37cbb59d6b13e854da3e2411e5c3e3e2fe5d6c1c5ad28fe20c1cbfb2
-  data.tar.gz: 97a9f031cd58f3ba87e97104cef2be3945a27c13815a55be444507cf9184f7285a3e6c011ee3e44d62fd0a7d5d586f31cd0ff817ed03373509f00ef9043f4fea
+  metadata.gz: 768f313e048275c7c79aab4e88a4e963999ca657cacfde98241f5ee13e8795e3c022cc28a9971e554e6ce014d7cbbaddb96fedae76eab89c355f8a0ce2f1f115
+  data.tar.gz: 257c6e1a90cb9b67e8d89f0fcb8ca23ea53d1c53609eb41cfcdf41b0fcd9d2b73ede6f315431fb5ff39a35d98fb27d43977bdaee3ef285db9d3109b7f80133e4

data/lib/optionsparser.rb

@@ -0,0 +1,69 @@
+require "optparse"
+require "ostruct"
+
+# Creates a default command-line argument parser.
+# command_name: For help text.
+def create_parser(command_name)
+  OptionParser.new do |parser|
+    parser.banner = "Usage: #{$PROGRAM_NAME} #{command_name} [options]"
+    parser
+  end
+end
+
+module PmgmtLib
+
+  ##
+  # Allows parsing of command line options without requiring any subclassing.
+
+  class OptionsParser
+    attr_reader :opts, :remaining
+
+    def initialize(command_name, args)
+      @opts = OpenStruct.new
+      @parser = create_parser(command_name)
+      @args = args
+      @validators = []
+    end
+
+    def add_option(option, assign, help)
+      @parser.on(option, help) {|v| assign.call(@opts, v)}
+      self
+    end
+
+    def add_typed_option(option, type, assign, help)
+      @parser.on(option, type, help) {|v| assign.call(@opts, v)}
+      self
+    end
+
+    def add_validator(fn)
+      @validators.push(fn)
+      self
+    end
+
+    def parse()
+      begin
+        @remaining = @parser.parse @args
+      rescue ArgumentError => e
+        STDERR.puts e
+        STDERR.puts
+        STDERR.puts @parser.help
+        exit 1
+      end
+      self
+    end
+
+    def validate()
+      @validators.each do |fn|
+        begin
+          fn.call(@opts)
+        rescue ArgumentError => e
+          STDERR.puts e
+          STDERR.puts
+          STDERR.puts @parser.help
+          exit 1
+        end
+      end
+      self
+    end
+  end
+end

data/lib/pmgmt.rb

@@ -3,11 +3,23 @@ require "ostruct"
 require "yaml"
 
 require_relative "dockerhelper"
+require_relative "optionsparser"
 require_relative "syncfiles"
 
 class Pmgmt
+  # State to hold registered commands. See {#Pmgmt.register_command}.
   @@commands = []
+  # Convenience method to provide access to the options parsing utility class.
+  @@options_parser = PmgmtLib::OptionsParser
 
+  def self.OptionsParser
+    @@options_parser
+  end
+
+  # Loads all `.rb` scripts from the given directory. Scripts are expected to register commands as
+  # a side-effect of loading.
+  # @param scripts_dir [String]
+  # @return [void]
   def self.load_scripts(scripts_dir)
     if !File.directory?(scripts_dir)
       self.new.error "Cannot load scripts. Not a directory: #{scripts_dir}"
@@ -20,9 +32,22 @@ class Pmgmt
     end
   end
 
+  # Registers a command. Registered commands can be invoked by name, appear in command lists and
+  # allow --help docs.
+  # @param command [Map] The :invocation key is what would be typed to invoke the command and the :fn key is what function to execute when invoked. Specify only a :fn key for shorthand.
+  # @return [void]
   def self.register_command(command)
-    invocation = command[:invocation]
-    fn = command[:fn]
+    if command.nil?
+      self.new.error "register_command called with nil argument"
+      exit 1
+    end
+    if command.is_a?(Symbol)
+      invocation = command.to_s
+      fn = command
+    else
+      invocation = command[:invocation]
+      fn = command[:fn]
+    end
     if fn.nil?
       self.new.error "No :fn key defined for command #{invocation}"
       exit 1
@@ -40,13 +65,16 @@ class Pmgmt
       end
     end
 
-    @@commands.push(command)
+    @@commands.push({:invocation => invocation, :fn => fn})
   end
 
+  # @return [Array] the commands array for inspection.
   def self.commands()
     @@commands
   end
 
+  # Handles command execution.
+  # @param args [Array] Pass ARGV.
   def self.handle_or_die(args)
     if args.length == 0 or args[0] == "--help"
       self.new.print_usage
@@ -65,19 +93,27 @@ class Pmgmt
     command = args.first
     handler = @@commands.select{ |x| x[:invocation] == command }.first
     if handler.nil?
-      error "#{command} command not found."
+      self.new.error "#{command} command not found."
       exit 1
     end
 
     fn = handler[:fn]
+    args = args
     if fn.is_a?(Symbol)
-      method(fn).call(*args)
+      fn = method(fn)
+    else
+      args = args.drop(1)
+    end
+    if fn.arity == 0
+      fn.call()
     else
-      handler[:fn].call(*args.drop(1))
+      fn.call(*args)
     end
   end
 
+  # Convenience method to easily retrieve Docker utilities. See {#PmgmtLib::DockerHelper}.
   attr :docker
+  # Convenience method to easily retrieve file-syncing utilities. See {#PmgmtLib::SyncFiles}.
   attr :sf
 
   def initialize()
@@ -123,19 +159,25 @@ class Pmgmt
     "\033[1m#{text}\033[0m"
   end
 
+  # Prints "status" text (blue) on STDERR.
+  # @return [void]
   def status(text)
     STDERR.puts blue_term_text(text)
   end
 
+  # Prints "warning" text (yellow) on STDERR.
+  # @return [void]
   def warning(text)
     STDERR.puts yellow_term_text(text)
   end
 
+  # Prints "error" text (red) on STDERR.
+  # @return [void]
   def error(text)
     STDERR.puts red_term_text(text)
   end
 
-  def put_command(cmd, redact=nil)
+  def put_command(cmd, redact: nil)
     if cmd.is_a?(String)
       command_string = "+ #{cmd}"
     else
@@ -148,8 +190,11 @@ class Pmgmt
     STDERR.puts command_to_echo
   end
 
-  # Pass err=nil to suppress stderr.
-  def capture_stdout(cmd, err = STDERR)
+  # Runs the given command and captures its stdout.
+  # @param cmd [Array] Command to run.
+  # @param err: Pass nil to suppress stderr output.
+  # @return [String] Captured stdout.
+  def capture_stdout(cmd, err: STDERR)
     if err.nil?
       err = "/dev/null"
     end
@@ -157,8 +202,12 @@ class Pmgmt
     output
   end
 
-  def run_inline(cmd, redact=nil)
-    put_command(cmd, redact)
+  # Runs the given command "inline," meaning that it will take over the terminal while running.
+  # @param cmd [Array] Command to run.
+  # @param redact: [String] Occurrances of this string will be hidden from normal output.
+  # @return [void]
+  def run_inline(cmd, redact: nil)
+    put_command(cmd, redact: redact)
 
     # `system`, by design (?!), hides stderr when the command fails.
     if ENV["PROJECTRB_USE_SYSTEM"] == "true"
@@ -179,6 +228,7 @@ class Pmgmt
     end
   end
 
+  # Similar to {#run_inline} but will prevent exiting when an interrupt is encountered.
   def run_inline_swallowing_interrupt(cmd)
     begin
       run_inline cmd
@@ -186,8 +236,9 @@ class Pmgmt
     end
   end
 
-  def run_or_fail(cmd, redact=nil)
-    put_command(cmd, redact)
+  # Runs a command and fails on non-success exit code.
+  def run_or_fail(cmd, redact: nil)
+    put_command(cmd, redact: redact)
     Open3.popen3(*cmd) do |i, o, e, t|
       i.close
       if not t.value.success?
@@ -197,6 +248,8 @@ class Pmgmt
     end
   end
 
+  # Runs a command without echoing.
+  # @return [Status] command's exit status.
   def run(cmd)
     Open3.popen3(*cmd) do |i, o, e, t|
       i.close
@@ -204,6 +257,8 @@ class Pmgmt
     end
   end
 
+  # Accepts multiple arrays of commands and pipes each one to the next, failing if any command
+  # exits with an error.
   def pipe(*cmds)
     s = cmds.map { |x| x.join(" ") }
     s = s.join(" | ")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pmgmt
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - David Mohs
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-07-10 00:00:00.000000000 Z
+date: 2018-12-09 00:00:00.000000000 Z
 dependencies: []
 description: A library to make Ruby your preferred scripting language for dev scripts.
 email: davidmohs@gmail.com
@@ -17,12 +17,14 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/dockerhelper.rb
+- lib/optionsparser.rb
 - lib/pmgmt.rb
 - lib/syncfiles.rb
-homepage: http://rubygems.org/gems/pmgmt
+homepage: https://github.com/dmohs/project-management
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/dmohs/project-management
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -31,7 +33,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -39,7 +41,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 2.5.2.3
 signing_key: 
 specification_version: 4
 summary: Project management scripting library.