csv_plus_plus 0.1.1 → 0.1.3

data/lib/csv_plus_plus/google_api_client.rb

@@ -1,16 +1,25 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
   # A convenience wrapper around Google's REST API client
   module GoogleApiClient
-    # Get a +::Google::Apis::SheetsV4::SheetsService+ instance connected to the sheets API
+    extend ::T::Sig
+
+    sig { returns(::Google::Apis::SheetsV4::SheetsService) }
+    # Get a +Google::Apis::SheetsV4::SheetsService+ instance configured to connect to the sheets API
+    #
+    # @return [Google::Apis::SheetsV4::SheetsService]
     def self.sheets_client
       ::Google::Apis::SheetsV4::SheetsService.new.tap do |s|
         s.authorization = ::Google::Auth.get_application_default(['https://www.googleapis.com/auth/spreadsheets'].freeze)
       end
     end
 
-    # Get a +::Google::Apis::DriveV3::DriveService+ instance connected to the drive API
+    sig { returns(::Google::Apis::DriveV3::DriveService) }
+    # Get a +Google::Apis::DriveV3::DriveService+ instance connected to the drive API
+    #
+    # @return [Google::Apis::DriveV3::DriveService]
     def self.drive_client
       ::Google::Apis::DriveV3::DriveService.new.tap do |d|
         d.authorization = ::Google::Auth.get_application_default(['https://www.googleapis.com/auth/drive.file'].freeze)

data/lib/csv_plus_plus/google_options.rb

@@ -1,27 +1,32 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  # The Google-specific options a user can supply
+  # The Google-specific options a user can supply.
   #
-  # attr sheet_id [String] The ID of the Google Sheet to write to
-  GoogleOptions =
-    ::Struct.new(:sheet_id) do
-      # Format a string with a verbose description of what we're doing with the options
-      #
-      # @return [String]
-      def verbose_summary
-        <<~SUMMARY
-          ## Google Sheets Options
+  # @attr sheet_id [String] The ID of the Google Sheet to write to.
+  class GoogleOptions
+    extend ::T::Sig
 
-          > Sheet ID | #{sheet_id}
-        SUMMARY
-      end
+    sig { returns(::String) }
+    attr_reader :sheet_id
 
-      # @return [String]
-      def to_s
-        "GoogleOptions(sheet_id: #{sheet_id})"
-      end
+    sig { params(sheet_id: ::String).void }
+    # @param sheet_id [String] The unique ID Google uses to reference the sheet
+    def initialize(sheet_id)
+      @sheet_id = sheet_id
     end
 
-  public_constant :GoogleOptions
+    sig { returns(::String) }
+    # Format a string with a verbose description of what we're doing with the options
+    #
+    # @return [String]
+    def verbose_summary
+      <<~SUMMARY
+        ## Google Sheets Options
+
+        > Sheet ID | #{@sheet_id}
+      SUMMARY
+    end
+  end
 end

data/lib/csv_plus_plus/lexer/lexer.rb

@@ -1,3 +1,4 @@
+# typed: false
 # frozen_string_literal: true
 
 module CSVPlusPlus
@@ -28,21 +29,27 @@ module CSVPlusPlus
 
       return return_value unless anything_to_parse?(input)
 
+      @runtime = runtime
+
       tokenize(input, runtime)
       do_parse
       return_value
     rescue ::Racc::ParseError => e
-      runtime.raise_syntax_error("Error parsing #{parse_subject}", e.message, wrapped_error: e)
+      runtime.raise_formula_syntax_error("Error parsing #{parse_subject}", e.message, wrapped_error: e)
+    rescue ::CSVPlusPlus::Error::ModifierValidationError => e
+      raise(::CSVPlusPlus::Error::ModifierSyntaxError.from_validation_error(runtime, e))
     end
 
     TOKEN_LIBRARY = {
-      TRUE: [/true/i, :TRUE],
+      A1_NOTATION: [::CSVPlusPlus::Entities::CellReference::A1_NOTATION_REGEXP, :A1_NOTATION],
       FALSE: [/false/i, :FALSE],
+      HEX_COLOR: [::CSVPlusPlus::Color::HEX_STRING_REGEXP, :HEX_COLOR],
+      ID: [/[$!\w:]+/, :ID],
+      INFIX_OP: [%r{\^|\+|-|\*|/|&|<|>|<=|>=|<>}, :INFIX_OP],
       NUMBER: [/-?[\d.]+/, :NUMBER],
       STRING: [%r{"(?:[^"\\]|\\(?:["\\/bfnrt]|u[0-9a-fA-F]{4}))*"}, :STRING],
-      INFIX_OP: [%r{\^|\+|-|\*|/|&|<|>|<=|>=|<>}, :INFIX_OP],
-      VAR_REF: [/\$\$/, :VAR_REF],
-      ID: [/[$!\w:]+/, :ID]
+      TRUE: [/true/i, :TRUE],
+      VAR_REF: [/\$\$/, :VAR_REF]
     }.freeze
     public_constant :TOKEN_LIBRARY
 
@@ -70,8 +77,12 @@ module CSVPlusPlus
         @tokens << [tokenizer.last_token, tokenizer.last_match]
       elsif tokenizer.scan_catchall
         @tokens << [tokenizer.last_match, tokenizer.last_match]
+      # TODO: checking the +parse_subject+ like this is a little hacky... but we need to know if we're parsing
+      # modifiers or code_section (or formulas in a cell)
+      elsif parse_subject == 'modifier'
+        runtime.raise_modifier_syntax_error("Unable to parse #{parse_subject} starting at", tokenizer.peek)
       else
-        runtime.raise_syntax_error("Unable to parse #{parse_subject} starting at", tokenizer.peek)
+        runtime.raise_formula_syntax_error("Unable to parse #{parse_subject} starting at", tokenizer.peek)
       end
     end
   end

data/lib/csv_plus_plus/lexer/tokenizer.rb

@@ -1,3 +1,4 @@
+# typed: true
 # frozen_string_literal: true
 
 require 'strscan'
@@ -11,7 +12,11 @@ module CSVPlusPlus
     class Tokenizer
       attr_reader :last_token, :scanner
 
-      # @param input [String]
+      # @param tokens [Array<Regexp, String>] The list of tokens to scan
+      # @param catchall [Regexp] A final regexp to try if nothing else matches
+      # @param ignore [Regexp] Ignore anything matching this regexp
+      # @param alter_matches [Object] A map of matches to alter
+      # @param stop_fn [Proc] Stop parsing when this is true
       def initialize(tokens:, catchall: nil, ignore: nil, alter_matches: {}, stop_fn: nil)
         @last_token = nil
 

data/lib/csv_plus_plus/lexer.rb

@@ -1,14 +1,38 @@
+# typed: strict
 # frozen_string_literal: true
 
 require_relative './lexer/lexer'
 require_relative './lexer/tokenizer'
 
 module CSVPlusPlus
+  # Code for tokenizing a csvpp file
   module Lexer
+    extend ::T::Sig
+
     END_OF_CODE_SECTION = '---'
     public_constant :END_OF_CODE_SECTION
 
     VARIABLE_REF = '$$'
     public_constant :VARIABLE_REF
+
+    sig { params(str: ::String).returns(::String) }
+    # When parsing a modifier with a quoted string field, we need a way to unescape.  Some examples of quoted and
+    # unquoted results:
+    #
+    # * "just a string" => "just a string"
+    # * "' this is a string'" => "this is a string"
+    # * "won\'t this work?" => "won't this work"
+    #
+    # @param str [::String]
+    #
+    # @return [::String]
+    def self.unquote(str)
+      # could probably do this with one regex but we do it in 3 steps:
+      #
+      # 1. remove leading and trailing spaces and '
+      # 2. remove any backslashes that are by themselves (none on either side)
+      # 3. turn double backslashes into singles
+      str.gsub(/^\s*'?|'?\s*$/, '').gsub(/([^\\]+)\\([^\\]+)/, '\1\2').gsub(/\\\\/, '\\')
+    end
   end
 end

data/lib/csv_plus_plus/modifier/conditional_formatting.rb

@@ -0,0 +1,18 @@
+# typed: true
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Modifier
+    # A class that handles the rules for modifiers to support conditional formatting.
+    class ConditionalFormatting
+      attr_reader :arguments, :condition, :invalid_reason
+
+      # @param value [::String] The unparsed conditional formatting rule
+      def initialize(value)
+        condition, args = value.split(/\si:\s*/)
+        @condition = condition.to_sym
+        @arguments = args.split(/\s+/)
+      end
+    end
+  end
+end

data/lib/csv_plus_plus/modifier/data_validation.rb

@@ -0,0 +1,138 @@
+# typed: true
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Modifier
+    # A validation on a cell value.  Used to support the `validate=` modifier directive.  This is mostly based on the
+    # Google Sheets API spec:
+    #
+    # @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/other#ConditionType
+    #
+    # @attr_reader arguments [Array<::String>] The parsed arguments as required by the condition.
+    # @attr_reader condition [Symbol] The condition (:blank, :text_eq, :date_before, etc.)
+    # @attr_reader invalid_reason [::String, nil] If set, the reason why this modifier is not valid.
+    class DataValidation
+      attr_reader :arguments, :condition, :invalid_reason
+
+      # @param value [::String] The value to parse as a data validation
+      def initialize(value)
+        condition, args = value.split(/\s*:\s*/)
+        @arguments = ::CSVPlusPlus::Lexer.unquote(args || '').split(/\s+/)
+        @condition = condition.to_sym
+
+        validate!
+      end
+
+      # Each data validation (represented by +@condition+) has their own requirements for which arguments are valid.
+      # If this object is invalid, you can see the reason in +@invalid_reason+.
+      #
+      # @return [boolean]
+      def valid?
+        @invalid_reason.nil?
+      end
+
+      protected
+
+      def invalid!(reason)
+        @invalid_reason = reason
+      end
+
+      def a_number(arg)
+        Float(arg)
+      rescue ::ArgumentError
+        invalid!("Requires a number but given: #{arg}")
+      end
+
+      def a1_notation(arg)
+        return arg if ::CSVPlusPlus::Entities::CellReference.valid_cell_reference?(arg)
+      end
+
+      def a_date(arg, allow_relative_date: false)
+        return arg if ::CSVPlusPlus::Entities::Date.valid_date?(arg)
+
+        if allow_relative_date
+          a_relative_date(arg)
+        else
+          invalid!("Requires a date but given: #{arg}")
+        end
+      end
+
+      def a_relative_date(arg)
+        return arg if %w[past_month past_week past_year yesterday today tomorrow].include?(arg.downcase)
+
+        invalid!('Requires a relative date: past_month, past_week, past_year, yesterday, today or tomorrow')
+      end
+
+      def no_args
+        return if @arguments.empty?
+
+        invalid!("Requires no arguments but #{@arguments.length} given: #{@arguments}")
+      end
+
+      def one_arg
+        return @arguments[0] if @arguments.length == 1
+
+        invalid!("Requires only one argument but #{@arguments.length} given: #{@arguments}")
+      end
+
+      def one_arg_or_more
+        return @arguments if @arguments.length.positive?
+
+        invalid!("Requires at least one argument but #{@arguments.length} given: #{@arguments}")
+      end
+
+      def two_dates
+        return @arguments if @arguments.length == 2 && a_date(@arguments[0]) && a_date(@arguments[1])
+
+        invalid!("Requires exactly two dates but given: #{@arguments}")
+      end
+
+      def two_numbers
+        return @arguments if @arguments.length == 2 && a_number(@arguments[0]) && a_number(@arguments[1])
+
+        invalid!("Requires exactly two numbers but given: #{@arguments}")
+      end
+
+      # validate_boolean is a weird one because it can have 0, 1 or 2 @arguments - all of them must be (true | false)
+      def validate_boolean
+        return @arguments if @arguments.empty?
+
+        converted_args = @arguments.map(&:strip).map(&:downcase)
+        return @arguments if [1, 2].include?(@arguments.length) && converted_args.all? do |arg|
+                               %w[true false].include?(arg)
+                             end
+
+        invalid!("Requires 0, 1 or 2 arguments and they all must be either 'true' or 'false'. Received: #{arguments}")
+      end
+
+      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+      def validate!
+        case condition.to_sym
+        when :blank, :date_is_valid, :not_blank, :text_is_email, :text_is_url
+          no_args
+        when :text_contains, :text_ends_with, :text_eq, :text_not_contains, :text_starts_with
+          one_arg
+        when :date_after, :date_before, :date_on_or_after, :date_on_or_before
+          a_date(one_arg, allow_relative_date: true)
+        when :date_eq, :date_not_eq
+          a_date(one_arg)
+        when :date_between, :date_not_between
+          two_dates
+        when :one_of_range
+          a1_notation(one_arg)
+        when :custom_formula, :one_of_list, :text_not_eq
+          one_arg_or_more
+        when :number_eq, :number_greater, :number_greater_than_eq, :number_less, :number_less_than_eq, :number_not_eq
+          a_number(one_arg)
+        when :number_between, :number_not_between
+          two_numbers
+        when :boolean
+          validate_boolean
+        else
+          invalid!('Not a recognized data validation directive')
+        end
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity, Metrics/AbcSize
+    end
+  end
+end

data/lib/csv_plus_plus/modifier/expand.rb

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Modifier
+    # The logic for how a row can expand
+    #
+    # @attr_reader ends_at [Integer, nil] Once the row has been expanded, where it ends at.
+    # @attr_reader repetitions [Integer, nil] How many times the row repeats/expands.
+    # @attr_reader starts_at [Integer, nil] Once the row has been expanded, where it starts at.
+    class Expand
+      extend ::T::Sig
+
+      sig { returns(::T.nilable(::Integer)) }
+      attr_reader :ends_at
+
+      sig { returns(::T.nilable(::Integer)) }
+      attr_reader :repetitions
+
+      sig { returns(::T.nilable(::Integer)) }
+      attr_reader :starts_at
+
+      sig { params(repetitions: ::T.nilable(::Integer), starts_at: ::T.nilable(::Integer)).void }
+      # @param repetitions [Integer, nil] How many times this expand repeats.  If it's +nil+ it will expand infinitely
+      #   (for the rest of the worksheet.)
+      # @param starts_at [Integer, nil] The final location where the +Expand+ will start.  It's important to note that
+      #   this can't be derived until all rows are expanded, because each expand modifier will push down the ones below
+      #   it.  So typically this param will not be passed in the initializer but instead set later.
+      def initialize(repetitions: nil, starts_at: nil)
+        @repetitions = ::T.let(repetitions, ::T.nilable(::Integer))
+        @starts_at = ::T.let(starts_at, ::T.nilable(::Integer)) unless starts_at.nil?
+        @ends_at = ::T.let(nil, ::T.nilable(::Integer))
+      end
+
+      sig { returns(::T::Boolean) }
+      # Has the row been expanded?
+      #
+      # @return [boolean]
+      def expanded?
+        !@starts_at.nil?
+      end
+
+      sig { returns(::T::Boolean) }
+      # Does this infinitely expand?
+      #
+      # @return [boolean]
+      def infinite?
+        repetitions.nil?
+      end
+
+      sig { params(row_index: ::Integer).void }
+      # Mark the start of the row once it's been expanded, as well as where it +ends_at+.  When expanding rows each one
+      # adds rows to the worksheet and if there are multiple `expand` modifiers in the worksheet, we don't know the
+      # final +row_index+ until we're in the phase of expanding all the rows out.
+      def starts_at=(row_index)
+        @starts_at = row_index
+        @ends_at = row_index + @repetitions unless @repetitions.nil?
+      end
+    end
+  end
+end

data/lib/csv_plus_plus/modifier/google_sheet_modifier.rb

@@ -0,0 +1,133 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Modifier
+    # Decorate a +Modifier+ so it is more compatible with the Google Sheets API
+    class GoogleSheetModifier < ::CSVPlusPlus::Modifier::Modifier
+      extend ::T::Sig
+
+      sig { returns(::T.nilable(::Google::Apis::SheetsV4::Color)) }
+      # Format the color for Google Sheets
+      #
+      # @return [Google::Apis::SheetsV4::Color]
+      def background_color
+        google_sheets_color(@color) if @color
+      end
+
+      sig { returns(::T.nilable(::Google::Apis::SheetsV4::Border)) }
+      # Format the border for Google Sheets
+      #
+      # @return [Google::Apis::SheetsV4::Border]
+      def border
+        return unless any_border?
+
+        # TODO: allow different border styles per side?
+        ::Google::Apis::SheetsV4::Border.new(
+          color: google_sheets_color(bordercolor || ::CSVPlusPlus::Color.new('#000000')),
+          style: border_style
+        )
+      end
+
+      sig { returns(::T.nilable(::Google::Apis::SheetsV4::Color)) }
+      # Format the fontcolor for Google Sheets
+      #
+      # @return [Google::Apis::SheetsV4::Color]
+      def font_color
+        google_sheets_color(@fontcolor) if @fontcolor
+      end
+
+      sig { returns(::T.nilable(::String)) }
+      # Format the halign for Google Sheets
+      #
+      # @return [::String]
+      def horizontal_alignment
+        halign&.serialize&.upcase
+      end
+
+      sig { returns(::T.nilable(::Google::Apis::SheetsV4::NumberFormat)) }
+      # Format the numberformat for Google Sheets
+      #
+      #
+      # @return [Google::Apis::SheetsV4::NumberFormat]
+      def number_format
+        ::Google::Apis::SheetsV4::NumberFormat.new(type: number_format_type(@numberformat)) if @numberformat
+      end
+
+      sig { returns(::Google::Apis::SheetsV4::TextFormat) }
+      # Builds a SheetsV4::TextFormat with the underlying Modifier
+      #
+      # @return [Google::Apis::SheetsV4::TextFormat]
+      def text_format
+        ::Google::Apis::SheetsV4::TextFormat.new(
+          bold: formatted?(::CSVPlusPlus::Modifier::TextFormat::Bold) || nil,
+          italic: formatted?(::CSVPlusPlus::Modifier::TextFormat::Italic) || nil,
+          strikethrough: formatted?(::CSVPlusPlus::Modifier::TextFormat::Strikethrough) || nil,
+          underline: formatted?(::CSVPlusPlus::Modifier::TextFormat::Underline) || nil,
+          font_family: fontfamily,
+          font_size: fontsize,
+          foreground_color: font_color
+        )
+      end
+
+      sig { returns(::T.nilable(::String)) }
+      # Format the valign for Google Sheets
+      def vertical_alignment
+        valign&.serialize&.upcase
+      end
+
+      private
+
+      sig { returns(::T.nilable(::String)) }
+      # Format the border style for Google Sheets
+      #
+      # @see https://developers.google.com/apps-script/reference/spreadsheet/border-style
+      #
+      # @return [::String, nil]
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def border_style
+        return 'SOLID' unless @borderstyle
+
+        case @borderstyle
+        when ::CSVPlusPlus::Modifier::BorderStyle::Dashed then 'DASHED'
+        when ::CSVPlusPlus::Modifier::BorderStyle::Dotted then 'DOTTED'
+        when ::CSVPlusPlus::Modifier::BorderStyle::Double then 'DOUBLE'
+        when ::CSVPlusPlus::Modifier::BorderStyle::Solid then 'SOLID'
+        when ::CSVPlusPlus::Modifier::BorderStyle::SolidMedium then 'SOLID_MEDIUM'
+        when ::CSVPlusPlus::Modifier::BorderStyle::SolidThick then 'SOLID_THICK'
+        else ::T.absurd(@borderstyle)
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      sig { params(color: ::CSVPlusPlus::Color).returns(::Google::Apis::SheetsV4::Color) }
+      def google_sheets_color(color)
+        ::Google::Apis::SheetsV4::Color.new(
+          red: color.red_percent,
+          green: color.green_percent,
+          blue: color.blue_percent
+        )
+      end
+
+      sig { params(numberformat: ::CSVPlusPlus::Modifier::NumberFormat).returns(::String) }
+      # @see https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets/cells#NumberFormat
+      #
+      # @return [::String]
+      # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+      def number_format_type(numberformat)
+        case numberformat
+        when ::CSVPlusPlus::Modifier::NumberFormat::Currency then 'CURRENCY'
+        when ::CSVPlusPlus::Modifier::NumberFormat::Date then 'DATE'
+        when ::CSVPlusPlus::Modifier::NumberFormat::DateTime then 'DATE_TIME'
+        when ::CSVPlusPlus::Modifier::NumberFormat::Number then 'NUMBER'
+        when ::CSVPlusPlus::Modifier::NumberFormat::Percent then 'PERCENT'
+        when ::CSVPlusPlus::Modifier::NumberFormat::Text then 'TEXT'
+        when ::CSVPlusPlus::Modifier::NumberFormat::Time then 'TIME'
+        when ::CSVPlusPlus::Modifier::NumberFormat::Scientific then 'SCIENTIFIC'
+        else ::T.absurd(numberformat)
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength
+    end
+  end
+end