csv_plus_plus 0.1.2 → 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

@@ -1,199 +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
-  # 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.
+  # All functionality needed to keep track of the runtime AKA execution context.  This module has a lot of
+  # reponsibilities:
   #
-  # @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_reader length_of_code_section [Integer] The length (count of lines) of the code section part of the original
-  #   input.
-  # @attr_reader length_of_csv_section [Integer] The length (count of lines) of the CSV part of the original csvpp
-  #   input.
-  # @attr_reader length_of_original_file [Integer] The length (count of lines) of the original csvpp input.
+  # - 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
   #
-  # @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
-    attr_reader :filename, :length_of_code_section, :length_of_csv_section, :length_of_original_file
-
-    attr_accessor :cell, :cell_index, :row_index, :line_number
-
-    # @param input [String] The input to be parsed
-    # @param 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
-    def initialize(input:, filename:)
-      @filename = filename || 'stdin'
-
-      init_input!(input)
-      start!
-    end
-
-    # Map over an a csvpp file and keep track of line_number and row_index
-    #
-    # @param lines [Array]
-    #
-    # @return [Array]
-    def map_lines(lines, &block)
-      @line_number = 1
-      lines.map do |line|
-        block.call(line).tap { next_line! }
-      end
-    end
-
-    # Map over a single row and keep track of the cell and it's index
-    #
-    # @param row [Array<Cell>] The row to map each cell over
-    #
-    # @return [Array]
-    def map_row(row, &block)
-      @cell_index = 0
-      row.map.with_index do |cell, index|
-        set_cell!(cell, index)
-        block.call(cell, index)
-      end
-    end
-
-    # Map over all rows and keep track of row and line numbers
-    #
-    # @param rows [Array<Row>] The rows to map over (and keep track of indexes)
-    # @param cells_too [boolean] If the cells of each +row+ should be iterated over also.
-    #
-    # @return [Array]
-    def map_rows(rows, cells_too: false, &block)
-      @row_index = 0
-      map_lines(rows) do |row|
-        if cells_too
-          # it's either CSV or a Row object
-          map_row((row.is_a?(::CSVPlusPlus::Row) ? row.cells : row), &block)
-        else
-          block.call(row)
-        end
-      end
-    end
-
-    # Increment state to the next line
-    #
-    # @return [Integer]
-    def next_line!
-      @row_index += 1 unless @row_index.nil?
-      @line_number += 1
-    end
-
-    # Return the current spreadsheet row number.  It parallels +@row_index+ but starts at 1.
-    #
-    # @return [Integer, nil]
-    def rownum
-      return if @row_index.nil?
-
-      @row_index + 1
-    end
-
-    # Set the current cell and index
-    #
-    # @param cell [Cell] The current cell
-    # @param cell_index [Integer] The index of the cell
-    def set_cell!(cell, cell_index)
-      @cell = cell
-      @cell_index = cell_index
-    end
-
-    # Each time we run a parse on the input, reset the runtime state starting at the beginning of the file
-    def start!
-      @row_index = @cell_index = nil
-      @line_number = 1
-    end
-
-    # Reset the runtime state starting at the CSV section
-    def start_at_csv!
-      # TODO: isn't the input re-written anyway without the code section? why do we need this?
-      start!
-      @line_number = @length_of_code_section || 1
-    end
-
-    # @return [String]
-    def to_s
-      "Runtime(cell: #{@cell}, row_index: #{@row_index}, cell_index: #{@cell_index})"
-    end
-
-    # Get the current (entity) value of a runtime value
-    #
-    # @param var_id [String, Symbol] The Variable#id  of the variable being resolved.
-    #
-    # @return [Entity]
-    def runtime_value(var_id)
-      if runtime_variable?(var_id)
-        ::CSVPlusPlus::Entities::Builtins::VARIABLES[var_id.to_sym].resolve_fn.call(self)
-      else
-        raise_formula_syntax_error('Undefined variable', var_id)
-      end
-    end
-
-    # Is +var_id+ a runtime variable?  (it's a static variable otherwise)
-    #
-    # @param var_id [String, Symbol] The Variable#id to check if it's a runtime variable
-    #
-    # @return [boolean]
-    def runtime_variable?(var_id)
-      ::CSVPlusPlus::Entities::Builtins::VARIABLES.key?(var_id.to_sym)
-    end
-
-    # Called when an error is encoutered during parsing.  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
-
-    # The currently available input for parsing.  The tmp state will be re-written
-    # between parsing the code section and the CSV section
-    #
-    # @return [String]
-    def input
-      @tmp
-    end
-
-    # We mutate the input over and over. It's ok because it's just a Tempfile
-    #
-    # @param data [String] The data to rewrite our input file to
-    def rewrite_input!(data)
-      @tmp.truncate(0)
-      @tmp.write(data)
-      @tmp.rewind
-    end
-
-    # Clean up the Tempfile we're using for parsing
-    def cleanup!
-      return unless @tmp
-
-      @tmp.close
-      @tmp.unlink
-      @tmp = nil
-    end
-
-    private
-
-    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
-
-    def init_input!(input)
-      lines = (input || '').split(/\s*\n\s*/)
-      @length_of_original_file = lines.length
-      @length_of_code_section = count_code_section_lines(lines)
-      @length_of_csv_section = @length_of_original_file - @length_of_code_section
-
-      # we're gonna take our input file, write it to a tmp file then each
-      # step is gonna mutate that tmp file
-      @tmp = ::Tempfile.new
-      rewrite_input!(input)
+  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 data from a parsed csvpp template.
   #
   # @attr_reader rows [Array<Row>] The +Row+s that comprise this +Template+
-  # @attr_reader scope [Scope] The +Scope+ containing all function and variable references
+  # @attr_reader runtime [Runtime] The +Runtime+ containing all function and variable references
   class Template
-    attr_reader :rows, :scope
+    extend ::T::Sig
 
+    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+
-    # @param scope [Scope] The +Scope+ containing all function and variable references
-    def initialize(rows:, scope:)
-      @scope = scope
+    # @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}, scope: #{@scope})"
+    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_formula_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 +@scope+)
+    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
-        #{@scope.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.2'
+  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