hledger-lib-0.26: Core data types, parsers and utilities for the hledger accounting tool.

Safe Haskell | None
Language | Haskell2010

Hledger.Read

Contents

- Journal reading API
- Parsers used elsewhere
- 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

- defaultJournalPath :: IO String
- defaultJournal :: IO Journal
- readJournal :: Maybe StorageFormat -> Maybe FilePath -> Bool -> Maybe FilePath -> String -> IO (Either String Journal)
- readJournal' :: String -> IO Journal
- readJournalFile :: Maybe StorageFormat -> Maybe FilePath -> Bool -> FilePath -> IO (Either String Journal)
- readJournalFiles :: Maybe StorageFormat -> Maybe FilePath -> Bool -> [FilePath] -> IO (Either String Journal)
- requireJournalFileExists :: FilePath -> IO ()
- ensureJournalFileExists :: FilePath -> IO ()
- postingp :: Stream [Char] m Char => ParsecT [Char] JournalContext m Posting
- accountnamep :: Stream [Char] m Char => ParsecT [Char] st m AccountName
- amountp :: Stream [Char] m t => ParsecT [Char] JournalContext m Amount
- amountp' :: String -> Amount
- mamountp' :: String -> MixedAmount
- numberp :: Stream [Char] m t => ParsecT [Char] JournalContext m (Quantity, Int, Maybe Char, Maybe DigitGroupStyle)
- codep :: Stream [Char] m Char => ParsecT [Char] JournalContext m String
- accountaliasp :: Stream [Char] m Char => ParsecT [Char] st m AccountAlias
- samplejournal :: IO Journal
- tests_Hledger_Read :: Test

# Journal reading API

defaultJournalPath :: IO String Source

All the data formats we can read. formats = map rFormat readers

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 Source

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

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

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' :: String -> IO Journal Source

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

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

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

requireJournalFileExists :: FilePath -> IO () Source

If the specified journal file does not exist, 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.

# Parsers used elsewhere

postingp :: Stream [Char] m Char => ParsecT [Char] JournalContext m Posting Source

accountnamep :: Stream [Char] m Char => ParsecT [Char] st m AccountName Source

Parse an account name. Account names start with a non-space, may have single spaces inside them, and are terminated by two or more spaces (or end of input). Also they have one or more components of at least one character, separated by the account separator char. (This parser will also consume one following space, if present.)

amountp :: Stream [Char] m t => ParsecT [Char] JournalContext m Amount Source

Parse a single-commodity amount, with optional symbol on the left or right, optional unit or total price, and optional (ignored) ledger-style balance assertion or fixed lot price declaration.

amountp' :: String -> Amount Source

Parse an amount from a string, or get an error.

mamountp' :: String -> MixedAmount Source

Parse a mixed amount from a string, or get an error.

numberp :: Stream [Char] m t => ParsecT [Char] JournalContext m (Quantity, Int, Maybe Char, Maybe DigitGroupStyle) Source

Parse a string representation of a number for its value and display attributes.

Some international number formats are accepted, eg either period or comma may be used for the decimal point, and the other of these may be used for separating digit groups in the integer part. See http://en.wikipedia.org/wiki/Decimal_separator for more examples.

This returns: the parsed numeric value, the precision (number of digits seen following the decimal point), the decimal point character used if any, and the digit group style if any.

codep :: Stream [Char] m Char => ParsecT [Char] JournalContext m String Source

accountaliasp :: Stream [Char] m Char => ParsecT [Char] st m AccountAlias Source

# Tests

samplejournal :: IO Journal Source

tests_Hledger_Read :: Test Source