csv_plus_plus 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abee03db0f21f9d8c5d3cfb4ec81dbd748568f878458f355cab6db5fc458a509
-  data.tar.gz: 6c4e95fa1c780a2d009eaeb58fd48b28c2dd96826b22be02f84d5fc8a06ad31e
+  metadata.gz: a4462a2a82490271a95479970e10246ed7d8b1e8a62d21928a5f2b710b2bd511
+  data.tar.gz: 31ce301945c5cc4d3154395dfa62271637baba4af78d2efed9b13d779036e015
 SHA512:
-  metadata.gz: 59f2cb756bdfd20f95f252aa1c07fb4b994def21f07d8bc4e5a976b22f0b439fb950e1723fdb34753baf23527e5950d244f1386e9231c6318b35de3974305ba4
-  data.tar.gz: 38b6d6d960aa17978adf2ee1724333754e7cdc86b8e41fa58522357448db8448d5441fb5961d3758af94d617b94b21b197b5e4d2d4eb2dba0cbc39da586c4413
+  metadata.gz: a968bc15a47a6ac129b0a4a13df3dfb1997991548f13af9ac28598091b5562be8d7d1943a03f86a1a501533ff2eb974d1e2cc788f43fca27f09be455edcdba9f
+  data.tar.gz: f091403bede1fb2e751fad9b6937a836f0676e5ab284690fa2c8983fa746d90e9780c701d3a7ca1161fa9aca04b84263a1b7e7789dda866d6fe1caf975593287

data/README.md

@@ -1,3 +1,4 @@
+![main](https://github.com/patrickomatic/csv-plus-plus/actions/workflows/rspec.yml/badge.svg)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-community-brightgreen.svg)](https://rubystyle.guide)
 [![Gem Version](https://badge.fury.io/rb/csv_plus_plus.svg)](https://badge.fury.io/rb/csv_plus_plus)
 
@@ -19,8 +20,8 @@ quantity := celladjacent(D)
 def profit() (price * quantity) - fees
 
 ---
-![[format=bold/align=center]]Date,Ticker,Price,Quantity,Total,Fees
-![[expand]],[[format=bold]],,,"=profit()",$$fees
+![[format=bold/align=center]]Date   ,Ticker             ,Price  ,Quantity   ,Profit       ,Fees
+![[expand]]                         ,[[format=italic]]  ,       ,           ,"=profit()"  ,=fees
 ```
 
 And can be compiled into a `.xlsx` file by:
@@ -45,7 +46,7 @@ or if you want the very latest changes, clone this repository and run:
 
 ## Examples
 
-Take a look at the [examples](./examples/) directory for a bunch of example `.csvpp` files.
+Take a look at the [repository of examples](https://github.com/patrickomatic/csvpp-examples) repository for a bunch of example `.csvpp` files.
 
 ## CLI Arguments
 
@@ -62,3 +63,7 @@ Usage: csv++ [options]
     -x, --offset-columns OFFSET      Apply the template offset by OFFSET cells
     -y, --offset-rows OFFSET         Apply the template offset by OFFSET rows
 ```
+
+## See Also:
+
+* [Supported features by output format](./docs/feature_matrix.csvpp)

data/docs/CHANGELOG.md

@@ -1,3 +1,19 @@
+## main/upcoming
+
+## v0.2.0
+
+### **Breaking Changes**
+
+- Removal of the $$ operator - to dereference variables you can just reference them by name and they will be resolved if they are defined.  Otherwise they will be left alone in the output
+
+### Non-breaking Changes
+
+- Excel: fix the merging of existing values 
+- CSV: fix the merging of existing values 
+- Support merging in values from CSV (previously it would ignore/overwrite them)
+- Allow for more generous spacing in the csv section (and reflect this in the examples)
+- More type coverage
+
 ## v0.1.3
 
 - Proper scoping of variables defined within an expand modifier

data/lib/csv_plus_plus/a1_reference.rb

@@ -0,0 +1,202 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  # A reference to a cell. Internally it is represented by a simple +cell_index+ and +row_index+ but there are
+  # functions for converting to and from A1-style formats.  Supported formats are:
+  #
+  # * `1` - A reference to the entire first row
+  # * `A` - A reference to the entire first column
+  # * `A1` - A reference to the first cell (top left)
+  # * `A1:D10` - The range defined between A1 and D10
+  # * `Sheet1!B2` - Cell B2 on the sheet "Sheet1"
+  #
+  # @attr sheet_name [String, nil] The name of the sheet reference
+  # @attr_reader cell_index [Integer, nil] The cell index of the cell being referenced
+  # @attr_reader row_index [Integer, nil] The row index of the cell being referenced
+  # @attr_reader upper_cell_index [Integer, nil] If set, the cell reference is a range and this is the upper cell
+  #   index of it
+  # @attr_reader upper_row_index [Integer, nil] If set, the cell reference is a range and this is the upper row index
+  #   of in
+  # rubocop:disable Metrics/ClassLength
+  class A1Reference
+    extend ::T::Sig
+
+    sig { returns(::T.nilable(::String)) }
+    attr_accessor :sheet_name
+
+    sig { returns(::T.nilable(::Integer)) }
+    attr_reader :cell_index
+
+    sig { returns(::T.nilable(::Integer)) }
+    attr_reader :row_index
+
+    sig { returns(::T.nilable(::Integer)) }
+    attr_reader :upper_cell_index
+
+    sig { returns(::T.nilable(::Integer)) }
+    attr_reader :upper_row_index
+
+    sig { returns(::T.nilable(::CSVPlusPlus::Modifier::Expand)) }
+    attr_reader :scoped_to_expand
+
+    # TODO: this is getting gross, maybe define an actual parser
+    A1_NOTATION_REGEXP = /
+      ^
+        (?:
+          (?:
+            (?:'([^'\\]|\\.)*') # allow for a single-quoted sheet name
+            |
+            (\w+)               # or if it's not quoted, just allow \w+
+          )
+          !                     # if a sheet name is specified, it's always followed by a !
+        )?
+        ([a-zA-Z0-9]+)          # the only part required - something alphanumeric
+        (?: :([a-zA-Z0-9]+))?   # and they might make it a range
+      $
+    /x
+    public_constant :A1_NOTATION_REGEXP
+
+    ALPHA = ::T.let(('A'..'Z').to_a.freeze, ::T::Array[::String])
+    private_constant :ALPHA
+
+    sig { params(cell_reference_string: ::String).returns(::T::Boolean) }
+    # Does the given +cell_reference_string+ conform to a valid cell reference?
+    #
+    # {https://developers.google.com/sheets/api/guides/concepts}
+    #
+    # @param cell_reference_string [::String] The string to check if it is a valid cell reference (we assume it's in
+    #   A1 notation but maybe can support R1C1)
+    #
+    # @return [::T::Boolean]
+    def self.valid_cell_reference?(cell_reference_string)
+      !(cell_reference_string =~ ::CSVPlusPlus::A1Reference::A1_NOTATION_REGEXP).nil?
+    end
+
+    sig do
+      params(
+        ref: ::T.nilable(::String),
+        cell_index: ::T.nilable(::Integer),
+        row_index: ::T.nilable(::Integer),
+        scoped_to_expand: ::T.nilable(::CSVPlusPlus::Modifier::Expand)
+      ).void
+    end
+    # Either +ref+, +cell_index+ or +row_index+ must be specified.  If +ref+ is supplied it will be parsed to calculate
+    # +row_index+ and +cell_index.
+    #
+    # @param ref [String, nil] A raw user-inputted reference
+    # @param cell_index [Integer, nil] The index of the cell being referenced.
+    # @param row_index [Integer, nil] The index of the row being referenced.
+    # @param scoped_to_expand [Expand] The [[expand]] that this cell reference will be scoped to. In other words, it
+    #   will only be able to be resolved if the position is within the bounds of the expand (it can't be referenced
+    #   outside of the expand.)
+    def initialize(ref: nil, cell_index: nil, row_index: nil, scoped_to_expand: nil)
+      raise(::ArgumentError, 'Must specify :cell_index or :row_index') unless ref || cell_index || row_index
+
+      @scoped_to_expand = scoped_to_expand
+
+      if ref
+        from_a1_ref!(ref)
+      else
+        @cell_index = ::T.let(cell_index, ::T.nilable(::Integer))
+        @row_index = ::T.let(row_index, ::T.nilable(::Integer))
+
+        @upper_cell_index = ::T.let(nil, ::T.nilable(::Integer))
+        @upper_row_index = ::T.let(nil, ::T.nilable(::Integer))
+      end
+    end
+
+    sig { override.params(other: ::BasicObject).returns(::T::Boolean) }
+    # @param other [BasicObject]
+    #
+    # @return [boolean]
+    def ==(other)
+      case other
+      when self.class
+        @cell_index == other.cell_index && @row_index == other.row_index && @sheet_name == other.sheet_name \
+          && @upper_cell_index == other.upper_cell_index && @upper_row_index == other.upper_row_index
+      else
+        false
+      end
+    end
+
+    sig { params(position: ::CSVPlusPlus::Runtime::Position).returns(::T.nilable(::String)) }
+    # Turns index-based/X,Y coordinates into a A1 format
+    #
+    # @param position [Position]
+    #
+    # @return [::String, nil]
+    def to_a1_ref(position)
+      row_index = position_row_index(position)
+      return unless row_index || @cell_index
+
+      rowref = row_index ? (row_index + 1).to_s : ''
+      cellref = @cell_index ? to_a1_cell_ref : ''
+      [cellref, rowref].join
+    end
+
+    private
+
+    sig { params(position: ::CSVPlusPlus::Runtime::Position).returns(::T.nilable(::Integer)) }
+    def position_row_index(position)
+      @scoped_to_expand ? position.row_index : @row_index
+    end
+
+    sig { returns(::String) }
+    # Turns a cell index into an A1 reference (just the "A" part - for example 0 == 'A', 1 == 'B', 2 == 'C', etc.)
+    #
+    # @return [::String]
+    def to_a1_cell_ref
+      c = @cell_index.dup
+      ref = ''
+
+      while c >= 0
+        # rubocop:disable Lint/ConstantResolution
+        ref += ::T.must(ALPHA[c % 26])
+        # rubocop:enable Lint/ConstantResolution
+        c = (c / 26).floor - 1
+      end
+
+      ref.reverse
+    end
+
+    sig { params(ref: ::String).void }
+    def from_a1_ref!(ref)
+      quoted_sheet_name, unquoted_sheet_name, lower_range, upper_range = ::T.must(
+        ref.strip.match(
+          ::CSVPlusPlus::A1Reference::A1_NOTATION_REGEXP
+        )
+      ).captures
+
+      @sheet_name = quoted_sheet_name || unquoted_sheet_name
+
+      parse_lower_range!(lower_range) if lower_range
+      parse_upper_range!(upper_range) if upper_range
+    end
+
+    sig { params(lower_range: ::String).void }
+    def parse_lower_range!(lower_range)
+      cell_ref, row_ref = ::T.must(lower_range.match(/^([a-zA-Z]+)?(\d+)?$/)).captures
+      @cell_index = from_a1_cell_ref!(cell_ref) if cell_ref
+      @row_index = Integer(row_ref, 10) - 1 if row_ref
+    end
+
+    sig { params(upper_range: ::String).void }
+    # TODO: make this less redundant with the above function
+    def parse_upper_range!(upper_range)
+      cell_ref, row_ref = ::T.must(upper_range.match(/^([a-zA-Z]+)?(\d+)?$/)).captures
+      @upper_cell_index = from_a1_cell_ref!(cell_ref) if cell_ref
+      @upper_row_index = Integer(row_ref, 10) - 1 if row_ref
+    end
+
+    sig { params(cell_ref: ::String).returns(::Integer) }
+    def from_a1_cell_ref!(cell_ref)
+      (cell_ref.upcase.chars.reduce(0) do |cell_index, letter|
+        # rubocop:disable Lint/ConstantResolution
+        (cell_index * 26) + ::T.must(ALPHA.find_index(letter)) + 1
+        # rubocop:enable Lint/ConstantResolution
+      end) - 1
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/csv_plus_plus/benchmarked_compiler.rb

@@ -18,7 +18,7 @@ module CSVPlusPlus
 
     sig do
       params(
-        options: ::CSVPlusPlus::Options,
+        options: ::CSVPlusPlus::Options::Options,
         runtime: ::CSVPlusPlus::Runtime::Runtime,
         block: ::T.proc.params(compiler: ::CSVPlusPlus::Compiler).void
       ).void
@@ -40,7 +40,7 @@ module CSVPlusPlus
     sig do
       params(
         benchmark: ::Benchmark::Report,
-        options: ::CSVPlusPlus::Options,
+        options: ::CSVPlusPlus::Options::Options,
         runtime: ::CSVPlusPlus::Runtime::Runtime
       ).void
     end
@@ -52,7 +52,7 @@ module CSVPlusPlus
       @timings = ::T.let([], ::T::Array[::Benchmark::Tms])
     end
 
-    sig { override.params(block: ::T.proc.params(runtime: ::CSVPlusPlus::Runtime::Runtime).void).void }
+    sig { params(block: ::T.proc.params(position: ::CSVPlusPlus::Runtime::Position).void).void }
     # Time the Compiler#outputting! stage
     # rubocop:disable Naming/BlockForwarding
     def outputting!(&block)

data/lib/csv_plus_plus/cell.rb

@@ -4,7 +4,7 @@
 module CSVPlusPlus
   # A cell of a template
   #
-  # @attr ast [Entity]
+  # @attr ast [Entity, nil] The AST of the formula in the cell (if there is one)
   # @attr row_index [Integer] The cell's row index (starts at 0)
   # @attr_reader index [Integer] The cell's index (starts at 0)
   # @attr_reader modifier [Modifier] The modifier for this cell
@@ -23,26 +23,6 @@ module CSVPlusPlus
     sig { returns(::CSVPlusPlus::Modifier::Modifier) }
     attr_reader :modifier
 
-    sig do
-      params(
-        value: ::T.nilable(::String),
-        runtime: ::CSVPlusPlus::Runtime::Runtime,
-        modifier: ::CSVPlusPlus::Modifier::Modifier
-      ).returns(::CSVPlusPlus::Cell)
-    end
-    # Parse a +value+ into a Cell object.
-    #
-    # @param value [String] A string value which should already have been processed through a CSV parser
-    # @param runtime [Runtime]
-    # @param modifier [Modifier]
-    #
-    # @return [Cell]
-    def self.parse(value, runtime:, modifier:)
-      new(value:, row_index: runtime.row_index, index: runtime.cell_index, modifier:).tap do |c|
-        c.ast = ::T.unsafe(::CSVPlusPlus::Parser::CellValue.new).parse(value, runtime)
-      end
-    end
-
     sig do
       params(
         index: ::Integer,
@@ -66,24 +46,10 @@ module CSVPlusPlus
     # The +@value+ (cleaned up some)
     #
     # @return [::String]
-    # TODO: is this used?
     def value
       stripped = @value&.strip
 
       stripped&.empty? ? nil : stripped
     end
-
-    sig { params(runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::T.nilable(::String)) }
-    # A compiled final representation of the cell.  This can only happen after all cell have had variables and functions
-    # resolved.
-    #
-    # @param runtime [Runtime]
-    #
-    # @return [::String]
-    def evaluate(runtime)
-      return value unless @ast
-
-      "=#{@ast.evaluate(runtime)}"
-    end
   end
 end

data/lib/csv_plus_plus/cli.rb

@@ -2,111 +2,46 @@
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  # Handle running the application with the given CLI flags
+  # Handle running the application with the supported +CLIFlag+s
   #
-  # @attr options [Options, nil] The parsed CLI options
+  # @attr options [Options] The parsed CLI options
   class CLI
     extend ::T::Sig
 
-    sig { returns(::CSVPlusPlus::Options) }
+    sig { returns(::CSVPlusPlus::Options::Options) }
     attr_accessor :options
 
+    sig { returns(::CSVPlusPlus::SourceCode) }
+    attr_accessor :source_code
+
     sig { void }
     # Handle CLI flags and launch the compiler
     #
     # @return [CLI]
     def self.launch_compiler!
-      cli = new
-      cli.main
+      new.main
     rescue ::StandardError => e
-      ::T.must(cli).handle_error(e)
+      warn(e.message)
       exit(1)
     end
 
     sig { void }
     # Initialize and parse the CLI flags provided to the program
     def initialize
-      @options = ::T.let(::CSVPlusPlus::Options.new, ::CSVPlusPlus::Options)
-      parse_options!
+      opts = parse_options
+
+      @source_code = ::T.let(::CSVPlusPlus::SourceCode.new(source_code_filename), ::CSVPlusPlus::SourceCode)
+      @options = ::T.let(apply_options(opts), ::CSVPlusPlus::Options::Options)
     end
 
     sig { void }
     # Compile the given template using the given CLI flags
     def main
-      ::CSVPlusPlus.apply_template_to_sheet!(::ARGF.read, ::ARGF.filename, @options)
-    end
-
-    sig { params(error: ::StandardError).void }
-    # Nicely handle a given error.  How it's handled depends on if it's our error and if @options.verbose
-    #
-    # @param error [CSVPlusPlus::Error, Google::Apis::ClientError, StandardError]
-    def handle_error(error)
-      # make sure that we're on a newline (verbose mode might be in the middle of printing a benchmark)
-      puts("\n\n") if @options.verbose
-
-      case error
-      when ::CSVPlusPlus::Error::Error
-        handle_internal_error(error)
-      when ::Google::Apis::ClientError
-        handle_google_error(error)
-      else
-        unhandled_error(error)
-      end
+      ::CSVPlusPlus.cli_compile(source_code, options)
     end
 
     private
 
-    sig { void }
-    # Handle the supplied command line options, setting +@options+ or throw an error if anything is invalid
-    def parse_options!
-      option_parser.parse!
-      validate_options
-    rescue ::OptionParser::InvalidOption => e
-      raise(::CSVPlusPlus::Error::Error, e.message)
-    end
-
-    sig { params(error: ::StandardError).void }
-    # An error was thrown that we weren't planning on
-    def unhandled_error(error)
-      warn(
-        <<~ERROR_MESSAGE)
-          An unexpected error was encountered.  Please try running again with --verbose and
-          reporting the error at: https://github.com/patrickomatic/csv-plus-plus/issues/new'
-        ERROR_MESSAGE
-
-      return unless @options.verbose
-
-      warn(error.full_message)
-      warn("Cause: #{error.cause}") if error.cause
-    end
-
-    sig { params(error: ::CSVPlusPlus::Error::Error).void }
-    def handle_internal_error(error)
-      case error
-      when ::CSVPlusPlus::Error::SyntaxError
-        warn(@options.verbose ? error.to_verbose_trace : error.to_trace)
-      else
-        warn(error.message)
-      end
-    end
-
-    sig { params(error: ::Google::Apis::ClientError).void }
-    def handle_google_error(error)
-      warn("Error making Google Sheets API request: #{error.message}")
-      return unless @options.verbose
-
-      warn("#{error.status_code} Error making Google API request [#{error.message}]: #{error.body}")
-    end
-
-    sig { void }
-    def validate_options
-      error_message = @options.validate
-      return if error_message.nil?
-
-      puts(option_parser)
-      raise(::CSVPlusPlus::Error::Error, error_message)
-    end
-
     sig { returns(::OptionParser) }
     def option_parser
       ::OptionParser.new do |parser|
@@ -115,10 +50,38 @@ module CSVPlusPlus
           exit
         end
 
-        ::SUPPORTED_CSVPP_FLAGS.each do |f|
-          parser.on(f.short_flag, f.long_flag, f.description) { |v| f.handler.call(@options, v) }
+        ::CSVPlusPlus::SUPPORTED_CSVPP_FLAGS.each do |f|
+          parser.on(f.short_flag, f.long_flag, f.description)
+        end
+      end
+    end
+
+    sig { params(opts: ::T::Hash[::Symbol, ::String]).returns(::CSVPlusPlus::Options::Options) }
+    def apply_options(opts)
+      ::CSVPlusPlus::Options.from_cli_flags(opts, source_code.filename).tap do |options|
+        opts.each do |key, value|
+          ::T.must(::CSVPlusPlus::FLAG_HANDLERS[key]).call(options, value) if ::CSVPlusPlus::FLAG_HANDLERS.key?(key)
         end
       end
     end
+
+    sig { returns(::T::Hash[::Symbol, ::String]) }
+    def parse_options
+      {}.tap do |opts|
+        option_parser.parse!(into: opts)
+      end
+    rescue ::OptionParser::InvalidOption => e
+      puts(option_parser)
+      raise(::CSVPlusPlus::Error::CLIError, e.message)
+    end
+
+    sig { returns(::String) }
+    # NOTE: this must be called after #parse_options, since #parse_options modifiers +ARGV+
+    def source_code_filename
+      ::ARGV.pop || raise(
+        ::CSVPlusPlus::Error::CLIError,
+        'You must specify a source (.csvpp) file to compile as the last argument'
+      )
+    end
   end
 end

data/lib/csv_plus_plus/cli_flag.rb

@@ -1,4 +1,4 @@
-# typed: true
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
@@ -8,83 +8,84 @@ module CSVPlusPlus
   # @attr_reader long_flag [String] A definition of the long/word-based flag
   # @attr_reader description [String] A description of what the flag does
   # @attr_reader handler [Proc(Options, String)] A proc which is called to handle when this flag is seen
-  class CliFlag
-    attr_reader :short_flag, :long_flag, :description, :handler
+  class CLIFlag
+    extend ::T::Sig
 
+    sig { returns(::String) }
+    attr_reader :description
+
+    sig { returns(::String) }
+    attr_reader :long_flag
+
+    sig { returns(::String) }
+    attr_reader :short_flag
+
+    sig { params(short_flag: ::String, long_flag: ::String, description: ::String).void }
     # @param short_flag [String] A definition of the short/single-character flag
     # @param long_flag [String] A definition of the long/word-based flag
     # @param description [String] A description of what the flag does
-    # @param handler [Proc(Options, String)] A proc which is called to handle when this flag is seen
-    def initialize(short_flag, long_flag, description, handler)
+    def initialize(short_flag, long_flag, description)
       @short_flag = short_flag
       @long_flag = long_flag
       @description = description
-      @handler = handler
-    end
-
-    # @return [String]
-    def to_s
-      "#{@short_flag}, #{@long_flag}  #{@description}"
     end
   end
-end
 
-SUPPORTED_CSVPP_FLAGS = [
-  ::CSVPlusPlus::CliFlag.new(
-    '-b',
-    '--backup',
-    'Create a backup of the spreadsheet before applying changes.',
-    ->(options, _v) { options.backup = true }
-  ),
-  ::CSVPlusPlus::CliFlag.new(
-    '-c',
-    '--create',
-    "Create the sheet if it doesn't exist.  It will use --sheet-name if specified",
-    ->(options, _v) { options.create_if_not_exists = true }
-  ),
-  ::CSVPlusPlus::CliFlag.new(
-    '-g SHEET_ID',
-    '--google-sheet-id SHEET_ID',
-    'The id of the sheet - you can extract this from the URL: ' \
-    'https://docs.google.com/spreadsheets/d/< ... SHEET_ID ... >/edit#gid=0',
-    ->(options, v) { options.google_sheet_id = v }
-  ),
-  ::CSVPlusPlus::CliFlag.new(
-    '-k',
-    '--key-values KEY_VALUES',
-    'A comma-separated list of key=values which will be made available to the template',
-    lambda do |options, v|
-      options.key_values =
-        begin
-          [v.split('=')].to_h
-        rescue ::StandardError
-          {}
-        end
-    end
-  ),
-  ::CSVPlusPlus::CliFlag.new(
-    '-n SHEET_NAME',
-    '--sheet-name SHEET_NAME',
-    'The name of the sheet to apply the template to',
-    ->(options, v) { options.sheet_name = v }
-  ),
-  ::CSVPlusPlus::CliFlag.new(
-    '-o OUTPUT_FILE',
-    '--output OUTPUT_FILE',
-    'The file to write to (must be .csv, .ods, .xls)',
-    ->(options, v) { options.output_filename = v }
-  ),
-  ::CSVPlusPlus::CliFlag.new('-v', '--verbose', 'Enable verbose output', ->(options, _v) { options.verbose = true }),
-  ::CSVPlusPlus::CliFlag.new(
-    '-x OFFSET',
-    '--offset-columns OFFSET',
-    'Apply the template offset by OFFSET cells',
-    ->(options, v) { options.offset[0] = v }
-  ),
-  ::CSVPlusPlus::CliFlag.new(
-    '-y OFFSET',
-    '--offset-rows OFFSET',
-    'Apply the template offset by OFFSET rows',
-    ->(options, v) { options.offset[1] = v }
+  FLAG_HANDLERS = ::T.let(
+    {
+      backup: ->(options, _v) { options.backup = true },
+      create: ->(options, _v) { options.create_if_not_exists = true },
+      'key-values': lambda { |options, v|
+                      options.key_values =
+                        begin
+                          [v.split('=')].to_h
+                        rescue ::StandardError
+                          {}
+                        end
+                    },
+      'offset-columns': ->(options, v) { options.offset[0] = v },
+      'offset-rows': ->(options, v) { options.offset[1] = v },
+      output: ->(options, v) { options.output_filename = ::Pathname.new(v) },
+      verbose: ->(options, _v) { options.verbose = true }
+    },
+    ::T::Hash[::Symbol, ::T.proc.params(options: ::CSVPlusPlus::Options::Options, v: ::String).void]
   )
-].freeze
+  public_constant :FLAG_HANDLERS
+
+  SUPPORTED_CSVPP_FLAGS = ::T.let(
+    [
+      ::CSVPlusPlus::CLIFlag.new('-b', '--backup', 'Create a backup of the spreadsheet before applying changes.'),
+      ::CSVPlusPlus::CLIFlag.new(
+        '-c',
+        '--create',
+        "Create the sheet if it doesn't exist.  It will use --sheet-name if specified"
+      ),
+      ::CSVPlusPlus::CLIFlag.new(
+        '-g SHEET_ID',
+        '--google-sheet-id SHEET_ID',
+        'The id of the sheet - you can extract this from the URL: ' \
+        'https://docs.google.com/spreadsheets/d/< ... SHEET_ID ... >/edit#gid=0'
+      ),
+      ::CSVPlusPlus::CLIFlag.new(
+        '-k',
+        '--key-values KEY_VALUES',
+        'A comma-separated list of key=values which will be made available to the template'
+      ),
+      ::CSVPlusPlus::CLIFlag.new(
+        '-n SHEET_NAME',
+        '--sheet-name SHEET_NAME',
+        'The name of the sheet to apply the template to'
+      ),
+      ::CSVPlusPlus::CLIFlag.new(
+        '-o OUTPUT_FILE',
+        '--output OUTPUT_FILE',
+        'The file to write to (must be .csv, .ods, .xls)'
+      ),
+      ::CSVPlusPlus::CLIFlag.new('-v', '--verbose', 'Enable verbose output'),
+      ::CSVPlusPlus::CLIFlag.new('-x OFFSET', '--offset-columns OFFSET', 'Apply the template offset by OFFSET cells'),
+      ::CSVPlusPlus::CLIFlag.new('-y OFFSET', '--offset-rows OFFSET', 'Apply the template offset by OFFSET rows')
+    ].freeze,
+    ::T::Array[::CSVPlusPlus::CLIFlag]
+  )
+  public_constant :SUPPORTED_CSVPP_FLAGS
+end