From cb11c02df85bf8c2f72c31717d3b44e96c2f6e9a Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 9 Jul 2010 02:07:42 +0000 Subject: [PATCH] docs: dev notes --- NOTES | 186 ++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 134 insertions(+), 52 deletions(-) diff --git a/NOTES b/NOTES index 57c3791c6..f42447f36 100644 --- a/NOTES +++ b/NOTES @@ -377,54 +377,17 @@ competitors/fellow niche inhabitants **** usability **** download & usage stats ** errors -*** balance: stack space overflow on timelog entries with colons -<<< -i 2010/1/1 09:15:00 a:b -o 2010/1/1 09:45:00 ->>>2 -Stack space overflow: current size 8388608 bytes. -Use `+RTS -Ksize' to increase it. +*** a first run with no journal file should give better help +*** print: bad layout with mixed amounts +*** register: confusing output with mixed amounts +$ hledger reg opening +2010/01/01 OPENING BALANCES $19690.92 $19690.92 + eq:opening balances €-35.00 €-35.00 +*** non-blockers +**** parsing: only journals can include, and only another journal +**** convert: rules file can't have blank lines after last data -*** register: eats memory -$ hours stats -Ledger statistics as of 2010-04-01 ----------------------------------- -File : current.timelog -Period : 2007-02-05 to 2010-01-31 (1091 days) -Last transaction : 2010-01-30 (61 days ago) -Transactions : 4333 (4.0 per day) -Transactions last 30 days: 0 (0.0 per day) -Transactions last 7 days : 0 (0.0 per day) -Accounts : 947 -Account tree depth : 8 -Commodities : 2 (h, p) -$ hours reg ...Nx100Mb... - -*** register: with reporting interval and depth, should aggregate deeper txns to specified depth -*** parsing: timelog conversion gives unbalanced txns -hledger -f- print -<<< -i 2009/01/02 10:18:26 work:business:systems:website:outage -o 2009/01/02 10:35:03 ->>> -2009/01/02 * 10:18-10:35 - work:business:systems:website:outage 0.3h - -*** print: virtual parentheses/brackets throw off alignment -<<< -2009/01/27 (1/2009) Foobar 2 - VLL:VLL_1_Year -7140.00 USD ; Some comment - (Company:Baz) -7140.00 USD - FLL:Foreign 6000.0 USD - VLL_VAT 1140.0 USD ->>> -2009/03/27 (000007) Foobar 1 - FLL 6783.00 USD - (Company:Baz) 6783.00 USD - VAT -5700.00 USD - VLL_VAT -1083.00 USD - -*** parsing: misleading error when final newline missing +**** parsing: misleading error when final newline missing hledger -f- balance <<< 2010/1/1 @@ -437,7 +400,7 @@ unexpected "\r" expecting digit, effective date, cleared flag, transaction code or description and/or comment >>>= 1 -*** parsing: wrong line number in error +**** parsing: wrong line number in error hledger -f- print <<< 2010-03-18 Postage @@ -448,7 +411,7 @@ hledger: parse error at (line 1, column 24): unexpected "@" expecting comment or new-line -*** parsing: errors should include the file name +**** parsing: errors should include the file name This one does: $ hledger -b today "/Users/simon/personal/current.journal" (line 4, column 1) in included file "2010.journal": @@ -462,14 +425,26 @@ hledger: parse error at (line 1, column 59): unexpected "[" expecting comment or new-line -*** parsing: better leap year checking +**** parsing: better leap year checking ledger: While parsing file "/Users/simon/personal/2010.ledger", line 442: While parsing transaction: > 2/27=2/29 (20100201ucla) ucla payment Error: Day of month is not valid for year -*** convert: rules file can't have blank lines after last data +**** print: virtual parentheses/brackets throw off alignment +<<< +2009/01/27 (1/2009) Foobar 2 + VLL:VLL_1_Year -7140.00 USD ; Some comment + (Company:Baz) -7140.00 USD + FLL:Foreign 6000.0 USD + VLL_VAT 1140.0 USD +>>> +2009/03/27 (000007) Foobar 1 + FLL 6783.00 USD + (Company:Baz) 6783.00 USD + VAT -5700.00 USD + VLL_VAT -1083.00 USD ** refactoring, cleanup *** more modularity @@ -479,7 +454,6 @@ Error: Day of month is not valid for year ***** more package splits ****** hledger-web ****** hledger-vty -****** makefile review/update **** plugin strategy **** export lists **** graph and reduce dependencies @@ -498,6 +472,10 @@ Error: Day of month is not valid for year *** inspiration http://community.haskell.org/~ndm/downloads/paper-hoogle_overview-19_nov_2008.pdf -> Design Guidelines ** features +*** register: depth could aggregate deeper txns, or only with reporting interval +when you do register --depth 1 and all transactions use depth-2 accounts, should it display synthetic aggregated depth-1 transactions ? +I have been wanting that, at least in the case when you have a reporting interval like -p daily + *** register --wide and/or --format ... *** --related *** Double -> Decimal @@ -687,6 +665,110 @@ are there any cashflow, tax, budgetary problems looming ? **** http://lwn.net/Articles/233627/ **** http://lwn.net/Articles/314577/ **** http://lwn.net/Articles/387967/ (free after 5/27) +*** hledger ghci examples +This is the main object you'll deal with as a user of the Ledger +library. + +The most useful functions also have shorter, lower-case aliases for easier +interaction. Here's an example: + +> > import Hledger.Data +> > j <- readJournal "sample.ledger" +> > let l = journalToLedger nullfilterspec j +> > accountnames l +> ["assets","assets:bank","assets:bank:checking","assets:bank:saving",... +> > accounts l +> [Account assets with 0 txns and $-1 balance,Account assets:bank with... +> > topaccounts l +> [Account assets with 0 txns and $-1 balance,Account expenses with... +> > account l "assets" +> Account assets with 0 txns and $-1 balance +> > accountsmatching ["ch"] l +> accountsmatching ["ch"] l +> [Account assets:bank:checking with 4 txns and $0 balance] +> > subaccounts l (account l "assets") +> subaccounts l (account l "assets") +> [Account assets:bank with 0 txns and $1 balance,Account assets:cash... +> > head $ transactions l +> 2008/01/01 income assets:bank:checking $1 RegularPosting +> > accounttree 2 l +> Node {rootLabel = Account top with 0 txns and 0 balance, subForest = [... +> > accounttreeat l (account l "assets") +> Just (Node {rootLabel = Account assets with 0 txns and $-1 balance, ... +> > datespan l -- disabled +> DateSpan (Just 2008-01-01) (Just 2009-01-01) +> > rawdatespan l +> DateSpan (Just 2008-01-01) (Just 2009-01-01) +> > ledgeramounts l +> [$1,$-1,$1,$-1,$1,$-1,$1,$1,$-2,$1,$-1] +> > commodities l +> [Commodity {symbol = "$", side = L, spaced = False, comma = False, ... + +*** ledger budgeting/forecasting +seanh: + +With `--budget` you can compare your budgeted transactions to your +actual transactions and see whether you are under or over your budget. + +The way it works is this: say you have a budget entry that moves £50 +from Assets into Expenses:Cash every week: + + ~ Weekly + Expenses:Cash £50 + Assets + +When you run register or balance with `--budget` ledger will insert +reverse transactions that move £50 _from_ Expenses:Cash _into_ Assets +every week. These are called budget entries. The idea is that your real +transactions that move money from Assets into Expenses will offset the +inserted budget entries that move money the other way. The budget +entries and the real transactions should sum to zero, if they don't then +it shows how much you have overspent or underspent. + +For example: + + ledger --budget balance '^expenses' + +balances your budgeted expenses against your actual expenses on those +budgeted accounts (sub-accounts of expenses that do not appear in the +budget are ignored in this calculation). The sum of the budget entries +(which move money out of expenses accounts) and your real transactions +(which move money into expenses accounts) should be 0. If the sum is +positive then it shows how much you've overspent, if it's negative then +it shows how much you've underspent. + +You can do the same with register and get a print out of each +transaction (budget entries and real transactions) with a running total: + + ledger --budget register '^expenses' + +And you can produce weekly, monthly or yearly budget reports: + + ledger --budget --weekly register '^expenses' + ledger --budget --monthly register '^expenses' + ledger --budget --yearly register '^expenses' + +These will only output reports for each week, month or year that has +passed (your ledger file contains transactions dated later than that +week, month, or year). You can see how well you did last week (or month, +or year) but you can't see how well you're doing so far this week +(month, year). + +The `--unbudgeted` argument will show (and sum) all your expenses for +accounts that are _not_ budgeted, and the `--add-budget` argument will +consider all your expenses budgeted or not with the budget entries +added in. + +With `--forecast` you can project your budget into the future to see, +for example, when some account will reach 0. For example, to predict +your net worth: + + ledger --forecast 'd<[2012]' register '^assets' '^liabilities' + +Or to see how your expenses will add up: + + ledger --forecast 'd<[2012]' register '^expenses' + ** software *** http://gnucash.org *** http://www.xtuple.com/postbooks