csv_plus_plus 0.0.5 → 0.1.1

data/lib/csv_plus_plus/modifier.rb

@@ -1,30 +1,28 @@
 # frozen_string_literal: true
 
-require 'set'
-require_relative './color'
-require_relative './expand'
-require_relative './language/syntax_error'
-
 module CSVPlusPlus
   # A container representing the operations that can be applied to a cell or row
   #
-  # @attr expand [Expand]
-  # @attr fontfamily [String]
-  # @attr fontsize [String]
-  # @attr halign ['left', 'center', 'right']
-  # @attr valign ['top', 'center', 'bottom']
-  # @attr note [String]
-  # @attr numberformat [String]
-  # @attr row_level [Boolean]
+  # @attr borders [Array<String>] The borders that will be set
+  # @attr expand [Expand] Whether this row expands into multiple rows
+  # @attr fontfamily [String] The font family
+  # @attr fontsize [Number] The font size
+  # @attr halign ['left', 'center', 'right'] Horizontal alignment
+  # @attr note [String] A note/comment on the cell
+  # @attr numberformat [String] A number format to apply to the value in the cell
+  # @attr row_level [Boolean] Is this a row modifier? If so it's values will apply to all cells in the row
+  #   (unless overridden by the cell modifier)
   # @attr validation [Object]
+  # @attr valign ['top', 'center', 'bottom'] Vertical alignment
   #
-  # @attr_writer borderstyle [String]
+  # @attr_writer borderstyle ['dashed', 'dotted', 'double', 'solid', 'solid_medium', 'solid_thick']
+  #   The style of border on the cell
   #
   # @attr_reader bordercolor [String]
   # @attr_reader borders [Array<String>]
-  # @attr_reader color [Color]
-  # @attr_reader fontcolor [Color]
-  # @attr_reader formats [Array<String>]
+  # @attr_reader color [Color] The background color of the cell
+  # @attr_reader fontcolor [Color] The font color of the cell
+  # @attr_reader formats [Array<String>] Bold/italics/underline/strikethrough formatting
   class Modifier
     attr_reader :bordercolor, :borders, :color, :fontcolor, :formats
     attr_writer :borderstyle
@@ -39,25 +37,32 @@ module CSVPlusPlus
     end
 
     # Set the color
+    #
     # @param hex_value [String]
+    #
+    # @return [Color]
     def color=(hex_value)
       @color = ::CSVPlusPlus::Color.new(hex_value)
     end
 
     # Assign a border
+    #
     # @param side ['top', 'left', 'bottom', 'right', 'all']
     def border=(side)
       @borders << side
     end
 
     # Does this have a border along +side+?
+    #
     # @param side ['top', 'left', 'bottom', 'right', 'all']
+    #
     # @return [Boolean]
     def border_along?(side)
       @borders.include?('all') || @borders.include?(side)
     end
 
     # Does this have a border along all sides?
+    #
     # @return [Boolean]
     def border_all?
       @borders.include?('all') \
@@ -65,65 +70,79 @@ module CSVPlusPlus
     end
 
     # Set the bordercolor
+    #
     # @param hex_value [String] formatted as '#000000', '#000' or '000000'
     def bordercolor=(hex_value)
       @bordercolor = ::CSVPlusPlus::Color.new(hex_value)
     end
 
     # Are there any borders set?
+    #
     # @return [Boolean]
     def any_border?
       !@borders.empty?
     end
 
     # Set the fontcolor
+    #
     # @param hex_value [String] formatted as '#000000', '#000' or '000000'
     def fontcolor=(hex_value)
       @fontcolor = ::CSVPlusPlus::Color.new(hex_value)
     end
 
     # Set a text format (bolid, italic, underline or strikethrough)
+    #
     # @param value ['bold', 'italic', 'underline', 'strikethrough']
     def format=(value)
       @formats << value
     end
 
     # Is the given format set?
+    #
     # @param type ['bold', 'italic', 'underline', 'strikethrough']
+    #
     # @return [Boolean]
     def formatted?(type)
       @formats.include?(type)
     end
 
     # Freeze the row from edits
+    #
+    # @return [true]
     def freeze!
       @frozen = true
     end
 
-    # Is the row forzen?
+    # Is the row frozen?
+    #
     # @return [Boolean]
     def frozen?
       @frozen
     end
 
     # Mark this modifer as row-level
+    #
+    # @return [true]
     def row_level!
       @row_level = true
     end
 
     # Is this a row-level modifier?
+    #
     # @return [Boolean]
     def row_level?
       @row_level
     end
 
     # Is this a cell-level modifier?
+    #
     # @return [Boolean]
     def cell_level?
       !@row_level
     end
 
     # Style of border
+    #
     # @return [String]
     def borderstyle
       @borderstyle || 'solid'
@@ -137,6 +156,7 @@ module CSVPlusPlus
     end
 
     # Create a new modifier instance, with all values defaulted from +other+
+    #
     # @param other [Modifier]
     def take_defaults_from!(other)
       other.instance_variables.each do |property|

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,18 @@ 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 +47,8 @@ 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 +73,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,27 @@
 
 module CSVPlusPlus
   # Contains the flow and data from a code section and CSV section
+  #
+  # @attr_reader code_section [CodeSection] The +CodeSection+ containing the functions and variables defined herein
+  # @attr_reader rows [Array<Row>] The +Row+s that comprise this +Template+
   class Template
-    attr_reader :rows, :scope
+    attr_reader :code_section, :rows
 
-    # initialize
-    def initialize(rows:, scope:)
+    # @param code_section [CodeSection] The +CodeSection+ containing the functions and variables
+    # @param rows [Array<Row>] The +Row+s that comprise this +Template+
+    def initialize(code_section:, rows:)
+      @code_section = code_section
       @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 +38,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
@@ -42,6 +50,18 @@ module CSVPlusPlus
       )
     end
 
+    # Provide a summary of the state of the template (and it's +@code_section+)
+    #
+    # @return [String]
+    def verbose_summary
+      # TODO: we can probably include way more stats in here
+      <<~SUMMARY
+        #{@code_section.verbose_summary}
+
+        > #{@rows.length} rows to be written
+      SUMMARY
+    end
+
     private
 
     def expand_rows(push_row_fn)

data/lib/csv_plus_plus/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  VERSION = '0.0.5'
+  VERSION = '0.1.1'
   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