hledger-forecast 0.4.0 → 1.0.0

data/lib/hledger_forecast/{summarize.rb → summarizer.rb}

@@ -1,37 +1,54 @@
 module HledgerForecast
   # Summarise a forecast YAML file and output it to the CLI
-  class Summarize
-    @table = nil
-    @generator = nil
-
-    def self.init_table
-      table = Terminal::Table.new
+  # TODO: Rename this to Summarizer and the main method becomes summarize
+  class Summarizer
+    def self.summarize(config, cli_options)
+      new.summarize(config, cli_options)
+    end
 
-      table.add_row([{ value: 'FORECAST SUMMARY'.bold, colspan: 3, alignment: :center }])
-      table.add_separator
+    def summarize(config, cli_options = nil)
+      @forecast = YAML.safe_load(config)
+      @settings = Settings.config(@forecast, cli_options)
+      @table = Terminal::Table.new
 
-      @table = table
+      generate(@forecast)
     end
 
-    def self.init_generator(forecast_data)
-      generator = HledgerForecast::Generator
-      generator.set_options(forecast_data)
+    private
+
+    def generate(forecast)
+      init_table
+
+      category_totals = {}
+      %w[monthly quarterly half-yearly yearly once custom].each do |period|
+        category_totals[period] = sum_transactions(forecast, period)
+      end
 
-      @generator = generator
+      add_categories_to_table(category_totals, forecast)
+
+      @table.add_separator
+      format_total("TOTAL", category_totals.values.map(&:values).flatten.sum)
+
+      @table
+    end
+
+    def init_table
+      @table.add_row([{ value: 'FORECAST SUMMARY'.bold, colspan: 3, alignment: :center }])
+      @table.add_separator
     end
 
-    def self.sum_transactions(forecast_data, period)
+    def sum_transactions(forecast, period)
       category_total = Hash.new(0)
-      forecast_data[period]&.each do |entry|
+      forecast[period]&.each do |entry|
         entry['transactions'].each do |transaction|
-          category_total[transaction['category']] += transaction['amount']
+          category_total[transaction['category']] += Calculator.new.evaluate(transaction['amount'])
         end
       end
 
       category_total
     end
 
-    def self.sum_custom_transactions(forecast_data)
+    def sum_custom_transactions(forecast_data)
       category_total = Hash.new(0)
       custom_periods = []
 
@@ -51,12 +68,12 @@ module HledgerForecast
       { totals: category_total, periods: custom_periods }
     end
 
-    def self.format_amount(amount)
-      formatted_amount = @generator.format_amount(amount)
+    def format_amount(amount)
+      formatted_amount = Formatter.format_money(amount, @settings)
       amount.to_f < 0 ? formatted_amount.green : formatted_amount.red
     end
 
-    def self.add_rows_to_table(row_data, period_total, custom: false)
+    def add_rows_to_table(row_data, period_total, custom: false)
       if custom
         row_data[:periods].each do |period|
           @table.add_row [{ value: period[:category], alignment: :left },
@@ -77,7 +94,7 @@ module HledgerForecast
       period_total
     end
 
-    def self.add_categories_to_table(categories, forecast_data)
+    def add_categories_to_table(categories, forecast_data)
       first_period = true
       categories.each do |period, total|
         category_total = total.reject { |_, amount| amount == 0 }
@@ -100,35 +117,16 @@ module HledgerForecast
       end
     end
 
-    def self.sort_transactions(category_total)
+    def sort_transactions(category_total)
       negatives = category_total.select { |_, amount| amount < 0 }.sort_by { |_, amount| amount }
       positives = category_total.select { |_, amount| amount > 0 }.sort_by { |_, amount| -amount }
 
       negatives.concat(positives).to_h
     end
 
-    def self.format_total(text, total)
+    def format_total(text, total)
       @table.add_row [{ value: text.bold, colspan: 2, alignment: :left },
-                      { value: format_amount(total).bold, alignment: :right }]
-    end
-
-    def self.generate(forecast)
-      forecast_data = YAML.safe_load(forecast)
-
-      init_table
-      init_generator(forecast_data)
-
-      category_totals = {}
-      %w[monthly quarterly half-yearly yearly once custom].each do |period|
-        category_totals[period] = sum_transactions(forecast_data, period)
-      end
-
-      add_categories_to_table(category_totals, forecast_data)
-
-      @table.add_separator
-      format_total("TOTAL", category_totals.values.map(&:values).flatten.sum)
-
-      puts @table
+                     { value: format_amount(total).bold, alignment: :right }]
     end
   end
 end

data/lib/hledger_forecast/transactions/default.rb

@@ -0,0 +1,88 @@
+module HledgerForecast
+  module Transactions
+    # Generate default hledger transactions
+    # Example output:
+    # ~ monthly from 2023-05-1  * Food expenses
+    #    Expenses:Groceries    $250.00 ;  Food expenses
+    #    Assets:Checking
+    class Default
+      def self.generate(data, options)
+        new(data, options).generate
+      end
+
+      def generate
+        data.each_value do |blocks|
+          blocks.each do |block|
+            process_block(block)
+          end
+        end
+
+        output
+      end
+
+      private
+
+      attr_reader :data, :options, :output
+
+      def initialize(data, options)
+        @data = data
+        @options = options
+        @output = []
+      end
+
+      def process_block(block)
+        block[:transactions].each do |to, transactions|
+          to = get_header(block[:to], to)
+          block[:descriptions] = get_descriptions(transactions)
+          frequency = get_periodic_rules(block[:type], block[:frequency])
+
+          header = "#{frequency} #{block[:from]}#{to}  * #{block[:descriptions]}\n"
+          footer = "    #{block[:account]}\n\n"
+
+          output << { header: header, transactions: write_transactions(transactions), footer: footer }
+        end
+      end
+
+      def get_header(block, transaction)
+        return " to #{transaction}" if transaction
+        return " to #{block}" if block
+
+        return nil
+      end
+
+      def get_descriptions(transactions)
+        transactions.map do |t|
+          # Skip transactions that have been marked as tracked
+          next if t[:track]
+
+          t[:description]
+        end.compact.join(', ')
+      end
+
+      def get_periodic_rules(type, frequency)
+        map = {
+          'once' => '~',
+          'monthly' => '~ monthly from',
+          'quarterly' => '~ every 3 months from',
+          'half-yearly' => '~ every 6 months from',
+          'yearly' => '~ yearly from',
+          'custom' => "~ #{frequency} from"
+        }
+
+        map[type]
+      end
+
+      def write_transactions(transactions)
+        transactions.map do |t|
+          # Skip transactions that have been marked as tracked
+          next if t[:track]
+
+          t[:amount] = t[:amount].to_s.ljust(options[:max_amount])
+          t[:category] = t[:category].ljust(options[:max_category])
+
+          "    #{t[:category]}    #{t[:amount]};  #{t[:description]}\n"
+        end
+      end
+    end
+  end
+end

data/lib/hledger_forecast/transactions/modifiers.rb

@@ -0,0 +1,90 @@
+module HledgerForecast
+  module Transactions
+    # Generate auto-posting hledger transactions
+    # Example output:
+    # = Expenses:Groceries date:2024-01-01..2025-12-31
+    #    Expenses:Groceries    *0.1 ;  Groceries
+    #    Assets:Checking       *-0.1
+    class Modifiers
+      def self.generate(data, options)
+        new(data, options).generate
+      end
+
+      def generate
+        return nil unless modifiers?
+
+        process_modifier
+
+        output
+      end
+
+      def self.get_modifiers(transaction, block)
+        modifiers = []
+
+        transaction['modifiers'].each do |modifier|
+          description = transaction['description']
+          description += " - #{modifier['description']}" unless modifier['description'].empty?
+
+          modifiers << {
+            account: block['account'],
+            amount: modifier['amount'],
+            category: transaction['category'],
+            description: description,
+            from: Date.parse(modifier['from'] || block['from']),
+            to: modifier['to'] ? Date.parse(modifier['to']) : nil
+          }
+        end
+
+        modifiers
+      end
+
+      private
+
+      attr_reader :data, :options, :output
+
+      def initialize(data, options)
+        @data = data
+        @options = options
+        @output = []
+      end
+
+      def modifiers?
+        @data.any? do |_, blocks|
+          blocks.any? do |block|
+            block[:transactions].any? do |_, transactions|
+              transactions.any? { |t| !t[:modifiers].empty? }
+            end
+          end
+        end
+      end
+
+      def process_modifier
+        get_transactions.each do |modifier|
+          account = modifier[:account].ljust(@options[:max_category])
+          category = modifier[:category].ljust(@options[:max_category])
+          # Fix the ljust by counting strings in amount
+          amount = modifier[:amount].to_s.ljust(@options[:max_amount] - 1)
+          to = modifier[:to] ? "..#{modifier[:to]}" : nil
+
+          header = "= #{modifier[:category]} date:#{modifier[:from]}#{to}\n"
+          transactions = "    #{category}    *#{amount};  #{modifier[:description]}\n"
+          footer = "    #{account}    *#{modifier[:amount] * -1}\n\n"
+
+          output << { header: header, transactions: [transactions], footer: footer }
+        end
+      end
+
+      def get_transactions
+        @data.each_with_object([]) do |(_key, blocks), result|
+          blocks.each do |block|
+            block[:transactions].each_value do |transactions|
+              transactions.each do |t|
+                result.concat(t[:modifiers]) if t[:modifiers]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hledger_forecast/transactions/trackers.rb

@@ -0,0 +1,87 @@
+module HledgerForecast
+  module Transactions
+    # Generate hledger transactions based on the non-existance of a transaction
+    # in your ledger. This is useful for ensuring that certain expenses are
+    # accounted for, even if you forget to enter them.
+    #
+    # Example output:
+    # ~ 2023-05-1  * [TRACKED] Food expenses
+    #    Expenses:Groceries    $250.00 ;  Food expenses
+    #    Assets:Checking
+    class Trackers
+      def self.generate(data, options)
+        new(data, options).generate
+      end
+
+      def generate
+        return nil unless tracked?(data)
+
+        data.each_value do |blocks|
+          blocks.each do |block|
+            process_tracked(block)
+          end
+        end
+
+        output
+      end
+
+      def self.track?(transaction, data, options)
+        now = Date.today
+        transaction['track'] && Date.parse(data['from']) <= now && !exists?(transaction, data['account'],
+                                                                            data['from'], now, options)
+      end
+
+      def self.exists?(transaction, account, from, to, options)
+        # Format the money
+        amount = Formatter.format_money(transaction['amount'], options)
+        inverse_amount = Formatter.format_money(transaction['amount'] * -1, options)
+
+        category = transaction['category'].gsub('[', '\\[').gsub(']', '\\]').gsub('(', '\\(').gsub(')', '\\)')
+
+        # We run two commands and check to see if category +/- amount or account +/- amount exists
+        command1 = %(hledger print -f #{options[:transaction_file]} "date:#{from}..#{to}" | tr -s '[:space:]' ' ' | grep -q -Eo "#{category} (#{amount}|#{inverse_amount})")
+        command2 = %(hledger print -f #{options[:transaction_file]} "date:#{from}..#{to}" | tr -s '[:space:]' ' ' | grep -q -Eo "#{account} (#{amount}|#{inverse_amount})")
+
+        system(command1) || system(command2)
+      end
+
+      private
+
+      attr_reader :data, :options, :output
+
+      def initialize(data, options)
+        @data = data
+        @options = options
+        @output = []
+      end
+
+      def tracked?(data)
+        data.any? do |_, blocks|
+          blocks.any? do |block|
+            block[:transactions].any? do |_, transactions|
+              transactions.any? { |t| t[:track] }
+            end
+          end
+        end
+      end
+
+      def process_tracked(block)
+        block[:transactions].each do |_to, transactions|
+          transactions.each do |t|
+            next unless t[:track]
+
+            category = t[:category].ljust(options[:max_category])
+            amount = t[:amount].to_s.ljust(options[:max_amount])
+
+            header = "~ #{Date.new(Date.today.year, Date.today.month,
+                                   1).next_month}  * [TRACKED] #{t[:description]}\n"
+            transactions = "    #{category}    #{amount};  #{t[:description]}\n"
+            footer = "    #{block[:account]}\n\n"
+
+            output << { header: header, transactions: [transactions], footer: footer }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "0.4.0"
+  VERSION = "1.0.0"
 end

data/lib/hledger_forecast.rb

@@ -12,8 +12,14 @@ require 'yaml'
 Money.locale_backend = nil
 Money.rounding_mode = BigDecimal::ROUND_HALF_UP
 
-require_relative 'hledger_forecast/version'
-require_relative 'hledger_forecast/generator'
-require_relative 'hledger_forecast/summarize'
-require_relative 'hledger_forecast/tracker'
+require_relative 'hledger_forecast/calculator'
 require_relative 'hledger_forecast/cli'
+require_relative 'hledger_forecast/formatter'
+require_relative 'hledger_forecast/generator'
+require_relative 'hledger_forecast/settings'
+require_relative 'hledger_forecast/summarizer'
+require_relative 'hledger_forecast/version'
+
+require_relative 'hledger_forecast/transactions/default'
+require_relative 'hledger_forecast/transactions/modifiers'
+require_relative 'hledger_forecast/transactions/trackers'

data/spec/custom_spec.rb

@@ -1,6 +1,6 @@
 require_relative '../lib/hledger_forecast'
 
-config = <<~YAML
+base_config = <<~YAML
   custom:
     - frequency: "every 2 weeks"
       from: "2023-05-01"
@@ -21,7 +21,7 @@ config = <<~YAML
     currency: GBP
 YAML
 
-output = <<~JOURNAL
+base_output = <<~JOURNAL
   ~ every 2 weeks from 2023-05-01  * Hair and beauty
       [Expenses:Personal Care]    £80.00;  Hair and beauty
       [Assets:Bank]
@@ -32,9 +32,36 @@ output = <<~JOURNAL
 
 JOURNAL
 
+calculated_config = <<~YAML
+  custom:
+    - frequency: "every 2 weeks"
+      from: "2023-05-01"
+      account: "[Assets:Bank]"
+      transactions:
+        - amount: 80
+          category: "[Expenses:Personal Care]"
+          description: Hair and beauty
+          to: "=6"
+
+  settings:
+    currency: GBP
+YAML
+
+calculated_output = <<~JOURNAL
+  ~ every 2 weeks from 2023-05-01 to 2023-10-31  * Hair and beauty
+      [Expenses:Personal Care]    £80.00;  Hair and beauty
+      [Assets:Bank]
+
+JOURNAL
+
 RSpec.describe 'generate' do
   it 'generates a forecast with correct CUSTOM transactions' do
-    generated_journal = HledgerForecast::Generator.generate(config)
-    expect(generated_journal).to eq(output)
+    generated_journal = HledgerForecast::Generator.generate(base_config)
+    expect(generated_journal).to eq(base_output)
+  end
+
+  it 'generates a forecast with correct CUSTOM transactions and CALCULATED to dates' do
+    generated_journal = HledgerForecast::Generator.generate(calculated_config)
+    expect(generated_journal).to eq(calculated_output)
   end
 end

data/spec/modifier_spec.rb

@@ -5,7 +5,7 @@ base_config = <<~YAML
     - account: "Assets:Bank"
       from: "2023-01-01"
       transactions:
-        - amount: 500
+        - amount: 300
           category: "Expenses:Groceries"
           description: Food shopping
           modifiers:
@@ -17,6 +17,17 @@ base_config = <<~YAML
               description: "Y2 inflation"
               from: "2025-01-01"
               to: "2025-12-31"
+    - account: "Assets:Savings"
+      from: "2023-05-01"
+      transactions:
+        - amount: 500
+          category: "Assets:Bank"
+          description: Savings
+          modifiers:
+            - amount: 0.1
+              description: "Savings uplift"
+              from: "2024-05-01"
+              to: "2025-04-30"
 
   settings:
     currency: USD
@@ -24,9 +35,13 @@ YAML
 
 base_journal = <<~JOURNAL
   ~ monthly from 2023-01-01  * Food shopping
-      Expenses:Groceries    $500.00;  Food shopping
+      Expenses:Groceries    $300.00;  Food shopping
       Assets:Bank
 
+  ~ monthly from 2023-05-01  * Savings
+      Assets:Bank           $500.00;  Savings
+      Assets:Savings
+
   = Expenses:Groceries date:2024-01-01..2024-12-31
       Expenses:Groceries    *0.02 ;  Food shopping - Y1 inflation
       Assets:Bank           *-0.02
@@ -35,6 +50,10 @@ base_journal = <<~JOURNAL
       Expenses:Groceries    *0.05 ;  Food shopping - Y2 inflation
       Assets:Bank           *-0.05
 
+  = Assets:Bank date:2024-05-01..2025-04-30
+      Assets:Bank           *0.1  ;  Savings - Savings uplift
+      Assets:Savings        *-0.1
+
 JOURNAL
 
 no_date_config = <<~YAML
@@ -67,20 +86,16 @@ JOURNAL
 RSpec.describe 'Applying modifiers to transactions -' do
   it 'Auto-postings should be created correctly' do
     generated = HledgerForecast::Generator
-    generated.modified = {} # Clear modified transactions
 
     generated_journal = generated.generate(base_config)
-    generated.modified = {} # Clear modified transactions
 
     expect(generated_journal).to eq(base_journal)
   end
 
   it 'Auto-postings should be created correctly if no dates are set' do
     generated = HledgerForecast::Generator
-    generated.modified = {} # Clear modified transactions
 
     generated_journal = generated.generate(no_date_config)
-    generated.modified = {} # Clear modified transactions
 
     expect(generated_journal).to eq(no_date_journal)
   end

data/spec/monthly_end_date_spec.rb

@@ -1,47 +1,32 @@
 require_relative '../lib/hledger_forecast'
 
 config = <<~YAML
-settings:
-  currency: GBP
+  settings:
+    currency: GBP
 
-monthly:
-  - from: "2023-03-01"
-    account: "Assets:Bank"
-    transactions:
-      - description: Mortgage
-        to: "2023-06-01"
-        category: "Expenses:Mortgage"
-        amount: 2000.00
-      - description: Mortgage top up
-        to: "2023-06-01"
-        category: "Expenses:Mortgage Top Up"
-        amount: 200.00
-      - description: Food
-        category: "Expenses:Food"
-        amount: 100.00
-      - description: Party time
-        category: "Expenses:Going Out"
-        amount: 50.00
+  monthly:
+    - from: "2023-03-01"
+      to: "2023-06-01"
+      account: "Assets:Bank"
+      transactions:
+        - description: Mortgage
+          category: "Expenses:Mortgage"
+          amount: 2000.00
+        - description: Food
+          category: "Expenses:Food"
+          amount: 100.00
 YAML
 
 output = <<~JOURNAL
-~ monthly from 2023-03-01  * Food, Party time
-    Expenses:Food               £100.00  ;  Food
-    Expenses:Going Out          £50.00   ;  Party time
-    Assets:Bank
-
-~ monthly from 2023-03-01 to 2023-06-01  * Mortgage
-    Expenses:Mortgage           £2,000.00;  Mortgage
-    Assets:Bank
-
-~ monthly from 2023-03-01 to 2023-06-01  * Mortgage top up
-    Expenses:Mortgage Top Up    £200.00  ;  Mortgage top up
-    Assets:Bank
+  ~ monthly from 2023-03-01 to 2023-06-01  * Mortgage, Food
+      Expenses:Mortgage    £2,000.00;  Mortgage
+      Expenses:Food        £100.00  ;  Food
+      Assets:Bank
 
 JOURNAL
 
 RSpec.describe 'generate' do
-  it 'generates a forecast with correct MONTHLY transactions that have an end date' do
+  it 'generates a forecast with correct MONTHLY transactions that have an end date, at the top level' do
     expect(HledgerForecast::Generator.generate(config)).to eq(output)
   end
 end