slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

dev:Journal: cleanup, improve docs

Browse Source
This commit is contained in:
Simon Michael 2024-11-02 15:53:37 -10:00
parent 445e80fd41
commit a58948c7a8
2 changed files with 38 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
hledger-lib/Hledger/Data/Journal.hs
View File

@ -204,9 +204,9 @@ journalDbg j@Journal{..} = chomp $ unlines $
,"jdeclaredaccounttags: " <> shw jdeclaredaccounttags ,"jdeclaredaccounttags: " <> shw jdeclaredaccounttags
,"jdeclaredaccounttypes: " <> shw jdeclaredaccounttypes ,"jdeclaredaccounttypes: " <> shw jdeclaredaccounttypes
,"jaccounttypes: " <> shw jaccounttypes ,"jaccounttypes: " <> shw jaccounttypes
,"jdeclaredcommodities: " <> shw jdeclaredcommodities
,"jinferredcommoditystyles: " <> shw jinferredcommoditystyles
,"jglobalcommoditystyles: " <> shw jglobalcommoditystyles ,"jglobalcommoditystyles: " <> shw jglobalcommoditystyles
,"jdeclaredcommodities: " <> shw jdeclaredcommodities
,"jinferredcommoditystyles: " <> shw jinferredcommoditystyles
,"jpricedirectives: " <> shw jpricedirectives ,"jpricedirectives: " <> shw jpricedirectives
,"jinferredmarketprices: " <> shw jinferredmarketprices ,"jinferredmarketprices: " <> shw jinferredmarketprices
,"jtxnmodifiers: " <> shw jtxnmodifiers ,"jtxnmodifiers: " <> shw jtxnmodifiers

73
hledger-lib/Hledger/Data/Types.hs
View File

@ -569,48 +569,47 @@ data MarketPrice = MarketPrice {
-- additional valuation-related types in Valuation.hs -- additional valuation-related types in Valuation.hs
-- | A Journal, containing transactions and various other things. -- | A journal, containing general ledger transactions; also directives and various other things.
-- The basic data model for hledger. -- This is hledger's main data model.
-- --
-- This is used during parsing (as the type alias ParsedJournal), and -- During parsing, it is used as the type alias "ParsedJournal".
-- then finalised/validated for use as a Journal. Some extra -- The jparse* fields are mainly used during parsing and included here for convenience.
-- parsing-related fields are included for convenience, at least for -- The list fields described as "in parse order" are usually reversed for efficiency during parsing.
-- now. In a ParsedJournal these are updated as parsing proceeds, in a -- After parsing, "journalFinalise" converts ParsedJournal to a finalised "Journal",
-- Journal they represent the final state at end of parsing (used eg -- which has all lists correctly ordered, and much data inference and validation applied.
-- by the add command).
-- --
data Journal = Journal { data Journal = Journal {
-- parsing-related data -- parsing-related state
jparsedefaultyear :: Maybe Year -- ^ the current default year, specified by the most recent Y directive (or current date) jparsedefaultyear :: Maybe Year -- ^ the current default year, specified by the most recent Y directive (or current date)
,jparsedefaultcommodity :: Maybe (CommoditySymbol,AmountStyle) -- ^ the current default commodity and its format, specified by the most recent D directive ,jparsedefaultcommodity :: Maybe (CommoditySymbol,AmountStyle) -- ^ the current default commodity and its format, specified by the most recent D directive
,jparsedecimalmark :: Maybe DecimalMark -- ^ the character to always parse as decimal point, if set by CsvReader's decimal-mark (or a future journal directive) ,jparsedecimalmark :: Maybe DecimalMark -- ^ the character to always parse as decimal point, if set by CsvReader's decimal-mark (or a future journal directive)
,jparseparentaccounts :: [AccountName] -- ^ the current stack of parent account names, specified by apply account directives ,jparseparentaccounts :: [AccountName] -- ^ the current stack of parent account names, specified by apply account directives
,jparsealiases :: [AccountAlias] -- ^ the current account name aliases in effect, specified by alias directives (& options ?) ,jparsealiases :: [AccountAlias] -- ^ the current account name aliases in effect, specified by alias directives (& options ?)
-- ,jparsetransactioncount :: Integer -- ^ the current count of transactions parsed so far (only journal format txns, currently) -- ,jparsetransactioncount :: Integer -- ^ the current count of transactions parsed so far (only journal format txns, currently)
,jparsetimeclockentries :: [TimeclockEntry] -- ^ timeclock sessions which have not been clocked out ,jparsetimeclockentries :: [TimeclockEntry] -- ^ timeclock sessions which have not been clocked out
,jincludefilestack :: [FilePath] ,jincludefilestack :: [FilePath]
-- principal data -- principal data
,jdeclaredpayees :: [(Payee,PayeeDeclarationInfo)] -- ^ Payees declared by payee directives, in parse order (after journal finalisation) ,jdeclaredpayees :: [(Payee,PayeeDeclarationInfo)] -- ^ Payees declared by payee directives, in parse order.
,jdeclaredtags :: [(TagName,TagDeclarationInfo)] -- ^ Tags declared by tag directives, in parse order (after journal finalisation) ,jdeclaredtags :: [(TagName,TagDeclarationInfo)] -- ^ Tags declared by tag directives, in parse order.
,jdeclaredaccounts :: [(AccountName,AccountDeclarationInfo)] -- ^ Accounts declared by account directives, in parse order (after journal finalisation) ,jdeclaredaccounts :: [(AccountName,AccountDeclarationInfo)] -- ^ Accounts declared by account directives, in parse order.
,jdeclaredaccounttags :: M.Map AccountName [Tag] -- ^ Accounts which have tags declared in their directives, and those tags. (Does not include parents' tags.) ,jdeclaredaccounttags :: M.Map AccountName [Tag] -- ^ Declared accounts which have tags, and those tags. (Not including parent accounts' tags.)
,jdeclaredaccounttypes :: M.Map AccountType [AccountName] -- ^ Accounts whose type has been explicitly declared in their account directives, grouped by type. ,jdeclaredaccounttypes :: M.Map AccountType [AccountName] -- ^ Declared accounts which have a type: tag, grouped by the type.
,jaccounttypes :: M.Map AccountName AccountType -- ^ All accounts for which a type has been declared or can be inferred from its parent or its name. ,jaccounttypes :: M.Map AccountName AccountType -- ^ All known account types, from account declarations or account names or account parents.
,jdeclaredcommodities :: M.Map CommoditySymbol Commodity -- ^ commodities (and display styles) declared by commodity directives ,jdeclaredcommodities :: M.Map CommoditySymbol Commodity -- ^ Commodities (and their display styles) declared by commodity directives, in parse order.
,jglobalcommoditystyles :: M.Map CommoditySymbol AmountStyle -- ^ per-commodity display styles declared globally, usually by command line options (see also the import command) ,jinferredcommoditystyles :: M.Map CommoditySymbol AmountStyle -- ^ Commodity display styles inferred from amounts in the journal.
,jinferredcommoditystyles :: M.Map CommoditySymbol AmountStyle -- ^ commodity styles inferred from journal amounts ,jglobalcommoditystyles :: M.Map CommoditySymbol AmountStyle -- ^ Commodity display styles declared by command line options (sometimes augmented, see the import command).
,jpricedirectives :: [PriceDirective] -- ^ Declarations of market prices by P directives, in parse order (after journal finalisation) ,jpricedirectives :: [PriceDirective] -- ^ P (market price) directives in the journal, in parse order.
,jinferredmarketprices :: [MarketPrice] -- ^ Market prices implied by transactions, in parse order (after journal finalisation) ,jinferredmarketprices :: [MarketPrice] -- ^ Market prices inferred from transactions in the journal, in parse order.
,jtxnmodifiers :: [TransactionModifier] ,jtxnmodifiers :: [TransactionModifier] -- ^ Auto posting rules declared in the journal.
,jperiodictxns :: [PeriodicTransaction] ,jperiodictxns :: [PeriodicTransaction] -- ^ Periodic transaction rules declared in the journal.
,jtxns :: [Transaction] ,jtxns :: [Transaction] -- ^ Transactions recorded in the journal. The important bit.
,jfinalcommentlines :: Text -- ^ any final trailing comments in the (main) journal file ,jfinalcommentlines :: Text -- ^ any final trailing comments in the (main) journal file
,jfiles :: [(FilePath, Text)] -- ^ the file path and raw text of the main and ,jfiles :: [(FilePath, Text)] -- ^ the file path and raw text of the main and
-- any included journal files. The main file is first, -- any included journal files. The main file is first,
-- followed by any included files in the order encountered. -- followed by any included files in the order encountered.
-- TODO: FilePath is a sloppy type here, don't assume it's a -- TODO: FilePath is a sloppy type here, don't assume it's a
-- real file; values like "", "-", "(string)" can be seen -- real file; values like "", "-", "(string)" can be seen
,jlastreadtime :: POSIXTime -- ^ when this journal was last read from its file(s) ,jlastreadtime :: POSIXTime -- ^ when this journal was last read from its file(s)
-- NOTE: after adding new fields, eg involving account names, consider updating -- NOTE: after adding new fields, eg involving account names, consider updating
-- the Anon instance in Hleger.Cli.Anon -- the Anon instance in Hleger.Cli.Anon
} deriving (Eq, Generic) } deriving (Eq, Generic)