| Safe Haskell | Safe-Infered |
|---|
Penny.Lincoln
Contents
Description
Lincoln - the Penny core
Penny's core types and classes are here. This module re-exports the most useful things. For more details you will want to look at the sub-modules. Also, not all types and functions are re-exported due to naming conflicts. In particular, neither Penny.Lincoln.Predicates nor Penny.Lincoln.Queries is exported from here due to the blizzard of name conflicts that would result.
- data Balance
- unBalance :: Balance -> Map Commodity BottomLine
- data Balanced
- = Balanced
- | Inferable Entry
- | NotInferable
- isBalanced :: Balance -> Balanced
- entryToBalance :: Entry -> Balance
- addBalances :: Balance -> Balance -> Balance
- removeZeroCommodities :: Balance -> Maybe Balance
- data BottomLine
- data Column = Column DrCr Qty
- newtype SubAccountName = SubAccountName {}
- newtype Account = Account {}
- data Amount = Amount {}
- newtype Commodity = Commodity {}
- newtype SubCommodity = SubCommodity {}
- charCommodity :: Char -> Commodity
- data DateTime
- dateTime :: LocalTime -> TimeZoneOffset -> DateTime
- localTime :: DateTime -> LocalTime
- timeZone :: DateTime -> TimeZoneOffset
- data TimeZoneOffset
- minsToOffset :: Int -> Maybe TimeZoneOffset
- offsetToMins :: TimeZoneOffset -> Int
- noOffset :: TimeZoneOffset
- data DrCr
- opposite :: DrCr -> DrCr
- data Entry = Entry {}
- newtype Flag = Flag {}
- newtype MemoLine = MemoLine {}
- newtype Memo = Memo {}
- newtype Number = Number {}
- newtype Payee = Payee {}
- newtype From = From {}
- newtype To = To {}
- newtype CountPerUnit = CountPerUnit {}
- data Price
- newPrice :: From -> To -> CountPerUnit -> Maybe Price
- data PricePoint = PricePoint DateTime Price PriceMeta
- data Qty
- unQty :: Qty -> Decimal
- partialNewQty :: Decimal -> Qty
- newQty :: Decimal -> Maybe Qty
- add :: Qty -> Qty -> Qty
- subt :: Qty -> Qty -> Maybe Qty
- mult :: Qty -> Qty -> Qty
- zero :: Qty
- difference :: Qty -> Qty -> Difference
- data Difference
- = LeftBiggerBy Qty
- | RightBiggerBy Qty
- | Equal
- newtype Tag = Tag {}
- newtype Tags = Tags {}
- crashy :: Show e => Exceptional e a -> a
- account :: String -> Exceptional String Account
- data Family p c = Family p c c [c]
- data Child p c = Child c c [c] p
- data Siblings a = Siblings a a [a]
- children :: Family p c -> Siblings (Child p c)
- orphans :: Family p c -> Siblings c
- adopt :: p -> Siblings c -> Family p c
- marryWith :: (p1 -> p2 -> p3) -> (c1 -> c2 -> c3) -> Family p1 c1 -> Family p2 c2 -> Family p3 c3
- marry :: Family p1 c1 -> Family p2 c2 -> Family (p1, p2) (c1, c2)
- divorceWith :: (p1 -> (p2, p3)) -> (c1 -> (c2, c3)) -> Family p1 c1 -> (Family p2 c2, Family p3 c3)
- divorce :: Family (p1, p2) (c1, c2) -> (Family p1 c1, Family p2 c2)
- class HasText a where
- data Delimited a = Delimited Text [a]
- class HasTextList a where
- class HasTextNonEmpty a where
- textNonEmpty :: a -> TextNonEmpty
- class HasTextNonEmptyList a where
- textNonEmptyList :: a -> NonEmpty TextNonEmpty
- data TextNonEmpty = TextNonEmpty Char Text
- data Posting
- data Transaction
- data PostFam
- transaction :: Family TopLine Posting -> Exceptional Error Transaction
- data Error
- data Inferred
- = Inferred
- | NotInferred
- pPayee :: Posting -> Maybe Payee
- pNumber :: Posting -> Maybe Number
- pFlag :: Posting -> Maybe Flag
- pAccount :: Posting -> Account
- pTags :: Posting -> Tags
- pEntry :: Posting -> Entry
- pMemo :: Posting -> Memo
- pInferred :: Posting -> Inferred
- pMeta :: Posting -> PostingMeta
- changePostingMeta :: (PostingMeta -> PostingMeta) -> Transaction -> Transaction
- data TopLine
- tDateTime :: TopLine -> DateTime
- tFlag :: TopLine -> Maybe Flag
- tNumber :: TopLine -> Maybe Number
- tPayee :: TopLine -> Maybe Payee
- tMemo :: TopLine -> Memo
- tMeta :: TopLine -> TopLineMeta
- changeTransactionMeta :: (TopLineMeta -> TopLineMeta) -> Transaction -> Transaction
- postFam :: Transaction -> [PostFam]
- addSerialsToList :: (Serial -> TopLineMeta -> TopLineMeta) -> (Serial -> PostingMeta -> PostingMeta) -> [Transaction] -> [Transaction]
- addSerialsToEithers :: (Serial -> TopLineMeta -> TopLineMeta) -> (Serial -> PostingMeta -> PostingMeta) -> [Either a Transaction] -> [Either a Transaction]
- unTransaction :: Transaction -> Family TopLine Posting
- unPostFam :: PostFam -> Child TopLine Posting
- data Box m = Box {
- boxMeta :: m
- boxPostFam :: PostFam
- newtype TopLineLine = TopLineLine {
- unTopLineLine :: Int
- newtype TopMemoLine = TopMemoLine {
- unTopMemoLine :: Int
- data Side
- data SpaceBetween
- data Format = Format {
- side :: Side
- between :: SpaceBetween
- newtype Filename = Filename {
- unFilename :: Text
- newtype PriceLine = PriceLine {
- unPriceLine :: Int
- newtype PostingLine = PostingLine {
- unPostingLine :: Int
- data PriceMeta = PriceMeta {}
- newtype GlobalPosting = GlobalPosting {}
- newtype FilePosting = FilePosting {}
- newtype GlobalTransaction = GlobalTransaction {}
- newtype FileTransaction = FileTransaction {}
- data PostingMeta = PostingMeta {}
- emptyPostingMeta :: PostingMeta
- data TopLineMeta = TopLineMeta {}
- emptyTopLineMeta :: TopLineMeta
- data PriceDb
- emptyDb :: PriceDb
- addPrice :: PriceDb -> PricePoint -> PriceDb
- getPrice :: PriceDb -> From -> To -> DateTime -> Exceptional PriceDbError CountPerUnit
- data PriceDbError
- convert :: PriceDb -> DateTime -> To -> Amount -> Exceptional PriceDbError Amount
- data Serial
- forward :: Serial -> Int
- backward :: Serial -> Int
- serials :: [a] -> [Serial]
- serialItems :: (Serial -> a -> b) -> [a] -> [b]
- type Matcher = Text -> Bool
- type Factory = CaseSensitive -> Text -> Exceptional Text Matcher
Balances
A balance summarizes several entries. You do not create a Balance
directly. Instead, use entryToBalance. Balance used to be a
monoid, but there is nothing appropriate for mempty. Instead,
Balance is really a semigroup, but not a monoid.
Returned by isBalanced.
Constructors
| Balanced | |
| Inferable Entry | |
| NotInferable |
isBalanced :: Balance -> BalancedSource
Is this balance balanced?
entryToBalance :: Entry -> BalanceSource
Converts an Entry to a Balance.
addBalances :: Balance -> Balance -> BalanceSource
Add two Balances together. Commodities are never removed from the balance, even if their balance is zero. Instead, they are left in the balance. Sometimes you want to know that a commodity was in the account but its balance is now zero.
removeZeroCommodities :: Balance -> Maybe BalanceSource
Removes zero balances from a Balance. Will not return a Balance with no commodities; instead, returns Nothing if there would be a balance with no commodities.
data BottomLine Source
Instances
Bits
Accounts
newtype SubAccountName Source
Constructors
| SubAccountName | |
Fields | |
Constructors
| Account | |
Fields | |
Amounts
Commodities
Constructors
| Commodity | |
Fields | |
newtype SubCommodity Source
Constructors
| SubCommodity | |
Fields | |
charCommodity :: Char -> CommoditySource
Creates a Commodity whose name is only a single character.
DateTime
A DateTime is a UTC time that also remembers the local time from which it was set. The Eq and Ord instances will compare two DateTimes based on their equivalent UTC times.
dateTime :: LocalTime -> TimeZoneOffset -> DateTimeSource
Construct a DateTime.
data TimeZoneOffset Source
The number of minutes that this timezone is offset from UTC. Can be positive, negative, or zero.
Instances
minsToOffset :: Int -> Maybe TimeZoneOffsetSource
Convert minutes to a time zone offset. I'm having a hard time deciding whether to be liberal or strict in what to accept here. Currently it is somewhat strict in that it will fail if absolute value is greater than 840 minutes; currently the article at http:en.wikipedia.orgwikiList_of_time_zones_by_UTC_offset says there is no offset greater than 14 hours, or 840 minutes.
Debits and credits
Entries
Flag
Constructors
| Flag | |
Fields | |
Memos
Constructors
| MemoLine | |
Fields | |
Number
Constructors
| Number | |
Fields | |
Payee
Constructors
| Payee | |
Fields | |
Prices and price points
newPrice :: From -> To -> CountPerUnit -> Maybe PriceSource
Succeeds only if From and To are different commodities.
Quantities
A quantity is always greater than zero. Various odd questions happen if quantities can be zero. For instance, what if you have a debit whose quantity is zero? Does it require a balancing credit that is also zero? And how can you have a debit of zero anyway?
I can imagine situations where a quantity of zero might be useful; for instance maybe you want to specifically indicate that a particular posting in a transaction did not happen (for instance, that a paycheck deduction did not take place). I think the better way to handle that though would be through an addition to DebitCredit - maybe DebitCredit/Zero. Barring the addition of that, though, the best way to indicate a situation such as this would be through transaction memos.
Unwrap a Qty to get the underlying Decimal. This Decimal will always be greater than zero.
partialNewQty :: Decimal -> QtySource
Make a new Qty. This function is partial. It will call error if its argument is less than or equal to zero.
newQty :: Decimal -> Maybe QtySource
Make a new Qty. Returns Nothing if its argument is less than zero.
difference :: Qty -> Qty -> DifferenceSource
Subtract the second Qty from the first.
data Difference Source
Constructors
| LeftBiggerBy Qty | |
| RightBiggerBy Qty | |
| Equal |
Tags
Constructors
| Tag | |
Fields | |
Builders
crashy :: Show e => Exceptional e a -> aSource
Makes a function partial. Use if you don't want to bother dealing with the Exceptional type.
account :: String -> Exceptional String AccountSource
Create an Account. You supply a single String, with colons to separate the different sub-accounts.
Families
Family types
A Family has one parent (ah, the anomie, sorry) and at least two children.
Constructors
| Family p c c [c] |
A Child has at least one sibling and a parent.
Constructors
| Child c c [c] p |
Describes the siblings of a family, but tells you nothing about the parent. There are always at least two Siblings.
Constructors
| Siblings a a [a] |
Manipulating families
children :: Family p c -> Siblings (Child p c)Source
Gets a family's children. The Child type contains information on the parent, and each Child contains information on the other Siblings.
adopt :: p -> Siblings c -> Family p cSource
Unites a parent and some siblings into one family; the dual of orphans.
marryWith :: (p1 -> p2 -> p3) -> (c1 -> c2 -> c3) -> Family p1 c1 -> Family p2 c2 -> Family p3 c3Source
Marries two families into one. This function is rather cruel: if one family has more children than the other family, then the extra children are discarded. That is, all children must pair one-by-one.
marry :: Family p1 c1 -> Family p2 c2 -> Family (p1, p2) (c1, c2)Source
marryWith a tupling function.
divorceWith :: (p1 -> (p2, p3)) -> (c1 -> (c2, c3)) -> Family p1 c1 -> (Family p2 c2, Family p3 c3)Source
Splits up a family.
divorce :: Family (p1, p2) (c1, c2) -> (Family p1 c1, Family p2 c2)Source
divorceWith an untupling function.
HasText
Applying text to a Delimited type will give you a single Text
with the delimiter interspersed between the values of the list.
class HasTextList a whereSource
Instances
| HasTextList Account | |
| HasTextList Commodity | |
| HasTextList Memo | |
| HasTextList Tags | |
| HasText a => HasTextList [a] | |
| HasText a => HasTextList (NonEmpty a) |
class HasTextNonEmpty a whereSource
Methods
textNonEmpty :: a -> TextNonEmptySource
TextNonEmpty
data TextNonEmpty Source
Constructors
| TextNonEmpty Char Text |
Transactions
Postings and transactions
Each Transaction consists of at least two Postings.
data Transaction Source
All the Postings in a Transaction must produce a Total whose debits and credits are equal. That is, the Transaction must be balanced. No Transactions are created that are not balanced.
Instances
Making transactions
transaction :: Family TopLine Posting -> Exceptional Error TransactionSource
Makes transactions.
Errors that can arise when making a Transaction.
Constructors
| UnbalancedError | |
| CouldNotInferError |
Querying postings
Indicates whether the entry for this posting was inferred. That is, if the user did not supply an entry for this posting, then it was inferred.
Constructors
| Inferred | |
| NotInferred |
pMeta :: Posting -> PostingMetaSource
changePostingMeta :: (PostingMeta -> PostingMeta) -> Transaction -> TransactionSource
Change the metadata on a posting.
Querying transactions
The TopLine holds information that applies to all the postings in a transaction (so named because in a ledger file, this information appears on the top line.)
tMeta :: TopLine -> TopLineMetaSource
Arguments
| :: (TopLineMeta -> TopLineMeta) | Function that, when applied to the old top line meta, returns the new meta. |
| -> Transaction | The old transaction with metadata |
| -> Transaction | Transaction with new metadata |
Change the metadata on a transaction.
postFam :: Transaction -> [PostFam]Source
Get the Postings from a Transaction, with information on the sibling Postings.
Adding serials to transactions
addSerialsToList :: (Serial -> TopLineMeta -> TopLineMeta) -> (Serial -> PostingMeta -> PostingMeta) -> [Transaction] -> [Transaction]Source
addSerialsToEithers :: (Serial -> TopLineMeta -> TopLineMeta) -> (Serial -> PostingMeta -> PostingMeta) -> [Either a Transaction] -> [Either a Transaction]Source
Unwrapping Transactions
Transaction boxes
A box stores a family of transaction data along with metadata. The transaction is stored in child form, indicating a particular posting of interest. The metadata is in addition to the metadata associated with the TopLine and with each posting.
Constructors
| Box | |
Fields
| |
Metadata
Constructors
| Format | |
Fields
| |
Constructors
| Filename | |
Fields
| |
Constructors
| PriceLine | |
Fields
| |
PriceDb
The PriceDb holds information about prices. Create an empty one
using emptyDb then fill it with values using foldl or similar.
addPrice :: PriceDb -> PricePoint -> PriceDbSource
Add a single price to the PriceDb.
getPrice :: PriceDb -> From -> To -> DateTime -> Exceptional PriceDbError CountPerUnitSource
Looks up values from the PriceDb. Throws Error if something fails.
First, tries to find the best possible From match. For example, if From is LUV:2001, first tries to see if there is a From match for LUV:2001. If there is not an exact match for LUV:2001 but there is a match for LUV, then LUV is used. If there is not a match for either LUV:2001 or for LUV, then FromNotFound is thrown.
The To commodity must match exactly. So, if the TO commodity is LUV:2001, only LUV:2001 will do. If the To commodity is not found, ToNotFound is thrown.
The DateTime is the time at which to find a price. If a price exists for that exact DateTime, that price is returned. If no price exists for that exact DateTime, but there is a price for an earlier DateTime, the latest possible price is returned. If there are no earlier prices, CpuNotFound is thrown.
There is no backtracking on earlier decisions. For example, if From is LUV:2001, and there is indeed at least one From price in the PriceDb and CpuNotFound occurs, getPrice does not check to see if the computation would have succeeded had it used LUV rather than LUV:2001.
data PriceDbError Source
Getting prices can fail; if it fails, an Error is returned.
Constructors
| FromNotFound | |
| ToNotFound | |
| CpuNotFound |
convert :: PriceDb -> DateTime -> To -> Amount -> Exceptional PriceDbError AmountSource
Given an Amount and a Commodity to convert the amount to,
converts the Amount to the given commodity. If the Amount given is
already in the To commodity, simply returns what was passed in. Can
fail and throw PriceDbError. Internally uses getPrice, so read its
documentation for details on how price lookup works.
Serials
A type for serial numbers, used widely for different purposes throughout Penny.
serials :: [a] -> [Serial]Source
Applied to a list of items, return a list of Serials usable to identify the list of items.
serialItems :: (Serial -> a -> b) -> [a] -> [b]Source
Label a list of items with serials.
Matchers
Arguments
| = CaseSensitive | Will this matcher be case sensitive? |
| -> Text | The pattern to use when testing for a match. For example, this might be a regular expression, or simply the text to be matched. |
| -> Exceptional Text Matcher | Sometimes producing a matcher might fail; for example, the user might have supplied a bad pattern. If so, an exception is returned. On success, a Matcher is returned. |
A function that makes Matchers.