neverbounce-cli 1.0.0

data/lib/never_bounce/cli/script/jobs_search.rb

@@ -0,0 +1,135 @@
+
+require "neverbounce"
+
+require "never_bounce/cli/script/feature/uses_pagination"
+
+require_relative "request_maker"
+
+module NeverBounce; module CLI; module Script
+  class JobsSearch < RequestMaker
+    Script::Feature::UsesPagination.load(self)
+
+    attr_writer :job_id
+
+    envar "ID", "Filter by Job ID", ["276816"]
+
+    # Job ID. Default is <tt>env["ID"]</tt>.
+    # @!attribute job_id
+    # @return [String]
+    def job_id
+      igetset(:job_id) { env["ID"] }
+    end
+
+    # An <tt>API::Request::JobsSearch</tt>.
+    # @!attribute request
+    # @return [Object]
+    def request
+      @request ||= API::Request::JobsSearch.new({
+        api_key: api_key,
+        job_id: job_id,
+        page: page,
+        per_page: per_page,
+      })
+    end
+
+    #--------------------------------------- Manifest
+
+    # @!attribute manifest
+    # @return [Manifest]
+    def manifest
+      @manifest ||= Manifest.new(
+        name: "nb-jobs-search",
+        function: "List jobs",
+        cmdline: "[options] [VAR1=value] [VAR2=value] ...",
+      )
+    end
+
+    #--------------------------------------- Main
+
+    # @return [Integer]
+    def slim_main
+      "Response".tap do |label|
+        headings = [
+          ["nPages", :total_pages, :right],
+          ["nResults", :total_results, :right],
+
+          ["ExecTime", :execution_time, :right],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      "Query".tap do |label|
+        headings = [
+          ["Page", :page, :right],
+          ["PerPage", :items_per_page, :right],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response.query, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      "Results".tap do |label|
+        headings = [
+          ["ID", :id, :right],
+          ["JobStatus", :job_status, :center],
+          ["Filename", :filename, :center],
+          ["BncEst", ->(r) { r.bounce_estimate.round(2) }, :right],
+          ["Complete%", :percent_complete, :right],
+
+          [
+            "At",
+            ->(r) { [
+              "Created:#{inil(r.created_at)}",
+              "Started:#{inil(r.started_at)}",
+              "Finished:#{inil(r.finished_at)}",
+            ].join("\n") },
+            :right,
+          ],
+
+          [
+            "Total",
+            ->(r) { [
+              "BadSynt:#{inil(r.total.bad_syntax)}",
+              "Billable:#{inil(r.total.billable)}",
+              "Catchall:#{inil(r.total.catchall)}",
+              "Disp:#{inil(r.total.disposable)}",
+              "Dup:#{inil(r.total.duplicates)}",
+              "Invalid:#{inil(r.total.invalid)}",
+              "Proc'd:#{inil(r.total.processed)}",
+              "Records:#{inil(r.total.records)}",
+              "Unknown:#{inil(r.total.unknown)}",
+              "Valid:#{inil(r.total.valid)}",
+            ].join("\n") },
+            :right,
+          ],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: response.results.map do |r|
+            headings.map do |ar|
+              get_table_value(r, ar)
+            end
+          end,
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      0
+    end
+  end
+end; end; end

data/lib/never_bounce/cli/script/jobs_start.rb

@@ -0,0 +1,73 @@
+
+require "neverbounce"
+
+require "never_bounce/cli/script/feature/requires_job_id"
+
+require_relative "request_maker"
+
+module NeverBounce; module CLI; module Script
+  class JobsStart < RequestMaker
+    Script::Feature::RequiresJobId.load(self)
+
+    attr_writer :run_sample
+
+    envar (k = "RUN_SAMPLE"), *SHARED_ENVARS[k]
+
+    # @return [true]
+    # @return [false]
+    # @return [nil]
+    def run_sample
+      igetset(:run_sample) do
+        if env.has_key?(k = "RUN_SAMPLE")
+          env_truthy?(k)
+        end
+      end
+    end
+
+    # An <tt>API::Request::JobsStart</tt>.
+    # @!attribute request
+    # @return [Object]
+    def request
+      @request ||= API::Request::JobsStart.new({
+        api_key: api_key,
+        job_id: job_id,
+        run_sample: run_sample,
+      })
+    end
+
+    #--------------------------------------- Manifest
+
+    # @!attribute manifest
+    # @return [Manifest]
+    def manifest
+      @manifest ||= Manifest.new(
+        name: "nb-jobs-start",
+        function: "Start a job created with `auto_start` disabled",
+        cmdline: "[options] [VAR1=value] [VAR2=value] ...",
+      )
+    end
+
+    #--------------------------------------- Main
+
+    # @return [Integer]
+    def slim_main
+      "Response".tap do |label|
+        headings = [
+          ["QueueId", :queue_id],
+
+          ["ExecTime", :execution_time, :right],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      0
+    end
+  end
+end; end; end

data/lib/never_bounce/cli/script/jobs_status.rb

@@ -0,0 +1,96 @@
+
+require "neverbounce"
+
+require "never_bounce/cli/script/feature/requires_job_id"
+
+require_relative "request_maker"
+
+module NeverBounce; module CLI; module Script
+  class JobsStatus < RequestMaker
+    Script::Feature::RequiresJobId.load(self)
+
+    # An <tt>API::Request::JobsStatus</tt>.
+    # @!attribute request
+    # @return [Object]
+    def request
+      @request ||= API::Request::JobsStatus.new({
+        api_key: api_key,
+        job_id: job_id,
+      })
+    end
+
+    #--------------------------------------- Manifest
+
+    # @!attribute manifest
+    # @return [Manifest]
+    def manifest
+      @manifest ||= Manifest.new(
+        name: "nb-jobs-status",
+        function: "Get job status",
+        cmdline: "[options] [VAR1=value] [VAR2=value] ...",
+      )
+    end
+
+    #--------------------------------------- Main
+
+    # @return [Integer]
+    def slim_main
+      "Response".tap do |label|
+        headings = [
+          ["ID", :id, :right],
+
+          ["JStatus", :job_status, :center],
+          ["BncEst", ->(r) { r.bounce_estimate.round(2) }, :right],
+          ["Complete%", :percent_complete, :right],
+
+          [
+            "At",
+            ->(r) { [
+              "Created:#{inil(r.created_at)}",
+              "Started:#{inil(r.started_at)}",
+              "Finished:#{inil(r.finished_at)}",
+            ].join("\n") },
+            :right,
+          ],
+
+          ["Filename", :filename],
+
+          ["ExecTime", :execution_time, :right],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      "Total".tap do |label|
+        headings = [
+          ["BadSyntax", :bad_syntax, :right],
+          ["Billable", :billable, :right],
+          ["Catchall", :catchall, :right],
+          ["Disposable", :disposable, :right],
+          ["Duplicates", :duplicates, :right],
+          ["Invalid", :invalid, :right],
+          ["Processed", :processed, :right],
+          ["Records", :records, :right],
+          ["Unknown", :unknown, :right],
+          ["Valid", :valid, :right],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response.total, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      0
+    end
+  end
+end; end; end

data/lib/never_bounce/cli/script/manifest.rb

@@ -0,0 +1,22 @@
+
+require "never_bounce/cli/feature/basic_initialize"
+
+module NeverBounce; module CLI; module Script
+  # A short descriptive piece of information about the script.
+  # @see CLI::Feature::BasicInitialize
+  class Manifest
+    CLI::Feature::BasicInitialize.load(self)
+
+    # Script command-line options.
+    # @return [String]
+    attr_accessor :cmdline
+
+    # Script function, one line.
+    # @return [String]
+    attr_accessor :function
+
+    # Script name, as typed in a shell.
+    # @return [String]
+    attr_accessor :name
+  end
+end; end; end

data/lib/never_bounce/cli/script/meaningful.rb

@@ -0,0 +1,233 @@
+
+require "optparse"
+
+require "never_bounce/cli/feature/envars"
+require "never_bounce/cli/script/error"
+require "never_bounce/cli/script/manifest"    # Provide successors with the class they'll need.
+
+require_relative "base"
+
+module NeverBounce; module CLI; module Script
+  # A meaningful base script class. Features:
+  #
+  # * Handle command-line options.
+  # * Handle envars.
+  # * Handle boilerplate actions like printing usage on `--help`.
+  #
+  # @abstract
+  # @see CLI::Feature::Envars
+  # @see CLI::Feature::Igetset
+  class Meaningful < Base
+    CLI::Feature::Envars.load(self)
+    CLI::Feature::Igetset.load(self)
+
+    attr_writer :banner_text, :envar_text, :help_text, :manifest, :options_text
+
+    # @return [String]
+    def banner_text
+      @banner_text ||= "#{manifest.name} - #{manifest.function}"
+    end
+
+    # @return [String]
+    def envar_text
+      @envar_text ||= begin
+        max_width = (envars = self.class.envars).map(&:name).map(&:size).max
+        envars.sort_by { |_| [_.mandatory?? 0 : 1, _.name] }.map do |r|
+          "%s %-#{max_width}s - %s%s" % [
+            (r.mandatory?? "*" : "-"),
+            r.name,
+            r.comment,
+            (s = self.class.format_envar_examples(r)) ? " (#{s})" : "",
+          ]
+        end.join("\n")
+      end
+    end
+
+    # Exception classes which are rescued fromc in {#main} and printed to user.
+    # @note Should be a few very high-level excaptions which you fully control.
+    # @return [Array]
+    def self.error_klasses
+      [Error]
+    end
+
+    # <tt>true</tt> if help has been requested via command-line options.
+    def help?
+      !!options[:help]
+    end
+
+    def help_text
+      @help_text ||= begin
+        [
+          banner_text,
+          "",
+          "USAGE: #{manifest.name} #{manifest.cmdline}",
+          "",
+          options_text,
+          "",
+          "Environment variables:",
+          envar_text,
+        ].join("\n")
+      end
+    end
+
+    # Parse command-line options with <tt>OptionParser</tt>.
+    #
+    #   options   # => {:help => true}
+    #
+    # @note This isn't an attribute and there's no writer for it. For simulation and testing
+    #   we use {#argv=}.
+    # @return [Hash]
+    def options
+      @options ||= begin
+        h = {}
+
+        @option_parser = OptionParser.new do |opts|
+          opts.banner = ""    # A hack to remove Ruby's "-e".
+
+          opts.on("-h", "--help", "Show help information") do
+            h[:help] = true
+          end
+        end
+
+        rmn_options = begin
+          @option_parser.parse!(argv)
+        rescue OptionParser::ParseError => e
+          (h[:errors] ||= []) << "Error: #{e.message}"
+          retry
+        end
+
+        # Parse and add "KEY=value" options to environment.
+        rmn_options.reject! do |s|
+          if s =~ /^(\w+)=(.*)$/m     # NOTE: `/m` allows for multiline options.
+            env[$1] = $2
+            true
+          end
+        end
+
+        # Treat remaining options as errors.
+        # If this behaviour changes, we should provide access to `rmn_options` via method.
+        rmn_options.each do |s|
+          (h[:errors] ||= []) << "Error: unexpected option: #{s}"
+        end
+
+        h
+      end
+    end
+
+    # Our <tt>OptionParser</tt> object.
+    def option_parser
+      options if not @options
+      @option_parser
+    end
+
+    def options_text
+      @options_text ||= option_parser.help.strip
+    end
+
+    #---------------------------------------
+
+    # Invoke one of the slim_main methods available in self.
+    #
+    #   call_slim_main(3)   # Try <tt>slim_main3</tt>, then <tt>slim_main2</tt> down to <tt>slim_main</tt>.
+    #
+    # @return [Integer] Result of <tt>slim_main[N]</tt>.
+    def call_slim_main(from_level = 3)
+      from_level.downto(0) do |i|
+        if respond_to?(m = "slim_main#{i > 0 ? i : ''}")
+          return send(m)
+        end
+      end
+
+      # This is in theory possible, stay sane.
+      raise "No `slim_main` responded, check your class hierarchy"
+    end
+    private :call_slim_main
+
+    #--------------------------------------- `main` and its friends
+
+    # Format an envar examples string.
+    #
+    #   format_examples_string(envar)   # => ""a", *"B""
+    #
+    # @return [String] Insertion-ready string or <tt>nil</tt> if envar doesn't have examples.
+    def self.format_envar_examples(envar)
+      return nil if envar.examples.empty?
+
+      envar.examples.map do |v|
+        if envar.default and v == envar.default
+          "[" + v.inspect + "]"
+        else
+          v.inspect
+        end
+      end.join(", ")
+    end
+
+    # Handle help request and invalid options.
+    # @note See method source for important details.
+    # @return [Integer] Program exit code (0, 1) if the program should exit now.
+    # @return [nil] If all okay.
+    def handle_help_and_options
+      # NOTES:
+      #
+      # * Due to `OptionParser` specifics we don't use on-the-fly handling of options.
+      #   We do it procedurally instead, to avoid running into a circular dependency.
+      #   Thus, it's okay to call this method directly in specs as long as `argv` is concerned.
+      # * The method has internal protection to ensure it's called just ones to make speccing a bit easier.
+      igetset(:handle_help_and_options) do
+        if help?
+          # We ignore errors if there's a help request.
+          stdout.puts help_text
+          0
+        elsif (ar = options[:errors])
+          stderr.puts ar
+          1
+        end
+      end
+    end
+
+    # Program manifest object. Successors should return it.
+    # @abstract
+    # @return [Manicest]
+    def manifest
+      raise NotImplementedError, "Redefine `manifest` in your class: #{self.class}"
+    end
+
+    # Main routine which handles most boilerplate.
+    # @return [Integer]
+    # @see #slim_main
+    def main
+      # Handle top-level errors like `UsageError`.
+      begin
+        if (res = handle_help_and_options)
+          return res
+        end
+
+        # Invoke dump'n'exit, if `def dx` defined.
+        # NOTE: This code is production-compatible. It's active only if final script responds to `dx`, which is strictly debug-time.
+        if respond_to? :dx and env_truthy? "DX"
+          dx
+          return 1
+        end
+
+        # Do it.
+        result = call_slim_main
+
+        # Help us stay sane.
+        raise "Unknown `slim_main` result: #{result.inspect}" if not result.is_a? Integer
+
+        result
+      rescue *self.class.error_klasses => e
+        stderr.puts "#{e.class.to_s.split('::').last}: #{e.message}"    # Like "UsageError: this and that".
+        1
+      end
+    end
+
+    # Slim or "real" main routine of the successor class.
+    # Called by {#main} considering all boilerplate has been taken care of.
+    # @abstract
+    # @return [Integer]
+    def slim_main
+      raise NotImplementedError, "Redefine `slim_main` in your class: #{self.class}"
+    end
+  end
+end; end; end