neverbounce-cli 1.0.0

data/lib/never_bounce/cli/feature/envars/item.rb

@@ -0,0 +1,41 @@
+
+require "never_bounce/cli/feature/basic_initialize"
+require "never_bounce/cli/feature/igetset"
+
+require_relative "../envars"
+
+module NeverBounce; module CLI; module Feature; module Envars
+  # Single envar item container.
+  class Item
+    CLI::Feature::BasicInitialize.load(self)
+    CLI::Feature::Igetset.load(self)
+
+    # @return [String]
+    attr_accessor :name
+
+    # @return [String]
+    attr_accessor :comment
+
+    attr_writer :default, :examples, :is_mandatory
+
+    # Default value. Default is <tt>nil</tt>.
+    # @return [mixed]
+    def default
+      igetset(:default) { nil }
+    end
+
+    # Value examples. Default is <tt>[]</tt>.
+    # @return [Array]
+    def examples
+      @examples ||= []
+    end
+
+    # True if this envar is mandatory. Default is <tt>false</tt>.
+    # @return [bool]
+    def is_mandatory
+      igetset(:is_mandatory) { false }
+    end
+
+    alias_method :mandatory?, :is_mandatory
+  end
+end; end; end; end

data/lib/never_bounce/cli/feature/envars.rb

@@ -0,0 +1,82 @@
+
+module NeverBounce; module CLI; module Feature
+  # Declare and manage environment variables of the class.
+  module Envars
+    require_relative "envars/examples_mapper"
+    require_relative "envars/item"
+
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.extend(ClassMethods)
+      owner.send(:include, InstanceMethods)
+    end
+
+    module ClassMethods
+      attr_writer :envars
+
+      def envars
+        @envars ||= if superclass.respond_to? :envars
+          superclass.envars.dup
+        else
+          []
+        end
+      end
+
+      #---------------------------------------
+      private
+
+      # Define an envar in a formal way.
+      # @param name [String]
+      # @param comment [String]
+      # @return [Item]
+      def define_envar(name, comment, is_mandatory: false, examples: [], default: nil)
+        Item.new({
+          name: name,
+
+          comment: comment,
+          default: default,
+          examples: examples,
+          is_mandatory: is_mandatory,
+        }).tap { |_| envars << _ }
+      end
+
+      # Declare an envar in a concise and magical way.
+      #
+      #   envar "ID", "Job ID"
+      #   => define_envar "ID", "Job ID"
+      #   envar "API_KEY*", "API key", ["2ed45186c72f9319dc64338cdf16ab76b44cf3d1"]
+      #   # => define_envar "API_KEY", "API key", is_mandatory: true, examples: [...]
+      #   envar "RAW", "Print raw response body", ["y", default: "N"]
+      #   # => define_envar "RAW", "Print raw response body", examples: ["y", "N"], default: "N"
+      def envar(name, comment, examples = [])
+        options = {}
+
+        real_name = if name[-1] == "*"
+          options[:is_mandatory] = true
+          name[0..-2]
+        else
+          name
+        end
+
+        if not examples.empty?
+          h = ExamplesMapper.new[examples]
+          options[:examples] = h[:values]
+          options[:default] = h[:default] if h.include?(:default)
+        end
+
+        define_envar(real_name, comment, options)
+      end
+    end
+
+    module InstanceMethods
+    end
+  end
+end; end; end
+
+#
+# Implementation notes:
+#
+# * `envars` belongs to the class, but considering its superclasses.
+#   We don't use @@var to avoid unnecessary side effect.

data/lib/never_bounce/cli/feature/igetset.rb

@@ -0,0 +1,41 @@
+
+module NeverBounce; module CLI; module Feature
+  # @see InstanceMethods#igetset
+  module Igetset
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+    end
+
+    module InstanceMethods
+      private
+
+      # Get/set an OTF instance variable of any type.
+      #
+      # Ruby's <tt>||=</tt> works nicely with object instances, but requires special bulky treatment for <tt>nil</tt> and <tt>false</tt>.
+      # For example, this will cause a hidden glitch since <tt>==</tt> can evaluate to <tt>false</tt>:
+      #
+      #   @is_verbose ||= begin
+      #     # This clause will be evaluated *every time* if its value is `false`.
+      #     ENV["VERBOSE"] == "y"
+      #   end
+      #
+      # There's a number of solutions to this problem, all of which involve calling <tt>instance_variable_*</tt> a few times per attribute accessor.
+      #
+      # <tt>igetset</tt> does this job for you. All you have to do is specify a block to compute the value.
+      #
+      #   igetset(:is_verbose) { ENV["VERBOSE"] == "y" }
+      #
+      # See source for details.
+      def igetset(name, &compute)
+        if instance_variable_defined?(k = "@#{name}")
+          instance_variable_get(k)
+        else
+          instance_variable_set(k, compute.call)
+        end
+      end
+    end
+  end
+end; end; end

data/lib/never_bounce/cli/feature/require_attr.rb

@@ -0,0 +1,25 @@
+
+module NeverBounce; module CLI; module Feature
+  # Provide attribute validation method(s) to the owner class.
+  # @see InstanceMethods#initialize
+  module RequireAttr
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+    end
+
+    module InstanceMethods
+      private
+
+      # Require attribute to be set. Return attribute value.
+      # @return [mixed]
+      def require_attr(name)
+        send(name).tap do |_|
+          raise "Attribute must be set: #{name}" if _.nil?
+        end
+      end
+    end
+  end
+end; end; end

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

@@ -0,0 +1,85 @@
+
+require "neverbounce"
+
+require_relative "request_maker"
+
+module NeverBounce; module CLI; module Script
+  class AccountInfo < RequestMaker
+    # An <tt>API::Request::AccountInfo</tt>.
+    # @!attribute request
+    # @return [Object]
+    def request
+      @request ||= API::Request::AccountInfo.new({
+        api_key: api_key,
+      })
+    end
+
+    #--------------------------------------- Manifest
+
+    # @!attribute manifest
+    # @return [Manifest]
+    def manifest
+      @manifest ||= Manifest.new(
+        name: "nb-account-info",
+        function: "Check account balance",
+        cmdline: "[options] [VAR1=value] [VAR2=value] ...",
+      )
+    end
+
+    #--------------------------------------- Main
+
+    # @return [Integer]
+    def slim_main
+      "Response".tap do |label|
+        headings = [
+          ["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
+
+      "Credits".tap do |label|
+        headings = [
+          ["FreeRmn", :free_credits_remaining, :right],
+          ["FreeUsed", :free_credits_used, :right],
+          (["MonthlyUsage", :monthly_api_usage, :right] if response.credits_info.monthly?),
+          (["PaidRmn", :paid_credits_remaining, :right] if response.credits_info.paid?),
+          (["PaidUsed", :paid_credits_used, :right] if response.credits_info.paid?),
+        ].compact
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response.credits_info, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      "JobCounts".tap do |label|
+        headings = [
+          ["Completed", :completed, :right],
+          ["Processing", :processing, :right],
+          ["Queued", :queued, :right],
+          ["UnderReview", :under_review, :right],
+        ]
+
+        table = Table.new(
+          headings: headings.map { |ar| ar[0] },
+          rows: [headings.map { |ar| get_table_value(response.job_counts, ar) }],
+        ).align!(headings)
+
+        stdout.puts "\n#{label}:"
+        stdout.puts table
+      end
+
+      0
+    end
+  end
+end; end; end

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

@@ -0,0 +1,101 @@
+
+require "shellwords"
+
+require "never_bounce/cli/feature/basic_initialize"
+require "never_bounce/cli/feature/require_attr"
+
+module NeverBounce; module CLI; module Script
+  # Barebones script base class.
+  # @abstract
+  # @see CLI::Feature::BasicInitialize
+  # @see CLI::Feature::RequireAttr
+  class Base
+    CLI::Feature::BasicInitialize.load(self)
+    CLI::Feature::RequireAttr.load(self)
+
+    attr_writer :argv, :env, :stderr, :stdout
+
+    # Command-line arguments. Default is <tt>ARGV</tt>.
+    # @return [Array]
+    def argv
+      @argv ||= ARGV
+    end
+
+    # A *copy* of the environment for value-reading purposes. Default is <tt>ENV.to_h</tt>.
+    # @!attribute env
+    # @return [Hash]
+    def env
+      # Ruby's `ENV` is a weird thing.
+      # It's a direct `Object` which acts like `Hash`.
+      # It can't be reliably dup'd cloned, at the same time writes to it are invocation-global.
+      # This implicit read/write nature of `ENV` is a major hassle in tests, since it creates unnecessary side effects we have to tackle with specifically.
+      # Solution for now:
+      #
+      # 1. Since 99% of the time our script isn't interested in *writing* to ENV, this method deals with the READ case as the most widely used one.
+      # 2. If we ever need to write to ENV in order to *create* the environment for a child process or something, we'll find a way to do it with grace.
+      #
+      # Everything above is a comment to `.to_h`, mysteriously present on the next line.
+      @env ||= ENV.to_h
+    end
+
+    # Script's error stream. Default is <tt>STDERR</tt>.
+    # @return [IO]
+    def stderr
+      @stderr ||= STDERR
+    end
+
+    # Script's output stream. Default is <tt>STDOUT</tt>.
+    # @return [IO]
+    def stdout
+      @stdout ||= STDOUT
+    end
+
+    # <tt>true</tt> if the script should be verbose.
+    # @return [true]
+    def verbose?
+      true
+    end
+
+    #--------------------------------------- Service
+
+    # @see #env_truthy?
+    def env_falsey?(k)
+      !env_truthy?(k)
+    end
+
+    # Return <tt>true</tt> if environment variable <tt>k</tt> is truthy.
+    #
+    #   env_truthy? "WITH_HTTP"   # => `true` or `false`
+    #   env_truthy? :WITH_HTTP    # same as above
+    def env_truthy?(k)
+      self.class.env_value_truthy?(env[k.to_s])
+    end
+
+    # Return <tt>true</tt> if environment variable value is truthy.
+    #
+    #   # These are truthy.
+    #   DEBUG=1
+    #   DEBUG=true
+    #   DEBUG=y
+    #   DEBUG=yes
+    def self.env_value_truthy?(s)
+      ["1", "true", "y", "yes"].include? s.to_s.downcase
+    end
+
+    # Run system command, print it if verbose.
+    # @return [mixed] Result of <tt>Kernel.system</tt>.
+    def system(cmd, *args)
+      puts "### #{cmd} #{args.map(&:shellescape).join(' ')}" if verbose?
+      Kernel.system(cmd, *args)
+    end
+
+    #---------------------------------------
+
+    # Main routine.
+    # @abstract
+    # @return [Integer]
+    def main
+      raise NotImplementedError, "Redefine `main` in your class: #{self.class}"
+    end
+  end
+end; end; end

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

@@ -0,0 +1,16 @@
+
+module NeverBounce; module CLI; module Script
+  # Base script error class.
+  class Error < StandardError; end
+
+  # Something went wrong in the protocol land.
+  class ProtocolError < Error; end
+
+  # User didn't provide sufficient options, other stuff of that kind.
+  class UsageError < Error; end
+end; end; end
+
+#
+# Implementation notes:
+#
+# * The file is named after the base class to follow the convention.

data/lib/never_bounce/cli/script/feature/requires_job_id.rb

@@ -0,0 +1,28 @@
+
+module NeverBounce; module CLI; module Script; module Feature
+  # Common traits for scripts which require job ID.
+  # @see InstanceMethods
+  module RequiresJobId
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+
+      owner.class_eval do
+        attr_writer :job_id
+
+        envar "ID", "Job ID", ["276816"]
+      end
+    end
+
+    module InstanceMethods
+      # Job ID. Default is <tt>env["ID"]</tt>.
+      # @!attribute job_id
+      # @return [String]
+      def job_id
+        @job_id ||= env[k = "ID"] or raise UsageError, "Job ID not given, use `#{k}=`"
+      end
+    end
+  end
+end; end; end; end

data/lib/never_bounce/cli/script/feature/uses_pagination.rb

@@ -0,0 +1,45 @@
+
+module NeverBounce; module CLI; module Script; module Feature
+  # Common traits for scripts which support pagination.
+  # @see InstanceMethods
+  module UsesPagination
+    # @param owner [Class]
+    # @return [nil]
+    def self.load(owner)
+      return if owner < InstanceMethods
+      owner.send(:include, InstanceMethods)
+
+      owner.class_eval do
+        attr_writer :page, :per_page
+
+        envar "PAGE", "Fetch page number N", [{default: 1}, 5]
+        envar "PER_PAGE", "Paginate results N items per page", [10, default: 1000]
+      end
+    end
+
+    module InstanceMethods
+      # Page number. Default is <tt>env["PAGE"]</tt>.
+      # @!attribute page
+      # @return [Integer]
+      def page
+        # OPTIMIZE: Consider default-less behaviour some day.
+        @page ||= if (v = env["PAGE"])
+          Integer(v)
+        else
+          1
+        end
+      end
+
+      # Items per page. Default is <tt>env["PER_PAGE"]</tt>.
+      # @!attribute per_page
+      # @return [Integer]
+      def per_page
+        @per_page ||= if (v = env["PER_PAGE"])
+          Integer(v)
+        else
+          1000
+        end
+      end
+    end
+  end
+end; end; end; end