hledger-forecast 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a21d32c5ee145d0bca5cb25f07a2fbb6f65126f16c5e15faf2ca11b3fbfac03c
-  data.tar.gz: bbf889db9f129ca62550399b2f2e7818936eee667d356bbeb52b476f305fe6b1
+  metadata.gz: cb90937d10de71d495146036711f7028d12de7f5b7c814ccf0fb62dc7ffc5e7f
+  data.tar.gz: 05143fad945647f27f30e49626974ec62b66074863a5f11e86898a824b182c85
 SHA512:
-  metadata.gz: b0fa4ad6d50c30eac65acc292d96f500182e211b1a4b9e039dfcff0f204a32ad01d9c01a7570535301bffeb6be865c720d6b8be8ba3e17370a2b992586f351d5
-  data.tar.gz: 554a06876170c161d35b68eececa7904b190aaa0fb6611e2a8bd672fad9b02b48a5a5e26e013db857671fd6f50e33242cb19ddf907fafb31b1b1bd27b74f86df
+  metadata.gz: 00e039f29f6f50237d4bca32d8f5e2f27173ac880661bb1445558a98380816de0718e3e748b639e7018d79b49ce019f6dac7b145b98104a687d04bbf36c8db57
+  data.tar.gz: 233262e4e1a0612c821334f97599a0d2b00962968a18f591eb5cd96f4efdd5116c037e5b5570f2b6c3e74b1955dec140ffd774a7c04feacdb6d628303d71cb87

data/.gitignore

@@ -15,7 +15,5 @@ pkg/*
 /coverage
 
 # Misc
-forecast.yml
-forecast.journal
 test_output.journal
 todo.md

data/README.md

@@ -2,14 +2,15 @@
 
 [![Tests](https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml/badge.svg)](https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml)
 
-Uses a YAML file to generate periodic transactions for better forecasting in [Hledger](https://github.com/simonmichael/hledger).
+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.
 
 See the [rationale](#brain-rationale) section for why this gem may be useful to you.
 
 ## :sparkles: Features
 
-- :book: Uses simple YAML files to generate forecasts from periodic transactions
-- :date: Generate forecasts between specified start and end dates
+- :book: Uses simple YAML files to generate forecasts which can be used with hledger
+- :date: Can smartly track forecasted transactions against actuals
+- :moneybag: Can automatically apply modifiers such as inflation/deflation to forecasts
 - :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
@@ -24,58 +25,81 @@ Assuming you have Ruby and [Rubygems](http://rubygems.org/pages/download) instal
 
 Run:
 
-    hledger-forecast generate
+    hledger-forecast
 
-> **Note**: This assumes that a `forecast.yml` exists in the current working directory
+The available options are:
 
-Running `hledger-forecast -h` shows the available options:
+    Usage: hledger-forecast [command] [options]
 
-    Usage: Hledger-Forecast generate [options]
+    Commands:
+      generate    Generate the forecast file
+      summarize   Summarize the forecast file and output to the terminal
 
-        -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
+    Options:
         -h, --help                       Show this help message
+        -v, --version                    Show version
 
-Another example of a common command:
+### Generate command
 
-    hledger-forecast generate -f my_forecast.yml -s 2023-05-01 -e 2024-12-31
+The `hledger-forecast generate` command will begin the generation of your forecast _from_ a `yaml` file _to_ a journal file.
 
-This will generate an output file (`my_forecast.journal`) from the forecast file between the two date ranges.
+The available options are:
+
+    Usage: hledger-forecast generate [options]
+
+      -f, --forecast FILE              The path to the FORECAST yaml file to generate from
+      -o, --output-file FILE           The path to the OUTPUT file to create
+      -t, --transaction FILE           The path to the TRANSACTION journal file
+          --force                      Force an overwrite of the output file
+          --no-track                   Don't track any transactions
+      -h, --help                       Show this help message
+
+> **Note**: For the tracking of transactions you need to include the `-t` flag
+
+Running the command with no options will assume a `forecast.yml` file exists.
 
 ### Using with Hledger
 
-To use the outputs in Hledger:
+To work with hledger, include the forecast file and use the `--forecast` flag:
+
+    hledger -f bank_transactions.journal -f forecast.journal --forecast bal assets -e 2024-02
+
+The command will generate a forecast up to the end of Feb 2024, showing the balance for any asset accounts, overlaying some bank transactions with the forecast journal file. Of course, refer to the [hledger](https://hledger.org/dev/hledger.html) documentation for more information on how to query your finances.
+
+To apply any modifiers, use the `--auto` flag at the end of your command.
+
+### 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:
+
+    hledger-forecast summarize -f my_forecast.yml
 
-    hledger -f transactions.journal -f my_forecast.journal
+The available options are:
 
-where:
+    Usage: hledger-forecast summarize [options]
 
-- `transactions.journal` might be your bank transactions (your "_actuals_")
-- `my_forecast.journal` is the generated forecast file
+        -f, --forecast FILE              The path to the FORECAST yaml file to summarize
+        -h, --help                       Show this help message
 
 ## :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
+> **Note**: See the [example.yml](https://github.com/olimorris/hledger-forecast/blob/main/example.yml) file for an example of a complex config file and its [output](https://github.com/olimorris/hledger-forecast/blob/main/example.journal)
 
-Firstly, create a `yml` file which will contain the transactions you'd like to forecast:
+Firstly, create a `yaml` file which will contain the transactions you'd like to forecast:
 
 ```yaml
 # forecast.yml
 monthly:
-  - account: "[Assets:Bank]"
-    start: "2023-03-01"
+  - account: "Assets:Bank"
+    from: "2023-03-01"
     transactions:
       - amount: 2000
-        category: "[Expenses:Mortgage]"
+        category: "Expenses:Mortgage"
         description: Mortgage
       - amount: 500
-        category: "[Expenses:Food]"
+        category: "Expenses:Food"
         description: Food
 
 settings:
@@ -84,45 +108,38 @@ settings:
 
 Let's examine what's going on in this config file:
 
-- Firstly, we're telling the app to create two monthly transactions and repeat them, forever, starting from March 2023. In this case, forever will be the `end_date` specified when running the app
-- If you ran the app with `hledger-forecast -s 2023-04-01` then no transactions would be generated for March as the start date is greater than the periodic start date
-- 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
+- We're telling the app to create two monthly transactions and repeat them, forever, starting from March 2023
+- We're telling the app to link them both to the `Assets:Bank` account
+- We've added descriptions to make it easy to follow in our output file
+- Finally, we're telling the app to use the `GBP` currency; the default (`USD`) will be used if this is not specified
 
 ### Periods
 
 Besides monthly recurring transactions, the app also supports the following periods:
 
-- `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
+- `quarterly` - For transactions every _3 months_
+- `half-yearly` - For transactions every _6 months_
+- `yearly` - Generate transactions _once a year_
 - `once` - Generate _one-time_ transactions on a specified date
 - `custom` - Generate transactions every _n days/weeks/months_
 
+These will write periodic transactions such as `~ every 3 months` or `~ every year` in the output journal file.
+
 #### 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:
+When you need a bespoke time bound forecast, a custom period may be useful. Custom periods allow you to specify a periodic rule as per hledger's [periodic rule syntax](https://hledger.org/dev/hledger.html#periodic-transactions):
 
 ```yaml
 custom:
-  - description: Fortnightly hair and beauty spend
-    recurrence:
-      period: weeks
-      quantity: 2
-    account: "[Assets:Bank]"
-    start: "2023-03-01"
+  - frequency: "every 2 weeks"
+    account: "Assets:Bank"
+    from: "2023-03-01"
     transactions:
       - amount: 80
-        category: "[Expenses:Personal Care]"
+        category: "Expenses:Personal Care"
         description: Hair and beauty
 ```
 
-Where `quantity` is an integer and `period` is one of:
-
-- days
-- weeks
-- months
-
 ### 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).
@@ -131,34 +148,97 @@ You can further control the dates at a period/top-level as well as at a transact
 
 #### Top level
 
-In the example below, all transactions in the `monthly` block will be constrained by the end date:
+In the example below, all transactions in the `monthly` block will be constrained by the `to` date:
 
 ```yaml
 monthly:
-  - account: "[Assets:Bank]"
-    start: "2023-03-01"
-    end: "2025-01-01"
+  - account: "Assets:Bank"
+    from: "2023-03-01"
+    to: "2025-01-01"
     transactions:
       # details omitted for brevity
 ```
 
 #### Transaction level
 
-In the example below, only the single transaction will be constrained by the end date and controlled via an additional start date:
+In the example below, only the single transaction will be constrained by the `to` date:
 
 ```yaml
 monthly:
-  - account: "[Assets:Bank]"
-    start: "2023-03-01"
+  - account: "Assets:Bank"
+    from: "2023-03-01"
     transactions:
       - amount: 2000
-        category: "[Expenses:Mortgage]"
+        category: "Expenses:Mortgage"
         description: Mortgage
-        start: "2023-05-01"
-        end: "2025-01-01"
+        to: "2025-01-01"
+```
+
+### Tracking transactions
+
+> **Note**: Marking a transaction for tracking will ensure that it is only written into the forecast if it isn't found within a specified transaction file
+
+Sometimes it can be useful to track and monitor forecasted transactions to ensure that they are accounted for in any financial projections. If they are present, then these should be discarded from your forecast as this will create a double count against your actuals. However, if they can't be found then they should be carried forward into a future period to ensure accurate recording.
+
+To mark transactions as available for tracking you may use the `track` option in your config file:
+
+```yaml
+once:
+    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
+
+To use this feature, ensure you pass a filepath to the `-t` flag, such as:
+
+    hledger-forecast generate -t [journal_file_to_search] -f [path_to_yaml_file] -o [path_to_output_journal]
+
+The app will use a hledger query to determine if the combination of category and amount is present in the periods between the `from` key and the current date in the journal file you've specified. If not, then the app will include it as a forecast transaction in the output file.
+
+### Applying modifiers
+
+> **Note**: For modifiers to be included in your hledger reporting, use the `--auto` flag
+
+Within your forecasts, it can be useful to reflect future increases/decreases in certain categories. For example, next year, I expect the cost of groceries to increase by 2%:
+
+```yaml
+monthly:
+    account: "Assets:Bank"
+    from: "2023-03-05"
+    transactions:
+      - amount: 450
+        category: "Expenses:Groceries"
+        description: Food shopping
+        modifiers:
+          - amount: 0.02
+            description: "Inflation"
+            from: "2024-01-01"
+            to: "2024-12-31"
 ```
 
-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`.
+This will generate an [auto-posting](https://hledger.org/dev/hledger.html#auto-postings) in your forecast which will
+uplift any transaction with an `Expenses:Groceries` category.
+
+Of course you may wish to apply 2% for next year and another 3% for the year after:
+
+```yaml
+# details above omitted for brevity
+modifiers:
+  - amount: 0.02
+    description: "Inflation"
+    from: "2024-01-01"
+    to: "2024-12-31"
+  - amount: 0.05
+    description: "Inflation"
+    from: "2025-01-01"
+    to: "2025-12-31"
+```
 
 ### Additional settings
 
@@ -168,28 +248,27 @@ Additional settings in the config file to consider:
 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?
 ```
 
-## :rainbow: Helpers
+## :camera_flash: Screenshots
 
-### Summarizing the forecast file
+**Yaml config file and output**
 
-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:
+<img src="https://user-images.githubusercontent.com/9512444/234382872-b81ac84d-2bcc-4488-a041-364f72627087.png" alt="Hledger-Forecast" />
 
-    hledger-forecast summarize -f my_forecast.yml
+**Summarize command**
 
-where `my_forecast.yml` is the config file to sum up.
+<img src="https://user-images.githubusercontent.com/9512444/234386807-1301c8d9-af77-4f58-a3c3-a345b5e890a2.png" alt="Summarize command" />
 
-## :brain: Rationale
+## :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!
+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.
 
-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.
+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 likely be for the period of 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 is a nice time saver.
 
-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.
+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.
 
-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?"_.
+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.
 
-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.
+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.

data/example.journal

@@ -0,0 +1,35 @@
+~ monthly from 2023-03-01  * Bonus, Salary, Food, New cell phone
+    Income:Bonus         £-100.00  ;  Bonus
+    Income:Salary        £-2,000.00;  Salary
+    Expenses:Food        £500.00   ;  Food
+    Expenses:Phone       £75.00    ;  New cell phone
+    Assets:Bank
+
+~ monthly from 2023-03-01 to 2024-01-01  * Mortgage
+    Expenses:Mortgage    £1,000.00 ;  Mortgage
+    Assets:Bank
+
+~ monthly from 2023-03-01  * Pension draw down
+    Income:Pension       £-500.00  ;  Pension draw down
+    Assets:Savings
+
+~ every 3 months from 2023-04-01  * Bonus
+    Income:Bonus         £-1,000.00;  Bonus
+    Assets:Bank
+
+~ every 6 months from 2023-04-01  * Holiday
+    Expenses:Holiday     £500.00   ;  Holiday
+    Assets:Bank
+
+~ yearly from 2023-04-01  * 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
+    Assets:Bank
+
+= Expenses:Food date:2024-01-01..2024-12-31
+    Expenses:Food        *0.1      ;  Food - Inflation
+    Assets:Bank          *-0.1
+

data/example.yml

@@ -1,77 +1,76 @@
 monthly:
-  - account: "[Assets:Bank]"
-    start: "2023-03-01"
+  - account: "Assets:Bank"
+    from: "2023-03-01"
     transactions:
       - amount: -100
-        category: "[Income:Bonus]"
+        category: "Income:Bonus"
         description: Bonus
       - amount: -2000
-        category: "[Income:Salary]"
+        category: "Income:Salary"
         description: Salary
-      - amount: 500.00
-        category: "[Expenses:Food]"
+      - amount: 500
+        category: "Expenses:Food"
         description: Food
+        modifiers:
+          - amount: 0.1
+            description: "Inflation"
+            from: "2024-01-01"
+            to: "2024-12-31"
       - amount: 75
-        category: "[Expenses:Phone]"
+        category: "Expenses:Phone"
         description: New cell phone
-        start: "2023-08-01"
-      - amount: 1000.00
-        category: "[Expenses:Mortgage]"
+      - amount: 1000
+        category: "Expenses:Mortgage"
         description: Mortgage
-        end: "2024-01-01"
-  - account: "[Assets:Savings]"
-    start: "2023-03-01"
+        to: "2024-01-01"
+  - account: "Assets:Savings"
+    from: "2023-03-01"
     transactions:
       - amount: -500
-        category: "[Income:Pension]"
+        category: "Income:Pension"
         description: Pension draw down
 
 quarterly:
-  - account: "[Assets:Bank]"
-    start: "2023-04-01"
+  - account: "Assets:Bank"
+    from: "2023-04-01"
     transactions:
       - amount: -1000.00
-        category: "[Income:Bonus]"
+        category: "Income:Bonus"
         description: Bonus
 
 half-yearly:
-  - account: "[Assets:Bank]"
-    start: "2023-04-01"
+  - account: "Assets:Bank"
+    from: "2023-04-01"
     transactions:
       - amount: 500
-        category: "[Expenses:Holiday]"
+        category: "Expenses:Holiday"
         description: Holiday
 
 yearly:
-  - account: "[Assets:Bank]"
-    start: "2023-04-01"
+  - account: "Assets:Bank"
+    from: "2023-04-01"
     transactions:
       - amount: -2000.00
-        category: "[Income:Bonus]"
+        category: "Income:Bonus"
         description: Annual Bonus
 
 once:
-  - account: "[Assets:Bank]"
-    start: "2024-01-01"
+  - account: "Assets:Bank"
+    from: "2023-03-01"
     transactions:
       - amount: 5000.00
-        category: "[Expenses:Car]"
+        category: "Expenses:Car"
         description: Forecast new car cost
+        track: true
 
 custom:
-  - description: Fuel every 5 days
-    recurrence:
-      period: days
-      quantity: 5
-    account: "[Assets:Bank]"
-    start: "2023-03-01"
+  - frequency: "every 5 days"
+    account: "Assets:Bank"
+    from: "2023-03-01"
     transactions:
       - amount: 150
-        category: "[Expenses:Car:Fuel]"
+        category: "Expenses:Car:Fuel"
         description: Car fuel
 
 settings:
   currency: GBP
-  show_symbol: true
-  sign_before_symbol: true
-  thousands_separator: true

data/hledger-forecast.gemspec

@@ -1,20 +1,21 @@
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
 require 'hledger_forecast/version'
 
 Gem::Specification.new do |s|
   s.name        = 'hledger-forecast'
   s.version     = HledgerForecast::VERSION
   s.authors     = ['Oli Morris']
-  s.summary     = 'Utility to generate forecasts in Hledger'
-  s.description = 'Uses a YAML file to generate monthly, quarterly, yearly and one-off transactions for better forecasting in Hledger'
+  s.summary     = "An extended wrapper around hledger's forecasting functionality"
+  s.description = 'Uses a YAML file to generate forecasts which can be used to extend the default functionality in hledger'
   s.email       = 'olimorris@users.noreply.github.com'
   s.homepage    = 'https://github.com/olimorris/hledger-forecast'
   s.license     = 'MIT'
 
+  s.add_dependency "colorize", "~> 0.8.1"
   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'