hledger-forecast 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33ae1c8b9a296f2420b87963e12ccc77a6a4b18cb5e9e977ed6e17f3d83b3c03
-  data.tar.gz: f4a4e1fa8df7a5d982036349903ce6a38b68edc59f2734be1ebc12a071ebf27f
+  metadata.gz: 914475b3b188c0bf0950e6d2e0a88eb374a4486d41c901603c8cb41332e268f7
+  data.tar.gz: 241b415b6b95b42e757fd5302700cb4b6395bdce105f00782a49b0149be6b2d5
 SHA512:
-  metadata.gz: 1942ba18912517ceb70a6f2e4639632f5bccb6c98945d88509405c046e41c59631bebb099f15c89cc630ebca270360d5efd2c9eaea9fe7449eeb9be2fc5d9dee
-  data.tar.gz: d717115be6e73cf7277f29e01d4f465a63f1e03c88271a16ecd9df20600430b0d7483dc5f9a4c1831796a71413fb8bb2df9adb9f9dd5b3fd4c583c7e3e79a5fa
+  metadata.gz: cc7ee657e34ec05931165642761b797ec783d1c5c370d6085777d494503782efd32d140aea61e1e9f0d005ce5a6b69f5e28250a3c4150225ce70e5fbcc840a22
+  data.tar.gz: 5e6de9e3a6da7531b7d6a4f47b6126e6c34f92ba387cbdcb21584053530f46447d74c9a472bd34e89b566b731c6f71b56a826d17e2613632ae46f435bdbe9d65

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [3.1.0](https://github.com/olimorris/hledger-forecast/compare/v3.0.0...v3.1.0) (2026-04-02)
+
+
+### Features
+
+* dates now support `+` prefix ([#14](https://github.com/olimorris/hledger-forecast/issues/14)) ([16ee70e](https://github.com/olimorris/hledger-forecast/commit/16ee70ec6d3a717f679fddcbf22324f71010e93d))
+
 ## [3.0.0](https://github.com/olimorris/hledger-forecast/compare/v2.0.1...v3.0.0) (2026-03-27)
 
 

data/README.md

@@ -9,6 +9,7 @@
 <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>
 <a href="https://github.com/olimorris/hledger-forecast/releases"><img src="https://img.shields.io/github/v/release/olimorris/hledger-forecast?style=for-the-badge"</a>
 </p>
+
 **"Improved", you say?** Using a _CSV_ file, forecasts can be quickly generated into a _journal_ file ready to be fed into [hledger](https://github.com/simonmichael/hledger). **A 16 line [CSV file](https://github.com/olimorris/hledger-forecast/blob/main/example.csv) can generate a 46 line hledger [forecast file](https://github.com/olimorris/hledger-forecast/blob/main/example.journal)!**
 
 ## :sparkles: Features
@@ -37,7 +38,7 @@ Except, you'd need to work out what 20 months from `2026-01-01` is and do $3000
 In `hledger-forecast`, you add a single line to your CSV:
 
 ```csv
-monthly,,Assets:Checking,01/01/2026,=20,New Laptop,Expenses:General Expenses,=3000/20,,,
+monthly,,Assets:Checking,01/01/2026,+20,New Laptop,Expenses:General Expenses,=3000/20,,,
 ```
 
 The tool calculates the amount and the end date for you.
@@ -67,14 +68,14 @@ Assuming you have Ruby and [RubyGems](http://rubygems.org/pages/download) instal
 ## :rocket: Usage
 
     hledger-forecast
-    
+
     Usage: hledger-forecast [command] [options]
-    
+
     Commands:
       generate    Generate a forecast from a CSV file
       summarize   Summarize the forecast file and output to the terminal
       compare     Compare and highlight the differences between two CSV files
-    
+
     Options:
         -h, --help                       Show this help message
         -v, --version                    Show version
@@ -84,9 +85,9 @@ Assuming you have Ruby and [RubyGems](http://rubygems.org/pages/download) instal
 Reads your CSV file and creates a journal file ready to use with hledger. See [example.journal](https://github.com/olimorris/hledger-forecast/blob/main/example.journal) for an example of the output.
 
     hledger-forecast generate -f my_forecast.csv -o forecast.journal
-    
+
     Usage: hledger-forecast generate [options]
-    
+
       -f, --forecast FILE              The path to the FORECAST CSV file to generate from
       -o, --output-file FILE           The path to the OUTPUT file to create
       -t, --tags TAGS                  Only include transactions with given tags (comma-separated)
@@ -111,9 +112,9 @@ This will generate a forecast up to the end of Feb 2027, showing asset balances
 As your forecast grows, it's useful to see the totals at a glance. Think of this as your income statement, rolled up to whatever period makes sense.
 
     hledger-forecast summarize -f my_forecast.csv
-    
+
     Usage: hledger-forecast summarize [options]
-    
+
       -f, --forecast FILE              The path to the FORECAST CSV file to summarize
       -r, --roll-up PERIOD             The period to roll-up your forecasts into. One of:
                                        [yearly], [half-yearly], [quarterly], [monthly], [weekly], [daily]
@@ -147,7 +148,7 @@ The CSV file should have a header row with these columns:
 | `frequency` | string | `custom` only | Repeating frequency, using hledger's [periodic rule syntax](https://hledger.org/dev/hledger.html#periodic-transactions) |
 | `account` | string | yes | The account the transaction applies to, e.g. `Assets:Bank` |
 | `from` | date | yes | Start date, e.g. `01/03/2023` |
-| `to` | date | no | End date, e.g. `01/01/2025` |
+| `to` | date | no | End date, e.g. `01/01/2025`. Supports `+` prefix for calculated values, e.g. `+12` for 12 months |
 | `description` | string | yes | A description of the transaction |
 | `category` | string | yes | The category account, e.g. `Expenses:Food` |
 | `amount` | number | yes | The transaction amount. Supports `=` prefix for calculated values |
@@ -164,7 +165,7 @@ monthly,,Assets:Bank,01/03/2023,01/01/2025,Mortgage,Expenses:Mortgage,2000,,,fix
 monthly,,Assets:Bank,01/03/2023,,Bills,Expenses:Bills,175,,,fixed|essential
 monthly,,Assets:Bank,01/03/2023,,Food,Expenses:Food,500,,,living|essential
 monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,,living
-monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,,living
+monthly,,Assets:Bank,01/03/2023,+12,Holiday,Expenses:Holiday,125,,,living
 monthly,,Assets:Bank,01/03/2023,01/03/2025,Rainy day fund,Assets:Savings,300,,,saving
 monthly,,Assets:Pension,01/01/2024,,Pension draw down,Income:Pension,-500,,,fixed|essential
 quarterly,,Assets:Bank,01/04/2023,,Quarterly bonus,Income:Bonus,-1000,,,fixed
@@ -188,13 +189,19 @@ monthly,,Assets:Bank,01/03/2023,,New Kitchen,Expenses:House,=5000/24,,
 
 ### Calculated dates
 
-The `to` column also supports calculated values. Use `=` followed by a number to mean "N months from the `from` date":
+The `to` column supports calculated values. Use `+` followed by a number to mean "N months from the `from` date":
+
+```csv
+monthly,,Assets:Bank,01/03/2026,+12,Holiday,Expenses:Holiday,125,,
+```
+
+That sets the end date to 12 months after `01/03/2026`. The `=` prefix also supports formulas — useful for longer periods:
 
 ```csv
-monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,
+monthly,,Assets:Bank,01/03/2026,=12*5,Mortgage,Expenses:Mortgage,2000,,
 ```
 
-That sets the end date to 12 months after `01/03/2023`.
+That sets the end date to 5 years (60 months) after `01/03/2026`.
 
 ### Tags
 

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/example.csv

@@ -10,7 +10,7 @@ monthly,,Assets:Pension,01/01/2024,,Pension draw down,Income:Pension,-500,,,fixe
 quarterly,,Assets:Bank,01/04/2023,,Quarterly bonus,Income:Bonus,-1000,,,fixed
 half-yearly,,Assets:Bank,01/04/2023,,Top up holiday funds,Expenses:Holiday,500,,,living
 yearly,,Assets:Bank,01/04/2023,,Annual bonus,Income:Bonus,-2000,,,fixed
-once,,Assets:Bank,05/03/2023,,Refund for that damn laptop,Expenses:Shopping,-3000,TRUE,
+once,,Assets:Bank,05/03/2023,,Refund for that damn laptop,Expenses:Shopping,-3000,,,
 custom,every 2 weeks,Assets:Bank,01/03/2023,,Hair and beauty,Expenses:Personal Care,80,26,,living
 custom,every 5 weeks,Assets:Bank,01/03/2023,,Misc expenses,Expenses:General Expenses,30,10.4,,living
 settings,currency,USD,,,,,,,,

data/hledger-forecast.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.name = "hledger-forecast"
   s.version = HledgerForecast::VERSION
   s.authors = ["Oli Morris"]
-  s.summary = "An extended wrapper around hledger's forecasting functionality"
-  s.description = "Use a CSV file for improved forecasting with hledger"
+  s.summary = "Generate hledger journal entries and income statements from a CSV forecast"
+  s.description = "Define recurring transactions in a CSV file with support for formulas, calculated dates, and tags. Generates hledger periodic transaction journals and provides income statement summaries with savings rates."
   s.email = "olimorris@users.noreply.github.com"
   s.homepage = "https://github.com/olimorris/hledger-forecast"
   s.license = "MIT"

data/lib/hledger_forecast/calculator.rb

@@ -9,7 +9,8 @@ module HledgerForecast
     end
 
     def self.evaluate_date(from, to)
-      return Date.parse(to) unless to.start_with?("=")
+      return (from >> to) - 1 if to.is_a?(Numeric)
+      return Date.parse(to) unless to.start_with?("=") || to.start_with?("+")
 
       (from >> @calc.evaluate(to.slice(1..-1))) - 1
     end

data/lib/hledger_forecast/transaction.rb

@@ -30,7 +30,7 @@ module HledgerForecast
         frequency: row[:frequency],
         account: row[:account],
         from: from,
-        to: row[:to] ? Calculator.evaluate_date(from, row[:to].to_s) : nil,
+        to: row[:to] ? Calculator.evaluate_date(from, row[:to]) : nil,
         description: row[:description],
         category: row[:category],
         amount: Calculator.evaluate(row[:amount]),

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "3.0.0"
+  VERSION = "3.1.0"
 end

data/spec/calculator_spec.rb

@@ -41,5 +41,13 @@ RSpec.describe HledgerForecast::Calculator do
     it "handles a 24-month offset" do
       expect(described_class.evaluate_date(from, "=24")).to(eq(Date.parse("2025-02-28")))
     end
+
+    it "handles dates with a +" do
+      expect(described_class.evaluate_date(from, "+24")).to(eq(Date.parse("2025-02-28")))
+    end
+
+    it "handles a numeric offset (CSV numeric converter coerces +N to integer)" do
+      expect(described_class.evaluate_date(from, 24)).to(eq(Date.parse("2025-02-28")))
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: abbrev
@@ -122,7 +122,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
-description: Use a CSV file for improved forecasting with hledger
+description: Define recurring transactions in a CSV file with support for formulas,
+  calculated dates, and tags. Generates hledger periodic transaction journals and
+  provides income statement summaries with savings rates.
 email: olimorris@users.noreply.github.com
 executables:
 - hledger-forecast
@@ -139,6 +141,7 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- Rakefile
 - bin/hledger-forecast
 - example.csv
 - example.journal
@@ -201,7 +204,7 @@ requirements: []
 rubygems_version: 3.4.20
 signing_key:
 specification_version: 4
-summary: An extended wrapper around hledger's forecasting functionality
+summary: Generate hledger journal entries and income statements from a CSV forecast
 test_files:
 - spec/calculator_spec.rb
 - spec/cli_spec.rb