hledger-forecast 0.1.8 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e4232c29fd944d0483590e646c0c5e1566357ec8dfc9f942007cdea6121dcad
-  data.tar.gz: 2a8636024b63cdce5cfe7bbec937c123a9f78492bfb53ac873f40e9aa00d204d
+  metadata.gz: a21d32c5ee145d0bca5cb25f07a2fbb6f65126f16c5e15faf2ca11b3fbfac03c
+  data.tar.gz: bbf889db9f129ca62550399b2f2e7818936eee667d356bbeb52b476f305fe6b1
 SHA512:
-  metadata.gz: 0a725ff17d252a8d2427ba4e2dd2c6fa90d10e4cc9e853a6d9293eebde6aa9a594c96a9e57f387c858767b03b56e3bb3717b49bee7adc64d32a47bcd93118ebe
-  data.tar.gz: 118d14cde7575795a9e6632b856b4a9a60392aa19d88ce4030e555f49b580aa0cd924a61e9d6970bfe1e26306b848af756337f50eb2fc48203662714f1edd4a3
+  metadata.gz: b0fa4ad6d50c30eac65acc292d96f500182e211b1a4b9e039dfcff0f204a32ad01d9c01a7570535301bffeb6be865c720d6b8be8ba3e17370a2b992586f351d5
+  data.tar.gz: 554a06876170c161d35b68eececa7904b190aaa0fb6611e2a8bd672fad9b02b48a5a5e26e013db857671fd6f50e33242cb19ddf907fafb31b1b1bd27b74f86df

data/README.md

@@ -8,7 +8,7 @@ See the [rationale](#brain-rationale) section for why this gem may be useful to
 
 ## :sparkles: Features
 
-- :book: Uses a simple YAML config file to generate periodic transactions
+- :book: Uses simple YAML files to generate forecasts from periodic transactions
 - :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
@@ -24,27 +24,25 @@ Assuming you have Ruby and [Rubygems](http://rubygems.org/pages/download) instal
 
 Run:
 
-    hledger-forecast
+    hledger-forecast generate
 
 > **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]
+    Usage: Hledger-Forecast generate [options]
 
-        -f, --forecast FILE              The FORECAST yaml file to generate from
         -t, --transaction FILE           The base TRANSACTIONS file to extend from
+        -f, --forecast FILE              The FORECAST yaml file to generate from
         -o, --output-file FILE           The OUTPUT file to create
         -s, --start-date DATE            The date to start generating from (yyyy-mm-dd)
         -e, --end-date DATE              The date to start generating to (yyyy-mm-dd)
             --force                      Force an overwrite of the output file
-            --summarize                  Summarize the forecast file and output to the terminal
-        -h, --help                       Show this message
-            --version                    Show version
+        -h, --help                       Show this help message
 
 Another example of a common command:
 
-    hledger-forecast -f my_forecast.yml -s 2023-05-01 -e 2024-12-31
+    hledger-forecast generate -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.
 
@@ -59,7 +57,9 @@ where:
 - `transactions.journal` might be your bank transactions (your "_actuals_")
 - `my_forecast.journal` is the generated forecast file
 
-### A simple config file
+## :gear: Configuration
+
+### 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
 
@@ -89,9 +89,7 @@ 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:
 
@@ -101,12 +99,11 @@ Besides monthly recurring transactions, the app also supports the following peri
 - `once` - Generate _one-time_ transactions on a specified date
 - `custom` - Generate transactions every _n days/weeks/months_
 
-##### Custom period
+#### Custom period
 
 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:
 
 ```yaml
-# forecast.yml
 custom:
   - description: Fortnightly hair and beauty spend
     recurrence:
@@ -126,18 +123,17 @@ Where `quantity` is an integer and `period` is one of:
 - weeks
 - months
 
-#### Date constraints
+### Dates
 
 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
+#### Top level
 
 In the example below, all transactions in the `monthly` block will be constrained by the end date:
 
 ```yaml
-# forecast.yml
 monthly:
   - account: "[Assets:Bank]"
     start: "2023-03-01"
@@ -146,12 +142,11 @@ monthly:
       # details omitted for brevity
 ```
 
-##### Transaction level
+#### Transaction level
 
-In the example below, only the single transaction will be constrained by the end date:
+In the example below, only the single transaction will be constrained by the end date and controlled via an additional start date:
 
 ```yaml
-# forecast.yml
 monthly:
   - account: "[Assets:Bank]"
     start: "2023-03-01"
@@ -159,15 +154,17 @@ monthly:
       - amount: 2000
         category: "[Expenses:Mortgage]"
         description: Mortgage
+        start: "2023-05-01"
         end: "2025-01-01"
 ```
 
-#### Additional settings
+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?
@@ -175,11 +172,13 @@ settings:
   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 my_forecast.yml --summarize
+    hledger-forecast summarize -f my_forecast.yml
 
 where `my_forecast.yml` is the config file to sum up.
 
@@ -189,8 +188,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 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.
+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 performance to date and my future commitments? And what about my savings goal in 12 and 24 months time? Or, how much are my financial positions impacted if inflation increases by x%? It was at this point in my shift to PTA that I found it difficult to answer those questions quickly.
 
-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?"_.
+While there is support in Hledger 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 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 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/bin/hledger-forecast

@@ -3,10 +3,10 @@
 require_relative '../lib/hledger_forecast'
 
 begin
-  options = HledgerForecast::Options.parse_command_line_options
+  subcommand, options = HledgerForecast::Cli.parse_commands
 rescue RuntimeError => e
   puts("ERROR: #{e}")
   exit(1)
 end
 
-HledgerForecast::Cli.run(options)
+HledgerForecast::Cli.run(subcommand, options)

data/example.yml

@@ -2,13 +2,29 @@ monthly:
   - account: "[Assets:Bank]"
     start: "2023-03-01"
     transactions:
+      - amount: -100
+        category: "[Income:Bonus]"
+        description: Bonus
+      - amount: -2000
+        category: "[Income:Salary]"
+        description: Salary
+      - amount: 500.00
+        category: "[Expenses:Food]"
+        description: Food
+      - amount: 75
+        category: "[Expenses:Phone]"
+        description: New cell phone
+        start: "2023-08-01"
       - amount: 1000.00
         category: "[Expenses:Mortgage]"
         description: Mortgage
         end: "2024-01-01"
-      - amount: 500.00
-        category: "[Expenses:Food]"
-        description: Food
+  - account: "[Assets:Savings]"
+    start: "2023-03-01"
+    transactions:
+      - amount: -500
+        category: "[Income:Pension]"
+        description: Pension draw down
 
 quarterly:
   - account: "[Assets:Bank]"

data/lib/hledger_forecast/cli.rb

@@ -1,19 +1,163 @@
 module HledgerForecast
+  # The Command Line Interface for the application
+  # Takes user arguments and translates them into actions
   class Cli
-    def self.run(args)
-      end_date = args[:end_date]
-      start_date = args[:start_date]
-      forecast = File.read(args[:forecast_file])
-      transactions = args[:transactions_file] ? File.read(args[:transactions_file]) : nil
 
-      return HledgerForecast::Summarize.generate(forecast) if args[:summarize]
+    def self.run(subcommand, options)
+      case subcommand
+      when 'generate'
+        generate(options)
+      when 'summarize'
+        summarize(options)
+      else
+        puts "Unknown command: #{subcommand}"
+        exit(1)
+      end
+    end
+
+    def self.parse_commands(args = ARGV, _stdin = $stdin)
+      subcommand = nil
+      options = {}
+
+      global = OptionParser.new do |opts|
+        opts.banner = "Usage: hledger-forecast [subcommand] [options]"
+        opts.separator ""
+        opts.separator "Subcommands:"
+        opts.separator "  generate    Generate the forecast file"
+        opts.separator "  summarize   Summarize the forecast file and output to the terminal"
+        opts.separator ""
+        opts.separator "Options:"
+
+        opts.on_tail("-h", "--help", "Show this help message") do
+          puts opts
+          exit
+        end
+
+        opts.on_tail("-v", "--version", "Show version") do
+          puts VERSION
+          exit
+        end
+      end
+
+      begin
+        global.order!(args)
+        subcommand = args.shift || 'generate'
+      rescue OptionParser::InvalidOption => e
+        puts e
+        puts global
+        exit(1)
+      end
+
+      case subcommand
+      when 'generate'
+        options = parse_generate_options(args)
+      when 'summarize'
+        options = parse_summarize_options(args)
+      else
+        puts "Unknown subcommand: #{subcommand}"
+        puts global
+        exit(1)
+      end
+
+      return subcommand, options
+    end
+
+    def self.parse_generate_options(args)
+      options = {}
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: Hledger-Forecast generate [options]"
+        opts.separator ""
+
+        opts.on("-t", "--transaction FILE",
+                "The base TRANSACTIONS file to extend from") do |file|
+          options[:transactions_file] = file if file && !file.empty?
+        end
+
+        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("-o", "--output-file FILE",
+                "The OUTPUT file to create") do |file|
+          options[:output_file] = file
+        end
+
+        opts.on("-s", "--start-date DATE",
+                "The date to start generating from (yyyy-mm-dd)") do |a|
+          options[:start_date] = a
+        end
+
+        opts.on("-e", "--end-date DATE",
+                "The date to start generating to (yyyy-mm-dd)") do |a|
+          options[:end_date] = a
+        end
+
+        opts.on("--force",
+                "Force an overwrite of the output file") do |a|
+          options[:force] = a
+        end
+
+        opts.on_tail("-h", "--help", "Show this help message") do
+          puts opts
+          exit
+        end
+      end.parse!(args)
+
+      options[:forecast_file] = "forecast.yml" unless options[:forecast_file]
+      options[:output_file] = "forecast.journal" unless options[:output_file]
+
+      today = Date.today
+
+      unless options[:start_date]
+        options[:default_dates] = true
+        options[:start_date] =
+          Date.new(today.year, today.month, 1).next_month.to_s
+      end
+      unless options[:end_date]
+        options[:default_dates] = true
+        options[:end_date] = Date.new(today.year + 3, 12, 31).to_s
+      end
+
+      options
+    end
+
+    def self.parse_summarize_options(args)
+      options = {}
 
-      puts "[Using default dates: #{start_date} to #{end_date}]" if args[:default_dates]
+      OptionParser.new do |opts|
+        opts.banner = "Usage: Hledger-Forecast summarize [options]"
+        opts.separator ""
+
+        opts.on("-f", "--forecast FILE",
+                "The FORECAST yaml file to summarize") do |file|
+          options[:forecast_file] = file
+        end
 
-      transactions = Generator.create_journal_entries(transactions, forecast, start_date, end_date)
+        opts.on_tail("-h", "--help", "Show this help message") do
+          puts opts
+          exit
+        end
+      end.parse!(args)
+
+      options
+    end
 
-      output_file = args[:output_file]
-      if File.exist?(output_file) && !args[:force]
+    def self.generate(options)
+      end_date = options[:end_date]
+      start_date = options[:start_date]
+      forecast = File.read(options[:forecast_file])
+      transactions = options[:transactions_file] ? File.read(options[:transactions_file]) : nil
+
+      # Generate the forecast
+      puts "[Using default dates: #{start_date} to #{end_date}]" if options[:default_dates]
+
+      transactions = Generator.generate(transactions, forecast, start_date, end_date)
+
+      output_file = options[:output_file]
+      if File.exist?(output_file) && !options[:force]
         print "File '#{output_file}' already exists. Overwrite? (y/n): "
         overwrite = gets.chomp.downcase
 
@@ -28,5 +172,49 @@ module HledgerForecast
         puts "File '#{output_file}' has been created."
       end
     end
+
+    def self.summarize(options)
+      forecast = File.read(options[:forecast_file])
+      puts Summarize.generate(forecast)
+    end
+
+    # def self.run(args)
+    #   end_date = args[:end_date]
+    #   start_date = args[:start_date]
+    #   forecast = File.read(args[:forecast_file])
+    #   transactions = args[:transactions_file] ? File.read(args[:transactions_file]) : nil
+    #
+    #   # Output the summary
+    #   return HledgerForecast::Summarize.generate(forecast) if args[:summarize]
+    #
+    #   # Generate the forecast
+    #   unless args[:skip]
+    #
+    #     puts "[Using default dates: #{start_date} to #{end_date}]" if args[:default_dates]
+    #
+    #     transactions = Generator.generate(transactions, forecast, start_date, end_date)
+    #
+    #     output_file = args[:output_file]
+    #     if File.exist?(output_file) && !args[:force]
+    #       print "File '#{output_file}' already exists. Overwrite? (y/n): "
+    #       overwrite = gets.chomp.downcase
+    #
+    #       if overwrite == 'y'
+    #         File.write(output_file, transactions)
+    #         puts "File '#{output_file}' has been overwritten."
+    #       else
+    #         puts "Operation aborted. File '#{output_file}' was not overwritten."
+    #       end
+    #     else
+    #       File.write(output_file, transactions)
+    #       puts "File '#{output_file}' has been created."
+    #     end
+    #   end
+    #
+    #   # Check for missing transactions
+    #   return unless args[:check] && args[:transactions_file] && args[:forecast_file]
+    #
+    #   HledgerForecast::Checker.check(args)
+    # end
   end
 end

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,7 +25,7 @@ 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
@@ -89,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
@@ -99,7 +101,7 @@ module HledgerForecast
       end
     end
 
-    def self.create_journal_entries(transactions, forecast, start_date, end_date)
+    def self.generate(transactions, forecast, start_date, end_date)
       start_date = Date.parse(start_date)
       end_date = Date.parse(end_date)
       forecast_data = YAML.safe_load(forecast)

data/lib/hledger_forecast/summarize.rb

@@ -1,132 +1,135 @@
 module HledgerForecast
   # Summarise a forecast YAML file and output it to the CLI
   class Summarize
-    def self.sum_transactions(forecast_data, period)
-      category_totals = Hash.new(0)
-      forecast_data[period]&.each do |entry|
-        entry['transactions'].each do |transaction|
-          category_totals[transaction['category']] += transaction['amount']
-        end
-      end
-
-      category_totals
-    end
+    @table = nil
+    @generator = nil
 
-    def self.print_category_totals(period, category_totals, generator)
-      puts "#{period.capitalize}:"
-      period_total = 0
+    def self.init_table
+      table = Terminal::Table.new
 
-      category_totals.each do |category, amount|
-        formatted_amount = generator.format_transaction({ 'amount' => amount })['amount']
-        formatted_amount = amount.to_i < 0 ? formatted_amount.green : formatted_amount.red
-        puts "  #{category.ljust(40)}#{formatted_amount}"
-        period_total += amount
-      end
+      table.add_row([{ value: 'FORECAST SUMMARY'.bold, colspan: 3, alignment: :center }])
+      table.add_separator
 
-      formatted_period_total = generator.format_transaction({ 'amount' => period_total })['amount']
-      formatted_period_total = period_total.to_i < 0 ? formatted_period_total.green : formatted_period_total.red
-      puts "  TOTAL".ljust(42) + formatted_period_total
+      @table = table
     end
 
-    def self.sum_all_periods(forecast_data)
-      periods = %w[monthly quarterly half-yearly yearly once]
-      total = {}
-      grand_total = 0
+    def self.init_generator(forecast_data)
+      generator = HledgerForecast::Generator
+      generator.configure_settings(forecast_data)
 
-      (periods + ['custom']).each do |period|
-        total[period] = sum_transactions(forecast_data, period)
-        grand_total += total[period]
+      @generator = generator
+    end
+
+    def self.sum_transactions(forecast_data, period)
+      category_total = Hash.new(0)
+      forecast_data[period]&.each do |entry|
+        entry['transactions'].each do |transaction|
+          category_total[transaction['category']] += transaction['amount']
+        end
       end
 
-      total['total'] = grand_total
-      total
+      category_total
     end
 
     def self.sum_custom_transactions(forecast_data)
-      category_totals = Hash.new(0)
+      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[:description] = entry['transactions'].first['description']
         period_data[:category] = entry['transactions'].first['category']
         period_data[:amount] = entry['transactions'].first['amount']
 
         entry['transactions'].each do |transaction|
-          category_totals[transaction['category']] += transaction['amount']
+          category_total[transaction['category']] += transaction['amount']
         end
 
         custom_periods << period_data
       end
 
-      { totals: category_totals, periods: custom_periods }
+      { totals: category_total, periods: custom_periods }
     end
 
-    def self.generate(forecast)
-      forecast_data = YAML.safe_load(forecast)
-
-      category_totals_by_period = {}
-      %w[monthly quarterly half-yearly yearly once custom].each do |period|
-        category_totals_by_period[period] = sum_transactions(forecast_data, period)
-      end
+    def self.format_amount(amount)
+      formatted_amount = @generator.format_transaction({ 'amount' => amount })['amount']
+      amount.to_f < 0 ? formatted_amount.green : formatted_amount.red
+    end
 
-      grand_total = category_totals_by_period.values.map(&:values).flatten.sum
+    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 }]
 
-      generator = HledgerForecast::Generator
-      generator.configure_settings(forecast_data)
+          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 }]
 
-      table = Terminal::Table.new
+          period_total += amount
+        end
+      end
 
-      table.add_row([{ value: 'FORECAST SUMMARY', colspan: 3, alignment: :center }])
-      table.add_separator
+      period_total
+    end
 
+    def self.add_categories_to_table(categories, forecast_data)
       first_period = true
-      category_totals_by_period.each do |period, category_totals|
-        non_zero_totals = category_totals.select { |_, amount| amount != 0 }
-        next if non_zero_totals.empty?
+      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, colspan: 3, alignment: :center }])
+        @table.add_separator unless first_period
+        @table.add_row([{ value: period.capitalize.bold, colspan: 3, alignment: :center }])
 
         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
 
-        if period == 'custom'
-          custom_periods_data = sum_custom_transactions(forecast_data)
-          custom_periods_data[:periods].each do |custom_period|
-            formatted_amount = generator.format_transaction({ 'amount' => custom_period[:amount] })['amount']
-            formatted_amount = custom_period[:amount].to_i < 0 ? formatted_amount.green : formatted_amount.red
-            table.add_row [{ value: custom_period[:category], alignment: :left },
-                           { value: "every #{custom_period[:quantity]} #{custom_period[:period]}", alignment: :right }, { value: formatted_amount, alignment: :right }]
-            period_total += custom_period[:amount]
-          end
-        else
-          non_zero_totals.each do |category, amount|
-            formatted_amount = generator.format_transaction({ 'amount' => amount })['amount']
-            formatted_amount = amount.to_i < 0 ? formatted_amount.green : formatted_amount.red
-
-            table.add_row [{ value: category, colspan: 2, alignment: :left },
-                           { value: formatted_amount, alignment: :right }]
-            period_total += amount
-          end
-        end
+        format_total("#{period.capitalize} TOTAL", period_total)
+        first_period = false
+      end
+    end
 
-        formatted_period_total = generator.format_transaction({ 'amount' => period_total })['amount']
-        formatted_period_total = period_total.to_i < 0 ? formatted_period_total.green : formatted_period_total.red
-        table.add_row [{ value: "#{period.capitalize} TOTAL", colspan: 2, alignment: :left },
-                       { value: formatted_period_total, alignment: :right }]
+    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 }
 
-        first_period = false
+      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
+
+    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
 
-      table.add_separator
-      formatted_grand_total = generator.format_transaction({ 'amount' => grand_total })['amount']
-      formatted_grand_total = grand_total.to_i < 0 ? formatted_grand_total.green : formatted_grand_total.red
-      table.add_row [{ value: 'TOTAL', colspan: 2, alignment: :left },
-                     { value: formatted_grand_total, alignment: :right }]
+      add_categories_to_table(category_totals, forecast_data)
+
+      @table.add_separator
+      format_total("TOTAL", category_totals.values.map(&:values).flatten.sum)
 
-      puts table
+      puts @table
     end
   end
 end

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "0.1.8"
+  VERSION = "0.2.0"
 end

data/lib/hledger_forecast.rb

@@ -12,7 +12,7 @@ Money.locale_backend = nil
 Money.rounding_mode = BigDecimal::ROUND_HALF_UP
 
 require_relative 'hledger_forecast/version'
-require_relative 'hledger_forecast/options'
 require_relative 'hledger_forecast/generator'
 require_relative 'hledger_forecast/summarize'
+require_relative 'hledger_forecast/checker'
 require_relative 'hledger_forecast/cli'

data/spec/command_spec.rb

@@ -2,11 +2,14 @@ require_relative '../lib/hledger_forecast'
 
 RSpec.describe 'command' do
   it 'uses the CLI to generate an output' do
-    system("./bin/hledger-forecast -t ./spec/stubs/transactions.journal -f ./spec/stubs/monthly/forecast_monthly.yml -o ./test_output.journal -s 2023-03-01 -e 2023-05-30 --force")
+    # Delete the file if it exists
+    generated_journal = './test_output.journal'
+    File.delete(generated_journal) if File.exist?(generated_journal)
+
+    system("./bin/hledger-forecast generate -t ./spec/stubs/transactions.journal -f ./spec/stubs/monthly/forecast_monthly.yml -o ./test_output.journal -s 2023-03-01 -e 2023-05-30 --force")
 
     expected_output = File.read('spec/stubs/monthly/output_monthly.journal')
-    generated_journal = File.read('./test_output.journal')
 
-    expect(generated_journal).to eq(expected_output)
+    expect(File.read(generated_journal)).to eq(expected_output)
   end
 end

data/spec/custom_spec.rb

@@ -5,7 +5,7 @@ RSpec.describe 'generate' 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',
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01',
                                                                           '2023-03-10')
 
     expected_output = File.read('spec/stubs/custom/output_custom_days.journal')
@@ -16,7 +16,7 @@ RSpec.describe 'generate' 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',
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01',
                                                                           '2023-04-30')
 
     expected_output = File.read('spec/stubs/custom/output_custom_weeks.journal')
@@ -27,7 +27,7 @@ RSpec.describe 'generate' 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',
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01',
                                                                           '2023-03-30')
 
     expected_output = File.read('spec/stubs/custom/output_custom_weeks_twice.journal')
@@ -38,7 +38,7 @@ RSpec.describe 'generate' 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',
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01',
                                                                           '2024-02-28')
 
     expected_output = File.read('spec/stubs/custom/output_custom_months.journal')

data/spec/half-yearly_spec.rb

@@ -5,7 +5,7 @@ RSpec.describe 'generate' do
     transactions = File.read('spec/stubs/transactions.journal')
     forecast = File.read('spec/stubs/half-yearly/forecast_half-yearly.yml')
 
-    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2024-04-30')
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01', '2024-04-30')
 
     expected_output = File.read('spec/stubs/half-yearly/output_half-yearly.journal')
     expect(generated_journal).to eq(expected_output)

data/spec/monthly_spec.rb

@@ -5,7 +5,7 @@ RSpec.describe 'generate' do
     transactions = File.read('spec/stubs/transactions.journal')
     forecast = File.read('spec/stubs/monthly/forecast_monthly.yml')
 
-    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-05-30')
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01', '2023-05-30')
 
     expected_output = File.read('spec/stubs/monthly/output_monthly.journal')
     expect(generated_journal).to eq(expected_output)
@@ -15,7 +15,7 @@ RSpec.describe 'generate' do
     transactions = File.read('spec/stubs/transactions.journal')
     forecast = File.read('spec/stubs/monthly/forecast_monthly_enddate.yml')
 
-    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-08-30')
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01', '2023-08-30')
 
     expected_output = File.read('spec/stubs/monthly/output_monthly_enddate.journal')
     expect(generated_journal).to eq(expected_output)
@@ -25,7 +25,7 @@ RSpec.describe 'generate' do
     transactions = File.read('spec/stubs/transactions.journal')
     forecast = File.read('spec/stubs/monthly/forecast_monthly_enddate_top.yml')
 
-    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-08-30')
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01', '2023-08-30')
 
     expected_output = File.read('spec/stubs/monthly/output_monthly_enddate_top.journal')
     expect(generated_journal).to eq(expected_output)

data/spec/once_spec.rb

@@ -5,7 +5,7 @@ RSpec.describe 'generate' do
     transactions = File.read('spec/stubs/transactions.journal')
     forecast = File.read('spec/stubs/once/forecast_once.yml')
 
-    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2024-04-30')
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01', '2024-04-30')
 
     expected_output = File.read('spec/stubs/once/output_once.journal')
     expect(generated_journal).to eq(expected_output)

data/spec/quarterly_spec.rb

@@ -5,7 +5,7 @@ RSpec.describe 'generate' do
     transactions = File.read('spec/stubs/transactions.journal')
     forecast = File.read('spec/stubs/quarterly/forecast_quarterly.yml')
 
-    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2023-10-30')
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01', '2023-10-30')
 
     expected_output = File.read('spec/stubs/quarterly/output_quarterly.journal')
     expect(generated_journal).to eq(expected_output)

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.generate(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/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,7 +2,7 @@ monthly:
   - account: "[Assets:Bank]"
     start: "2023-03-01"
     transactions:
-      - amount: 2000
+      - amount: 2000.55
         category: "[Expenses:Mortgage]"
         description: Mortgage
       - amount: 100

data/spec/stubs/monthly/output_monthly.journal

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

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]
+

data/spec/yearly_spec.rb

@@ -5,7 +5,7 @@ RSpec.describe 'generate' do
     transactions = File.read('spec/stubs/transactions.journal')
     forecast = File.read('spec/stubs/yearly/forecast_yearly.yml')
 
-    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2024-04-30')
+    generated_journal = HledgerForecast::Generator.generate(transactions, forecast, '2023-03-01', '2024-04-30')
 
     expected_output = File.read('spec/stubs/yearly/output_yearly.journal')
     expect(generated_journal).to eq(expected_output)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.2.0
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-04-17 00:00:00.000000000 Z
+date: 2023-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -100,7 +100,6 @@ files:
 - lib/hledger_forecast.rb
 - lib/hledger_forecast/cli.rb
 - lib/hledger_forecast/generator.rb
-- lib/hledger_forecast/options.rb
 - lib/hledger_forecast/summarize.rb
 - lib/hledger_forecast/version.rb
 - spec/command_spec.rb
@@ -109,6 +108,7 @@ files:
 - 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
@@ -119,6 +119,8 @@ files:
 - 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
@@ -131,6 +133,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
@@ -165,6 +169,7 @@ test_files:
 - 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
@@ -175,6 +180,8 @@ test_files:
 - 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
@@ -187,6 +194,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

data/lib/hledger_forecast/options.rb

@@ -1,77 +0,0 @@
-module HledgerForecast
-  class Options
-    def self.parse_command_line_options(args = ARGV, _stdin = $stdin)
-      options = {}
-
-      OptionParser.new do |opts|
-        opts.banner = "Usage: Hledger-Forecast [options]"
-        opts.separator ""
-
-        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",
-                "The base TRANSACTIONS file to extend from") do |file|
-          options[:transactions_file] = file if file && !file.empty?
-        end
-
-        opts.on("-o", "--output-file FILE",
-                "The OUTPUT file to create") do |file|
-          options[:output_file] = file
-        end
-
-        opts.on("-s", "--start-date DATE",
-                "The date to start generating from (yyyy-mm-dd)") do |a|
-          options[:start_date] = a
-        end
-
-        opts.on("-e", "--end-date DATE",
-                "The date to start generating to (yyyy-mm-dd)") do |a|
-          options[:end_date] = a
-        end
-
-        opts.on("--summarize",
-                "Summarize the forecast file and output to the terminal") do |a|
-          options[:summarize] = a
-        end
-
-        opts.on("--force",
-                "Force an overwrite of the output file") do |a|
-          options[:force] = a
-        end
-
-        opts.on_tail("-h", "--help", "Show this message") do
-          puts opts
-          exit
-        end
-
-        opts.on_tail("--version", "Show version") do
-          puts VERSION
-          exit
-        end
-
-        opts.parse!(args)
-      end
-
-      options[:forecast_file] = "forecast.yml" unless options[:forecast_file]
-      options[:output_file] = "forecast.journal" unless options[:output_file]
-
-      today = Date.today
-
-      unless options[:start_date]
-        options[:default_dates] = true
-        options[:start_date] =
-          Date.new(today.year, today.month, 1).next_month.to_s
-      end
-      unless options[:end_date]
-        options[:default_dates] = true
-        options[:end_date] = Date.new(today.year + 3, 12, 31).to_s
-      end
-
-      return options
-    end
-  end
-end