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.004'; # 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.004
  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