banco 1.0.3 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +45 -0
- data/README.md +141 -0
- data/bin/banco +95 -44
- data/lib/banco/bank_format.rb +67 -0
- data/lib/banco/cli.rb +92 -0
- data/lib/banco/file_picker.rb +45 -0
- data/lib/banco/formatter/base.rb +37 -0
- data/lib/banco/formatter/csv_formatter.rb +21 -0
- data/lib/banco/formatter/json_formatter.rb +29 -0
- data/lib/banco/formatter/text.rb +143 -0
- data/lib/banco/grouper.rb +50 -0
- data/lib/banco/parser.rb +39 -0
- data/lib/banco/report.rb +10 -0
- data/lib/banco/transaction.rb +46 -25
- data/lib/banco/version.rb +5 -0
- data/lib/banco.rb +17 -0
- metadata +231 -30
- data/README +0 -12
- data/lib/banco/get_file.rb +0 -43
- data/lib/banco/reader.rb +0 -64
- data/lib/banco/reporter.rb +0 -74
- data/lib/banco/viewable.rb +0 -181
- data/spec/banco/reader_spec.rb +0 -16
- data/spec/banco/reporter_spec.rb +0 -55
- data/spec/banco/transaction_spec.rb +0 -49
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'csv'
|
|
4
|
+
require_relative 'base'
|
|
5
|
+
|
|
6
|
+
module Banco
|
|
7
|
+
module Formatter
|
|
8
|
+
class Text < Base
|
|
9
|
+
def self.format_name = 'text'
|
|
10
|
+
|
|
11
|
+
def call = bottom_line
|
|
12
|
+
|
|
13
|
+
def menu
|
|
14
|
+
output = +''
|
|
15
|
+
output << "Enter :\n\n"
|
|
16
|
+
output << "'a' to view all transactions\n"
|
|
17
|
+
output << "'o' to view all outgoing transactions\n"
|
|
18
|
+
output << "'i' to view all incoming transactions\n"
|
|
19
|
+
output << "'m' for money out summary\n"
|
|
20
|
+
output << "'n' for money in summary\n"
|
|
21
|
+
output << "'b' for the bottom line\n"
|
|
22
|
+
output << "'s' to save summary as csv\n"
|
|
23
|
+
output << "'t' to save transactions as csv\n"
|
|
24
|
+
output << "\n'l' to load a new file\n"
|
|
25
|
+
output << "'+' to merge another file into the current set\n"
|
|
26
|
+
output << "\nor 'q' to quit\n\n\n"
|
|
27
|
+
output
|
|
28
|
+
end
|
|
29
|
+
|
|
30
|
+
def transactions_all
|
|
31
|
+
output = +''
|
|
32
|
+
output << dashes << "\n"
|
|
33
|
+
output << "All transactions:\n"
|
|
34
|
+
output << "#{facts(@report.all_transactions)}\n\n"
|
|
35
|
+
@report.all_transactions.each do |trans|
|
|
36
|
+
output << if trans.debit_pence.zero?
|
|
37
|
+
"#{trans} + #{format_pence(trans.credit_pence)}\n"
|
|
38
|
+
else
|
|
39
|
+
"#{trans} - #{format_pence(trans.debit_pence)}\n"
|
|
40
|
+
end
|
|
41
|
+
end
|
|
42
|
+
output << dashes << "\n\n"
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
def transactions_out
|
|
46
|
+
output = +''
|
|
47
|
+
output << dashes << "\n"
|
|
48
|
+
output << "Outgoing Transactions:\n"
|
|
49
|
+
output << "#{facts(@report.outgoing_trans)}\n\n"
|
|
50
|
+
@report.outgoing_trans.each { |t| output << "#{t} - #{format_pence(t.debit_pence)}\n" }
|
|
51
|
+
output << dashes << "\n\n"
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
def transactions_in
|
|
55
|
+
output = +''
|
|
56
|
+
output << dashes << "\n"
|
|
57
|
+
output << "Incoming Transactions :\n"
|
|
58
|
+
output << "#{facts(@report.incoming_trans)}\n\n"
|
|
59
|
+
@report.incoming_trans.each { |t| output << "#{t} + #{format_pence(t.credit_pence)}\n" }
|
|
60
|
+
output << dashes << "\n\n"
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
def money_out_summary
|
|
64
|
+
print_summary('Outgoings', @report.outgoings, @report.outgoing_total)
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
def money_in_summary
|
|
68
|
+
print_summary('Incomings', @report.incomings, @report.incoming_total)
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
def bottom_line
|
|
72
|
+
output = +''
|
|
73
|
+
output << dashes << "\n"
|
|
74
|
+
output << facts(@report.all_transactions).to_s.rjust(54) << "\n\n"
|
|
75
|
+
output << "Money In : #{format_pence(@report.incoming_total)}".rjust(54) << "\n"
|
|
76
|
+
output << "Money Out : #{format_pence(@report.outgoing_total)}".rjust(54) << "\n\n"
|
|
77
|
+
diff = @report.incoming_total - @report.outgoing_total
|
|
78
|
+
output << if @report.outgoing_total > @report.incoming_total
|
|
79
|
+
"Outgoings exceed Incomings, DEFICIT of #{format_pence(diff.abs)}".rjust(54)
|
|
80
|
+
else
|
|
81
|
+
"Incomings exceed Outgoings, SURPLUS of #{format_pence(diff)}".rjust(54)
|
|
82
|
+
end
|
|
83
|
+
output << "\n" << dashes << "\n\n"
|
|
84
|
+
end
|
|
85
|
+
|
|
86
|
+
def save_summary_to_file(path)
|
|
87
|
+
CSV.open(path, 'w') do |csv|
|
|
88
|
+
csv << %w[Direction Category Total]
|
|
89
|
+
@report.outgoings.sort_by { |_, v| -v }.each do |k, v|
|
|
90
|
+
csv << ['Outgoing', k.strip, format('%.2f', v / 100.0)]
|
|
91
|
+
end
|
|
92
|
+
@report.incomings.sort_by { |_, v| -v }.each do |k, v|
|
|
93
|
+
csv << ['Incoming', k.strip, format('%.2f', v / 100.0)]
|
|
94
|
+
end
|
|
95
|
+
end
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
def save_transactions_to_file(path)
|
|
99
|
+
CSV.open(path, 'w') do |csv|
|
|
100
|
+
csv << %w[Date Description Amount]
|
|
101
|
+
@report.all_transactions.each do |t|
|
|
102
|
+
amount = t.credit_pence.positive? ? t.credit_pence / 100.0 : -(t.debit_pence / 100.0)
|
|
103
|
+
csv << [t.date, t.description.strip, format('%.2f', amount)]
|
|
104
|
+
end
|
|
105
|
+
end
|
|
106
|
+
end
|
|
107
|
+
|
|
108
|
+
def dashes
|
|
109
|
+
'---'.center(55, '-')
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
def date_range
|
|
113
|
+
first = @report.all_transactions.first
|
|
114
|
+
last_t = @report.all_transactions.last
|
|
115
|
+
days = (first.parsed_date - last_t.parsed_date).to_i.abs + 1 if first&.parsed_date && last_t&.parsed_date
|
|
116
|
+
day_label = days == 1 ? 'day' : 'days'
|
|
117
|
+
day_str = days ? " — #{days} #{day_label}" : ''
|
|
118
|
+
"(#{last_t&.date} - #{first&.date})#{day_str}"
|
|
119
|
+
end
|
|
120
|
+
|
|
121
|
+
def facts(transactions)
|
|
122
|
+
"#{transactions.size} transactions for period #{date_range}"
|
|
123
|
+
end
|
|
124
|
+
|
|
125
|
+
private
|
|
126
|
+
|
|
127
|
+
def format_pence(pence)
|
|
128
|
+
"£#{format('%10.2f', pence / 100.0)}"
|
|
129
|
+
end
|
|
130
|
+
|
|
131
|
+
def print_summary(kind, hash, total)
|
|
132
|
+
output = +''
|
|
133
|
+
output << dashes << "\n"
|
|
134
|
+
output << "#{kind} Summary, totals from #{hash.size} different sources :\n"
|
|
135
|
+
output << "#{date_range}\n"
|
|
136
|
+
hash.sort_by { |_k, v| v }.reverse_each { |k, v| output << "#{k} #{format_pence(v)}\n".rjust(54) }
|
|
137
|
+
output << "\n"
|
|
138
|
+
output << "Total #{kind}: #{format_pence(total)}\n".rjust(54)
|
|
139
|
+
output << dashes << "\n\n"
|
|
140
|
+
end
|
|
141
|
+
end
|
|
142
|
+
end
|
|
143
|
+
end
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'banco/report'
|
|
4
|
+
|
|
5
|
+
module Banco
|
|
6
|
+
class Grouper
|
|
7
|
+
DEFAULT_PREFIX_LENGTH = 9
|
|
8
|
+
|
|
9
|
+
def initialize(transactions, prefix_length: DEFAULT_PREFIX_LENGTH, from: nil, to: nil)
|
|
10
|
+
@transactions = transactions
|
|
11
|
+
@prefix_length = prefix_length
|
|
12
|
+
@from = from
|
|
13
|
+
@to = to
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
def call
|
|
17
|
+
clean = @transactions.reject { |t| t.credit_pence.zero? && t.debit_pence.zero? }
|
|
18
|
+
clean = filter_by_date(clean)
|
|
19
|
+
out, inc = clean.partition { |t| t.credit_pence.zero? && t.debit_pence.positive? }
|
|
20
|
+
Report.new(
|
|
21
|
+
all_transactions: clean,
|
|
22
|
+
outgoing_trans: out,
|
|
23
|
+
incoming_trans: inc,
|
|
24
|
+
outgoings: group(out, :debit_pence),
|
|
25
|
+
incomings: group(inc, :credit_pence)
|
|
26
|
+
)
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
private
|
|
30
|
+
|
|
31
|
+
def filter_by_date(transactions)
|
|
32
|
+
return transactions if @from.nil? && @to.nil?
|
|
33
|
+
|
|
34
|
+
transactions.select { |t| in_range?(t) }
|
|
35
|
+
end
|
|
36
|
+
|
|
37
|
+
def in_range?(transaction)
|
|
38
|
+
return false if transaction.parsed_date.nil?
|
|
39
|
+
|
|
40
|
+
(@from.nil? || transaction.parsed_date >= @from) &&
|
|
41
|
+
(@to.nil? || transaction.parsed_date <= @to)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
def group(transactions, attr)
|
|
45
|
+
transactions.each_with_object(Hash.new(0)) do |t, h|
|
|
46
|
+
h[t.description[0, @prefix_length]] += t.public_send(attr)
|
|
47
|
+
end
|
|
48
|
+
end
|
|
49
|
+
end
|
|
50
|
+
end
|
data/lib/banco/parser.rb
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'csv'
|
|
4
|
+
require 'banco/transaction'
|
|
5
|
+
|
|
6
|
+
module Banco
|
|
7
|
+
class Parser
|
|
8
|
+
def initialize(file_path, skip_header: false, bank_format: BankFormat[:legacy])
|
|
9
|
+
@file_path = file_path
|
|
10
|
+
@skip_header = skip_header
|
|
11
|
+
@bank_format = bank_format
|
|
12
|
+
end
|
|
13
|
+
|
|
14
|
+
def parse
|
|
15
|
+
rows = []
|
|
16
|
+
CSV.foreach(@file_path).with_index do |row, i|
|
|
17
|
+
next if @skip_header && i.zero?
|
|
18
|
+
|
|
19
|
+
parsed = parse_row(row, i)
|
|
20
|
+
rows << parsed if parsed
|
|
21
|
+
end
|
|
22
|
+
rows
|
|
23
|
+
rescue Errno::ENOENT
|
|
24
|
+
raise ArgumentError, "File not found: #{@file_path}"
|
|
25
|
+
end
|
|
26
|
+
|
|
27
|
+
private
|
|
28
|
+
|
|
29
|
+
def parse_row(row, index)
|
|
30
|
+
Transaction.from_row(row, @bank_format)
|
|
31
|
+
rescue ArgumentError => e
|
|
32
|
+
if index.zero? && e.message.include?('Non-numeric')
|
|
33
|
+
warn 'Skipping header row (use --header to suppress this warning)'
|
|
34
|
+
return nil
|
|
35
|
+
end
|
|
36
|
+
raise ArgumentError, "Row #{index + 1}: #{e.message}"
|
|
37
|
+
end
|
|
38
|
+
end
|
|
39
|
+
end
|
data/lib/banco/report.rb
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Banco
|
|
4
|
+
Report = Data.define(:all_transactions, :outgoing_trans, :incoming_trans, :outgoings, :incomings) do
|
|
5
|
+
def outgoing_total = outgoings.values.sum
|
|
6
|
+
def incoming_total = incomings.values.sum
|
|
7
|
+
def surplus_pence = incoming_total - outgoing_total
|
|
8
|
+
def date_range = [all_transactions.first&.date, all_transactions.last&.date]
|
|
9
|
+
end
|
|
10
|
+
end
|
data/lib/banco/transaction.rb
CHANGED
|
@@ -1,32 +1,53 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'date'
|
|
4
|
+
require 'banco/bank_format'
|
|
1
5
|
|
|
2
6
|
module Banco
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
7
|
+
Transaction = Data.define(:date, :description, :type, :credit_pence, :debit_pence, :parsed_date) do
|
|
8
|
+
class << self
|
|
9
|
+
def from_row(row, fmt = BankFormat[:legacy])
|
|
10
|
+
date_str = row[fmt.date_col]
|
|
11
|
+
credit, debit = money_columns(row, fmt)
|
|
12
|
+
new(
|
|
13
|
+
date: date_str,
|
|
14
|
+
description: row[fmt.description_col].to_s.upcase.ljust(22)[0, 22],
|
|
15
|
+
type: (fmt.type_col && row[fmt.type_col]).to_s.upcase.ljust(8)[0, 8],
|
|
16
|
+
credit_pence: credit,
|
|
17
|
+
debit_pence: debit,
|
|
18
|
+
parsed_date: parse_date(date_str, fmt.date_fmt)
|
|
19
|
+
)
|
|
20
|
+
end
|
|
15
21
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
22
|
+
private
|
|
23
|
+
|
|
24
|
+
# When credit and debit share a column the value is a signed amount:
|
|
25
|
+
# positive is incoming (credit), negative is outgoing (debit).
|
|
26
|
+
def money_columns(row, fmt)
|
|
27
|
+
return [parse_pence(row[fmt.credit_col]), parse_pence(row[fmt.debit_col])] if fmt.credit_col != fmt.debit_col
|
|
28
|
+
|
|
29
|
+
amount = parse_pence(row[fmt.credit_col])
|
|
30
|
+
amount.negative? ? [0, amount.abs] : [amount, 0]
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
def parse_pence(str)
|
|
34
|
+
return 0 if str.nil? || str.strip.empty?
|
|
19
35
|
|
|
20
|
-
|
|
21
|
-
|
|
36
|
+
Float(str) # validates; exact conversion uses Rational below
|
|
37
|
+
(str.to_r * 100).to_i
|
|
38
|
+
rescue ArgumentError
|
|
39
|
+
raise ArgumentError, "Non-numeric money value: #{str.inspect}"
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
def parse_date(str, fmt_str)
|
|
43
|
+
return nil if str.nil? || str.strip.empty? || fmt_str.nil?
|
|
44
|
+
|
|
45
|
+
Date.strptime(str, fmt_str)
|
|
46
|
+
rescue Date::Error
|
|
47
|
+
nil
|
|
48
|
+
end
|
|
22
49
|
end
|
|
23
|
-
end
|
|
24
|
-
end
|
|
25
50
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
p trans
|
|
29
|
-
t = Banco::Transaction.new
|
|
30
|
-
t.send(:initialize, '02/02/18', 'new way', 'credit', '0', '111.11', '2')
|
|
31
|
-
p t
|
|
51
|
+
def to_s = "#{date} #{type} #{description}"
|
|
52
|
+
end
|
|
32
53
|
end
|
data/lib/banco.rb
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require 'banco/version'
|
|
4
|
+
require 'banco/bank_format'
|
|
5
|
+
require 'banco/transaction'
|
|
6
|
+
require 'banco/report'
|
|
7
|
+
require 'banco/grouper'
|
|
8
|
+
require 'banco/parser'
|
|
9
|
+
require 'banco/formatter/base'
|
|
10
|
+
require 'banco/formatter/text'
|
|
11
|
+
require 'banco/formatter/json_formatter'
|
|
12
|
+
require 'banco/formatter/csv_formatter'
|
|
13
|
+
require 'banco/cli'
|
|
14
|
+
require 'banco/file_picker'
|
|
15
|
+
|
|
16
|
+
user_formats = File.expand_path('~/.banco/formats.rb')
|
|
17
|
+
load user_formats if File.exist?(user_formats)
|
metadata
CHANGED
|
@@ -1,63 +1,268 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: banco
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version:
|
|
4
|
+
version: 2.0.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- s33d
|
|
8
|
-
autorequire:
|
|
9
8
|
bindir: bin
|
|
10
9
|
cert_chain: []
|
|
11
|
-
date:
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
12
11
|
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: csv
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - ">="
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: '0'
|
|
19
|
+
type: :runtime
|
|
20
|
+
prerelease: false
|
|
21
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
22
|
+
requirements:
|
|
23
|
+
- - ">="
|
|
24
|
+
- !ruby/object:Gem::Version
|
|
25
|
+
version: '0'
|
|
26
|
+
- !ruby/object:Gem::Dependency
|
|
27
|
+
name: rake
|
|
28
|
+
requirement: !ruby/object:Gem::Requirement
|
|
29
|
+
requirements:
|
|
30
|
+
- - ">="
|
|
31
|
+
- !ruby/object:Gem::Version
|
|
32
|
+
version: '0'
|
|
33
|
+
type: :development
|
|
34
|
+
prerelease: false
|
|
35
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
36
|
+
requirements:
|
|
37
|
+
- - ">="
|
|
38
|
+
- !ruby/object:Gem::Version
|
|
39
|
+
version: '0'
|
|
13
40
|
- !ruby/object:Gem::Dependency
|
|
14
41
|
name: rspec
|
|
15
42
|
requirement: !ruby/object:Gem::Requirement
|
|
16
43
|
requirements:
|
|
17
44
|
- - "~>"
|
|
18
45
|
- !ruby/object:Gem::Version
|
|
19
|
-
version: '
|
|
46
|
+
version: '3.13'
|
|
20
47
|
type: :development
|
|
21
48
|
prerelease: false
|
|
22
49
|
version_requirements: !ruby/object:Gem::Requirement
|
|
23
50
|
requirements:
|
|
24
51
|
- - "~>"
|
|
25
52
|
- !ruby/object:Gem::Version
|
|
26
|
-
version: '
|
|
53
|
+
version: '3.13'
|
|
54
|
+
- !ruby/object:Gem::Dependency
|
|
55
|
+
name: rubocop
|
|
56
|
+
requirement: !ruby/object:Gem::Requirement
|
|
57
|
+
requirements:
|
|
58
|
+
- - ">="
|
|
59
|
+
- !ruby/object:Gem::Version
|
|
60
|
+
version: '0'
|
|
61
|
+
type: :development
|
|
62
|
+
prerelease: false
|
|
63
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
64
|
+
requirements:
|
|
65
|
+
- - ">="
|
|
66
|
+
- !ruby/object:Gem::Version
|
|
67
|
+
version: '0'
|
|
68
|
+
- !ruby/object:Gem::Dependency
|
|
69
|
+
name: rubocop-performance
|
|
70
|
+
requirement: !ruby/object:Gem::Requirement
|
|
71
|
+
requirements:
|
|
72
|
+
- - ">="
|
|
73
|
+
- !ruby/object:Gem::Version
|
|
74
|
+
version: '0'
|
|
75
|
+
type: :development
|
|
76
|
+
prerelease: false
|
|
77
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
78
|
+
requirements:
|
|
79
|
+
- - ">="
|
|
80
|
+
- !ruby/object:Gem::Version
|
|
81
|
+
version: '0'
|
|
82
|
+
- !ruby/object:Gem::Dependency
|
|
83
|
+
name: rubocop-rspec
|
|
84
|
+
requirement: !ruby/object:Gem::Requirement
|
|
85
|
+
requirements:
|
|
86
|
+
- - ">="
|
|
87
|
+
- !ruby/object:Gem::Version
|
|
88
|
+
version: '0'
|
|
89
|
+
type: :development
|
|
90
|
+
prerelease: false
|
|
91
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
92
|
+
requirements:
|
|
93
|
+
- - ">="
|
|
94
|
+
- !ruby/object:Gem::Version
|
|
95
|
+
version: '0'
|
|
27
96
|
description: |
|
|
28
|
-
|
|
97
|
+
# Banco
|
|
98
|
+
|
|
99
|
+
Summarise bank statement CSV files from the command line.
|
|
100
|
+
|
|
101
|
+
## Installation
|
|
102
|
+
|
|
103
|
+
```sh
|
|
104
|
+
gem install banco
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Requires Ruby >= 3.3.
|
|
108
|
+
|
|
109
|
+
## Usage
|
|
110
|
+
|
|
111
|
+
Navigate to the directory containing your CSV file and run:
|
|
112
|
+
|
|
113
|
+
```sh
|
|
114
|
+
banco
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Banco scans for CSV files, lets you pick one (or pass `--file`), then
|
|
118
|
+
presents an interactive menu:
|
|
119
|
+
|
|
120
|
+
| Key | Action |
|
|
121
|
+
|-----|--------|
|
|
122
|
+
| `a` | All transactions |
|
|
123
|
+
| `o` | Outgoing transactions |
|
|
124
|
+
| `i` | Incoming transactions |
|
|
125
|
+
| `m` | Money-out summary (grouped) |
|
|
126
|
+
| `n` | Money-in summary (grouped) |
|
|
127
|
+
| `b` | Bottom line (net position) |
|
|
128
|
+
| `s` | Save summary as CSV (prompts for path, default is `<filename>_summary.csv`) |
|
|
129
|
+
| `t` | Save transactions as CSV (prompts for path, default is `<filename>_transactions.csv`) |
|
|
130
|
+
| `l` | Load a new file |
|
|
131
|
+
| `+` | Merge another file into the current dataset |
|
|
132
|
+
| `q` | Quit |
|
|
133
|
+
|
|
134
|
+
Use `--format json` or `--format csv` for pipe-friendly output (no menu, exits after printing).
|
|
135
|
+
|
|
136
|
+
## CLI flags
|
|
137
|
+
|
|
138
|
+
| Flag | Default | Description |
|
|
139
|
+
|------|---------|-------------|
|
|
140
|
+
| `-f`, `--file FILE` | — | CSV file to analyse |
|
|
141
|
+
| `-F`, `--format FORMAT` | `text` | Output format: `text` / `json` / `csv` |
|
|
142
|
+
| `-b`, `--bank NAME` | `legacy` | Bank CSV format (see Bank formats below) |
|
|
143
|
+
| `-p`, `--prefix-length N` | `9` | Description prefix length for grouping |
|
|
144
|
+
| `-H`, `--header` | off | Skip first row as header (auto-detected when the first row is non-numeric) |
|
|
145
|
+
| `--from DATE` | — | Filter from date (format matches bank format) |
|
|
146
|
+
| `--to DATE` | — | Filter to date (format matches bank format) |
|
|
147
|
+
| `-v`, `--version` | — | Print version and exit |
|
|
148
|
+
| `-h`, `--help` | — | Show help and exit |
|
|
149
|
+
|
|
150
|
+
### Examples
|
|
151
|
+
|
|
152
|
+
```sh
|
|
153
|
+
# Summarise all transactions in statements.csv
|
|
154
|
+
banco --file statements.csv
|
|
155
|
+
|
|
156
|
+
# September only, JSON output
|
|
157
|
+
banco --file statements.csv --from 01/09/17 --to 30/09/17 --format json
|
|
158
|
+
|
|
159
|
+
# Skip header row, group by first 6 characters
|
|
160
|
+
banco --file export.csv --header --prefix-length 6
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Bank formats
|
|
164
|
+
|
|
165
|
+
| Name | Date format | Columns | Notes |
|
|
166
|
+
|------|-------------|---------|-------|
|
|
167
|
+
| `legacy` | `%d/%m/%y` | date, description, type, credit, debit | Default — Barclays-style, separate money-in / money-out columns |
|
|
168
|
+
| `split_columns` | `%d/%m/%Y` | date, description, type, credit, debit | Like `legacy` with a 4-digit year |
|
|
169
|
+
| `signed_amount` | `%Y-%m-%d` | date, description, amount | Single signed amount column, no type column |
|
|
170
|
+
| `date_description_amount` | `%d/%m/%Y` | date, description, amount, trailing | Signed amount at second-to-last position; trailing column (balance, reference, etc.) ignored. Tolerates unquoted commas in descriptions. |
|
|
171
|
+
|
|
172
|
+
### Column ordering
|
|
173
|
+
|
|
174
|
+
`date_description_amount` uses `Date | Description | Amount | trailing column`:
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
Date Description Amount Balance/Reference
|
|
178
|
+
07/10/2026 SAINSBURYS S/MKTS LEWES ROAD -22.05 72.73
|
|
179
|
+
07/10/2026 MARLEY EI Loan/rent 450.00 1093.70
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
The trailing column (Balance or Reference) is always ignored. The Amount column is read
|
|
183
|
+
from the **second-to-last** position, so unquoted commas inside a description (which
|
|
184
|
+
can appear in credit card exports) do not shift the Amount value.
|
|
185
|
+
|
|
186
|
+
`legacy` and `split_columns` use `Date | Description | Type | Credit | Debit`:
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
Date Description Type Credit Debit
|
|
190
|
+
21/09/17 Incoming Transaction credit 12.34
|
|
191
|
+
21/09/17 Outgoing Transaction Purchase 12.34
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### Signed amount columns
|
|
195
|
+
|
|
196
|
+
When a format maps `credit_column` and `debit_column` to the **same** column
|
|
197
|
+
(as `signed_amount` and `date_description_amount` do), that column is read as a
|
|
198
|
+
single **signed** amount: positive values are money in (credit) and negative values
|
|
199
|
+
are money out (debit). Formats with separate columns (`legacy`, `split_columns`)
|
|
200
|
+
read each column directly.
|
|
201
|
+
|
|
202
|
+
### Custom formats
|
|
203
|
+
|
|
204
|
+
Define your own format in `~/.banco/formats.rb`:
|
|
205
|
+
|
|
206
|
+
```ruby
|
|
207
|
+
Banco::BankFormat.define(:my_bank) do
|
|
208
|
+
date_column 0
|
|
209
|
+
description_column 2
|
|
210
|
+
type_column 1
|
|
211
|
+
credit_column 3
|
|
212
|
+
debit_column 4
|
|
213
|
+
date_format '%Y-%m-%d'
|
|
214
|
+
end
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Then use it with `banco --bank my_bank`.
|
|
218
|
+
|
|
219
|
+
## CSV format (legacy)
|
|
220
|
+
|
|
221
|
+
Banco's default (`--bank legacy`) expects columns in this order:
|
|
222
|
+
|
|
223
|
+
| # | Content |
|
|
224
|
+
|---|---------|
|
|
225
|
+
| 1 | Date (`dd/mm/yy`) |
|
|
226
|
+
| 2 | Description |
|
|
227
|
+
| 3 | Type |
|
|
228
|
+
| 4 | Money in |
|
|
229
|
+
| 5 | Money out |
|
|
29
230
|
|
|
30
|
-
|
|
31
|
-
Install as a Rubygem, navigate to the directory your .csv files are in and execute from the command line with 'banco'.
|
|
231
|
+
Header rows are auto-detected and skipped. Pass `--header` explicitly to suppress the warning. Any columns beyond the fifth are ignored.
|
|
32
232
|
|
|
33
|
-
|
|
233
|
+
## Licence
|
|
34
234
|
|
|
35
|
-
|
|
235
|
+
MIT — see [LICENSE](LICENSE).
|
|
36
236
|
|
|
37
|
-
Hope your numbers are positive
|
|
38
|
-
https://github.com/s33dco/banco
|
|
39
|
-
https://rubygems.org/gems/banco
|
|
237
|
+
Hope your numbers are positive!
|
|
40
238
|
email: code@s33d.co
|
|
41
239
|
executables:
|
|
42
240
|
- banco
|
|
43
241
|
extensions: []
|
|
44
242
|
extra_rdoc_files: []
|
|
45
243
|
files:
|
|
244
|
+
- CHANGELOG.md
|
|
46
245
|
- LICENSE
|
|
47
|
-
- README
|
|
246
|
+
- README.md
|
|
48
247
|
- bin/banco
|
|
49
|
-
- lib/banco
|
|
50
|
-
- lib/banco/
|
|
51
|
-
- lib/banco/
|
|
248
|
+
- lib/banco.rb
|
|
249
|
+
- lib/banco/bank_format.rb
|
|
250
|
+
- lib/banco/cli.rb
|
|
251
|
+
- lib/banco/file_picker.rb
|
|
252
|
+
- lib/banco/formatter/base.rb
|
|
253
|
+
- lib/banco/formatter/csv_formatter.rb
|
|
254
|
+
- lib/banco/formatter/json_formatter.rb
|
|
255
|
+
- lib/banco/formatter/text.rb
|
|
256
|
+
- lib/banco/grouper.rb
|
|
257
|
+
- lib/banco/parser.rb
|
|
258
|
+
- lib/banco/report.rb
|
|
52
259
|
- lib/banco/transaction.rb
|
|
53
|
-
- lib/banco/
|
|
54
|
-
- spec/banco/reader_spec.rb
|
|
55
|
-
- spec/banco/reporter_spec.rb
|
|
56
|
-
- spec/banco/transaction_spec.rb
|
|
260
|
+
- lib/banco/version.rb
|
|
57
261
|
homepage: https://github.com/s33dco/banco
|
|
58
262
|
licenses:
|
|
59
263
|
- MIT
|
|
60
|
-
metadata:
|
|
264
|
+
metadata:
|
|
265
|
+
rubygems_mfa_required: 'true'
|
|
61
266
|
post_install_message: Thanks for installing, hope your numbers are positive!
|
|
62
267
|
rdoc_options: []
|
|
63
268
|
require_paths:
|
|
@@ -66,18 +271,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
|
66
271
|
requirements:
|
|
67
272
|
- - ">="
|
|
68
273
|
- !ruby/object:Gem::Version
|
|
69
|
-
version: '
|
|
274
|
+
version: '3.3'
|
|
70
275
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
71
276
|
requirements:
|
|
72
277
|
- - ">="
|
|
73
278
|
- !ruby/object:Gem::Version
|
|
74
279
|
version: '0'
|
|
75
280
|
requirements: []
|
|
76
|
-
rubygems_version:
|
|
77
|
-
signing_key:
|
|
281
|
+
rubygems_version: 4.0.18
|
|
78
282
|
specification_version: 4
|
|
79
|
-
summary:
|
|
80
|
-
test_files:
|
|
81
|
-
- spec/banco/reader_spec.rb
|
|
82
|
-
- spec/banco/transaction_spec.rb
|
|
83
|
-
- spec/banco/reporter_spec.rb
|
|
283
|
+
summary: Summarise bank statement CSV files from the command line
|
|
284
|
+
test_files: []
|
data/README
DELETED
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
Welcome to Banco !
|
|
2
|
-
|
|
3
|
-
Banco has been developed to summarize statements downloaded from your bank.
|
|
4
|
-
Install as a Rubygem, navigate to the directory your .csv files are in and execute from the command line with 'banco'.
|
|
5
|
-
|
|
6
|
-
Banco will only accept comma seperated value files (.csv) and will produce a summary for the period uploaded from the file.
|
|
7
|
-
|
|
8
|
-
Remove the header line from your downloaded bank statement, ensure the columns are ordered date, description, type of charge, money in an money out from left to right, any columns right of the fifth will be ignored. Banco will total the incoming & outgoing transactions for the period. Reporting the bottom line aswell as summing up the values for similar transactions. This is achieved by matching the description name, currently set at the first 9 characters of the string, (:total_outgoing :total_incoming - class Reporter), you can change this to be more or less exact.
|
|
9
|
-
|
|
10
|
-
Hope your numbers are positive !
|
|
11
|
-
https://github.com/s33dco/banco
|
|
12
|
-
https://rubygems.org/gems/banco
|