hledger-forecast 2.0.0 → 3.0.0

data/lib/hledger_forecast/settings.rb

@@ -1,56 +1,43 @@
 module HledgerForecast
-  # Set the options from a user's config
   class Settings
-    def self.config(forecast, cli_options)
-      settings = {}
-      settings[:max_amount] = 0
-      settings[:max_category] = 0
-
-      forecast.each do |row|
-        if row['type'] != 'settings'
-          category_length = row['category'].length
-          settings[:max_category] = category_length if category_length > settings[:max_category]
-
-          amount = if row['amount'].is_a?(Integer) || row['amount'].is_a?(Float)
-                     ((row['amount'] + 3) * 100).to_s
-                   else
-                     row['amount'].to_s
-                   end
-
-          settings[:max_amount] = amount.length if amount.length > settings[:max_amount]
-        end
-
-        if row['type'] == 'settings'
-
-          settings[:currency] = if row['frequency'] == "currency"
-                                  row['account']
-                                else
-                                  "USD"
-                                end
-
-          settings[:show_symbol] = if row['frequency'] == "show_symbol"
-                                     row['account']
-                                   else
-                                     true
-                                   end
+    DEFAULTS = {
+      currency: "USD",
+      show_symbol: true,
+      sign_before_symbol: false,
+      thousands_separator: ","
+    }.freeze
+
+    attr_reader(
+      :currency,
+      :show_symbol,
+      :sign_before_symbol,
+      :thousands_separator,
+      :verbose,
+      :roll_up
+    )
+
+    def self.parse(settings_rows, cli_options = nil)
+      new(settings_rows, cli_options)
+    end
 
-          settings[:sign_before_symbol] = if row['frequency'] == "sign_before_symbol"
-                                            row['account']
-                                          else
-                                            false
-                                          end
+    def verbose? = @verbose
 
-          settings[:thousands_separator] = if row['frequency'] == "thousands_separator"
-                                             row['account']
-                                           else
-                                             ","
-                                           end
-        end
+    private
 
-        settings.merge!(cli_options) if cli_options
-      end
+    def initialize(settings_rows, cli_options)
+      overrides = settings_rows.each_with_object({}) { |row, h| h[row[:frequency]] = row[:account] }
+      opts = cli_options || {}
 
-      settings
+      @currency = opts[:currency] || overrides["currency"] || DEFAULTS[:currency]
+      @show_symbol = opts[:show_symbol] || overrides["show_symbol"] || DEFAULTS[:show_symbol]
+      @sign_before_symbol = opts[:sign_before_symbol] ||
+        overrides["sign_before_symbol"] ||
+        DEFAULTS[:sign_before_symbol]
+      @thousands_separator = opts[:thousands_separator] ||
+        overrides["thousands_separator"] ||
+        DEFAULTS[:thousands_separator]
+      @verbose = opts[:verbose] || false
+      @roll_up = opts[:roll_up]
     end
   end
 end

data/lib/hledger_forecast/summarizer.rb

@@ -1,72 +1,51 @@
 module HledgerForecast
-  # Summarise a forecast yaml file and output it to the CLI
   class Summarizer
-    def self.summarize(config, cli_options)
-      new.summarize(config, cli_options)
+    def self.summarize(csv_string, cli_options = nil)
+      new.summarize(csv_string, cli_options)
     end
 
-    def summarize(config, cli_options = nil)
-      @forecast = CSV.parse(config, headers: true)
-      @settings = Settings.config(@forecast, cli_options)
+    def summarize(csv_string, cli_options = nil)
+      forecast = Forecast.parse(csv_string, cli_options)
+      transactions = forecast.transactions.reject(&:summary_exclude?)
 
-      { output: generate(@forecast), settings: @settings }
-    end
-
-    private
-
-    def generate(forecast)
-      output = []
+      if cli_options&.dig(:tags)
+        raise "The --tags option requires a 'tag' column in the forecast CSV" unless forecast.has_tags_column?
+        transactions = transactions.select { |t| t.matches_tags?(cli_options[:tags]) }
+      end
 
-      forecast.each do |row|
-        next if row['type'] == 'settings'
-        next if row['summary_exclude']
+      output = transactions.map { |t| build_summary_row(t) }
+      output = apply_roll_up(output, forecast.settings.roll_up) if forecast.settings.roll_up
 
-        row['amount'] = Utilities.convert_amount(row['amount'])
+      {output: output, settings: forecast.settings}
+    end
 
-        begin
-          annualised_amount = row['roll-up'] ? row['amount'] * row['roll-up'].to_f : row['amount'] * annualise(row['type'])
-        rescue StandardError
-          puts "\nError: ".bold.red + 'Could not create an annualised ammount. Have you set the roll-up for your custom type transactions?'
-          exit
-        end
+    private
 
-        output << {
-          account: row['account'],
-          from: Date.parse(row['from']),
-          to: row['to'] ? Calculator.new.evaluate_date(Date.parse(row['from']), row['to']) : nil,
-          type: row['type'],
-          frequency: row['frequency'],
-          category: row['category'],
-          description: row['description'],
-          amount: row['amount'],
-          annualised_amount: annualised_amount.to_f,
-          exclude: row['summary_exclude']
-        }
+    def build_summary_row(transaction)
+      annualised = begin
+        transaction.annualised_amount
+      rescue KeyError => e
+        puts("\nError: ".bold.red + e.message)
+        exit
       end
 
-      output = calculate_rolled_up_amount(output) unless @settings[:roll_up].nil?
-
-      output
-    end
-
-    def annualise(period)
-      annualise = {
-        'monthly' => 12,
-        'quarterly' => 4,
-        'half-yearly' => 2,
-        'yearly' => 1,
-        'once' => 1,
-        'daily' => 352,
-        'weekly' => 52
+      {
+        account: transaction.account,
+        from: transaction.from,
+        to: transaction.to,
+        type: transaction.type,
+        frequency: transaction.frequency,
+        category: transaction.category,
+        description: transaction.description,
+        amount: transaction.amount,
+        annualised_amount: annualised.to_f,
+        exclude: transaction.summary_exclude
       }
-
-      annualise[period]
     end
 
-    def calculate_rolled_up_amount(forecast)
-      forecast.each do |row|
-        row[:rolled_up_amount] = row[:annualised_amount] / annualise(@settings[:roll_up])
-      end
+    def apply_roll_up(output, roll_up_period)
+      divisor = ANNUAL_MULTIPLIERS.fetch(roll_up_period)
+      output.each { |row| row[:rolled_up_amount] = row[:annualised_amount] / divisor }
     end
   end
 end

data/lib/hledger_forecast/summarizer_formatter.rb

@@ -1,5 +1,4 @@
 module HledgerForecast
-  # Output the summarised forecast to the CLI
   class SummarizerFormatter
     def self.format(output, settings)
       new.format(output, settings)
@@ -11,7 +10,7 @@ module HledgerForecast
 
       init_table
 
-      if @settings[:roll_up].nil?
+      if @settings.roll_up.nil?
         add_rows_to_table(output)
         add_total_row_to_table(output, :amount)
       else
@@ -25,115 +24,113 @@ module HledgerForecast
     private
 
     def init_table
-      title = 'FORECAST SUMMARY'
-      title += " (#{@settings[:roll_up].upcase} ROLL UP)" if @settings[:roll_up]
+      title = "FORECAST SUMMARY"
+      title += " (#{@settings.roll_up.upcase} ROLL UP)" if @settings.roll_up
 
-      @table.add_row([{ value: title.bold, colspan: 3, alignment: :center }])
+      @table.add_row([{value: title.bold, colspan: 3, alignment: :center}])
       @table.add_separator
     end
 
     def add_rows_to_table(data)
-      data = data.group_by { |item| item[:type] }
+      data.group_by { |item| item[:type] }.tap { |d| sort_items(d) }.each_with_index do |(type, items), index|
+        @table.add_row([{value: type.capitalize.bold, colspan: 3, alignment: :center}])
 
-      data = sort(data)
-
-      data.each_with_index do |(type, items), index|
-        @table.add_row([{ value: type.capitalize.bold, colspan: 3, alignment: :center }])
         total = 0
         items.each do |item|
           total += item[:amount].to_f
 
-          if @settings[:verbose]
-            @table.add_row [{ value: item[:category], alignment: :left },
-                            { value: item[:description], alignment: :left },
-                            { value: format_amount(item[:amount]), alignment: :right }]
+          if @settings.verbose
+            @table.add_row(
+              [
+                {value: item[:category], alignment: :left},
+                {value: item[:description], alignment: :left},
+                {value: format_amount(item[:amount]), alignment: :right}
+              ]
+            )
           else
-            @table.add_row [{ value: item[:category], colspan: 2, alignment: :left },
-                            { value: format_amount(item[:amount]), alignment: :right }]
+            @table.add_row(
+              [
+                {value: item[:category], colspan: 2, alignment: :left},
+                {value: format_amount(item[:amount]), alignment: :right}
+              ]
+            )
           end
         end
 
-        @table.add_row [{ value: "TOTAL".bold, colspan: 2, alignment: :left },
-                        { value: format_amount(total).bold, alignment: :right }]
+        @table.add_row(
+          [
+            {value: "TOTAL".bold, colspan: 2, alignment: :left},
+            {value: format_amount(total).bold, alignment: :right}
+          ]
+        )
 
         @table.add_separator if index != data.size - 1
       end
     end
 
-    def sort(data)
-      data.each do |type, items|
-        data[type] = items.sort_by do |item|
-          value = item[:amount].to_f
-          [value >= 0 ? 1 : 0, value >= 0 ? -value : value]
-        end
-      end
-    end
-
     def add_rolled_up_rows_to_table(data)
-      sum_hash = Hash.new { |h, k| h[k] = { sum: 0, descriptions: [] } }
-
-      data.each do |item|
-        sum_hash[item[:category]][:sum] += item[:rolled_up_amount]
-        sum_hash[item[:category]][:descriptions] << item[:description]
+      aggregated = data.each_with_object(Hash.new { |h, k| h[k] = {sum: 0, descriptions: []} }) do |item, h|
+        h[item[:category]][:sum] += item[:rolled_up_amount]
+        h[item[:category]][:descriptions] << item[:description]
       end
 
-      # Convert arrays of descriptions to single strings
-      sum_hash.each do |_category, values|
-        values[:descriptions] = values[:descriptions].join(", ")
-      end
-
-      # Sort the array
-      sorted_sums = sort_roll_up(sum_hash, :sum)
-
-      if @settings[:verbose]
-        sorted_sums.each do |hash|
-          @table.add_row [{ value: hash[:category], colspan: 1, alignment: :left },
-                          { value: hash[:descriptions], colspan: 1, alignment: :left },
-                          { value: format_amount(hash[:sum]), alignment: :right }]
-        end
-      else
-        sorted_sums.each do |hash|
-          @table.add_row [{ value: hash[:category], colspan: 2, alignment: :left },
-                          { value: format_amount(hash[:sum]), alignment: :right }]
+      aggregated.each_value { |v| v[:descriptions] = v[:descriptions].join(", ") }
+
+      sort_by_amount(aggregated.map { |cat, v| {category: cat, sum: v[:sum], descriptions: v[:descriptions]} })
+        .each do |hash|
+          if @settings.verbose
+            @table.add_row(
+              [
+                {value: hash[:category], colspan: 1, alignment: :left},
+                {value: hash[:descriptions], colspan: 1, alignment: :left},
+                {value: format_amount(hash[:sum]), alignment: :right}
+              ]
+            )
+          else
+            @table.add_row(
+              [
+                {value: hash[:category], colspan: 2, alignment: :left},
+                {value: format_amount(hash[:sum]), alignment: :right}
+              ]
+            )
+          end
         end
-      end
     end
 
-    def sort_roll_up(data, sort_by)
-      # Convert the hash to an array of hashes
-      array = data.map do |category, values|
-        { category: category, sum: values[sort_by], descriptions: values[:descriptions] }
-      end
+    def add_total_row_to_table(data, row_to_sum)
+      total = data.sum { |item| item[row_to_sum].to_f }
+      income = data.sum { |item| (v = item[row_to_sum].to_f) < 0 ? v : 0 }
+      savings = (total / income * 100).round(2)
 
-      # Sort the array
-      array.sort_by do |hash|
-        value = hash[:sum]
-        [value >= 0 ? 1 : 0, value >= 0 ? -value : value]
-      end
+      @table.add_separator
+      @table.add_row(
+        [
+          {value: "TOTAL".bold, colspan: 2, alignment: :left},
+          {value: format_amount(total).bold, alignment: :right}
+        ]
+      )
+      @table.add_row(
+        [
+          {value: "as a % of income".italic, colspan: 2, alignment: :left},
+          {value: "#{savings}%".italic, alignment: :right}
+        ]
+      )
     end
 
-    def add_total_row_to_table(data, row_to_sum)
-      total = data.reduce(0) do |sum, item|
-        sum + item[row_to_sum].to_f
-      end
+    def sort_items(grouped)
+      grouped.transform_values! { |items| sort_by_amount(items, key: :amount) }
+    end
 
-      income = data.reduce(0) do |sum, item|
-        sum += item[row_to_sum].to_f if item[row_to_sum].to_f < 0
-        sum
+    def sort_by_amount(collection, key: :sum)
+      collection.sort_by do |item|
+        value = item[key].to_f
+        [value >= 0 ? 1 : 0, value >= 0 ? -value : value]
       end
-
-      savings = (total / income * 100).to_f.round(2)
-
-      @table.add_separator
-      @table.add_row [{ value: "TOTAL".bold, colspan: 2, alignment: :left },
-                      { value: format_amount(total).bold, alignment: :right }]
-      @table.add_row [{ value: "as a % of income".italic, colspan: 2, alignment: :left },
-                      { value: "#{savings}%".italic, alignment: :right }]
     end
 
     def format_amount(amount)
-      formatted_amount = Formatter.format_money(amount, @settings)
-      amount.to_f < 0 ? formatted_amount.green : formatted_amount.red
+      formatted = Formatter.format_money(amount, @settings)
+      amount.to_f.negative? ? formatted.green : formatted.red
     end
   end
 end

data/lib/hledger_forecast/transaction.rb

@@ -0,0 +1,63 @@
+module HledgerForecast
+  ANNUAL_MULTIPLIERS = {
+    "monthly" => 12,
+    "quarterly" => 4,
+    "half-yearly" => 2,
+    "yearly" => 1,
+    "once" => 1,
+    "daily" => 352,
+    "weekly" => 52
+  }.freeze
+
+  Transaction = Struct.new(
+    :type,
+    :frequency,
+    :account,
+    :from,
+    :to,
+    :description,
+    :category,
+    :amount,
+    :roll_up,
+    :summary_exclude,
+    :tags,
+    keyword_init: true
+  ) do
+    def self.from_row(row)
+      from = Date.parse(row[:from].to_s)
+      new(
+        type: row[:type],
+        frequency: row[:frequency],
+        account: row[:account],
+        from: from,
+        to: row[:to] ? Calculator.evaluate_date(from, row[:to].to_s) : nil,
+        description: row[:description],
+        category: row[:category],
+        amount: Calculator.evaluate(row[:amount]),
+        roll_up: row[:roll_up],
+        summary_exclude: row[:summary_exclude],
+        tags: row[:tag].to_s.split("|").map(&:strip).reject(&:empty?)
+      )
+    end
+
+    def matches_tags?(filter_tags)
+      return true if filter_tags.nil? || filter_tags.empty?
+      (tags & filter_tags).any?
+    end
+
+    def annualised_amount
+      if roll_up
+        amount * roll_up
+      else
+        amount *
+          ANNUAL_MULTIPLIERS.fetch(type) {
+            raise(KeyError, "Unknown type '#{type}'. Set a roll-up for custom transactions.")
+          }
+      end
+    end
+
+    def summary_exclude? = !!summary_exclude
+  end
+
+  TransactionGroup = Struct.new(:type, :frequency, :account, :from, :to, :transactions, keyword_init: true)
+end

data/lib/hledger_forecast/transactions/default.rb

@@ -1,100 +1,73 @@
 module HledgerForecast
   module Transactions
-    # Generate default hledger transactions
+    # Generate hledger periodic transactions from TransactionGroups.
     # Example output:
-    # ~ monthly from 2023-05-1  * Food expenses
+    # ~ monthly from 2023-05-01  * Food expenses
     #    Expenses:Groceries    $250.00 ;  Food expenses
     #    Assets:Checking
     class Default
-      def self.generate(forecast, settings)
-        new(forecast, settings).generate
+      def self.render(groups, settings)
+        new(groups, settings).render
       end
 
-      def generate
-        forecast.each do |row|
-          next if row[:type] == "settings"
-
-          process_transactions(row)
-        end
-
-        output
+      def render
+        groups.map { |group| render_group(group) }.join.gsub(/\n{2,}/, "\n\n")
       end
 
       private
 
-      attr_reader :forecast, :settings, :output
+      attr_reader :groups, :settings
 
-      def initialize(forecast, settings)
-        @forecast = forecast
+      def initialize(groups, settings)
+        @groups = groups
         @settings = settings
-        @output = []
+        precompute_padding
       end
 
-      def process_transactions(row)
-        to = build_to_header(row[:to])
-        frequency = get_periodic_rules(row[:type], row[:frequency])
-
-        if @settings[:verbose]
-          description = row[:description]
-          transactions = [row]
-        else
-          description = get_descriptions(row[:transactions])
-          transactions = row[:transactions]
-        end
-
-        header = build_header(row, frequency, to, description)
-        footer = build_footer(row)
+      def precompute_padding
+        all_transactions = groups.flat_map(&:transactions)
+        formatted_amounts = all_transactions.map { |t| Formatter.format_money(t.amount, settings) }
 
-        output << build_transaction(header, transactions, footer)
+        @max_amount = formatted_amounts.map(&:length).max || 0
+        @max_category = all_transactions.map { |t| t.category.to_s.length }.max || 0
       end
 
-      def build_header(row, frequency, to, descriptions)
-        "#{frequency} #{row[:from]}#{to}  * #{descriptions}\n"
+      def render_group(group)
+        render_header(group) + render_postings(group) + "    #{group.account}\n\n"
       end
 
-      def build_footer(block)
-        "    #{block[:account]}\n\n"
+      def render_header(group)
+        to_part = " to #{group.to}" if group.to
+        descriptions = group.transactions.map(&:description).join(", ")
+        "#{periodic_rule_for(group.type, group.frequency)} #{group.from}#{to_part}  * #{descriptions}\n"
       end
 
-      def build_transaction(header, transactions, footer)
-        { header: header, transactions: write_transactions(transactions), footer: footer }
+      def render_postings(group)
+        group
+          .transactions
+          .map do |t|
+            amount = Formatter.format_money(t.amount, settings)
+            category = t.category.to_s.ljust(@max_category)
+
+            if t.tags.any?
+              tags_str = t.tags.map { |tag| "#{tag}:" }.join(", ")
+              "    #{category}    #{amount.ljust(@max_amount)};  #{tags_str}\n"
+            else
+              "    #{category}    #{amount}\n"
+            end
+          end
+          .join
       end
 
-      def build_to_header(to)
-        return " to #{to}" if to
-      end
-
-      def get_descriptions(transactions)
-        transactions.map do |t|
-          # Skip transactions that have been marked as tracked
-          next if t[:track]
-
-          t[:description]
-        end.compact.join(', ')
-      end
-
-      def get_periodic_rules(type, frequency)
-        map = {
-          'once' => '~',
-          'monthly' => '~ monthly from',
-          'quarterly' => '~ every 3 months from',
-          'half-yearly' => '~ every 6 months from',
-          'yearly' => '~ yearly from',
-          'custom' => "~ #{frequency} from"
-        }
-        map[type]
-      end
-
-      def write_transactions(transactions)
-        transactions.map do |t|
-          # Skip transactions that have been marked as tracked
-          next if t[:track]
-
-          t[:amount] = t[:amount].to_s.ljust(@settings[:max_amount] + 5)
-          t[:category] = t[:category].to_s.ljust(@settings[:max_category])
-
-          "    #{t[:category]}    #{t[:amount]};  #{t[:description]}\n"
-        end.compact
+      def periodic_rule_for(type, frequency)
+        {
+          "once" => "~",
+          "monthly" => "~ monthly from",
+          "quarterly" => "~ every 3 months from",
+          "half-yearly" => "~ every 6 months from",
+          "yearly" => "~ yearly from",
+          "custom" => "~ #{frequency} from"
+        }.fetch(type)
       end
     end
   end

data/lib/hledger_forecast/version.rb

@@ -1,3 +1,3 @@
 module HledgerForecast
-  VERSION = "2.0.0".freeze
+  VERSION = "3.0.0"
 end