hledger-forecast 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 119f25363a44375cf21a44614306b714f9beacc8e6c87fd0cd8b527a601d039d
-  data.tar.gz: 7bc635c9122980d9c4f2d321b2572b39113f9b6db409d913fe0fc7468dabeb6e
+  metadata.gz: f6dc9ef51b0f8d7927eb2b798d66257b740fad83be62d86c8207a5982aac752f
+  data.tar.gz: aec51b551655e2927de40237c64db32cfd4f4ebc40c855cd2bf97601e27112e2
 SHA512:
-  metadata.gz: 6da28ae5b49a274894c089b0fad8adac80544beee0d1ff435cbd30c435c429a65ddec379d5e73efc09e0f6ad5eef6a30316d05a769a34b7a5ee902e13c58973d
-  data.tar.gz: 8acb5c8ab9e229eacc914e6cb2c341eb5fc57bb4e1f70d44e60904e5030de745e2e9357036c1f6fb5f7a56e4d56d592ea0da145ef4c508153512d2b6cdcbb938
+  metadata.gz: bf00818fbbb03977e633c1e4c4eba8dd3596a6150e87117aa04e2d4b0df94c83593bef598200fa524a5d7c1777ce0be4bec2c0c4f4f0f8c9cc362732a3c8a1dc
+  data.tar.gz: 7a093260f8624ba0a27ead898fcda52926a00cfa12ed9f3bf67e020eb8d3df0cdfe0aa498164f0d07975f7c39efac9f0c39dd282fdd14e6684328d94b3ebbac1

data/Gemfile

@@ -4,5 +4,6 @@ source "https://rubygems.org"
 
 gem 'colorize'
 gem 'money'
+gem 'terminal-table'
 
 gemspec

data/README.md

@@ -2,18 +2,17 @@
 
 [![Tests](https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml/badge.svg)](https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml)
 
-> **Warning**: This is still in the early stages of development and the API is likely to change
-
-Uses a YAML file to generate monthly, quarterly, yearly and one-off transactions for better forecasting in [Hledger](https://github.com/simonmichael/hledger).
+Uses a YAML file to generate periodic transactions for better forecasting in [Hledger](https://github.com/simonmichael/hledger).
 
 See the [rationale](#brain-rationale) section for why this gem may be useful to you.
 
 ## :sparkles: Features
 
 - :book: Uses a simple YAML config file to generate periodic transactions
-- :date: Specify start and end dates for forecasts
+- :date: Generate forecasts between specified start and end dates
 - :heavy_dollar_sign: Full currency support (uses the [RubyMoney](https://github.com/RubyMoney/money) gem)
 - :computer: Simple and easy to use CLI
+- :chart_with_upwards_trend: Summarize your forecasts by period and category and output to the CLI
 
 ## :package: Installation
 
@@ -23,10 +22,12 @@ Assuming you have Ruby and [Rubygems](http://rubygems.org/pages/download) instal
 
 ## :rocket: Usage
 
-Simply run:
+Run:
 
     hledger-forecast
 
+> **Note**: This assumes that a `forecast.yml` exists in the current working directory
+
 Running `hledger-forecast -h` shows the available options:
 
     Usage: Hledger-Forecast [options]
@@ -41,18 +42,28 @@ Running `hledger-forecast -h` shows the available options:
         -h, --help                       Show this message
             --version                    Show version
 
-To then include in Hledger:
+Another example of a common command:
+
+    hledger-forecast -f my_forecast.yml -s 2023-05-01 -e 2024-12-31
+
+This will generate an output file (`my_forecast.journal`) from the forecast file between the two date ranges.
+
+### Using with Hledger
+
+To use the outputs in Hledger:
 
-    hledger -f transactions.journal -f forecast.journal
+    hledger -f transactions.journal -f my_forecast.journal
 
 where:
 
 - `transactions.journal` might be your bank transactions (your "_actuals_")
-- `forecast.journal` is the generated forecast file
+- `my_forecast.journal` is the generated forecast file
 
-### A simple config file
+## :gear: Configuration
 
-> **Note**: See the [example.yml](https://github.com/olimorris/hledger-forecast/blob/main/example.yml) file for all of the options
+### The YAML file
+
+> **Note**: See the [example.yml](https://github.com/olimorris/hledger-forecast/blob/main/example.yml) file for an example of a complex config file
 
 Firstly, create a `yml` file which will contain the transactions you'd like to forecast:
 
@@ -68,6 +79,9 @@ monthly:
       - amount: 500
         category: "[Expenses:Food]"
         description: Food
+
+settings:
+  currency: GBP
 ```
 
 Let's examine what's going on in this config file:
@@ -77,50 +91,98 @@ Let's examine what's going on in this config file:
 - Notice we're also using [virtual postings](https://hledger.org/1.29/hledger.html#virtual-postings) (designated by the brackets). This makes it easy to filter them out with the `-R` or `--real` option in Hledger
 - We also have not specified a currency; the default (`USD`) will be used
 
-### Extending the config file
+### Periods
 
-#### Periods
+Besides monthly recurring transactions, the app also supports the following periods:
 
-If you'd like to add quarterly, half-yearly, yearly or one-off transactions, use the following keys:
+- `quarterly` - For transactions every _3 months_ from the given start date
+- `half-yearly` - For transactions every _6 months_ from the given start date
+- `yearly` - Generate transactions _once a year_ from the given start date
+- `once` - Generate _one-time_ transactions on a specified date
+- `custom` - Generate transactions every _n days/weeks/months_
 
-- `quarterly`
-- `half-yearly`
-- `yearly`
-- `once`
+#### Custom period
 
-The structure of the config file remains exactly the same.
+A custom period allows you to specify a given number of days, weeks or months for a transaction to repeat within. These can be included in the config file as follows:
 
-> **Note**: A quarterly transaction will repeat for every 3 months from the start date
+```yaml
+custom:
+  - description: Fortnightly hair and beauty spend
+    recurrence:
+      period: weeks
+      quantity: 2
+    account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 80
+        category: "[Expenses:Personal Care]"
+        description: Hair and beauty
+```
+
+Where `quantity` is an integer and `period` is one of:
+
+- days
+- weeks
+- months
 
-#### Currency
+### Dates
 
-To specify a currency:
+The core of any solid forecast is predicting the correct periods that costs will fall into. When running the app from the CLI, you can specify specific dates to generate transactions over (see the [usage](#rocket-usage) section).
+
+You can further control the dates at a period/top-level as well as at a transaction level:
+
+#### Top level
+
+In the example below, all transactions in the `monthly` block will be constrained by the end date:
 
 ```yaml
-# forecast.yml
-settings:
-  currency: GBP
+monthly:
+  - account: "[Assets:Bank]"
+    start: "2023-03-01"
+    end: "2025-01-01"
+    transactions:
+      # details omitted for brevity
 ```
 
-#### Additional settings
+#### Transaction level
 
-Additional settings in the config file:
+In the example below, only the single transaction will be constrained by the end date and controlled via an additional start date:
+
+```yaml
+monthly:
+  - account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 2000
+        category: "[Expenses:Mortgage]"
+        description: Mortgage
+        start: "2023-05-01"
+        end: "2025-01-01"
+```
+
+The addition of the `start` key means that while the block will start on 2023-03-01, the transaction for the mortgage won't start until `2023-05-01`.
+
+### Additional settings
+
+Additional settings in the config file to consider:
 
 ```yaml
-# forecast.yml
 settings:
+  currency: GBP                 # Specify the currency to use
   show_symbol: true             # Show the currency symbol?
   sign_before_symbol: true      # Show the negative sign before the symbol?
   thousands_separator: true     # Separate thousands with a comma?
 ```
 
-### Summarizing the config file
+## :rainbow: Helpers
+
+### Summarizing the forecast file
 
 As your config file grows, it can be helpful to sum up the total amounts and output them in the CLI. This can be achieved by:
 
-    hledger-forecast -f forecast.yml --summarize
+    hledger-forecast -f my_forecast.yml --summarize
 
-where `forecast.yml` is the config file to sum up.
+where `my_forecast.yml` is the config file to sum up.
 
 ## :brain: Rationale
 
@@ -128,8 +190,8 @@ Firstly, I've come to realise from reading countless blog and Reddit posts on [p
 
 My days working in financial modelling have meant that a big macro-enabled spreadsheet was my go-to tool. Growing tired with the manual approach of importing transactions, heavily manipulating them, watching Excel become increasingly slower lead me to PTA. It's been a wonderful discovery.
 
-One of the aspects of my previous approach to personal finance that I liked was the monthly recap of my performance and the looking ahead to the future. Am I still on track to hit my year-end savings goal? Am I still on track to hit my savings goal for 12, 24 months time? It was at this point in my shift to PTA that I hit a wall.
+One of the aspects of my previous approach to personal finance that I liked was the monthly recap of my performance and the looking ahead to the future. Am I still on track to hit my year-end savings goal given my future commitments? Am I still on track to hit my savings goal in 12 and 24 months time? It was at this point in my shift to PTA that I found it difficult to answer those questions with Hledger.
 
-While Hledger provides support for [forecasting](https://hledger.org/1.29/hledger.html#forecasting) using periodic transactions, these are computed virtually at runtime. If I notice a big difference in my forecasted year-end balance compared to what I'm expecting, I want to investigate and start reconcilling. Computed transactions make this difficult and tiresome.
+While there is support for [forecasting](https://hledger.org/1.29/hledger.html#forecasting) using periodic transactions in Hledger, these are computed virtually at runtime. If I notice a big difference in my forecasted year-end balance compared to what I'm expecting, I want to investigate and start reconcilling. Computed transactions make this nigh on impossible to unpick. Also, I get a lot of value out of running different forecast scenarios and seeing the impact. For example, _"what's my savings balance looking like in 3 years time if I get the kitchen remodelled?"_.
 
-With this gem, my aim was to make it easy for users to change a config file, re-run a CLI command and be able to open a text file and see the changes. No guesswork. No surprises.
+With this gem, my aim was to make it easy for users to change their config file, regenerate the forecast and open a journal file and see the transactions. Or, use multiple forecast files for different scenarios and pass them in turn to Hledger to observe the impact.

data/example.yml

@@ -1,17 +1,24 @@
 monthly:
   - account: "[Assets:Bank]"
-    date: "2023-03-01"
+    start: "2023-03-01"
     transactions:
-      - amount: 1000.00
-        category: "[Expenses:Mortgage]"
-        description: Mortgage
+      - amount: -100
+        category: "[Income:Bonus]"
+        description: Bonus
+      - amount: -2000
+        category: "[Income:Salary]"
+        description: Salary
       - amount: 500.00
         category: "[Expenses:Food]"
         description: Food
+      - amount: 1000.00
+        category: "[Expenses:Mortgage]"
+        description: Mortgage
+        end: "2024-01-01"
 
 quarterly:
   - account: "[Assets:Bank]"
-    date: "2023-04-01"
+    start: "2023-04-01"
     transactions:
       - amount: -1000.00
         category: "[Income:Bonus]"
@@ -19,7 +26,7 @@ quarterly:
 
 half-yearly:
   - account: "[Assets:Bank]"
-    date: "2023-04-01"
+    start: "2023-04-01"
     transactions:
       - amount: 500
         category: "[Expenses:Holiday]"
@@ -27,7 +34,7 @@ half-yearly:
 
 yearly:
   - account: "[Assets:Bank]"
-    date: "2023-04-01"
+    start: "2023-04-01"
     transactions:
       - amount: -2000.00
         category: "[Income:Bonus]"
@@ -35,12 +42,24 @@ yearly:
 
 once:
   - account: "[Assets:Bank]"
-    date: "2024-01-01"
+    start: "2024-01-01"
     transactions:
       - amount: 5000.00
         category: "[Expenses:Car]"
         description: Forecast new car cost
 
+custom:
+  - description: Fuel every 5 days
+    recurrence:
+      period: days
+      quantity: 5
+    account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 150
+        category: "[Expenses:Car:Fuel]"
+        description: Car fuel
+
 settings:
   currency: GBP
   show_symbol: true

data/hledger-forecast.gemspec

@@ -15,6 +15,7 @@ Gem::Specification.new do |s|
   s.add_dependency "highline", "~> 2.1.0"
   s.add_dependency "money", "~> 6.16.0"
   s.add_dependency "colorize", "~> 0.8.1"
+  s.add_dependency "terminal-table", "~> 3.0.2"
   s.add_development_dependency 'rspec', '~> 3.12'
 
   s.files = `git ls-files`.split("\n")

data/lib/hledger_forecast/generator.rb

@@ -1,7 +1,6 @@
 module HledgerForecast
   # Generates journal entries based on a YAML forecast file.
   # on forecast data and optional existing transactions.
-  #
   class Generator
     class << self
       attr_accessor :settings
@@ -26,15 +25,46 @@ module HledgerForecast
       formatted_transaction = transaction.clone
 
       formatted_transaction['amount'] =
-        Money.from_cents(formatted_transaction['amount'].to_i * 100, @settings[:currency]).format(
+        Money.from_cents(formatted_transaction['amount'].to_f * 100, @settings[:currency]).format(
           symbol: @settings[:show_symbol],
           sign_before_symbol: @settings[:sign_before_symbol],
-          thousands_separator: @settings[:thousands_separator] ? ',' : nil,
+          thousands_separator: @settings[:thousands_separator] ? ',' : nil
         )
 
       formatted_transaction
     end
 
+    def self.process_custom(output, forecast_data, date)
+      forecast_data['custom']&.each do |forecast|
+        start_date = Date.parse(forecast['start'])
+        end_date = forecast['end'] ? Date.parse(forecast['end']) : nil
+        account = forecast['account']
+        period = forecast['recurrence']['period']
+        quantity = forecast['recurrence']['quantity']
+
+        next if end_date && date > end_date
+
+        date_matches = case period
+                       when 'days'
+                         (date - start_date).to_i % quantity == 0
+                       when 'weeks'
+                         (date - start_date).to_i % (quantity * 7) == 0
+                       when 'months'
+                         ((date.year * 12 + date.month) - (start_date.year * 12 + start_date.month)) % quantity == 0 && date.day == start_date.day
+                       end
+
+        if date_matches
+          forecast['transactions'].each do |transaction|
+            end_date = transaction['end'] ? Date.parse(transaction['end']) : nil
+
+            next unless end_date.nil? || date <= end_date
+
+            write_transactions(output, date, account, format_transaction(transaction))
+          end
+        end
+      end
+    end
+
     def self.process_forecast(output_file, forecast_data, type, date)
       forecast_data[type]&.each do |forecast|
         start_date = Date.parse(forecast['start'])
@@ -58,9 +88,12 @@ module HledgerForecast
 
         if date_matches
           forecast['transactions'].each do |transaction|
-            end_date = transaction['end'] ? Date.parse(transaction['end']) : nil
+            transaction_start_date = transaction['start'] ? Date.parse(transaction['start']) : nil
+            transaction_end_date = transaction['end'] ? Date.parse(transaction['end']) : nil
 
-            next unless end_date.nil? || date <= end_date
+            if (transaction_start_date && date < transaction_start_date) || (transaction_end_date && date > transaction_end_date)
+              next
+            end
 
             write_transactions(output_file, date, account, format_transaction(transaction))
           end
@@ -86,6 +119,7 @@ module HledgerForecast
         process_forecast(output, forecast_data, 'half-yearly', date)
         process_forecast(output, forecast_data, 'yearly', date)
         process_forecast(output, forecast_data, 'once', date)
+        process_custom(output, forecast_data, date)
 
         date = date.next_day
       end

data/lib/hledger_forecast/options.rb

@@ -10,6 +10,7 @@ module HledgerForecast
         opts.on("-f", "--forecast FILE",
                 "The FORECAST yaml file to generate from") do |file|
           options[:forecast_file] = file
+          options[:output_file] ||= file.sub(/\.yml$/, '.journal')
         end
 
         opts.on("-t", "--transaction FILE",

data/lib/hledger_forecast/summarize.rb

@@ -1,68 +1,135 @@
 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
+
+      table.add_row([{ value: 'FORECAST SUMMARY'.bold, colspan: 3, alignment: :center }])
+      table.add_separator
+
+      @table = table
+    end
+
+    def self.init_generator(forecast_data)
+      generator = HledgerForecast::Generator
+      generator.configure_settings(forecast_data)
+
+      @generator = generator
+    end
+
     def self.sum_transactions(forecast_data, period)
-      category_totals = Hash.new(0)
+      category_total = Hash.new(0)
       forecast_data[period]&.each do |entry|
         entry['transactions'].each do |transaction|
-          category_totals[transaction['category']] += transaction['amount']
+          category_total[transaction['category']] += transaction['amount']
         end
       end
-      category_totals
+
+      category_total
     end
 
-    def self.print_category_totals(period, category_totals, generator)
-      puts "#{period.capitalize}:"
-      period_total = 0
+    def self.sum_custom_transactions(forecast_data)
+      category_total = Hash.new(0)
+      custom_periods = []
+
+      forecast_data['custom']&.each do |entry|
+        period_data = {}
+        period_data[:quantity] = entry['recurrence']['quantity']
+        period_data[:period] = entry['recurrence']['period']
+        period_data[:category] = entry['transactions'].first['category']
+        period_data[:amount] = entry['transactions'].first['amount']
+
+        entry['transactions'].each do |transaction|
+          category_total[transaction['category']] += transaction['amount']
+        end
 
-      category_totals.each do |category, amount|
-        formatted_amount = generator.format_transaction({ 'amount' => amount })['amount']
-        formatted_amount = amount.to_i < 0 ? formatted_amount.red : formatted_amount.green
-        puts "  #{category.ljust(40)}#{formatted_amount}"
-        period_total += amount
+        custom_periods << period_data
       end
 
-      formatted_period_total = generator.format_transaction({ 'amount' => period_total })['amount']
-      formatted_period_total = period_total.to_i < 0 ? formatted_period_total.red : formatted_period_total.green
-      puts "  TOTAL".ljust(42) + formatted_period_total
+      { totals: category_total, periods: custom_periods }
     end
 
-    def self.sum_all_periods(forecast_data)
-      periods = %w[monthly quarterly half-yearly yearly once]
-      total = {}
-      grand_total = 0
+    def self.format_amount(amount)
+      formatted_amount = @generator.format_transaction({ 'amount' => amount })['amount']
+      amount.to_f < 0 ? formatted_amount.green : formatted_amount.red
+    end
+
+    def self.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 },
+                          { value: "every #{period[:quantity]} #{period[:period]}", alignment: :right },
+                          { value: format_amount(period[:amount]), alignment: :right }]
+
+          period_total += period[:amount]
+        end
+      else
+        row_data.each do |category, amount|
+          @table.add_row [{ value: category, colspan: 2, alignment: :left },
+                          { value: format_amount(amount), alignment: :right }]
 
-      periods.each do |period|
-        total[period] = sum_transactions(forecast_data, period)
-        grand_total += total[period]
+          period_total += amount
+        end
       end
 
-      total['total'] = grand_total
-      total
+      period_total
     end
 
-    def self.generate(forecast)
-      forecast_data = YAML.safe_load(forecast)
+    def self.add_categories_to_table(categories, forecast_data)
+      first_period = true
+      categories.each do |period, total|
+        category_total = total.reject { |_, amount| amount == 0 }
+        next if category_total.empty?
+
+        sorted_category_total = sort_transactions(category_total)
+
+        @table.add_separator unless first_period
+        @table.add_row([{ value: period.capitalize.bold, colspan: 3, alignment: :center }])
 
-      category_totals_by_period = {}
-      %w[monthly quarterly half-yearly yearly once].each do |period|
-        category_totals_by_period[period] = sum_transactions(forecast_data, period)
+        period_total = 0
+        period_total += if period == 'custom'
+                          add_rows_to_table(sum_custom_transactions(forecast_data), period_total, custom: true)
+                        else
+                          add_rows_to_table(sorted_category_total, period_total)
+                        end
+
+        format_total("#{period.capitalize} TOTAL", period_total)
+        first_period = false
       end
+    end
 
-      grand_total = category_totals_by_period.values.map(&:values).flatten.sum
+    def self.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 }
 
-      generator = HledgerForecast::Generator
-      generator.configure_settings(forecast_data)
+      negatives.concat(positives).to_h
+    end
+
+    def self.format_total(text, total)
+      @table.add_row [{ value: text.bold, colspan: 2, alignment: :left },
+                      { value: format_amount(total).bold, alignment: :right }]
+    end
 
-      puts
-      category_totals_by_period.each do |period, category_totals|
-        print_category_totals(period, category_totals, generator)
-        puts
+    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
 
-      formatted_grand_total = generator.format_transaction({ 'amount' => grand_total })['amount']
-      formatted_grand_total = grand_total.to_i < 0 ? formatted_grand_total.red : formatted_grand_total.green
-      puts "TOTAL:".ljust(42) + formatted_grand_total
+      add_categories_to_table(category_totals, forecast_data)
+
+      @table.add_separator
+      format_total("TOTAL", category_totals.values.map(&:values).flatten.sum)
+
+      puts @table
     end
   end
 end

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "0.1.7"
+  VERSION = "0.1.9"
 end

data/lib/hledger_forecast.rb

@@ -5,6 +5,7 @@ require 'date'
 require 'highline'
 require 'money'
 require 'optparse'
+require 'terminal-table'
 require 'yaml'
 
 Money.locale_backend = nil

data/spec/custom_spec.rb

@@ -0,0 +1,47 @@
+require_relative '../lib/hledger_forecast'
+
+RSpec.describe 'generate' do
+  it 'generates a forecast with correct CUSTOM DAILY transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/custom/forecast_custom_days.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01',
+                                                                          '2023-03-10')
+
+    expected_output = File.read('spec/stubs/custom/output_custom_days.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+
+  it 'generates a forecast with correct CUSTOM WEEKlY transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/custom/forecast_custom_weeks.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01',
+                                                                          '2023-04-30')
+
+    expected_output = File.read('spec/stubs/custom/output_custom_weeks.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+
+  it 'generates a forecast with MULTIPLE correct CUSTOM WEEKlY transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/custom/forecast_custom_weeks_twice.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01',
+                                                                          '2023-03-30')
+
+    expected_output = File.read('spec/stubs/custom/output_custom_weeks_twice.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+
+  it 'generates a forecast with correct CUSTOM MONTHLY transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/custom/forecast_custom_months.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01',
+                                                                          '2024-02-28')
+
+    expected_output = File.read('spec/stubs/custom/output_custom_months.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+end

data/spec/start_date_spec.rb

@@ -0,0 +1,12 @@
+require_relative '../lib/hledger_forecast'
+RSpec.describe 'generate' do
+  it 'generates a forecast with correct MONTHLY transactions that have a START DATE' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/start_date/forecast_startdate.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-08-30')
+
+    expected_output = File.read('spec/stubs/start_date/output_startdate.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+end

data/spec/stubs/custom/forecast_custom_days.yml

@@ -0,0 +1,14 @@
+custom:
+  - description: Repeat every 3 days
+    recurrence:
+      period: days
+      quantity: 3
+    account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 80
+        category: "[Expenses:Personal Care]"
+        description: Hair and beauty
+
+settings:
+  currency: GBP

data/spec/stubs/custom/forecast_custom_months.yml

@@ -0,0 +1,14 @@
+custom:
+  - description: Repeat every 5 months
+    recurrence:
+      period: months
+      quantity: 5
+    account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 100
+        category: "[Expenses:Personal Care]"
+        description: Hair and beauty
+
+settings:
+  currency: GBP

data/spec/stubs/custom/forecast_custom_weeks.yml

@@ -0,0 +1,14 @@
+custom:
+  - description: Repeat every 2 weeks
+    recurrence:
+      period: weeks
+      quantity: 2
+    account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 75
+        category: "[Expenses:Personal Care]"
+        description: Hair and beauty
+
+settings:
+  currency: GBP

data/spec/stubs/custom/forecast_custom_weeks_twice.yml

@@ -0,0 +1,24 @@
+custom:
+  - description: Beauty expenses every 2 weeks
+    recurrence:
+      period: weeks
+      quantity: 2
+    account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 75
+        category: "[Expenses:Personal Care]"
+        description: Hair and beauty
+  - description: Car fuel every 5 days
+    recurrence:
+      period: days
+      quantity: 5
+    account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 150
+        category: "[Expenses:Car:Fuel]"
+        description: Car Fuel
+
+settings:
+  currency: GBP

data/spec/stubs/custom/output_custom_days.journal

@@ -0,0 +1,24 @@
+2023-02-01 * Opening balance
+    Assets:Bank                             £1,000.00
+    Equity:Opening balance
+
+2023-02-05 * Mortgage payment
+    Expenses:Mortgage                 £1,500.00
+    Assets:Bank
+
+2023-03-01 * Hair and beauty
+    [Expenses:Personal Care]                £80.00
+    [Assets:Bank]
+
+2023-03-04 * Hair and beauty
+    [Expenses:Personal Care]                £80.00
+    [Assets:Bank]
+
+2023-03-07 * Hair and beauty
+    [Expenses:Personal Care]                £80.00
+    [Assets:Bank]
+
+2023-03-10 * Hair and beauty
+    [Expenses:Personal Care]                £80.00
+    [Assets:Bank]
+

data/spec/stubs/custom/output_custom_months.journal

@@ -0,0 +1,20 @@
+2023-02-01 * Opening balance
+    Assets:Bank                             £1,000.00
+    Equity:Opening balance
+
+2023-02-05 * Mortgage payment
+    Expenses:Mortgage                 £1,500.00
+    Assets:Bank
+
+2023-03-01 * Hair and beauty
+    [Expenses:Personal Care]                £100.00
+    [Assets:Bank]
+
+2023-08-01 * Hair and beauty
+    [Expenses:Personal Care]                £100.00
+    [Assets:Bank]
+
+2024-01-01 * Hair and beauty
+    [Expenses:Personal Care]                £100.00
+    [Assets:Bank]
+

data/spec/stubs/custom/output_custom_weeks.journal

@@ -0,0 +1,28 @@
+2023-02-01 * Opening balance
+    Assets:Bank                             £1,000.00
+    Equity:Opening balance
+
+2023-02-05 * Mortgage payment
+    Expenses:Mortgage                 £1,500.00
+    Assets:Bank
+
+2023-03-01 * Hair and beauty
+    [Expenses:Personal Care]                £75.00
+    [Assets:Bank]
+
+2023-03-15 * Hair and beauty
+    [Expenses:Personal Care]                £75.00
+    [Assets:Bank]
+
+2023-03-29 * Hair and beauty
+    [Expenses:Personal Care]                £75.00
+    [Assets:Bank]
+
+2023-04-12 * Hair and beauty
+    [Expenses:Personal Care]                £75.00
+    [Assets:Bank]
+
+2023-04-26 * Hair and beauty
+    [Expenses:Personal Care]                £75.00
+    [Assets:Bank]
+

data/spec/stubs/custom/output_custom_weeks_twice.journal

@@ -0,0 +1,44 @@
+2023-02-01 * Opening balance
+    Assets:Bank                             £1,000.00
+    Equity:Opening balance
+
+2023-02-05 * Mortgage payment
+    Expenses:Mortgage                 £1,500.00
+    Assets:Bank
+
+2023-03-01 * Hair and beauty
+    [Expenses:Personal Care]                £75.00
+    [Assets:Bank]
+
+2023-03-01 * Car Fuel
+    [Expenses:Car:Fuel]                £150.00
+    [Assets:Bank]
+
+2023-03-06 * Car Fuel
+    [Expenses:Car:Fuel]                £150.00
+    [Assets:Bank]
+
+2023-03-11 * Car Fuel
+    [Expenses:Car:Fuel]                £150.00
+    [Assets:Bank]
+
+2023-03-15 * Hair and beauty
+    [Expenses:Personal Care]                £75.00
+    [Assets:Bank]
+
+2023-03-16 * Car Fuel
+    [Expenses:Car:Fuel]                £150.00
+    [Assets:Bank]
+
+2023-03-21 * Car Fuel
+    [Expenses:Car:Fuel]                £150.00
+    [Assets:Bank]
+
+2023-03-26 * Car Fuel
+    [Expenses:Car:Fuel]                £150.00
+    [Assets:Bank]
+
+2023-03-29 * Hair and beauty
+    [Expenses:Personal Care]                £75.00
+    [Assets:Bank]
+

data/spec/stubs/modifiers/forecast_modifiers.yml

@@ -0,0 +1,13 @@
+monthly:
+  - account: "[Assets:Bank]"
+    start: "2023-03-01"
+    transactions:
+      - amount: 2000
+        category: "[Expenses:Mortgage]"
+        description: Mortgage
+        modifier:
+          amount: 2.0
+          period: yearly
+
+settings:
+  currency: GBP

data/spec/stubs/modifiers/output_modifiers.journal

@@ -0,0 +1,44 @@
+2023-02-01 * Opening balance
+    Assets:Bank                             £1,000.00
+    Equity:Opening balance
+
+2023-02-05 * Mortgage payment
+    Expenses:Mortgage                 £1,500.00
+    Assets:Bank
+
+2023-03-01 * Mortgage
+    [Expenses:Mortgage]                £2,000.00
+    [Assets:Bank]
+
+2023-03-01 * Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+
+2023-03-01 * Savings
+    [Assets:Bank]                -£1,000.00
+    [Assets:Savings]
+
+2023-04-01 * Mortgage
+    [Expenses:Mortgage]                £2,000.00
+    [Assets:Bank]
+
+2023-04-01 * Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+
+2023-04-01 * Savings
+    [Assets:Bank]                -£1,000.00
+    [Assets:Savings]
+
+2023-05-01 * Mortgage
+    [Expenses:Mortgage]                £2,000.00
+    [Assets:Bank]
+
+2023-05-01 * Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+
+2023-05-01 * Savings
+    [Assets:Bank]                -£1,000.00
+    [Assets:Savings]
+

data/spec/stubs/monthly/forecast_monthly.yml

@@ -2,12 +2,18 @@ monthly:
   - account: "[Assets:Bank]"
     start: "2023-03-01"
     transactions:
-      - amount: 2000
+      - amount: 2000.55
         category: "[Expenses:Mortgage]"
         description: Mortgage
       - amount: 100
         category: "[Expenses:Food]"
         description: Food
+  - account: "[Assets:Savings]"
+    start: "2023-03-01"
+    transactions:
+      - amount: -1000
+        category: "[Assets:Bank]"
+        description: Savings
 
 settings:
   currency: GBP

data/spec/stubs/monthly/output_monthly.journal

@@ -7,26 +7,38 @@
     Assets:Bank
 
 2023-03-01 * Mortgage
-    [Expenses:Mortgage]                £2,000.00
+    [Expenses:Mortgage]                £2,000.55
     [Assets:Bank]
 
 2023-03-01 * Food
     [Expenses:Food]                £100.00
     [Assets:Bank]
 
+2023-03-01 * Savings
+    [Assets:Bank]                -£1,000.00
+    [Assets:Savings]
+
 2023-04-01 * Mortgage
-    [Expenses:Mortgage]                £2,000.00
+    [Expenses:Mortgage]                £2,000.55
     [Assets:Bank]
 
 2023-04-01 * Food
     [Expenses:Food]                £100.00
     [Assets:Bank]
 
+2023-04-01 * Savings
+    [Assets:Bank]                -£1,000.00
+    [Assets:Savings]
+
 2023-05-01 * Mortgage
-    [Expenses:Mortgage]                £2,000.00
+    [Expenses:Mortgage]                £2,000.55
     [Assets:Bank]
 
 2023-05-01 * Food
     [Expenses:Food]                £100.00
     [Assets:Bank]
 
+2023-05-01 * Savings
+    [Assets:Bank]                -£1,000.00
+    [Assets:Savings]
+

data/spec/stubs/start_date/forecast_startdate.yml

@@ -0,0 +1,26 @@
+settings:
+  currency: GBP
+
+monthly:
+  - start: "2023-03-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Monthly Mortgage
+        start: "2023-06-01"
+        category: "[Expenses:Mortgage]"
+        amount: 2000
+      - description: Monthly Food
+        category: "[Expenses:Food]"
+        amount: 100
+
+quarterly:
+  - start: "2023-04-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Quarterly Mortgage
+        start: "2023-07-01"
+        category: "[Expenses:Mortgage]"
+        amount: 1000
+      - description: Quarterly Food
+        category: "[Expenses:Food]"
+        amount: 50

data/spec/stubs/start_date/output_startdate.journal

@@ -0,0 +1,56 @@
+2023-02-01 * Opening balance
+    Assets:Bank                             £1,000.00
+    Equity:Opening balance
+
+2023-02-05 * Mortgage payment
+    Expenses:Mortgage                 £1,500.00
+    Assets:Bank
+
+2023-03-01 * Monthly Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+
+2023-04-01 * Monthly Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+
+2023-04-01 * Quarterly Food
+    [Expenses:Food]                £50.00
+    [Assets:Bank]
+
+2023-05-01 * Monthly Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+
+2023-06-01 * Monthly Mortgage
+    [Expenses:Mortgage]                £2,000.00
+    [Assets:Bank]
+
+2023-06-01 * Monthly Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+
+2023-07-01 * Monthly Mortgage
+    [Expenses:Mortgage]                £2,000.00
+    [Assets:Bank]
+
+2023-07-01 * Monthly Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+
+2023-07-01 * Quarterly Mortgage
+    [Expenses:Mortgage]                £1,000.00
+    [Assets:Bank]
+
+2023-07-01 * Quarterly Food
+    [Expenses:Food]                £50.00
+    [Assets:Bank]
+
+2023-08-01 * Monthly Mortgage
+    [Expenses:Mortgage]                £2,000.00
+    [Assets:Bank]
+
+2023-08-01 * Monthly Food
+    [Expenses:Food]                £100.00
+    [Assets:Bank]
+

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-15 00:00:00.000000000 Z
+date: 2023-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.8.1
+- !ruby/object:Gem::Dependency
+  name: terminal-table
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.0.2
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -90,12 +104,24 @@ files:
 - lib/hledger_forecast/summarize.rb
 - lib/hledger_forecast/version.rb
 - spec/command_spec.rb
+- spec/custom_spec.rb
 - spec/half-yearly_spec.rb
 - spec/monthly_spec.rb
 - spec/once_spec.rb
 - spec/quarterly_spec.rb
+- spec/start_date_spec.rb
+- spec/stubs/custom/forecast_custom_days.yml
+- spec/stubs/custom/forecast_custom_months.yml
+- spec/stubs/custom/forecast_custom_weeks.yml
+- spec/stubs/custom/forecast_custom_weeks_twice.yml
+- spec/stubs/custom/output_custom_days.journal
+- spec/stubs/custom/output_custom_months.journal
+- spec/stubs/custom/output_custom_weeks.journal
+- spec/stubs/custom/output_custom_weeks_twice.journal
 - spec/stubs/half-yearly/forecast_half-yearly.yml
 - spec/stubs/half-yearly/output_half-yearly.journal
+- spec/stubs/modifiers/forecast_modifiers.yml
+- spec/stubs/modifiers/output_modifiers.journal
 - spec/stubs/monthly/forecast_monthly.yml
 - spec/stubs/monthly/forecast_monthly_enddate.yml
 - spec/stubs/monthly/forecast_monthly_enddate_top.yml
@@ -108,6 +134,8 @@ files:
 - spec/stubs/once/output_once.journal
 - spec/stubs/quarterly/forecast_quarterly.yml
 - spec/stubs/quarterly/output_quarterly.journal
+- spec/stubs/start_date/forecast_startdate.yml
+- spec/stubs/start_date/output_startdate.journal
 - spec/stubs/transactions.journal
 - spec/stubs/yearly/forecast_yearly.yml
 - spec/stubs/yearly/output_yearly.journal
@@ -131,18 +159,30 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.12
 signing_key:
 specification_version: 4
 summary: Utility to generate forecasts in Hledger
 test_files:
 - spec/command_spec.rb
+- spec/custom_spec.rb
 - spec/half-yearly_spec.rb
 - spec/monthly_spec.rb
 - spec/once_spec.rb
 - spec/quarterly_spec.rb
+- spec/start_date_spec.rb
+- spec/stubs/custom/forecast_custom_days.yml
+- spec/stubs/custom/forecast_custom_months.yml
+- spec/stubs/custom/forecast_custom_weeks.yml
+- spec/stubs/custom/forecast_custom_weeks_twice.yml
+- spec/stubs/custom/output_custom_days.journal
+- spec/stubs/custom/output_custom_months.journal
+- spec/stubs/custom/output_custom_weeks.journal
+- spec/stubs/custom/output_custom_weeks_twice.journal
 - spec/stubs/half-yearly/forecast_half-yearly.yml
 - spec/stubs/half-yearly/output_half-yearly.journal
+- spec/stubs/modifiers/forecast_modifiers.yml
+- spec/stubs/modifiers/output_modifiers.journal
 - spec/stubs/monthly/forecast_monthly.yml
 - spec/stubs/monthly/forecast_monthly_enddate.yml
 - spec/stubs/monthly/forecast_monthly_enddate_top.yml
@@ -155,6 +195,8 @@ test_files:
 - spec/stubs/once/output_once.journal
 - spec/stubs/quarterly/forecast_quarterly.yml
 - spec/stubs/quarterly/output_quarterly.journal
+- spec/stubs/start_date/forecast_startdate.yml
+- spec/stubs/start_date/output_startdate.journal
 - spec/stubs/transactions.journal
 - spec/stubs/yearly/forecast_yearly.yml
 - spec/stubs/yearly/output_yearly.journal