csv_plus_plus 0.0.5 → 0.1.0

data/lib/csv_plus_plus/language/compiler.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require 'benchmark'
 require 'csv'
+# TODO: move some of these out to csv_plus_plus.rb
 require_relative '../cell'
 require_relative '../modifier'
 require_relative '../modifier.tab'
 require_relative '../row'
 require_relative '../template'
+require_relative 'benchmarked_compiler'
 require_relative 'code_section.tab'
 require_relative 'entities'
 require_relative 'runtime'
@@ -14,59 +15,73 @@ require_relative 'scope'
 
 module CSVPlusPlus
   module Language
-    # Encapsulates the parsing and building of objects (+Template+ -> +Row+ -> +Cell+).
-    # Variable resolution is delegated to the +Scope+
-    # rubocop:disable Metrics/ClassLength
+    # Encapsulates the parsing and building of objects (+Template+ -> +Row+ -> +Cell+). Variable resolution is delegated
+    # to the +Scope+
+    #
+    # @attr_reader options [Options] The +Options+ to compile with
+    # @attr_reader runtime [Runtime] The runtime execution
+    # @attr_reader scope [Scope] +Scope+ for variable resolution
     class Compiler
       attr_reader :timings, :benchmark, :options, :runtime, :scope
 
       # Create a compiler and make sure it gets cleaned up
-      def self.with_compiler(input:, filename:, options:, &block)
-        runtime = ::CSVPlusPlus::Language::Runtime.new(filename:, input:)
-
+      #
+      # @param runtime [Runtime] The initial +Runtime+ for the compiler
+      # @param options [Options]
+      def self.with_compiler(runtime:, options:, &block)
+        compiler = new(options:, runtime:)
         if options.verbose
-          compiler_with_timings(runtime:, options:) do |c|
+          ::CSVPlusPlus::Language::BenchmarkedCompiler.with_benchmarks(compiler) do |c|
             block.call(c)
           end
         else
-          yield(new(runtime:, options:))
+          yield(compiler)
         end
       ensure
         runtime.cleanup!
       end
 
-      # Create a compiler that can time each of it's stages
-      def self.compiler_with_timings(options:, runtime:, &block)
-        ::Benchmark.benchmark(::Benchmark::CAPTION, 25, ::Benchmark::FORMAT, '> Total') do |x|
-          compiler = new(options:, runtime:, benchmark: x)
-          block.call(compiler)
-          [compiler.timings.reduce(:+)]
-        end
-      end
-
-      # initialize
-      def initialize(runtime:, options:, scope: nil, benchmark: nil)
+      # @param runtime [Runtime]
+      # @param options [Options]
+      # @param scope [Scope, nil]
+      def initialize(runtime:, options:, scope: nil)
         @options = options
         @runtime = runtime
         @scope = scope || ::CSVPlusPlus::Language::Scope.new(runtime:)
-        @benchmark = benchmark
-        @timings = [] if benchmark
       end
 
-      # Parse an entire template and return a +::CSVPlusPlus::Template+ instance
-      def parse_template
+      # Write the compiled results
+      def outputting!
+        @runtime.start_at_csv!
+        yield
+      end
+
+      # Compile a template and return a +::CSVPlusPlus::Template+ instance ready to be written with a +Writer+
+      #
+      # @return [Template]
+      def compile_template
         parse_code_section!
         rows = parse_csv_section!
 
-        ::CSVPlusPlus::Template.new(rows:, scope: @scope).tap do |t|
+        ::CSVPlusPlus::Template.new(rows:).tap do |t|
           t.validate_infinite_expands(@runtime)
           expanding { t.expand_rows! }
           resolve_all_cells!(t)
         end
       end
 
-      # parses the input file and returns a +CodeSection+
+      # @return [String]
+      def to_s
+        "Compiler(options: #{@options}, runtime: #{@runtime}, scope: #{@scope})"
+      end
+
+      protected
+
+      # Parses the input file and returns a +CodeSection+
+      #
+      # @return [CodeSection]
       def parse_code_section!
+        @runtime.start!
         parsing_code_section do |input|
           code_section, csv_section = ::CSVPlusPlus::Language::CodeSectionParser.new.parse(input, self)
           # TODO: infer a type
@@ -82,20 +97,48 @@ module CSVPlusPlus
         @scope.code_section
       end
 
-      # workflow when parsing csv
+      # Parse the CSV section and return an array of +Row+s
+      #
+      # @return [Array<Row>]
       def parse_csv_section!
-        workflow(stage: 'Parsing CSV section') do
-          @runtime.map_rows(::CSV.new(runtime.input)) do |csv_row|
-            parse_row(csv_row)
-          end
+        @runtime.start_at_csv!
+        @runtime.map_rows(::CSV.new(runtime.input)) do |csv_row|
+          parse_row(csv_row)
         end
       ensure
         # we're done with the file and everything is in memory
         @runtime.cleanup!
       end
 
+      # Iterates through each cell of each row and resolves it's variable and function references.
+      #
+      # @param template [Template]
+      # @return [Array<Entity>]
+      def resolve_all_cells!(template)
+        @runtime.start_at_csv!
+        @runtime.map_rows(template.rows, cells_too: true) do |cell|
+          cell.ast = @scope.resolve_cell_value if cell.ast
+        end
+      end
+
+      # Expanding rows
+      def expanding
+        @runtime.start_at_csv!
+        yield
+      end
+
+      private
+
+      def parsing_code_section
+        csv_section = yield(@runtime.input.read)
+        @runtime.rewrite_input!(csv_section)
+      end
+
       # Using the current +@runtime+ and the given +csv_row+ parse it into a +Row+ of +Cell+s
       # +csv_row+ should have already been run through a CSV parser and is an array of strings
+      #
+      # @param csv_row [Array<Array<String>>]
+      # @return [Row]
       def parse_row(csv_row)
         row_modifier = ::CSVPlusPlus::Modifier.new(row_level: true)
 
@@ -109,61 +152,6 @@ module CSVPlusPlus
 
         ::CSVPlusPlus::Row.new(@runtime.row_index, cells, row_modifier)
       end
-
-      # workflow when resolving the values of all cells
-      def resolve_all_cells!(template)
-        workflow(stage: 'Resolving each cell') do
-          @runtime.map_rows(template.rows, cells_too: true) do |cell|
-            cell.ast = @scope.resolve_cell_value if cell.ast
-          end
-        end
-      end
-
-      # workflow when writing results
-      def outputting!(&block)
-        workflow(stage: 'Writing the spreadsheet') do
-          block.call
-        end
-      end
-
-      # to_s
-      def to_s
-        "Compiler(options: #{@options}, runtime: #{@runtime}, scope: #{@scope})"
-      end
-
-      private
-
-      # workflow when parsing the code section
-      def parsing_code_section(&block)
-        workflow(
-          stage: 'Parsing code section',
-          processing_code_section: true
-        ) do
-          csv_section = block.call(@runtime.input.read)
-          @runtime.rewrite_input!(csv_section)
-        end
-      end
-
-      # workflow when expanding rows
-      def expanding(&block)
-        workflow(stage: 'Expanding rows') do
-          block.call
-        end
-      end
-
-      def workflow(stage:, processing_code_section: false, &block)
-        @runtime.init!(processing_code_section ? 1 : (@runtime.length_of_code_section || 1))
-
-        ret = nil
-        if @benchmark
-          @timings << @benchmark.report(stage) { ret = block.call }
-        else
-          ret = block.call
-        end
-
-        ret
-      end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/csv_plus_plus/language/entities/boolean.rb

@@ -6,10 +6,11 @@ module CSVPlusPlus
   module Language
     module Entities
       # A boolean value
+      #
+      # @attr_reader value [true, false]
       class Boolean < Entity
         attr_reader :value
 
-        # initialize
         # @param value [String, Boolean]
         def initialize(value)
           super(:boolean)
@@ -22,7 +23,7 @@ module CSVPlusPlus
           @value.to_s.upcase
         end
 
-        # @return [Boolean]
+        # @return [boolean]
         def ==(other)
           super && value == other.value
         end

data/lib/csv_plus_plus/language/entities/cell_reference.rb

@@ -5,21 +5,28 @@ require_relative './entity'
 module CSVPlusPlus
   module Language
     module Entities
-      ##
       # A reference to a cell
+      #
+      # @attr_reader cell_reference [String] The cell reference in A1 format
       class CellReference < Entity
         attr_reader :cell_reference
 
-        # initialize
+        # @param cell_reference [String] The cell reference in A1 format
         def initialize(cell_reference)
           super(:cell_reference)
+
           @cell_reference = cell_reference
         end
 
-        # to_s
+        # @return [String]
         def to_s
           @cell_reference
         end
+
+        # @return [Boolean]
+        def ==(other)
+          super && @cell_reference == other.cell_reference
+        end
       end
     end
   end

data/lib/csv_plus_plus/language/entities/entity.rb

@@ -6,22 +6,28 @@ module CSVPlusPlus
   module Language
     module Entities
       # A basic building block of the abstract syntax tree (AST)
+      #
+      # @attr_reader id [Symbol] The identifier of the entity.  For functions this is the function name,
+      #   for variables it's the variable name
+      # @attr_reader type [Symbol] The type of the entity.  Valid values are defined in +::CSVPlusPlus::Language::Types+
       class Entity
         attr_reader :id, :type
 
-        # @param type [String, Symbol]
-        # @param id [String]
+        # @param type [::String, Symbol]
+        # @param id [::String, nil]
         def initialize(type, id: nil)
           @type = type.to_sym
           @id = id.downcase.to_sym if id
         end
 
-        # @return [Boolean]
+        # @return [boolean]
         def ==(other)
           self.class == other.class && @type == other.type && @id == other.id
         end
 
         # Respond to predicates that correspond to types like #boolean?, #string?, etc
+        #
+        # @param method_name [Symbol] The +method_name+ to respond to
         def method_missing(method_name, *_arguments)
           if method_name =~ /^(\w+)\?$/
             t = ::Regexp.last_match(1)
@@ -32,7 +38,10 @@ module CSVPlusPlus
         end
 
         # Respond to predicates by type (entity.boolean?, entity.string?, etc)
-        # @return [Boolean]
+        #
+        # @param method_name [Symbol] The +method_name+ to respond to
+        #
+        # @return [boolean]
         def respond_to_missing?(method_name, *_arguments)
           (method_name =~ /^(\w+)\?$/ && a_type?(::Regexp.last_match(1))) || super
         end
@@ -44,19 +53,22 @@ module CSVPlusPlus
         end
       end
 
-      # An entity that can take other entities as arguments
+      # An entity that can take other entities as arguments.  Current use cases for this
+      # are function calls and function definitions
+      #
+      # @attr_reader arguments [Array<Entity>] The arguments supplied to this entity.
       class EntityWithArguments < Entity
         attr_reader :arguments
 
-        # @param type [String, Symbol]
-        # @param id [String]
+        # @param type [::String, Symbol]
+        # @param id [::String]
         # @param arguments [Array<Entity>]
         def initialize(type, id: nil, arguments: [])
           super(type, id:)
           @arguments = arguments
         end
 
-        # @return [Boolean]
+        # @return [boolean]
         def ==(other)
           super && @arguments == other.arguments
         end

data/lib/csv_plus_plus/language/entities/function.rb

@@ -6,24 +6,26 @@ module CSVPlusPlus
   module Language
     module Entities
       # A function definition
+      #
+      # @attr_reader body [Entity] The body of the function.  +body+ can contain variable references
+      # from +@arguments+
       class Function < EntityWithArguments
         attr_reader :body
 
-        # Create a function
         # @param id [Symbool, String] the name of the function - what it will be callable by
-        # @param arguments [Array(Symbol)]
+        # @param arguments [Array<Symbol>]
         # @param body [Entity]
         def initialize(id, arguments, body)
           super(:function, id:, arguments: arguments.map(&:to_sym))
           @body = body
         end
 
-        # to_s
+        # @return [String]
         def to_s
           "def #{@id.to_s.upcase}(#{arguments_to_s}) #{@body}"
         end
 
-        # ==
+        # @return [boolean]
         def ==(other)
           super && @body == other.body
         end

data/lib/csv_plus_plus/language/entities/function_call.rb

@@ -5,17 +5,18 @@ module CSVPlusPlus
     module Entities
       # A function call
       class FunctionCall < EntityWithArguments
-        # initialize
+        # @param id [String] The name of the function
+        # @param arguments [Array<Entity>] The arguments to the function
         def initialize(id, arguments)
           super(:function_call, id:, arguments:)
         end
 
-        # to_s
+        # @return [String]
         def to_s
           "#{@id.to_s.upcase}(#{arguments_to_s})"
         end
 
-        # ==
+        # @return [boolean]
         def ==(other)
           super && @id == other.id
         end

data/lib/csv_plus_plus/language/entities/number.rb

@@ -3,14 +3,16 @@
 module CSVPlusPlus
   module Language
     module Entities
-      ##
       # A number value
+      #
+      # @attr_reader value [Numeric] The parsed number value
       class Number < Entity
         attr_reader :value
 
-        # initialize
+        # @param value [String, Numeric] Either a +String+ that looks like a number, or an already parsed Numeric
         def initialize(value)
           super(:number)
+
           @value =
             if value.instance_of?(::String)
               value.include?('.') ? Float(value) : Integer(value, 10)
@@ -19,12 +21,12 @@ module CSVPlusPlus
             end
         end
 
-        # to_s
+        # @return [String]
         def to_s
           @value.to_s
         end
 
-        # ==
+        # @return [boolean]
         def ==(other)
           super && value == other.value
         end

data/lib/csv_plus_plus/language/entities/runtime_value.rb

@@ -3,21 +3,22 @@
 module CSVPlusPlus
   module Language
     module Entities
-      ##
-      # A runtime value
-      #
-      # These are values which can be materialized at any point via the +resolve_fn+
+      # A runtime value. These are values which can be materialized at any point via the +resolve_fn+
       # which takes an ExecutionContext as a param
+      #
+      # @attr_reader resolve_fn [lambda] A lambda that is called when the runtime value is resolved
       class RuntimeValue < Entity
-        attr_reader :resolve_fn
+        attr_reader :arguments, :resolve_fn
 
-        # initialize
-        def initialize(resolve_fn)
+        # @param resolve_fn [lambda] A lambda that is called when the runtime value is resolved
+        def initialize(resolve_fn, arguments: nil)
           super(:runtime_value)
+
+          @arguments = arguments
           @resolve_fn = resolve_fn
         end
 
-        # to_s
+        # @return [String]
         def to_s
           '(runtime_value)'
         end

data/lib/csv_plus_plus/language/entities/string.rb

@@ -3,23 +3,25 @@
 module CSVPlusPlus
   module Language
     module Entities
-      ##
       # A string value
+      #
+      # @attr_reader value [String]
       class String < Entity
         attr_reader :value
 
-        # initialize
+        # @param value [String] The string that has been parsed out of the template
         def initialize(value)
           super(:string)
+
           @value = value.gsub(/^"|"$/, '')
         end
 
-        # to_s
+        # @return [String]
         def to_s
           "\"#{@value}\""
         end
 
-        # ==
+        # @return [boolean]
         def ==(other)
           super && value == other.value
         end

data/lib/csv_plus_plus/language/references.rb

@@ -6,10 +6,19 @@ require_relative './scope'
 module CSVPlusPlus
   module Language
     # References in an AST that need to be resolved
+    #
+    # @attr functions [Array<Entities::Function>] Functions references
+    # @attr variables [Array<Entities::Variable>] Variable references
     class References
       attr_accessor :functions, :variables
 
-      # Extract references from an AST.  And return them in a new +References+ object
+      # Extract references from an AST and return them in a new +References+ object
+      #
+      # @param ast [Entity] An +Entity+ to do a depth first search on for references.  Entities can be
+      #   infinitely deep because they can contain other function calls as params to a function call
+      # @param code_section [CodeSection] The +CodeSection+ containing all currently defined functions
+      #
+      # @return [References]
       def self.extract(ast, code_section)
         new.tap do |refs|
           ::CSVPlusPlus::Graph.depth_first_search(ast) do |node|
@@ -22,8 +31,14 @@ module CSVPlusPlus
       end
 
       # Is the node a resolvable reference?
+      #
+      # @param node [Entity] The node to check if it's resolvable
+      #
+      # @return [boolean]
+      # TODO: move this into the Entity subclasses
       def self.function_reference?(node, code_section)
-        node.function_call? && (code_section.defined_function?(node.id) || ::BUILTIN_FUNCTIONS.key?(node.id))
+        node.function_call? && (code_section.defined_function?(node.id) \
+                                || ::CSVPlusPlus::Language::Builtins::FUNCTIONS.key?(node.id))
       end
 
       private_class_method :function_reference?
@@ -34,17 +49,19 @@ module CSVPlusPlus
         @variables = []
       end
 
-      # are there any references to be resolved?
+      # Are there any references to be resolved?
+      #
+      # @return [boolean]
       def empty?
         @functions.empty? && @variables.empty?
       end
 
-      # to_s
+      # @return [String]
       def to_s
         "References(functions: #{@functions}, variables: #{@variables})"
       end
 
-      # ==
+      # @return [boolean]
       def ==(other)
         @functions == other.functions && @variables == other.variables
       end