feat: journal: tag directive declares tag names

hledger-lib/Hledger/Data/Journal.hs

@@ -66,6 +66,9 @@ module Hledger.Data.Journal (
   journalPayeesDeclared,
   journalPayeesUsed,
   journalPayeesDeclaredOrUsed,
+  journalTagsDeclared,
+  journalTagsUsed,
+  journalTagsDeclaredOrUsed,
   journalCommoditiesDeclared,
   journalCommodities,
   journalDateSpan,
@@ -217,6 +220,7 @@ journalConcat j1 j2 =
     ,jparsetimeclockentries     = jparsetimeclockentries     j1 <> jparsetimeclockentries     j2
     ,jincludefilestack          = jincludefilestack j2
     ,jdeclaredpayees            = jdeclaredpayees            j1 <> jdeclaredpayees            j2
+    ,jdeclaredtags              = jdeclaredtags              j1 <> jdeclaredtags              j2
     ,jdeclaredaccounts          = jdeclaredaccounts          j1 <> jdeclaredaccounts          j2
     ,jdeclaredaccounttags       = jdeclaredaccounttags       j1 <> jdeclaredaccounttags       j2
     ,jdeclaredaccounttypes      = jdeclaredaccounttypes      j1 <> jdeclaredaccounttypes      j2
@@ -275,6 +279,7 @@ nulljournal = Journal {
   ,jparsetimeclockentries     = []
   ,jincludefilestack          = []
   ,jdeclaredpayees            = []
+  ,jdeclaredtags              = []
   ,jdeclaredaccounts          = []
   ,jdeclaredaccounttags       = M.empty
   ,jdeclaredaccounttypes      = M.empty
@@ -356,6 +361,20 @@ journalPayeesDeclaredOrUsed :: Journal -> [Payee]
 journalPayeesDeclaredOrUsed j = toList $ foldMap S.fromList
     [journalPayeesDeclared j, journalPayeesUsed j]
 
+-- | Sorted unique tag names declared by tag directives in this journal.
+journalTagsDeclared :: Journal -> [TagName]
+journalTagsDeclared = nubSort . map fst . jdeclaredtags
+
+-- | Sorted unique tag names used in this journal (in account directives, transactions, postings..)
+journalTagsUsed :: Journal -> [TagName]
+journalTagsUsed j = nubSort $ map fst $ concatMap transactionAllTags $ jtxns j
+  -- tags used in all transactions and postings and postings' accounts
+
+-- | Sorted unique tag names used in transactions or declared by tag directives in this journal.
+journalTagsDeclaredOrUsed :: Journal -> [TagName]
+journalTagsDeclaredOrUsed j = toList $ foldMap S.fromList
+    [journalTagsDeclared j, journalTagsUsed j]
+
 -- | Sorted unique account names posted to by this journal's transactions.
 journalAccountNamesUsed :: Journal -> [AccountName]
 journalAccountNamesUsed = accountNamesFromPostings . journalPostings

hledger-lib/Hledger/Data/Json.hs

@@ -133,6 +133,7 @@ instance ToJSON AccountType
 instance ToJSONKey AccountType
 instance ToJSON AccountDeclarationInfo
 instance ToJSON PayeeDeclarationInfo
+instance ToJSON TagDeclarationInfo
 instance ToJSON Commodity
 instance ToJSON TimeclockCode
 instance ToJSON TimeclockEntry

hledger-lib/Hledger/Data/Types.hs

@@ -529,6 +529,7 @@ data Journal = Journal {
   ,jincludefilestack      :: [FilePath]
   -- principal data
   ,jdeclaredpayees        :: [(Payee,PayeeDeclarationInfo)]         -- ^ Payees declared by payee directives, in parse order (after journal finalisation)
+  ,jdeclaredtags          :: [(TagName,TagDeclarationInfo)]         -- ^ Tags declared by tag directives, in parse order (after journal finalisation)
   ,jdeclaredaccounts      :: [(AccountName,AccountDeclarationInfo)] -- ^ Accounts declared by account directives, in parse order (after journal finalisation)
   ,jdeclaredaccounttags   :: M.Map AccountName [Tag]                -- ^ Accounts which have tags declared in their directives, and those tags. (Does not include parents' tags.)
   ,jdeclaredaccounttypes  :: M.Map AccountType [AccountName]        -- ^ Accounts whose type has been explicitly declared in their account directives, grouped by type.
@@ -571,6 +572,15 @@ nullpayeedeclarationinfo = PayeeDeclarationInfo {
   ,pditags             = []
 }
 
+-- | Extra information found in a tag directive.
+data TagDeclarationInfo = TagDeclarationInfo {
+   tdicomment :: Text   -- ^ any comment lines following the tag directive
+} deriving (Eq,Show,Generic)
+
+nulltagdeclarationinfo = TagDeclarationInfo {
+   tdicomment          = ""
+}
+
 -- | Extra information about an account that can be derived from
 -- its account directive (and the other account directives).
 data AccountDeclarationInfo = AccountDeclarationInfo {

hledger/hledger.m4.md

@@ -2339,7 +2339,9 @@ in another commodity. See [Valuation](#valuation).
 
 ## `payee` directive
 
-The `payee` directive can be used to declare a limited set of payees which may appear in [transaction descriptions](#descriptions).
+`payee PAYEE NAME`
+
+This directive can be used to declare a limited set of payees which may appear in [transaction descriptions](#descriptions).
 The ["payees" check](#check) will report an error if any transaction refers to a payee that has not been declared.
 Eg:
 
@@ -2349,6 +2351,18 @@ payee Whole Foods
 
 Any indented subdirectives are currently ignored.
 
+## `tag` directive
+
+`tag TAGNAME`
+
+This directive can be used to declare a limited set of tag names allowed in [tags](#tags).
+TAGNAME should be a valid tag name (no spaces). Eg:
+
+```journal
+tag  item-id
+```
+Any indented subdirectives are currently ignored.
+
 ## Periodic transactions
 
 The `~` directive declares recurring transactions.