Safe Haskell	None
Language	Haskell2010

Hledger.Data.Dates

Contents

Misc date handling utilities
Orphan instances

Description

Date parsing and utilities for hledger.

For date and time values, we use the standard Day and UTCTime types.

A SmartDate is a date which may be partially-specified or relative. Eg 2008/12/31, but also 2008/12, 12/31, tomorrow, last week, next year. We represent these as a triple of strings like ("2008","12",""), ("","","tomorrow"), ("","last","week").

A DateSpan is the span of time between two specific calendar dates, or an open-ended span where one or both dates are unspecified. (A date span with both ends unspecified matches all dates.)

An Interval is ledger's "reporting interval" - weekly, monthly, quarterly, etc.

Period will probably replace DateSpan in due course.

Synopsis

getCurrentDay :: IO Day
getCurrentMonth :: IO Int
getCurrentYear :: IO Integer
nulldate :: Day
spanContainsDate :: DateSpan -> Day -> Bool
periodContainsDate :: Period -> Day -> Bool
parsedateM :: String -> Maybe Day
parsedate :: String -> Day
showDate :: Day -> String
showDateSpan :: DateSpan -> String
showDateSpanMonthAbbrev :: DateSpan -> String
elapsedSeconds :: Fractional a => UTCTime -> UTCTime -> a
prevday :: Day -> Day
periodexprp :: Day -> TextParser m (Interval, DateSpan)
parsePeriodExpr :: Day -> Text -> Either (ParseErrorBundle Text CustomErr) (Interval, DateSpan)
parsePeriodExpr' :: Day -> Text -> (Interval, DateSpan)
nulldatespan :: DateSpan
emptydatespan :: DateSpan
failIfInvalidYear :: Monad m => String -> m ()
failIfInvalidMonth :: Monad m => String -> m ()
failIfInvalidDay :: Monad m => String -> m ()
datesepchar :: TextParser m Char
datesepchars :: [Char]
isDateSepChar :: Char -> Bool
spanStart :: DateSpan -> Maybe Day
spanEnd :: DateSpan -> Maybe Day
spansSpan :: [DateSpan] -> DateSpan
spanIntersect :: DateSpan -> DateSpan -> DateSpan
spansIntersect :: [DateSpan] -> DateSpan
spanIntervalIntersect :: Interval -> DateSpan -> DateSpan -> DateSpan
spanDefaultsFrom :: DateSpan -> DateSpan -> DateSpan
spanUnion :: DateSpan -> DateSpan -> DateSpan
spansUnion :: [DateSpan] -> DateSpan
smartdate :: TextParser m SmartDate
splitSpan :: Interval -> DateSpan -> [DateSpan]
fixSmartDate :: Day -> SmartDate -> Day
fixSmartDateStr :: Day -> Text -> String
fixSmartDateStrEither :: Day -> Text -> Either (ParseErrorBundle Text CustomErr) String
fixSmartDateStrEither' :: Day -> Text -> Either (ParseErrorBundle Text CustomErr) Day
daysInSpan :: DateSpan -> Maybe Integer
maybePeriod :: Day -> Text -> Maybe (Interval, DateSpan)
mkdatespan :: String -> String -> DateSpan

Misc date handling utilities

getCurrentDay :: IO Day Source #

Get the current local date.

getCurrentMonth :: IO Int Source #

Get the current local month number.

getCurrentYear :: IO Integer Source #

Get the current local year.

nulldate :: Day Source #

spanContainsDate :: DateSpan -> Day -> Bool Source #

Does the span include the given date ?

periodContainsDate :: Period -> Day -> Bool Source #

Does the period include the given date ? (Here to avoid import cycle).

parsedateM :: String -> Maybe Day Source #

Parse a couple of date string formats to a time type.

parsedate :: String -> Day Source #

Parse a YYYY-MM-DD or YYYYMMDD date string to a Day, or raise an error. For testing/debugging.

>>> parsedate "2008/02/03"
2008-02-03

showDate :: Day -> String Source #

showDateSpan :: DateSpan -> String Source #

Render a datespan as a display string, abbreviating into a compact form if possible.

showDateSpanMonthAbbrev :: DateSpan -> String Source #

Like showDateSpan, but show month spans as just the abbreviated month name in the current locale.

elapsedSeconds :: Fractional a => UTCTime -> UTCTime -> a Source #

prevday :: Day -> Day Source #

periodexprp :: Day -> TextParser m (Interval, DateSpan) Source #

>>> let p = parsePeriodExpr (parsedate "2008/11/26")
>>> p "from Aug to Oct"
Right (NoInterval,DateSpan 2008/08/01-2008/09/30)
>>> p "aug to oct"
Right (NoInterval,DateSpan 2008/08/01-2008/09/30)
>>> p "every 3 days in Aug"
Right (Days 3,DateSpan 2008/08)
>>> p "daily from aug"
Right (Days 1,DateSpan 2008/08/01-)
>>> p "every week to 2009"
Right (Weeks 1,DateSpan -2008/12/31)
>>> p "every 2nd day of month"
Right (DayOfMonth 2,DateSpan -)
>>> p "every 2nd day"
Right (DayOfMonth 2,DateSpan -)
>>> p "every 2nd day 2009-"
Right (DayOfMonth 2,DateSpan 2009/01/01-)  
>>> p "every 29th Nov"
Right (DayOfYear 11 29,DateSpan -)
>>> p "every 29th nov -2009"
Right (DayOfYear 11 29,DateSpan -2008/12/31)
>>> p "every nov 29th"
Right (DayOfYear 11 29,DateSpan -)
>>> p "every Nov 29th 2009-"
Right (DayOfYear 11 29,DateSpan 2009/01/01-)
>>> p "every 11/29 from 2009"
Right (DayOfYear 11 29,DateSpan 2009/01/01-)
>>> p "every 2nd Thursday of month to 2009"
Right (WeekdayOfMonth 2 4,DateSpan -2008/12/31)
>>> p "every 1st monday of month to 2009"
Right (WeekdayOfMonth 1 1,DateSpan -2008/12/31)
>>> p "every tue"
Right (DayOfWeek 2,DateSpan -)
>>> p "every 2nd day of week"
Right (DayOfWeek 2,DateSpan -)
>>> p "every 2nd day of month"
Right (DayOfMonth 2,DateSpan -)
>>> p "every 2nd day"
Right (DayOfMonth 2,DateSpan -)
>>> p "every 2nd day 2009-"
Right (DayOfMonth 2,DateSpan 2009/01/01-)
>>> p "every 2nd day of month 2009-"
Right (DayOfMonth 2,DateSpan 2009/01/01-)

parsePeriodExpr :: Day -> Text -> Either (ParseErrorBundle Text CustomErr) (Interval, DateSpan) Source #

Parse a period expression to an Interval and overall DateSpan using the provided reference date, or return a parse error.

parsePeriodExpr' :: Day -> Text -> (Interval, DateSpan) Source #

Like parsePeriodExpr, but call error' on failure.

nulldatespan :: DateSpan Source #

emptydatespan :: DateSpan Source #

A datespan of zero length, that matches no date.

failIfInvalidYear :: Monad m => String -> m () Source #

failIfInvalidMonth :: Monad m => String -> m () Source #

failIfInvalidDay :: Monad m => String -> m () Source #

datesepchar :: TextParser m Char Source #

datesepchars :: [Char] Source #

isDateSepChar :: Char -> Bool Source #

spanStart :: DateSpan -> Maybe Day Source #

spanEnd :: DateSpan -> Maybe Day Source #

spansSpan :: [DateSpan] -> DateSpan Source #

Get overall span enclosing multiple sequentially ordered spans.

spanIntersect :: DateSpan -> DateSpan -> DateSpan Source #

Calculate the intersection of two datespans.

For non-intersecting spans, gives an empty span beginning on the second's start date: >>> mkdatespan "2018-01-01" "2018-01-03" spanIntersect mkdatespan "2018-01-03" "2018-01-05" DateSpan 20180103-20180102

spansIntersect :: [DateSpan] -> DateSpan Source #

Calculate the intersection of a number of datespans.

spanIntervalIntersect :: Interval -> DateSpan -> DateSpan -> DateSpan Source #

Calculate the intersection of two DateSpans, adjusting the start date so the interval is preserved.

>>> let intervalIntersect = spanIntervalIntersect (Days 3)
>>> mkdatespan "2018-01-01" "2018-01-03" `intervalIntersect` mkdatespan "2018-01-01" "2018-01-05"
DateSpan 2018/01/01-2018/01/02
>>> mkdatespan "2018-01-01" "2018-01-05" `intervalIntersect` mkdatespan "2018-01-02" "2018-01-05"
DateSpan 2018/01/04
>>> mkdatespan "2018-01-01" "2018-01-05" `intervalIntersect` mkdatespan "2018-01-03" "2018-01-05"
DateSpan 2018/01/04
>>> mkdatespan "2018-01-01" "2018-01-05" `intervalIntersect` mkdatespan "2018-01-04" "2018-01-05"
DateSpan 2018/01/04
>>> mkdatespan "2018-01-01" "2018-01-05" `intervalIntersect` mkdatespan "2017-12-01" "2018-01-05"
DateSpan 2018/01/01-2018/01/04

spanDefaultsFrom :: DateSpan -> DateSpan -> DateSpan Source #

Fill any unspecified dates in the first span with the dates from the second one. Sort of a one-way spanIntersect.

spanUnion :: DateSpan -> DateSpan -> DateSpan Source #

Calculate the union of two datespans.

spansUnion :: [DateSpan] -> DateSpan Source #

Calculate the union of a number of datespans.

smartdate :: TextParser m SmartDate Source #

Parse a date in any of the formats allowed in Ledger's period expressions, and some others. Assumes any text in the parse stream has been lowercased. Returns a SmartDate, to be converted to a full date later (see fixSmartDate).

Examples:

2004                                        (start of year, which must have 4+ digits)
2004/10                                     (start of month, which must be 1-12)
2004/10/1                                   (exact date, day must be 1-31)
10/1                                        (month and day in current year)
21                                          (day in current month)
october, oct                                (start of month in current year)
yesterday, today, tomorrow                  (-1, 0, 1 days from today)
last/this/next day/week/month/quarter/year  (-1, 0, 1 periods from the current period)
20181201                                    (8 digit YYYYMMDD with valid year month and day)
201812                                      (6 digit YYYYMM with valid year and month)

Note malformed digit sequences might give surprising results:

201813                                      (6 digits with an invalid month is parsed as start of 6-digit year)
20181301                                    (8 digits with an invalid month is parsed as start of 8-digit year)
20181232                                    (8 digits with an invalid day gives an error)
201801012                                   (9+ digits beginning with a valid YYYYMMDD gives an error)

Eg:

YYYYMMDD is parsed as year-month-date if those parts are valid (>=4 digits, 1-12, and 1-31 respectively): >>> parsewith (smartdate <* eof) "20181201" Right ("2018","12","01")

YYYYMM is parsed as year-month-01 if year and month are valid: >>> parsewith (smartdate <* eof) "201804" Right ("2018","04","01")

With an invalid month, it's parsed as a year: >>> parsewith (smartdate <* eof) "201813" Right ("201813","","")

A 9+ digit number beginning with valid YYYYMMDD gives an error: >>> parsewith (smartdate <* eof) "201801012" Left (...)

Big numbers not beginning with a valid YYYYMMDD are parsed as a year: >>> parsewith (smartdate <* eof) "201813012" Right ("201813012","","")

splitSpan :: Interval -> DateSpan -> [DateSpan] Source #

Split a DateSpan into consecutive whole spans of the specified interval which fully encompass the original span (and a little more when necessary). If no interval is specified, the original span is returned. If the original span is the null date span, ie unbounded, the null date span is returned. If the original span is empty, eg if the end date is <= the start date, no spans are returned.

Examples:

>>> let t i d1 d2 = splitSpan i $ mkdatespan d1 d2
>>> t NoInterval "2008/01/01" "2009/01/01"
[DateSpan 2008]
>>> t (Quarters 1) "2008/01/01" "2009/01/01"
[DateSpan 2008q1,DateSpan 2008q2,DateSpan 2008q3,DateSpan 2008q4]
>>> splitSpan (Quarters 1) nulldatespan
[DateSpan -]
>>> t (Days 1) "2008/01/01" "2008/01/01"  -- an empty datespan
[]
>>> t (Quarters 1) "2008/01/01" "2008/01/01"
[]
>>> t (Months 1) "2008/01/01" "2008/04/01"
[DateSpan 2008/01,DateSpan 2008/02,DateSpan 2008/03]
>>> t (Months 2) "2008/01/01" "2008/04/01"
[DateSpan 2008/01/01-2008/02/29,DateSpan 2008/03/01-2008/04/30]
>>> t (Weeks 1) "2008/01/01" "2008/01/15"
[DateSpan 2007/12/31w01,DateSpan 2008/01/07w02,DateSpan 2008/01/14w03]
>>> t (Weeks 2) "2008/01/01" "2008/01/15"
[DateSpan 2007/12/31-2008/01/13,DateSpan 2008/01/14-2008/01/27]
>>> t (DayOfMonth 2) "2008/01/01" "2008/04/01"
[DateSpan 2007/12/02-2008/01/01,DateSpan 2008/01/02-2008/02/01,DateSpan 2008/02/02-2008/03/01,DateSpan 2008/03/02-2008/04/01]
>>> t (WeekdayOfMonth 2 4) "2011/01/01" "2011/02/15"
[DateSpan 2010/12/09-2011/01/12,DateSpan 2011/01/13-2011/02/09,DateSpan 2011/02/10-2011/03/09]
>>> t (DayOfWeek 2) "2011/01/01" "2011/01/15"
[DateSpan 2010/12/28-2011/01/03,DateSpan 2011/01/04-2011/01/10,DateSpan 2011/01/11-2011/01/17]
>>> t (DayOfYear 11 29) "2011/10/01" "2011/10/15"
[DateSpan 2010/11/29-2011/11/28]
>>> t (DayOfYear 11 29) "2011/12/01" "2012/12/15"
[DateSpan 2011/11/29-2012/11/28,DateSpan 2012/11/29-2013/11/28]

fixSmartDate :: Day -> SmartDate -> Day Source #

Convert a SmartDate to an absolute date using the provided reference date.

Examples:

>>> :set -XOverloadedStrings
>>> let t = fixSmartDateStr (parsedate "2008/11/26")
>>> t "0000-01-01"
"0000/01/01"
>>> t "1999-12-02"
"1999/12/02"
>>> t "1999.12.02"
"1999/12/02"
>>> t "1999/3/2"
"1999/03/02"
>>> t "19990302"
"1999/03/02"
>>> t "2008/2"
"2008/02/01"
>>> t "0020/2"
"0020/02/01"
>>> t "1000"
"1000/01/01"
>>> t "4/2"
"2008/04/02"
>>> t "2"
"2008/11/02"
>>> t "January"
"2008/01/01"
>>> t "feb"
"2008/02/01"
>>> t "today"
"2008/11/26"
>>> t "yesterday"
"2008/11/25"
>>> t "tomorrow"
"2008/11/27"
>>> t "this day"
"2008/11/26"
>>> t "last day"
"2008/11/25"
>>> t "next day"
"2008/11/27"
>>> t "this week"  -- last monday
"2008/11/24"
>>> t "last week"  -- previous monday
"2008/11/17"
>>> t "next week"  -- next monday
"2008/12/01"
>>> t "this month"
"2008/11/01"
>>> t "last month"
"2008/10/01"
>>> t "next month"
"2008/12/01"
>>> t "this quarter"
"2008/10/01"
>>> t "last quarter"
"2008/07/01"
>>> t "next quarter"
"2009/01/01"
>>> t "this year"
"2008/01/01"
>>> t "last year"
"2007/01/01"
>>> t "next year"
"2009/01/01"

t "last wed" "20081119" t "next friday" "20081128" t "next january" "20090101"

fixSmartDateStr :: Day -> Text -> String Source #

Convert a smart date string to an explicit yyyy/mm/dd string using the provided reference date, or raise an error.

fixSmartDateStrEither :: Day -> Text -> Either (ParseErrorBundle Text CustomErr) String Source #

A safe version of fixSmartDateStr.

fixSmartDateStrEither' :: Day -> Text -> Either (ParseErrorBundle Text CustomErr) Day Source #

daysInSpan :: DateSpan -> Maybe Integer Source #

Count the days in a DateSpan, or if it is open-ended return Nothing.

maybePeriod :: Day -> Text -> Maybe (Interval, DateSpan) Source #

mkdatespan :: String -> String -> DateSpan Source #

Make a datespan from two valid date strings parseable by parsedate (or raise an error). Eg: mkdatespan "201111" "20111231".

Orphan instances

Show DateSpan Source #
Instance details Methods showsPrec :: Int -> DateSpan -> ShowS # show :: DateSpan -> String # showList :: [DateSpan] -> ShowS #