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

Safe Haskell | None
Language | Haskell2010

Hledger.Read.Common

Contents

- parsing utilities
- parsers
  - transaction bits
  - dates
  - account names
  - amounts
  - comments
  - bracketed dates
  - misc
- tests

Description

Some common parsers and helpers used by several readers. Some of these might belong in Hledger.Read.JournalReader or Hledger.Read.

Synopsis

- data Reader = Reader {
  - rFormat :: StorageFormat
  - rExtensions :: [String]
  - rParser :: InputOpts -> FilePath -> Text -> ExceptT String IO Journal
  - rExperimental :: Bool
  }
- data InputOpts = InputOpts {
  - mformat_ :: Maybe StorageFormat
  - mrules_file_ :: Maybe FilePath
  - separator_ :: Char
  - aliases_ :: [String]
  - anon_ :: Bool
  - ignore_assertions_ :: Bool
  - new_ :: Bool
  - new_save_ :: Bool
  - pivot_ :: String
  - auto_ :: Bool
  }
- definputopts :: InputOpts
- rawOptsToInputOpts :: RawOpts -> InputOpts
- runTextParser :: TextParser Identity a -> Text -> Either (ParseErrorBundle Text CustomErr) a
- rtp :: TextParser Identity a -> Text -> Either (ParseErrorBundle Text CustomErr) a
- runJournalParser :: Monad m => JournalParser m a -> Text -> m (Either (ParseErrorBundle Text CustomErr) a)
- rjp :: Monad m => JournalParser m a -> Text -> m (Either (ParseErrorBundle Text CustomErr) a)
- runErroringJournalParser :: Monad m => ErroringJournalParser m a -> Text -> m (Either FinalParseError (Either (ParseErrorBundle Text CustomErr) a))
- rejp :: Monad m => ErroringJournalParser m a -> Text -> m (Either FinalParseError (Either (ParseErrorBundle Text CustomErr) a))
- genericSourcePos :: SourcePos -> GenericSourcePos
- journalSourcePos :: SourcePos -> SourcePos -> GenericSourcePos
- applyTransactionModifiers :: Journal -> Journal
- parseAndFinaliseJournal :: ErroringJournalParser IO ParsedJournal -> InputOpts -> FilePath -> Text -> ExceptT String IO Journal
- parseAndFinaliseJournal' :: JournalParser IO ParsedJournal -> InputOpts -> FilePath -> Text -> ExceptT String IO Journal
- setYear :: Year -> JournalParser m ()
- getYear :: JournalParser m (Maybe Year)
- setDefaultCommodityAndStyle :: (CommoditySymbol, AmountStyle) -> JournalParser m ()
- getDefaultCommodityAndStyle :: JournalParser m (Maybe (CommoditySymbol, AmountStyle))
- getDefaultAmountStyle :: JournalParser m (Maybe AmountStyle)
- getAmountStyle :: CommoditySymbol -> JournalParser m (Maybe AmountStyle)
- pushDeclaredAccount :: AccountName -> JournalParser m ()
- addDeclaredAccountType :: AccountName -> AccountType -> JournalParser m ()
- pushParentAccount :: AccountName -> JournalParser m ()
- popParentAccount :: JournalParser m ()
- getParentAccount :: JournalParser m AccountName
- addAccountAlias :: MonadState Journal m => AccountAlias -> m ()
- getAccountAliases :: MonadState Journal m => m [AccountAlias]
- clearAccountAliases :: MonadState Journal m => m ()
- journalAddFile :: (FilePath, Text) -> Journal -> Journal
- statusp :: TextParser m Status
- codep :: TextParser m Text
- descriptionp :: TextParser m Text
- datep :: JournalParser m Day
- datetimep :: JournalParser m LocalTime
- secondarydatep :: Day -> TextParser m Day
- modifiedaccountnamep :: JournalParser m AccountName
- accountnamep :: TextParser m AccountName
- spaceandamountormissingp :: JournalParser m MixedAmount
- amountp :: JournalParser m Amount
- amountp' :: String -> Amount
- mamountp' :: String -> MixedAmount
- commoditysymbolp :: TextParser m CommoditySymbol
- priceamountp :: JournalParser m Price
- balanceassertionp :: JournalParser m BalanceAssertion
- fixedlotpricep :: JournalParser m (Maybe Amount)
- numberp :: Maybe AmountStyle -> TextParser m (Quantity, Int, Maybe Char, Maybe DigitGroupStyle)
- fromRawNumber :: RawNumber -> Maybe Int -> Either String (Quantity, Int, Maybe Char, Maybe DigitGroupStyle)
- rawnumberp :: TextParser m (Either AmbiguousNumber RawNumber)
- multilinecommentp :: TextParser m ()
- emptyorcommentlinep :: TextParser m ()
- followingcommentp :: TextParser m Text
- transactioncommentp :: TextParser m (Text, [Tag])
- postingcommentp :: Maybe Year -> TextParser m (Text, [Tag], Maybe Day, Maybe Day)
- bracketeddatetagsp :: Maybe Year -> TextParser m [(TagName, Day)]
- singlespacedtextp :: TextParser m Text
- singlespacedtextsatisfyingp :: (Char -> Bool) -> TextParser m Text
- singlespacep :: TextParser m ()
- tests_Common :: Test ()

# Documentation

data Reader Source #

A hledger journal reader is a triple of storage format name, a detector of that format, and a parser from that format to Journal.

Constructors

Reader |

Fields

- rFormat :: StorageFormat
- rExtensions :: [String]
- rParser :: InputOpts -> FilePath -> Text -> ExceptT String IO Journal
- rExperimental :: Bool

Instances

Show Reader Source # |
Instance details Defined in Hledger.Read.Common Methods showsPrec :: Int -> Reader -> ShowS Source # show :: Reader -> String Source # showList :: [Reader] -> ShowS Source #

data InputOpts Source #

Various options to use when reading journal files. Similar to CliOptions.inputflags, simplifies the journal-reading functions.

Constructors

InputOpts |

Fields

- mformat_ :: Maybe StorageFormat

  a file/storage format to try, unless overridden by a filename prefix. Nothing means try all.

- mrules_file_ :: Maybe FilePath

  a conversion rules file to use (when reading CSV)

- separator_ :: Char

  the separator to use (when reading CSV)

- aliases_ :: [String]

  account name aliases to apply

- anon_ :: Bool

  do light anonymisation/obfuscation of the data

- ignore_assertions_ :: Bool

  don't check balance assertions

- new_ :: Bool

  read only new transactions since this file was last read

- new_save_ :: Bool

  save latest new transactions state for next time

- pivot_ :: String

  use the given field's value as the account name

- auto_ :: Bool

  generate automatic postings when journal is parsed

Instances

Data InputOpts Source # |

Instance details

Defined in Hledger.Read.Common

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> InputOpts -> c InputOpts Source #

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c InputOpts Source #

toConstr :: InputOpts -> Constr Source #

dataTypeOf :: InputOpts -> DataType Source #

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c InputOpts) Source #

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c InputOpts) Source #

gmapT :: (forall b. Data b => b -> b) -> InputOpts -> InputOpts Source #

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> InputOpts -> r Source #

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> InputOpts -> r Source #

gmapQ :: (forall d. Data d => d -> u) -> InputOpts -> [u] Source #

gmapQi :: Int -> (forall d. Data d => d -> u) -> InputOpts -> u Source #

gmapM :: Monad m => (forall d. Data d => d -> m d) -> InputOpts -> m InputOpts Source #

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> InputOpts -> m InputOpts Source #

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> InputOpts -> m InputOpts Source #

Show InputOpts Source # |
Instance details Defined in Hledger.Read.Common Methods showsPrec :: Int -> InputOpts -> ShowS Source # show :: InputOpts -> String Source # showList :: [InputOpts] -> ShowS Source #
Default InputOpts Source # |
Instance details Defined in Hledger.Read.Common Methods def :: InputOpts #

definputopts :: InputOpts Source #

rawOptsToInputOpts :: RawOpts -> InputOpts Source #

# parsing utilities

runTextParser :: TextParser Identity a -> Text -> Either (ParseErrorBundle Text CustomErr) a Source #

Run a text parser in the identity monad. See also: parseWithState.

rtp :: TextParser Identity a -> Text -> Either (ParseErrorBundle Text CustomErr) a Source #

Run a text parser in the identity monad. See also: parseWithState.

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

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

rjp :: Monad m => JournalParser m a -> Text -> m (Either (ParseErrorBundle Text CustomErr) a) Source #

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

runErroringJournalParser :: Monad m => ErroringJournalParser m a -> Text -> m (Either FinalParseError (Either (ParseErrorBundle Text CustomErr) a)) Source #

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

rejp :: Monad m => ErroringJournalParser m a -> Text -> m (Either FinalParseError (Either (ParseErrorBundle Text CustomErr) a)) Source #

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

genericSourcePos :: SourcePos -> GenericSourcePos Source #

journalSourcePos :: SourcePos -> SourcePos -> GenericSourcePos Source #

Construct a generic start & end line parse position from start and end megaparsec SourcePos's.

applyTransactionModifiers :: Journal -> Journal Source #

Apply any transaction modifier rules in the journal (adding automated postings to transactions, eg).

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

Given a megaparsec ParsedJournal parser, input options, file path and file content: parse and post-process a Journal, or give an error.

parseAndFinaliseJournal' :: JournalParser IO ParsedJournal -> InputOpts -> FilePath -> Text -> ExceptT String IO Journal Source #

setYear :: Year -> JournalParser m () Source #

getYear :: JournalParser m (Maybe Year) Source #

setDefaultCommodityAndStyle :: (CommoditySymbol, AmountStyle) -> JournalParser m () Source #

getDefaultCommodityAndStyle :: JournalParser m (Maybe (CommoditySymbol, AmountStyle)) Source #

getDefaultAmountStyle :: JournalParser m (Maybe AmountStyle) Source #

Get amount style associated with default currency.

Returns `AmountStyle` used to defined by a latest default commodity directive prior to current position within this file or its parents.

getAmountStyle :: CommoditySymbol -> JournalParser m (Maybe AmountStyle) Source #

Lookup currency-specific amount style.

Returns `AmountStyle` used in commodity directive within current journal prior to current position or in its parents files.

pushDeclaredAccount :: AccountName -> JournalParser m () Source #

addDeclaredAccountType :: AccountName -> AccountType -> JournalParser m () Source #

pushParentAccount :: AccountName -> JournalParser m () Source #

popParentAccount :: JournalParser m () Source #

getParentAccount :: JournalParser m AccountName Source #

addAccountAlias :: MonadState Journal m => AccountAlias -> m () Source #

getAccountAliases :: MonadState Journal m => m [AccountAlias] Source #

clearAccountAliases :: MonadState Journal m => m () Source #

journalAddFile :: (FilePath, Text) -> Journal -> Journal Source #

# parsers

## transaction bits

statusp :: TextParser m Status Source #

codep :: TextParser m Text Source #

descriptionp :: TextParser m Text Source #

## dates

datep :: JournalParser m Day Source #

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

datetimep :: JournalParser m LocalTime Source #

Parse a date and time in YYYYMMDD HH:MM[:SS][+-ZZZZ] format. Hyphen (-) 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).

secondarydatep :: Day -> TextParser m Day Source #

## account names

modifiedaccountnamep :: JournalParser m AccountName Source #

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

accountnamep :: TextParser m AccountName Source #

Parse an account name, plus one following space if present. Account names have one or more parts separated by the account separator character, and are terminated by two or more spaces (or end of input). Each part is at least one character long, may have single spaces inside it, and starts with a non-whitespace. Note, this means "{account}", "%^!" and ";comment" are all accepted (parent parsers usually prevent/consume the last). It should have required parts to start with an alphanumeric; for now it remains as-is for backwards compatibility.

## amounts

spaceandamountormissingp :: JournalParser m MixedAmount Source #

Parse whitespace then an amount, with an optional left or right currency symbol and optional price, or return the special "missing" marker amount.

amountp :: JournalParser 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.

commoditysymbolp :: TextParser m CommoditySymbol Source #

priceamountp :: JournalParser m Price Source #

balanceassertionp :: JournalParser m BalanceAssertion Source #

fixedlotpricep :: JournalParser m (Maybe Amount) Source #

numberp :: Maybe AmountStyle -> TextParser 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.

fromRawNumber :: RawNumber -> Maybe Int -> Either String (Quantity, Int, Maybe Char, Maybe DigitGroupStyle) Source #

Interpret a raw number as a decimal number.

Returns: - the decimal number - the precision (number of digits after the decimal point) - the decimal point character, if any - the digit group style, if any (digit group character and sizes of digit groups)

rawnumberp :: TextParser m (Either AmbiguousNumber RawNumber) Source #

Parse and interpret the structure of a number without external hints. Numbers are digit strings, possibly separated into digit groups by one of two types of separators. (1) Numbers may optionally have a decimal point, which may be either a period or comma. (2) Numbers may optionally contain digit group separators, which must all be either a period, a comma, or a space.

It is our task to deduce the identities of the decimal point and digit separator characters, based on the allowed syntax. For instance, we make use of the fact that a decimal point can occur at most once and must succeed all digit group separators.

    >>> parseTest rawnumberp "1,234,567.89"
    Right (WithSeparators ',' ["1","234","567"] (Just ('.',"89")))
    >>> parseTest rawnumberp "1,000"
    Left (AmbiguousNumber "1" ',' "000")
    >>> parseTest rawnumberp "1 000"
    Right (WithSeparators ' ' ["1","000"] Nothing)

## comments

multilinecommentp :: TextParser m () Source #

emptyorcommentlinep :: TextParser m () Source #

followingcommentp :: TextParser m Text Source #

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"

transactioncommentp :: TextParser m (Text, [Tag]) Source #

Parse a transaction comment and extract its tags.

The first line of a transaction may be followed by comments, which begin with semicolons and extend to the end of the line. Transaction comments may span multiple lines, but comment lines below the transaction must be preceeded by leading whitespace.

200011 ; a transaction comment starting on the same line ... ; extending to the next line account1 $1 account2

Tags are name-value pairs.

    >>> let getTags (_,tags) = tags
    >>> let parseTags = fmap getTags . rtp transactioncommentp

    >>> parseTags "; name1: val1, name2:all this is value2"
    Right [("name1","val1"),("name2","all this is value2")]

A tag's name must be immediately followed by a colon, without separating whitespace. The corresponding value consists of all the text following the colon up until the next colon or newline, stripped of leading and trailing whitespace.

postingcommentp :: Maybe Year -> TextParser m (Text, [Tag], Maybe Day, Maybe Day) Source #

Parse a posting comment and extract its tags and dates.

Postings may be followed by comments, which begin with semicolons and extend to the end of the line. Posting comments may span multiple lines, but comment lines below the posting must be preceeded by leading whitespace.

200011 account1 $1 ; a posting comment starting on the same line ... ; extending to the next line

account2 ; a posting comment beginning on the next line

Tags are name-value pairs.

    >>> let getTags (_,tags,_,_) = tags
    >>> let parseTags = fmap getTags . rtp (postingcommentp Nothing)

    >>> parseTags "; name1: val1, name2:all this is value2"
    Right [("name1","val1"),("name2","all this is value2")]

A tag's name must be immediately followed by a colon, without separating whitespace. The corresponding value consists of all the text following the colon up until the next colon or newline, stripped of leading and trailing whitespace.

Posting dates may be expressed with "date"/"date2" tags or with bracketed date syntax. Posting dates will inherit their year from the transaction date if the year is not specified. We throw parse errors on invalid dates.

    >>> let getDates (_,_,d1,d2) = (d1, d2)
    >>> let parseDates = fmap getDates . rtp (postingcommentp (Just 2000))

    >>> parseDates "; date: 1/2, date2: 1999/12/31"
    Right (Just 2000-01-02,Just 1999-12-31)
    >>> parseDates "; [1/2=1999/12/31]"
    Right (Just 2000-01-02,Just 1999-12-31)

Example: tags, date tags, and bracketed dates >>> rtp (postingcommentp (Just 2000)) "; a:b, date:34, [=56]" Right ("a:b, date:34, [=56]n",[("a","b"),("date","3/4")],Just 2000-03-04,Just 2000-05-06)

Example: extraction of dates from date tags ignores trailing text >>> rtp (postingcommentp (Just 2000)) "; date:34=56" Right ("date:34=56n",[("date","34=56")],Just 2000-03-04,Nothing)

## bracketed dates

bracketeddatetagsp :: Maybe Year -> TextParser m [(TagName, Day)] Source #

Parse Ledger-style bracketed posting dates ([DATE=DATE2]), as "date" and/or "date2" tags. Anything that looks like an attempt at this (a square-bracketed sequence of 0123456789/-.= containing at least one digit and one date separator) is also parsed, and will throw an appropriate error.

The dates are parsed in full here so that errors are reported in the right position. A missing year in DATE can be inferred if a default date is provided. A missing year in DATE2 will be inferred from DATE.

    >>> either (Left . customErrorBundlePretty) Right $ rtp (bracketeddatetagsp Nothing) "[2016/1/2=3/4]"
    Right [("date",2016-01-02),("date2",2016-03-04)]

    >>> either (Left . customErrorBundlePretty) Right $ rtp (bracketeddatetagsp Nothing) "[1]"
    Left ...not a bracketed date...

    >>> either (Left . customErrorBundlePretty) Right $ rtp (bracketeddatetagsp Nothing) "[2016/1/32]"
    Left ...1:2:...well-formed but invalid date: 2016/1/32...

    >>> either (Left . customErrorBundlePretty) Right $ rtp (bracketeddatetagsp Nothing) "[1/31]"
    Left ...1:2:...partial date 1/31 found, but the current year is unknown...

    >>> either (Left . customErrorBundlePretty) Right $ rtp (bracketeddatetagsp Nothing) "[0123456789/-.=/-.=]"
    Left ...1:13:...expecting month or day...

## misc

singlespacedtextp :: TextParser m Text Source #

Parse any text beginning with a non-whitespace character, until a double space or the end of input.

singlespacedtextsatisfyingp :: (Char -> Bool) -> TextParser m Text Source #

Similar to `singlespacedtextp`, except that the text must only contain characters satisfying the given predicate.

singlespacep :: TextParser m () Source #

Parse one non-newline whitespace character that is not followed by another one.

# tests

tests_Common :: Test () Source #