Dogcows Code - chaz/homebank2ledger/blob - lib/App/HomeBank2Ledger/Ledger.pm

   1 package App::HomeBank2Ledger::Ledger;
   2 # ABSTRACT: Ledger data representation
   3
   4 =head1 SYNOPSIS
   5
   6     my $ledger = App::HomeBank2Ledger::Ledger->new;
   7
   8     $ledger->add_payees("Ann's Antiques", "Missy Automative");
   9
  10     for my $payee (@{$ledger->payees}) {
  11         print "Payee: $payee\n";
  12     }
  13
  14 =head1 DESCRIPTION
  15
  16 This class provides a unified in-memory representation of a ledger, including associated metadata.
  17
  18 Here is a specification for the substructures:
  19
  20 =head2 account
  21
  22 This is a fully-qualified account name. Names may contain colons for representing a hierarchy of
  23 accounts. Examples:
  24
  25 =for :list
  26 * "Assets:Bank:Chase1234"
  27 * "Liabilities:Credit Card:Capital One"
  28
  29 =head2 commodity
  30
  31 This is a hashref like this:
  32
  33     {
  34         symbol  => '$',             # required
  35         iso     => 'USD',           # optional
  36         name    => 'US Dollar',     # optional
  37         format  => '$1000.00',      # optional
  38     }
  39
  40 =head2 payee
  41
  42 This is just a string with the name of a "payee" or memo/description/narration.
  43
  44 =head2 tag
  45
  46 This is just a string with the text of a tag.
  47
  48 =head2 transaction
  49
  50 This is a hashref like this:
  51
  52     {
  53         date        => '2019-06-12',        # required
  54         aux_date    => '2019-06-13',        # optional
  55         status      => 'cleared',           # optional; can be "cleared" or "pending"
  56         code        => '1234',              # optional
  57         payee       => 'Malcolm Reynolds',  # required
  58         note        => 'Medical supplies',  # optional
  59         postings    => [                    # required
  60             {
  61                 account     => 'Some Account',  # required
  62                 amount      => '16.25',         # required for at least n-1 postings
  63                 commodity   => {
  64                     symbol  => '$',
  65                     format  => '$1,000.00',
  66                     iso     => 'USD',
  67                     name    => 'US Dollar',
  68                     syprf   => 1,
  69                     dchar   => '.',
  70                     gchar   => ',',
  71                     frac    => 2,
  72                 },
  73                 payee       => 'Somebody',      # optional
  74                 note        => 'Whatever',      # optional
  75                 status      => 'pending',       # optional; can be "cleared" or "pending"
  76                 tags        => [qw(niska train-job)],
  77                 lot         => {                # optional
  78                     date        => '2019-01-28',
  79                     price       => {
  80                         amount      => '15.00',
  81                         commodity   => { ... },
  82                     },
  83                 },
  84                 cost        => {                # optional
  85                     amount      => '10.00',
  86                     commodity   => { ... },
  87                 },
  88             },
  89             ...
  90         ],
  91     }
  92
  93 =cut
  94
  95 use warnings;
  96 use strict;
  97
  98 our $VERSION = '9999.999'; # VERSION
  99
 100 =method new
 101
 102     $ledger = App::HomeBank2Ledger::Ledger->new(%ledger_data);
 103
 104 Construct a new ledger instance.
 105
 106 =cut
 107
 108 sub new {
 109     my $class = shift;
 110     my %args  = @_;
 111     return bless {%args}, $class;
 112 }
 113
 114 =attr accounts
 115
 116 Get an arrayref of accounts.
 117
 118 =attr commodities
 119
 120 Get an arrayref of commodities.
 121
 122 =attr payees
 123
 124 Get an arrayref of payees.
 125
 126 =attr tags
 127
 128 Get an arrayref of tags.
 129
 130 =attr transactions
 131
 132 Get an arrayref of transactions.
 133
 134 =cut
 135
 136 sub accounts     { shift->{accounts}     || [] }
 137 sub commodities  { shift->{commodities}  || [] }
 138 sub payees       { shift->{payees}       || [] }
 139 sub tags         { shift->{tags}         || [] }
 140 sub transactions { shift->{transactions} || [] }
 141
 142 =method add_accounts
 143
 144 Add accounts.
 145
 146 =method add_commodities
 147
 148 Add commodities.
 149
 150 =method add_payees
 151
 152 Add payees.
 153
 154 =method add_tags
 155
 156 Add tags.
 157
 158 =method add_transactions
 159
 160 Add transactions.
 161
 162 =cut
 163
 164 # TODO - These should validate incoming data.
 165
 166 sub add_accounts {
 167     my $self = shift;
 168     push @{$self->{accounts}}, @_;
 169 }
 170
 171 sub add_commodities {
 172     my $self = shift;
 173     push @{$self->{commodities}}, @_;
 174 }
 175
 176 sub add_payees {
 177     my $self = shift;
 178     push @{$self->{payees}}, @_;
 179 }
 180
 181 sub add_tags {
 182     my $self = shift;
 183     push @{$self->{tags}}, @_;
 184 }
 185
 186 sub add_transactions {
 187     my $self = shift;
 188     push @{$self->{transactions}}, @_;
 189 }
 190
 191 1;