From 5a1452c5db00fb96ddaf78a272c5eba0e5072c06 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 1 Oct 2008 09:33:05 +0000 Subject: [PATCH] move around and clean up haddock comments --- AccountName.hs | 10 ++-- Amount.hs | 19 ++++--- Ledger.hs | 146 ++++++++++++++++++++++++++----------------------- LedgerEntry.hs | 55 +++++++++++-------- Types.hs | 47 ++++------------ hledger.hs | 34 ++++++++++-- 6 files changed, 169 insertions(+), 142 deletions(-) diff --git a/AccountName.hs b/AccountName.hs index fc0111ec6..c45f96b30 100644 --- a/AccountName.hs +++ b/AccountName.hs @@ -46,11 +46,11 @@ s `isSubAccountNameOf` p = subAccountNamesFrom :: [AccountName] -> AccountName -> [AccountName] subAccountNamesFrom accts a = filter (`isSubAccountNameOf` a) accts --- | We could almost get by with just the above, but we need smarter --- structures to eg display the account tree with boring accounts elided. --- first, here is a tree of AccountNames; Account and Account tree are --- defined later. - +-- | We could almost get by with just the AccountName manipulations +-- above, but we need smarter structures to eg display the account +-- tree with boring accounts elided. This converts a list of +-- AccountNames to a tree (later we will convert that to a tree of +-- Accounts.) accountNameTreeFrom_props = [ accountNameTreeFrom ["a"] == Node "top" [Node "a" []], diff --git a/Amount.hs b/Amount.hs index 10d1817dc..52f05f39a 100644 --- a/Amount.hs +++ b/Amount.hs @@ -1,6 +1,7 @@ {-| -a simple amount is a currency, quantity pair: +A simple amount is a currency, quantity pair: +@ $1 £-50 EUR 3.44 @@ -8,18 +9,20 @@ a simple amount is a currency, quantity pair: 1.5h 90m 0 +@ -a mixed amount is one or more simple amounts: +A mixed amount is one or more simple amounts: +@ $50, EUR 3, AAPL 500 16h, $13.55, oranges 6 +@ -currencies may be convertible or not (eg, currencies representing +Currencies may be convertible or not (eg, currencies representing non-money commodities). A mixed amount containing only convertible -currencies can be converted to a simple amount. - -arithmetic: +currencies can be converted to a simple amount. Arithmetic examples: +@ $1 - $5 = $-4 $1 + EUR 0.76 = $2 EUR0.76 + $1 = EUR 1.52 @@ -28,7 +31,7 @@ arithmetic: ($50, EUR 3, AAPL 500) + ($13.55, oranges 6) = $67.51, AAPL 500, oranges 6 ($50, EUR 3) * $-1 = $-53.96 ($50, AAPL 500) * $-1 = error - +@ -} module Amount @@ -80,7 +83,7 @@ instance Num Amount where (-) = amountop (-) (*) = amountop (*) --- | problem: when an integer is converted to an amount it must pick a +-- problem: when an integer is converted to an amount it must pick a -- precision, which we specify here (should be infinite ?). This can -- affect amount arithmetic, in particular the sum of a list of amounts. -- So, we may need to adjust the precision after summing amounts. diff --git a/Ledger.hs b/Ledger.hs index 8ecdf9f7b..ed8f6f0f8 100644 --- a/Ledger.hs +++ b/Ledger.hs @@ -110,74 +110,86 @@ ledgerAccountTree l depth = addDataToAccountNameTree :: Ledger -> Tree AccountName -> Tree Account addDataToAccountNameTree = treemap . ledgerAccount --- | balance report support --- --- examples: here is a sample account tree: --- --- assets --- cash --- checking --- saving --- equity --- expenses --- food --- shelter --- income --- salary --- liabilities --- debts --- --- standard balance command shows all top-level accounts: --- --- > ledger bal --- --- $ assets --- $ equity --- $ expenses --- $ income --- $ liabilities --- --- with an account pattern, show only the ones with matching names: --- --- > ledger bal asset --- --- $ assets --- --- with -s, show all subaccounts of matched accounts: --- --- > ledger -s bal asset --- --- $ assets --- $ cash --- $ checking --- $ saving --- --- we elide boring accounts in two ways: --- --- - leaf accounts and branches with 0 balance or 0 transactions are omitted --- --- - inner accounts with 0 transactions and 1 subaccount are displayed inline --- --- so this: --- --- a (0 txns) --- b (0 txns) --- c --- d --- e (0 txns) --- f --- g --- h (0 txns) --- i (0 balance) --- --- is displayed like: --- --- a:b:c --- d --- e --- f --- g +{-| +This and the functions below help generate ledger-compatible balance +reports. Here's how it should work: + +a sample account tree: + +@ +assets + cash + checking + saving +equity +expenses + food + shelter +income + salary +liabilities + debts +@ + +the standard balance command shows all top-level accounts: + +@ +\> ledger balance +$ assets +$ equity +$ expenses +$ income +$ liabilities +@ + +with an account pattern, show only the ones with matching names: + +@ +\> ledger balance asset +$ assets +@ + +with -s, show all subaccounts of matched accounts: + +@ +\> ledger -s balance asset +$ assets +$ cash +$ checking +$ saving +@ + +we elide boring accounts in two ways: + +- leaf accounts and branches with 0 balance or 0 transactions are omitted + +- inner accounts with 0 transactions and 1 subaccount are displayed inline + +so this: + +@ +a (0 txns) + b (0 txns) + c + d +e (0 txns) + f + g +h (0 txns) + i (0 balance) +@ + +is displayed like: + +@ +a:b:c + d +e + f + g +@ +-} showLedgerAccounts :: Ledger -> Int -> String showLedgerAccounts l maxdepth = concatMap diff --git a/LedgerEntry.hs b/LedgerEntry.hs index ac5fd1afb..accbb14b8 100644 --- a/LedgerEntry.hs +++ b/LedgerEntry.hs @@ -8,18 +8,23 @@ import Amount instance Show LedgerEntry where show = showEntryDescription --- | for register report --- --- a register entry is displayed as two or more lines like this: --- date description account amount balance --- DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAA AAAAAAAAAAAA --- aaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAA AAAAAAAAAAAA --- ... ... ... --- datewidth = 10 --- descwidth = 20 --- acctwidth = 22 --- amtwidth = 11 --- balwidth = 12 +{- +Helpers for the register report. A register entry is displayed as two +or more lines like this: + +@ +date description account amount balance +DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAA AAAAAAAAAAAA + aaaaaaaaaaaaaaaaaaaaaa AAAAAAAAAAA AAAAAAAAAAAA + ... ... ... + +datewidth = 10 +descwidth = 20 +acctwidth = 22 +amtwidth = 11 +balwidth = 12 +@ +-} showEntryDescription e = (showDate $ edate e) ++ " " ++ (showDescription $ edescription e) ++ " " showDate d = printf "%-10s" d @@ -36,18 +41,22 @@ autofillEntry e@(LedgerEntry _ _ _ _ _ ts _) = True -> e' False -> (error $ "transactions don't balance in " ++ show e) --- | the print command shows cleaned up ledger file entries, something like: --- --- yyyy/mm/dd[ *][ CODE] description......... [ ; comment...............] --- account name 1..................... ...$amount1[ ; comment...............] --- account name 2..................... ..$-amount1[ ; comment...............] --- --- pcodewidth = no limit -- 10 --- pdescwidth = no limit -- 20 --- pacctwidth = 35 minimum, no maximum --- pamtwidth = 11 --- pcommentwidth = no limit -- 22 +{-| +Helper for the print command which shows cleaned up ledger file +entries, something like: +@ +yyyy/mm/dd[ *][ CODE] description......... [ ; comment...............] + account name 1..................... ...$amount1[ ; comment...............] + account name 2..................... ..$-amount1[ ; comment...............] + +pcodewidth = no limit -- 10 +pdescwidth = no limit -- 20 +pacctwidth = 35 minimum, no maximum +pamtwidth = 11 +pcommentwidth = no limit -- 22 +@ +-} showEntry :: LedgerEntry -> String showEntry e = unlines $ [precedingcomment ++ description] ++ (showtxns $ etransactions e) ++ [""] diff --git a/Types.hs b/Types.hs index ac7366824..97eb51496 100644 --- a/Types.hs +++ b/Types.hs @@ -1,35 +1,11 @@ +{-| +All the basic data types, defined here for easy re-use. See "Main". +-} module Types where import Utils import qualified Data.Map as Map -{- -Here is the approximate module hierarchy. The early code defined types in -each module and so was strictly layered. Now, all data types have been -moved to the bottom. The modules are still used to group related -functions/methods (" make overview " to list those). - -hledger - Options - Tests - Parse - Models - TimeLog - TimeLogEntry - Ledger - Account - Transaction - LedgerFile - LedgerEntry - LedgerTransaction - AccountName - Amount - Currency - Types - Utils - --} - -- | account and description-matching patterns type FilterPatterns = (Maybe Regex, Maybe Regex) @@ -42,14 +18,14 @@ data Currency = Currency { rate :: Double -- relative to the dollar.. 0 rates not supported yet } deriving (Eq,Show) --- | some amount of money, time, stock, oranges, etc. +-- | some amount of money, time, stock, oranges, or whatever. data Amount = Amount { currency :: Currency, quantity :: Double, - precision :: Int -- ^ number of significant decimal places + precision :: Int -- number of significant decimal places } deriving (Eq) --- AccountNames are strings like "assets:cash:petty", from which we derive +-- | AccountNames are strings like assets:cash:petty, from which we derive -- the chart of accounts type AccountName = String @@ -60,7 +36,7 @@ data LedgerTransaction = LedgerTransaction { tcomment :: String } deriving (Eq) --- | a ledger entry, with two or more balanced transactions +-- | a ledger entry, containing two or more balanced transactions data LedgerEntry = LedgerEntry { edate :: Date, estatus :: Bool, @@ -83,13 +59,14 @@ data PeriodicEntry = PeriodicEntry { p_transactions :: [LedgerTransaction] } deriving (Eq) --- | we also parse timeclock.el timelogs +-- | a timelog entry (we also parse timeclock.el timelogs) data TimeLogEntry = TimeLogEntry { tlcode :: Char, tldatetime :: DateTime, tlcomment :: String } deriving (Eq,Ord) +-- | a parsed timelog file data TimeLog = TimeLog { timelog_entries :: [TimeLogEntry] } deriving (Eq) @@ -114,9 +91,9 @@ data Transaction = Transaction { -- | cached information for a particular account data Account = Account { - aname :: AccountName, - atransactions :: [Transaction], -- ^ excludes sub-accounts - abalance :: Amount -- ^ includes sub-accounts + aname :: AccountName, -- ^ the account name + atransactions :: [Transaction], -- ^ the transactions, excluding sub-accounts + abalance :: Amount -- ^ the total balance, including sub-accounts } -- | a ledger with account information cached for faster queries diff --git a/hledger.hs b/hledger.hs index 38f01492c..c89295204 100644 --- a/hledger.hs +++ b/hledger.hs @@ -6,11 +6,37 @@ Copyright (c) 2007-2008 Simon Michael Released under GPL version 3 or later. This is a minimal haskell clone of John Wiegley's ledger -. hledger does basic -register & balance reports, and demonstrates a (naive) purely -functional implementation of ledger. +. hledger generates +simple ledger-compatible register & balance reports from a standard +ledger file, and demonstrates a (naive) purely functional +implementation of ledger. -See the "Types" module for a code overview. +Code overview: + +The early code defined types in each module and so was very strictly +layered. Since then, all data types have been moved to "Types" at the +bottom, but the original modules are still used to group related +functions/methods. Here is the approximate module hierarchy: + +@ +hledger ("Main") + "Options" + "Tests" + "Parse" + "Models" + "TimeLog" + "Ledger" + "Account" + "Transaction" + "LedgerFile" + "LedgerEntry" + "LedgerTransaction" + "AccountName" + "Amount" + "Currency" + "Types" + "Utils" +@ -} module Main