csv_plus_plus 0.1.3 → 0.2.0

data/lib/csv_plus_plus/runtime/scope.rb

@@ -0,0 +1,280 @@
+# typed: strict
+# frozen_string_literal: true
+
+module CSVPlusPlus
+  module Runtime
+    # Responsible for storing and resolving variables and function references
+    # rubocop:disable Metrics/ClassLength
+    class Scope
+      extend ::T::Sig
+
+      sig { returns(::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Function]) }
+      attr_reader :functions
+
+      sig { returns(::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]) }
+      attr_reader :variables
+
+      sig do
+        params(
+          functions: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Function],
+          variables: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]
+        ).void
+      end
+      # @param functions [Hash<Symbol, Function>] Pre-defined functions
+      # @param variables [Hash<Symbol, Entity>] Pre-defined variables
+      def initialize(functions: {}, variables: {})
+        @functions = functions
+        @variables = variables
+      end
+
+      sig { params(id: ::Symbol, entity: ::CSVPlusPlus::Entities::Entity).returns(::CSVPlusPlus::Entities::Entity) }
+      # 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
+      #
+      # @return [Entity] The value of the variable (+entity+)
+      def def_variable(id, entity)
+        @variables[id] = entity
+      end
+
+      sig { params(vars: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]).void }
+      # Define (or re-define existing) variables
+      #
+      # @param vars [Hash<Symbol, Variable>] Variables to define
+      def def_variables(vars)
+        vars.each { |id, entity| def_variable(id, entity) }
+      end
+
+      sig do
+        params(id: ::Symbol, function: ::CSVPlusPlus::Entities::Function).returns(::CSVPlusPlus::Entities::Function)
+      end
+      # Define a (or re-define an existing) function
+      #
+      # @param id [Symbol] The identifier for the function
+      # @param function [Entities::Function] The defined function
+      #
+      # @return [Entities::Function] The defined function
+      def def_function(id, function)
+        @functions[id.to_sym] = function
+      end
+
+      sig { params(var_id: ::Symbol, position: ::CSVPlusPlus::Runtime::Position).returns(::T::Boolean) }
+      # Variables outside of an ![[expand=...] are always in scope.  If it's defined within an expand then things
+      # get trickier because the variable is only in scope while we're processing cells within that expand.
+      #
+      # @param var_id [Symbol] The variable's identifier that we are checking if it's in scope
+      # @param position [Position]
+      #
+      # @return [boolean]
+      def in_scope?(var_id, position)
+        value = @variables[var_id]
+
+        return false unless value
+
+        expand = value.is_a?(::CSVPlusPlus::Entities::Reference) && value.a1_ref.scoped_to_expand
+        !expand || expand.position_within?(position)
+      end
+
+      sig { returns(::String) }
+      # Provide a summary of the functions and variables compiled (to show in verbose mode)
+      #
+      # @return [::String]
+      def verbose_summary
+        <<~SUMMARY
+          # Code Section Summary
+
+          ## Resolved Variables
+
+          #{variable_summary}
+
+          ## Functions
+
+          #{function_summary}
+        SUMMARY
+      end
+
+      sig do
+        params(
+          position: ::CSVPlusPlus::Runtime::Position,
+          ast: ::CSVPlusPlus::Entities::Entity,
+          refs: ::T::Enumerable[::CSVPlusPlus::Entities::FunctionCall]
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # @param position [Position
+      # @param ast [Entity]
+      # @param refs [Array<FunctionCall>]
+      #
+      # @return [Entity]
+      def resolve_functions(position, ast, refs)
+        refs.reduce(ast.dup) do |acc, elem|
+          function_replace(position, acc, elem.id, resolve_function(elem.id))
+        end
+      end
+
+      sig do
+        params(
+          position: ::CSVPlusPlus::Runtime::Position,
+          ast: ::CSVPlusPlus::Entities::Entity,
+          refs: ::T::Enumerable[::CSVPlusPlus::Entities::Reference]
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # @param position [Position]
+      # @param ast [Entity]
+      # @param refs [Array<Variable>]
+      #
+      # @return [Entity]
+      def resolve_variables(position, ast, refs)
+        refs.reduce(ast.dup) do |acc, elem|
+          next acc unless (id = elem.id)
+
+          variable_replace(acc, id, resolve_variable(position, id))
+        end
+      end
+
+      sig do
+        params(
+          position: ::CSVPlusPlus::Runtime::Position,
+          node: ::CSVPlusPlus::Entities::Entity,
+          fn_id: ::Symbol,
+          replacement: ::T.any(::CSVPlusPlus::Entities::Function, ::CSVPlusPlus::Entities::RuntimeValue)
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # Make a copy of the AST represented by +node+ and replace +fn_id+ with +replacement+ throughout
+      # rubocop:disable Metrics/MethodLength
+      def function_replace(position, node, fn_id, replacement)
+        if node.is_a?(::CSVPlusPlus::Entities::FunctionCall) && node.id == fn_id
+          call_function_or_builtin(position, replacement, node)
+        elsif node.is_a?(::CSVPlusPlus::Entities::FunctionCall)
+          # not our function, but continue our depth first search on it
+          ::CSVPlusPlus::Entities::FunctionCall.new(
+            node.id,
+            node.arguments.map { |n| function_replace(position, n, fn_id, replacement) },
+            infix: node.infix
+          )
+        else
+          node
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      sig do
+        params(fn_id: ::Symbol)
+          .returns(::T.any(::CSVPlusPlus::Entities::Function, ::CSVPlusPlus::Entities::RuntimeValue))
+      end
+      # @param fn_id [Symbol]
+      #
+      # @return [Entities::Function]
+      def resolve_function(fn_id)
+        return ::T.must(@functions[fn_id]) if @functions.key?(fn_id)
+
+        builtin = ::CSVPlusPlus::Entities::Builtins::FUNCTIONS[fn_id]
+        raise(::CSVPlusPlus::Error::FormulaSyntaxError.new('Undefined function', bad_input: fn_id.to_s)) unless builtin
+
+        builtin
+      end
+
+      sig do
+        params(
+          position: ::CSVPlusPlus::Runtime::Position,
+          function_or_builtin: ::T.any(::CSVPlusPlus::Entities::RuntimeValue, ::CSVPlusPlus::Entities::Function),
+          function_call: ::CSVPlusPlus::Entities::FunctionCall
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # @param position [Position]
+      # @param function_or_builtin [Entities::Function, Entities::RuntimeValue]
+      # @param function_call [Entities::FunctionCall]
+      #
+      # @return [Entities::Entity]
+      def call_function_or_builtin(position, function_or_builtin, function_call)
+        if function_or_builtin.is_a?(::CSVPlusPlus::Entities::RuntimeValue)
+          function_or_builtin.call(position, function_call.arguments)
+        else
+          call_function(function_or_builtin, function_call)
+        end
+      end
+
+      sig do
+        params(
+          function: ::CSVPlusPlus::Entities::Function,
+          function_call: ::CSVPlusPlus::Entities::FunctionCall
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # Since functions are just built up from existing functions, a "call" is effectively replacing the variable
+      # references in the +@body+ with the ones being passed as arguments
+      #
+      # @param function [Entities::Function] The function being called
+      # @param function_call [Entities::FunctionCall] The actual call of the function
+      #
+      # @return [Entities::Entity]
+      def call_function(function, function_call)
+        i = 0
+        function.arguments.reduce(function.body.dup) do |ast, argument|
+          variable_replace(ast, argument, ::T.must(function_call.arguments[i])).tap do
+            i += 1
+          end
+        end
+      end
+
+      sig do
+        params(
+          node: ::CSVPlusPlus::Entities::Entity,
+          var_id: ::Symbol,
+          replacement: ::CSVPlusPlus::Entities::Entity
+        ).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # Make a copy of the AST represented by +node+ and replace +var_id+ with +replacement+ throughout
+      def variable_replace(node, var_id, replacement)
+        if node.is_a?(::CSVPlusPlus::Entities::FunctionCall)
+          arguments = node.arguments.map { |n| variable_replace(n, var_id, replacement) }
+          # TODO: refactor these places where we copy functions... it's brittle with the kwargs
+          ::CSVPlusPlus::Entities::FunctionCall.new(node.id, arguments, infix: node.infix)
+        elsif node.is_a?(::CSVPlusPlus::Entities::Reference) && node.id == var_id
+          replacement
+        else
+          node
+        end
+      end
+
+      sig do
+        params(position: ::CSVPlusPlus::Runtime::Position, var_id: ::Symbol).returns(::CSVPlusPlus::Entities::Entity)
+      end
+      # @param position [Position]
+      # @param var_id [Symbol]
+      #
+      # @return [Entities::Entity]
+      def resolve_variable(position, var_id)
+        return ::T.must(@variables[var_id]) if @variables.key?(var_id)
+
+        unless ::CSVPlusPlus::Entities::Builtins.builtin_variable?(var_id)
+          raise(::CSVPlusPlus::Error::FormulaSyntaxError.new('Undefined variable', bad_input: var_id.to_s))
+        end
+
+        ::T.must(::CSVPlusPlus::Entities::Builtins::VARIABLES[var_id]).call(position, [])
+      end
+
+      sig { returns(::String) }
+      # Create a summary of all currently defined variables
+      #
+      # @return [String]
+      def variable_summary
+        return '(no variables defined)' if @variables.empty?
+
+        @variables.map { |k, v| "#{k} := #{v}" }
+                  .join("\n")
+      end
+
+      sig { returns(::String) }
+      # Create a summary of all currently defined functions
+      #
+      # @return [String]
+      def function_summary
+        return '(no functions defined)' if @functions.empty?
+
+        @functions.map { |k, f| "#{k}: #{f}" }
+                  .join("\n")
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/csv_plus_plus/runtime.rb

@@ -1,12 +1,11 @@
 # typed: strict
 # frozen_string_literal: true
 
-require_relative './runtime/can_define_references'
-require_relative './runtime/can_resolve_references'
 require_relative './runtime/graph'
-require_relative './runtime/position_tracker'
+require_relative './runtime/position'
 require_relative './runtime/references'
 require_relative './runtime/runtime'
+require_relative './runtime/scope'
 
 module CSVPlusPlus
   # All functionality needed to keep track of the runtime AKA execution context.  This module has a lot of
@@ -23,20 +22,21 @@ module CSVPlusPlus
     sig do
       params(
         source_code: ::CSVPlusPlus::SourceCode,
-        functions: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Function],
-        variables: ::T::Hash[::Symbol, ::CSVPlusPlus::Entities::Entity]
+        position: ::T.nilable(::CSVPlusPlus::Runtime::Position),
+        scope: ::T.nilable(::CSVPlusPlus::Runtime::Scope)
       ).returns(::CSVPlusPlus::Runtime::Runtime)
     end
     # Initialize a runtime instance with all the functionality we need.  A runtime is one-to-one with a file being
     # compiled.
     #
     # @param source_code [SourceCode] The csv++ source code to be compiled
-    # @param functions [Hash<Symbol, Function>] Pre-defined functions
-    # @param variables [Hash<Symbol, Entity>] Pre-defined variables
+    # @param position [Position, nil]
+    # @param scope [Scope, nil]
     #
     # @return [Runtime::Runtime]
-    def self.new(source_code:, functions: {}, variables: {})
-      ::CSVPlusPlus::Runtime::Runtime.new(source_code:, functions:, variables:)
+    def self.new(source_code:, position: nil, scope: nil)
+      position ||= ::CSVPlusPlus::Runtime::Position.new(source_code.input)
+      ::CSVPlusPlus::Runtime::Runtime.new(source_code:, position:, scope:)
     end
   end
 end

data/lib/csv_plus_plus/source_code.rb

@@ -9,7 +9,7 @@ module CSVPlusPlus
     sig { returns(::String) }
     attr_reader :input
 
-    sig { returns(::String) }
+    sig { returns(::Pathname) }
     attr_reader :filename
 
     sig { returns(::Integer) }
@@ -21,15 +21,13 @@ module CSVPlusPlus
     sig { returns(::Integer) }
     attr_reader :length_of_file
 
-    sig { params(input: ::String, filename: ::T.nilable(::String)).void }
-    # @param input [::String] The source code being parsed
-    # @param filename [::String, nil] The name of the file the source came from.  If not set we assume it came
-    #   from stdin
-    def initialize(input:, filename: nil)
-      @input = input
-      @filename = ::T.let(filename || 'stdin', ::String)
+    sig { params(filename: ::String, input: ::T.nilable(::String)).void }
+    # @param filename [::String] The name of the file the source came from.
+    def initialize(filename, input: nil)
+      @filename = ::T.let(::Pathname.new(filename), ::Pathname)
+      @input = ::T.let(input || read_file, ::String)
 
-      lines = input.split(/[\r\n]/)
+      lines = @input.split(/[\r\n]/)
       @length_of_file = ::T.let(lines.length, ::Integer)
       @length_of_code_section = ::T.let(count_code_section_lines(lines), ::Integer)
       @length_of_csv_section = ::T.let(@length_of_file - @length_of_code_section, ::Integer)
@@ -57,6 +55,13 @@ module CSVPlusPlus
 
     private
 
+    sig { returns(::String) }
+    def read_file
+      raise(::CSVPlusPlus::Error::CLIError, "Source file #{@filename} does not exist") unless ::File.exist?(@filename)
+
+      ::File.read(@filename)
+    end
+
     sig { params(lines: ::T::Array[::String]).returns(::Integer) }
     def count_code_section_lines(lines)
       eoc = ::CSVPlusPlus::Lexer::END_OF_CODE_SECTION

data/lib/csv_plus_plus/template.rb

@@ -27,24 +27,29 @@ module CSVPlusPlus
     # Only run after expanding all rows, now we can bind all [[var=]] modifiers to a variable.  There are two distinct
     # types of variable bindings here:
     #
-    # * Binding to a cell: for this we just make a +CellReference+ to the cell itself (A1, B4, etc)
+    # * Binding to a cell: for this we just make an +A1Reference+ to the cell itself (A1, B4, etc)
     # * Binding to a cell within an expand: the variable can only be resolved within that expand and needs to be
     #   relative to it's row (it can't be an absolute cell reference like above)
     #
     # @param runtime [Runtime] The current runtime
+    # rubocop:disable Metrics/MethodLength
     def bind_all_vars!(runtime)
-      runtime.map_rows(@rows) do |row|
+      runtime.position.map_rows(@rows) do |row|
         # rubocop:disable Style/MissingElse
         if row.unexpanded?
           # rubocop:enable Style/MissingElse
-          raise(::CSVPlusPlus::Error::Error, 'Template#expand_rows! must be called before Template#bind_all_vars!')
+          raise(
+            ::CSVPlusPlus::Error::CompilerError,
+            'Template#expand_rows! must be called before Template#bind_all_vars!'
+          )
         end
 
-        runtime.map_row(row.cells) do |cell|
+        runtime.position.map_row(row.cells) do |cell|
           bind_vars(cell, row.modifier.expand)
         end
       end
     end
+    # rubocop:enable Metrics/MethodLength
 
     sig { returns(::T::Array[::CSVPlusPlus::Row]) }
     # Apply expand= (adding rows to the results) modifiers to the parsed template. This happens in towards the end of
@@ -64,17 +69,17 @@ module CSVPlusPlus
         end
     end
 
-    sig { params(runtime: ::CSVPlusPlus::Runtime::Runtime).void }
+    sig { void }
     # 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)
+    def validate_infinite_expands
       infinite_expand_rows = @rows.filter { |r| r.modifier.expand&.infinite? }
       return unless infinite_expand_rows.length > 1
 
-      runtime.raise_modifier_syntax_error(
-        'You can only have one infinite expand= (on all others you must specify an amount)',
-        infinite_expand_rows[1].to_s
+      raise(
+        ::CSVPlusPlus::Error::ModifierSyntaxError.new(
+          'You can only have one infinite expand= (on all others you must specify an amount)',
+          bad_input: infinite_expand_rows[1].to_s
+        )
       )
     end
 
@@ -85,7 +90,7 @@ module CSVPlusPlus
     def verbose_summary
       # TODO: we can probably include way more stats in here
       <<~SUMMARY
-        #{@runtime.verbose_summary}
+        #{@runtime.scope.verbose_summary}
 
         > #{@rows.length} rows to be written
       SUMMARY

data/lib/csv_plus_plus/version.rb

@@ -2,6 +2,6 @@
 # frozen_string_literal: true
 
 module CSVPlusPlus
-  VERSION = '0.1.3'
+  VERSION = '0.2.0'
   public_constant :VERSION
 end

data/lib/csv_plus_plus/writer/csv.rb

@@ -6,10 +6,20 @@ require_relative './file_backer_upper'
 module CSVPlusPlus
   module Writer
     # A class that can output a +Template+ to CSV
-    class CSV < ::CSVPlusPlus::Writer::BaseWriter
+    class CSV < ::CSVPlusPlus::Writer::Writer
       extend ::T::Sig
-
       include ::CSVPlusPlus::Writer::FileBackerUpper
+      include ::CSVPlusPlus::Writer::Merger
+
+      sig { params(options: ::CSVPlusPlus::Options::FileOptions, position: ::CSVPlusPlus::Runtime::Position).void }
+      # @param options [Options::FileOptions]
+      # @param position [Runtime::Position]
+      def initialize(options, position)
+        super(position)
+
+        @reader = ::T.let(::CSVPlusPlus::Reader::CSV.new(options), ::CSVPlusPlus::Reader::CSV)
+        @options = options
+      end
 
       sig { override.params(template: ::CSVPlusPlus::Template).void }
       # Write a +template+ to CSV
@@ -17,19 +27,36 @@ module CSVPlusPlus
       # @param template [Template] The template to use as input to be written.  It should have been compiled by calling
       #   Compiler#compile_template
       def write(template)
-        # TODO: also read it and merge the results
         ::CSV.open(@options.output_filename, 'wb') do |csv|
-          @runtime.map_rows(template.rows) do |row|
+          @position.map_rows(template.rows) do |row|
             csv << build_row(row)
           end
         end
       end
 
+      sig { override.void }
+      # Write a backup of the current spreadsheet.
+      def write_backup
+        backup_file(@options)
+      end
+
+      sig { params(cell: ::CSVPlusPlus::Cell).returns(::T.nilable(::String)) }
+      # Turn the cell into a CSV-
+      def evaluate_cell(cell)
+        if (ast = cell.ast)
+          "=#{ast.evaluate(@position)}"
+        else
+          cell.value
+        end
+      end
+
       private
 
       sig { params(row: ::CSVPlusPlus::Row).returns(::T::Array[::T.nilable(::String)]) }
       def build_row(row)
-        @runtime.map_row(row.cells) { |cell, _i| cell.evaluate(@runtime) }
+        @position.map_row(row.cells) do |cell, _i|
+          merge_cell_value(existing_value: @reader.value_at(cell), new_value: evaluate_cell(cell), options: @options)
+        end
       end
     end
   end

data/lib/csv_plus_plus/writer/excel.rb

@@ -7,23 +7,36 @@ require_relative './rubyxl_builder'
 module CSVPlusPlus
   module Writer
     # A class that can output a +Template+ to an Excel file
-    class Excel < ::CSVPlusPlus::Writer::BaseWriter
+    class Excel < ::CSVPlusPlus::Writer::Writer
       extend ::T::Sig
-
       include ::CSVPlusPlus::Writer::FileBackerUpper
 
+      sig { params(options: ::CSVPlusPlus::Options::FileOptions, position: ::CSVPlusPlus::Runtime::Position).void }
+      # @param options [Options::FileOptions]
+      # @param position [Runtime::Position]
+      def initialize(options, position)
+        super(position)
+
+        @options = options
+      end
+
       sig { override.params(template: ::CSVPlusPlus::Template).void }
       # Write the +template+ to an Excel file
       #
       # @param template [Template] The template to write
       def write(template)
         ::CSVPlusPlus::Writer::RubyXLBuilder.new(
-          input_filename: ::T.must(@options.output_filename),
-          rows: template.rows,
-          runtime: @runtime,
-          sheet_name: @options.sheet_name
+          options: @options,
+          position: @position,
+          rows: template.rows
         ).build_workbook.write(@options.output_filename)
       end
+
+      sig { override.void }
+      # Write a backup of the current spreadsheet.
+      def write_backup
+        backup_file(@options)
+      end
     end
   end
 end

data/lib/csv_plus_plus/writer/file_backer_upper.rb

@@ -1,4 +1,4 @@
-# typed: false
+# typed: strict
 # frozen_string_literal: true
 
 module CSVPlusPlus
@@ -6,32 +6,44 @@ module CSVPlusPlus
     # 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
+      include ::Kernel
+      extend ::T::Sig
+
       # 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
+      DESIRED_BACKUP_FORMATS = ::T.let(
+        [
+          %(%Y_%m_%d-%I_%M%p),
+          %(%Y_%m_%d-%I_%M_%S%p),
+          %(%Y_%m_%d-%I_%M_%S_%L%p)
+        ].freeze,
+        ::T::Array[::String]
+      )
       private_constant :DESIRED_BACKUP_FORMATS
 
+      sig { params(options: ::CSVPlusPlus::Options::FileOptions).returns(::T.nilable(::Pathname)) }
       # Assuming the underlying spreadsheet is file-based, create a backup of it
-      def write_backup
-        return unless ::File.exist?(@options.output_filename)
+      def backup_file(options)
+        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
+        attempt_backups(options).tap do |backed_up_to|
+          puts("Backed up #{options.output_filename} to #{backed_up_to}") if options.verbose
         end
       end
 
       private
 
+      sig { params(options: ::CSVPlusPlus::Options::FileOptions).returns(::Pathname) }
       # rubocop:disable Metrics/MethodLength
-      def attempt_backups
+      def attempt_backups(options)
         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)
+            filename = format_backup_filename(file_format, options.output_filename)
+            backed_up_to = backup(filename, options.output_filename)
 
             next filename unless backed_up_to
 
@@ -45,16 +57,17 @@ module CSVPlusPlus
       end
       # rubocop:enable Metrics/MethodLength
 
-      def backup(filename)
+      sig { params(filename: ::Pathname, output_filename: ::Pathname).returns(::T.nilable(::Pathname)) }
+      def backup(filename, output_filename)
         return if ::File.exist?(filename)
 
-        ::FileUtils.cp(@options.output_filename, filename)
+        ::FileUtils.cp(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)
+      sig { params(file_format: ::String, output_filename: ::Pathname).returns(::Pathname) }
+      def format_backup_filename(file_format, output_filename)
+        output_filename.sub_ext("-#{::Time.now.strftime(file_format)}" + output_filename.extname)
       end
     end
   end