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.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