csv_plus_plus 0.1.0 → 0.1.2

data/lib/csv_plus_plus/runtime.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # @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.
+  #
+  # @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)
+    end
+  end
+end

data/lib/csv_plus_plus/scope.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative 'can_define_references'
+require_relative 'entities'
+require_relative 'graph'
+require_relative 'references'
+
+module CSVPlusPlus
+  # A class representing the scope of the current Template and responsible for resolving variables
+  #
+  # @attr_reader functions [Hash<Symbol, Function>] The currently functions defined
+  # @attr_reader runtime [Runtime] The compiler's current runtime
+  # @attr_reader variables [Hash<Symbol, Entity>] The currently defined variables
+  #
+  # rubocop:disable Metrics/ClassLength
+  class Scope
+    include ::CSVPlusPlus::CanDefineReferences
+    # TODO: split out a CanResolveReferences
+
+    attr_reader :functions, :runtime, :variables
+
+    # @param runtime [Runtime]
+    def initialize(runtime:, functions: {}, variables: {})
+      @runtime = runtime
+      @functions = functions
+      @variables = variables
+    end
+
+    # Resolve all values in the ast of the current cell being processed
+    #
+    # @return [Entity]
+    def resolve_cell_value
+      return unless (ast = @runtime.cell&.ast)
+
+      last_round = nil
+      loop do
+        refs = ::CSVPlusPlus::References.extract(ast, self)
+        return ast if refs.empty?
+
+        # TODO: throw an error here instead I think - basically we did a round and didn't make progress
+        return ast if last_round == refs
+
+        ast = resolve_functions(resolve_variables(ast, refs.variables), refs.functions)
+      end
+    end
+
+    # Bind +var_id+ to the current cell (based on where +@runtime+ is currently pointing).
+    #
+    # @param var_id [Symbol] The name of the variable to bind the cell reference to
+    #
+    # @return [CellReference]
+    def bind_variable_to_cell(var_id)
+      ::CSVPlusPlus::Entities::CellReference.from_index(
+        cell_index: runtime.cell_index,
+        row_index: runtime.row_index
+      ).tap do |cell_reference|
+        def_variable(var_id, cell_reference)
+      end
+    end
+
+    # @return [String]
+    def to_s
+      "Scope(functions: #{@functions}, runtime: #{@runtime}, variables: #{@variables})"
+    end
+
+    private
+
+    # Resolve all variable references defined statically in the code section
+    # TODO: experiment with getting rid of this - does it even play correctly with runtime vars?
+    def resolve_static_variables!
+      last_var_dependencies = {}
+      loop do
+        var_dependencies, resolution_order = variable_resolution_order(only_static_vars(variables))
+        return if var_dependencies == last_var_dependencies
+
+        # TODO: make the contract better here
+        @variables = resolve_dependencies(var_dependencies, resolution_order, variables)
+        last_var_dependencies = var_dependencies.clone
+      end
+    end
+
+    def only_static_vars(var_dependencies)
+      var_dependencies.reject { |k| @runtime.runtime_variable?(k) }
+    end
+
+    def resolve_functions(ast, refs)
+      refs.reduce(ast.dup) do |acc, elem|
+        function_replace(acc, elem.id, resolve_function(elem.id))
+      end
+    end
+
+    def resolve_variables(ast, refs)
+      refs.reduce(ast.dup) do |acc, elem|
+        variable_replace(acc, elem.id, resolve_variable(elem.id))
+      end
+    end
+
+    # Make a copy of the AST represented by +node+ and replace +fn_id+ with +replacement+ throughout
+    # rubocop:disable Metrics/MethodLength
+    def function_replace(node, fn_id, replacement)
+      if node.function_call? && node.id == fn_id
+        call_function_or_runtime_value(replacement, node)
+      elsif node.function_call?
+        # not our function, but continue our depth first search on it
+        ::CSVPlusPlus::Entities::FunctionCall.new(
+          node.id,
+          node.arguments.map { |n| function_replace(n, fn_id, replacement) },
+          infix: node.infix
+        )
+      else
+        node
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def resolve_function(fn_id)
+      id = fn_id.to_sym
+      return functions[id] if defined_function?(id)
+
+      ::CSVPlusPlus::Entities::Builtins::FUNCTIONS[id]
+    end
+
+    def call_function_or_runtime_value(function_or_runtime_value, function_call)
+      if function_or_runtime_value.function?
+        call_function(function_or_runtime_value, function_call)
+      else
+        function_or_runtime_value.resolve_fn.call(@runtime, function_call.arguments)
+      end
+    end
+
+    def call_function(function, function_call)
+      i = 0
+      function.arguments.reduce(function.body.dup) do |ast, argument|
+        variable_replace(ast, argument, function_call.arguments[i]).tap do
+          i += 1
+        end
+      end
+    end
+
+    # Make a copy of the AST represented by +node+ and replace +var_id+ with +replacement+ throughout
+    def variable_replace(node, var_id, replacement)
+      if node.function_call?
+        arguments = node.arguments.map { |n| variable_replace(n, var_id, replacement) }
+        # TODO: refactor these places where we copy functions... it's brittle with the kwargs
+        ::CSVPlusPlus::Entities::FunctionCall.new(node.id, arguments, infix: node.infix)
+      elsif node.variable? && node.id == var_id
+        replacement
+      else
+        node
+      end
+    end
+
+    def resolve_variable(var_id)
+      id = var_id.to_sym
+      return variables[id] if defined_variable?(id)
+
+      # this will throw a syntax error if it doesn't exist (which is what we want)
+      @runtime.runtime_value(id)
+    end
+
+    def check_unbound_vars(dependencies, variables)
+      unbound_vars = dependencies.values.flatten - variables.keys
+      return if unbound_vars.empty?
+
+      @runtime.raise_formula_syntax_error('Undefined variables', unbound_vars.map(&:to_s).join(', '))
+    end
+
+    def variable_resolution_order(variables)
+      # we have a hash of variables => ASTs but they might have references to each other, so
+      # we need to interpolate them first (before interpolating the cell values)
+      var_dependencies = ::CSVPlusPlus::Graph.dependency_graph(variables, @runtime)
+      # are there any references that we don't have variables for? (undefined variable)
+      check_unbound_vars(var_dependencies, variables)
+
+      # a topological sort will give us the order of dependencies
+      [var_dependencies, ::CSVPlusPlus::Graph.topological_sort(var_dependencies)]
+      # TODO: don't expose this exception directly to the caller
+    rescue ::TSort::Cyclic
+      @runtime.raise_formula_syntax_error('Cyclic variable dependency detected', var_refs.keys)
+    end
+
+    def resolve_dependencies(var_dependencies, resolution_order, variables)
+      {}.tap do |resolved_vars|
+        # for each var and each dependency it has, build up and mutate resolved_vars
+        resolution_order.each do |var|
+          resolved_vars[var] = variables[var].dup
+
+          var_dependencies[var].each do |dependency|
+            resolved_vars[var] = variable_replace(resolved_vars[var], dependency, variables[dependency])
+          end
+        end
+      end
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/csv_plus_plus/template.rb

@@ -1,23 +1,27 @@
 # 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 rows [Array<Row>] The +Row+s that comprise this +Template+
+  # @attr_reader scope [Scope] The +Scope+ containing all function and variable references
   class Template
-    attr_reader :rows
+    attr_reader :rows, :scope
 
     # @param rows [Array<Row>] The +Row+s that comprise this +Template+
-    def initialize(rows:)
+    # @param scope [Scope] The +Scope+ containing all function and variable references
+    def initialize(rows:, scope:)
+      @scope = scope
       @rows = rows
     end
 
     # @return [String]
     def to_s
-      "Template(rows: #{@rows})"
+      "Template(rows: #{@rows}, scope: #{@scope})"
     end
 
     # Apply any expand= modifiers to the parsed template
+    #
     # @return [Array<Row>]
     def expand_rows!
       expanded_rows = []
@@ -40,12 +44,24 @@ 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_formula_syntax_error(
         'You can only have one infinite expand= (on all others you must specify an amount)',
         infinite_expand_rows[1]
       )
     end
 
+    # Provide a summary of the state of the template (and it's +@scope+)
+    #
+    # @return [String]
+    def verbose_summary
+      # TODO: we can probably include way more stats in here
+      <<~SUMMARY
+        #{@scope.verbose_summary}
+
+        > #{@rows.length} rows to be written
+      SUMMARY
+    end
+
     private
 
     def expand_rows(push_row_fn)

data/lib/csv_plus_plus/validated_modifier.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative 'data_validation'
+require_relative 'modifier'
+
+module CSVPlusPlus
+  # Validates and coerces modifier values as they are parsed.
+  #
+  # Previously this logic was handled in the parser's grammar, but with the introduction of variable binding, the
+  # grammar is no longer context free so we need the parser to be a little looser on what it accepts and validate it
+  # here.  Having this layer is also nice because we can provide better error messages to the user for what went
+  # wrong during the parse.
+  class ValidatedModifier < ::CSVPlusPlus::Modifier
+    # Validates that +border+ is 'all', 'top', 'bottom', 'left' or 'right'.
+    #
+    # @param value [String] The unvalidated user input
+    def border=(value)
+      super(one_of(:border, value, %i[all top bottom left right]))
+    end
+
+    # Validates that +bordercolor+ is a hex color.
+    #
+    # @param value [String] The unvalidated user input
+    def bordercolor=(value)
+      super(color_value(:bordercolor, value))
+    end
+
+    # Validates that +borderstyle+ is 'dashed', 'dotted', 'double', 'solid', 'solid_medium' or 'solid_thick'.
+    #
+    # @param value [String] The unvalidated user input
+    def borderstyle=(value)
+      super(one_of(:borderstyle, value, %i[dashed dotted double solid solid_medium solid_thick]))
+    end
+
+    # Validates that +color+ is a hex color.
+    #
+    # @param value [String] The unvalidated user input
+    def color=(value)
+      super(color_value(:color, value))
+    end
+
+    # Validates that +expand+ is a positive integer.
+    #
+    # @param value [String] The unvalidated user input
+    def expand=(value)
+      super(::CSVPlusPlus::Expand.new(positive_integer(:expand, value)))
+    end
+
+    # Validates that +fontcolor+ is a hex color.
+    #
+    # @param value [String] The unvalidated user input
+    def fontcolor=(value)
+      super(color_value(:fontcolor, value))
+    end
+
+    # Validates that +fontcolor+ is a hex color.
+    def fontfamily=(value)
+      super(matches_regexp(:fontfamily, unquote(value), /^[\w\s]+$/, 'It is not a valid font family.'))
+    end
+
+    # Validates that +fontsize+ is a positive integer
+    #
+    # @param value [String] The unvalidated user input
+    def fontsize=(value)
+      super(positive_integer(:fontsize, value))
+    end
+
+    # Validates that +format+ is 'bold', 'italic', 'strikethrough' or 'underline'.
+    #
+    # @param value [String] The unvalidated user input
+    def format=(value)
+      super(one_of(:format, value, %i[bold italic strikethrough underline]))
+    end
+
+    # Validates that +halign+ is 'left', 'center' or 'right'.
+    #
+    # @param value [String] The unvalidated user input
+    def halign=(value)
+      super(one_of(:halign, value, %i[left center right]))
+    end
+
+    # Validates that +note+ is a quoted string.
+    #
+    # @param value [String] The unvalidated user input
+
+    # Validates that +numberformat+ is 'currency', 'date', 'date_time', 'number', 'percent', 'text', 'time' or
+    # 'scientific'.
+    #
+    # @param value [String] The unvalidated user input
+    def numberformat=(value)
+      super(one_of(:nubmerformat, value, %i[currency date date_time number percent text time scientific]))
+    end
+
+    # Validates that +valign+ is 'top', 'center' or 'bottom'.
+    #
+    # @param value [String] The unvalidated user input
+    def valign=(value)
+      super(one_of(:valign, value, %i[top center bottom]))
+    end
+
+    # Validates that the conditional validating rules are well-formed.
+    #
+    # Pretty much based off of the Google Sheets API spec here:
+    #
+    # @param value [String] The unvalidated user input
+    def validation=(value)
+      super(a_data_validation(:validation, value))
+    end
+
+    # Validates +variable+ is a valid variable identifier.
+    #
+    # @param value [String] The unvalidated user input
+    def var=(value)
+      # TODO: I need a shared definition of what a variable can be (I guess the :ID token)
+      super(matches_regexp(:var, value, /^\w+$/, 'It must be a sequence of letters, numbers and _.').to_sym)
+    end
+
+    private
+
+    # XXX centralize this :(((
+    def unquote(str)
+      # TODO: I'm pretty sure this isn't sufficient and we need to deal with the backslashes
+      str.gsub(/^['\s]*|['\s]*$/, '')
+    end
+
+    def a_data_validation(modifier, value)
+      data_validation = ::CSVPlusPlus::DataValidation.new(value)
+      return data_validation unless data_validation.valid?
+
+      raise_error(modifier, value, message: data_validation.invalid_reason)
+    end
+
+    def color_value(modifier, value)
+      unless ::CSVPlusPlus::Color.valid_hex_string?(value)
+        raise_error(modifier, value, message: 'It must be a 3 or 6 digit hex code.')
+      end
+
+      ::CSVPlusPlus::Color.new(value)
+    end
+
+    def matches_regexp(modifier, value, regexp, message)
+      raise_error(modifier, value, message:) unless value =~ regexp
+      value
+    end
+
+    def one_of(modifier, value, choices)
+      value.downcase.to_sym.tap do |v|
+        raise_error(modifier, value, choices:) unless choices.include?(v)
+      end
+    end
+
+    def positive_integer(modifier, value)
+      Integer(value, 10).tap do |i|
+        raise_error(modifier, value, message: 'It must be positive and greater than 0.') unless i.positive?
+      end
+    rescue ::ArgumentError
+      raise_error(modifier, value, message: 'It must be a valid (whole) number.')
+    end
+
+    def raise_error(modifier, bad_input, choices: nil, message: nil)
+      raise(::CSVPlusPlus::Error::ModifierValidationError.new(modifier, bad_input, choices:, message:))
+    end
+  end
+end

data/lib/csv_plus_plus/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
   public_constant :VERSION
 end

data/lib/csv_plus_plus/writer/file_backer_upper.rb

@@ -1,8 +1,5 @@
 # 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 +23,7 @@ module CSVPlusPlus
 
       private
 
+      # rubocop:disable Metrics/MethodLength
       def attempt_backups
         attempted =
           # rubocop:disable Lint/ConstantResolution
@@ -39,8 +37,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)