csv_plus_plus 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0fb79a1f7a00d60f77289518fb9c6ccac6b059024d5cf66a3f083ec92e77def
-  data.tar.gz: a35796b982b01171636e27b1d1a9d19d6d414249b0e4634947d5a754cb240146
+  metadata.gz: a4462a2a82490271a95479970e10246ed7d8b1e8a62d21928a5f2b710b2bd511
+  data.tar.gz: 31ce301945c5cc4d3154395dfa62271637baba4af78d2efed9b13d779036e015
 SHA512:
-  metadata.gz: 45dd804f7889d65ac5f5c63ccc131d774e7ea24097bfe9449af63a48345ca0b9f16ea9e84c17a73151c9ee8d9d90ce4b01d67b7ced817e831e66781d2e7141e0
-  data.tar.gz: 21cda263af6d05d5ee396a9d00b4c1c78f1a043d91787dcf0d822e1adb6a97a2326da836cdc3bbc3c78e43e5c342c1bdb9da966884f1d9d8df364e574f334ded
+  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:
@@ -29,7 +30,6 @@ And can be compiled into a `.xlsx` file by:
 $ csv++ -n 'My Stock Tracker' -o mystocks.xlsx mystocks.csvpp
 ```
 
-
 See the [Language Reference](./docs/LANGUAGE_REFERENCE.md) for a full explanation of features.
 
 ## Installing
@@ -38,7 +38,7 @@ Just install it via rubygems (homebrew and debian packages are in the works):
 
 `$ gem install csv_plus_plus`
 
-or if you want the very latest changes, clone the repository and run:
+or if you want the very latest changes, clone this repository and run:
 
 `$ rake gem:install`
 
@@ -46,7 +46,7 @@ or if you want the very latest changes, clone the 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
 
@@ -63,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/{CHANGELOG.md → docs/CHANGELOG.md}

@@ -1,3 +1,28 @@
+## 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
+- Types via Sorbet
+- Fix formula insertion on Excel
+- Fix modifier string quoting
+- Fix broken Yard doc generation
+- Fix: multiple modifiers on the same row weren't being handled 
+
 ## v0.1.2
 
 - var=... modifier which allows binding a variable to a cell

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

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
@@ -5,57 +6,106 @@ module CSVPlusPlus
   #
   # @attr_reader timings [Array<Benchmark::Tms>] +Benchmark+ timings that have been accumulated by each step of
   #   compilation
-  # @attr_reader benchmark [Benchmark] A +Benchmark+ instance
-  module BenchmarkedCompiler
-    attr_reader :benchmark, :timings
+  # @attr_reader benchmark [Benchmark::Report] A +Benchmark+ instance
+  class BenchmarkedCompiler < ::CSVPlusPlus::Compiler
+    extend ::T::Sig
 
-    # Wrap a +Compiler+ with our instance methods that add benchmarks
-    def self.with_benchmarks(compiler, &block)
-      ::Benchmark.benchmark(::Benchmark::CAPTION, 25, ::Benchmark::FORMAT, '> Total') do |x|
-        # compiler = new(options:, runtime:, benchmark: x)
-        compiler.extend(self)
-        compiler.benchmark = x
+    sig { returns(::Benchmark::Report) }
+    attr_reader :benchmark
 
-        block.call(compiler)
+    sig { returns(::T::Array[::Benchmark::Tms]) }
+    attr_reader :timings
 
+    sig do
+      params(
+        options: ::CSVPlusPlus::Options::Options,
+        runtime: ::CSVPlusPlus::Runtime::Runtime,
+        block: ::T.proc.params(compiler: ::CSVPlusPlus::Compiler).void
+      ).void
+    end
+    # Instantiate a +::Compiler+ that can benchmark (time) it's stages. For better or worse, the only way that they
+    # Benchmark library exposes it's +::Benchmark::Report+ is via a block, so this code also has to wrap with one
+    #
+    # @param options [Options]
+    # @param runtime [Runtime]
+    def self.with_benchmarks(options:, runtime:, &block)
+      ::Benchmark.benchmark(::Benchmark::CAPTION, 25, ::Benchmark::FORMAT, '> Total') do |x|
+        # compiler.extend(self)
+        compiler = new(benchmark: x, options:, runtime:)
+        block.call(compiler)
         [compiler.timings.reduce(:+)]
       end
     end
 
-    # @param benchmark [Benchmark] A +Benchmark+ instance
-    def benchmark=(benchmark)
-      @benchmark = benchmark
-      @timings = []
+    sig do
+      params(
+        benchmark: ::Benchmark::Report,
+        options: ::CSVPlusPlus::Options::Options,
+        runtime: ::CSVPlusPlus::Runtime::Runtime
+      ).void
     end
+    # @param benchmark [::Benchmark::Report]
+    def initialize(benchmark:, options:, runtime:)
+      super(options:, runtime:)
 
+      @benchmark = ::T.let(benchmark, ::Benchmark::Report)
+      @timings = ::T.let([], ::T::Array[::Benchmark::Tms])
+    end
+
+    sig { params(block: ::T.proc.params(position: ::CSVPlusPlus::Runtime::Position).void).void }
     # Time the Compiler#outputting! stage
-    def outputting!
-      time_stage('Writing the spreadsheet') { super }
+    # rubocop:disable Naming/BlockForwarding
+    def outputting!(&block)
+      time_stage('Writing the spreadsheet') { super(&block) }
     end
+    # rubocop:enable Naming/BlockForwarding
 
     protected
 
+    sig { override.void }
     def parse_code_section!
       time_stage('Parsing code section') { super }
     end
 
+    sig { override.returns(::T::Array[::CSVPlusPlus::Row]) }
     def parse_csv_section!
       time_stage('Parsing CSV section') { super }
     end
 
-    def expanding
-      time_stage('Expanding rows') { super }
+    sig { override.params(block: ::T.proc.void).void }
+    # rubocop:disable Naming/BlockForwarding
+    def expanding!(&block)
+      time_stage('Expanding rows') { super(&block) }
+    end
+    # rubocop:enable Naming/BlockForwarding
+
+    sig { override.params(block: ::T.proc.void).void }
+    # rubocop:disable Naming/BlockForwarding
+    def bind_all_vars!(&block)
+      time_stage('Binding [[var=]]') { super(&block) }
     end
+    # rubocop:enable Naming/BlockForwarding
 
+    sig do
+      override
+        .params(template: ::CSVPlusPlus::Template)
+        .returns(::T::Array[::T::Array[::CSVPlusPlus::Entities::Entity]])
+    end
     def resolve_all_cells!(template)
       time_stage('Resolving each cell') { super(template) }
     end
 
     private
 
+    sig do
+      type_parameters(:R).params(
+        stage: ::String,
+        block: ::T.proc.returns(::T.type_parameter(:R))
+      ).returns(::T.nilable(::T.type_parameter(:R)))
+    end
     def time_stage(stage, &block)
-      ret = nil
-      @timings << @benchmark.report(stage) { ret = block.call }
+      ret = ::T.let(nil, ::T.nilable(::T.type_parameter(:R)))
+      @timings << ::T.unsafe(@benchmark.report(stage) { ret = block.call })
       ret
     end
   end

data/lib/csv_plus_plus/cell.rb

@@ -1,67 +1,55 @@
+# typed: strict
 # frozen_string_literal: true
 
-require_relative 'modifier'
-require_relative 'parser/cell_value.tab'
-
 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
   class Cell
-    attr_accessor :ast, :row_index
-    attr_reader :index, :modifier
+    extend ::T::Sig
 
-    # 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 = ::CSVPlusPlus::Parser::CellValue.new.parse(value, runtime)
-      end
-    end
+    sig { returns(::T.nilable(::CSVPlusPlus::Entities::Entity)) }
+    attr_accessor :ast
 
-    # @param row_index [Integer] The cell's row index (starts at 0)
+    sig { returns(::Integer) }
+    attr_accessor :row_index
+
+    sig { returns(::Integer) }
+    attr_reader :index
+
+    sig { returns(::CSVPlusPlus::Modifier::Modifier) }
+    attr_reader :modifier
+
+    sig do
+      params(
+        index: ::Integer,
+        modifier: ::CSVPlusPlus::Modifier::Modifier,
+        row_index: ::Integer,
+        value: ::T.nilable(::String)
+      ).void
+    end
     # @param index [Integer] The cell's index (starts at 0)
-    # @param value [String] A string value which should already have been processed through a CSV parser
     # @param modifier [Modifier] A modifier to apply to this cell
-    def initialize(row_index:, index:, value:, modifier:)
+    # @param row_index [Integer] The cell's row index (starts at 0)
+    # @param value [String] A string value which should already have been processed through a CSV parser
+    def initialize(index:, modifier:, row_index:, value:)
       @value = value
       @modifier = modifier
       @index = index
       @row_index = row_index
     end
 
+    sig { returns(::T.nilable(::String)) }
     # The +@value+ (cleaned up some)
     #
-    # @return [String]
+    # @return [::String]
     def value
-      return if @value.nil? || @value.strip.empty?
-
-      @value.strip
-    end
-
-    # @return [String]
-    def to_s
-      "Cell(index: #{@index}, row_index: #{@row_index}, value: #{@value}, modifier: #{@modifier})"
-    end
-
-    # A compiled final representation of the cell.  This can only happen after all cell have had
-    # variables and functions resolved.
-    #
-    # @return [String]
-    def to_csv
-      return value unless @ast
+      stripped = @value&.strip
 
-      # This looks really simple but we're relying on each node of the AST to define #to_s such that calling
-      # this at the top will recursively print the tree (as a well-formatted spreadsheet formula)
-      "=#{@ast}"
+      stripped&.empty? ? nil : stripped
     end
   end
 end

data/lib/csv_plus_plus/cli.rb

@@ -1,103 +1,48 @@
+# typed: strict
 # frozen_string_literal: true
 
-require 'optparse'
-
 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::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.parse_options!
-      cli.main
+      new.main
     rescue ::StandardError => e
-      cli.handle_error(e)
+      warn(e.message)
       exit(1)
     end
 
-    # Compile the given template using the given CLI flags
-    def main
-      parse_options! unless @options
-      ::CSVPlusPlus.apply_template_to_sheet!(::ARGF.read, ::ARGF.filename, @options)
-    end
-
-    # 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
-    end
+    sig { void }
+    # Initialize and parse the CLI flags provided to the program
+    def initialize
+      opts = parse_options
 
-    # Handle the supplied command line options, setting +@options+ or throw an error if anything is invalid
-    def parse_options!
-      @options = ::CSVPlusPlus::Options.new
-      option_parser.parse!
-      validate_options
-    rescue ::OptionParser::InvalidOption => e
-      raise(::CSVPlusPlus::Error::Error, e.message)
+      @source_code = ::T.let(::CSVPlusPlus::SourceCode.new(source_code_filename), ::CSVPlusPlus::SourceCode)
+      @options = ::T.let(apply_options(opts), ::CSVPlusPlus::Options::Options)
     end
 
-    # @return [::String]
-    def to_s
-      "CLI(options: #{options})"
+    sig { void }
+    # Compile the given template using the given CLI flags
+    def main
+      ::CSVPlusPlus.cli_compile(source_code, options)
     end
 
     private
 
-    # 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
-
-    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
-
-    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
-
-    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|
         parser.on('-h', '--help', 'Show help information') do
@@ -105,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