csv_plus_plus 0.0.5 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4f5c9b5a342102fa8e1c31b319fb05f19ad55278bc633435129254b5b2511a8
-  data.tar.gz: 0c2656d4d7b22d0b3b3311745ed5a70b789277c622f0f2d09d2b8a144de71a8d
+  metadata.gz: 0a93c3ee93f2320dc717ee330c55cd3f300cfa4d155a4502b9a433cdafdcc389
+  data.tar.gz: aa95dca43a374d57f2217030e0aefef680341549613b0388cb5df1122cb5f815
 SHA512:
-  metadata.gz: 90965e2275cc7988f4054b59e30523cd645b21c1adb89797828e86a767217b09ac174bbc17094604dd608b93defd79f4c9a74ccf7e2f20dd17995f8c1b5dadac
-  data.tar.gz: 291011896232e88a7bd0e252887459986812d2877c1d0383458250e1c30cf735d8b2bdaf5dd759f44fa5b8b33b08f74d780df7960622ab774e9f6d856628508f
+  metadata.gz: 19a827c9a5fc8f0f9fe9d58c4e6b85de821c9e09627465673c2813c2690fadc886c7d8f24e3da5402783b27347a79f7832b13c82abe4e204026d12839d6f4691
+  data.tar.gz: b157b531d9ae9e2fda9c93ed466976deacfe639b1fbc1527b60c706be9d97792946341a767f00c32b6d35cbc6e388711980767d9ef6b5c20b4a2f44ebe7fb121

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+
+## v0.1.0
+
+- revamp of builtin functions
+
+- docs & tests
+
 ## v0.0.5
 
 - Support the --backup/-b option

data/README.md

@@ -1,4 +1,5 @@
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-community-brightgreen.svg)](https://rubystyle.guide)
+[![Gem Version](https://badge.fury.io/rb/csv_plus_plus.svg)](https://badge.fury.io/rb/csv_plus_plus)
 
 # csv++
 

data/lib/csv_plus_plus/cell.rb

@@ -4,21 +4,33 @@ require_relative './language/cell_value.tab'
 require_relative './modifier'
 
 module CSVPlusPlus
-  ##
   # A cell of a template
+  #
+  # @attr ast [Entity]
+  # @attr row_index [Integer] The cell's row index (starts at 0)
+  # @attr_reader index [Integer] The cell's index (starts at 0)
+  # @attr_reader modifier [Modifier] The modifier for this cell
   class Cell
     attr_accessor :ast, :row_index
     attr_reader :index, :modifier
 
-    # Parse a +value+ into a Cell object.  The +value+ should already have been through
-    # a CSV parser
+    # Parse a +value+ into a Cell object.
+    #
+    # @param value [String] A string value which should already have been processed through a CSV parser
+    # @param runtime [Runtime]
+    # @param modifier [Modifier]
+    #
+    # @return [Cell]
     def self.parse(value, runtime:, modifier:)
       new(value:, row_index: runtime.row_index, index: runtime.cell_index, modifier:).tap do |c|
         c.ast = ::CSVPlusPlus::Language::CellValueParser.new.parse(value, runtime)
       end
     end
 
-    # initialize
+    # @param row_index [Integer] The cell's row index (starts at 0)
+    # @param index [Integer] The cell's index (starts at 0)
+    # @param value [String] A string value which should already have been processed through a CSV parser
+    # @param modifier [Modifier] A modifier to apply to this cell
     def initialize(row_index:, index:, value:, modifier:)
       @value = value
       @modifier = modifier
@@ -26,25 +38,29 @@ module CSVPlusPlus
       @row_index = row_index
     end
 
-    # The value (cleaned up some)
+    # The +@value+ (cleaned up some)
+    #
+    # @return [String]
     def value
       return if @value.nil? || @value.strip.empty?
 
       @value.strip
     end
 
-    # to_s
+    # @return [String]
     def to_s
       "Cell(index: #{@index}, row_index: #{@row_index}, value: #{@value}, modifier: #{@modifier})"
     end
 
     # A compiled final representation of the cell.  This can only happen after all cell have had
     # variables and functions resolved.
+    #
+    # @return [String]
     def to_csv
       return value unless @ast
 
-      # This looks really simple but we're relying on each node of the AST to define #to_s and calling
-      # this at the top will recursively print the tree
+      # This looks really simple but we're relying on each node of the AST to define #to_s such that calling
+      # this at the top will recursively print the tree (as a well-formatted spreadsheet formula)
       "=#{@ast}"
     end
   end

data/lib/csv_plus_plus/cli.rb

@@ -4,27 +4,32 @@ require 'optparse'
 
 module CSVPlusPlus
   # Handle running the application with the given CLI flags
+  #
+  # @attr options [Options, nil] The parsed CLI options
   class CLI
-    # handle any CLI flags and launch the compiler
+    attr_accessor :options
+
+    # Handle CLI flags and launch the compiler
+    #
+    # @return [CLI]
     def self.launch_compiler!
       cli = new
-      cli.compile!
+      cli.parse_options!
+      cli.main
     rescue ::StandardError => e
       cli.handle_error(e)
       exit(1)
     end
 
-    # initialize
-    def initialize
-      parse_options!
-    end
-
-    # compile the given template, using the given CLI flags
-    def compile!
+    # Compile the given template using the given CLI flags
+    def main
+      parse_options! unless @options
       ::CSVPlusPlus.apply_template_to_sheet!(::ARGF.read, ::ARGF.filename, @options)
     end
 
-    # (nicely) handle a given error.  how it's handled depends on if it's our error and if @options.verbose
+    # Nicely handle a given error.  How it's handled depends on if it's our error and if @options.verbose
+    #
+    # @param error [CSVPlusPlus::Error, Google::Apis::ClientError, StandardError]
     def handle_error(error)
       case error
       when ::CSVPlusPlus::Error
@@ -37,6 +42,20 @@ module CSVPlusPlus
       end
     end
 
+    # Handle the supplied command line options, setting +@options+ or throw an error if anything is invalid
+    def parse_options!
+      @options = ::CSVPlusPlus::Options.new
+      option_parser.parse!
+      validate_options
+    rescue ::OptionParser::InvalidOption => e
+      raise(::CSVPlusPlus::Error, e.message)
+    end
+
+    # @return [String]
+    def to_s
+      "CLI(options: #{options})"
+    end
+
     private
 
     def handle_internal_error(error)
@@ -54,12 +73,6 @@ module CSVPlusPlus
       warn("#{error.status_code} Error making Google API request [#{error.message}]: #{error.body}")
     end
 
-    def parse_options!
-      @options = ::CSVPlusPlus::Options.new
-      option_parser.parse!
-      validate_options
-    end
-
     def validate_options
       error_message = @options.validate
       return if error_message.nil?

data/lib/csv_plus_plus/cli_flag.rb

@@ -4,10 +4,18 @@ require_relative './google_options'
 
 module CSVPlusPlus
   # Individual CLI flags that a user can supply
+  #
+  # @attr_reader short_flag [String] A definition of the short/single-character flag
+  # @attr_reader long_flag [String] A definition of the long/word-based flag
+  # @attr_reader description [String] A description of what the flag does
+  # @attr_reader handler [Proc(Options, String)] A proc which is called to handle when this flag is seen
   class CliFlag
     attr_reader :short_flag, :long_flag, :description, :handler
 
-    # initialize
+    # @param short_flag [String] A definition of the short/single-character flag
+    # @param long_flag [String] A definition of the long/word-based flag
+    # @param description [String] A description of what the flag does
+    # @param handler [Proc(Options, String)] A proc which is called to handle when this flag is seen
     def initialize(short_flag, long_flag, description, handler)
       @short_flag = short_flag
       @long_flag = long_flag
@@ -15,7 +23,7 @@ module CSVPlusPlus
       @handler = handler
     end
 
-    # to_s
+    # @return [String]
     def to_s
       "#{@short_flag}, #{@long_flag}  #{@description}"
     end

data/lib/csv_plus_plus/code_section.rb

@@ -4,44 +4,63 @@ require_relative './language/code_section.tab'
 require_relative './language/entities'
 
 module CSVPlusPlus
-  ##
   # A representation of the code section part of a template (the variable and function definitions)
+  #
+  # @attr variables [Hash<Symbol, Variable>] All defined variables
+  # @attr_reader functions [Hash<Symbol, Function>] All defined functions
   class CodeSection
     attr_reader :functions
     attr_accessor :variables
 
-    # initialize
+    # @param variables [Hash<Symbol, Variable>] Initial variables
+    # @param functions [Hash<Symbol, Variable>] Initial functions
     def initialize(variables: {}, functions: {})
       @variables = variables
       @functions = functions
     end
 
     # 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
     def def_variable(id, entity)
       @variables[id.to_sym] = entity
     end
 
     # Define (or re-define existing) variables
+    #
+    # @param variables [Hash<Symbol, Variable>] Variables to define
     def def_variables(variables)
       variables.each { |id, entity| def_variable(id, entity) }
     end
 
     # Define a (or re-define an existing) function
+    #
+    # @param id [String, Symbol] The identifier for the function
+    # @param entity [Entities::Function] The defined function
     def def_function(id, entity)
       @functions[id.to_sym] = entity
     end
 
     # Is the variable defined?
+    #
+    # @param var_id [Symbol, String] The identifier of the variable
+    #
+    # @return [boolean]
     def defined_variable?(var_id)
       @variables.key?(var_id.to_sym)
     end
 
     # Is the function defined?
+    #
+    # @param fn_id [Symbol, String] The identifier of the function
+    #
+    # @return [boolean]
     def defined_function?(fn_id)
       @functions.key?(fn_id.to_sym)
     end
 
-    # to_s
+    # @return [String]
     def to_s
       "CodeSection(functions: #{@functions}, variables: #{@variables})"
     end

data/lib/csv_plus_plus/color.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  # A color value
+  # A color value parsed into it's respective components
+  #
+  # attr_reader blue_hex [String] The blue value in hex ("FF", "00", "AF", etc)
+  # attr_reader green_hex [String] The green value in hex ("FF", "00", "AF", etc)
+  # attr_reader red_hex [String] The red value in hex ("FF", "00", "AF", etc)
   class Color
     attr_reader :red_hex, :green_hex, :blue_hex
 
     # create an instance from a string like "#FFF" or "#FFFFFF"
+    #
+    # @param hex_string [String] The hex string input to parse
     def initialize(hex_string)
       @red_hex, @green_hex, @blue_hex = hex_string
                                         .gsub(/^#?/, '')
@@ -15,31 +21,39 @@ module CSVPlusPlus
     end
 
     # The percent (decimal between 0-1) of red
+    #
+    # @return [Numeric]
     def red_percent
       hex_to_percent(@red_hex)
     end
 
     # The percent (decimal between 0-1) of green
+    #
+    # @return [Numeric]
     def green_percent
       hex_to_percent(@green_hex)
     end
 
     # The percent (decimal between 0-1) of blue
+    #
+    # @return [Numeric]
     def blue_percent
       hex_to_percent(@blue_hex)
     end
 
-    # to_hex
+    # Create a hex representation of the color (without a '#')
+    #
+    # @return [String]
     def to_hex
       [@red_hex, @green_hex, @blue_hex].join
     end
 
-    # to_s
+    # @return [String]
     def to_s
       "Color(r: #{@red_hex}, g: #{@green_hex}, b: #{@blue_hex})"
     end
 
-    # ==
+    # @return [boolean]
     def ==(other)
       other.is_a?(self.class) &&
         other.red_hex == @red_hex &&
@@ -50,7 +64,7 @@ module CSVPlusPlus
     private
 
     def hex_to_percent(hex)
-      hex.to_i(16) / 255
+      hex.to_i(16) / 255.0
     end
   end
 end

data/lib/csv_plus_plus/google_options.rb

@@ -2,9 +2,13 @@
 
 module CSVPlusPlus
   # The Google-specific options a user can supply
+  #
+  # attr sheet_id [String] The ID of the Google Sheet to write to
   GoogleOptions =
     ::Struct.new(:sheet_id) do
-      # Return a string with a verbose description of what we're doing with the options
+      # Format a string with a verbose description of what we're doing with the options
+      #
+      # @return [String]
       def verbose_summary
         <<~SUMMARY
           ## Google Sheets Options
@@ -13,7 +17,7 @@ module CSVPlusPlus
         SUMMARY
       end
 
-      # to_s
+      # @return [String]
       def to_s
         "GoogleOptions(sheet_id: #{sheet_id})"
       end

data/lib/csv_plus_plus/graph.rb

@@ -3,7 +3,6 @@
 require 'tsort'
 
 module CSVPlusPlus
-  ##
   # Graph ordering and searching functions
   module Graph
     # Get a list of all variables references in a given +ast+

data/lib/csv_plus_plus/language/ast_builder.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative './entities'
+
+module CSVPlusPlus
+  module Language
+    # Some helpful functions that can be mixed into a class to help building ASTs
+    module ASTBuilder
+      # Let the current class have functions which can build a given entity by calling it's type.  For example
+      # +number(1)+, +variable(:foo)+
+      #
+      # @param method_name [Symbol] The +method_name+ to respond to
+      # @param arguments [] The arguments to create the entity with
+      #
+      # @return [Entity, #super]
+      def method_missing(method_name, *arguments)
+        entity_class = ::CSVPlusPlus::Language::TYPES[method_name.to_sym]
+        return super unless entity_class
+
+        entity_class.new(*arguments)
+      end
+
+      # Let the current class have functions which can build a given entity by calling it's type.  For example
+      # +number(1)+, +variable(:foo)+
+      #
+      # @param method_name [Symbol] The +method_name+ to respond to
+      # @param arguments [] The arguments to create the entity with
+      #
+      # @return [Boolean, #super]
+      def respond_to_missing?(method_name, *_arguments)
+        ::CSVPlusPlus::Language::TYPES.include?(method_name.to_sym) || super
+      end
+
+      # Turns index-based/X,Y coordinates into a A1 format
+      #
+      # @param row_index [Integer]
+      # @param cell_index [Integer]
+      #
+      # @return [String]
+      def ref(row_index: nil, cell_index: nil)
+        return unless row_index || cell_index
+
+        rowref = row_index ? (row_index + 1).to_s : ''
+        cellref = cell_index ? cell_ref(cell_index) : ''
+        cell_reference([cellref, rowref].join)
+      end
+
+      private
+
+      ALPHA = ('A'..'Z').to_a.freeze
+      private_constant :ALPHA
+
+      def cell_ref(cell_index)
+        c = cell_index.dup
+        ref = ''
+
+        while c >= 0
+          # rubocop:disable Lint/ConstantResolution
+          ref += ALPHA[c % 26]
+          # rubocop:enable Lint/ConstantResolution
+          c = (c / 26).floor - 1
+        end
+
+        ref.reverse
+      end
+    end
+  end
+end

data/lib/csv_plus_plus/language/benchmarked_compiler.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+
+module CSVPlusPlus
+  module Language
+    # Extend a +Compiler+ class and add benchmark timings
+    # @attr_reader timings [Array<Benchmark::Tms>] +Benchmark+ timings that have been accumulated by each step of
+    #   compilation
+    # @attr_reader benchmark [Benchmark] A +Benchmark+ instance
+    module BenchmarkedCompiler
+      attr_reader :benchmark, :timings
+
+      # Wrap a +Compiler+ with our instance methods that add benchmarks
+      def self.with_benchmarks(compiler, &block)
+        ::Benchmark.benchmark(::Benchmark::CAPTION, 25, ::Benchmark::FORMAT, '> Total') do |x|
+          # compiler = new(options:, runtime:, benchmark: x)
+          compiler.extend(self)
+          compiler.benchmark = x
+
+          block.call(compiler)
+
+          [compiler.timings.reduce(:+)]
+        end
+      end
+
+      # @param benchmark [Benchmark] A +Benchmark+ instance
+      def benchmark=(benchmark)
+        @benchmark = benchmark
+        @timings = []
+      end
+
+      # Time the Compiler#outputting! stage
+      def outputting!
+        time_stage('Writing the spreadsheet') { super }
+      end
+
+      protected
+
+      def parse_code_section!
+        time_stage('Parsing code section') { super }
+      end
+
+      def parse_csv_section!
+        time_stage('Parsing CSV section') { super }
+      end
+
+      def expanding
+        time_stage('Expanding rows') { super }
+      end
+
+      def resolve_all_cells!(template)
+        time_stage('Resolving each cell') { super(template) }
+      end
+
+      private
+
+      def time_stage(stage, &block)
+        ret = nil
+        @timings << @benchmark.report(stage) { ret = block.call }
+        ret
+      end
+    end
+  end
+end

data/lib/csv_plus_plus/language/builtins.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative './ast_builder'
+
+module CSVPlusPlus
+  module Language
+    # Provides ASTs for builtin functions and variables
+    module Builtins
+      extend ::CSVPlusPlus::Language::ASTBuilder
+
+      VARIABLES = {
+        # The number (integer) of the current cell. Starts at 1
+        cellnum: runtime_value(->(runtime) { number(runtime.cell_index + 1) }),
+
+        # A reference to the current cell
+        cellref: runtime_value(->(runtime) { ref(row_index: runtime.row_index, cell_index: runtime.cell_index) }),
+
+        # A reference to the row above
+        rowabove: runtime_value(->(runtime) { ref(row_index: [0, (runtime.row_index - 1)].max) }),
+
+        # A reference to the row below
+        rowbelow: runtime_value(->(runtime) { ref(row_index: runtime.row_index + 1) }),
+
+        # The number (integer) of the current row.  Starts at 1
+        rownum: runtime_value(->(runtime) { number(runtime.rownum) }),
+
+        # A reference to the current row
+        rowref: runtime_value(->(runtime) { ref(row_index: runtime.row_index) })
+      }.freeze
+      public_constant :VARIABLES
+
+      FUNCTIONS = {
+        # TODO: A reference to a cell in a given row?
+        # A reference to a cell above the current row
+        cellabove: runtime_value(->(runtime, args) { cell_reference([args[0], [1, (runtime.rownum - 1)].max].join) }),
+
+        # A reference to a cell in the current row
+        celladjacent: runtime_value(->(runtime, args) { cell_reference([args[0], runtime.rownum].join) }),
+
+        # A reference to a cell below the current row
+        cellbelow: runtime_value(->(runtime, args) { cell_reference([args[0], runtime.rownum + 1].join) })
+      }.freeze
+      public_constant :FUNCTIONS
+    end
+  end
+end

data/lib/csv_plus_plus/language/cell_value.tab.rb

@@ -29,11 +29,10 @@ module_eval(<<'...end cell_value.y/module_eval...', 'cell_value.y', 48)
     @ast
   end
 
-  def tokenizer(input)
+  def tokenizer
     ::CSVPlusPlus::Lexer::Tokenizer.new(
       catchall: /[\(\)\/\*\+\-,=&]/,
       ignore: /\s+/,
-      input:,
       tokens: [
         [/true/i, :TRUE],
         [/false/i, :FALSE],

data/lib/csv_plus_plus/language/code_section.tab.rb

@@ -33,11 +33,10 @@ module_eval(<<'...end code_section.y/module_eval...', 'code_section.y', 67)
     'code section'
   end
 
-  def tokenizer(input)
+  def tokenizer
     ::CSVPlusPlus::Lexer::Tokenizer.new(
       catchall: /[\(\)\{\}\/\*\+\-,=&]/,
       ignore: /\s+|\#[^\n]+\n/,
-      input:,
       stop_fn: lambda do |scanner|
         return false unless scanner.scan(/#{::CSVPlusPlus::Lexer::END_OF_CODE_SECTION}/)