csv_plus_plus 0.1.2 → 0.1.3

data/lib/csv_plus_plus/entities/runtime_value.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
@@ -7,19 +8,35 @@ module CSVPlusPlus
     #
     # @attr_reader resolve_fn [lambda] A lambda that is called when the runtime value is resolved
     class RuntimeValue < Entity
-      attr_reader :arguments, :resolve_fn
+      extend ::T::Sig
 
+      sig { returns(::T::Array[::T.untyped]) }
+      attr_reader :arguments
+
+      sig { returns(::T.proc.params(arg0: ::CSVPlusPlus::Runtime::Runtime).returns(::CSVPlusPlus::Entities::Entity)) }
+      attr_reader :resolve_fn
+
+      sig do
+        params(
+          resolve_fn: ::T.proc.params(arg0: ::CSVPlusPlus::Runtime::Runtime).returns(::CSVPlusPlus::Entities::Entity),
+          arguments: ::T::Array[::T.untyped]
+        ).void
+      end
       # @param resolve_fn [lambda] A lambda that is called when the runtime value is resolved
-      def initialize(resolve_fn, arguments: nil)
-        super(:runtime_value)
+      # @param arguments [Any] Arguments to the runtime value call
+      def initialize(resolve_fn, arguments: [])
+        super(::CSVPlusPlus::Entities::Type::RuntimeValue)
 
         @arguments = arguments
         @resolve_fn = resolve_fn
       end
 
+      sig { override.params(_runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::String) }
+      # @param _runtime [Runtime]
+      #
       # @return [String]
-      def to_s
-        '(runtime_value)'
+      def evaluate(_runtime)
+        '(runtime value)'
       end
     end
   end

data/lib/csv_plus_plus/entities/string.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
@@ -6,23 +7,35 @@ module CSVPlusPlus
     #
     # @attr_reader value [String]
     class String < Entity
+      extend ::T::Sig
+
+      sig { returns(::String) }
       attr_reader :value
 
+      sig { params(value: ::String).void }
       # @param value [String] The string that has been parsed out of the template
       def initialize(value)
-        super(:string)
+        super(::CSVPlusPlus::Entities::Type::String)
 
-        @value = value.gsub(/^"|"$/, '')
+        @value = ::T.let(value.gsub(/^"|"$/, ''), ::String)
       end
 
-      # @return [String]
-      def to_s
+      sig { override.params(_runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::String) }
+      # @param _runtime [Runtime]
+      #
+      # @return [::String]
+      def evaluate(_runtime)
         "\"#{@value}\""
       end
 
-      # @return [boolean]
+      sig { override.params(other: ::CSVPlusPlus::Entities::Entity).returns(::T::Boolean) }
+      # @param other [Entity]
+      #
+      # @return [T::Boolean]
       def ==(other)
-        super && value == other.value
+        return false unless super
+
+        other.is_a?(self.class) && @value == other.value
       end
     end
   end

data/lib/csv_plus_plus/entities/variable.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
@@ -6,19 +7,30 @@ module CSVPlusPlus
     #
     # A reference to a variable
     class Variable < Entity
+      extend ::T::Sig
+
+      sig { params(id: ::Symbol).void }
       # @param id [Symbol] The identifier of the variable
       def initialize(id)
-        super(:variable, id:)
+        super(::CSVPlusPlus::Entities::Type::Variable, id:)
       end
 
-      # @return [String]
-      def to_s
+      sig { override.params(_runtime: ::CSVPlusPlus::Runtime::Runtime).returns(::String) }
+      # @param _runtime [Runtime]
+      #
+      # @return [::String]
+      def evaluate(_runtime)
         "$$#{@id}"
       end
 
+      sig { override.params(other: ::CSVPlusPlus::Entities::Entity).returns(::T::Boolean) }
+      # @param other [Entity]
+      #
       # @return [boolean]
       def ==(other)
-        super && id == other.id
+        return false unless super
+
+        other.is_a?(self.class) && @id == other.id
       end
     end
   end

data/lib/csv_plus_plus/entities.rb

@@ -1,9 +1,12 @@
+# typed: strict
 # frozen_string_literal: true
 
+require_relative 'entities/entity'
+require_relative 'entities/entity_with_arguments'
+
 require_relative 'entities/boolean'
 require_relative 'entities/cell_reference'
 require_relative 'entities/date'
-require_relative 'entities/entity'
 require_relative 'entities/function'
 require_relative 'entities/function_call'
 require_relative 'entities/number'
@@ -12,20 +15,24 @@ require_relative 'entities/string'
 require_relative 'entities/variable'
 
 module CSVPlusPlus
+  # The entities that form abstract syntax trees which make up the language
   module Entities
-    TYPES = {
-      boolean: ::CSVPlusPlus::Entities::Boolean,
-      cell_reference: ::CSVPlusPlus::Entities::CellReference,
-      date: ::CSVPlusPlus::Entities::Date,
-      function: ::CSVPlusPlus::Entities::Function,
-      function_call: ::CSVPlusPlus::Entities::FunctionCall,
-      number: ::CSVPlusPlus::Entities::Number,
-      runtime_value: ::CSVPlusPlus::Entities::RuntimeValue,
-      string: ::CSVPlusPlus::Entities::String,
-      variable: ::CSVPlusPlus::Entities::Variable
-    }.freeze
+    extend ::T::Sig
 
-    public_constant :TYPES
+    # A primitive type.  These all correspond to an implementation of the same name in the CSVPlusPlus::Entities module.
+    class Type < ::T::Enum
+      enums do
+        Boolean = new
+        CellReference = new
+        Date = new
+        Function = new
+        FunctionCall = new
+        Number = new
+        RuntimeValue = new
+        String = new
+        Variable = new
+      end
+    end
   end
 end
 

data/lib/csv_plus_plus/error/error.rb

@@ -1,10 +1,20 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
   module Error
     # An error thrown by our code (generally to be handled at the top level bin/ command)
     class Error < StandardError
-      # TODO: perhaps give this a better name? something more descriptive than just Error
+      extend ::T::Sig
+      extend ::T::Helpers
+
+      sig { returns(::String) }
+      # Return an error message for display to a command-line user.
+      #
+      # @return [::String]
+      def error_message
+        message
+      end
     end
   end
 end

data/lib/csv_plus_plus/error/formula_syntax_error.rb

@@ -1,3 +1,4 @@
+# typed: true
 # frozen_string_literal: true
 
 require_relative './syntax_error'

data/lib/csv_plus_plus/error/modifier_syntax_error.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 require_relative './syntax_error'
@@ -6,21 +7,68 @@ module CSVPlusPlus
   module Error
     # An Error that wraps a +ModifierValidationError+ with a +Runtime+.
     class ModifierSyntaxError < ::CSVPlusPlus::Error::SyntaxError
-      # You must supply either a +choices+ or +message+
+      extend ::T::Sig
+
+      sig { returns(::String) }
+      attr_reader :bad_input
+
+      sig { returns(::String) }
+      attr_reader :message
+
+      sig { returns(::T.nilable(::Symbol)) }
+      attr_reader :modifier
+
+      sig do
+        params(
+          runtime: ::CSVPlusPlus::Runtime::Runtime,
+          modifier_validation_error: ::CSVPlusPlus::Error::ModifierValidationError
+        ).returns(::CSVPlusPlus::Error::ModifierSyntaxError)
+      end
+      # Create a +ModifierSyntaxError+ given a +runtime+ and +ModifierValidationError+.
       #
+      # @param runtime [Runtime]
+      # @param modifier_validation_error [ModifierValidationError]
+      #
+      # @return [ModifierSyntaxError]
+      def self.from_validation_error(runtime, modifier_validation_error)
+        new(
+          runtime,
+          modifier: modifier_validation_error.modifier,
+          bad_input: modifier_validation_error.bad_input,
+          message: modifier_validation_error.message,
+          wrapped_error: modifier_validation_error
+        )
+      end
+
+      sig do
+        params(
+          runtime: ::CSVPlusPlus::Runtime::Runtime,
+          bad_input: ::String,
+          message: ::String,
+          modifier: ::T.nilable(::Symbol),
+          wrapped_error: ::T.nilable(::StandardError)
+        ).void
+      end
       # @param runtime [Runtime] The current runtime
       # @param wrapped_error [ModifierValidationError] The validtion error that this is wrapping
-      def initialize(runtime, wrapped_error:)
-        @wrapped_error = wrapped_error
+      def initialize(runtime, bad_input:, message:, modifier: nil, wrapped_error: nil)
+        @bad_input = bad_input
+        @modifier = modifier
+        @message = message
 
         super(runtime, wrapped_error:)
       end
 
-      # Calls +wrapped_error.error_message+.
+      sig { override.returns(::String) }
+      # Create a relevant error message given +@choices+ or +@message+ (one of them must be supplied).
       #
       # @return [::String]
       def error_message
-        @wrapped_error.error_message
+        <<~ERROR_MESSAGE
+          Error parsing modifier: [[#{@modifier}=...]]
+          Bad input: #{@bad_input}
+          Reason: #{@message}
+        ERROR_MESSAGE
       end
     end
   end

data/lib/csv_plus_plus/error/modifier_validation_error.rb

@@ -1,7 +1,6 @@
+# typed: strict
 # frozen_string_literal: true
 
-require_relative './syntax_error'
-
 module CSVPlusPlus
   module Error
     # An error that can be thrown when a modifier doesn't pass our validation.
@@ -11,38 +10,59 @@ module CSVPlusPlus
     # @attr_reader choices [Array<Symbol>, nil] The choices that +value+ must be one of (but violated)
     # @attr_reader message [String, nil] A relevant message to show
     class ModifierValidationError < ::CSVPlusPlus::Error::Error
-      attr_reader :bad_input, :choices, :message, :modifier
+      extend ::T::Sig
+
+      sig { returns(::String) }
+      attr_reader :bad_input
+
+      sig { returns(::T.nilable(::T.class_of(::T::Enum))) }
+      attr_reader :choices
 
+      sig { returns(::String) }
+      attr_reader :message
+
+      sig { returns(::Symbol) }
+      attr_reader :modifier
+
+      sig do
+        params(
+          modifier: ::Symbol,
+          bad_input: ::String,
+          choices: ::T.nilable(::T.class_of(::T::Enum)),
+          message: ::T.nilable(::String)
+        ).void
+      end
       # You must supply either a +choices+ or +message+
       #
       # @param modifier [Symbol] The modifier being parsed when the bad input was encountered
       # @param bad_input [String] The offending input that caused the error to be thrown
       # @param choices [Array<Symbol>, nil] The choices that +value+ must be one of (but violated)
       # @param message [String, nil] A relevant message to show
-      def initialize(modifier, bad_input, choices: nil, message: nil)
+      # rubocop:disable Metrics/MethodLength
+      def initialize(modifier, bad_input:, choices: nil, message: nil)
         @bad_input = bad_input
         @choices = choices
         @modifier = modifier
 
-        @message =
+        @message = ::T.let(
           if @choices
-            "must be one of (#{@choices.map(&:to_s).join(', ')})"
+            "must be one of (#{@choices.values.map(&:serialize).join(', ')})"
           else
-            message
-          end
+            ::T.must(message)
+          end,
+          ::String
+        )
 
         super(@message)
       end
+      # rubocop:enable Metrics/MethodLength
 
-      # Create a relevant error message given +@choices+ or +@message+ (one of them must be supplied).
+      sig { returns(::String) }
+      # A user-facing error message
       #
       # @return [::String]
       def error_message
-        <<~ERROR_MESSAGE
-          Error parsing modifier: [[#{@modifier}=...]]
-          Bad input: #{@bad_input}
-          Reason: #{@message}
-        ERROR_MESSAGE
+        @message
       end
     end
   end

data/lib/csv_plus_plus/error/syntax_error.rb

@@ -1,9 +1,13 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
   module Error
     # An error that can be thrown for various syntax errors
     class SyntaxError < ::CSVPlusPlus::Error::Error
+      extend ::T::Sig
+
+      sig { params(runtime: ::CSVPlusPlus::Runtime::Runtime, wrapped_error: ::T.nilable(::StandardError)).void }
       # @param runtime [Runtime] The current runtime
       # @param wrapped_error [StandardError] The underlying error that caused the syntax error.  For example a
       #   Racc::ParseError that was thrown
@@ -14,18 +18,28 @@ module CSVPlusPlus
         super()
       end
 
-      # @return [String]
+      sig { returns(::String) }
+      # @return [::String]
       def to_s
         to_trace
       end
 
+      # TODO: clean up all these different string-formatting error classes
+      sig { override.returns(::String) }
+      # @return [::String]
+      def error_message
+        ''
+      end
+
+      sig { returns(::String) }
       # Output a verbose user-helpful string that references the current runtime
       def to_verbose_trace
         warn(@wrapped_error.full_message) if @wrapped_error
-        warn(@wrapped_error.backtrace) if @wrapped_error
+        warn((@wrapped_error.backtrace || []).join("\n")) if @wrapped_error&.backtrace
         to_trace
       end
 
+      sig { returns(::String) }
       # Output a user-helpful string that references the runtime state
       #
       # @return [String]
@@ -35,22 +49,21 @@ module CSVPlusPlus
 
       private
 
+      sig { returns(::String) }
       def cell_index
-        row_index = @runtime.row_index
-        if @runtime.cell_index
-          "[#{row_index},#{@runtime.cell_index}]"
-        elsif row_index
-          "[#{row_index}]"
+        if @runtime.parsing_csv_section?
+          "[#{@runtime.row_index},#{@runtime.cell_index}]"
         else
           ''
         end
       end
 
+      sig { returns(::String) }
       def message_prefix
         line_number = @runtime.line_number
-        filename = @runtime.filename
+        filename = @runtime.source_code.filename
 
-        line_str = line_number ? ":#{line_number}" : ''
+        line_str = ":#{line_number}"
         "#{filename}#{line_str}"
       end
     end

data/lib/csv_plus_plus/error/writer_error.rb

@@ -1,9 +1,17 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
   module Error
     # An error that can be thrown when writing a spreadsheet
     class WriterError < ::CSVPlusPlus::Error::Error
+      extend ::T::Sig
+
+      sig { override.returns(::String) }
+      # @return [::String]
+      def error_message
+        "Error writing template: #{message}"
+      end
     end
   end
 end

data/lib/csv_plus_plus/error.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 require_relative './error/error'

data/lib/csv_plus_plus/google_api_client.rb

@@ -1,9 +1,13 @@
+# 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
@@ -12,7 +16,8 @@ module CSVPlusPlus
       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

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,7 +1,6 @@
+# typed: false
 # frozen_string_literal: true
 
-require_relative '../color'
-
 module CSVPlusPlus
   # Common methods to be mixed into the Racc parsers
   #
@@ -30,13 +29,15 @@ 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_formula_syntax_error("Error parsing #{parse_subject}", e.message, wrapped_error: e)
     rescue ::CSVPlusPlus::Error::ModifierValidationError => e
-      raise(::CSVPlusPlus::Error::ModifierSyntaxError.new(runtime, wrapped_error: e))
+      raise(::CSVPlusPlus::Error::ModifierSyntaxError.from_validation_error(runtime, e))
     end
 
     TOKEN_LIBRARY = {
@@ -76,8 +77,11 @@ 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
-        # TODO: this should raise a modifier_syntax_error if we're on the modifier parser
         runtime.raise_formula_syntax_error("Unable to parse #{parse_subject} starting at", tokenizer.peek)
       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

@@ -1,3 +1,4 @@
+# typed: true
 # frozen_string_literal: true
 
 module CSVPlusPlus