=================================================
 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 current 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 <more arguments>
     -n --name -> get the name of the active account
        $ brinance -4 -n
     -a --all -> show details of all accounts
        $ brinance -a
     -A --datedall -> show details of all accounts at given date
        $ brinance -A 200306271200
     -r --create -> create a new account
        $ brinance -r <account number> <account description>
     -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 eons 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

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

   -a --all
      Print the name and current balance of each account
=========================================================

[loco@erebor]% brinance -a
--
Account 0: default
Balance: 9450.00
--
Account 1: new
Balance: 27000.00
--
Account 2: <No Name>
Balance: 2.00
--

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

   -A --datedall
      Like -a, but requires a date in the same format as -[BCD]
=========================================================

[loco@erebor]% brinance -A +10
--
Account 0: default
Balance at 200603251323: 9800.00
--
Account 1: new
Balance at 200603251323: 28000.00
--
Account 2: <No Name>
Balance at 200603251323: 2.00
--

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

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


===========================
 Using the futures feature
===========================

   One of the major new features of Brinance 4.x is the ability to express
recurring transactions. Older versions allowed you to post individual
transactions in the future, but this version allows you to express, for
instance, a transaction that posts every Friday from now indefinitely (like a
paycheck). To let Brinance know about a recurring transaction you want, you have
to create a pattern. This pattern lets Brinance know the schedule of the
recurring transaction you want. Because the pattern is very different than what
goes into the Brinance accounts file, there's a whole file just for these
patterns, the futures file.
   If you've been running a 4.x version of Brinance (or a pre-release), the
futures file already exists in your Brinance directory. Just run the program
once, and the file will be created for you.
   You need to add a line in the file for each recurring transaction (e.g., your
weekly paycheck). The patterns on these lines are similar to the patterns used
for the UNIX cron daemon, but slightly different to meet the needs of Brinance.
Here's the layout of these patterns:

<YEAR> <MONTH> <DATE> <DAY-LOGIC> <WEEKDAY> <HOUR> <MINUTE> :<ORIGIN>: <ACCOUNT> <AMOUNT> <DESCRIPTION>

<YEAR> - 4 digit year
<MONTH> - numeric month (12 is December) or the first 3 letters of the month's
	name (e.g. Jun)
<DATE> - day of the month
<DAY-LOGIC> - determines whether we apply a transaction when the current date
	matches the date AND weekday, or the date OR weekday; defaults to OR, so
	you can leave it off
<WEEKDAY> - day of the week, 1-7 (for Monday - Sunday), or first three letters
	of the name of the day (e.g. Wed)
<HOUR> - The hour when to apply the transaction if the pattern matches today
<MINUTE> - The minute of the hour when to apply the transaction if the pattern
	matches today
:<ORIGIN>: - used in some more complex patterns to specify when to first apply
<ACCOUNT> - which account this transaction affects
<AMOUNT> - how much
<DESCRIPTION> - a transaction description

   <YEAR>, <MONTH>, <DATE>, and <WEEKDAY> can all simply be a '*' by itself,
which indicates that the pattern matches any value in this field. The
every-Friday paycheck example we used above would look like this:

* * * Fri 0 0 :: 1 500 Paycheck

   This would apply the transaction every Friday morning at midnight.
   What if you get paid every other Friday? That's a little trickier, but
doable. The trick is that you have to give an origin date, an example of a
Friday on which you do get paid, so Brinance knows where to start. This is like
Brinance's 12-digit dates, but you don't specify hour or minute, so it's only 8
digits. Like so:

* * * Fri/2 0 0 :20060303: 1 1000 Paycheck

======
 TIPS
======

**Option Grouping (bundling)

   You can put options (the arguments that start with a '-') together into
option "bundles." For instance:
=========================================================

[loco@erebor]% brinance -b -1 -b

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

   ... is the same as ...
=========================================================

[loco@erebor]% brinance -b1b

=========================================================
   You can save some typing time..


**Less Specific Dates

   Brinance can figure out what date you mean if you give it a less specific
date. This can also be a typing time saver.
=========================================================

[loco@erebor]% brinance -B 1700

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

   The above command will tell you the balance at 5pm today. Note that it won't
give the balance at the most recent 5pm, but only today's, whether that's in the
past or the future. You only have to give the parts of the date that are
different from right now. So, if the 12-digit date for right now is
'200603151330', and you want to apply a transaction from 11:00AM this morning,
you only need to type:
=========================================================

[loco@erebor]% brinance -D 1100 1.09 "bottle of coke"

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

   If the transaction was last week sometime, just specify the date, too.
=========================================================

[loco@erebor]% brinance -D 091348 23.47 gas

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

   Notice that there is a leading zero on that date. If that was left off,
Brinance would assume you meant '191348', because the date now is
'200603151330', and it's just combining what you inputted with the current date.

