hledger-forecast 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb90937d10de71d495146036711f7028d12de7f5b7c814ccf0fb62dc7ffc5e7f
-  data.tar.gz: 05143fad945647f27f30e49626974ec62b66074863a5f11e86898a824b182c85
+  metadata.gz: 85bd96722d50a8d5b2c8e8cbb9f973d88832827f74226d3b78d5f511b96265bf
+  data.tar.gz: b69f6698e5c7294cd2b62c8672887044a416d0ed6624803293acd9246a84fa14
 SHA512:
-  metadata.gz: 00e039f29f6f50237d4bca32d8f5e2f27173ac880661bb1445558a98380816de0718e3e748b639e7018d79b49ce019f6dac7b145b98104a687d04bbf36c8db57
-  data.tar.gz: 233262e4e1a0612c821334f97599a0d2b00962968a18f591eb5cd96f4efdd5116c037e5b5570f2b6c3e74b1955dec140ffd774a7c04feacdb6d628303d71cb87
+  metadata.gz: 2e3c4e2a1ef57546778525c37fa4b53854a10244f3e509c3bd48d8c3fcb49c2edc892c84f221f7980c56687ec4766f5379939ea82a06a06b238a8aa3f1a1ed8b
+  data.tar.gz: 4fd49fc32b5fd5aa17e24ac166f384352a5cb85a72f57cb3aa774b8837c62c94439412252ba7164641b59c4cec7fc60a218eab1419dad913ea008c30058722d5

data/README.md

@@ -2,15 +2,16 @@
 
 [![Tests](https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml/badge.svg)](https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml)
 
-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.
+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 which can be used with hledger
+- :book: Uses a simple yaml file 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
+- :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)
 - :computer: Simple and easy to use CLI
 - :chart_with_upwards_trend: Summarize your forecasts by period and category and output to the CLI
@@ -41,7 +42,7 @@ The available options are:
 
 ### Generate command
 
-The `hledger-forecast generate` command will begin the generation of your forecast _from_ a `yaml` file _to_ a journal file.
+The `hledger-forecast generate` command will generate a forecast  _from_ a `yaml` file _to_ a journal file. You can see the output of this command in the [example.journal](https://github.com/olimorris/hledger-forecast/blob/main/example.journal) file.
 
 The available options are:
 
@@ -174,6 +175,24 @@ monthly:
         to: "2025-01-01"
 ```
 
+### Calculated amounts
+
+> **Note**: Calculations will be determined up to two decimal places
+
+It may be helpful to let the app calculate the forecasted amount in your transactions on your behalf. This can be especially useful if you're spreading a payment out over a number of months:
+
+```yaml
+monthly:
+  - account: "Liabilities:Amex"
+    from: "2023-05-01"
+    transactions:
+      - amount: "=5000/24"
+        category: "Expenses:House"
+        description: New Kitchen
+```
+
+Simply ensure that the amount starts with an `=` sign, is enclosed in quotation marks and uses standard mathematical notations.
+
 ### 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
@@ -265,7 +284,7 @@ settings:
 
 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 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.
+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.
 
 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.
 

data/example.journal

@@ -1,8 +1,9 @@
-~ monthly from 2023-03-01  * Bonus, Salary, Food, New cell phone
+~ 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
     Assets:Bank
 
 ~ monthly from 2023-03-01 to 2024-01-01  * Mortgage
@@ -29,6 +30,10 @@
     Expenses:Car:Fuel    £150.00   ;  Car fuel
     Assets:Bank
 
+~ 2023-06-01  * [TRACKED] Forecast new car cost
+    Expenses:Car         £5,000.00 ;  Forecast new car cost
+    Assets:Bank
+
 = Expenses:Food date:2024-01-01..2024-12-31
     Expenses:Food        *0.1      ;  Food - Inflation
     Assets:Bank          *-0.1

data/example.yml

@@ -19,6 +19,9 @@ monthly:
       - amount: 75
         category: "Expenses:Phone"
         description: New cell phone
+      - amount: "=2500/12"
+        category: "Expenses:Holiday"
+        description: Holiday savings
       - amount: 1000
         category: "Expenses:Mortgage"
         description: Mortgage

data/hledger-forecast.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |s|
   s.license     = 'MIT'
 
   s.add_dependency "colorize", "~> 0.8.1"
+  s.add_dependency "dentaku", "~> 3.5.1"
   s.add_dependency "highline", "~> 2.1.0"
   s.add_dependency "money", "~> 6.16.0"
   s.add_dependency "terminal-table", "~> 3.0.2"

data/lib/hledger_forecast/generator.rb

@@ -2,9 +2,10 @@ module HledgerForecast
   # Generates periodic transactions from a YAML file
   class Generator
     class << self
-      attr_accessor :options, :modified, :tracked
+      attr_accessor :calculator, :options, :modified, :tracked
     end
 
+    self.calculator = {}
     self.options = {}
     self.modified = {}
     self.tracked = {}
@@ -24,6 +25,8 @@ module HledgerForecast
 
       set_options(forecast_data)
 
+      @calculator = Dentaku::Calculator.new
+
       output = ""
 
       # Generate regular transactions
@@ -75,7 +78,7 @@ module HledgerForecast
 
         modified_transaction(from, to, account, transaction)
 
-        output += output_transaction(transaction['category'], format_amount(transaction['amount']),
+        output += output_transaction(transaction['category'], format_amount(calculate_amount(transaction['amount'])),
                                      transaction['description'])
       end
 
@@ -107,7 +110,7 @@ module HledgerForecast
         modified_transaction(from, to, account, transaction)
 
         output += "#{frequency} #{from} to #{to}  * #{transaction['description']}\n"
-        output += output_transaction(transaction['category'], format_amount(transaction['amount']),
+        output += output_transaction(transaction['category'], format_amount(calculate_amount(transaction['amount'])),
                                      transaction['description'])
         output += "    #{account}\n\n"
       end
@@ -137,7 +140,7 @@ module HledgerForecast
 
           modified_transaction(from, to, account, transaction)
 
-          output += output_transaction(transaction['category'], format_amount(transaction['amount']),
+          output += output_transaction(transaction['category'], format_amount(calculate_amount(transaction['amount'])),
                                        transaction['description'])
         end
 
@@ -216,7 +219,7 @@ module HledgerForecast
     end
 
     def self.track_transaction(from, to, account, transaction)
-      amount = transaction['amount']
+      amount = calculate_amount(transaction['amount'])
       transaction['amount'] = format_amount(amount)
       transaction['inverse_amount'] = format_amount(amount * -1)
 
@@ -240,6 +243,12 @@ module HledgerForecast
       map[period]
     end
 
+    def self.calculate_amount(amount)
+      return amount unless amount.is_a?(String)
+
+      @calculator.evaluate(amount.slice(1..-1))
+    end
+
     def self.format_amount(amount)
       Money.from_cents(amount.to_f * 100, @options[:currency]).format(
         symbol: @options[:show_symbol],

data/lib/hledger_forecast/version.rb

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

data/lib/hledger_forecast.rb

@@ -2,6 +2,7 @@
 
 require 'colorize'
 require 'date'
+require 'dentaku'
 require 'highline'
 require 'money'
 require 'optparse'

data/spec/computed_amounts_spec.rb

@@ -0,0 +1,35 @@
+require_relative '../lib/hledger_forecast'
+
+config = <<~YAML
+  settings:
+    currency: GBP
+
+  monthly:
+    - account: "Liabilities:Amex"
+      from: "2023-05-01"
+      transactions:
+        - amount: "=5000/24"
+          category: "Expenses:House"
+          description: New Kitchen
+        - amount: "=25*4.3"
+          category: "Expenses:Food"
+          description: Monthly food shop
+        - amount: "=(102.50+3.25)/2"
+          category: "Expenses:Food"
+          description: Random food
+YAML
+
+output = <<~JOURNAL
+  ~ monthly from 2023-05-01  * New Kitchen, Monthly food shop, Random food
+      Expenses:House    £208.33          ;  New Kitchen
+      Expenses:Food     £107.50          ;  Monthly food shop
+      Expenses:Food     £52.88           ;  Random food
+      Liabilities:Amex
+
+JOURNAL
+
+RSpec.describe 'generate' do
+  it 'generates a forecast with correct CALCULATED transactions' do
+    expect(HledgerForecast::Generator.generate(config)).to eq(output)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-08 00:00:00.000000000 Z
+date: 2023-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.8.1
+- !ruby/object:Gem::Dependency
+  name: dentaku
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.5.1
 - !ruby/object:Gem::Dependency
   name: highline
   requirement: !ruby/object:Gem::Requirement
@@ -105,6 +119,7 @@ files:
 - lib/hledger_forecast/tracker.rb
 - lib/hledger_forecast/version.rb
 - spec/command_spec.rb
+- spec/computed_amounts_spec.rb
 - spec/custom_spec.rb
 - spec/half-yearly_spec.rb
 - spec/modifier_spec.rb
@@ -144,6 +159,7 @@ specification_version: 4
 summary: An extended wrapper around hledger's forecasting functionality
 test_files:
 - spec/command_spec.rb
+- spec/computed_amounts_spec.rb
 - spec/custom_spec.rb
 - spec/half-yearly_spec.rb
 - spec/modifier_spec.rb