view release on metacpan or  search on metacpan

lib/Business/US_Amort.pm  view on Meta::CPAN

and the loan object, in case you want to do things with it.

=back

Example usages:

  $monthly_payment = Business::US_Amort::simple(123654, 9.25, 20);
  
  ($monthly_payment, $total_toward_interest, $o)
    = Business::US_Amort::simple(123654, 9.25, 20);

Of course, if you find yourself doing much of anything with the
loan object, you probably should be using the OOP interface instead
of the functional one.

=cut

sub simple ($$$) {
  my($p, $i, $t) = @_[0,1,2];
  my $o = Business::US_Amort->new;
  $o->principal($p);
  $o->interest_rate($i);
  $o->term($t);

  $o->run || croak("Error while amortizing: " . $o->error . "\n");
  
  return
    wantarray ?
      ($o->initial_monthly_payment, $o->total_paid_interest, $o)
    : $o->initial_monthly_payment
  ;
}

#===========================================================================

=head1 OBJECT ATTRIBUTES

All attributes for this class are scalar attributes.  They can be read via:

  $thing = $loan->principal     OR    $thing = $loan->{'principal'}

or set via:

  $loan->principal(VALUE)       OR    $loan->{'principal'} = VALUE


=head2 MAIN ATTRIBUTES

These attributes are used as parameters to the C<run> method.

=over

=item principal

The principal amount of the loan.

=item interest_rate

The annual rate, expressed like 8.3, not like .083.

Note that if you're defining callbacks, you can change this attribute
at any time in your callbacks, to change the rate of interest from
then on.

=item term

The term of the loan, in years, not months.

=item callback_before_monthly_calc

If set, this should be a coderef to a routine to call at the B<beginning>
of each month, B<before any> calculations are done.
The one parameter passed to this routine, in $_[0], is the object.
See the SYNOPSIS, above, for an example.

=item callback_after_monthly_calc

If set, this should be a coderef to a routine to call at the B<end>
of each month, B<after all> monthly calculations are done.
The one parameter passed to this routine, in $_[0], is the object.

=item block_table

If set to true, this inhibits C<run> from adding to C<table>.  (This
is false by default.) If you're not going to access C<table>, set this
to true before calling C<run> -- it'll speed things up and use less
memory.

=item start_date

If set to a date in the format "YYYY-MM", C<_date> will be defined
appropriately for each month.  You can set C<start_date> to the current
month by just saying $loan->start_date_be_now.

=item cent_rounding

If set to true, figures are rounded to the nearest cent at appropriate
moments, so as to avoid having to suppose that the debtor is to make a
monthly payment of $1025.229348723948 on a remaining principal of
$196239.12082309123408, or the like.

=back

These attributes are set by the C<run> method:

=over

=item initial_monthly_payment

The monthly payment that follows from the basic amortization parameters
given.  Compare with C<_monthly_payment>.

=item total_paid_interest

The total amount paid toward interest during the term of this loan.

=item total_month_count

The total number of months the loan took to pay off.
E.g., "12" for a loan that took 12 months to pay off.

=item table

This will be a reference to a list of copies made of the object
("snapshots") each month.  You can then use this if you want to
generate a dump of particular values of the object's state in
each month.

Note that snapshots have their C<am_snapshot> attribute set to true,
and have their C<table> attribute set to undef.  (Otherwise this'd be
a circular data structure, which would be a hassle for you and me.)

=item error

A string explaining any error that might have occurred, which would/should
accompany C<run> returning 0.  Use like:

  $loan->run or die("Run failed: " . $loan->error);

=back

Other attributes:

=over

=item am_snapshot

This attribute is set to true in snapshots, as stored in C<table>.

=item _month_count_limit

This is a variable such that if the month count ever exceeds this
amount, the main loop will abort.  This is intended to keep the
iterator from entering any infinite loops, even in pathological cases.
Currently the C<run> method sets this to twelve plus twice the number
of months that it's expected this loan will take.
Increase as necessary.

=back

=head2 ITERATION ATTRIBUTES

These are attributes of little or no interest once C<run> is done, but
may be of interest to callbacks while C<run> is running, or may
be of interest in examining snapshots in C<table>.

=over

=item _month_count

This is how many months we are into the loan.  The first month is 1.

=item _abort

If you want callbacks to be able to halt the iteration for some
reason, you can have them set C<_abort> to true.  You may also choose
to set C<error> to something helpful.

=item _monthly_payment

The amount to be paid to toward the principal each month. At the start
of the loan, this is set to whatever C<initial_monthly_payment> is
figured to be, but you can manipulate C<_monthly_payment> with
callbacks to change how much actually gets paid when.

=item _remainder

The balance on the loan.

=item _date

The given month's date, if known, in the format "YYYY-MM".  Unless you'd
set the C<start_date> to something, this will be undef.

=item _h

The interest to be paid this month.

=item _old_amount

What the remainder was before we made this month's payment.

=item _c

The current monthly payment, minus the monthly interest, possibly
tweaked in the last month to avoid paying off more than is actually left
on the loan.

=back

=cut

###########################################################################

%Proto =  # public attributes and their values
(
  principal => 0,
  interest_rate => 8, # annual, percent
  term => 30, # years (target term)
  error => '',
  cent_rounding => 1,
  start_date => undef,

  initial_monthly_payment => undef,
  total_paid_interest => undef,
  total_month_count => undef,

  am_snapshot => 0, # flag for objects that are snapshots
  block_table => 0, # set to 1 to block table generation

  table => undef,
  callback_before_monthly_calc => undef,
  callback_after_monthly_calc => undef,

  _month_count_limit => undef,
  _abort => undef,
  _remainder => undef,
  _date => undef,
  _h => undef,
  _old_amount => undef,
  _monthly_payment => undef,
);

#===========================================================================