=================================================
 How to use brinance (and a bit of motivation..)
=================================================

   Brinance is a commandline financial planning and tracking program, hoping to
be a functional replacement for something overly complicated like GnuCash for
those who prefer the commandline. It is written in simple Perl and has a few
advanced features, such as scheduling transactions in the future and having as
many accounts as one might care to have.
   No disrespect to GnuCash, but I started this program so that I wouldn't have
to be tied to a GUI interface to do my finances. I originally wrote it in simple
C++, but wanted to try out Perl more, so when the time came to do a re-write
(add future transactions and multiple accounts, mostly) I was able to think of
how to do it in Perl pretty quickly, so off I went.

   Brinance keeps its data in some files in its own directory within your home
directory, cleverly called '.brinance'. The first file of note holds all normal
past and future transactions for all accounts, cleverly called 'accounts'. There
is also a 'futures' file that contains patterns for complex and repeated future
transactions in a different format than the 'accounts' file.

[loco@erebor]% ls -l ~/.brinance/
total 37
-rw-------  1 loco users 24917 May 26 11:46 accounts
-rw-------  1 loco users    20 May 25 22:53 futures
drwxr-xr-x  2 loco users  4096 May 26 15:35 lib/

   Anyway, so on to how to use this program. First, here's the help output,
which I'll explain a bit more below:
=========================================================

[loco@erebor]% brinance --help
Usage:

  $ brinance <args>

  Accepted args:
     -b --balance -> show balance
        $ brinance -b
     -B --datedbalance -> show dated balance
        $ brinance -B 200306271200
     -c --credit -> apply credit
        $ brinance -c <amount> <comment>
     -C --datedcredit -> apply dated credit
        $ brinance -C 200306271200 <amount> <comment>
     -d --debit -> apply debit
        $ brinance -d <amount> <comment>
     -D --dateddebit -> apply dated debit
        $ brinance -D 200306271200 <amount> <comment>
     -# -> (as in, a number) all following arguments refer to this account
        $ brinance -2 <action>
     -n --name -> get the name of the active account
        $ brinance -4 -n
     -r --create -> create a new account
        $ brinance -r <account description> <account number>
     -h --help -> help
        $ brinance -h
     -v --version -> version
        $ brinance -v

See README for more information.

=========================================================

OPTIONS:
   -b --balance
      Shows the balance on the current account. This can be specified many times
on the command line, as in:

[loco@erebor]% brinance -b -1 -b
Balance: 136.65
Now working with account 1
Balance: 777.31

      ..which would give the current balances on accounts 0 (the default) and 1.

   -B --datedbalance
      Shows the balance at a specified time. The date can be indicated by either
giving a date stamp in the format %C%y%m%d%H%M (out to the minute, all bunched
together with no punctuation, padded values so that there are a total of 12
digits), or by how many full days in the future (only for the future) by putting
a '+' in front of the number, as so..
=========================================================

[loco@erebor]% brinance -b -B +100 -1 -B 200307190000
Balance: 136.65
account0 dated balance: 823.35
Now working with account1
account1 dated balance: 883.74

=========================================================
      When specifying a 12-digit date, you can specify a future date or a past
date. The ability to check what your balance was some times aeons ago is
supported.

   -c --credit
      Post a credit right now. You need to give an amount (no currency symbol,
just '.' and '-' are allowed where appropriate).
=========================================================

[loco@erebor]% brinance -c 12.56 "A test credit"
Balance after credit: 69.56

=========================================================
      The transaction description ("A test credit" in this example) is only one
argument, so if you've got spaces or special characters, you need to quote them
however you do that with your shell.

   -C --datedcredit
      Post a credit at a specified date. Just like a normal credit, but you need
to specify a date (in either format listed above) before the amount.
=========================================================

[loco@erebor]% brinance -C 200308080000 100 "birthday money"

=========================================================

   -d --debit
      Just like a credit, but the amount is negated before it's recorded. Same
syntax as '-c'. Give it it a regular number value, and brinance will subtract it
from the total balance for that account.

   -D --dateddebit
      Just what you'd think, a dated debit. Same syntax as '-C'.

   -{#}
      Switch the active account to this numbered account. That account must
already exist, or brinance exits. You use a literal number though. You'll use
this option to switch to that account to work with it. You can specify this
option more than once to work with multiple accounts in one command line.

[loco@erebor]% brinance -1 -b
Now working with account1
Balance: 777.31

   -n --name
      Get the name of the active account. If there isn't a name on the specified
account, it'll say so.

[loco@erebor]% brinance -n -2 -n
account0 name: checking account
Now working with account2
No name for account2

   -r --create
      Create a new account. You will have to manually do this for every account
you want besides the initial. This creates an account with the number you
specify, if those files don't already exist. The first argument to -r is an
account description. The second argument is the requested number.

[loco@erebor]% brinance -r "My new account" 17
account17 created successfully

[loco@erebor]% brinance -r "An error this time.." 17
ERROR: account17 already exists

   -h --help
      Print all the options along with brief descriptions.

   -v --version
      Print the versions of the brinance CLI and module that you are running.

