Hledger.Read.JournalReader

A reader for hledger's journal file format (http://hledger.org/MANUAL.html#the-journal-file). hledger's journal format is a compatible subset of c++ ledger's (http://ledger-cli.org/3.0/doc/ledger3.html#Journal-Format), so this reader should handle many ledger files as well. Example:

2012/3/24 gift
    expenses:gifts  $10
    assets:cash

Journal format supports the include directive which can read files in other formats, so the other file format readers need to be importable and invocable here.

Some important parts of journal parsing are therefore kept in Hledger.Read.Common, to avoid import cycles.

Reader-finding utils

findReader :: MonadIO m => Maybe StorageFormat -> Maybe FilePath -> Maybe (Reader m)

findReader mformat mpath

Find the reader named by mformat, if provided. Or, if a file path is provided, find the first reader that handles its file extension, if any.

splitReaderPrefix :: PrefixedFilePath -> (Maybe String, FilePath)

If a filepath is prefixed by one of the reader names and a colon, split that off. Eg "csv:-" -> (Just "csv", "-").

Reader

reader :: MonadIO m => Reader m

Parsing utils

parseAndFinaliseJournal :: ErroringJournalParser IO ParsedJournal -> InputOpts -> FilePath -> Text -> ExceptT String IO Journal

Given a parser to ParsedJournal, input options, file path and content: run the parser on the content, and finalise the result to get a Journal; or throw an error.

runJournalParser :: Monad m => JournalParser m a -> Text -> m (Either HledgerParseErrors a)

Run a journal parser in some monad. See also: parseWithState.

rjp :: Monad m => JournalParser m a -> Text -> m (Either HledgerParseErrors a)

Run a journal parser in some monad. See also: parseWithState.

runErroringJournalParser :: Monad m => ErroringJournalParser m a -> Text -> m (Either FinalParseError (Either HledgerParseErrors a))

Run an erroring journal parser in some monad. See also: parseWithState.

rejp :: Monad m => ErroringJournalParser m a -> Text -> m (Either FinalParseError (Either HledgerParseErrors a))

Run an erroring journal parser in some monad. See also: parseWithState.

Parsers used elsewhere

getParentAccount :: JournalParser m AccountName

journalp :: MonadIO m => ErroringJournalParser m ParsedJournal

A journal parser. Accumulates and returns a ParsedJournal, which should be finalised/validated before use.

>>> rejp (journalp <* eof) "2015/1/1\n a  0\n"
Right (Right Journal  with 1 transactions, 1 accounts)

directivep :: MonadIO m => ErroringJournalParser m ()

Parse any journal directive and update the parse state accordingly. Cf http://hledger.org/manual.html#directives, http://ledger-cli.org/3.0/doc/ledger3.html#Command-Directives

defaultyeardirectivep :: JournalParser m ()

marketpricedirectivep :: JournalParser m PriceDirective

datetimep :: JournalParser m LocalTime

Parse a date and time in YYYY-MM-DD HH:MM[:SS][+-ZZZZ] format. Slash (/) and period (.) are also allowed as date separators. The year may be omitted if a default year has been set. Seconds are optional. The timezone is optional and ignored (the time is always interpreted as a local time). Leading zeroes may be omitted (except in a timezone).

datep :: JournalParser m Day

Parse a date in YYYY-MM-DD format. Slash (/) and period (.) are also allowed as separators. The year may be omitted if a default year has been set. Leading zeroes may be omitted.

modifiedaccountnamep :: JournalParser m AccountName

Parse an account name (plus one following space if present), then apply any parent account prefix and/or account aliases currently in effect, in that order. (Ie first add the parent account prefix, then rewrite with aliases). This calls error if any account alias with an invalid regular expression exists.

tmpostingrulep :: Maybe Year -> JournalParser m TMPostingRule

statusp :: TextParser m Status

emptyorcommentlinep :: TextParser m ()

A blank or comment line in journal format: a line that's empty or containing only whitespace or whose first non-whitespace character is semicolon, hash, or star.

followingcommentp :: TextParser m Text

Parse the text of a (possibly multiline) comment following a journal item.

>>> rtp followingcommentp ""   -- no comment
Right ""
>>> rtp followingcommentp ";"    -- just a (empty) same-line comment. newline is added
Right "\n"
>>> rtp followingcommentp ";  \n"
Right "\n"
>>> rtp followingcommentp ";\n ;\n"  -- a same-line and a next-line comment
Right "\n\n"
>>> rtp followingcommentp "\n ;\n"  -- just a next-line comment. Insert an empty same-line comment so the next-line comment doesn't become a same-line comment.
Right "\n\n"

accountaliasp :: TextParser m AccountAlias

Tests

tests_JournalReader :: TestTree