command_line_boss 0.1.0

data/examples/create_spreadsheet/spec/create_spreadsheet/command_line.feature

@@ -0,0 +1,239 @@
+Feature: CreateSpreadsheet::Cli#parse
+
+Parse the create-spreadsheet command line
+
+  Example: Nothing is given on the command line
+    Given the command line ""
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the title attribute should be nil
+    And the sheets attribute should be empty
+    And the permissions attribute should be empty
+    And the folder_id attribute should be nil
+
+  Example: A spreadsheet title is given
+    Given the command line "MySpreadsheet"
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the title attribute should be "MySpreadsheet"
+
+  Example: A sheet is defined with a title
+    Given the command line "--sheet=Summary"
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the sheets attribute should contain the following Sheets:
+      """
+        [
+          {
+            title: "Summary",
+            data: nil
+          }
+        ]
+      """
+
+  Example: A sheet is defined with a title and data
+    Given the command line "--sheet=Summary --data=data1.csv"
+    And a file "data1.csv" containing:
+      """
+      1,2,3
+      4,5,6
+      """
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the sheets attribute should contain the following Sheets:
+      """
+        [
+          {
+            "title": "Summary",
+            "data": [["1", "2", "3"], ["4", "5", "6"]]
+          }
+        ]
+      """
+
+  Example: Multiple sheets are defined both with data
+    Given the command line "--sheet=Summary --data=summary.csv --sheet=Detail --data=detail.csv"
+    And a file "summary.csv" containing:
+      """
+      6
+      """
+    And a file "detail.csv" containing:
+      """
+      1
+      2
+      3
+      """
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the sheets attribute should contain the following Sheets:
+      """
+      [
+        { "title": "Summary", "data": [["6"]] },
+        { "title": "Detail", "data": [["1"], ["2"], ["3"]] }
+      ]
+      """
+
+  Example: Multiple sheets are defined only one with data
+    Given the command line "--sheet=Summary --sheet=Detail --data=detail.csv"
+    And a file "detail.csv" containing:
+      """
+      Name,Age
+      John,25
+      Jane,23
+      """
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the sheets attribute should contain the following Sheets:
+      """
+      [
+        { title: "Summary", data: nil },
+        { title: "Detail", data: [["Name", "Age"], ["John", "25"], ["Jane", "23"]] }
+      ]
+      """
+
+  Example: A user permission is given
+    Given the command line "--permission=user:bob@example.com:reader"
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the permissions attribute should contain the following Permissions:
+      """
+      [
+        {
+          "permission_spec": "user:bob@example.com:reader",
+          "type": "user", "subject": "bob@example.com", "role": "reader"
+        }
+      ]
+      """
+
+  Example: A group permission is given
+    Given the command line "--permission=group:admins@example.com:writer"
+
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the permissions attribute should contain the following Permissions:
+      """
+      [
+        {
+          "permission_spec": "group:admins@example.com:writer",
+          "type": "group", "subject": "admins@example.com", "role": "writer"
+        }
+      ]
+      """
+
+  Example: A domain permission is given
+    Given the command line "--permission=domain:domain_name:reader"
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the permissions attribute should contain the following Permissions:
+      """
+      [
+        {
+          "permission_spec": "domain:domain_name:reader",
+          "type": "domain", "subject": "domain_name", "role": "reader"
+        }
+      ]
+      """
+
+  Example: An anyone permission is given
+    Given the command line "--permission=anyone:reader"
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the permissions attribute should contain the following Permissions:
+      """
+      [
+        {
+          permission_spec: "anyone:reader", type: "anyone", subject: nil, role: "reader"
+        }
+      ]
+      """
+
+  Example: Multiple permissions are given
+    Given the command line "--permission=user:bob@example.com:writer --permission=anyone:reader"
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the permissions attribute should contain the following Permissions:
+      """
+      [
+        {
+          permission_spec: "user:bob@example.com:writer", type: "user", subject: "bob@example.com", role: "writer"
+        },
+        {
+          permission_spec: "anyone:reader", type: "anyone", subject: nil, role: "reader"
+        }
+      ]
+      """
+
+  Example: A folder is given
+    Given the command line "--folder=0ALLuhm2AwwlJUk9PVA"
+    When the command line is parsed
+    Then the parser should have succeeded
+    And the folder_id attribute should be "0ALLuhm2AwwlJUk9PVA"
+
+  # Failure cases
+
+  Example: A sheet given without a name
+    Given the command line "--sheet"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: missing argument: --sheet"
+
+  Example: A permission is given without a permission spec
+    Given the command line "--permission"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: missing argument: --permission"
+
+  Example: A invalid permission is given
+    Given the command line "--permission=anyone-writer"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: Invalid permission: anyone-writer"
+
+  Example: The permission spec has an invalid type
+    Given the command line "--permission=invalid:test@example.com:reader"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: Invalid permission type: invalid"
+
+  Example: A permission spec has an invalid role
+    Given the command line "--permission=user:test@example.com:invalid"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: Invalid permission role: invalid"
+
+  Example: A subject is given for an anyone permission
+    Given the command line "--permission=anyone:test@example.com:reader"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: An anyone permission must not have a subject"
+
+  Example: A subject is not given for a user permission
+    Given the command line "--permission=user:writer"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: A user permission must have a subject"
+
+  Example: Data is given without a path
+    Given the command line "--sheet=Summary --data"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: missing argument: --data"
+
+  Example: Data is given with an non-existant path
+    Given the command line "--sheet=Summary --data=nonexistent.csv"
+    And the file "nonexistent.csv" does not exist
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: Data file not found: nonexistent.csv"
+
+  Example: The folder option is given twice
+    Given the command line "--folder=0ALLuhm2AwwlJUk9PVA --folder=0ALLuhm2AwwlJUk9PVA"
+    When the command line is parsed
+
+  Example: A same sheet name is given twice
+    Given the command line "--sheet=Summary --sheet=Summary"
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: The sheet Summary was given more than once"
+
+  Example: Data is given twice for the same sheet
+    Given the command line "--sheet=Summary --data=data1.csv --data=data2.csv"
+    And a file "data1.csv" containing:
+      """
+      1
+      """
+    And a file "data2.csv" containing:
+      """
+      2
+      """
+    When the command line is parsed
+    Then the parser should have failed with the error "ERROR: Only one data file is allowed per sheet"

data/examples/create_spreadsheet/spec/create_spreadsheet/command_line_steps.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+step 'the command line :command_line' do |command_line|
+  @args = command_line.split
+end
+
+# step 'the command line is parsed' do
+#   @options = CreateSpreadsheetCli.new.parse(@args)
+# end
+
+step 'the command line is parsed' do
+  stdout = StringIO.new
+  stderr = StringIO.new
+  original_stdout = $stdout
+  original_stderr = $stderr
+
+  begin
+    $stdout = stdout
+    $stderr = stderr
+    @options = CreateSpreadsheet::CommandLine.new.parse(@args)
+  rescue StandardError => e
+    @error = e
+    @options = e.parser
+  ensure
+    $stdout = original_stdout
+    $stderr = original_stderr
+  end
+
+  @stdout = stdout.string
+  @stderr = stderr.string
+end
+
+step 'the parser should have succeeded' do
+  expect(@options.error_messages).to eq([])
+  expect(@error).to be_nil
+  expect(@stdout).to be_empty
+  expect(@stderr).to be_empty
+end
+
+step 'the parser should have failed' do
+  expect(@options.error_messages).not_to be_empty
+  expect(@error).to be_nil
+  expect(@stdout).to be_empty
+  expect(@stderr).to be_empty
+end
+
+step 'the parser should have failed with the error :message' do |message|
+  expect(@options.error_messages).not_to be_empty
+  expect(@error).to be_nil
+  expect(@stdout).to be_empty
+  expect(@stderr).to be_empty
+  expect(@options.error_messages).to include(message)
+end
+
+step 'the :attribute attribute should be nil' do |attribute|
+  expect(@options.send(attribute.to_sym)).to be_nil
+end
+
+step 'the :attribute attribute should be empty' do |attribute|
+  expect(@options.send(attribute.to_sym)).to be_empty
+end
+
+step 'the :attribute attribute should be ":value"' do |attribute, value|
+  expect(@options.send(attribute.to_sym)).to eq(value)
+end
+
+step 'the sheets attribute should contain the following Sheets:' do |hash_as_string|
+  # rubocop:disable Security/Eval
+  expected_sheets = eval(hash_as_string).map { |s| CreateSpreadsheet::Sheet.new(s) }
+  # rubocop:enable Security/Eval
+  expect(@options.sheets).to match_array(expected_sheets)
+end
+
+RSpec.configure do |config|
+  config.before(type: :feature) do
+    allow(File).to receive(:read).and_call_original
+  end
+end
+
+step 'a file :path containing:' do |path, content|
+  allow(File).to receive(:read).with(path).and_return(content)
+end
+
+step 'the file :path does not exist' do |path|
+  allow(File).to receive(:read).with(path).and_raise(Errno::ENOENT, "No such file or directory @ rb_sysopen - #{path}")
+end
+
+step 'the permissions attribute should contain the following Permissions:' do |hash_as_string|
+  # rubocop:disable Security/Eval
+  expected_permissions = eval(hash_as_string).map { |p| CreateSpreadsheet::Permission.new(p) }
+  # rubocop:enable Security/Eval
+  expect(@options.permissions).to match_array(expected_permissions)
+end

data/examples/create_spreadsheet/spec/spec_helper.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# Turnip setup
+#
+require 'turnip/rspec'
+Dir[File.join(__dir__, '**/*_steps.rb')].each { |f| require f }
+
+RSpec.configure do |config|
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = '.rspec_status'
+
+  # Disable RSpec exposing methods globally on `Module` and `main`
+  config.disable_monkey_patching!
+
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+end
+
+# Setup simplecov
+
+require 'simplecov'
+require 'simplecov-lcov'
+require 'json'
+
+SimpleCov.formatters = [SimpleCov::Formatter::HTMLFormatter, SimpleCov::Formatter::LcovFormatter]
+
+# Return `true` if the environment variable is set to a truthy value
+#
+# @example
+#   env_true?('COV_SHOW_UNCOVERED')
+#
+# @param name [String] the name of the environment variable
+# @return [Boolean]
+#
+def env_true?(name)
+  value = ENV.fetch(name, '').downcase
+  %w[yes on true 1].include?(value)
+end
+
+# Return `true` if the environment variable is NOT set to a truthy value
+#
+# @example
+#   env_false?('COV_NO_FAIL')
+#
+# @param name [String] the name of the environment variable
+# @return [Boolean]
+#
+def env_false?(name)
+  !env_true?(name)
+end
+
+# Return `true` if the the test run should fail if the coverage is below the threshold
+#
+# @return [Boolean]
+#
+def fail_on_low_coverage?
+  !(RSpec.configuration.dry_run? || env_true?('COV_NO_FAIL'))
+end
+
+# Return `true` if the the test run should show the lines not covered by tests
+#
+# @return [Boolean]
+#
+def show_lines_not_covered?
+  env_true?('COV_SHOW_UNCOVERED')
+end
+
+# Report if the test coverage was below the configured threshold
+#
+# The threshold is configured by setting the `test_coverage_threshold` variable
+# in this file.
+#
+# Example:
+#
+# ```Ruby
+# test_coverage_threshold = 100
+# ```
+#
+# Coverage below the threshold will cause the rspec run to fail unless the
+# `COV_NO_FAIL` environment variable is set to TRUE.
+#
+# ```Shell
+# COV_NO_FAIL=TRUE rspec
+# ```
+#
+# Example of running the tests in an infinite loop writing failures to `fail.txt`:
+#
+# ```Shell
+# while true; do COV_NO_FAIL=TRUE rspec >> fail.txt; done
+# ````
+#
+# The lines missing coverage will be displayed if the `COV_SHOW_UNCOVERED`
+# environment variable is set to TRUE.
+#
+# ```Shell
+# COV_SHOW_UNCOVERED=TRUE rspec
+# ```
+#
+test_coverage_threshold = 100
+
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  # rubocop:disable Style/StderrPuts
+  if SimpleCov.result.covered_percent < test_coverage_threshold
+    $stderr.puts
+    $stderr.print 'FAIL: ' if fail_on_low_coverage?
+    $stderr.puts "RSpec Test coverage fell below #{test_coverage_threshold}%"
+
+    if show_lines_not_covered?
+      $stderr.puts "\nThe following lines were not covered by tests:\n"
+      SimpleCov.result.files.each do |source_file| # SimpleCov::SourceFile
+        source_file.missed_lines.each do |line| # SimpleCov::SourceFile::Line
+          $stderr.puts "  .#{source_file.project_filename}:#{line.number}"
+        end
+      end
+    end
+
+    $stderr.puts
+
+    exit 1 if fail_on_low_coverage?
+  end
+  # rubocop:enable Style/StderrPuts
+end
+
+SimpleCov.start do
+  enable_coverage :branch
+end
+
+require 'create_spreadsheet'

data/examples/readme_example/create-spreadsheet

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'command_line_boss'
+
+# Define a command line interface for creating a spreadsheet
+class CreateSpreadsheetCli < CommandLineBoss
+  attr_reader :spreadsheet_name, :sheet_names
+
+  private
+
+  def set_defaults
+    @spreadsheet_name = nil
+    @sheet_names = []
+  end
+
+  def define_sheet_option
+    parser.on('--sheet=SHEET_NAME', 'Name of a sheet to create') do |name|
+      add_error_message('Sheet names must be unique!') if sheet_names.include?(name)
+      sheet_names << name
+    end
+  end
+
+  def validate_spreadsheet_name_given
+    add_error_message('A spreadsheet name is required') if spreadsheet_name.nil?
+  end
+
+  def validate_at_least_one_sheet_name_given
+    add_error_message('At least one sheet name is required') if sheet_names.empty?
+  end
+
+  def parse_arguments
+    @spreadsheet_name = args.shift
+  end
+
+  include CommandLineBoss::HelpOption
+
+  def banner = <<~BANNER
+    Create a spreadsheetasdf
+
+    Usage:
+      create_spreadsheet SPREADSHEET_NAME --sheet=SHEET_NAME [--sheet=SHEET_NAME ...]
+
+  BANNER
+end
+
+# Parse the command line arguments
+
+options = CreateSpreadsheetCli.new.parse(ARGV)
+
+# Report errors
+
+if options.failed?
+  warn options.error_messages.join("\n")
+  exit 1
+end
+
+# Do something with the result
+
+require 'pp'
+
+puts \
+  "Creating spreadsheet #{options.spreadsheet_name.pretty_inspect.chomp} " \
+  "with sheets #{options.sheet_names.map(&:pretty_inspect).map(&:chomp).join(', ')}"

data/lib/command_line_boss/help_option.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+class CommandLineBoss
+  # Add the --help option
+  module HelpOption
+    private
+
+    # Define the command line options
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def define_options
+      add_banner
+      add_header
+      super
+      add_footer
+    end
+
+    # Define the --help option
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def define_help_option
+      parser.on('-h', '--help', 'Show this message') do
+        puts parser.help
+        exit
+      end
+    end
+
+    # Adds the banner to the parser output
+    # @return [void]
+    # @api private
+    #
+    def add_banner
+      return unless banner
+
+      parser.banner = banner
+    end
+
+    # Derived classes should override this method to provide a banner
+    # @return [String, nil]
+    # @api private
+    #
+    def banner = nil
+
+    # Adds the header to the parser output
+    # @return [void]
+    # @api private
+    #
+    def add_header
+      return unless header
+
+      parser.separator header
+    end
+
+    # Derived classes should override this method to provide a header
+    # @return [String, nil]
+    # @api private
+    #
+    def header = nil
+
+    # Adds the footer to the parser output
+    # @return [void]
+    # @api private
+    #
+    def add_footer
+      return unless footer
+
+      parser.separator footer
+    end
+
+    # Derived classes should override this method to provide a footer
+    # @return [String, nil]
+    # @api private
+    #
+    def footer = nil
+  end
+end

data/lib/command_line_boss/logger_options.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+class CommandLineBoss
+  # Add --debug and --verbose options and a logger method
+  module LoggerOptions
+    # true if the --debug option was given
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    #
+    attr_reader :debug
+
+    # true if the --verbose option was given
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    #
+    attr_reader :verbose
+
+    # The logger to use to report progress
+    #
+    # Messages are logged at info and debug levels. The logger returned is one of
+    # the following:
+    #
+    # * A logger that logs to the console at the :info level if verbose mode is enabled
+    # * A logger that logs to the console at the :debug level if debug mode is enabled
+    # * Otherwise a null logger that does not log anything
+    #
+    # @example
+    #   options.logger #=> #<Logger:0x00007f9e3b8b3e08>
+    #
+    # @return [Logger]
+    #
+    def logger
+      @logger ||=
+        if verbose
+          verbose_logger
+        elsif debug
+          debug_logger
+        else
+          Logger.new(nil, level: Logger::UNKNOWN + 1)
+        end
+    end
+
+    private
+
+    # Define the --verbose option
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def define_verbose_option
+      parser.on('-v', '--verbose', 'Enable verbose mode (default is off)') do |verbose|
+        @verbose = verbose
+      end
+    end
+
+    # Define the --debug option
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def define_debug_option
+      parser.on('-D', '--debug', 'Enable debug mode default is off') do |debug|
+        @debug = debug
+      end
+    end
+
+    # Ensure that the --debug and --verbose options are not both given
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def validate_debug_verbose_option
+      add_error_message('Can not give both --debug and --verbose') if debug && verbose
+    end
+
+    # A Logger that logs to the console at the :debug level with a simple formatter
+    #
+    # @return [Logger]
+    #
+    # @api private
+    #
+    def debug_logger
+      Logger.new($stdout, level: 'debug', formatter: ->(_severity, _datetime, _progname, msg) { "#{msg}\n" })
+    end
+
+    # A Logger that logs to the console at the :info level with a simple formatter
+    #
+    # @return [Logger]
+    #
+    # @api private
+    #
+    def verbose_logger
+      Logger.new($stdout, level: 'info', formatter: ->(_severity, _datetime, _progname, msg) { "#{msg}\n" })
+    end
+  end
+end