csv_plus_plus 0.1.2 → 0.2.0

data/lib/csv_plus_plus/runtime/scope.rb

@@ -0,0 +1,280 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Runtime
+    # Responsible for storing and resolving variables and function references
+    # rubocop:disable Metrics/ClassLength
+    class Scope
+      extend ::T::Sig
+
+      sig { returns(::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Function]) }
+      attr_reader :functions
+
+      sig { returns(::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]) }
+      attr_reader :variables
+
+      sig do
+        params(
+          functions: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Function],
+          variables: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]
+        ).void
+      end
+      # @param functions [Hash<Symbol, Function>] Pre-defined functions
+      # @param variables [Hash<Symbol, Entity>] Pre-defined variables
+      def initialize(functions: {}, variables: {})
+        @functions = functions
+        @variables = variables
+      end
+
+      sig { params(id: ::Symbol, entity: ::CSVPlusPlus::Entities::Entity).returns(::CSVPlusPlus::Entities::Entity) }
+      # Define a (or re-define an existing) variable
+      #
+      # @param id [String, Symbol] The identifier for the variable
+      # @param entity [Entity] The value (entity) the variable holds
+      #
+      # @return [Entity] The value of the variable (+entity+)
+      def def_variable(id, entity)
+        @variables[id] = entity
+      end
+
+      sig { params(vars: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]).void }
+      # Define (or re-define existing) variables
+      #
+      # @param vars [Hash<Symbol, Variable>] Variables to define
+      def def_variables(vars)
+        vars.each { |id, entity| def_variable(id, entity) }
+      end
+
+      sig do
+        params(id: ::Symbol, function: ::CSVPlusPlus::Entities::Function).returns(::CSVPlusPlus::Entities::Function)
+      end
+      # Define a (or re-define an existing) function
+      #
+      # @param id [Symbol] The identifier for the function
+      # @param function [Entities::Function] The defined function
+      #
+      # @return [Entities::Function] The defined function
+      def def_function(id, function)
+        @functions[id.to_sym] = function
+      end
+
+      sig { params(var_id: ::Symbol, position: ::CSVPlusPlus::Runtime::Position).returns(::T::Boolean) }
+      # Variables outside of an ![[expand=...] are always in scope.  If it's defined within an expand then things
+      # get trickier because the variable is only in scope while we're processing cells within that expand.
+      #
+      # @param var_id [Symbol] The variable's identifier that we are checking if it's in scope
+      # @param position [Position]
+      #
+      # @return [boolean]
+      def in_scope?(var_id, position)
+        value = @variables[var_id]
+
+        return false unless value
+
+        expand = value.is_a?(::CSVPlusPlus::Entities::Reference) && value.a1_ref.scoped_to_expand
+        !expand || expand.position_within?(position)
+      end
+
+      sig { returns(::String) }
+      # Provide a summary of the functions and variables compiled (to show in verbose mode)
+      #
+      # @return [::String]
+      def verbose_summary
+        <<~SUMMARY
+          # Code Section Summary
+
+          ## Resolved Variables
+
+          #{variable_summary}
+
+          ## Functions
+
+          #{function_summary}
+        SUMMARY
+      end
+
+      sig do
+        params(
+          position: ::CSVPlusPlus::Runtime::Position,
+          ast: ::CSVPlusPlus::Entities::Entity,
+          refs: ::T::Enumerable[::CSVPlusPlus::Entities::FunctionCall]
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # @param position [Position
+      # @param ast [Entity]
+      # @param refs [Array<FunctionCall>]
+      #
+      # @return [Entity]
+      def resolve_functions(position, ast, refs)
+        refs.reduce(ast.dup) do |acc, elem|
+          function_replace(position, acc, elem.id, resolve_function(elem.id))
+        end
+      end
+
+      sig do
+        params(
+          position: ::CSVPlusPlus::Runtime::Position,
+          ast: ::CSVPlusPlus::Entities::Entity,
+          refs: ::T::Enumerable[::CSVPlusPlus::Entities::Reference]
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # @param position [Position]
+      # @param ast [Entity]
+      # @param refs [Array<Variable>]
+      #
+      # @return [Entity]
+      def resolve_variables(position, ast, refs)
+        refs.reduce(ast.dup) do |acc, elem|
+          next acc unless (id = elem.id)
+
+          variable_replace(acc, id, resolve_variable(position, id))
+        end
+      end
+
+      sig do
+        params(
+          position: ::CSVPlusPlus::Runtime::Position,
+          node: ::CSVPlusPlus::Entities::Entity,
+          fn_id: ::Symbol,
+          replacement: ::T.any(::CSVPlusPlus::Entities::Function, ::CSVPlusPlus::Entities::RuntimeValue)
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # Make a copy of the AST represented by +node+ and replace +fn_id+ with +replacement+ throughout
+      # rubocop:disable Metrics/MethodLength
+      def function_replace(position, node, fn_id, replacement)
+        if node.is_a?(::CSVPlusPlus::Entities::FunctionCall) && node.id == fn_id
+          call_function_or_builtin(position, replacement, node)
+        elsif node.is_a?(::CSVPlusPlus::Entities::FunctionCall)
+          # not our function, but continue our depth first search on it
+          ::CSVPlusPlus::Entities::FunctionCall.new(
+            node.id,
+            node.arguments.map { |n| function_replace(position, n, fn_id, replacement) },
+            infix: node.infix
+          )
+        else
+          node
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      sig do
+        params(fn_id: ::Symbol)
+          .returns(::T.any(::CSVPlusPlus::Entities::Function, ::CSVPlusPlus::Entities::RuntimeValue))
+      end
+      # @param fn_id [Symbol]
+      #
+      # @return [Entities::Function]
+      def resolve_function(fn_id)
+        return ::T.must(@functions[fn_id]) if @functions.key?(fn_id)
+
+        builtin = ::CSVPlusPlus::Entities::Builtins::FUNCTIONS[fn_id]
+        raise(::CSVPlusPlus::Error::FormulaSyntaxError.new('Undefined function', bad_input: fn_id.to_s)) unless builtin
+
+        builtin
+      end
+
+      sig do
+        params(
+          position: ::CSVPlusPlus::Runtime::Position,
+          function_or_builtin: ::T.any(::CSVPlusPlus::Entities::RuntimeValue, ::CSVPlusPlus::Entities::Function),
+          function_call: ::CSVPlusPlus::Entities::FunctionCall
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # @param position [Position]
+      # @param function_or_builtin [Entities::Function, Entities::RuntimeValue]
+      # @param function_call [Entities::FunctionCall]
+      #
+      # @return [Entities::Entity]
+      def call_function_or_builtin(position, function_or_builtin, function_call)
+        if function_or_builtin.is_a?(::CSVPlusPlus::Entities::RuntimeValue)
+          function_or_builtin.call(position, function_call.arguments)
+        else
+          call_function(function_or_builtin, function_call)
+        end
+      end
+
+      sig do
+        params(
+          function: ::CSVPlusPlus::Entities::Function,
+          function_call: ::CSVPlusPlus::Entities::FunctionCall
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # Since functions are just built up from existing functions, a "call" is effectively replacing the variable
+      # references in the +@body+ with the ones being passed as arguments
+      #
+      # @param function [Entities::Function] The function being called
+      # @param function_call [Entities::FunctionCall] The actual call of the function
+      #
+      # @return [Entities::Entity]
+      def call_function(function, function_call)
+        i = 0
+        function.arguments.reduce(function.body.dup) do |ast, argument|
+          variable_replace(ast, argument, ::T.must(function_call.arguments[i])).tap do
+            i += 1
+          end
+        end
+      end
+
+      sig do
+        params(
+          node: ::CSVPlusPlus::Entities::Entity,
+          var_id: ::Symbol,
+          replacement: ::CSVPlusPlus::Entities::Entity
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      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.is_a?(::CSVPlusPlus::Entities::FunctionCall)
+          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.is_a?(::CSVPlusPlus::Entities::Reference) && node.id == var_id
+          replacement
+        else
+          node
+        end
+      end
+
+      sig do
+        params(position: ::CSVPlusPlus::Runtime::Position, var_id: ::Symbol).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # @param position [Position]
+      # @param var_id [Symbol]
+      #
+      # @return [Entities::Entity]
+      def resolve_variable(position, var_id)
+        return ::T.must(@variables[var_id]) if @variables.key?(var_id)
+
+        unless ::CSVPlusPlus::Entities::Builtins.builtin_variable?(var_id)
+          raise(::CSVPlusPlus::Error::FormulaSyntaxError.new('Undefined variable', bad_input: var_id.to_s))
+        end
+
+        ::T.must(::CSVPlusPlus::Entities::Builtins::VARIABLES[var_id]).call(position, [])
+      end
+
+      sig { returns(::String) }
+      # Create a summary of all currently defined variables
+      #
+      # @return [String]
+      def variable_summary
+        return '(no variables defined)' if @variables.empty?
+
+        @variables.map { |k, v| "#{k} := #{v}" }
+                  .join("\n")
+      end
+
+      sig { returns(::String) }
+      # Create a summary of all currently defined functions
+      #
+      # @return [String]
+      def function_summary
+        return '(no functions defined)' if @functions.empty?
+
+        @functions.map { |k, f| "#{k}: #{f}" }
+                  .join("\n")
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/csv_plus_plus/runtime.rb

@@ -1,199 +1,42 @@
+# typed: strict
 # frozen_string_literal: true
 
+require_relative './runtime/graph'
+require_relative './runtime/position'
+require_relative './runtime/references'
+require_relative './runtime/runtime'
+require_relative './runtime/scope'
+
 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,
+        position: ::T.nilable(::CSVPlusPlus::Runtime::Position),
+        scope: ::T.nilable(::CSVPlusPlus::Runtime::Scope)
+      ).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 position [Position, nil]
+    # @param scope [Scope, nil]
+    #
+    # @return [Runtime::Runtime]
+    def self.new(source_code:, position: nil, scope: nil)
+      position ||= ::CSVPlusPlus::Runtime::Position.new(source_code.input)
+      ::CSVPlusPlus::Runtime::Runtime.new(source_code:, position:, scope:)
     end
   end
 end

data/lib/csv_plus_plus/source_code.rb

@@ -0,0 +1,71 @@
+# 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(::Pathname) }
+    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(filename: ::String, input: ::T.nilable(::String)).void }
+    # @param filename [::String] The name of the file the source came from.
+    def initialize(filename, input: nil)
+      @filename = ::T.let(::Pathname.new(filename), ::Pathname)
+      @input = ::T.let(input || read_file, ::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 { returns(::String) }
+    def read_file
+      raise(::CSVPlusPlus::Error::CLIError, "Source file #{@filename} does not exist") unless ::File.exist?(@filename)
+
+      ::File.read(@filename)
+    end
+
+    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