hledger-lib-1.30: A reusable library providing the core functionality of hledger

Safe Haskell | Safe-Inferred
Language | Haskell2010

Hledger.Read

Contents

- Journal files
- Journal parsing
- Easy journal parsing
- Re-exported
- Tests

Description

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.

Synopsis

- type PrefixedFilePath = FilePath
- defaultJournal :: IO Journal
- defaultJournalPath :: IO String
- requireJournalFileExists :: FilePath -> IO ()
- ensureJournalFileExists :: FilePath -> IO ()
- readJournal :: InputOpts -> Maybe FilePath -> Text -> ExceptT String IO Journal
- readJournalFile :: InputOpts -> PrefixedFilePath -> ExceptT String IO Journal
- readJournalFiles :: InputOpts -> [PrefixedFilePath] -> ExceptT String IO Journal
- runExceptT :: ExceptT e m a -> m (Either e a)
- readJournal' :: Text -> IO Journal
- readJournalFile' :: PrefixedFilePath -> IO Journal
- readJournalFiles' :: [PrefixedFilePath] -> IO Journal
- orDieTrying :: MonadIO m => ExceptT String m a -> m a
- tmpostingrulep :: Maybe Year -> JournalParser m TMPostingRule
- findReader :: MonadIO m => Maybe StorageFormat -> Maybe FilePath -> Maybe (Reader m)
- splitReaderPrefix :: PrefixedFilePath -> (Maybe String, FilePath)
- runJournalParser :: Monad m => JournalParser m a -> Text -> m (Either HledgerParseErrors a)
- module Hledger.Read.Common
- module Hledger.Read.InputOptions
- tests_Read :: TestTree

# Journal files

type PrefixedFilePath = FilePath Source #

A file path optionally prefixed by a reader name and colon (journal:, csv:, timedot:, etc.).

defaultJournal :: IO Journal Source #

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

defaultJournalPath :: IO String Source #

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).

requireJournalFileExists :: FilePath -> IO () Source #

If the specified journal file does not exist (and is not "-"), give a helpful error and quit.

ensureJournalFileExists :: FilePath -> IO () Source #

Ensure there is a journal file at the given path, creating an empty one if needed. On Windows, also ensure that the path contains no trailing dots which could cause data loss (see `isWindowsUnsafeDotPath`).

# Journal parsing

readJournal :: InputOpts -> Maybe FilePath -> Text -> ExceptT String IO Journal Source #

    readJournal iopts mfile txt

Read a Journal from some text, or return an error message.

The reader (data format) is chosen based on, in this order:

- a reader name provided in `iopts`
- a reader prefix in the `mfile` path
- a file extension in `mfile`

If none of these is available, or if the reader name is unrecognised, we use the journal reader. (We used to try all readers in this case; since hledger 1.17, we prefer predictability.)

readJournalFile :: InputOpts -> PrefixedFilePath -> ExceptT String IO Journal Source #

Read a Journal from this file, or from stdin if the file path is -, or return an error message. The file path can have a READER: prefix.

The reader (data format) to use is determined from (in priority order): the `mformat_` specified in the input options, if any; the file path's READER: prefix, if any; a recognised file name extension. if none of these identify a known reader, the journal reader is used.

The input options can also configure balance assertion checking, automated posting generation, a rules file for converting CSV data, etc.

readJournalFiles :: InputOpts -> [PrefixedFilePath] -> ExceptT String IO Journal Source #

Read a Journal from each specified file path and combine them into one. Or, return the first error message.

Combining Journals means concatenating them, basically. The parse state resets at the start of each file, which means that directives & aliases do not affect subsequent sibling or parent files. They do affect included child files though. Also the final parse state saved in the Journal does span all files.

runExceptT :: ExceptT e m a -> m (Either e a) Source #

The inverse of `ExceptT`.

# Easy journal parsing

readJournal' :: Text -> IO Journal Source #

An easy version of `readJournal` which assumes default options, and fails in the IO monad.

readJournalFile' :: PrefixedFilePath -> IO Journal Source #

An easy version of `readJournalFile` which assumes default options, and fails in the IO monad.

readJournalFiles' :: [PrefixedFilePath] -> IO Journal Source #

An easy version of `readJournalFiles'` which assumes default options, and fails in the IO monad.

orDieTrying :: MonadIO m => ExceptT String m a -> m a Source #

Extract ExceptT to the IO monad, failing with an error message if necessary.

# Re-exported

tmpostingrulep :: Maybe Year -> JournalParser m TMPostingRule Source #

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

    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) Source #

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

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

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

module Hledger.Read.Common

module Hledger.Read.InputOptions

# Tests

tests_Read :: TestTree Source #