hledger-forecast 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d7bd2190c7f86b3d6a1fe76583a8f7e959f4429719b9903de343d25e0bf3b51
-  data.tar.gz: 7bb59da35fc2f9f3c47b6ed8b45d2ef38fb9c5c084c6bce9d6ee66fd004157a8
+  metadata.gz: 60e8bd939c2bb57d5d1fdf01d39d4fd7bc1cd59886a189b8b0d8a8fe7a7b6640
+  data.tar.gz: e752946a04d49b531ca303a8832d11a686d610392ce29d5a7d96c5aae2658dee
 SHA512:
-  metadata.gz: 3251f466cd2072685cf063268aca5c9ddc6231e9ac5c217049369c3e6b1c1d729967059441d4318247b7477ebaf357dc317e4f40df6b8e44dbe59a14b5005b9a
-  data.tar.gz: 55251b35a8cfea885fbbcb861ad650635a0fed4c91e618942ddd4eb76c38b9d3826d1b35e9078c1fae9c2ea96aa311cef750cc37fd88d5e4aed75ecb5c6db21f
+  metadata.gz: a7b44e5ceebc727be1a578a1210741fc5bbb9ec5e6d5a13feb36012bd35fb253173594ef0a35fb8448e1da697575ecdc97797473f7d5751db032a5065cce2bf8
+  data.tar.gz: c341817f928c9120662319a6ef9c1434d22b8872e685283b162ad4043efd9a0d1366eeeed4a58196e54708689833fa24af1b6b9e92dc59b8a75a98ad77810390

data/Gemfile

@@ -2,6 +2,7 @@
 
 source "https://rubygems.org"
 
+gem 'colorize'
 gem 'money'
 
 gemspec

data/README.md

@@ -37,6 +37,7 @@ Running `hledger-forecast -h` shows the available options:
         -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
+            --summarize                  Summarize the forecast file and output to the terminal
         -h, --help                       Show this message
             --version                    Show version
 
@@ -73,16 +74,17 @@ 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) to be explicit to Hledger. This also makes it easy to filter them out with the `-R` or `--real` option in Hledger
+- 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
 
 ### Extending the config file
 
 #### Periods
 
-If you'd like to add quarterly, yearly or one-off transactions, use the following keys:
+If you'd like to add quarterly, half-yearly, yearly or one-off transactions, use the following keys:
 
 - `quarterly`
+- `half-yearly`
 - `yearly`
 - `once`
 
@@ -112,6 +114,14 @@ settings:
   thousands_separator: true     # Separate thousands with a comma?
 ```
 
+### Summarizing the config file
+
+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:
+
+    hledger-forecast -f forecast.yml --summarize
+
+where `forecast.yml` is the config file to sum up.
+
 ## :brain: 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!

data/bin/hledger-forecast

@@ -9,4 +9,4 @@ rescue RuntimeError => e
   exit(1)
 end
 
-HledgerForecast::Command.run(options)
+HledgerForecast::CLI.run(options)

data/example.yml

@@ -17,6 +17,14 @@ quarterly:
         category: "[Income:Bonus]"
         description: Bonus
 
+half-yearly:
+  - account: "[Assets:Bank]"
+    date: "2023-04-01"
+    transactions:
+      - amount: 500
+        category: "[Expenses:Holiday]"
+        description: Holiday
+
 yearly:
   - account: "[Assets:Bank]"
     date: "2023-04-01"
@@ -35,6 +43,6 @@ once:
 
 settings:
   currency: GBP
-  show_symbol: false
+  show_symbol: true
   sign_before_symbol: true
-  thousands_separator: false
+  thousands_separator: true

data/hledger-forecast.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |s|
 
   s.add_dependency "highline", "~> 2.1.0"
   s.add_dependency "money", "~> 6.16.0"
+  s.add_dependency "colorize", "~> 0.8.1"
   s.add_development_dependency 'rspec', '~> 3.12'
 
   s.files = `git ls-files`.split("\n")

data/lib/hledger_forecast/{command.rb → cli.rb}

@@ -1,11 +1,13 @@
 module HledgerForecast
-  class Command
+  class CLI
     def self.run(args)
       end_date = args[:end_date]
       start_date = args[:start_date]
       forecast = File.read(args[:forecast_file])
       transactions = args[:transactions_file] ? File.read(args[:transactions_file]) : nil
 
+      return HledgerForecast::Summarize.generate(forecast) if args[:summarize]
+
       puts "[Using default dates: #{start_date} to #{end_date}]" if args[:default_dates]
 
       transactions = Generator.create_journal_entries(transactions, forecast, start_date, end_date)

data/lib/hledger_forecast/generator.rb

@@ -29,7 +29,7 @@ module HledgerForecast
         Money.from_cents(formatted_transaction['amount'].to_i * 100, @settings[:currency]).format(
           symbol: @settings[:show_symbol],
           sign_before_symbol: @settings[:sign_before_symbol],
-          thousands_separator: @settings[:thousands_separator] ? ',' : nil
+          thousands_separator: @settings[:thousands_separator] ? ',' : nil,
         )
 
       formatted_transaction
@@ -48,6 +48,8 @@ module HledgerForecast
                          date.day == start_date.day
                        when 'quarterly'
                          date.day == start_date.day && date.month % 3 == start_date.month % 3
+                       when 'half-yearly'
+                         date.day == start_date.day && (date.month - start_date.month) % 6 == 0
                        when 'yearly'
                          date.day == start_date.day && date.month == start_date.month
                        when 'once'
@@ -81,6 +83,7 @@ module HledgerForecast
       while date <= end_date
         process_forecast(output, forecast_data, 'monthly', date)
         process_forecast(output, forecast_data, 'quarterly', date)
+        process_forecast(output, forecast_data, 'half-yearly', date)
         process_forecast(output, forecast_data, 'yearly', date)
         process_forecast(output, forecast_data, 'once', date)
 

data/lib/hledger_forecast/options.rb

@@ -32,6 +32,11 @@ module HledgerForecast
           options[:end_date] = a
         end
 
+        opts.on("--summarize",
+                "Summarize the forecast file and output to the terminal") do |a|
+          options[:summarize] = a
+        end
+
         opts.on("--force",
                 "Force an overwrite of the output file") do |a|
           options[:force] = a

data/lib/hledger_forecast/summarize.rb

@@ -0,0 +1,68 @@
+module HledgerForecast
+  # Summarise a forecast YAML file and output it to the CLI
+  class Summarize
+    def self.sum_transactions(forecast_data, period)
+      category_totals = Hash.new(0)
+      forecast_data[period]&.each do |entry|
+        entry['transactions'].each do |transaction|
+          category_totals[transaction['category']] += transaction['amount']
+        end
+      end
+      category_totals
+    end
+
+    def self.print_category_totals(period, category_totals, generator)
+      puts "#{period.capitalize}:"
+      period_total = 0
+
+      category_totals.each do |category, amount|
+        formatted_amount = generator.format_transaction({ 'amount' => amount })['amount']
+        formatted_amount = amount.to_i < 0 ? formatted_amount.red : formatted_amount.green
+        puts "  #{category.ljust(40)}#{formatted_amount}"
+        period_total += amount
+      end
+
+      formatted_period_total = generator.format_transaction({ 'amount' => period_total })['amount']
+      formatted_period_total = period_total.to_i < 0 ? formatted_period_total.red : formatted_period_total.green
+      puts "  TOTAL".ljust(42) + formatted_period_total
+    end
+
+    def self.sum_all_periods(forecast_data)
+      periods = %w[monthly quarterly half-yearly yearly once]
+      total = {}
+      grand_total = 0
+
+      periods.each do |period|
+        total[period] = sum_transactions(forecast_data, period)
+        grand_total += total[period]
+      end
+
+      total['total'] = grand_total
+      total
+    end
+
+    def self.generate(forecast)
+      forecast_data = YAML.safe_load(forecast)
+
+      category_totals_by_period = {}
+      %w[monthly quarterly half-yearly yearly once].each do |period|
+        category_totals_by_period[period] = sum_transactions(forecast_data, period)
+      end
+
+      grand_total = category_totals_by_period.values.map(&:values).flatten.sum
+
+      generator = HledgerForecast::Generator
+      generator.configure_settings(forecast_data)
+
+      puts
+      category_totals_by_period.each do |period, category_totals|
+        print_category_totals(period, category_totals, generator)
+        puts
+      end
+
+      formatted_grand_total = generator.format_transaction({ 'amount' => grand_total })['amount']
+      formatted_grand_total = grand_total.to_i < 0 ? formatted_grand_total.red : formatted_grand_total.green
+      puts "TOTAL:".ljust(42) + formatted_grand_total
+    end
+  end
+end

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "0.1.4"
+  VERSION = "0.1.6"
 end

data/lib/hledger_forecast.rb

@@ -1,5 +1,6 @@
 #!/usr/bin/env ruby
 
+require 'colorize'
 require 'date'
 require 'highline'
 require 'money'
@@ -12,4 +13,5 @@ Money.rounding_mode = BigDecimal::ROUND_HALF_UP
 require_relative 'hledger_forecast/version'
 require_relative 'hledger_forecast/options'
 require_relative 'hledger_forecast/generator'
-require_relative 'hledger_forecast/command'
+require_relative 'hledger_forecast/summarize'
+require_relative 'hledger_forecast/CLI'

data/spec/half-yearly_spec.rb

@@ -0,0 +1,13 @@
+require_relative '../lib/hledger_forecast'
+
+RSpec.describe 'generate' do
+  it 'generates a forecast with correct HALF-YEARLY transactions' do
+    transactions = File.read('spec/stubs/transactions.journal')
+    forecast = File.read('spec/stubs/half-yearly/forecast_half-yearly.yml')
+
+    generated_journal = HledgerForecast::Generator.create_journal_entries(transactions, forecast, '2023-03-01', '2024-04-30')
+
+    expected_output = File.read('spec/stubs/half-yearly/output_half-yearly.journal')
+    expect(generated_journal).to eq(expected_output)
+  end
+end

data/spec/stubs/half-yearly/forecast_half-yearly.yml

@@ -0,0 +1,10 @@
+settings:
+  currency: GBP
+
+half-yearly:
+  - start: "2023-04-01"
+    account: "[Assets:Bank]"
+    transactions:
+      - description: Holiday
+        category: "[Expenses:Holiday]"
+        amount: 500

data/spec/stubs/half-yearly/output_half-yearly.journal

@@ -0,0 +1,20 @@
+2023-02-01 * Opening balance
+    Assets:Bank                             £1,000.00
+    Equity:Opening balance
+
+2023-02-05 * Mortgage payment
+    Expenses:Mortgage                 £1,500.00
+    Assets:Bank
+
+2023-04-01 * Holiday
+    [Expenses:Holiday]                £500.00
+    [Assets:Bank]
+
+2023-10-01 * Holiday
+    [Expenses:Holiday]                £500.00
+    [Assets:Bank]
+
+2024-04-01 * Holiday
+    [Expenses:Holiday]                £500.00
+    [Assets:Bank]
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Oli Morris
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 6.16.0
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.1
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -70,14 +84,18 @@ files:
 - example.yml
 - hledger-forecast.gemspec
 - lib/hledger_forecast.rb
-- lib/hledger_forecast/command.rb
+- lib/hledger_forecast/cli.rb
 - lib/hledger_forecast/generator.rb
 - lib/hledger_forecast/options.rb
+- lib/hledger_forecast/summarize.rb
 - lib/hledger_forecast/version.rb
 - spec/command_spec.rb
+- spec/half-yearly_spec.rb
 - spec/monthly_spec.rb
 - spec/once_spec.rb
 - spec/quarterly_spec.rb
+- spec/stubs/half-yearly/forecast_half-yearly.yml
+- spec/stubs/half-yearly/output_half-yearly.journal
 - spec/stubs/monthly/forecast_monthly.yml
 - spec/stubs/monthly/forecast_monthly_enddate.yml
 - spec/stubs/monthly/forecast_monthly_enddate_top.yml
@@ -119,9 +137,12 @@ specification_version: 4
 summary: Utility to generate forecasts in Hledger
 test_files:
 - spec/command_spec.rb
+- spec/half-yearly_spec.rb
 - spec/monthly_spec.rb
 - spec/once_spec.rb
 - spec/quarterly_spec.rb
+- spec/stubs/half-yearly/forecast_half-yearly.yml
+- spec/stubs/half-yearly/output_half-yearly.journal
 - spec/stubs/monthly/forecast_monthly.yml
 - spec/stubs/monthly/forecast_monthly_enddate.yml
 - spec/stubs/monthly/forecast_monthly_enddate_top.yml