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:CapitalOne"
  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         payee       => 'Malcolm Reynolds',  # required
  55         status      => 'cleared',           # optional; can be "cleared" or "pending"
  56         memo        => 'Medical supplies',  # optional
  57         postings    => [                    # required
  58             {
  59                 account     => 'Some Account',  # required
  60                 amount      => '16.25',         # required for at least n-1 postings
  61                 commodity   => {
  62                     symbol  => '$',
  63                     format  => '$1,000.00',
  64                     iso     => 'USD',
  65                     name    => 'US Dollar',
  66                     syprf   => 1,
  67                     dchar   => '.',
  68                     gchar   => ',',
  69                     frac    => 2,
  70                 },
  71                 payee       => 'Somebody',      # optional
  72                 memo        => 'Whatever',      # optional
  73                 status      => 'pending',       # optional; can be "cleared" or "pending"
  74                 tags        => [qw(niska train-job)],
  75             },
  76             ...
  77         ],
  78     }
  79
  80 =cut
  81
  82 use warnings;
  83 use strict;
  84
  85 our $VERSION = '9999.999'; # VERSION
  86
  87 =method new
  88
  89     $ledger = App::HomeBank2Ledger::Ledger->new(%ledger_data);
  90
  91 Construct a new ledger instance.
  92
  93 =cut
  94
  95 sub new {
  96     my $class = shift;
  97     my %args  = @_;
  98     return bless {%args}, $class;
  99 }
 100
 101 =attr accounts
 102
 103 Get an arrayref of accounts.
 104
 105 =attr commodities
 106
 107 Get an arrayref of commodities.
 108
 109 =attr payees
 110
 111 Get an arrayref of payees.
 112
 113 =attr tags
 114
 115 Get an arrayref of tags.
 116
 117 =attr transactions
 118
 119 Get an arrayref of transactions.
 120
 121 =cut
 122
 123 sub accounts     { shift->{accounts}     || [] }
 124 sub commodities  { shift->{commodities}  || [] }
 125 sub payees       { shift->{payees}       || [] }
 126 sub tags         { shift->{tags}         || [] }
 127 sub transactions { shift->{transactions} || [] }
 128
 129 =method add_accounts
 130
 131 Add accounts.
 132
 133 =method add_commodities
 134
 135 Add commodities.
 136
 137 =method add_payees
 138
 139 Add payees.
 140
 141 =method add_tags
 142
 143 Add tags.
 144
 145 =method add_transactions
 146
 147 Add transactions.
 148
 149 =cut
 150
 151 # TODO - These should validate incoming data.
 152
 153 sub add_accounts {
 154     my $self = shift;
 155     push @{$self->{accounts}}, @_;
 156 }
 157
 158 sub add_commodities {
 159     my $self = shift;
 160     push @{$self->{commodities}}, @_;
 161 }
 162
 163 sub add_payees {
 164     my $self = shift;
 165     push @{$self->{payees}}, @_;
 166 }
 167
 168 sub add_tags {
 169     my $self = shift;
 170     push @{$self->{tags}}, @_;
 171 }
 172
 173 sub add_transactions {
 174     my $self = shift;
 175     push @{$self->{transactions}}, @_;
 176 }
 177
 178 1;