hledger/NOTES

hledger project notes

"...simplicity of design was the most essential, guiding principle.
Clarity of concepts, economy of features, efficiency and reliability of
implementations were its consequences." --Niklaus Wirth

* to do
** errors
*** make account balances reflect account filtering
*** print command doesn't filter by account ?
*** ? in description or amount gives "too many blank transactions"
*** parse commented lines at end of file 
*** display mixed amounts vertically, not horizontally
** features
*** flexible date expressions, for easier time reports
*** commodity @ rate, for tracking client hours in main ledger
*** actual/effective entry & txn dates, for ...
*** --display, for reconciling recent transactions with real balance
*** more ledger features from README
*** new features
**** option for strict ledger-compatible output (or, compare xml ?)
**** --compare to compare ledger with same args
**** workable horizontal commodities display
**** in/out times in timelog entry descriptions
**** graphs
**** easier data entry
**** flexible option ordering
**** parse more file formats
**** easy conversion from cabal-installed to darcs repo
**** i18n
*** speed
**** profile
**** cache file
** cleanups
** tests
*** test on more ledger files
*** speed regression tests
*** more modular/scalable approach to test data ?
*** figure out reliable maintainable appropriate tests
*** easy ledger compatibility testing
** docs
*** --version
*** --help
*** readme
**** keep in sync (automate)
***** README file
***** hledger.hs module description
***** hledger.cabal description field (exclude home page link)
***** home page description (http://joyful.com/Hledger/editform)
***** mail list description (http://google.com/groups/hledger)
***** gmane description
***** darcsweb description
*** announcements
**** generate from README and NEWS
*** release notes
**** NEWS
*** implementation docs
*** api docs
*** developer intro
*** user manual
** web presence
*** clarify bugtracking process
* misc
** differences noted
*** ledger needs a space after -f
*** ledger shows description comments as part of description
*** ledger shows small time amounts in minutes
*** ledger can get timelog entry balance wrong, see mail list
** things I want to know
*** time
where have I been spending my time in recent weeks ?
where have I spent my time today ?
what is my status wrt spending plan for this week/month/year ?
what is my current status wrt time spending goals ?
*** money
where have I been spending my money ?
what is my status wrt spending plan for this week/month/year ?
what is my current status wrt spending/savings goals ?
what are all my current balances ?
what does my balance history look like ?
what does my balance future look like ?
are there any cashflow, tax, budgetary problems looming ?
*** charts
[1:27pm] <sm> I have decided I am not getting enough visible day-to-day value out of my ledger, I need more of that to stay motivated
[1:27pm] <Nafai> What do you think will help in that?
[1:27pm] <sm> I think some simple self-updating charts, or even good reports in a visible place
[1:28pm] <sm> something I don't have to spend an hour fiddling with to get answers
[1:38pm] <sm> Nafai: identifying/designing some useful reports/charts seems to be blocking me
[1:39pm] <sm> there are probably some standard ones I should use
[1:40pm] <sm> a graph of daily net worth is probably one of the simplest
[1:58pm] <sm> what else.. a chart of weekly expenses in key categories
[1:58pm] <sm> ditto, monthly
[1:58pm] <sm> a chart of monthly income
[1:59pm] <sm> those three should help me be more clear about cashflow status
[2:00pm] <sm> also I'd like something that shows me how much I am on top of financial tracking - how current my numbers are, when last reconciled etc - at a glance
[2:01pm] <sm> another simple one: current balances in all accounts
[2:01pm] <sm> those would be a great start
[2:04pm] <sm> daily net worth, weekly expense, monthly expense, monthly income, confidence/currentness report, and balance report
[2:05pm] <sm> let's see, which of those 6 would give most payoff right now
[2:05pm] <sm> probably 5
[2:06pm] <sm> how could I measure that ?
[2:06pm] <sm> number of days since last ledger entry..
[2:06pm] <sm> number of ledger entries in last 30 days (compared to average)
[2:07pm] <sm> number of days since last cleared checking entry (indicating an online reconcile)
[2:08pm] <sm> those would be a good start. How do I make those visual
[2:09pm] <sm> well I guess the first step is a script to print them

** compare other languages! a parser generator and decent speed is required
*** python: http://cheeseshop.python.org/pypi/ZestyParser, pysec, pyparsing
*** squeak: LanguageGame, T-Gen, SmaCC
*** lisp: ?
*** ruby: too slow (?)

** data representation
*** http://www.python.org/dev/peps/pep-0327/
*** http://www.n-heptane.com/nhlab/repos/Decimal/
*** http://www.n-heptane.com/nhlab/repos/Decimal/Money.hs
*** http://www2.hursley.ibm.com/decimal/

** lispy's template haskell for quickcheck
-- find tests with template haskell
import Language.Haskell.Parser

{-# OPTIONS_GHC -fno-warn-unused-imports -no-recomp -fth #-}
{- ghc --make Unit.hs -main-is Unit.runTests -o unit -}
runTests :: IO ()
runTests = $(mkChecks props)

mkChecks []        = undefined
mkChecks [name]    = mkCheck name
mkChecks (name:ns) = [| $(mkCheck name) >> $(mkChecks ns) |]

mkCheck name = [| putStr (name ++ ": ") >> quickCheck $(varE (mkName name)) |]

{- | looks in Tests.hs for functions like prop_foo and returns
  the list.  Requires that Tests.hs be valid Haskell98. -}
props :: [String]
props = unsafePerformIO $
  do h <- openFile "Tests.hs" ReadMode
     s <- hGetContents h
     case parseModule s of
       (ParseOk (HsModule _ _ _ _ ds)) -> return (map declName (filter isProp ds))
       (ParseFailed loc s')            -> error (s' ++ " " ++ show loc)

{- | checks if function binding name starts with @prop_@ indicating
 that it is a quickcheck property -}
isProp :: HsDecl -> Bool
isProp d@(HsFunBind _) = "prop_" `isPrefixOf` (declName d)
isProp _ = False

{- | takes an HsDecl and returns the name of the declaration -}
declName :: HsDecl -> String
declName (HsFunBind (HsMatch _ (HsIdent name) _ _ _:_)) = name
declName _                                              = undefined

** separate commodity display settings
type CommoditySymbol = String

data CommodityDisplayPrefs = CommodityDisplayPrefs {
      side :: Side,      -- ^ should the symbol appear on the left or the right
      spaced :: Bool,    -- ^ should there be a space between symbol and quantity
      comma :: Bool,     -- ^ should thousands be comma-separated
      precision :: Int,  -- ^ number of decimal places to display
    } deriving (Eq,Show)

data Amount = Amount {
      commodity :: CommoditySymbol,
      quantity :: Double
    } deriving (Eq)