Dogcows Code - chaz/homebank2ledger/blob - 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.010'; # 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.010
  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:Capital One"
  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         aux_date    => '2019-06-13',        # optional
 127         status      => 'cleared',           # optional; can be "cleared" or "pending"
 128         code        => '1234',              # optional
 129         payee       => 'Malcolm Reynolds',  # required
 130         note        => 'Medical supplies',  # optional
 131         postings    => [                    # required
 132             {
 133                 account     => 'Some Account',  # required
 134                 amount      => '16.25',         # required for at least n-1 postings
 135                 commodity   => {
 136                     symbol  => '$',
 137                     format  => '$1,000.00',
 138                     iso     => 'USD',
 139                     name    => 'US Dollar',
 140                     syprf   => 1,
 141                     dchar   => '.',
 142                     gchar   => ',',
 143                     frac    => 2,
 144                 },
 145                 payee       => 'Somebody',      # optional
 146                 note        => 'Whatever',      # optional
 147                 status      => 'pending',       # optional; can be "cleared" or "pending"
 148                 tags        => [qw(niska train-job)],
 149                 lot         => {                # optional
 150                     date        => '2019-01-28',
 151                     price       => {
 152                         amount      => '15.00',
 153                         commodity   => { ... },
 154                     },
 155                 },
 156                 cost        => {                # optional
 157                     amount      => '10.00',
 158                     commodity   => { ... },
 159                 },
 160             },
 161             ...
 162         ],
 163     }
 164
 165 =head1 ATTRIBUTES
 166
 167 =head2 accounts
 168
 169 Get an arrayref of accounts.
 170
 171 =head2 commodities
 172
 173 Get an arrayref of commodities.
 174
 175 =head2 payees
 176
 177 Get an arrayref of payees.
 178
 179 =head2 tags
 180
 181 Get an arrayref of tags.
 182
 183 =head2 transactions
 184
 185 Get an arrayref of transactions.
 186
 187 =head1 METHODS
 188
 189 =head2 new
 190
 191     $ledger = App::HomeBank2Ledger::Ledger->new(%ledger_data);
 192
 193 Construct a new ledger instance.
 194
 195 =head2 add_accounts
 196
 197 Add accounts.
 198
 199 =head2 add_commodities
 200
 201 Add commodities.
 202
 203 =head2 add_payees
 204
 205 Add payees.
 206
 207 =head2 add_tags
 208
 209 Add tags.
 210
 211 =head2 add_transactions
 212
 213 Add transactions.
 214
 215 =head1 BUGS
 216
 217 Please report any bugs or feature requests on the bugtracker website
 218 L<https://github.com/chazmcgarvey/homebank2ledger/issues>
 219
 220 When submitting a bug or request, please include a test-file or a
 221 patch to an existing test-file that illustrates the bug or desired
 222 feature.
 223
 224 =head1 AUTHOR
 225
 226 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 227
 228 =head1 COPYRIGHT AND LICENSE
 229
 230 This software is Copyright (c) 2019 by Charles McGarvey.
 231
 232 This is free software, licensed under:
 233
 234   The MIT (X11) License
 235
 236 =cut