command_line_boss 0.1.0

data/examples/create_spreadsheet/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'command_line_boss', path: File.expand_path(`git rev-parse --show-toplevel`.chomp)
+
+gem 'create_spreadsheet', path: '.'
+
+gem 'csv', '~> 3.3'
+gem 'fuubar', '~> 2.5'
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'rubocop', '~> 1.64'
+gem 'simplecov', '~> 0.22'
+gem 'simplecov-lcov', '~> 0.8'
+gem 'turnip', '~> 4.4'

data/examples/create_spreadsheet/README.md

@@ -0,0 +1,314 @@
+# Example: create-spreadsheet
+
+Ideally, with a command line parser class, you want a class that you can simply pass
+in ARGV to the parser and get the values parsed from the command line using getter
+methods.
+
+This example shows step-by-step how to write a class that implements parsing the
+command line for creating a Google Docs Spreadsheet.
+
+* [Step 1: Define requirements](#step-1-define-requirements)
+* [Step 2: Design the command line](#step-2-design-the-command-line)
+* [Step 3: Implement accessors and set default values for result attributes](#step-3-implement-accessors-and-set-default-values-for-result-attributes)
+* [Step 4: Write tests](#step-4-write-tests)
+* [Step 5: Define options](#step-5-define-options)
+* [Step 6: Define validations](#step-6-define-validations)
+* [Step 7: Parse remaining command line arguments](#step-7-parse-remaining-command-line-arguments)
+* [Step 8: Make the --help output look good](#step-8-make-the---help-output-look-good)
+
+## Step 1: Define requirements
+
+For this example, write a class that implements parsing the command line that meets
+the following requirements:
+
+* Optionally specify the **title** of the spreadsheet. If not specified, use the
+  default title assigned by Google for new spreadsheets (usually "Untitled
+  Spreadsheet")
+* Optionally specify a list of **sheets** to create and give an optional CSV data
+  file to preload into each sheet. If no sheets are specified, one blank sheet is
+  created by Google with the default title (usually "Sheet 1"). If a data file is not
+  specified for a given sheet, that sheet should be left blank.
+* Optionally specify a list of **permissions** to add to the spreadsheet. The user
+  must be able to specify the type of the permission (user, group, domain, or
+  anyone), the subject of the permission (depending on the type either an email
+  address, domain name or nothing), and the role being granted (organizer,
+  fileOrganizer, writer, commenter, or reader).
+* Optionally specify the Google Drive **folder** to create the spreadsheet in. If not
+  given, the spreadsheet will be created in the root drive directory of the user
+  whose credentials are being used to make the request.
+
+Once the command line is parsed, return this information in the following attributes:
+
+* **title**: the optional title of the spreadsheet
+* **sheets**: an array of sheets each having attributes **title** and **data** (read from the given CSV)
+* **permissions**: an array of permissions each having attributes **type**, **subject**, and **role**
+* **folder_id**: the id of the Google Drive folder in which to create the spreadsheet
+
+## Step 2: Design the command line
+
+Design the command line following the
+[Google developer documentation style guide for command line syntax](https://developers.google.com/style/code-syntax).
+
+Document what the `--help` option SHOULD output in the following sections:
+
+```text
+BANNER
+HEADER
+OPTIONS
+FOOTER
+```
+
+For this example, here is what the --help output should be:
+
+```text
+Create a new Google Spreadsheet
+
+Usage:
+
+create_spreadsheet [SPREADSHEET_TITLE] \
+  [--sheet=TITLE [--data=DATA_FILE]]... \
+  [--folder=FOLDER_ID] \
+  [--permission=PERMISSION_SPEC]...
+
+Options:
+        --sheet=TITLE                Title of a sheet to create
+        --data=DATA_FILE             Data file for the last sheet
+        --folder=FOLDER_ID           Create the spreadsheet in the given Google Drive folder
+        --permission=PERMISSION_SPEC Set permissions on the spreadsheet
+
+DATA_FILE := A file containing data in CSV format
+PERMISSION_SPEC := {user:EMAIL:ROLE | group:EMAIL:ROLE | domain:DOMAIN:ROLE | anyone:ROLE}
+ROLE := {organizer | fileOrganizer | writer | commenter | reader}
+```
+
+## Step 3: Implement accessors and set default values for result attributes
+
+In the requirements, there were 4 public attributes defined for this command line
+parser: title, sheets, permissions, and folder_id. Use the private `set_defaults`
+method to set the default values for each attribute.
+
+```ruby
+# Parse the command line for creating a Google Spreadsheet
+#
+# @example
+#   options = CreateSpreadsheetCLI.new.call(ARGV)
+#
+# @!attribute title [String, nil] the title to give the new spreadsheet or nil for the default
+# @!attribute sheets [Array<Sheet>] the sheets to create including title and data for each
+# @!attribute permissions [Array<Permission>] the permissions to add to the spreadsheet
+# @!attribute folder_id [String] the id of the Google Drive folder in which to create the spreadsheet
+#
+# @api public
+#
+class CreateSpreadsheetCli < CommandLineBoss
+  attr_reader :title, :sheets, :folder, :permissions
+
+  private
+
+  def set_defaults
+      @title = nil
+      @sheets = []
+      @permissions = []
+      @folder_id = nil
+  end
+end
+```
+
+In this case, it would be advantageous to create a few supporting classes and
+constants to return sheets and permissions. Add the following code to the
+CreateSpreadsheetCli class.
+
+```ruby
+# Sheets specified at the command line
+#
+# @!attribute title [String, nil] the title of the sheet to create or nil for the default title
+# @!attribute data [Array<Array<Object>>, nil] the data to write to the sheet or nil
+#
+# @api public
+Sheet = Struct.new(:title, :data)
+
+# Permissions specified at the command line
+#
+# @!attribute type [String] must be one of VALID_PERM_TYPES
+# @!attribute subject [String, nil] the name of the subject the permission is given to
+#
+#   * If the type is 'user' or 'group', must be a valid email address
+#   * If type is 'domain', must be a valid domain name
+#   * If type is anyone, must be nil
+#
+# @!attribute role [String] myst be one of VALID_PERM_ROLES
+Permission = Struct.new(:type, :subject, :role)
+
+VALID_PERM_TYPES = %w[user group domain anyone].freeze
+VALID_PERM_ROLES = %w[organizer fileOrganizer writer commenter reader].freeze
+```
+
+## Step 4: Write tests
+
+Write tests in your favorite testing framework that assert various permutations of
+command line arguments result either in:
+
+* The expected attrbiute values, or
+* The expected exception was raised
+
+Tests for this example can be found in spec/create_spreadsheet.feature`
+Tests for this interface might include:
+
+* Nothing is given on the command line
+* A spreadsheet title is given
+* A sheet is defined with a title
+* A sheet is defined with a title and data
+* Multiple sheets are defined both with data
+* Multiple sheets are defined only one with data
+* A user permission is given
+* A group permission is given
+* A domain permission is given
+* An anyone permission is given
+* Multiple permissions are given
+* A folder is given
+* A sheet given without a name
+* A permission is given without a permission spec
+* A invalid permission is given
+* The permission spec has an invalid type
+* A permission spec has an invalid role
+* A subject is given for an anyone permission
+* A subject is not given for a user permission
+* Data is given without a path
+* Data is given with an non-existant path
+* The folder option is given twice
+* A same sheet name is given twice
+* Data is given twice for the same sheet
+
+## Step 5: Define options
+
+Define private methods whose name is define_*_option.
+
+Methods MUST be private or they won't be called.
+
+Add any errors to the `error_messages` array.
+
+```ruby
+private
+
+def define_sheet_title_option
+  parser.on('--sheet-title=TITLE', 'Title of a sheet to create') do |title|
+    sheets << Sheet.new(title:, data: nil)
+  end
+end
+
+def define_sheet_data_option
+  parser.on('--sheet-data=DATA_FILE', 'Data file for the last sheet') do |data_file|
+    sheets << Sheet.new(title: nil, data: nil) if sheets.empty?
+    if sheets.last.data
+      error_messages << 'Only one --sheet-data option is allowed per --sheet-title'
+    else
+      sheets.last.data = CSV.read(data_file)
+    end
+  end
+end
+
+def define_folder_option
+  parser.on('--folder=FOLDER_ID', 'Create the spreadsheet to the given folder') do |folder_id|
+    if @folder_id
+      error_messages << 'Only one --folder option is allowed'
+    else
+      @folder_id = folder_id
+    end
+  end
+end
+
+PERMISSION_SPEC_REGEXP = /
+  ^
+  (?<type>[^:]+)
+  (?:
+    :(?<subject>[^:]+)
+  )?
+  :(?<role>[^:]+)
+  $
+/x
+
+def define_permission_option
+  parser.on('--permission=PERMISSION_SPEC', 'Set permissions on the spreadsheet') do |permission_spec|
+    match = permission_spec.match(PERMISSION_SPEC_REGEXP)
+    unless match
+      error_messages << "Invalid permission spec: #{permission_spec}"
+      next
+    end
+    permissions << Permission.new(
+      permission_spec:, type: match[:type], subject: match[:subject], role: match[:role]
+    )
+  end
+end
+```
+
+## Step 6: Define validations
+
+Define private methods whose name is validate_*.
+
+Methods MUST be private or they won't be called.
+
+Add any errors to the `error_messages` array.
+
+```ruby
+def validate_permission_types
+  permissions.each do |permission|
+    unless VALID_PERMISSION_TYPES.include?(permission.type)
+      error_messages << "Invalid permission type: #{permission.type}"
+    end
+  end
+end
+
+def validate_permission_roles
+  permissions.each do |permission|
+    unless VALID_PERMISSION_ROLES.include?(permission.role)
+      error_messages << "Invalid permission role: #{permission.role}"
+    end
+  end
+end
+
+def validate_permission_subjects
+  permissions.each do |permission|
+    if permission.type == 'anyone' && permission.subject
+      error_messages << "Permission subject for type 'anyone' should be blank in #{permission.permission_spec}"
+    end
+    if permission.type != 'anyone' && !permission.subject
+      error_messages << "Permission subject missing in #{permission.permission_spec}"
+    end
+  end
+end
+```
+
+## Step 7: Parse remaining command line arguments
+
+```ruby
+def parse_arguments
+  @spreadsheet_title = args.shift
+end
+```
+
+## Step 8: Make the --help output look good
+
+```ruby
+def banner = <<~TEXT
+  Create a new Google Spreadsheet
+TEXT
+
+# Usage text for the command line help
+# @api private
+def usage = <<~TEXT
+  Usage:
+
+  create_spreadsheet SPREADSHEET_TITLE \
+    [--sheet-title=TITLE [--sheet-data=DATA_FILE]]... \
+    [--folder=FOLDER_ID }] \
+    [--permission=PERMISSION_SPEC]...
+TEXT
+
+# Footer text for the command line help
+# @api private
+def footer = <<~TEXT
+  PERMISSION_SPEC := {user:EMAIL:ROLE | group:EMAIL:ROLE | domain:DOMAIN:ROLE | anyone:ROLE}
+  ROLE := {organizer | fileOrganizer | writer | commenter | reader}
+  DATA_FILE := A file containing data in CSV format
+TEXT
+```

data/examples/create_spreadsheet/Rakefile

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+task default: %i[spec rubocop build]
+
+require 'rake/clean'
+
+# RSpec
+
+require 'rake'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = './spec/**/*{_spec.rb,.feature}'
+end
+
+CLEAN << 'coverage'
+CLEAN << 'test'
+CLEAN << '.rspec_status'
+CLEAN << 'rspec-report.xml'
+
+# Bundler Gem Build
+
+require 'bundler'
+require 'bundler/gem_tasks'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  warn e.message
+  warn 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+
+CLEAN << 'pkg'
+CLOBBER << 'Gemfile.lock'
+
+# Rubocop
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new do |t|
+  t.options = %w[
+    --format fuubar
+    --format json --out rubocop-report.json
+    --display-cop-names
+    --config .rubocop.yml
+  ]
+end
+
+CLEAN << 'rubocop-report.json'

data/examples/create_spreadsheet/create_spreadsheet.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = 'create_spreadsheet'
+  spec.version = '1.0.0'
+  spec.authors = ['James Couball']
+  spec.email = ['jcouball@yahoo.com']
+
+  spec.summary = 'A command line utility to create a Google Spreadsheet'
+  spec.description = ''
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.homepage = 'https://github.com/main-branch/create_spreadsheet'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/main-branch/create_spreadsheet'
+  spec.metadata['changelog_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}/file/CHANGELOG.md"
+  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  gemspec = File.basename(__FILE__)
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      (f == gemspec) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/examples/create_spreadsheet/exe/create-spreadsheet

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'create_spreadsheet'
+require 'csv'
+require 'pp'
+
+options = CreateSpreadsheet::CommandLine.new.parse(ARGV)
+
+if options.failed?
+  warn "Parsing failed:\n#{options.error_messages.join("\n")}"
+  exit 1
+end
+
+# options =
+#   begin
+#     CreateSpreadsheet::CommandLine.new.parse(ARGV)
+#   rescue CommandLineBoss::Error => e
+#     warn "ERROR: #{e.parser.error_messages.join("\nERROR: ")}"
+#     exit 1
+#   end
+
+puts <<~OPTIONS
+  Creating spreadsheet with title: #{options.title.pretty_inspect}
+  Creating sheets: #{options.sheets.pretty_inspect}
+  In folder: #{options.folder_id.pretty_inspect}
+  Adding permissions: #{options.permissions.pretty_inspect}
+OPTIONS

data/examples/create_spreadsheet/lib/create_spreadsheet/command_line.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require 'command_line_boss'
+require 'csv'
+
+module CreateSpreadsheet
+  # Sheet`s specified at the command line
+  #
+  # @!attribute title [String, nil] the title of the sheet to create or nil for the default title
+  # @!attribute data [Array<Array<Object>>, nil] the data to write to the sheet or nil
+  #
+  # @api public
+  Sheet = Struct.new(:title, :data, keyword_init: true)
+
+  # Permissions specified at the command line
+  #
+  # @!attribute permission_spec [String] the unparsed permission spec as given at the command line
+  # @!attribute type [String] must be one of VALID_PERM_TYPES
+  # @!attribute subject [String, nil] the name of the subject the permission is given to
+  #
+  #   * If the type is 'user' or 'group', must be a valid email address
+  #   * If type is 'domain', must be a valid domain name
+  #   * If type is anyone, must be nil
+  #
+  # @!attribute role [String] myst be one of VALID_PERM_ROLES
+  Permission = Struct.new(:permission_spec, :type, :subject, :role, keyword_init: true)
+
+  # The list of valid permission types the user can give
+  # @return [Array<String>]
+  # @api private
+  VALID_PERM_TYPES = %w[user group domain anyone].freeze
+
+  # The list of valid permission roles the user can give
+  # @return [Array<String>]
+  # @api private
+  VALID_PERM_ROLES = %w[organizer fileOrganizer writer commenter reader].freeze
+
+  # The regular expression for parsing a permission spec
+  # @return [Regexp]
+  PERMISSION_SPEC_REGEXP = /
+  ^
+    (?<type>[^:]+)
+    (?:
+      :(?<subject>[^:]+)
+    )?
+    :(?<role>[^:]+)
+    $
+  /x
+
+  # A command line interface for creating spreadsheets
+  #
+  # @!attribute [r] title
+  #   @return [String, nil] The title of the spreadsheet to create or nil for the default title
+  #
+  # @!attribute [r] sheets
+  #   @return [Array<Sheet>] The sheets to create in the spreadsheet
+  #
+  # @!attribute [r] permissions
+  #   @return [Array<Permission>] The list of permissions to add to the spreadsheet
+  #
+  # @!attribute [r] folder_id
+  #   @return [String, nil] The ID of the folder to move the spreadsheet to
+  #
+  # @example Create a spreadsheet named "My Spreadsheet" with a default sheet named "Sheet1"
+  #   ARGV #=> ["My Spreadsheet"]
+  #   options = CommandLineParser.new.call(ARGV)
+  #   options.spreadsheet_title #=> "My Spreadsheet"
+  #
+  # @api pubic
+  #
+  class CommandLine < CommandLineBoss
+    attr_reader :title, :sheets, :permissions, :folder_id
+
+    private
+
+    # Set the attribute default values
+    # @return [void]
+    # @api private
+    def set_defaults
+      @title = nil
+      @sheets = []
+      @permissions = []
+      @folder_id = nil
+    end
+
+    # Remove the title from the remaining arguments
+    # @return [void]
+    # @api private
+    def parse_arguments
+      @title = @args.shift
+    end
+
+    # Define the --sheet option
+    # @return [void]
+    # @api private
+    def define_sheet_option
+      parser.on('--sheet=TITLE', 'Title of a sheet to create') do |title|
+        if sheets.any? { |sheet| sheet.title.downcase == title.downcase }
+          add_error_message("The sheet #{title} was given more than once")
+        end
+
+        sheets << Sheet.new(title:, data: nil)
+      end
+    end
+
+    # Read the csv data file
+    # @param data_file [String] the name of the data file
+    # @return [Array<Array<Object>>, nil] the data in the file or nil if the file is not found
+    # @api private
+    def read_data_file(data_file)
+      CSV.parse(File.read(data_file))
+    rescue Errno::ENOENT
+      add_error_message "Data file not found: #{data_file}"
+      nil
+    end
+
+    # Define the --data option
+    # @return [void]
+    # @api private
+    def define_data_option
+      parser.on('--data=DATA_FILE', 'Data file for the last named sheet') do |data_file|
+        sheets << Sheet.new(title: nil, data: nil) if sheets.empty?
+        if sheets.last.data
+          add_error_message 'Only one data file is allowed per sheet'
+        else
+          sheets.last.data = read_data_file(data_file)
+        end
+      end
+    end
+
+    # Define the --permission option
+    # @return [void]
+    # @api private
+    def define_permission_option
+      parser.on('--permission=PERMISSION_SPEC', 'Set permissions on the spreadsheet') do |permission_spec|
+        match = permission_spec.match(PERMISSION_SPEC_REGEXP)
+        unless match
+          add_error_message "Invalid permission: #{permission_spec}"
+          next
+        end
+        permissions << Permission.new(
+          permission_spec:, type: match[:type], subject: match[:subject], role: match[:role]
+        )
+      end
+    end
+
+    # Define the --folder option
+    # @return [void]
+    # @api private
+    def define_folder_option
+      parser.on('--folder=FOLDER_ID', 'Create the spreadsheet to the given folder') do |folder_id|
+        if @folder_id
+          add_error_message 'Only one --folder option is allowed'
+        else
+          @folder_id = folder_id
+        end
+      end
+    end
+
+    # Validate the permission role value
+    # @return [void]
+    # @api private
+    def validate_permission_role
+      permissions.each do |p|
+        add_error_message "Invalid permission role: #{p.role}" unless VALID_PERM_ROLES.include?(p.role)
+      end
+    end
+
+    # Validate that no permissions of type 'anyone' has a subject
+    # @return [void]
+    # @api private
+    def validate_permission_anyone_subject
+      permissions.each do |p|
+        add_error_message 'An anyone permission must not have a subject' if p.type == 'anyone' && p.subject
+      end
+    end
+
+    # Validate that all permissions that are not type 'anyone' have a subject
+    # @return [void]
+    # @api private
+    def validate_permission_other_subject
+      permissions.each do |p|
+        add_error_message "A #{p.type} permission must have a subject" if p.type != 'anyone' && !p.subject
+      end
+    end
+
+    # Validate that all permissions have a valid type
+    # @return [void]
+    # @api private
+    def validate_permission_type
+      permissions.each do |p|
+        add_error_message "Invalid permission type: #{p.type}" unless VALID_PERM_TYPES.include?(p.type)
+      end
+    end
+
+    include CommandLineBoss::HelpOption
+
+    # Banner shown at the top of the help message
+    # @return [String]
+    # @api private
+    def banner = <<~BANNER
+      Create a new Google Spreadsheet'
+
+      Usage:
+
+      create_spreadsheet [SPREADSHEET_TITLE] \\
+        [--sheet=TITLE [--data=DATA_FILE]]... \\
+        [--folder=FOLDER_ID] \\
+        [--permission=PERMISSION_SPEC]...
+    BANNER
+
+    # Footer shown at the bottom of the help message
+    # @return [String]
+    # @api private
+    def footer = <<~FOOTER
+      DATA_FILE := A file containing data in CSV format
+      PERMISSION_SPEC := {user:EMAIL:ROLE | group:EMAIL:ROLE | domain:DOMAIN:ROLE | anyone:ROLE}
+      ROLE := {organizer | fileOrganizer | writer | commenter | reader}
+    FOOTER
+  end
+end

data/examples/create_spreadsheet/lib/create_spreadsheet.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'command_line_boss'
+
+# CreateSpreadsheet is a command line parser for creating spreadsheets
+module CreateSpreadsheet; end
+
+require 'create_spreadsheet/command_line'