csv_plus_plus 0.1.3 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abee03db0f21f9d8c5d3cfb4ec81dbd748568f878458f355cab6db5fc458a509
-  data.tar.gz: 6c4e95fa1c780a2d009eaeb58fd48b28c2dd96826b22be02f84d5fc8a06ad31e
+  metadata.gz: c29d586e678385367fe7a4a67fa66f4f0d111ceb1ace46125daaecbdd0bf7b03
+  data.tar.gz: aa13e49605c6448aa61cbf6d64ac39f3cfd9d8f84cb20370d8129ab5f1dd6f4b
 SHA512:
-  metadata.gz: 59f2cb756bdfd20f95f252aa1c07fb4b994def21f07d8bc4e5a976b22f0b439fb950e1723fdb34753baf23527e5950d244f1386e9231c6318b35de3974305ba4
-  data.tar.gz: 38b6d6d960aa17978adf2ee1724333754e7cdc86b8e41fa58522357448db8448d5441fb5961d3758af94d617b94b21b197b5e4d2d4eb2dba0cbc39da586c4413
+  metadata.gz: 6736fa3154f3ad44a4b3737a7d6e3b6571f6ba34226a8be4191a6cce3a53b1bcd09057b25bbc96da0ad01cc8c397e7b78df379b48fd510f881a810e8754aec65
+  data.tar.gz: 8160d63e5bda5417619d6a6e4e2a73b5cee744fc26b356d2c36efe3c56b93e2cfda8ed5cb128758079463542d0306d634c4804e02b7e4c56c14d9b98b0f3c1db

data/README.md

@@ -1,3 +1,8 @@
+# Deprecated!!!
+
+This version of csv++ is deprecated.  For the current version please go to [github.com/patrickomatic/csv-plus-plus](https://github.com/patrickomatic/csv-plus-plus)
+
+![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 +24,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 +50,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
 
@@ -58,7 +63,12 @@ Usage: csv++ [options]
     -k, --key-values KEY_VALUES      A comma-separated list of key=values which will be made available to the template
     -n, --sheet-name SHEET_NAME      The name of the sheet to apply the template to
     -o, --output OUTPUT_FILE         The file to write to (must be .csv, .ods, .xls)
+    -s, --safe                       Do not overwrite values in the spreadsheet being written to. The default is to overwrite
     -v, --verbose                    Enable verbose output
     -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,21 @@
+## main
+
+- Add a `-s`/`--safe` flag which changes the merge strategy to not overwrite existing values.  If the spreadsheet being written to has values where the csvpp template wants to write, they will be overwritten otherwise.
+
+## 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