hledger-forecast 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85bd96722d50a8d5b2c8e8cbb9f973d88832827f74226d3b78d5f511b96265bf
-  data.tar.gz: b69f6698e5c7294cd2b62c8672887044a416d0ed6624803293acd9246a84fa14
+  metadata.gz: 01faf9619f0b906b089956c1b81c16766830be412a678336848a7bbe23f78cb7
+  data.tar.gz: c93786627631d0f589250a8c721d8360a9feddf6f9b21954cc49b0b6b206ff29
 SHA512:
-  metadata.gz: 2e3c4e2a1ef57546778525c37fa4b53854a10244f3e509c3bd48d8c3fcb49c2edc892c84f221f7980c56687ec4766f5379939ea82a06a06b238a8aa3f1a1ed8b
-  data.tar.gz: 4fd49fc32b5fd5aa17e24ac166f384352a5cb85a72f57cb3aa774b8837c62c94439412252ba7164641b59c4cec7fc60a218eab1419dad913ea008c30058722d5
+  metadata.gz: 218ecb7ea26f4daee36981d345cf4a67052b6c3876f4f2090d608a86a10ba7e07889010fa91ab3618da60bfac98caf2c48bbdda78ab68f0290e744a580f75076
+  data.tar.gz: c3940bb307bbba32d374f0161ecaf5ca8bcdba2a1a0cafd0d1e4ea7f13ceea20a781dd0367eb02cd1c01fe73475f23fdcf1e520d3b76a9b7d875729971f221b7

data/.github/workflows/ci.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.6', '2.7', '3.0', '3.1', '3.2']
+        ruby-version: ['3.0', '3.1', '3.2']
 
     steps:
       - uses: actions/checkout@v3

data/.gitignore

@@ -10,6 +10,7 @@ pkg/*
 .rvmrc
 .ruby-version
 .ruby-gemset
+.tool-versions
 
 # Spec artifacts
 /coverage

data/.rubocop.yml

@@ -1,3 +1,6 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
 Layout/LineLength:
   Max: 120
 

data/README.md

@@ -1,6 +1,11 @@
-# Hledger-Forecast
+<h1 align="center">Hledger-Forecast</h1>
 
-[![Tests](https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml/badge.svg)](https://github.com/olimorris/hledger-forecast/actions/workflows/ci.yml)
+<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>
+<a href="https://github.com/olimorris/hledger-forecast/issues"><img src="https://img.shields.io/github/issues/olimorris/hledger-forecast?color=%23d19a66&style=for-the-badge"></a>
+<a href="https://github.com/olimorris/hledger-forecast/blob/main/LICENSE"><img src="https://img.shields.io/github/license/olimorris/hledger-forecast?color=%2361afef&style=for-the-badge"></a>
+<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.
 
@@ -42,7 +47,7 @@ The available options are:
 
 ### Generate command
 
-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 `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:
 
@@ -67,7 +72,7 @@ To work with hledger, include the forecast file and use the `--forecast` flag:
 
 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.
+> **Note**: To apply any modifiers, use the `--auto` flag at the end of your command.
 
 ### Summarize command
 
@@ -84,9 +89,9 @@ The available options are:
 
 ## :gear: Configuration
 
-### The YAML file
+### 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 and its [output](https://github.com/olimorris/hledger-forecast/blob/main/example.journal)
+> **Note**: See the [example.yml](https://github.com/olimorris/hledger-forecast/blob/main/example.yml) file for an example config and its corresponding [output](https://github.com/olimorris/hledger-forecast/blob/main/example.journal)
 
 Firstly, create a `yaml` file which will contain the transactions you'd like to forecast:
 
@@ -175,6 +180,17 @@ monthly:
         to: "2025-01-01"
 ```
 
+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
+  to: "=12"
+```
+
+This will take the `to` date to _2024-02-29_. This can be useful if you know a payment is due to end in _n_ months time and don't wish to use one of the many date calculators on the internet.
+
 ### Calculated amounts
 
 > **Note**: Calculations will be determined up to two decimal places
@@ -191,7 +207,7 @@ monthly:
         description: New Kitchen
 ```
 
-Simply ensure that the amount starts with an `=` sign, is enclosed in quotation marks and uses standard mathematical notations.
+Simply ensure that the amount starts with an `=` sign, is enclosed in quotation marks and uses standard mathematical notations. Of course, it may make sense to restrict this transaction with a `to` date in months, as per the [transaction level dates](#transaction-level) section.
 
 ### Tracking transactions
 
@@ -203,13 +219,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
@@ -220,7 +236,7 @@ To use this feature, ensure you pass a filepath to the `-t` flag, such as:
 
 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
+### Modifiers
 
 > **Note**: For modifiers to be included in your hledger reporting, use the `--auto` flag
 
@@ -228,17 +244,17 @@ Within your forecasts, it can be useful to reflect future increases/decreases in
 
 ```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"
+  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"
 ```
 
 This will generate an [auto-posting](https://hledger.org/dev/hledger.html#auto-postings) in your forecast which will
@@ -259,15 +275,15 @@ modifiers:
     to: "2025-12-31"
 ```
 
-### Additional settings
+### Additional config settings
 
 Additional settings in the config file to consider:
 
 ```yaml
 settings:
-  currency: GBP                 # Specify the currency to use
-  show_symbol: true             # Show the currency symbol?
-  thousands_separator: true     # Separate thousands with a comma?
+  currency: GBP # Specify the currency to use
+  show_symbol: true # Show the currency symbol?
+  thousands_separator: true # Separate thousands with a comma?
 ```
 
 ## :camera_flash: Screenshots
@@ -282,7 +298,7 @@ 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.
+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.
 

data/hledger-forecast.gemspec

@@ -4,6 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'hledger_forecast/version'
 
 Gem::Specification.new do |s|
+  s.required_ruby_version = '~> 3.0'
   s.name        = 'hledger-forecast'
   s.version     = HledgerForecast::VERSION
   s.authors     = ['Oli Morris']

data/lib/hledger_forecast/calculator.rb

@@ -0,0 +1,21 @@
+module HledgerForecast
+  # Calculate various
+  class Calculator
+    def initialize
+      @calculator = Dentaku::Calculator.new
+    end
+
+    def evaluate(amount)
+      return amount unless amount.is_a?(String)
+
+      @calculator.evaluate(amount.slice(1..-1))
+    end
+
+    def evaluate_date(from, to)
+      return to unless to[0] == "="
+
+      # Subtract a day from the final date
+      (from >> @calculator.evaluate(to.slice(1..-1))) - 1
+    end
+  end
+end

data/lib/hledger_forecast/cli.rb

@@ -155,8 +155,8 @@ module HledgerForecast
     end
 
     def self.summarize(options)
-      forecast = File.read(options[:forecast_file])
-      puts Summarize.generate(forecast)
+      config = File.read(options[:forecast_file])
+      puts Summarizer.summarize(config, options)
     end
   end
 end

data/lib/hledger_forecast/formatter.rb

@@ -0,0 +1,24 @@
+module HledgerForecast
+  # Formats various items used throughout the application
+  class Formatter
+    def self.format_money(amount, settings)
+      Money.from_cents(amount.to_f * 100, (settings[:currency]) || 'USD').format(
+        symbol: settings[:show_symbol] || true,
+        sign_before_symbol: settings[:sign_before_symbol] || false,
+        thousands_separator: settings[:thousands_separator] ? ',' : nil
+      )
+    end
+
+    def self.output_to_ledger(*compiled_data)
+      output = compiled_data.compact.map do |data|
+        data.map do |item|
+          next unless item[:transactions].any?
+
+          item[:header] + item[:transactions].join + item[:footer]
+        end.join
+      end.join("\n")
+
+      output.gsub(/\n{2,}/, "\n\n")
+    end
+  end
+end

data/lib/hledger_forecast/generator.rb

@@ -1,282 +1,65 @@
 module HledgerForecast
-  # Generates periodic transactions from a YAML file
+  # Generate forecasts for hledger from a yaml config file
   class Generator
-    class << self
-      attr_accessor :calculator, :options, :modified, :tracked
+    def self.generate(config, cli_options = nil)
+      new.generate(config, cli_options)
     end
 
-    self.calculator = {}
-    self.options = {}
-    self.modified = {}
-    self.tracked = {}
+    def generate(config, cli_options = nil)
+      forecast = YAML.safe_load(config)
+      @settings = Settings.config(forecast, cli_options)
 
-    def self.set_options(forecast_data)
-      @options[:max_amount] = get_max_field_size(forecast_data, 'amount') + 1 # +1 for the negatives
-      @options[:max_category] = get_max_field_size(forecast_data, 'category')
+      output = {}
+      forecast.each do |period, blocks|
+        next if %w[settings].include?(period)
 
-      @options[:currency] = Money::Currency.new(forecast_data.fetch('settings', {}).fetch('currency', 'USD'))
-      @options[:show_symbol] = forecast_data.fetch('settings', {}).fetch('show_symbol', true)
-      # @options[:sign_before_symbol] = forecast_data.fetch('settings', {}).fetch('sign_before_symbol', false)
-      @options[:thousands_separator] = forecast_data.fetch('settings', {}).fetch('thousands_separator', true)
-    end
-
-    def self.generate(yaml_file, options = nil)
-      forecast_data = YAML.safe_load(yaml_file)
-
-      set_options(forecast_data)
-
-      @calculator = Dentaku::Calculator.new
-
-      output = ""
-
-      # Generate regular transactions
-      forecast_data.each do |period, forecasts|
-        if period == 'custom'
-          output += custom_transaction(forecasts)
-        else
-          frequency = convert_period_to_frequency(period)
-          next unless frequency
-
-          forecasts.each do |forecast|
-            account = forecast['account']
-            from = Date.parse(forecast['from'])
-            to = forecast['to'] ? Date.parse(forecast['to']) : nil
-            transactions = forecast['transactions']
-
-            output += regular_transaction(frequency, from, to, transactions, account)
-            output += ending_transaction(frequency, from, transactions, account)
-          end
-        end
-      end
-
-      # Generate tracked transactions
-      if options && !options[:no_track] && !@tracked.empty?
-        if options[:transaction_file]
-          output += output_tracked_transaction(Tracker.track(@tracked,
-                                                             options[:transaction_file]))
-        else
-          puts "\nWarning: ".yellow.bold + "You need to specify a transaction file with the `--t` flag for smart transactions to work\n"
-        end
-      end
-
-      output += output_modified_transaction(@modified) unless @modified.empty?
-
-      output
-    end
-
-    def self.regular_transaction(frequency, from, to, transactions, account)
-      transactions = transactions.select { |transaction| transaction['to'].nil? }
-      return "" if transactions.empty?
-
-      output = ""
-
-      transactions.each do |transaction|
-        if track_transaction?(transaction, from)
-          track_transaction(from, to, account, transaction)
-          next
-        end
-
-        modified_transaction(from, to, account, transaction)
-
-        output += output_transaction(transaction['category'], format_amount(calculate_amount(transaction['amount'])),
-                                     transaction['description'])
-      end
-
-      return "" unless output != ""
-
-      output = if to
-                 "#{frequency} #{from} to #{to}  * #{extract_descriptions(transactions,
-                                                                          from)}\n" << output
-               else
-                 "#{frequency} #{from}  * #{extract_descriptions(transactions, from)}\n" << output
-               end
-
-      output += "    #{account}\n\n"
-      output
-    end
-
-    def self.ending_transaction(frequency, from, transactions, account)
-      output = ""
-
-      transactions.each do |transaction|
-        to = transaction['to'] ? Date.parse(transaction['to']) : nil
-        next unless to
-
-        if track_transaction?(transaction, from)
-          track_transaction(from, to, account, transaction)
-          next
-        end
-
-        modified_transaction(from, to, account, transaction)
-
-        output += "#{frequency} #{from} to #{to}  * #{transaction['description']}\n"
-        output += output_transaction(transaction['category'], format_amount(calculate_amount(transaction['amount'])),
-                                     transaction['description'])
-        output += "    #{account}\n\n"
-      end
-
-      output
-    end
-
-    def self.custom_transaction(forecasts)
-      output = ""
-
-      forecasts.each do |forecast|
-        account = forecast['account']
-        from = Date.parse(forecast['from'])
-        to = forecast['to'] ? Date.parse(forecast['to']) : nil
-        frequency = forecast['frequency']
-        transactions = forecast['transactions']
-
-        output += "~ #{frequency} from #{from}  * #{extract_descriptions(transactions, from)}\n"
-
-        transactions.each do |transaction|
-          to = transaction['to'] ? Date.parse(transaction['to']) : to
-
-          if track_transaction?(transaction, from)
-            track_transaction(from, to, account, transaction)
-            next
-          end
-
-          modified_transaction(from, to, account, transaction)
-
-          output += output_transaction(transaction['category'], format_amount(calculate_amount(transaction['amount'])),
-                                       transaction['description'])
+        blocks.each do |block|
+          output[output.length] = process_block(period, block)
         end
-
-        output += "    #{account}\n\n"
-      end
-
-      output
-    end
-
-    def self.output_transaction(category, amount, description)
-      "    #{category.ljust(@options[:max_category])}    #{amount.ljust(@options[:max_amount])};  #{description}\n"
-    end
-
-    def self.output_modified_transaction(transactions)
-      output = ""
-
-      transactions.each do |_key, transaction|
-        date = "date:#{transaction['from']}"
-        date += "..#{transaction['to']}" if transaction['to']
-
-        output += "= #{transaction['category']} #{date}\n"
-        output += "    #{transaction['category'].ljust(@options[:max_category])}    *#{transaction['amount'].to_s.ljust(@options[:max_amount] - 1)};  #{transaction['description']}\n"
-        output += "    #{transaction['account'].ljust(@options[:max_category])}    *#{transaction['amount'] * -1}\n\n"
       end
 
-      output
+      Formatter.output_to_ledger(
+        Transactions::Default.generate(output, @settings),
+        Transactions::Trackers.generate(output, @settings),
+        Transactions::Modifiers.generate(output, @settings)
+      )
     end
 
-    def self.output_tracked_transaction(transactions)
-      output = ""
-
-      transactions.each do |_key, transaction|
-        next if transaction['found']
-
-        output += "~ #{transaction['from']}  * [TRACKED] #{transaction['transaction']['description']}\n"
-        output += "    #{transaction['transaction']['category'].ljust(@options[:max_category])}    #{transaction['transaction']['amount'].ljust(@options[:max_amount])};  #{transaction['transaction']['description']}\n"
-        output += "    #{transaction['account']}\n\n"
-      end
+    private
 
-      output
-    end
+    def process_block(period, block)
+      output = []
 
-    def self.extract_descriptions(transactions, from)
-      descriptions = []
+      output << {
+        account: block['account'],
+        from: Date.parse(block['from']),
+        to: block['to'] ? Date.parse(block['to']) : nil,
+        type: period,
+        frequency: block['frequency'],
+        transactions: []
+      }
 
-      transactions.each do |transaction|
-        next if track_transaction?(transaction, from)
+      output = process_transactions(block, output)
 
-        description = transaction['description']
-        descriptions << description
+      output.map do |item|
+        transactions = item[:transactions].group_by { |t| t[:to] }
+        item.merge(transactions: transactions)
       end
-
-      descriptions.join(', ')
     end
 
-    def self.modified_transaction(from, to, account, transaction)
-      return unless transaction['modifiers']
-
-      transaction['modifiers'].each do |modifier|
-        description = transaction['description']
-        description += ' - ' + modifier['description'] unless modifier['description'].empty?
-
-        @modified[@modified.length] = {
-          'account' => account,
-          'amount' => modifier['amount'],
-          'category' => transaction['category'],
-          'description' => description,
-          'from' => modifier['from'] ? Date.parse(modifier['from']) : (from || nil),
-          'to' => modifier['to'] ? Date.parse(modifier['to']) : (to || nil)
+    def process_transactions(block, output)
+      block['transactions'].each do |t|
+        output.last[:transactions] << {
+          category: t['category'],
+          amount: Formatter.format_money(Calculator.new.evaluate(t['amount']), @settings),
+          description: t['description'],
+          to: t['to'] ? Calculator.new.evaluate_date(Date.parse(block['from']), t['to']) : nil,
+          modifiers: t['modifiers'] ? Transactions::Modifiers.get_modifiers(t, block) : [],
+          track: Transactions::Trackers.track?(t, block, @settings) ? true : false
         }
       end
-    end
 
-    def self.track_transaction?(transaction, from)
-      transaction['track'] && from <= Date.today
-    end
-
-    def self.track_transaction(from, to, account, transaction)
-      amount = calculate_amount(transaction['amount'])
-      transaction['amount'] = format_amount(amount)
-      transaction['inverse_amount'] = format_amount(amount * -1)
-
-      @tracked[@tracked.length] = {
-        'account' => account,
-        'from' => from,
-        'to' => to,
-        'transaction' => transaction
-      }
-    end
-
-    def self.convert_period_to_frequency(period)
-      map = {
-        'once' => '~',
-        'monthly' => '~ monthly from',
-        'quarterly' => '~ every 3 months from',
-        'half-yearly' => '~ every 6 months from',
-        'yearly' => '~ yearly from'
-      }
-
-      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],
-        sign_before_symbol: @options[:sign_before_symbol],
-        thousands_separator: @options[:thousands_separator] ? ',' : nil
-      )
-    end
-
-    def self.get_max_field_size(forecast_data, field)
-      max_size = 0
-
-      forecast_data.each do |period, forecasts|
-        next if period == 'settings'
-
-        forecasts.each do |forecast|
-          transactions = forecast['transactions']
-          transactions.each do |transaction|
-            field_value = if transaction[field].is_a?(Integer) || transaction[field].is_a?(Float)
-                            ((transaction[field] + 3) * 100).to_s
-                          else
-                            transaction[field].to_s
-                          end
-            max_size = [max_size, field_value.length].max
-          end
-        end
-      end
-
-      max_size
+      output
     end
   end
 end

data/lib/hledger_forecast/settings.rb

@@ -0,0 +1,41 @@
+module HledgerForecast
+  # Set the options from a user's confgi
+  class Settings
+    def self.config(forecast, cli_options)
+      settings = {}
+
+      settings[:max_amount] = get_max_field_size(forecast, 'amount') + 1 # +1 for the negatives
+      settings[:max_category] = get_max_field_size(forecast, 'category')
+
+      settings[:currency] = Money::Currency.new(forecast.fetch('settings', {}).fetch('currency', 'USD'))
+      settings[:show_symbol] = forecast.fetch('settings', {}).fetch('show_symbol', true)
+      # settings[:sign_before_symbol] = forecast.fetch('settings', {}).fetch('sign_before_symbol', false)
+      settings[:thousands_separator] = forecast.fetch('settings', {}).fetch('thousands_separator', true)
+
+      settings.merge!(cli_options) if cli_options
+
+      settings
+    end
+
+    def self.get_max_field_size(block, field)
+      max_size = 0
+
+      block.each do |period, items|
+        next if %w[settings].include?(period)
+
+        items.each do |item|
+          item['transactions'].each do |t|
+            field_value = if t[field].is_a?(Integer) || t[field].is_a?(Float)
+                            ((t[field] + 3) * 100).to_s
+                          else
+                            t[field].to_s
+                          end
+            max_size = [max_size, field_value.length].max
+          end
+        end
+      end
+
+      max_size
+    end
+  end
+end