hledger-forecast 3.0.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 33ae1c8b9a296f2420b87963e12ccc77a6a4b18cb5e9e977ed6e17f3d83b3c03
-  data.tar.gz: f4a4e1fa8df7a5d982036349903ce6a38b68edc59f2734be1ebc12a071ebf27f
+  metadata.gz: 5acfd1bbab287a58bfe5ce7237576535b6b927d034da9e3651a4c240653e0f33
+  data.tar.gz: 23eb8d2646996b422473440b8f90797215a7390f4d6e2862b470bd361b6d55d5
 SHA512:
-  metadata.gz: 1942ba18912517ceb70a6f2e4639632f5bccb6c98945d88509405c046e41c59631bebb099f15c89cc630ebca270360d5efd2c9eaea9fe7449eeb9be2fc5d9dee
-  data.tar.gz: d717115be6e73cf7277f29e01d4f465a63f1e03c88271a16ecd9df20600430b0d7483dc5f9a4c1831796a71413fb8bb2df9adb9f9dd5b3fd4c583c7e3e79a5fa
+  metadata.gz: 62a027f56e0faf7641769b13928ed61c91e3851fe6b1623df00efd233ec244be03c57d7b94ea2605f01580ba18e0a916807a59c6ef848118d9b80fa9a3e8be28
+  data.tar.gz: 470b89a138eff0a2f5da24d4a4fe31ffd7e9584646094665020d19a40a9303877073bfcbc95eb35eae1498149fbfa96b899bd44c5ee4eab4225f26acec9b2e11

data/.github/workflows/release.yml

@@ -13,9 +13,36 @@ jobs:
       contents: write
       pull-requests: write
 
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+
     steps:
-      - name: Release 📦
+      - name: Release
+        id: release
         uses: googleapis/release-please-action@v4
         with:
           release-type: ruby
 
+  publish:
+    runs-on: ubuntu-latest
+    needs: release
+    if: needs.release.outputs.release_created == 'true'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+
+      - name: Publish to RubyGems
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push *.gem
+        env:
+          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [3.2.0](https://github.com/olimorris/hledger-forecast/compare/v3.1.0...v3.2.0) (2026-04-13)
+
+
+### Features
+
+* can exclude tags in summarizer ([#16](https://github.com/olimorris/hledger-forecast/issues/16)) ([faee83e](https://github.com/olimorris/hledger-forecast/commit/faee83ee8eb554d146177832c307b87f5ecd4616))
+* from date can have calculations ([#18](https://github.com/olimorris/hledger-forecast/issues/18)) ([e62a693](https://github.com/olimorris/hledger-forecast/commit/e62a69385bf6c34f2d446593d5046fe22a1e7f5f))
+
+## [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]
@@ -146,8 +147,8 @@ The CSV file should have a header row with these columns:
 | `type` | string | yes | One of: `monthly`, `quarterly`, `half-yearly`, `yearly`, `once`, `custom` |
 | `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` |
+| `from` | date | yes | Start date, e.g. `01/03/2023`. Supports `=` prefix for calculated values, e.g. `=01/03/2023+(5*12)` |
+| `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,29 @@ 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":
+Both `from` and `to` support calculated values.
+
+**`from` column** — prefix with `=` to compute a start date. The formula is `=BASE_DATE+OFFSET` where the offset is evaluated as months:
 
 ```csv
-monthly,,Assets:Bank,01/03/2023,=12,Holiday,Expenses:Holiday,125,,
+monthly,,Assets:Bank,=01/09/2025+(5*12),,Salary,Income:Salary,-3500,,
 ```
 
-That sets the end date to 12 months after `01/03/2023`.
+That sets the start date to 60 months (5 years) after `01/09/2025`, giving `01/09/2030`.
+
+**`to` column** — 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/2026,=12*5,Mortgage,Expenses:Mortgage,2000,,
+```
+
+That sets the end date to 5 years (60 months) after `01/03/2026`.
 
 ### Tags
 
@@ -228,6 +245,9 @@ hledger-forecast summarize -f forecast.csv --tags=essential
 
 # Multiple tags use OR logic — matches any
 hledger-forecast summarize -f forecast.csv --tags=fixed,living
+
+# Can also exclude tags with a `-` prefix
+hledger-forecast summarize -f forecast.csv --tags=fixed,-essential
 ```
 
 **Querying in hledger** - because the tags are native hledger format, you can query them directly:

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

@@ -8,8 +8,20 @@ module HledgerForecast
       @calc.evaluate(amount.slice(1..-1))
     end
 
+    def self.evaluate_from_date(value)
+      value = value.to_s
+      return Date.parse(value) unless value.start_with?("=")
+
+      date_str, offset_expr = value[1..].split("+", 2)
+      date = Date.parse(date_str)
+      return date unless offset_expr
+
+      date >> @calc.evaluate(offset_expr).to_i
+    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

@@ -24,13 +24,13 @@ module HledgerForecast
     keyword_init: true
   ) do
     def self.from_row(row)
-      from = Date.parse(row[:from].to_s)
+      from = Calculator.evaluate_from_date(row[:from])
       new(
         type: row[:type],
         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]),
@@ -42,7 +42,14 @@ module HledgerForecast
 
     def matches_tags?(filter_tags)
       return true if filter_tags.nil? || filter_tags.empty?
-      (tags & filter_tags).any?
+
+      exclude_tags = filter_tags.select { |t| t.start_with?("-") }.map { |t| t[1..] }
+      include_tags = filter_tags.reject { |t| t.start_with?("-") }
+
+      return false if exclude_tags.any? && (tags & exclude_tags).any?
+      return (tags & include_tags).any? if include_tags.any?
+
+      true
     end
 
     def annualised_amount

data/lib/hledger_forecast/version.rb

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

data/spec/calculator_spec.rb

@@ -23,6 +23,24 @@ RSpec.describe HledgerForecast::Calculator do
     end
   end
 
+  describe ".evaluate_from_date" do
+    it "parses a plain date string" do
+      expect(described_class.evaluate_from_date("01/09/2022")).to(eq(Date.parse("2022-09-01")))
+    end
+
+    it "evaluates a date with a month offset" do
+      expect(described_class.evaluate_from_date("=01/09/2022+6")).to(eq(Date.parse("2023-03-01")))
+    end
+
+    it "evaluates a date with a multiplied offset" do
+      expect(described_class.evaluate_from_date("=01/09/2022+(5*12)")).to(eq(Date.parse("2027-09-01")))
+    end
+
+    it "evaluates a formula with no offset" do
+      expect(described_class.evaluate_from_date("=01/09/2022")).to(eq(Date.parse("2022-09-01")))
+    end
+  end
+
   describe ".evaluate_date" do
     let(:from) { Date.parse("2023-03-01") }
 
@@ -41,5 +59,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

data/spec/tags_spec.rb

@@ -72,6 +72,32 @@ RSpec.describe "tags" do
     expect(descriptions).to(eq(["Food", "Netflix"]))
   end
 
+  it "excludes transactions by tag with - prefix" do
+    result = HledgerForecast::Summarizer.summarize(config, {tags: ["-fixed"]})
+    descriptions = result[:output].map { |r| r[:description] }
+
+    expect(descriptions).to(eq(["Food", "Netflix"]))
+  end
+
+  it "excludes tags in generator output" do
+    expected = <<~JOURNAL
+      ~ monthly from 2023-03-01  * Food, Netflix
+          Expenses:Food             £500.00;  living:, essential:
+          Expenses:Subscriptions    £15.00 ;  living:
+          Assets:Bank
+
+    JOURNAL
+
+    expect(HledgerForecast::Generator.generate(config, {tags: ["-fixed"]})).to(eq(expected))
+  end
+
+  it "combines include and exclude tags" do
+    result = HledgerForecast::Summarizer.summarize(config, {tags: ["essential", "-fixed"]})
+    descriptions = result[:output].map { |r| r[:description] }
+
+    expect(descriptions).to(eq(["Food"]))
+  end
+
   it "raises an error when --tags is used on a CSV without a tag column" do
     csv_without_tag_column = <<~CSV
       type,frequency,account,from,to,description,category,amount,roll-up,summary_exclude

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-04-13 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
@@ -130,7 +132,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/ci.yml"
-- ".github/workflows/publish_ruby_gem.yml"
 - ".github/workflows/release.yml"
 - ".gitignore"
 - ".mise.toml"
@@ -139,6 +140,7 @@ files:
 - Gemfile
 - LICENSE
 - README.md
+- Rakefile
 - bin/hledger-forecast
 - example.csv
 - example.journal
@@ -198,10 +200,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.20
+rubygems_version: 3.5.22
 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

data/.github/workflows/publish_ruby_gem.yml

@@ -1,24 +0,0 @@
-name: Publish Ruby Gem
-
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-      - name: Publish Gem 💎️
-        run: |
-          mkdir -p $HOME/.gem
-          touch $HOME/.gem/credentials
-          chmod 0600 $HOME/.gem/credentials
-          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-          gem build *.gemspec
-          gem push *.gem
-        env:
-          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"