csv_plus_plus 0.0.5 → 0.1.0

data/lib/csv_plus_plus/modifier.tab.rb

@@ -17,6 +17,7 @@ module_eval(<<'...end modifier.y/module_eval...', 'modifier.y', 121)
 
   include ::CSVPlusPlus::Lexer
 
+  # @param cell_modifier 
   def initialize(cell_modifier:, row_modifier:)
     super()
 
@@ -42,11 +43,10 @@ module_eval(<<'...end modifier.y/module_eval...', 'modifier.y', 121)
     'modifier'
   end
 
-  def tokenizer(input)
+  def tokenizer
     ::CSVPlusPlus::Lexer::Tokenizer.new(
       catchall: /\w+/,
       ignore: /\s+/,
-      input:,
       stop_fn: lambda do |scanner|
         return false unless scanner.scan(/\]\]/)
 

data/lib/csv_plus_plus/options.rb

@@ -4,7 +4,16 @@ require_relative './cli_flag'
 require_relative './google_options'
 
 module CSVPlusPlus
-  # The options a user can supply
+  # The options a user can supply (via CLI flags)
+  #
+  # @attr backup [boolean] Create a backup of the spreadsheet before writing
+  # @attr create_if_not_exists [boolean] Create the spreadsheet if it does not exist?
+  # @attr key_values [Hash] Additional variables that can be supplied to the template
+  # @attr offset [Array<Integer>] An [x, y] offset (array with two integers)
+  # @attr output_filename [String] The file to write our compiled results to
+  # @attr sheet_name [String] The name of the spreadsheet to write to
+  # @attr verbose [boolean] Include extra verbose output?
+  # @attr_reader google [GoogleOptions] Options that are specific to the Google Sheets writer
   class Options
     attr_accessor :backup, :create_if_not_exists, :key_values, :offset, :output_filename, :sheet_name, :verbose
     attr_reader :google
@@ -19,11 +28,16 @@ module CSVPlusPlus
     end
 
     # Set the Google Sheet ID
+    #
+    # @param sheet_id [String] The identifier used by Google's API to reference the sheet.  You can find it in the URL
+    #   for the sheet
+    # @return [String]
     def google_sheet_id=(sheet_id)
       @google = ::CSVPlusPlus::GoogleOptions.new(sheet_id)
     end
 
     # Returns an error string or nil if there are no validation problems
+    # @return [String, nil]
     def validate
       return if @google || @output_filename
 
@@ -31,6 +45,7 @@ module CSVPlusPlus
     end
 
     # Return a string with a verbose description of what we're doing with the options
+    # @return [String]
     def verbose_summary
       <<~SUMMARY
         #{summary_divider}
@@ -55,7 +70,7 @@ module CSVPlusPlus
       SUMMARY
     end
 
-    # to_s
+    # @return [String]
     def to_s
       "Options(create_if_not_exists: #{@create_if_not_exists}, google: #{@google}, key_values: #{@key_values}, " \
         "offset: #{@offset}, sheet_name: #{@sheet_name}, verbose: #{@verbose})"

data/lib/csv_plus_plus/row.rb

@@ -4,37 +4,48 @@ require_relative 'cell'
 require_relative 'modifier.tab'
 
 module CSVPlusPlus
-  ##
   # A row of a template
+  #
+  # @attr_reader cells [Array<Cell>]
+  # @attr_reader index [Integer] The index of this row
+  # @attr_reader modifier [Modifier] The modifier to apply to all cells in this row
   class Row
     attr_reader :cells, :index, :modifier
 
-    # initialize
+    # @param index [Integer] The index of this row (starts at 0)
+    # @param cells [Array<Cell>] The cells belonging to this row
+    # @param modifier [Modifier] The modifier to apply to all cells in this row
     def initialize(index, cells, modifier)
       @cells = cells
       @modifier = modifier
       @index = index
     end
 
-    # Set the row index. And update the index of all affected cells
+    # Set the row's +index+ and update the +row_index+ of all affected cells
+    #
+    # @param index [Integer] The index of this row (starts at 0)
     def index=(index)
       @index = index
       @cells.each { |cell| cell.row_index = index }
     end
 
     # How much this row will expand itself, if at all (0)
+    #
+    # @return [Integer]
     def expand_amount
       return 0 unless @modifier.expand
 
       @modifier.expand.repetitions || (1000 - @index)
     end
 
-    # to_s
+    # @return [String]
     def to_s
       "Row(index: #{index}, modifier: #{modifier}, cells: #{cells})"
     end
 
     # Return a deep copy of this row
+    #
+    # @return [Row]
     def deep_clone
       ::Marshal.load(::Marshal.dump(self))
     end

data/lib/csv_plus_plus/template.rb

@@ -2,21 +2,23 @@
 
 module CSVPlusPlus
   # Contains the flow and data from a code section and CSV section
+  #
+  # @attr_reader rows [Array<Row>] The +Row+s that comprise this +Template+
   class Template
-    attr_reader :rows, :scope
+    attr_reader :rows
 
-    # initialize
-    def initialize(rows:, scope:)
+    # @param rows [Array<Row>] The +Row+s that comprise this +Template+
+    def initialize(rows:)
       @rows = rows
-      @scope = scope
     end
 
-    # to_s
+    # @return [String]
     def to_s
-      "Template(rows: #{@rows}, scope: #{@scope})"
+      "Template(rows: #{@rows})"
     end
 
     # Apply any expand= modifiers to the parsed template
+    # @return [Array<Row>]
     def expand_rows!
       expanded_rows = []
       row_index = 0
@@ -32,6 +34,8 @@ module CSVPlusPlus
     end
 
     # Make sure that the template has a valid amount of infinite expand modifiers
+    #
+    # @param runtime [Runtime] The compiler's current runtime
     def validate_infinite_expands(runtime)
       infinite_expand_rows = @rows.filter { |r| r.modifier.expand&.infinite? }
       return unless infinite_expand_rows.length > 1

data/lib/csv_plus_plus/version.rb

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

data/lib/csv_plus_plus/writer/excel.rb

@@ -12,17 +12,10 @@ module CSVPlusPlus
       # write the +template+ to an Excel file
       def write(template)
         ::CSVPlusPlus::Writer::RubyXLBuilder.new(
-          output_filename: @options.output_filename,
+          input_filename: @options.output_filename,
           rows: template.rows,
           sheet_name: @options.sheet_name
-        ).write
-      end
-
-      protected
-
-      def load_requires
-        require('rubyXL')
-        require('rubyXL/convenience_methods')
+        ).build_workbook.write(@options.output_filename)
       end
     end
   end

data/lib/csv_plus_plus/writer/file_backer_upper.rb

@@ -5,41 +5,43 @@ require 'pathname'
 
 module CSVPlusPlus
   module Writer
-    # A mixin that can
+    # A module that can be mixed into any Writer that needs to back up it's @output_filename (all of them except Google
+    # Sheets)
     module FileBackerUpper
-      # we don't want to include a bunch of second/millisecond stuff in the filename  unless we
+      # I don't want to include a bunch of second/millisecond stuff in the filename  unless we
       # really need to. so try a less specifically formatted filename then get more specific
       DESIRED_BACKUP_FORMATS = [%(%Y_%m_%d-%I_%M%p), %(%Y_%m_%d-%I_%M_%S%p), %(%Y_%m_%d-%I_%M_%S_%L%p)].freeze
       private_constant :DESIRED_BACKUP_FORMATS
 
       # Assuming the underlying spreadsheet is file-based, create a backup of it
-      # rubocop:disable Metrics/MethodLength
       def write_backup
         return unless ::File.exist?(@options.output_filename)
 
-        attempted = []
-        backed_up_to = nil
+        # TODO: also don't do anything if the current backups contents haven't changed (do a md5sum or something)
 
-        # rubocop:disable Lint/ConstantResolution
-        DESIRED_BACKUP_FORMATS.find do |file_format|
-          # rubocop:enable Lint/ConstantResolution
-          filename = format_backup_filename(file_format)
-          attempted << filename
-          backed_up_to = backup(filename)
-
-          break if backed_up_to
-        end
-
-        unless backed_up_to
-          raise(::CSVPlusPlus::Error, "Unable to write backup file despite trying these: #{attempted.join(', ')}")
+        attempt_backups.tap do |backed_up_to|
+          warn("Backed up #{@options.output_filename} to #{backed_up_to}") if @options.verbose
         end
-
-        warn("Backed up #{@options.output_filename} to #{backed_up_to}") if @options.verbose
       end
-      # rubocop:enable Metrics/MethodLength
 
       private
 
+      def attempt_backups
+        attempted =
+          # rubocop:disable Lint/ConstantResolution
+          DESIRED_BACKUP_FORMATS.map do |file_format|
+            # rubocop:enable Lint/ConstantResolution
+            filename = format_backup_filename(file_format)
+            backed_up_to = backup(filename)
+
+            next filename unless backed_up_to
+
+            return backed_up_to
+          end
+
+        raise(::CSVPlusPlus::Error, "Unable to write backup file despite trying these: #{attempted.join(', ')}")
+      end
+
       def backup(filename)
         return if ::File.exist?(filename)
 

data/lib/csv_plus_plus/writer/google_sheet_builder.rb

@@ -7,7 +7,7 @@ module CSVPlusPlus
     # Given +rows+ from a +Template+, build requests compatible with Google Sheets Ruby API
     # rubocop:disable Metrics/ClassLength
     class GoogleSheetBuilder
-      # initialize
+      # @param current_sheet_values
       def initialize(current_sheet_values:, sheet_id:, rows:, column_index: 0, row_index: 0)
         @current_sheet_values = current_sheet_values
         @sheet_id = sheet_id
@@ -17,6 +17,8 @@ module CSVPlusPlus
       end
 
       # Build a Google::Apis::SheetsV4::BatchUpdateSpreadsheetRequest
+      #
+      # @return [Google::Apis::SheetsV4::BatchUpdateSpreadsheetRequest]
       def batch_update_spreadsheet_request
         build_batch_request(@rows)
       end
@@ -42,20 +44,16 @@ module CSVPlusPlus
         end
       end
 
-      # rubocop:disable Metrics/AbcSize
       def build_cell_format(mod)
         sheets_ns::CellFormat.new.tap do |cf|
           cf.text_format = mod.text_format
 
-          cf.horizontal_alignment = mod.halign if mod.halign
-          cf.vertical_alignment = mod.valign if mod.valign
-
-          cf.background_color = mod.color if mod.color
-
-          cf.number_format = mod.numberformat if mod.numberformat
+          cf.horizontal_alignment = mod.halign
+          cf.vertical_alignment = mod.valign
+          cf.background_color = mod.color
+          cf.number_format = mod.numberformat
         end
       end
-      # rubocop:enable Metrics/AbcSize
 
       def grid_range_for_cell(cell)
         sheets_ns::GridRange.new(
@@ -68,7 +66,7 @@ module CSVPlusPlus
       end
 
       def current_value(row_index, cell_index)
-        @current_values[row_index][cell_index]
+        @current_sheet_values[row_index][cell_index]
       rescue ::StandardError
         nil
       end

data/lib/csv_plus_plus/writer/google_sheets.rb

@@ -12,7 +12,7 @@ module CSVPlusPlus
       SPREADSHEET_INFINITY = 1000
       public_constant :SPREADSHEET_INFINITY
 
-      # initialize
+      # @param options [Options]
       def initialize(options)
         super(options)
 
@@ -21,6 +21,8 @@ module CSVPlusPlus
       end
 
       # write a +template+ to Google Sheets
+      #
+      # @param template [Template]
       def write(template)
         @sheets_client = ::CSVPlusPlus::GoogleApiClient.sheets_client
 
@@ -38,14 +40,6 @@ module CSVPlusPlus
         drive_client.copy_file(@sheet_id)
       end
 
-      protected
-
-      def load_requires
-        require('google/apis/drive_v3')
-        require('google/apis/sheets_v4')
-        require('googleauth')
-      end
-
       private
 
       def format_range(range)
@@ -118,7 +112,7 @@ module CSVPlusPlus
           sheet_id: sheet&.properties&.sheet_id,
           column_index: @options.offset[1],
           row_index: @options.offset[0],
-          current_sheet_values: @current_sheet_values
+          current_sheet_values: @current_values
         )
       end
     end

data/lib/csv_plus_plus/writer/rubyxl_builder.rb

@@ -5,21 +5,29 @@ require_relative './rubyxl_modifier'
 module CSVPlusPlus
   module Writer
     # Build a RubyXL workbook formatted according to the given +rows+
+    #
+    # @attr_reader input_filename [String] The filename being written to
+    # @attr_reader rows [Array<Row>] The rows being written
     class RubyXLBuilder
-      attr_reader :output_filename, :rows
+      attr_reader :input_filename, :rows
 
-      # initialize
-      def initialize(output_filename:, rows:, sheet_name:)
+      # @param input_filename [String] The file to write to
+      # @param rows [Array<Row>] The rows to write
+      # @param sheet_name [String] The name of the sheet within the workbook to write to
+      def initialize(input_filename:, rows:, sheet_name:)
         @rows = rows
-        @output_filename = output_filename
-        @workbook = open_workbook(sheet_name)
-        @worksheet = @workbook[sheet_name]
+        @input_filename = input_filename
+        @sheet_name = sheet_name
       end
 
-      # write the given @rows in +sheet_name+ to +@output_filename+
-      def write
-        build_workbook!
-        @workbook.write(@output_filename)
+      # Build a +RubyXL::Workbook+ with the given +@rows+ in +sheet_name+
+      #
+      # @return [RubyXL::Workbook]
+      def build_workbook
+        open_workbook.tap do |workbook|
+          @worksheet = workbook[@sheet_name]
+          build_workbook!
+        end
       end
 
       private
@@ -96,14 +104,14 @@ module CSVPlusPlus
         end
       end
 
-      def open_workbook(sheet_name)
-        if ::File.exist?(@output_filename)
-          ::RubyXL::Parser.parse(@output_filename).tap do |workbook|
-            workbook.add_worksheet(sheet_name) unless workbook[sheet_name]
+      def open_workbook
+        if ::File.exist?(@input_filename)
+          ::RubyXL::Parser.parse(@input_filename).tap do |workbook|
+            workbook.add_worksheet(@sheet_name) unless workbook[@sheet_name]
           end
         else
           ::RubyXL::Workbook.new.tap do |workbook|
-            workbook.worksheets[0].sheet_name = sheet_name
+            workbook.worksheets[0].sheet_name = @sheet_name
           end
         end
       end

data/lib/csv_plus_plus/writer/rubyxl_modifier.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  # Writer
   module Writer
     # Build a RubyXL-decorated Modifier class adds some support for Excel
     class RubyXLModifier < ::SimpleDelegator
@@ -32,21 +31,29 @@ module CSVPlusPlus
       }.freeze
       private_constant :BORDER_STYLES
 
+      # The excel-specific border weight
+      #
+      # @return [Integer]
+      def border_weight
+        return unless borderstyle
+
+        # rubocop:disable Lint/ConstantResolution
+        BORDER_STYLES[borderstyle.to_sym]
+        # rubocop:enable Lint/ConstantResolution
+      end
+
       # The excel-specific number format code
+      #
+      # @return [String]
       def number_format_code
+        return unless numberformat
+
         ::RubyXL::NumberFormats::DEFAULT_NUMBER_FORMATS.find_by_format_id(
           # rubocop:disable Lint/ConstantResolution
           NUM_FMT_IDS[numberformat.to_sym]
           # rubocop:enable Lint/ConstantResolution
         ).format_code
       end
-
-      # The excel-specific border weight
-      def border_weight
-        # rubocop:disable Lint/ConstantResolution
-        BORDER_STYLES[borderstyle.to_sym]
-        # rubocop:enable Lint/ConstantResolution
-      end
     end
   end
 end

data/lib/csv_plus_plus.rb

@@ -1,19 +1,36 @@
 # frozen_string_literal: true
 
+require 'google/apis/drive_v3'
+require 'google/apis/sheets_v4'
+require 'googleauth'
+require 'rubyXL'
+require 'rubyXL/convenience_methods'
+
 require_relative 'csv_plus_plus/cli'
 require_relative 'csv_plus_plus/error'
+require_relative 'csv_plus_plus/language/builtins'
 require_relative 'csv_plus_plus/language/compiler'
+require_relative 'csv_plus_plus/language/runtime'
 require_relative 'csv_plus_plus/options'
 require_relative 'csv_plus_plus/writer'
 
-# A language for writing rich CSV data
+# A programming language for writing rich CSV files
 module CSVPlusPlus
   # Parse the input into a +Template+ and write it to the desired format
+  #
+  # @param input [String] The csvpp input to compile
+  # @param filename [String, nil] The filename the input was read from.  +nil+ if it is read from stdin.
+  # @param options [Options] The various options to compile with
+  #
+  # rubocop:disable Metrics/MethodLength
   def self.apply_template_to_sheet!(input, filename, options)
     warn(options.verbose_summary) if options.verbose
 
-    ::CSVPlusPlus::Language::Compiler.with_compiler(input:, filename:, options:) do |c|
-      template = c.parse_template
+    ::CSVPlusPlus::Language::Compiler.with_compiler(
+      options:,
+      runtime: ::CSVPlusPlus::Language::Runtime.new(input:, filename:)
+    ) do |c|
+      template = c.compile_template
 
       output = ::CSVPlusPlus::Writer.writer(options)
       c.outputting! do
@@ -22,4 +39,5 @@ module CSVPlusPlus
       end
     end
   end
+  # rubocop:enable Metrics/MethodLength
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: csv_plus_plus
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.1.0
 platform: ruby
 authors:
 - Patrick Carroll
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-18 00:00:00.000000000 Z
+date: 2023-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-apis-drive_v3
@@ -133,6 +133,9 @@ files:
 - lib/csv_plus_plus/google_api_client.rb
 - lib/csv_plus_plus/google_options.rb
 - lib/csv_plus_plus/graph.rb
+- lib/csv_plus_plus/language/ast_builder.rb
+- lib/csv_plus_plus/language/benchmarked_compiler.rb
+- lib/csv_plus_plus/language/builtins.rb
 - lib/csv_plus_plus/language/cell_value.tab.rb
 - lib/csv_plus_plus/language/code_section.tab.rb
 - lib/csv_plus_plus/language/compiler.rb