hledger-lib-1.3: Core data types, parsers and functionality for the hledger accounting tools

Safe Haskell | None
Language | Haskell2010

Hledger.Read

Contents

- Journal files
- 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
- readJournalFiles :: Maybe StorageFormat -> Maybe FilePath -> Bool -> [PrefixedFilePath] -> IO (Either String Journal)
- readJournalFile :: Maybe StorageFormat -> Maybe FilePath -> Bool -> PrefixedFilePath -> IO (Either String Journal)
- requireJournalFileExists :: FilePath -> IO ()
- ensureJournalFileExists :: FilePath -> IO ()
- splitReaderPrefix :: PrefixedFilePath -> (Maybe String, FilePath)
- readJournal :: Maybe StorageFormat -> Maybe FilePath -> Bool -> Maybe FilePath -> Text -> IO (Either String Journal)
- readJournal' :: Text -> IO Journal
- accountaliasp :: TextParser m AccountAlias
- postingp :: MonadIO m => Maybe Day -> ErroringJournalParser m Posting
- module Hledger.Read.Common
- samplejournal :: IO Journal
- tests_Hledger_Read :: Test

# Journal files

type PrefixedFilePath = FilePath #

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

defaultJournal :: IO Journal #

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

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

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

    readJournalFiles mformat mrulesfile assrt prefixedfiles

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 cross file boundaries. (The final parse state saved in the Journal does span all files, however.)

As with readJournalFile, file paths can optionally have a READER: prefix, and the `mformat`, `mrulesfile, and` assrt@ arguments are supported (and these are applied to all files).

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

    readJournalFile mformat mrulesfile assrt prefixedfile

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) is chosen based on (in priority order): the `mformat` argument; the file path's READER: prefix, if any; a recognised file name extension (in readJournal); if none of these identify a known reader, all built-in readers are tried in turn.

A CSV conversion rules file (`mrulesfiles`) can be specified to help convert CSV data.

Optionally, any balance assertions in the journal can be checked (`assrt`).

requireJournalFileExists :: FilePath -> IO () #

If the specified journal file does not exist (and is not "-"), 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.

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

# Journal parsing

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

    readJournal mformat mrulesfile assrt mfile txt

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

The reader (data format) is chosen based on (in priority order): the `mformat` argument; a recognised file name extension in `mfile` (if provided). If none of these identify a known reader, all built-in readers are tried in turn (returning the first one's error message if none of them succeed).

A CSV conversion rules file (`mrulesfiles`) can be specified to help convert CSV data.

Optionally, any balance assertions in the journal can be checked (`assrt`).

readJournal' :: Text -> IO Journal #

Read a Journal from the given text trying all readers in turn, or throw an error.

# Re-exported

accountaliasp :: TextParser m AccountAlias #

postingp :: MonadIO m => Maybe Day -> ErroringJournalParser m Posting #

module Hledger.Read.Common

# Tests

samplejournal :: IO Journal #

tests_Hledger_Read :: Test #