Version 0.001
[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.001'; # 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.001
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 =head1 ATTRIBUTES
90
91 =head2 accounts
92
93 Get an arrayref of accounts.
94
95 =head2 commodities
96
97 Get an arrayref of commodities.
98
99 =head2 payees
100
101 Get an arrayref of payees.
102
103 =head2 tags
104
105 Get an arrayref of tags.
106
107 =head2 transactions
108
109 Get an arrayref of transactions.
110
111 =head1 METHODS
112
113 =head2 new
114
115 $ledger = App::HomeBank2Ledger::Ledger->new(%ledger_data);
116
117 Construct a new ledger instance.
118
119 =head2 add_accounts
120
121 Add accounts.
122
123 =head2 add_commodities
124
125 Add commodities.
126
127 =head2 add_payees
128
129 Add payees.
130
131 =head2 add_tags
132
133 Add tags.
134
135 =head2 add_transactions
136
137 Add transactions.
138
139 =for: list
140 * "Assets:Bank:Chase1234"
141 * "Liabilities:Credit Card:CapitalOne"
142
143 =head2 commodity
144
145 This is a hashref like this:
146
147 {
148 symbol => '$', # required
149 iso => 'USD', # optional
150 name => 'US Dollar', # optional
151 format => '$1000.00', # optional
152 }
153
154 =head2 payee
155
156 This is just a string with the name of a "payee" or memo/description/narration.
157
158 =head2 tag
159
160 This is just a string with the text of a tag.
161
162 =head2 transaction
163
164 This is a hashref like this:
165
166 {
167 date => '2019-06-12', # required
168 payee => 'Malcolm Reynolds', # required
169 status => 'cleared', # optional; can be "cleared" or "pending"
170 memo => 'Medical supplies', # optional
171 postings => [ # required
172 {
173 account => 'Some Account', # required
174 amount => '16.25', # required for at least n-1 postings
175 commodity => {
176 symbol => '$',
177 format => '$1,000.00',
178 iso => 'USD',
179 name => 'US Dollar',
180 syprf => 1,
181 dchar => '.',
182 gchar => ',',
183 frac => 2,
184 },
185 payee => 'Somebody', # optional
186 memo => 'Whatever', # optional
187 status => 'pending', # optional; can be "cleared" or "pending"
188 tags => [qw(niska train-job)],
189 },
190 ...
191 ],
192 }
193
194 =head1 BUGS
195
196 Please report any bugs or feature requests on the bugtracker website
197 L<https://github.com/chazmcgarvey/homebank2ledger/issues>
198
199 When submitting a bug or request, please include a test-file or a
200 patch to an existing test-file that illustrates the bug or desired
201 feature.
202
203 =head1 AUTHOR
204
205 Charles McGarvey <chazmcgarvey@brokenzipper.com>
206
207 =head1 COPYRIGHT AND LICENSE
208
209 This software is Copyright (c) 2019 by Charles McGarvey.
210
211 This is free software, licensed under:
212
213 The MIT (X11) License
214
215 =cut
This page took 0.042085 seconds and 4 git commands to generate.