hledger-forecast 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01faf9619f0b906b089956c1b81c16766830be412a678336848a7bbe23f78cb7
-  data.tar.gz: c93786627631d0f589250a8c721d8360a9feddf6f9b21954cc49b0b6b206ff29
+  metadata.gz: 37dbc9f011b6a43fa1d186e92dfb77c3c184cdb4a7cc5ef690a77d53c57f4722
+  data.tar.gz: e71185f0ad678b45f1ffa155c89c491bd37d36307d845dd023b823db6ced42d4
 SHA512:
-  metadata.gz: 218ecb7ea26f4daee36981d345cf4a67052b6c3876f4f2090d608a86a10ba7e07889010fa91ab3618da60bfac98caf2c48bbdda78ab68f0290e744a580f75076
-  data.tar.gz: c3940bb307bbba32d374f0161ecaf5ca8bcdba2a1a0cafd0d1e4ea7f13ceea20a781dd0367eb02cd1c01fe73475f23fdcf1e520d3b76a9b7d875729971f221b7
+  metadata.gz: d25713fb91fde68daaa07f6809a3c567afc18864a759e47fd032c31cd78cbe195eba2919deff4547d2fe6888e032f7394af4012aea839d1fc6b3d4ee7b1e94bf
+  data.tar.gz: 363185c38d788ae91528dc1fde6e21201fc19bec673848202a43589c36c8be3f6fe8e54cb367bfb8652ea286eda6513ab38e86e20aef99f8b7011cb1351fed3b

data/README.md

@@ -1,4 +1,8 @@
-<h1 align="center">Hledger-Forecast</h1>
+<p align="center">
+<img src="https://github.com/olimorris/hledger-forecast/assets/9512444/5edb77e3-0ec6-4158-9b16-3978c1259879" alt="hledger-forecast" />
+</p>
+
+<h1 align="center">hledger-forecast</h1>
 
 <p align="center">
 <a href="https://github.com/olimorris/hledger-forecast/stargazers"><img src="https://img.shields.io/github/stars/olimorris/hledger-forecast?color=c678dd&logoColor=e06c75&style=for-the-badge"></a>
@@ -7,19 +11,18 @@
 <a href="https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/olimorris/hledger-forecast/ci.yml?branch=main&label=tests&style=for-the-badge"></a>
 </p>
 
-A wrapper which builds on [hledger's](https://github.com/simonmichael/hledger) [forecasting](https://hledger.org/dev/hledger.html#forecasting) capability. Uses a `yaml` config file to generate forecasts whilst adding functionality for future cost rises (e.g. inflation) and the automatic tracking of planned transactions.
+**"Improved", you say?** Using a _yaml_ file, forecasts can be quickly generated into a _journal_ file ready to be fed into [hledger](https://github.com/simonmichael/hledger). Forecasts can be easily constrained between dates, inflated by modifiers, tracked until they appear in your bank statements and summarized into your own daily/weekly/monthly/yearly personal forecast income and expenditure statement.
 
-See the [rationale](#brain-rationale) section for why this gem may be useful to you.
+I **strongly** recommend you read the [rationale](#paintbrush-rationale) section to see if this app might be useful to you.
 
 ## :sparkles: Features
 
 - :book: Uses a simple yaml file to generate forecasts which can be used with hledger
-- :date: Can smartly track forecasted transactions against actuals
+- :date: Can smartly track forecasts against your bank statement
 - :moneybag: Can automatically apply modifiers such as inflation/deflation to forecasts
-- :abacus: Supports calculated amounts in forecasts (uses the [Dentaku](https://github.com/rubysolo/dentaku) gem)
-- :heavy_dollar_sign: Full currency support (uses the [RubyMoney](https://github.com/RubyMoney/money) gem)
+- :abacus: Enables the use of maths in your forecasts (for amounts and dates)
+- :chart_with_upwards_trend: Display your forecasts as income and expenditure reports (e.g. daily, weekly, monthly)
 - :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
 
@@ -64,7 +67,7 @@ The available options are:
 
 Running the command with no options will assume a `forecast.yml` file exists.
 
-### Using with Hledger
+### Using with hledger
 
 To work with hledger, include the forecast file and use the `--forecast` flag:
 
@@ -76,7 +79,9 @@ The command will generate a forecast up to the end of Feb 2024, showing the bala
 
 ### Summarize command
 
-As your `yaml` configuration file grows, it can be helpful to sum up the total amounts and output them to the CLI. This can be achieved by:
+As your `yaml` configuration file grows, it can be helpful to sum up the total amounts and output them to the CLI.
+Furthermore, being able to see your monthly profit and loss statement _if_ you were to purchase that new item may
+influence your buying decision. In hledger-forecast, this can be achieved by:
 
     hledger-forecast summarize -f my_forecast.yml
 
@@ -84,8 +89,10 @@ The available options are:
 
     Usage: hledger-forecast summarize [options]
 
-        -f, --forecast FILE              The path to the FORECAST yaml file to summarize
-        -h, --help                       Show this help message
+    -f, --forecast FILE              The path to the FORECAST yaml file to summarize
+    -r, --roll-up PERIOD             The period to roll-up your forecasts into. One of:
+                                     [yearly], [half-yearly], [quarterly], [monthly], [weekly], [daily]
+    -h, --help                       Show this help message
 
 ## :gear: Configuration
 
@@ -183,9 +190,9 @@ monthly:
 It can also be useful to compute a `to` date by adding on a number of months to the `from` date. Extending the example above:
 
 ```yaml
-- amount: 2000
-  category: "Expenses:Mortgage"
-  description: Mortgage
+- amount: 125
+  category: "Expenses:Holiday"
+  description: Holiday
   to: "=12"
 ```
 
@@ -219,13 +226,13 @@ To mark transactions as available for tracking you may use the `track` option in
 
 ```yaml
 once:
-  account: "Assets:Bank"
-  from: "2023-03-05"
-  transactions:
-    - amount: 3000
-      category: "Expenses:Shopping"
-      description: Refund for that damn laptop
-      track: true
+  - account: "Assets:Bank"
+    from: "2023-03-05"
+    transactions:
+      - amount: -3000
+        category: "Expenses:Shopping"
+        description: Refund for that damn laptop
+        track: true
 ```
 
 > **Note**: This feature has been designed to work with one-off transactions only
@@ -275,6 +282,55 @@ modifiers:
     to: "2025-12-31"
 ```
 
+### Roll-ups
+
+As part of the summarize command, it can be useful to sum-up all of the transactions in your `yaml` file and see what your income and expenditure is over a given period (e.g. "how much profit do I _actually_ make every year when all of my costs are taken into account?").
+
+In order to do this, custom forecasts need to have the `roll-up` key defined. That is, given the custom period you've specified, what number do you need to multiply the amount by in order to "roll it up" into an annualised figure. Let's look at the example below:
+
+```yaml
+custom:
+  - frequency: "every 2 weeks"
+    account: "Assets:Bank"
+    from: "2023-03-01"
+    roll-up: 26
+    transactions:
+      - amount: 80
+        category: "Expenses:Personal Care"
+        description: Hair and beauty
+```
+
+Every 2 weeks a planned expense of £80 is made. So over the course of a year, we'd need to multiply that amount by 26 to get to an annualised figure. Of course for periods like `monthly` and `quarterly` it's easy for hledger-forecast to annualise those amounts so no `roll-up` is required.
+
+To see the monthly summary of your `yaml` file, the following command can be used:
+
+    hledger-forecast summarize -f my_forecast.yml -r monthly
+
+You can also roll-up with the following periods:
+
+- daily
+- weekly
+- monthly
+- quarterly
+- half-yearly
+- yearly
+
+### Summary exclusions
+
+It can be useful to exclude certain items from your summary, like one-off items. This can be achieved by specifying `summary_exclude: true` next to a transaction:
+
+```yaml
+once:
+  - account: "Assets:Bank"
+    from: "2023-03-05"
+    transactions:
+      - amount: -3000
+        category: "Expenses:Shopping"
+        description: Refund for that damn laptop
+        summary_exclude: true
+        track: true
+```
+
 ### Additional config settings
 
 Additional settings in the config file to consider:
@@ -298,12 +354,10 @@ settings:
 
 ## :paintbrush: Rationale
 
-Firstly, I've come to realise from reading countless blog and Reddit posts on [plain text accounting](https://plaintextaccounting.org), that everyone does it **completely** differently! There is _great_ support in hledger for [forecasting](https://hledger.org/1.29/hledger.html#forecasting) using periodic transactions. Infact, it's nearly perfect for my needs. My only wishes were to be able to sum up monthly transactions much faster (so I can see my forecasted monthly I&E), apply future cost pressures more easily (such as inflation) and to be able to track and monitor specific transactions.
-
-Regarding the latter; I may be expecting a material amount of money to leave my account in May (perhaps for a holiday booking). But maybe, that booking ends up leaving in July instead. Whilst I would have accounted for that expense in my forecast, it will be tied to some date in May. So if that transaction doesn't appear in the "actuals" of my May bank statement (which I import into hledger), it won't be included in my forecast at all (as the latest transaction period will be greater than the forecast period). The impact is that my forecasted balance in any future month could be $X better off than reality. Being able to automatically look out for these transactions, and include them if they're not present, is a nice time saver.
+I moved to hledger from my trusty Excel macro workbook. This thing had been with me for 5+ years. I used it to workout whether I could afford that new gadget and when I'd be in a position to buy a house. I used it to see if I was on track to have £X in my savings accounts by a given date as well as see how much money I could save on a monthly basis. That time I accidentally double counted my bonus or thought I'd accounted for my credit card bill? Painful! Set me back a few months in terms of my savings plans. In summary, I relied _heavily_ on having a detailed and accurate forecast.
 
-Also, I like to look ahead up to 3 years at a time and understand what my bank balances might look like. For this to be really accurate, factors such as inflation and salary expectations should be included. This is where the idea for modifiers came in. Being able to apply a percentage to a given category between two dates and automatically have the impact included any extended forecasts.
+I love hledger. Switching from Excel has been a breath of fresh air. There's only so many bank transactions a workbook can take before it starts groaning (yes, even on an M1 Mac). However there were a few forecasting features that I missed. The sort of features that in Excel terms mean I'd just copy a bunch of cells and paste them into columns which represented future dates or apply a neat little formula to divide a big number by 12 to get to a monthly repayment. Because I like to plan 3-5 years out at a time, I wanted to crudely account for future price and salary increases. Sure, I can add some auto-postings to the end of my journal file but I bet a lot of users didn't know about this or even know how to constrain them between two dates.
 
-Now I'll freely admit these are two minor issues. So minor infact that they can probably be addressed by a dedicated 5 minutes every month as part of your hledger workflow. However I liked the idea of automating as much of my month end process as possible and saw this as an interesting challenge to try and solve.
+I also made an assumption that a lot of users probably think of their finances in terms of their monthly costs (e.g. car payments, mortgage, food), half-yearly costs (e.g. service charge if you have an apartment in the UK) and yearly costs (e.g. holidays, gifts) etc. But likely never do the math to add them all together and workout how much money they have left over by the end of it all. Well I built that into this app and my daily profit figure hit me hard :rofl:. Give it a try!
 
-Whilst I tried to work within the constraints of a `journal` file, moving to a `yaml` format made the implementation of these features much easier and allowed me to stay true to how you'd accomplish forecasting in hledger, manually. Whilst the config file can end up being many lines long, the output journal should be relatively streamlined and easy to follow.
+So I thought I'd share this little Ruby gem in the hope that people find it useful. Perhaps for those who are moving from an Excel based approach to [plain text accounting](https://plaintextaccounting.org), or for those who want a little bit of improvement to the existing capabilities within hledger.

data/example.journal

@@ -1,40 +1,51 @@
-~ monthly from 2023-03-01  * Bonus, Salary, Food, New cell phone, Holiday savings
-    Income:Bonus         £-100.00  ;  Bonus
-    Income:Salary        £-2,000.00;  Salary
-    Expenses:Food        £500.00   ;  Food
-    Expenses:Phone       £75.00    ;  New cell phone
-    Expenses:Holiday     £208.33   ;  Holiday savings
+~ monthly from 2023-03-01  * Salary, Bills, Food, New Kitchen
+    Income:Salary             $-3,500.00;  Salary
+    Expenses:Bills            $175.00   ;  Bills
+    Expenses:Food             $500.00   ;  Food
+    Expenses:House            $208.33   ;  New Kitchen
     Assets:Bank
 
-~ monthly from 2023-03-01 to 2024-01-01  * Mortgage
-    Expenses:Mortgage    £1,000.00 ;  Mortgage
+~ monthly from 2023-03-01 to 2025-01-01  * Mortgage
+    Expenses:Mortgage         $2,000.00 ;  Mortgage
     Assets:Bank
 
-~ monthly from 2023-03-01  * Pension draw down
-    Income:Pension       £-500.00  ;  Pension draw down
-    Assets:Savings
+~ monthly from 2023-03-01 to 2024-02-29  * Holiday
+    Expenses:Holiday          $125.00   ;  Holiday
+    Assets:Bank
 
-~ every 3 months from 2023-04-01  * Bonus
-    Income:Bonus         £-1,000.00;  Bonus
+~ monthly from 2023-03-01 to 2025-01-01  * Rainy day fund
+    Assets:Savings            $300.00   ;  Rainy day fund
     Assets:Bank
 
-~ every 6 months from 2023-04-01  * Holiday
-    Expenses:Holiday     £500.00   ;  Holiday
+~ monthly from 2024-01-01  * Pension draw down
+    Income:Pension            $-500.00  ;  Pension draw down
+    Assets:Pension
+
+~ every 3 months from 2023-04-01  * Quarterly bonus
+    Income:Bonus              $-1,000.00;  Quarterly bonus
+    Assets:Bank
+
+~ every 6 months from 2023-04-01  * Top up holiday funds
+    Expenses:Holiday          $500.00   ;  Top up holiday funds
     Assets:Bank
 
 ~ yearly from 2023-04-01  * Annual Bonus
-    Income:Bonus         £-2,000.00;  Annual Bonus
+    Income:Bonus              $-2,000.00;  Annual Bonus
     Assets:Bank
 
-~ every 5 days from 2023-03-01  * Car fuel
-    Expenses:Car:Fuel    £150.00   ;  Car fuel
+~ every 2 weeks from 2023-03-01  * Hair and beauty
+    Expenses:Personal Care    $80.00    ;  Hair and beauty
     Assets:Bank
 
-~ 2023-06-01  * [TRACKED] Forecast new car cost
-    Expenses:Car         £5,000.00 ;  Forecast new car cost
+~ 2023-06-01  * [TRACKED] Refund for that damn laptop
+    Expenses:Shopping         $-3,000.00;  Refund for that damn laptop
     Assets:Bank
 
 = Expenses:Food date:2024-01-01..2024-12-31
-    Expenses:Food        *0.1      ;  Food - Inflation
-    Assets:Bank          *-0.1
+    Expenses:Food             *0.02     ;  Food - Inflation
+    Assets:Bank               *-0.02
+
+= Expenses:Food date:2025-01-01..2025-12-31
+    Expenses:Food             *0.05     ;  Food - Inflation
+    Assets:Bank               *-0.05
 

data/example.yml

@@ -2,32 +2,44 @@ monthly:
   - account: "Assets:Bank"
     from: "2023-03-01"
     transactions:
-      - amount: -100
-        category: "Income:Bonus"
-        description: Bonus
-      - amount: -2000
+      - amount: -3500
         category: "Income:Salary"
         description: Salary
+      - amount: 2000
+        category: "Expenses:Mortgage"
+        description: Mortgage
+        to: "2025-01-01"
+      - amount: 175
+        category: "Expenses:Bills"
+        description: Bills
       - amount: 500
         category: "Expenses:Food"
         description: Food
         modifiers:
-          - amount: 0.1
+          - amount: 0.02
             description: "Inflation"
             from: "2024-01-01"
             to: "2024-12-31"
-      - amount: 75
-        category: "Expenses:Phone"
-        description: New cell phone
-      - amount: "=2500/12"
+          - amount: 0.05
+            description: "Inflation"
+            from: "2025-01-01"
+            to: "2025-12-31"
+      - amount: "=5000/24"
+        category: "Expenses:House"
+        description: New Kitchen
+      - amount: 125
         category: "Expenses:Holiday"
-        description: Holiday savings
-      - amount: 1000
-        category: "Expenses:Mortgage"
-        description: Mortgage
-        to: "2024-01-01"
-  - account: "Assets:Savings"
+        description: Holiday
+        to: "=12"
+  - account: "Assets:Bank"
     from: "2023-03-01"
+    to: "2025-01-01"
+    transactions:
+      - amount: 300
+        category: "Assets:Savings"
+        description: "Rainy day fund"
+  - account: "Assets:Pension"
+    from: "2024-01-01"
     transactions:
       - amount: -500
         category: "Income:Pension"
@@ -39,7 +51,7 @@ quarterly:
     transactions:
       - amount: -1000.00
         category: "Income:Bonus"
-        description: Bonus
+        description: Quarterly bonus
 
 half-yearly:
   - account: "Assets:Bank"
@@ -47,7 +59,7 @@ half-yearly:
     transactions:
       - amount: 500
         category: "Expenses:Holiday"
-        description: Holiday
+        description: Top up holiday funds
 
 yearly:
   - account: "Assets:Bank"
@@ -59,21 +71,23 @@ yearly:
 
 once:
   - account: "Assets:Bank"
-    from: "2023-03-01"
+    from: "2023-03-05"
     transactions:
-      - amount: 5000.00
-        category: "Expenses:Car"
-        description: Forecast new car cost
+      - amount: -3000
+        category: "Expenses:Shopping"
+        description: Refund for that damn laptop
+        summary_exclude: true
         track: true
 
 custom:
-  - frequency: "every 5 days"
+  - frequency: "every 2 weeks"
     account: "Assets:Bank"
     from: "2023-03-01"
+    roll-up: 26
     transactions:
-      - amount: 150
-        category: "Expenses:Car:Fuel"
-        description: Car fuel
+      - amount: 80
+        category: "Expenses:Personal Care"
+        description: Hair and beauty
 
 settings:
-  currency: GBP
+  currency: USD

data/lib/hledger_forecast/cli.rb

@@ -118,6 +118,29 @@ module HledgerForecast
           options[:forecast_file] = file
         end
 
+        opts.on("-r", "--roll-up PERIOD",
+                "The period to roll-up your forecasts into. One of:",
+                "[yearly], [half-yearly], [quarterly], [monthly], [weekly], [daily]") do |rollup|
+          options[:roll_up] = rollup
+        end
+
+        opts.on("--from DATE",
+                "Include transactions that start FROM a given DATE [yyyy-mm-dd]") do |from|
+          options[:from] = from
+        end
+
+        opts.on("--to DATE",
+                "Include transactions that run TO a given DATE [yyyy-mm-dd]") do |to|
+          options[:to] = to
+        end
+
+        opts.on("-s", "--scenario \"NAMES\"",
+                "Include transactions from given scenarios, e.g.:",
+                "\"base, rennovation, car purchase\"") do |_scenario|
+          # Loop through scenarios, seperated by a comma
+          options[:scenario] = {}
+        end
+
         opts.on_tail("-h", "--help", "Show this help message") do
           puts opts
           exit
@@ -156,7 +179,9 @@ module HledgerForecast
 
     def self.summarize(options)
       config = File.read(options[:forecast_file])
-      puts Summarizer.summarize(config, options)
+      summarizer = Summarizer.summarize(config, options)
+
+      puts SummarizerFormatter.format(summarizer[:output], summarizer[:settings])
     end
   end
 end

data/lib/hledger_forecast/summarizer.rb

@@ -1,6 +1,5 @@
 module HledgerForecast
-  # Summarise a forecast YAML file and output it to the CLI
-  # TODO: Rename this to Summarizer and the main method becomes summarize
+  # Summarise a forecast yaml file and output it to the CLI
   class Summarizer
     def self.summarize(config, cli_options)
       new.summarize(config, cli_options)
@@ -9,124 +8,99 @@ module HledgerForecast
     def summarize(config, cli_options = nil)
       @forecast = YAML.safe_load(config)
       @settings = Settings.config(@forecast, cli_options)
-      @table = Terminal::Table.new
 
-      generate(@forecast)
+      return { output: generate(@forecast), settings: @settings }
     end
 
     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)
+      output = {}
+      forecast.each do |period, blocks|
+        next if %w[settings].include?(period)
+
+        blocks.each do |block|
+          key = if @settings[:roll_up].nil?
+                  period
+                else
+                  output.length
+                end
+
+          output[key] ||= []
+          output[key] << process_block(period, block)
+        end
       end
 
-      add_categories_to_table(category_totals, forecast)
-
-      @table.add_separator
-      format_total("TOTAL", category_totals.values.map(&:values).flatten.sum)
+      output = filter_out(flatten_and_merge(output))
+      output = calculate_rolled_up_amount(output) unless @settings[:roll_up].nil?
 
-      @table
+      output
     end
 
-    def init_table
-      @table.add_row([{ value: 'FORECAST SUMMARY'.bold, colspan: 3, alignment: :center }])
-      @table.add_separator
-    end
+    def process_block(period, block)
+      output = []
 
-    def sum_transactions(forecast, period)
-      category_total = Hash.new(0)
-      forecast[period]&.each do |entry|
-        entry['transactions'].each do |transaction|
-          category_total[transaction['category']] += Calculator.new.evaluate(transaction['amount'])
-        end
-      end
+      output << {
+        account: block['account'],
+        from: Date.parse(block['from']),
+        to: block['to'] ? Date.parse(block['to']) : nil,
+        type: period,
+        frequency: block['frequency'],
+        transactions: []
+      }
 
-      category_total
+      process_transactions(period, block, output)
     end
 
-    def sum_custom_transactions(forecast_data)
-      category_total = Hash.new(0)
-      custom_periods = []
-
-      forecast_data['custom']&.each do |entry|
-        period_data = {}
-        period_data[:frequency] = entry['frequency']
-        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
-
-        custom_periods << period_data
+    def process_transactions(period, block, output)
+      block['transactions'].each do |t|
+        amount = Calculator.new.evaluate(t['amount'])
+
+        output.last[:transactions] << {
+          amount: amount,
+          annualised_amount: amount * (block['roll-up'] || annualise(period)),
+          rolled_up_amount: 0,
+          category: t['category'],
+          exclude: t['summary_exclude'],
+          description: t['description'],
+          to: t['to'] ? Calculator.new.evaluate_date(Date.parse(block['from']), t['to']) : nil
+        }
       end
 
-      { totals: category_total, periods: custom_periods }
+      output
     end
 
-    def format_amount(amount)
-      formatted_amount = Formatter.format_money(amount, @settings)
-      amount.to_f < 0 ? formatted_amount.green : formatted_amount.red
+    def annualise(period)
+      annualise = {
+        'monthly' => 12,
+        'quarterly' => 4,
+        'half-yearly' => 2,
+        'yearly' => 1,
+        'once' => 1,
+        'daily' => 352,
+        'weekly' => 52
+      }
+
+      annualise[period]
     end
 
-    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 },
-                          { value: period[:frequency], 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 }]
+    def filter_out(data)
+      data.reject { |item| item[:exclude] == true }
+    end
 
-          period_total += amount
+    def flatten_and_merge(blocks)
+      blocks.values.flatten.flat_map do |block|
+        block[:transactions].map do |transaction|
+          block.slice(:account, :from, :to, :type, :frequency).merge(transaction)
         end
       end
-
-      period_total
     end
 
-    def 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 }])
-
-        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
+    def calculate_rolled_up_amount(data)
+      data.map do |item|
+        item[:rolled_up_amount] = item[:annualised_amount] / annualise(@settings[:roll_up])
+        item
       end
     end
-
-    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 format_total(text, total)
-      @table.add_row [{ value: text.bold, colspan: 2, alignment: :left },
-                     { value: format_amount(total).bold, alignment: :right }]
-    end
   end
 end

data/lib/hledger_forecast/summarizer_formatter.rb

@@ -0,0 +1,115 @@
+module HledgerForecast
+  # Output the summarised forecast to the CLI
+  class SummarizerFormatter
+    def self.format(output, settings)
+      new.format(output, settings)
+    end
+
+    def format(output, settings)
+      @table = Terminal::Table.new
+      @settings = settings
+
+      init_table
+
+      if @settings[:roll_up].nil?
+        add_rows_to_table(output)
+        add_total_row_to_table(output, :amount)
+      else
+        add_rolled_up_rows_to_table(output)
+        add_total_row_to_table(output, :rolled_up_amount)
+      end
+
+      @table
+    end
+
+    private
+
+    def init_table
+      title = 'FORECAST SUMMARY'
+      title += " (#{@settings[:roll_up].upcase} ROLL UP)" if @settings[:roll_up]
+
+      @table.add_row([{ value: title.bold, colspan: 3, alignment: :center }])
+      @table.add_separator
+    end
+
+    def add_rows_to_table(data)
+      data = data.group_by { |item| item[:type] }
+
+      data = sort(data)
+
+      data.each_with_index do |(type, items), index|
+        @table.add_row([{ value: type.capitalize.bold, colspan: 3, alignment: :center }])
+        total = 0
+        items.each do |item|
+          total += item[:amount]
+          @table.add_row [{ value: item[:category], colspan: 2, alignment: :left },
+                          { value: format_amount(item[:amount]), alignment: :right }]
+        end
+
+        @table.add_row [{ value: "TOTAL".bold, colspan: 2, alignment: :left },
+                        { value: format_amount(total).bold, alignment: :right }]
+
+        @table.add_separator if index != data.size - 1
+      end
+    end
+
+    def sort(data)
+      data.each do |type, items|
+        data[type] = items.sort_by do |item|
+          value = item[:amount]
+          [value >= 0 ? 1 : 0, value >= 0 ? -value : value]
+        end
+      end
+    end
+
+    def add_rolled_up_rows_to_table(data)
+      sum_hash = Hash.new { |h, k| h[k] = { sum: 0, descriptions: [] } }
+
+      data.each do |item|
+        sum_hash[item[:category]][:sum] += item[:rolled_up_amount]
+        sum_hash[item[:category]][:descriptions] << item[:description]
+      end
+
+      # Convert arrays of descriptions to single strings
+      sum_hash.each do |_category, values|
+        values[:descriptions] = values[:descriptions].join(", ")
+      end
+
+      # Sort the array
+      sorted_sums = sort_roll_up(sum_hash, :sum)
+
+      sorted_sums.each do |hash|
+        @table.add_row [{ value: hash[:category], colspan: 2, alignment: :left },
+                        { value: format_amount(hash[:sum]), alignment: :right }]
+      end
+    end
+
+    def sort_roll_up(data, sort_by)
+      # Convert the hash to an array of hashes
+      array = data.map do |category, values|
+        { category: category, sum: values[sort_by], descriptions: values[:descriptions] }
+      end
+
+      # Sort the array
+      array.sort_by do |hash|
+        value = hash[:sum]
+        [value >= 0 ? 1 : 0, value >= 0 ? -value : value]
+      end
+    end
+
+    def add_total_row_to_table(data, row_to_sum)
+      total = data.reduce(0) do |sum, item|
+        sum + item[row_to_sum]
+      end
+
+      @table.add_separator
+      @table.add_row [{ value: "TOTAL".bold, colspan: 2, alignment: :left },
+                      { value: format_amount(total).bold, alignment: :right }]
+    end
+
+    def format_amount(amount)
+      formatted_amount = Formatter.format_money(amount, @settings)
+      amount.to_f < 0 ? formatted_amount.green : formatted_amount.red
+    end
+  end
+end

data/lib/hledger_forecast/version.rb

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

data/lib/hledger_forecast.rb

@@ -18,8 +18,10 @@ require_relative 'hledger_forecast/formatter'
 require_relative 'hledger_forecast/generator'
 require_relative 'hledger_forecast/settings'
 require_relative 'hledger_forecast/summarizer'
+require_relative 'hledger_forecast/summarizer_formatter'
 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/monthly_spec.rb

@@ -23,14 +23,14 @@ config = <<~YAML
 YAML
 
 output = <<~JOURNAL
-~ monthly from 2023-03-01  * Mortgage, Food
-    Expenses:Mortgage    £2,000.55;  Mortgage
-    Expenses:Food        £100.00  ;  Food
-    Assets:Bank
+  ~ monthly from 2023-03-01  * Mortgage, Food
+      Expenses:Mortgage    £2,000.55;  Mortgage
+      Expenses:Food        £100.00  ;  Food
+      Assets:Bank
 
-~ monthly from 2023-03-01  * Savings
-    Assets:Bank          £-1,000.00;  Savings
-    Assets:Savings
+  ~ monthly from 2023-03-01  * Savings
+      Assets:Bank          £-1,000.00;  Savings
+      Assets:Savings
 
 JOURNAL
 

data/spec/summarizer_spec.rb

@@ -0,0 +1,86 @@
+require_relative '../lib/hledger_forecast'
+
+config = <<~YAML
+  monthly:
+    - account: "Assets:Bank"
+      from: "2023-03-01"
+      transactions:
+        - amount: 2000.55
+          category: "Expenses:Mortgage"
+          description: Mortgage
+          to: "=24"
+        - amount: 100
+          category: "Expenses:Food"
+          description: Food
+    - account: "Assets:Savings"
+      from: "2023-03-01"
+      transactions:
+        - amount: -1000
+          category: "Assets:Bank"
+          description: Savings
+
+  custom:
+    - frequency: "every 2 weeks"
+      from: "2023-05-01"
+      account: "[Assets:Bank]"
+      roll-up: 26
+      transactions:
+        - amount: 80
+          category: "[Expenses:Personal Care]"
+          description: Hair and beauty
+    - frequency: "every 5 days"
+      from: "2023-05-01"
+      account: "[Assets:Checking]"
+      roll-up: 73
+      transactions:
+        - amount: 50
+          category: "[Expenses:Groceries]"
+          description: Gotta feed that stomach
+
+  settings:
+    currency: GBP
+YAML
+
+RSpec.describe HledgerForecast::Summarizer do
+  let(:summarizer) { described_class.new }
+
+  describe '#generate with roll_up' do
+    let(:forecast) { YAML.safe_load(config) }
+    let(:cli_options) { { roll_up: 'monthly' } }
+
+    before do
+      summarizer.summarize(config, cli_options)
+    end
+
+    it 'generates the correct output' do
+      output = summarizer.send(:generate, forecast)
+
+      expect(output.first).to include(:account, :from, :to, :type, :frequency)
+      expect(output.first[:amount]).to eq(2000.55)
+      expect(output.last[:rolled_up_amount]).to eq(304) # ((50 * 73) / 12)
+      expect(output.length).to eq(5)
+    end
+
+    it 'transaction TO date take precedence over block TO date' do
+      output = summarizer.send(:generate, forecast)
+
+      expect(output.first[:to]).to eq(Date.parse("2025-02-28"))
+    end
+  end
+
+  describe '#generate' do
+    let(:forecast) { YAML.safe_load(config) }
+    let(:cli_options) { nil }
+
+    before do
+      summarizer.summarize(config, cli_options)
+    end
+
+    it 'generates the correct output' do
+      output = summarizer.send(:generate, forecast)
+
+      # expect(output.first).to include(:account, :from, :to, :type, :frequency)
+      expect(output.length).to eq(5)
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-15 00:00:00.000000000 Z
+date: 2023-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -119,6 +119,7 @@ files:
 - lib/hledger_forecast/generator.rb
 - lib/hledger_forecast/settings.rb
 - lib/hledger_forecast/summarizer.rb
+- lib/hledger_forecast/summarizer_formatter.rb
 - lib/hledger_forecast/transactions/default.rb
 - lib/hledger_forecast/transactions/modifiers.rb
 - lib/hledger_forecast/transactions/trackers.rb
@@ -137,6 +138,7 @@ files:
 - spec/stubs/transactions_found.journal
 - spec/stubs/transactions_found_inverse.journal
 - spec/stubs/transactions_not_found.journal
+- spec/summarizer_spec.rb
 - spec/track_spec.rb
 - spec/yearly_spec.rb
 homepage: https://github.com/olimorris/hledger-forecast
@@ -177,5 +179,6 @@ test_files:
 - spec/stubs/transactions_found.journal
 - spec/stubs/transactions_found_inverse.journal
 - spec/stubs/transactions_not_found.journal
+- spec/summarizer_spec.rb
 - spec/track_spec.rb
 - spec/yearly_spec.rb