csv_plus_plus 0.0.4 → 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
@@ -15,16 +24,20 @@ module CSVPlusPlus
       @create_if_not_exists = false
       @key_values = {}
       @verbose = false
-      # TODO: switch to true? probably a safer choice
       @backup = false
     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
 
@@ -32,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}
@@ -56,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.4'
+  VERSION = '0.1.0'
   public_constant :VERSION
 end

data/lib/csv_plus_plus/writer/base_writer.rb

@@ -2,7 +2,6 @@
 
 module CSVPlusPlus
   module Writer
-    ##
     # Some shared functionality that all Writers should build on
     class BaseWriter
       attr_accessor :options

data/lib/csv_plus_plus/writer/csv.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
+require_relative './file_backer_upper'
+
 module CSVPlusPlus
   module Writer
-    ##
     # A class that can output a +Template+ to CSV
     class CSV < ::CSVPlusPlus::Writer::BaseWriter
+      include ::CSVPlusPlus::Writer::FileBackerUpper
+
       # write a +template+ to CSV
       def write(template)
         # TODO: also read it and merge the results

data/lib/csv_plus_plus/writer/excel.rb

@@ -1,25 +1,21 @@
 # frozen_string_literal: true
 
+require_relative './file_backer_upper'
 require_relative './rubyxl_builder'
 
 module CSVPlusPlus
   module Writer
     # A class that can output a +Template+ to an Excel file
     class Excel < ::CSVPlusPlus::Writer::BaseWriter
+      include ::CSVPlusPlus::Writer::FileBackerUpper
+
       # 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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+
+module CSVPlusPlus
+  module Writer
+    # 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
+      # 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
+      def write_backup
+        return unless ::File.exist?(@options.output_filename)
+
+        # TODO: also don't do anything if the current backups contents haven't changed (do a md5sum or something)
+
+        attempt_backups.tap do |backed_up_to|
+          warn("Backed up #{@options.output_filename} to #{backed_up_to}") if @options.verbose
+        end
+      end
+
+      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)
+
+        ::FileUtils.cp(@options.output_filename, filename)
+        filename
+      end
+
+      def format_backup_filename(file_format)
+        pn = ::Pathname.new(@options.output_filename)
+        pn.sub_ext("-#{::Time.now.strftime(file_format)}" + pn.extname)
+      end
+    end
+  end
+end

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

@@ -1,20 +1,18 @@
 # frozen_string_literal: true
 
+require_relative '../google_api_client'
 require_relative 'base_writer'
 require_relative 'google_sheet_builder'
 
-AUTH_SCOPES = ['https://www.googleapis.com/auth/spreadsheets'].freeze
-FULL_RANGE = 'A1:Z1000'
-
 module CSVPlusPlus
   module Writer
-    # A class that can output a +Template+ to Google Sheets (via their API)
+    # A class that can write a +Template+ to Google Sheets (via their API)
     class GoogleSheets < ::CSVPlusPlus::Writer::BaseWriter
-      # XXX it would be nice to raise this but we shouldn't expand out more than necessary for our data
+      # TODO: it would be nice to raise this but we shouldn't expand out more than necessary for our data
       SPREADSHEET_INFINITY = 1000
       public_constant :SPREADSHEET_INFINITY
 
-      # initialize
+      # @param options [Options]
       def initialize(options)
         super(options)
 
@@ -23,8 +21,10 @@ module CSVPlusPlus
       end
 
       # write a +template+ to Google Sheets
+      #
+      # @param template [Template]
       def write(template)
-        auth!
+        @sheets_client = ::CSVPlusPlus::GoogleApiClient.sheets_client
 
         fetch_spreadsheet!
         fetch_spreadsheet_values!
@@ -32,15 +32,12 @@ module CSVPlusPlus
         create_sheet! if @options.create_if_not_exists
 
         update_cells!(template)
-      rescue ::Google::Apis::ClientError => e
-        handle_google_error(e)
       end
 
-      protected
-
-      def load_requires
-        require('google/apis/sheets_v4')
-        require('googleauth')
+      # write a backup of the google sheet
+      def write_backup
+        drive_client = ::CSVPlusPlus::GoogleApiClient.drive_client
+        drive_client.copy_file(@sheet_id)
       end
 
       private
@@ -50,12 +47,7 @@ module CSVPlusPlus
       end
 
       def full_range
-        format_range(::FULL_RANGE)
-      end
-
-      def auth!
-        @gs ||= sheets_ns::SheetsService.new
-        @gs.authorization = ::Google::Auth.get_application_default(::AUTH_SCOPES)
+        format_range('A1:Z1000')
       end
 
       def fetch_spreadsheet_values!
@@ -85,7 +77,7 @@ module CSVPlusPlus
       end
 
       def get_all_spreadsheet_values(render_option)
-        @gs.get_spreadsheet_values(@sheet_id, full_range, value_render_option: render_option)
+        @sheets_client.get_spreadsheet_values(@sheet_id, full_range, value_render_option: render_option)
       end
 
       def sheet
@@ -95,7 +87,7 @@ module CSVPlusPlus
       end
 
       def fetch_spreadsheet!
-        @spreadsheet = @gs.get_spreadsheet(@sheet_id)
+        @spreadsheet = @sheets_client.get_spreadsheet(@sheet_id)
 
         return unless @sheet_name.nil?
 
@@ -105,34 +97,23 @@ module CSVPlusPlus
       def create_sheet!
         return if sheet
 
-        @gs.create_spreadsheet(@sheet_name)
-        get_spreadsheet!
+        @sheets_client.create_spreadsheet(@sheet_name)
+        fetch_spreadsheet!
         @sheet_name = @spreadsheet.sheets.last.properties.title
       end
 
       def update_cells!(template)
-        builder = ::CSVPlusPlus::Writer::GoogleSheetBuilder.new(
+        @sheets_client.batch_update_spreadsheet(@sheet_id, builder(template).batch_update_spreadsheet_request)
+      end
+
+      def builder(template)
+        ::CSVPlusPlus::Writer::GoogleSheetBuilder.new(
           rows: template.rows,
           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
         )
-        @gs.batch_update_spreadsheet(@sheet_id, builder.batch_update_spreadsheet_request)
-      rescue ::Google::Apis::ClientError => e
-        handle_google_error(e)
-      end
-
-      def sheets_ns
-        ::Google::Apis::SheetsV4
-      end
-
-      def handle_google_error(error)
-        if @options.verbose
-          warn("#{error.status_code} Error making Google Sheets API request [#{error.message}]: #{error.body}")
-        else
-          warn("Error making Google Sheets API request: #{error.message}")
-        end
       end
     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,21 +1,43 @@
 # 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! { output.write(template) }
+      c.outputting! do
+        output.write_backup if options.backup
+        output.write(template)
+      end
     end
   end
+  # rubocop:enable Metrics/MethodLength
 end