Hledger.Read

This is the entry point to hledger's reading system, which can read Journals from various data formats. Use this module if you want to parse journal data or read journal files. Generally it should not be necessary to import modules below this one.

Documentation

module Hledger.Read.Common

readFormatNames :: [StorageFormat]

Journal reading API

defaultJournalPath :: IO String

Get the default journal file path specified by the environment. Like ledger, we look first for the LEDGER_FILE environment variable, and if that does not exist, for the legacy LEDGER environment variable. If neither is set, or the value is blank, return the hard-coded default, which is .hledger.journal in the users's home directory (or in the current directory, if we cannot determine a home directory).

defaultJournal :: IO Journal

Read the default journal file specified by the environment, or raise an error.

readJournal :: Maybe StorageFormat -> Maybe FilePath -> Bool -> Maybe FilePath -> Text -> IO (Either String Journal)

Read a journal from this string, trying whatever readers seem appropriate:

• if a format is specified, try that reader only
• or if one or more readers recognises the file path and data, try those
• otherwise, try them all.

A CSV conversion rules file may also be specified for use by the CSV reader. Also there is a flag specifying whether to check or ignore balance assertions in the journal.

readJournal' :: Text -> IO Journal

Read a journal from the given text, trying all known formats, or simply throw an error.

readJournalFile :: Maybe StorageFormat -> Maybe FilePath -> Bool -> FilePath -> IO (Either String Journal)

Read a Journal from this file (or stdin if the filename is -) or give an error message, using the specified data format or trying all known formats. A CSV conversion rules file may be specified for better conversion of that format. Also there is a flag specifying whether to check or ignore balance assertions in the journal.

readJournalFiles :: Maybe StorageFormat -> Maybe FilePath -> Bool -> [FilePath] -> IO (Either String Journal)

Call readJournalFile on each specified file path, and combine the resulting journals into one. If there are any errors, the first is returned, otherwise they are combined per Journal's monoid instance (concatenated, basically). Parse context (eg directives & aliases) is not maintained across file boundaries, it resets at the start of each file (though the rfinal parse state saved in the resulting journal is the combination of parse states from all files).

requireJournalFileExists :: FilePath -> IO ()

If the specified journal file does not exist, give a helpful error and quit.

ensureJournalFileExists :: FilePath -> IO ()

Ensure there is a journal file at the given path, creating an empty one if needed.

Parsers used elsewhere

postingp :: Maybe Day -> ErroringJournalParser Posting

accountaliasp :: TextParser m AccountAlias

Tests

samplejournal :: IO Journal

tests_Hledger_Read :: Test