Version 0.002
[chaz/homebank2ledger] / lib / App / HomeBank2Ledger / Ledger.pm
1 package App::HomeBank2Ledger::Ledger;
2 # ABSTRACT: Ledger data representation
3
4
5 use warnings;
6 use strict;
7
8 our $VERSION = '0.002'; # VERSION
9
10
11 sub new {
12 my $class = shift;
13 my %args = @_;
14 return bless {%args}, $class;
15 }
16
17
18 sub accounts { shift->{accounts} || [] }
19 sub commodities { shift->{commodities} || [] }
20 sub payees { shift->{payees} || [] }
21 sub tags { shift->{tags} || [] }
22 sub transactions { shift->{transactions} || [] }
23
24
25 # TODO - These should validate incoming data.
26
27 sub add_accounts {
28 my $self = shift;
29 push @{$self->{accounts}}, @_;
30 }
31
32 sub add_commodities {
33 my $self = shift;
34 push @{$self->{commodities}}, @_;
35 }
36
37 sub add_payees {
38 my $self = shift;
39 push @{$self->{payees}}, @_;
40 }
41
42 sub add_tags {
43 my $self = shift;
44 push @{$self->{tags}}, @_;
45 }
46
47 sub add_transactions {
48 my $self = shift;
49 push @{$self->{transactions}}, @_;
50 }
51
52 1;
53
54 __END__
55
56 =pod
57
58 =encoding UTF-8
59
60 =head1 NAME
61
62 App::HomeBank2Ledger::Ledger - Ledger data representation
63
64 =head1 VERSION
65
66 version 0.002
67
68 =head1 SYNOPSIS
69
70 my $ledger = App::HomeBank2Ledger::Ledger->new;
71
72 $ledger->add_payees("Ann's Antiques", "Missy Automative");
73
74 for my $payee (@{$ledger->payees}) {
75 print "Payee: $payee\n";
76 }
77
78 =head1 DESCRIPTION
79
80 This class provides a unified in-memory representation of a ledger, including associated metadata.
81
82 Here is a specification for the substructures:
83
84 =head2 account
85
86 This is a fully-qualified account name. Names may contain colons for representing a hierarchy of
87 accounts. Examples:
88
89 =over 4
90
91 =item *
92
93 "Assets:Bank:Chase1234"
94
95 =item *
96
97 "Liabilities:Credit Card:CapitalOne"
98
99 =back
100
101 =head2 commodity
102
103 This is a hashref like this:
104
105 {
106 symbol => '$', # required
107 iso => 'USD', # optional
108 name => 'US Dollar', # optional
109 format => '$1000.00', # optional
110 }
111
112 =head2 payee
113
114 This is just a string with the name of a "payee" or memo/description/narration.
115
116 =head2 tag
117
118 This is just a string with the text of a tag.
119
120 =head2 transaction
121
122 This is a hashref like this:
123
124 {
125 date => '2019-06-12', # required
126 payee => 'Malcolm Reynolds', # required
127 status => 'cleared', # optional; can be "cleared" or "pending"
128 memo => 'Medical supplies', # optional
129 postings => [ # required
130 {
131 account => 'Some Account', # required
132 amount => '16.25', # required for at least n-1 postings
133 commodity => {
134 symbol => '$',
135 format => '$1,000.00',
136 iso => 'USD',
137 name => 'US Dollar',
138 syprf => 1,
139 dchar => '.',
140 gchar => ',',
141 frac => 2,
142 },
143 payee => 'Somebody', # optional
144 memo => 'Whatever', # optional
145 status => 'pending', # optional; can be "cleared" or "pending"
146 tags => [qw(niska train-job)],
147 },
148 ...
149 ],
150 }
151
152 =head1 ATTRIBUTES
153
154 =head2 accounts
155
156 Get an arrayref of accounts.
157
158 =head2 commodities
159
160 Get an arrayref of commodities.
161
162 =head2 payees
163
164 Get an arrayref of payees.
165
166 =head2 tags
167
168 Get an arrayref of tags.
169
170 =head2 transactions
171
172 Get an arrayref of transactions.
173
174 =head1 METHODS
175
176 =head2 new
177
178 $ledger = App::HomeBank2Ledger::Ledger->new(%ledger_data);
179
180 Construct a new ledger instance.
181
182 =head2 add_accounts
183
184 Add accounts.
185
186 =head2 add_commodities
187
188 Add commodities.
189
190 =head2 add_payees
191
192 Add payees.
193
194 =head2 add_tags
195
196 Add tags.
197
198 =head2 add_transactions
199
200 Add transactions.
201
202 =head1 BUGS
203
204 Please report any bugs or feature requests on the bugtracker website
205 L<https://github.com/chazmcgarvey/homebank2ledger/issues>
206
207 When submitting a bug or request, please include a test-file or a
208 patch to an existing test-file that illustrates the bug or desired
209 feature.
210
211 =head1 AUTHOR
212
213 Charles McGarvey <chazmcgarvey@brokenzipper.com>
214
215 =head1 COPYRIGHT AND LICENSE
216
217 This software is Copyright (c) 2019 by Charles McGarvey.
218
219 This is free software, licensed under:
220
221 The MIT (X11) License
222
223 =cut
This page took 0.039137 seconds and 4 git commands to generate.