===========================
 Using the Brinance module
===========================

   Version of 3 of Brinance introduced a Perl module that does all the heavy
lifting for you. Herein, you'll find documentation for each subroutine and
variable in the module. This is current as of version 3.93, found in brinance
version 3.96. Some subroutines have been deprecated since version 3.x.
   I've tried to maintain combatibility with the 3.x releases in the 4.x
releases. I've only added one subroutine since then, &get_accts. Some
subroutines have been deprecated since then, though.

SUBROUTINES:

sub &Brinance::version ():
   Takes no arguments. Returns the value of the global $VERSION string, the
version of the module.

sub &Brinance::getName ():
   Takes no arguments. Returns the name of the current account, or undef if
there is no name.

sub &Brinance::balance ( <$date> ):
   Returns the balance of the current account. Takes a date in 12-digit format
(YYYYMMDDHHmm, e.g. 200306271645) to calculate the balance from, or calculates
for now if no arguments.
   0    => dated balance is 0, or date is incorrect format
   else => dated balance is returned

sub &Brinance::trans ( $amount, $comment, <$date> ):
   Applies a transaction against the current account. Takes two or three
arguments: a transaction amount, a string describing the transaction, and
optionally a date in 12-digit format (YYYYMMDDHHmm, e.g. 200306271645). If no
date is specified, the transaction is applied for the current time. This
subroutine is called for either a credit or a debit. Negative amounts are
debits, positive amounts are credits. The subroutine returns as follows:
   0 => success
  -1 => Too few arguments (at least two are required)
  -2 => A zero-value transaction, which is meaningless, and might mean a
non-number was passed as the transaction amount
  -3 => Invalid date format

sub &Brinance::create ( $accountName, $accountNumber ):
   Takes two arguments: an account name and an account number. The account name
can be an empty string. The subroutine returns as follows:
   1 => The requested account already exists, no change
   0 => success
  -1 => Too few arguments (two are required)

sub &Brinance::switch_acct ( $accountNumber ):
   Takes one argument: the account number to switch to. Makes sure the requested
account exists, and errors if not. This is checked by looking to make sure that
there is a NAME line in the accounts file. The subroutine returns as follows:
   1 => initial creation of account0, the default, success
   0 => account exists, success
  -1 => account doesn't exist, unsafe to use

sub &Brinance::get_accts ():
	Returns a list of numbers of all accounts

**Internal; you shouldn't need to call this function
sub &Brinance::_renow ():
   Takes no arguments. Reinitializes the $Brinance::now variable to the current
time. Should not need to be called by external code; only used within the
module. Returns nothing.

**Deprecated: Use sub &Brinance::balance**
sub &Brinance::datedbalance ( $date ):
   Takes one argument: a date in 12-digit format (YYYYMMDDHHmm, e.g.
200306271645). Calculates the balance for the current account at the specified
date. The calling code must be careful to supply a properly formatted date, or
the output may be unreliable. The subroutine returns as follows:
   0    => dated balance is 0, or there are not enough arguments
   else => dated balance is returned

**Deprecated: Use sub &Briance::trans**
sub &Brinance::datedtrans ( $date, $amount, $comment ):
   Takes three arguments: a date in 12-digit format (YYYYMMDDHHmm, e.g.
200306271645), a transaction amount and a transaction comment. Applies the
transaction at the specified date. The subroutine returns as follows:
   0 => success
  -1 => Too few arguments (three are required)
  -2 => A zero-value transaction, which is meaningless, and might mean a
non-number was passed as the transaction amount
  -3 => Invalid date format

**Deprecated: This functionality occurs implicitly now when switch_acct is
called. This is now a no-op.**
sub &Brinance::update_future ():
   Takes no arguments. Scans future file for the current account to see if there
are any transactions that are now in the past. If so, they are applied to the
current account file. Returns nothing.

   All other functions in the module are internal only and are not meant to be
called by outside code.

VARIABLES: No calling program should need to modify these variables. They can be
used for reference.

$Brinance::current_acct:
   The number of the current account. This is set by using the
&Brinance::switch_acct method.

$Brinance::$now:
   The current date and time in 12-digit format, just as if running the command:
`date +%C%y%m%d%H%M`. This is automatically set inside the module anytime before
it might need the current date. The &_renow method is used to do this.

$Brinance::$account_dir:
   A string indicating where Brinance looks for all of its account files,
generally set to ~/.brinance/. This is initialized inside the module code.
