csv_plus_plus 0.1.1 → 0.1.3

data/lib/csv_plus_plus/runtime/runtime.rb

@@ -0,0 +1,126 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Runtime
+    # The runtime state of the compiler (the current +line_number+/+row_index+, +cell+ being processed, etc) for parsing
+    # a given file.  We take multiple runs through the input file for parsing so it's really convenient to have a
+    # central place for these things to be managed.
+    #
+    # @attr_reader filename [String, nil] The filename that the input came from (mostly used for debugging since
+    #   +filename+ can be +nil+ if it's read from stdin.
+    #
+    # @attr cell [Cell] The current cell being processed
+    # @attr cell_index [Integer] The index of the current cell being processed (starts at 0)
+    # @attr row_index [Integer] The index of the current row being processed (starts at 0)
+    # @attr line_number [Integer] The line number of the original csvpp template (starts at 1)
+    class Runtime
+      extend ::T::Sig
+
+      include ::CSVPlusPlus::Runtime::CanDefineReferences
+      include ::CSVPlusPlus::Runtime::CanResolveReferences
+      include ::CSVPlusPlus::Runtime::PositionTracker
+
+      sig { returns(::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Function]) }
+      attr_reader :functions
+
+      sig { returns(::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]) }
+      attr_reader :variables
+
+      sig { returns(::CSVPlusPlus::SourceCode) }
+      attr_reader :source_code
+
+      sig do
+        params(
+          source_code: ::CSVPlusPlus::SourceCode,
+          functions: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Function],
+          variables: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]
+        ).void
+      end
+      # @param source_code [SourceCode] The source code being compiled
+      # @param functions [Hash<Symbol, Function>] Pre-defined functions
+      # @param variables [Hash<Symbol, Entity>] Pre-defined variables
+      def initialize(source_code:, functions: {}, variables: {})
+        @functions = functions
+        @variables = variables
+        @source_code = source_code
+
+        rewrite_input!(source_code.input)
+      end
+
+      sig { params(fn_id: ::Symbol).returns(::T::Boolean) }
+      # Is +fn_id+ a builtin function?
+      #
+      # @param fn_id [Symbol] The Function#id to check if it's a runtime variable
+      #
+      # @return [T::Boolean]
+      def builtin_function?(fn_id)
+        ::CSVPlusPlus::Entities::Builtins::FUNCTIONS.key?(fn_id)
+      end
+
+      sig { params(var_id: ::Symbol).returns(::T::Boolean) }
+      # Is +var_id+ a builtin variable?
+      #
+      # @param var_id [Symbol] The Variable#id to check if it's a runtime variable
+      #
+      # @return [T::Boolean]
+      def builtin_variable?(var_id)
+        ::CSVPlusPlus::Entities::Builtins::VARIABLES.key?(var_id)
+      end
+
+      sig { returns(::T::Boolean) }
+      # Is the parser currently inside of the code section? (includes the `---`)
+      #
+      # @return [T::Boolean]
+      def parsing_code_section?
+        source_code.in_code_section?(line_number)
+      end
+
+      sig { returns(::T::Boolean) }
+      # Is the parser currently inside of the CSV section?
+      #
+      # @return [T::Boolean]
+      def parsing_csv_section?
+        source_code.in_csv_section?(line_number)
+      end
+
+      sig do
+        params(message: ::String, bad_input: ::String, wrapped_error: ::T.nilable(::StandardError))
+          .returns(::T.noreturn)
+      end
+      # Called when an error is encoutered during parsing formulas (whether in the code section or a cell).  It will
+      # construct a useful error with the current +@row/@cell_index+, +@line_number+ and +@filename+
+      #
+      # @param message [::String] A message relevant to why this error is being raised.
+      # @param bad_input [::String] The offending input that caused this error to be thrown.
+      # @param wrapped_error [StandardError, nil] The underlying error that was raised (if it's not from our own logic)
+      def raise_formula_syntax_error(message, bad_input, wrapped_error: nil)
+        raise(::CSVPlusPlus::Error::FormulaSyntaxError.new(message, bad_input, self, wrapped_error:))
+      end
+
+      sig do
+        params(message: ::String, bad_input: ::String, wrapped_error: ::T.nilable(::StandardError))
+          .returns(::T.noreturn)
+      end
+      # Called when an error is encountered while parsing a modifier.
+      #
+      # @param message [::String] A message relevant to why this error is being raised.
+      # @param bad_input [::String] The offending input that caused this error to be thrown.
+      # @param wrapped_error [StandardError, nil] The underlying error that was raised (if it's not from our own logic)
+      def raise_modifier_syntax_error(message, bad_input, wrapped_error: nil)
+        raise(::CSVPlusPlus::Error::ModifierSyntaxError.new(self, bad_input:, message:, wrapped_error:))
+      end
+
+      sig do
+        type_parameters(:R).params(block: ::T.proc.returns(::T.type_parameter(:R))).returns(::T.type_parameter(:R))
+      end
+      # Reset the runtime state starting at the CSV section
+      # rubocop:disable Naming/BlockForwarding
+      def start_at_csv!(&block)
+        self.line_number = source_code.length_of_code_section + 1
+        start!(&block)
+      end
+      # rubocop:enable Naming/BlockForwarding
+    end
+  end
+end

data/lib/csv_plus_plus/runtime.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative './runtime/can_define_references'
+require_relative './runtime/can_resolve_references'
+require_relative './runtime/graph'
+require_relative './runtime/position_tracker'
+require_relative './runtime/references'
+require_relative './runtime/runtime'
+
+module CSVPlusPlus
+  # All functionality needed to keep track of the runtime AKA execution context.  This module has a lot of
+  # reponsibilities:
+  #
+  # - variables and function resolution and scoping
+  # - variable & function definitions
+  # - keeping track of the runtime state (the current cell being processed)
+  # - rewriting the input file that's being parsed
+  #
+  module Runtime
+    extend ::T::Sig
+
+    sig do
+      params(
+        source_code: ::CSVPlusPlus::SourceCode,
+        functions: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Function],
+        variables: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]
+      ).returns(::CSVPlusPlus::Runtime::Runtime)
+    end
+    # Initialize a runtime instance with all the functionality we need.  A runtime is one-to-one with a file being
+    # compiled.
+    #
+    # @param source_code [SourceCode] The csv++ source code to be compiled
+    # @param functions [Hash<Symbol, Function>] Pre-defined functions
+    # @param variables [Hash<Symbol, Entity>] Pre-defined variables
+    #
+    # @return [Runtime::Runtime]
+    def self.new(source_code:, functions: {}, variables: {})
+      ::CSVPlusPlus::Runtime::Runtime.new(source_code:, functions:, variables:)
+    end
+  end
+end

data/lib/csv_plus_plus/source_code.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  # Information about the unparsed source code
+  class SourceCode
+    extend ::T::Sig
+
+    sig { returns(::String) }
+    attr_reader :input
+
+    sig { returns(::String) }
+    attr_reader :filename
+
+    sig { returns(::Integer) }
+    attr_reader :length_of_csv_section
+
+    sig { returns(::Integer) }
+    attr_reader :length_of_code_section
+
+    sig { returns(::Integer) }
+    attr_reader :length_of_file
+
+    sig { params(input: ::String, filename: ::T.nilable(::String)).void }
+    # @param input [::String] The source code being parsed
+    # @param filename [::String, nil] The name of the file the source came from.  If not set we assume it came
+    #   from stdin
+    def initialize(input:, filename: nil)
+      @input = input
+      @filename = ::T.let(filename || 'stdin', ::String)
+
+      lines = input.split(/[\r\n]/)
+      @length_of_file = ::T.let(lines.length, ::Integer)
+      @length_of_code_section = ::T.let(count_code_section_lines(lines), ::Integer)
+      @length_of_csv_section = ::T.let(@length_of_file - @length_of_code_section, ::Integer)
+    end
+
+    sig { params(line_number: ::Integer).returns(::T::Boolean) }
+    # Does the given +line_number+ land in the code section of the file? (which includes the --- separator)
+    #
+    # @param line_number [Integer]
+    #
+    # @return [T::Boolean]
+    def in_code_section?(line_number)
+      line_number <= @length_of_code_section
+    end
+
+    sig { params(line_number: ::Integer).returns(::T::Boolean) }
+    # Does the given +line_number+ land in the CSV section of the file?
+    #
+    # @param line_number [Integer]
+    #
+    # @return [T::Boolean]
+    def in_csv_section?(line_number)
+      line_number > @length_of_code_section
+    end
+
+    private
+
+    sig { params(lines: ::T::Array[::String]).returns(::Integer) }
+    def count_code_section_lines(lines)
+      eoc = ::CSVPlusPlus::Lexer::END_OF_CODE_SECTION
+      lines.include?(eoc) ? (lines.take_while { |l| l != eoc }).length + 1 : 0
+    end
+  end
+end

data/lib/csv_plus_plus/template.rb

@@ -1,42 +1,70 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  # Contains the flow and data from a code section and CSV section
+  # Contains the data from a parsed csvpp template.
   #
-  # @attr_reader code_section [CodeSection] The +CodeSection+ containing the functions and variables defined herein
   # @attr_reader rows [Array<Row>] The +Row+s that comprise this +Template+
+  # @attr_reader runtime [Runtime] The +Runtime+ containing all function and variable references
   class Template
-    attr_reader :code_section, :rows
+    extend ::T::Sig
 
-    # @param code_section [CodeSection] The +CodeSection+ containing the functions and variables
+    sig { returns(::T::Array[::CSVPlusPlus::Row]) }
+    attr_reader :rows
+
+    sig { returns(::CSVPlusPlus::Runtime::Runtime) }
+    attr_reader :runtime
+
+    sig { params(rows: ::T::Array[::CSVPlusPlus::Row], runtime: ::CSVPlusPlus::Runtime::Runtime).void }
     # @param rows [Array<Row>] The +Row+s that comprise this +Template+
-    def initialize(code_section:, rows:)
-      @code_section = code_section
+    # @param runtime [Runtime] The +Runtime+ containing all function and variable references
+    def initialize(rows:, runtime:)
       @rows = rows
+      @runtime = runtime
     end
 
-    # @return [String]
-    def to_s
-      "Template(rows: #{@rows})"
+    sig { params(runtime: ::CSVPlusPlus::Runtime::Runtime).void }
+    # Only run after expanding all rows, now we can bind all [[var=]] modifiers to a variable.  There are two distinct
+    # types of variable bindings here:
+    #
+    # * Binding to a cell: for this we just make a +CellReference+ to the cell itself (A1, B4, etc)
+    # * Binding to a cell within an expand: the variable can only be resolved within that expand and needs to be
+    #   relative to it's row (it can't be an absolute cell reference like above)
+    #
+    # @param runtime [Runtime] The current runtime
+    def bind_all_vars!(runtime)
+      runtime.map_rows(@rows) do |row|
+        # rubocop:disable Style/MissingElse
+        if row.unexpanded?
+          # rubocop:enable Style/MissingElse
+          raise(::CSVPlusPlus::Error::Error, 'Template#expand_rows! must be called before Template#bind_all_vars!')
+        end
+
+        runtime.map_row(row.cells) do |cell|
+          bind_vars(cell, row.modifier.expand)
+        end
+      end
     end
 
-    # Apply any expand= modifiers to the parsed template
+    sig { returns(::T::Array[::CSVPlusPlus::Row]) }
+    # Apply expand= (adding rows to the results) modifiers to the parsed template. This happens in towards the end of
+    # compilation because expanding rows will change the relative rownums as rows are added, and variables can't be
+    # bound until the rows have been assigned their final rownums.
     #
     # @return [Array<Row>]
     def expand_rows!
-      expanded_rows = []
-      row_index = 0
-      expand_rows(
-        lambda do |new_row|
-          new_row.index = row_index
-          expanded_rows << new_row
-          row_index += 1
+      # TODO: make it so that an infinite expand will not overwrite the rows below it, but instead merge with them
+      @rows =
+        rows.reduce([]) do |expanded_rows, row|
+          if row.modifier.expand
+            row.expand_rows(starts_at: expanded_rows.length, into: expanded_rows)
+          else
+            expanded_rows << row.tap { |r| r.index = expanded_rows.length }
+          end
         end
-      )
-
-      @rows = expanded_rows
     end
 
+    sig { params(runtime: ::CSVPlusPlus::Runtime::Runtime).void }
     # Make sure that the template has a valid amount of infinite expand modifiers
     #
     # @param runtime [Runtime] The compiler's current runtime
@@ -44,19 +72,20 @@ module CSVPlusPlus
       infinite_expand_rows = @rows.filter { |r| r.modifier.expand&.infinite? }
       return unless infinite_expand_rows.length > 1
 
-      runtime.raise_syntax_error(
+      runtime.raise_modifier_syntax_error(
         'You can only have one infinite expand= (on all others you must specify an amount)',
-        infinite_expand_rows[1]
+        infinite_expand_rows[1].to_s
       )
     end
 
-    # Provide a summary of the state of the template (and it's +@code_section+)
+    sig { returns(::String) }
+    # Provide a summary of the state of the template (and it's +@runtime+)
     #
-    # @return [String]
+    # @return [::String]
     def verbose_summary
       # TODO: we can probably include way more stats in here
       <<~SUMMARY
-        #{@code_section.verbose_summary}
+        #{@runtime.verbose_summary}
 
         > #{@rows.length} rows to be written
       SUMMARY
@@ -64,17 +93,15 @@ module CSVPlusPlus
 
     private
 
-    def expand_rows(push_row_fn)
-      # TODO: make it so that an infinite expand will not overwrite the rows below it, but
-      # instead merge with them
-      rows.each do |row|
-        if row.modifier.expand
-          row.expand_amount.times do
-            push_row_fn.call(row.deep_clone)
-          end
-        else
-          push_row_fn.call(row)
-        end
+    sig { params(cell: ::CSVPlusPlus::Cell, expand: ::T.nilable(::CSVPlusPlus::Modifier::Expand)).void }
+    def bind_vars(cell, expand)
+      var = cell.modifier.var
+      return unless var
+
+      if expand
+        @runtime.bind_variable_in_expand(var, expand)
+      else
+        @runtime.bind_variable_to_cell(var)
       end
     end
   end

data/lib/csv_plus_plus/version.rb

@@ -1,6 +1,7 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  VERSION = '0.1.1'
+  VERSION = '0.1.3'
   public_constant :VERSION
 end

data/lib/csv_plus_plus/writer/base_writer.rb

@@ -1,20 +1,45 @@
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
   module Writer
     # Some shared functionality that all Writers should build on
+    #
+    # @attr_reader options [Options] The supplied options - some of which are relevant for our writer instance
+    # @attr_reader runtime [Runtime] The current runtime - needed to resolve variables and display useful error messages
     class BaseWriter
-      attr_accessor :options
+      extend ::T::Sig
+      extend ::T::Helpers
+
+      abstract!
+
+      sig { returns(::CSVPlusPlus::Options) }
+      attr_reader :options
+
+      sig { returns(::CSVPlusPlus::Runtime::Runtime) }
+      attr_reader :runtime
 
       protected
 
-      # Open a CSV outputter to +filename+
-      def initialize(options)
+      sig { params(options: ::CSVPlusPlus::Options, runtime: ::CSVPlusPlus::Runtime::Runtime).void }
+      # Open a CSV outputter to the +output_filename+ specified by the +Options+
+      #
+      # @param options [Options] The supplied options.
+      # @param runtime [Runtime] The current runtime.
+      def initialize(options, runtime)
         @options = options
-        load_requires
+        @runtime = runtime
       end
 
-      def load_requires; end
+      sig { abstract.params(template: ::CSVPlusPlus::Template).void }
+      # Write the given +template+.
+      #
+      # @param template [Template]
+      def write(template); end
+
+      sig { abstract.void }
+      # Write a backup of the current spreadsheet.
+      def write_backup; end
     end
   end
 end

data/lib/csv_plus_plus/writer/csv.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 require_relative './file_backer_upper'
@@ -6,28 +7,29 @@ module CSVPlusPlus
   module Writer
     # A class that can output a +Template+ to CSV
     class CSV < ::CSVPlusPlus::Writer::BaseWriter
+      extend ::T::Sig
+
       include ::CSVPlusPlus::Writer::FileBackerUpper
 
-      # write a +template+ to CSV
+      sig { override.params(template: ::CSVPlusPlus::Template).void }
+      # Write a +template+ to CSV
+      #
+      # @param template [Template] The template to use as input to be written.  It should have been compiled by calling
+      #   Compiler#compile_template
       def write(template)
         # TODO: also read it and merge the results
         ::CSV.open(@options.output_filename, 'wb') do |csv|
-          template.rows.each do |row|
+          @runtime.map_rows(template.rows) do |row|
             csv << build_row(row)
           end
         end
       end
 
-      protected
-
-      def load_requires
-        require('csv')
-      end
-
       private
 
+      sig { params(row: ::CSVPlusPlus::Row).returns(::T::Array[::T.nilable(::String)]) }
       def build_row(row)
-        row.cells.map(&:to_csv)
+        @runtime.map_row(row.cells) { |cell, _i| cell.evaluate(@runtime) }
       end
     end
   end

data/lib/csv_plus_plus/writer/excel.rb

@@ -1,3 +1,4 @@
+# typed: strict
 # frozen_string_literal: true
 
 require_relative './file_backer_upper'
@@ -7,13 +8,19 @@ module CSVPlusPlus
   module Writer
     # A class that can output a +Template+ to an Excel file
     class Excel < ::CSVPlusPlus::Writer::BaseWriter
+      extend ::T::Sig
+
       include ::CSVPlusPlus::Writer::FileBackerUpper
 
-      # write the +template+ to an Excel file
+      sig { override.params(template: ::CSVPlusPlus::Template).void }
+      # Write the +template+ to an Excel file
+      #
+      # @param template [Template] The template to write
       def write(template)
         ::CSVPlusPlus::Writer::RubyXLBuilder.new(
-          input_filename: @options.output_filename,
+          input_filename: ::T.must(@options.output_filename),
           rows: template.rows,
+          runtime: @runtime,
           sheet_name: @options.sheet_name
         ).build_workbook.write(@options.output_filename)
       end

data/lib/csv_plus_plus/writer/file_backer_upper.rb

@@ -1,8 +1,6 @@
+# typed: false
 # frozen_string_literal: true
 
-require 'fileutils'
-require 'pathname'
-
 module CSVPlusPlus
   module Writer
     # A module that can be mixed into any Writer that needs to back up it's @output_filename (all of them except Google
@@ -26,6 +24,7 @@ module CSVPlusPlus
 
       private
 
+      # rubocop:disable Metrics/MethodLength
       def attempt_backups
         attempted =
           # rubocop:disable Lint/ConstantResolution
@@ -39,8 +38,12 @@ module CSVPlusPlus
             return backed_up_to
           end
 
-        raise(::CSVPlusPlus::Error, "Unable to write backup file despite trying these: #{attempted.join(', ')}")
+        raise(
+          ::CSVPlusPlus::Error::WriterError,
+          "Unable to write backup file despite trying these: #{attempted.join(', ')}"
+        )
       end
+      # rubocop:enable Metrics/MethodLength
 
       def backup(filename)
         return if ::File.exist?(filename)