hledger-forecast 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5ba12a84909e9d92ac3a9b1b5d977b661131fe6673f8a1c6e73f9ec57d790e2
-  data.tar.gz: 8f7f23fde8f640912eacb23982e198d67bfe83671c43eba6357a1cdde9a87528
+  metadata.gz: 0f769e017bc9ad46ea7d7571f74c64286e9c2415d0696e40f3301438a9038514
+  data.tar.gz: 52f69b30edfbc0c9d5430b88d25687c9c311d6c6aa4b1e5fd3b2815b3602d240
 SHA512:
-  metadata.gz: 33c532dc9e25ff41c968a1ada59379dbc56a9a0587e2abc4f07acdd10387c88b6f834ec6025dccb44e5ab5f4b3446341e09b947275e540857884728e84b5392a
-  data.tar.gz: 918e5be4d90e1bd52a75436ce0ded33a72e49dd29e9d0a112067eddf2b86693a8ac6c21bd027ed2148d28819e5af432e594a063ca28fdcbe14bceeaee335d283
+  metadata.gz: 2721eb985469db575b66172a94ee670e96711437da7b94f27da53301beed9f385b46c19121c9d365ce01fb0423ea5ea728ce511296c29adc26fc2051ff33e794
+  data.tar.gz: e41363954be45ca668dd73cc1a816b47a94419be53cde4fccdfc5a88a55601a2166e5f6eeb6532d4673c3bfe204020122165b71fabcca07a9dbf7cf0f1f80271

data/README.md

@@ -11,30 +11,30 @@
 <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>
 
-**"Improved", you say?** Using a _CSV_ (or _YML_) file, forecasts can be quickly generated into a _journal_ file ready to be fed into [hledger](https://github.com/simonmichael/hledger). **A 15 line [CSV file](https://github.com/olimorris/hledger-forecast/blob/main/example.csv) can generate a 42 line hledger [forecast file](https://github.com/olimorris/hledger-forecast/blob/main/example.journal)!**
+**"Improved", you say?** Using a _CSV_ (or _YML_) 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)!**
 
 Forecasts can also be constrained between dates, inflated by modifiers, tracked until they appear in your bank statements and summarized into your own daily/weekly/monthly/yearly personal forecast income and expenditure statement.
 
 ## :sparkles: Features
 
-- :muscle: Uses a simple CSV (or YML) file to generate forecasts which can be used with hledger
-- :date: Can smartly track forecasts against your bank statement
-- :moneybag: Can automatically apply modifiers such as inflation/deflation to forecasts
-- :abacus: Enables the use of maths in your forecasts (for amounts and dates)
-- :chart_with_upwards_trend: Display your forecasts as income and expenditure reports (e.g. daily, weekly, monthly)
+- :rocket: Uses a simple CSV (or YML) file to generate forecasts which can be used with hledger
+- :calendar: Can smartly track forecasts against your bank statement
+- :dollar: Can automatically apply modifiers such as inflation/deflation to forecasts
+- :mag: Enables the use of maths in your forecasts (for amounts and dates)
+- :bar_chart: Display your forecasts as income and expenditure reports (e.g. daily, weekly, monthly)
+- :twisted_rightwards_arrows: Compare and display the difference between hledger outputs
 - :computer: Simple and easy to use CLI
 
 ## :camera_flash: Screenshots
 
-**CSV forecast and corresponding journal output**
+**A CSV forecast and the hledger journal it generates**
 
-<img src="https://github.com/olimorris/hledger-forecast/assets/9512444/430503b5-f447-4972-b122-b48f8628aff9" alt="Hledger-Forecast" />
+<img src="https://github.com/olimorris/hledger-forecast/assets/9512444/430503b5-f447-4972-b122-b48f8628aff9" alt="hledger-Forecast" />
 
-**Output from the `summarize` command**
+**The ouput from the `summarize` command**
 
 <img src="https://github.com/olimorris/hledger-forecast/assets/9512444/f5017ea2-9606-46ec-8b38-8840dc175e7b" alt="Summarize command" />
 
-
 ## :package: Installation
 
 Assuming you have Ruby and [Rubygems](http://rubygems.org/pages/download) installed on your system, simply run:
@@ -52,8 +52,9 @@ The available options are:
     Usage: hledger-forecast [command] [options]
 
     Commands:
-      generate    Generate the forecast file
+      generate    Generate a forecast from a 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
@@ -91,9 +92,7 @@ If you use the `hledger-ui` tool, it may be helpful to use the `--verbose` flag.
 
 ### Summarize command
 
-As your configuration file grows, it can be helpful to sum up the total amounts and output them to the CLI.
-Furthermore, being able to see your monthly profit and loss statement _if_ you were to purchase that new item may
-influence your buying decision. In hledger-forecast, this can be achieved by:
+As your forecast file grows, it can be helpful to sum up the total amounts and output them to the CLI. Think of this command as your own _profit and loss_ summarizer, generating a statement over a period you specify.
 
     hledger-forecast summarize -f my_forecast.csv
 
@@ -107,6 +106,18 @@ The available options are:
     -v, --verbose                    Show additional information in the summary
     -h, --help                       Show this help message
 
+### Compare command
+
+A core part of managing your personal finances is the comparison of what you _expected_ to happen versus what _actually_ happened. This can be challenging to accomplish with hledger so to make this easier, the app has a useful `compare` command:
+
+    hledger-forecast compare [path/to/file1.csv] [path/to/file2.csv]
+
+To generate CSV output with hledger, append `-O csv > output.csv` to your desired command.
+
+To make it easier to read horizontal output in the terminal, consider the use of a terminal pager like [most](https://en.wikipedia.org/wiki/Most_(Unix)) by appending `| most` to the compare command.
+
+> **Note:** The two CSV files being compared must have the same structure
+
 ## :gear: Creating your forecast
 
 The app makes it easy to generate a comprehensive _journal_ file with very few lines of code, making it much easier to stay on top of your forecasting from month to month.
@@ -375,4 +386,3 @@ The app will use a hledger query to determine if the combination of category and
 ## :pencil2: Contributing
 
 I am open to any pull requests that fix bugs but would ask that any new functionality is discussed before it could be accepted.
-

data/lib/hledger_forecast/cli.rb

@@ -8,6 +8,8 @@ module HledgerForecast
         generate(options)
       when 'summarize'
         summarize(options)
+      when 'compare'
+        compare(options)
       else
         puts "Unknown command: #{command}"
         exit(1)
@@ -22,8 +24,9 @@ module HledgerForecast
         opts.banner = "Usage: hledger-forecast [command] [options]"
         opts.separator ""
         opts.separator "Commands:"
-        opts.separator "  generate    Generate the forecast file"
+        opts.separator "  generate    Generate a forecast from a file"
         opts.separator "  summarize   Summarize the forecast file and output to the terminal"
+        opts.separator "  compare     Compare and highlight the differences between two CSV files"
         opts.separator ""
         opts.separator "Options:"
 
@@ -38,6 +41,11 @@ module HledgerForecast
         end
       end
 
+      if args.empty?
+        puts global
+        exit(1)
+      end
+
       begin
         global.order!(args)
         command = args.shift || 'generate'
@@ -52,6 +60,8 @@ module HledgerForecast
         options = parse_generate_options(args)
       when 'summarize'
         options = parse_summarize_options(args)
+      when 'compare'
+        options = parse_compare_options(args)
       else
         puts "Unknown command: #{command}"
         puts global
@@ -64,7 +74,7 @@ module HledgerForecast
     def self.parse_generate_options(args)
       options = {}
 
-      OptionParser.new do |opts|
+      global = OptionParser.new do |opts|
         opts.banner = "Usage: hledger-forecast generate [options]"
         opts.separator ""
 
@@ -110,11 +120,24 @@ module HledgerForecast
           puts opts
           exit
         end
-      end.parse!(args)
+      end
+
+      begin
+        global.parse!(args)
+      rescue OptionParser::InvalidOption => e
+        puts e
+        puts global
+        exit(1)
+      end
+
+      if options.empty?
+        puts global
+        exit(1)
+      end
 
-      options[:forecast_file] = "forecast.csv" unless options[:forecast_file]
-      options[:file_type] = "csv" unless options[:file_type]
-      options[:output_file] = "forecast.journal" unless options[:output_file]
+      options[:forecast_file] ||= "forecast.csv"
+      options[:file_type] ||= "csv"
+      options[:output_file] ||= "forecast.journal"
 
       options
     end
@@ -122,7 +145,7 @@ module HledgerForecast
     def self.parse_summarize_options(args)
       options = {}
 
-      OptionParser.new do |opts|
+      global = OptionParser.new do |opts|
         opts.banner = "Usage: hledger-forecast summarize [options]"
         opts.separator ""
 
@@ -168,7 +191,47 @@ module HledgerForecast
           puts opts
           exit
         end
-      end.parse!(args)
+      end
+
+      begin
+        global.parse!(args)
+      rescue OptionParser::InvalidOption => e
+        puts e
+        puts global
+        exit(1)
+      end
+
+      if options.empty?
+        puts global
+        exit(1)
+      end
+
+      options
+    end
+
+    def self.parse_compare_options(args)
+      options = {}
+
+      global = OptionParser.new do |opts|
+        opts.banner = "Usage: hledger-forecast compare [path/to/file1.csv] [path/to/file2.csv]"
+        opts.separator ""
+      end
+
+      begin
+        global.parse!(args)
+      rescue OptionParser::InvalidOption => e
+        puts e
+        puts global
+        exit(1)
+      end
+
+      if args[0].nil? || args[1].nil?
+        puts global
+        exit(1)
+      end
+
+      options[:file1] = args[0]
+      options[:file2] = args[1]
 
       options
     end
@@ -210,5 +273,13 @@ module HledgerForecast
 
       puts SummarizerFormatter.format(summarizer[:output], summarizer[:settings])
     end
+
+    def self.compare(options)
+      if !File.exist?(options[:file1]) || !File.exist?(options[:file2])
+        return puts "\nError: ".bold.red + "One or more of the files could not be found to compare"
+      end
+
+      puts Comparator.compare(options[:file1], options[:file2])
+    end
   end
 end

data/lib/hledger_forecast/comparator.rb

@@ -0,0 +1,80 @@
+module HledgerForecast
+  # Compare the output of two CSV files
+  class Comparator
+    def initialize
+      @table = Terminal::Table.new
+    end
+
+    def self.compare(file1, file2)
+      new.compare(file1, file2)
+    end
+
+    def compare(file1, file2)
+      compare_csvs(file1, file2)
+    end
+
+    private
+
+    def compare_csvs(file1, file2)
+      csv1 = CSV.read(file1)
+      csv2 = CSV.read(file2)
+
+      unless csv1.length == csv2.length && csv1[0].length == csv2[0].length
+        return puts "\nError: ".bold.red + "The files have different formats and cannot be compared"
+      end
+
+      @table.add_row csv2[0].map(&:bold)
+      @table.add_separator
+
+      generate_diff(csv1, csv2).drop(1).each do |row|
+        @table.add_row [row[0].bold] + row[1..]
+      end
+
+      puts @table
+    end
+
+    def header?(row_num)
+      row_num == 0
+    end
+
+    def generate_diff(csv1, csv2)
+      csv1.each_with_index.map do |row, i|
+        row.each_with_index.map do |cell, j|
+          if header?(i) || j == 0 # Checking for the first column here
+            csv2[i][j]
+          else
+            difference = parse_money(cell) - parse_money(csv2[i][j])
+            format_difference(difference, detect_currency(cell))
+          end
+        end
+      end
+    end
+
+    def detect_currency(str)
+      # Explicitly check for common currencies first
+      return "GBP" if str.include?("£")
+      return "EUR" if str.include?("€")
+      return "USD" if str.include?("$")
+
+      Money::Currency.table.each_value do |currency|
+        return currency[:iso_code] if str.include?(currency[:symbol])
+      end
+
+      nil
+    end
+
+    def parse_money(value)
+      # Remove currency symbols and parse the result as a float, then convert to cents
+      cleaned_value = value.gsub(/[^0-9.]/, '').to_f
+      cleaned_value.to_i
+    end
+
+    def format_difference(amount, currency)
+      formatted_amount = Formatter.format_money(amount, { currency: currency })
+
+      return formatted_amount if amount == 0
+
+      amount > 0 ? formatted_amount.green : formatted_amount.red
+    end
+  end
+end

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

data/lib/hledger_forecast.rb

@@ -12,9 +12,11 @@ require 'yaml'
 
 Money.locale_backend = nil
 Money.rounding_mode = BigDecimal::ROUND_HALF_UP
+Money.default_currency = 'USD'
 
 require_relative 'hledger_forecast/calculator'
 require_relative 'hledger_forecast/cli'
+require_relative 'hledger_forecast/comparator'
 require_relative 'hledger_forecast/csv_parser'
 require_relative 'hledger_forecast/formatter'
 require_relative 'hledger_forecast/generator'

data/spec/{command_spec.rb → cli_spec.rb}

@@ -12,6 +12,19 @@ output = <<~JOURNAL
 
 JOURNAL
 
+def strip_ansi_codes(str)
+  str.gsub(/\e\[([;\d]+)?m/, "")
+end
+
+def capture_stdout
+  old_stdout = $stdout
+  $stdout = StringIO.new
+  yield
+  $stdout.string
+ensure
+  $stdout = old_stdout
+end
+
 RSpec.describe 'command' do
   it 'uses the CLI to generate an output' do
     generated_journal = './test_output.journal'
@@ -30,4 +43,19 @@ RSpec.describe 'command' do
 
     expect(File.read(generated_journal)).to eq(output)
   end
+
+  it 'uses the CLI to compare two CSV files' do
+    expected_output = strip_ansi_codes(<<~OUTPUT)
+      +---------+---------+---------+
+      | account | 2023-07 | 2023-08 |
+      +---------+---------+---------+
+      | total   | £-10.00 | €10.00  |
+      +---------+---------+---------+
+
+    OUTPUT
+
+    actual_output = `./bin/hledger-forecast compare ./spec/stubs/output1.csv ./spec/stubs/output2.csv`
+
+    expect(strip_ansi_codes(actual_output)).to eq(expected_output)
+  end
 end

data/spec/compare_spec.rb

@@ -0,0 +1,54 @@
+require_relative '../lib/hledger_forecast'
+require 'stringio'
+
+def strip_ansi_codes(str)
+  str.gsub(/\e\[([;\d]+)?m/, "")
+end
+
+def capture_stdout
+  old_stdout = $stdout
+  $stdout = StringIO.new
+  yield
+  $stdout.string
+ensure
+  $stdout = old_stdout
+end
+
+RSpec.describe HledgerForecast::Comparator do
+  let(:file1_content) do
+    <<~CSV
+      "account","2023-07","2023-08"
+      "total","£100.00","€200.00"
+    CSV
+  end
+
+  let(:file2_content) do
+    <<~CSV
+      "account","2023-07","2023-08"
+      "total","£110.00","€190.00"
+    CSV
+  end
+
+  let(:file1) { StringIO.new(file1_content) }
+  let(:file2) { StringIO.new(file2_content) }
+
+  before do
+    allow(CSV).to receive(:read).with('file1.csv').and_return(CSV.parse(file1.read))
+    allow(CSV).to receive(:read).with('file2.csv').and_return(CSV.parse(file2.read))
+  end
+
+  it "compares the contents of two CSV files and outputs the difference" do
+    comparator = described_class.new
+
+    expected_output = strip_ansi_codes(<<~OUTPUT)
+      +---------+---------+---------+
+      | account | 2023-07 | 2023-08 |
+      +---------+---------+---------+
+      | total   | £-10.00 | €10.00  |
+      +---------+---------+---------+
+    OUTPUT
+
+    actual_output = capture_stdout { comparator.compare('file1.csv', 'file2.csv') }
+    expect(strip_ansi_codes(actual_output)).to eq(expected_output)
+  end
+end

data/spec/stubs/output1.csv

@@ -0,0 +1,2 @@
+"account","2023-07","2023-08"
+"total","£100.00","€200.00"

data/spec/stubs/output2.csv

@@ -0,0 +1,2 @@
+"account","2023-07","2023-08"
+"total","£110.00","€190.00"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hledger-forecast
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Oli Morris
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-06-10 00:00:00.000000000 Z
+date: 2023-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: colorize
@@ -116,6 +116,7 @@ files:
 - lib/hledger_forecast.rb
 - lib/hledger_forecast/calculator.rb
 - lib/hledger_forecast/cli.rb
+- lib/hledger_forecast/comparator.rb
 - lib/hledger_forecast/csv_parser.rb
 - lib/hledger_forecast/formatter.rb
 - lib/hledger_forecast/generator.rb
@@ -126,7 +127,8 @@ files:
 - lib/hledger_forecast/transactions/modifiers.rb
 - lib/hledger_forecast/transactions/trackers.rb
 - lib/hledger_forecast/version.rb
-- spec/command_spec.rb
+- spec/cli_spec.rb
+- spec/compare_spec.rb
 - spec/computed_amounts_spec.rb
 - spec/csv_and_yml_comparison_spec.rb
 - spec/csv_parser_spec.rb
@@ -140,6 +142,8 @@ files:
 - spec/quarterly_spec.rb
 - spec/stubs/forecast.csv
 - spec/stubs/forecast.yml
+- spec/stubs/output1.csv
+- spec/stubs/output2.csv
 - spec/stubs/transactions_found.journal
 - spec/stubs/transactions_found_inverse.journal
 - spec/stubs/transactions_not_found.journal
@@ -166,12 +170,13 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.13
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: An extended wrapper around hledger's forecasting functionality
 test_files:
-- spec/command_spec.rb
+- spec/cli_spec.rb
+- spec/compare_spec.rb
 - spec/computed_amounts_spec.rb
 - spec/csv_and_yml_comparison_spec.rb
 - spec/csv_parser_spec.rb
@@ -185,6 +190,8 @@ test_files:
 - spec/quarterly_spec.rb
 - spec/stubs/forecast.csv
 - spec/stubs/forecast.yml
+- spec/stubs/output1.csv
+- spec/stubs/output2.csv
 - spec/stubs/transactions_found.journal
 - spec/stubs/transactions_found_inverse.journal
 - spec/stubs/transactions_not_found.journal