README money
============

money 0.2

ABOUT

money is a Unix utility that  keeps track of monthly income and
expenditure. It is a money management software with a focus on ultimate
simplicity: it is currency-agnostic, does not handle several accounts
and should not take more than five minutes to learn.

Basically, this was written by a student for a student's needs :-)


INSTALLATION

Run the file install.sh as root. This will copy the script to
/usr/bin and create an initial budget file in ~/.money.


USAGE 

money [options] <command> [parameters]

Options:
	--version -v	Print the version number.
	--help -h		Print this help text.
	--file <file>	Specify a budget file other than ~/.money
	--month <month>	Specify another month instead of the current one
	--monthly -m	Shorthand for '--month "Monthly budget"'

Commands:
	balance		Print the current month's balance
	report		Print all transactions this month
	find <string>	Display all budget entries containing this string
	spent <amount> [comment]	Log a spending
	received <amount> [comment]	Log an amount received


DETAILS

money is a short Python script that uses a plain text file stored under 
~/.money to save all budget information. This file has a very simple
syntax, as illustrated below.

[EXAMPLE]
Monthly budget
	+        900.00 Scholarship 
	+        650.00 Side job 
	+        250.00 Pocket money
	-       1200.00 College fees
	-        375.00 Rent
	===============
	Balance: 225.00

January 1970
	+		 225.00 Monthly budget
	+        120.00 Birthday present 
	-        161.00 Food
	-		  89.00 TAOCP
	-	      53.00 Transport
	===============
	Balance:  42.00
[/EXAMPLE]

Each section contains the incomes and expenditures of one month. Sections are 
separated by an empty line. The first section contains the overall monthly 
budget (entries that are constant every month). This section has to be called
"Monthly budget" (without the quotes). If no section matching the current month
is found, a new section is automatically created. The first line of each section
is its name (consisting of the month and the year), the last word of the last 
line the total balance. For lines in the middle, money looks at the first word 
(words are strings separated by whitespace). If the first word is the symbol +, 
the subsequent word is assumed to be a number denoting an income. If the first 
word is the symbol -, the next word is interpreted as an expenditure. Any other 
text on such lines is treated as comments and preserved. Lines not starting with
+ or - are ignored and removed (except for the bottom line money draws in above
the balance line).

Unless a wrong entry was made or some other mistake needs to be corrected, the
user should not normally have to edit the budget file by hand. Manually updating
the balance is not necessary, as money recalculates it every time based on that
month's entries.

In general, money sticks to Postel's Prescription: "Be generous in what you 
accept, rigorous in what you emit". This means that any file conforming to the 
rules in the paragraphs above will be accepted, but money will always save its 
budget file formatted as in the example.


CONTRIBUTING

Contributions via Launchpad are welcome. Please note, however, that ultimate
simplicity remains money's primary goal - requests for features will be
considered in the light of this. Apart from that, all contributions are very
welcome, be they comments, patches or other.


LICENSE

	money 0.2
    Copyright (c) 2015 Daniel Vedder

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.