Hledger.Query · hledger-lib-1.52.4

Query and QueryOpt

6 declarations

datadata Query

#

A query is a composition of search criteria, which can be used to match postings, transactions, accounts and more.

Constructors

Any
always match
None
never match data queries (in "standard" order, roughly as they appear in a transaction)
Date DateSpan
match primary dates in this date span
Date2 DateSpan
match secondary dates in this date span
StatusQ Status
match this txn/posting status
Code Regexp
match txn codes infix-matched by this regexp
Desc Regexp
match txn descriptions infix-matched by this regexp
Tag Regexp (Maybe Regexp)
match if a tag's name, and optionally its value, is infix-matched by the respective regexps
Acct Regexp
match account names infix-matched by this regexp
Type [AccountType]
match accounts whose type is one of these (or with no types, any account)
Depth Int
match if account depth is less than or equal to this value (or, sometimes used as a display option)
DepthAcct Regexp Int
match if the account matches and account depth is less than or equal to this value (usually used as a display option)
Real Bool
match postings with this "realness" value
Amt OrdPlus Quantity
match if the amount's numeric quantity is less thangreater thanequal to/unsignedly equal to some value
Sym Regexp
match if the commodity symbol is fully-matched by this regexp compound queries (expr:)
Not Query
negate this match
And [Query]
match if all of these match
Or [Query]
match if any of these match compound queries for transactions (any:, all:) If used in a non transaction-matching context, these are equivalent to And.
AnyPosting [Query]
match if any one posting is matched by all of these
AllPostings [Query]
match if all of one or more postings are matched by all of these

Instances3Eq, Show, Default

Eq QueryDefined in hledger-lib-1.52.4 · Hledger.Query
Show QueryDefined in hledger-lib-1.52.4 · Hledger.Query
Default QueryDefined in hledger-lib-1.52.4 · Hledger.Query

datadata QueryOpt

#

A query option changes a query's/report's behaviour and output in some way.

Constructors

QueryOptInAcctOnly AccountName
show an account register focussed on this account
QueryOptInAcct AccountName
as above but include sub-accounts in the account register
QueryOptInterval Interval
report interval extracted from a date: query | QueryOptCostBasis -- ^ show amounts converted to cost where possible | QueryOptDate2 -- ^ show secondary dates instead of primary dates

Instances2Eq, Show

Eq QueryOptDefined in hledger-lib-1.52.4 · Hledger.Query
Show QueryOptDefined in hledger-lib-1.52.4 · Hledger.Query

datadata OrdPlus

#

A more expressive Ord, used for amt: queries. The Abs* variants compare with the absolute value of a number, ignoring sign.

Lt LtEq Gt GtEq Eq AbsLt AbsLtEq AbsGt AbsGtEq AbsEq

Instances2Eq, Show

Eq OrdPlusDefined in hledger-lib-1.52.4 · Hledger.Query
Show OrdPlusDefined in hledger-lib-1.52.4 · Hledger.Query

valuepayeeTag :: Maybe Text -> Either RegexError Query

#

Construct a query for the payee: tag

valuenoteTag :: Maybe Text -> Either RegexError Query

#

Construct a query for the note: tag

valuegeneratedTransactionTag :: Query

#

Construct a query for the generated-transaction: tag

parsing

5 declarations

valueparseQuery :: Day -> Text -> Either String (Query, [QueryOpt])

#

A version of parseQueryList which acts on a single Text of space-separated terms.

The usual shell quoting rules are assumed. When a pattern contains whitespace, it (or the whole term including prefix) should be enclosed in single or double quotes.

A query term is either:

a search pattern, which matches on one or more fields, eg:
acct:REGEXP - match the account name with a regular expression desc:REGEXP - match the transaction description date:PERIODEXP - match the date with a period expression

The prefix indicates the field to match, or if there is no prefix account name is assumed.

a query option, which modifies the reporting behaviour in some way. There is currently one of these, which may appear only once:
inacct:FULLACCTNAME

Period expressions may contain relative dates, so a reference date is required to fully parse these.

Example1 expression

>>> parseQuery nulldate "expenses:dining out"Right (Or [Acct (RegexpCI "expenses:dining"),Acct (RegexpCI "out")],[])

Example1 expression

>>> parseQuery nulldate "\"expenses:dining out\""Right (Acct (RegexpCI "expenses:dining out"),[])

valueparseQueryList :: Day -> [Text] -> Either String (Query, [QueryOpt])

#

Convert a list of space-separated queries to a single query

Multiple terms are combined as follows: 1. multiple account patterns are OR'd together 2. multiple description patterns are OR'd together 3. multiple status patterns are OR'd together 4. then all terms are AND'd together

valueparseQueryTerm :: Day -> Text -> Either String (Query, [QueryOpt])

#

Parse a single query term as either a query or a query option, or return an error message if parsing fails.

valueparseAccountType :: Bool -> Text -> Either String AccountType

#

Case-insensitively parse one single-letter code, or one long-form word if permitted, to an account type. On failure, returns the unparseable text.

valueparseDepthSpec :: Text -> Either RegexError DepthSpec

#

modifying

4 declarations

valuesimplifyQuery :: Query -> Query

#

valuefilterQuery :: (Query -> Bool) -> Query -> Query

#

Remove query terms (or whole sub-expressions) from this query which do not match the given predicate. XXX Semantics not completely clear. Also calls simplifyQuery on the result.

valuefilterQueryOrNotQuery :: (Query -> Bool) -> Query -> Query

#

Remove query terms (or whole sub-expressions) from this query which match neither the given predicate nor that predicate negated (eg, if predicate is queryIsAcct, this will keep both "acct:" and "not:acct:" terms). Also calls simplifyQuery on the result. (Since 1.24.1, might be merged into filterQuery in future.) XXX Semantics not completely clear.

valuematchesQuery :: (Query -> Bool) -> Query -> Bool

#

Does this simple query predicate match any part of this possibly compound query ?

predicates

17 declarations

valuequeryIsNull :: Query -> Bool

#

Does this query match everything ?

valuequeryIsDate :: Query -> Bool

#

Is this a simple query of this type (date:) ? Does not match a compound query involving andornot. Likewise for the following functions.

valuequeryIsDate2 :: Query -> Bool

#

valuequeryIsDateOrDate2 :: Query -> Bool

#

valuequeryIsStatus :: Query -> Bool

#

valuequeryIsCode :: Query -> Bool

#

valuequeryIsDesc :: Query -> Bool

#

valuequeryIsTag :: Query -> Bool

#

valuequeryIsAcct :: Query -> Bool

#

valuequeryIsType :: Query -> Bool

#

valuequeryIsDepth :: Query -> Bool

#

valuequeryIsReal :: Query -> Bool

#

valuequeryIsAmt :: Query -> Bool

#

valuequeryIsSym :: Query -> Bool

#

valuequeryIsAmtOrSym :: Query -> Bool

#

valuequeryIsStartDateOnly :: Bool -> Query -> Bool

#

Does this query specify a start date and nothing else (that would filter postings prior to the date) ? When the flag is true, look for a starting secondary date instead.

valuequeryIsTransactionRelated :: Query -> Bool

#

Does this query involve a property of transactions (or their postings), making it inapplicable to account declarations ?

accessors

7 declarations

valuequeryStartDate :: Bool -> Query -> Maybe Day

#

What start date (or secondary date) does this query specify, if any ? For OR expressions, use the earliest of the dates. NOT is ignored.

valuequeryEndDate :: Bool -> Query -> Maybe Day

#

What end date (or secondary date) does this query specify, if any ? For OR expressions, use the latest of the dates. NOT is ignored.

valuequeryDateSpan :: Bool -> Query -> DateSpan

#

What date span (or with a true argument, what secondary date span) does this query specify ? OR clauses specifying multiple spans return their union (the span enclosing all of them). AND clauses specifying multiple spans return their intersection. NOT clauses are ignored.

valuequeryDateSpan' :: Query -> DateSpan

#

What date span does this query specify, treating primary and secondary dates as equivalent ? OR clauses specifying multiple spans return their union (the span enclosing all of them). AND clauses specifying multiple spans return their intersection. NOT clauses are ignored.

valuequeryDepth :: Query -> DepthSpec

#

The depth limit this query specifies, if it has one

valueinAccount :: [QueryOpt] -> Maybe (AccountName, Bool)

#

The account we are currently focussed on, if any, and whether subaccounts are included. Just looks at the first query option.

valueinAccountQuery :: [QueryOpt] -> Maybe Query

#

A query for the account(s) we are currently focussed on, if any. Just looks at the first query option.

matching things with queries

15 declarations

valuematchesTransaction :: Query -> Transaction -> Bool

#

Does the match expression match this transaction ?

valuematchesTransactionExtra

#

Like matchesTransaction, but if the journal's account types are provided, any type: terms in the query must match at least one posting's account type (and any negated type: terms must match none).

valuematchesDescription :: Query -> Text -> Bool

#

Does the query match this transaction description ? Non-desc: query terms are ignored (this might disrupt some boolean queries).

valuematchesPayeeWIP :: Query -> Payee -> Bool

#

Does the query match this transaction payee ? Tests desc: (and payee: ?) terms, any other terms are ignored. XXX Currently an alias for matchDescription. I'm not sure if more is needed, There's some shenanigan with payee: and "payeeTag" to figure out.

valuematchesPosting :: Query -> Posting -> Bool

#

Does the match expression match this posting ? When matching account name, and the posting has been transformed in some way, we will match either the original or transformed name.

valuematchesPostingExtra

#

Like matchesPosting, but if the posting's account's type is provided, any type: terms in the query must match it (and any negated type: terms must not match it).

valuematchesAccount :: Query -> AccountName -> Bool

#

Does the query match this account name ? A matching in: clause is also considered a match.

valuematchesAccountExtra

#

Like matchesAccount, but with optional extra matching features:

If the account's type is provided, any type: terms in the query must match it (and any negated type: terms must not match it).
If the account's tags are provided, any tag: terms must match at least one of them (and any negated tag: terms must match none).

valuematchesMixedAmount :: Query -> MixedAmount -> Bool

#

valuematchesAmount :: Query -> Amount -> Bool

#

Does the match expression match this (simple) amount ?

valuematchesCommodity :: Query -> CommoditySymbol -> Bool

#

valuematchesTag :: Query -> Tag -> Bool

#

Does the query match the name and optionally the value of this tag ? Non-tag: query terms are ignored (this might disrupt some boolean queries).

valuematchesPriceDirective :: Query -> PriceDirective -> Bool

#

Does the query match this market price ?

valuewords'' :: [Text] -> Text -> [Text]

#

Quote-and-prefix-aware version of words - don't split on spaces which are inside quotes, including quotes which may have one of the specified prefixes in front, and maybe an additional not: prefix in front of that.

valuequeryprefixes :: [Text]

#

tests

1 declaration

valuetests_Query :: TestTree

#