hledger-lib 1.15 → 1.15.1
raw patch · 10 files changed
+275/−274 lines, 10 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
Files
- CHANGES.md +4/−0
- Hledger/Data/PeriodicTransaction.hs +23/−23
- Hledger/Data/TransactionModifier.hs +2/−2
- hledger-lib.cabal +2/−2
- hledger_csv.txt +27/−27
- hledger_journal.5 +4/−4
- hledger_journal.info +4/−4
- hledger_journal.txt +195/−198
- hledger_timeclock.txt +12/−12
- hledger_timedot.txt +2/−2
CHANGES.md view
@@ -1,6 +1,10 @@ Internal/api/developer-ish changes in the hledger-lib (and hledger) packages. For user-visible changes, see the hledger package changelog. +# 16a3c96d++- fix failing doctests+ # 1.15 2019-09-01 Removals include:
Hledger/Data/PeriodicTransaction.hs view
@@ -76,107 +76,107 @@ -- -- >>> _ptgen "monthly from 2017/1 to 2017/4" -- 2017/01/01--- ; recur: monthly from 2017/1 to 2017/4+-- ; generated-transaction:~ monthly from 2017/1 to 2017/4 -- a $1.00 -- <BLANKLINE> -- 2017/02/01--- ; recur: monthly from 2017/1 to 2017/4+-- ; generated-transaction:~ monthly from 2017/1 to 2017/4 -- a $1.00 -- <BLANKLINE> -- 2017/03/01--- ; recur: monthly from 2017/1 to 2017/4+-- ; generated-transaction:~ monthly from 2017/1 to 2017/4 -- a $1.00 -- <BLANKLINE> -- -- >>> _ptgen "monthly from 2017/1 to 2017/5" -- 2017/01/01--- ; recur: monthly from 2017/1 to 2017/5+-- ; generated-transaction:~ monthly from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- 2017/02/01--- ; recur: monthly from 2017/1 to 2017/5+-- ; generated-transaction:~ monthly from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- 2017/03/01--- ; recur: monthly from 2017/1 to 2017/5+-- ; generated-transaction:~ monthly from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- 2017/04/01--- ; recur: monthly from 2017/1 to 2017/5+-- ; generated-transaction:~ monthly from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- -- >>> _ptgen "every 2nd day of month from 2017/02 to 2017/04" -- 2017/01/02--- ; recur: every 2nd day of month from 2017/02 to 2017/04+-- ; generated-transaction:~ every 2nd day of month from 2017/02 to 2017/04 -- a $1.00 -- <BLANKLINE> -- 2017/02/02--- ; recur: every 2nd day of month from 2017/02 to 2017/04+-- ; generated-transaction:~ every 2nd day of month from 2017/02 to 2017/04 -- a $1.00 -- <BLANKLINE> -- 2017/03/02--- ; recur: every 2nd day of month from 2017/02 to 2017/04+-- ; generated-transaction:~ every 2nd day of month from 2017/02 to 2017/04 -- a $1.00 -- <BLANKLINE> -- -- >>> _ptgen "every 30th day of month from 2017/1 to 2017/5" -- 2016/12/30--- ; recur: every 30th day of month from 2017/1 to 2017/5+-- ; generated-transaction:~ every 30th day of month from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- 2017/01/30--- ; recur: every 30th day of month from 2017/1 to 2017/5+-- ; generated-transaction:~ every 30th day of month from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- 2017/02/28--- ; recur: every 30th day of month from 2017/1 to 2017/5+-- ; generated-transaction:~ every 30th day of month from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- 2017/03/30--- ; recur: every 30th day of month from 2017/1 to 2017/5+-- ; generated-transaction:~ every 30th day of month from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- 2017/04/30--- ; recur: every 30th day of month from 2017/1 to 2017/5+-- ; generated-transaction:~ every 30th day of month from 2017/1 to 2017/5 -- a $1.00 -- <BLANKLINE> -- -- >>> _ptgen "every 2nd Thursday of month from 2017/1 to 2017/4" -- 2016/12/08--- ; recur: every 2nd Thursday of month from 2017/1 to 2017/4+-- ; generated-transaction:~ every 2nd Thursday of month from 2017/1 to 2017/4 -- a $1.00 -- <BLANKLINE> -- 2017/01/12--- ; recur: every 2nd Thursday of month from 2017/1 to 2017/4+-- ; generated-transaction:~ every 2nd Thursday of month from 2017/1 to 2017/4 -- a $1.00 -- <BLANKLINE> -- 2017/02/09--- ; recur: every 2nd Thursday of month from 2017/1 to 2017/4+-- ; generated-transaction:~ every 2nd Thursday of month from 2017/1 to 2017/4 -- a $1.00 -- <BLANKLINE> -- 2017/03/09--- ; recur: every 2nd Thursday of month from 2017/1 to 2017/4+-- ; generated-transaction:~ every 2nd Thursday of month from 2017/1 to 2017/4 -- a $1.00 -- <BLANKLINE> -- -- >>> _ptgen "every nov 29th from 2017 to 2019" -- 2016/11/29--- ; recur: every nov 29th from 2017 to 2019+-- ; generated-transaction:~ every nov 29th from 2017 to 2019 -- a $1.00 -- <BLANKLINE> -- 2017/11/29--- ; recur: every nov 29th from 2017 to 2019+-- ; generated-transaction:~ every nov 29th from 2017 to 2019 -- a $1.00 -- <BLANKLINE> -- 2018/11/29--- ; recur: every nov 29th from 2017 to 2019+-- ; generated-transaction:~ every nov 29th from 2017 to 2019 -- a $1.00 -- <BLANKLINE> -- -- >>> _ptgen "2017/1" -- 2017/01/01--- ; recur: 2017/1+-- ; generated-transaction:~ 2017/1 -- a $1.00 -- <BLANKLINE> --
Hledger/Data/TransactionModifier.hs view
@@ -57,7 +57,7 @@ -- >>> putStr $ showTransaction $ transactionModifierToFunction (TransactionModifier "" ["pong" `post` usd 2]) nulltransaction{tpostings=["ping" `post` usd 1]} -- 0000/01/01 -- ping $1.00--- pong $2.00+-- pong $2.00 ; generated-posting:= -- <BLANKLINE> -- >>> putStr $ showTransaction $ transactionModifierToFunction (TransactionModifier "miss" ["pong" `post` usd 2]) nulltransaction{tpostings=["ping" `post` usd 1]} -- 0000/01/01@@ -66,7 +66,7 @@ -- >>> putStr $ showTransaction $ transactionModifierToFunction (TransactionModifier "ping" ["pong" `post` amount{aismultiplier=True, aquantity=3}]) nulltransaction{tpostings=["ping" `post` usd 2]} -- 0000/01/01 -- ping $2.00--- pong $6.00+-- pong $6.00 ; generated-posting:= ping -- <BLANKLINE> -- transactionModifierToFunction :: TransactionModifier -> (Transaction -> Transaction)
hledger-lib.cabal view
@@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack ----- hash: 29b6dee7771d38c64240d2b8c53c8e41ed43c08e8fe2e93cbd6c531edc2a4ecd+-- hash: f27fe6795990dd3740ec4ca8e421ad8faaf22945809a16448fcf4d5ac0174165 name: hledger-lib-version: 1.15+version: 1.15.1 synopsis: Core data types, parsers and functionality for the hledger accounting tools description: This is a reusable library containing hledger's core functionality. .
hledger_csv.txt view
@@ -24,9 +24,9 @@ When reading a CSV file named FILE.csv, hledger looks for a conversion rules file named FILE.csv.rules in the same directory. You can over-- ride this with the --rules-file option. If the rules file does not- exist, hledger will auto-create one with some example rules, which- you'll need to adjust.+ ride this with the --rules-file option. If the rules file does not ex-+ ist, hledger will auto-create one with some example rules, which you'll+ need to adjust. At minimum, the rules file must identify the date and amount fields. It's often necessary to specify the date format, and the number of@@ -178,33 +178,33 @@ newest-first newest-first - Consider adding this rule if all of the following are true: you might- be processing just one day of data, your CSV records are in reverse- chronological order (newest first), and you care about preserving the- order of same-day transactions. It usually isn't needed, because- hledger autodetects the CSV order, but when all CSV records have the+ Consider adding this rule if all of the following are true: you might+ be processing just one day of data, your CSV records are in reverse+ chronological order (newest first), and you care about preserving the+ order of same-day transactions. It usually isn't needed, because+ hledger autodetects the CSV order, but when all CSV records have the same date it will assume they are oldest first. CSV TIPS CSV ordering- The generated journal entries will be sorted by date. The order of- same-day entries will be preserved (except in the special case where+ The generated journal entries will be sorted by date. The order of+ same-day entries will be preserved (except in the special case where you might need newest-first, see above). CSV accounts- Each journal entry will have two postings, to account1 and account2- respectively. It's not yet possible to generate entries with more than- two postings. It's conventional and recommended to use account1 for+ Each journal entry will have two postings, to account1 and account2 re-+ spectively. It's not yet possible to generate entries with more than+ two postings. It's conventional and recommended to use account1 for the account whose CSV we are reading. CSV amounts A transaction amount must be set, in one of these ways: - o with an amount field assignment, which sets the first posting's+ o with an amount field assignment, which sets the first posting's amount o (When the CSV has debit and credit amounts in separate fields:)- with field assignments for the amount-in and amount-out pseudo fields+ with field assignments for the amount-in and amount-out pseudo fields (both of them). Whichever one has a value will be used, with appropri- ate sign. If both contain a value, it might not work so well. @@ -212,30 +212,30 @@ There is some special handling for sign in amounts: - o If an amount value is parenthesised, it will be de-parenthesised and+ o If an amount value is parenthesised, it will be de-parenthesised and sign-flipped. o If an amount value begins with a double minus sign, those will cancel out and be removed. - If the currency/commodity symbol is provided as a separate CSV field,+ If the currency/commodity symbol is provided as a separate CSV field, assign it to the currency pseudo field; the symbol will be prepended to- the amount (TODO: when there is an amount). Or, you can use an amount+ the amount (TODO: when there is an amount). Or, you can use an amount field assignment for more control, eg: fields date,description,currency,amount amount %amount %currency CSV balance assertions/assignments- If the CSV includes a running balance, you can assign that to one of- the pseudo fields balance (or balance1) or balance2. This will gener-- ate a balance assertion (or if the amount is left empty, a balance- assignment), on the first or second posting, whenever the running bal-- ance field is non-empty. (TODO: #1000)+ If the CSV includes a running balance, you can assign that to one of+ the pseudo fields balance (or balance1) or balance2. This will gener-+ ate a balance assertion (or if the amount is left empty, a balance as-+ signment), on the first or second posting, whenever the running balance+ field is non-empty. (TODO: #1000) Reading multiple CSV files- You can read multiple CSV files at once using multiple -f arguments on- the command line, and hledger will look for a correspondingly-named+ You can read multiple CSV files at once using multiple -f arguments on+ the command line, and hledger will look for a correspondingly-named rules file for each. Note if you use the --rules-file option, this one rules file will be used for all the CSV files being read. @@ -254,7 +254,7 @@ REPORTING BUGS- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -268,7 +268,7 @@ SEE ALSO- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1)
hledger_journal.5 view
@@ -1175,8 +1175,8 @@ .IP .nf \f[C]-# commodity-less amounts should be treated as dollars-# (and displayed with symbol on the left, thousands separators and two decimal places)+; commodity-less amounts should be treated as dollars+; (and displayed with symbol on the left, thousands separators and two decimal places) D $1,000.00 1/1@@ -1450,7 +1450,7 @@ .nf \f[C] alias checking = assets:bank:wells fargo:checking-# rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq]+; rewrites \[dq]checking\[dq] to \[dq]assets:bank:wells fargo:checking\[dq], or \[dq]checking:a\[dq] to \[dq]assets:bank:wells fargo:checking:a\[dq] \f[R] .fi .SS Regex aliases@@ -1476,7 +1476,7 @@ .nf \f[C] alias /\[ha](.+):bank:([\[ha]:]+)(.*)/ = \[rs]1:\[rs]2 \[rs]3-# rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq]+; rewrites \[dq]assets:bank:wells fargo:checking\[dq] to \[dq]assets:wells fargo checking\[dq] \f[R] .fi .PP
hledger_journal.info view
@@ -1042,8 +1042,8 @@ and display format will be applied to all subsequent commodity-less amounts, or until the next 'D' directive. -# commodity-less amounts should be treated as dollars-# (and displayed with symbol on the left, thousands separators and two decimal places)+; commodity-less amounts should be treated as dollars+; (and displayed with symbol on the left, thousands separators and two decimal places) D $1,000.00 1/1@@ -1289,7 +1289,7 @@ Subaccounts are also affected. Eg: alias checking = assets:bank:wells fargo:checking-# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"+; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" File: hledger_journal.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: Rewriting accounts@@ -1310,7 +1310,7 @@ referenced by the usual numeric backreferences in REPLACEMENT. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3-# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"+; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" Also note that REPLACEMENT continues to the end of line (or on command line, to end of option argument), so it can contain trailing
hledger_journal.txt view
@@ -7,24 +7,24 @@ Journal - hledger's default file format, representing a General Journal DESCRIPTION- hledger's usual data source is a plain text file containing journal- entries in hledger journal format. This file represents a standard- accounting general journal. I use file names ending in .journal, but+ hledger's usual data source is a plain text file containing journal en-+ tries in hledger journal format. This file represents a standard ac-+ counting general journal. I use file names ending in .journal, but that's not required. The journal file contains a number of transaction entries, each describing a transfer of money (or any commodity) between two or more named accounts, in a simple format readable by both hledger and humans. - hledger's journal format is a compatible subset, mostly, of ledger's- journal format, so hledger can work with compatible ledger journal- files as well. It's safe, and encouraged, to run both hledger and+ hledger's journal format is a compatible subset, mostly, of ledger's+ journal format, so hledger can work with compatible ledger journal+ files as well. It's safe, and encouraged, to run both hledger and ledger on the same journal file, eg to validate the results you're get- ting. You can use hledger without learning any more about this file; just use- the add or web commands to create and update it. Many users, though,- also edit the journal file directly with a text editor, perhaps- assisted by the helper modes for emacs or vim.+ the add or web commands to create and update it. Many users, though,+ also edit the journal file directly with a text editor, perhaps as-+ sisted by the helper modes for emacs or vim. Here's an example: @@ -57,73 +57,73 @@ FILE FORMAT Transactions- Transactions are movements of some quantity of commodities between- named accounts. Each transaction is represented by a journal entry- beginning with a simple date in column 0. This can be followed by any- of the following, separated by spaces:+ Transactions are movements of some quantity of commodities between+ named accounts. Each transaction is represented by a journal entry be-+ ginning with a simple date in column 0. This can be followed by any of+ the following, separated by spaces: o (optional) a status character (empty, !, or *) - o (optional) a transaction code (any short number or text, enclosed in+ o (optional) a transaction code (any short number or text, enclosed in parentheses) o (optional) a transaction description (any remaining text until end of line or a semicolon) - o (optional) a transaction comment (any remaining text following a+ o (optional) a transaction comment (any remaining text following a semicolon until end of line) - Then comes zero or more (but usually at least 2) indented lines repre-+ Then comes zero or more (but usually at least 2) indented lines repre- senting... Postings- A posting is an addition of some amount to, or removal of some amount- from, an account. Each posting line begins with at least one space or+ A posting is an addition of some amount to, or removal of some amount+ from, an account. Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by: o (optional) a status character (empty, !, or *), followed by a space - o (required) an account name (any text, optionally containing single+ o (required) an account name (any text, optionally containing single spaces, until end of line or a double space) o (optional) two or more spaces or tabs followed by an amount. - Positive amounts are being added to the account, negative amounts are+ Positive amounts are being added to the account, negative amounts are being removed. The amounts within a transaction must always sum up to zero. As a con-- venience, one amount may be left blank; it will be inferred so as to+ venience, one amount may be left blank; it will be inferred so as to balance the transaction. - Be sure to note the unusual two-space delimiter between account name- and amount. This makes it easy to write account names containing spa-- ces. But if you accidentally leave only one space (or tab) before the+ Be sure to note the unusual two-space delimiter between account name+ and amount. This makes it easy to write account names containing spa-+ ces. But if you accidentally leave only one space (or tab) before the amount, the amount will be considered part of the account name. Dates Simple dates- Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)- Leading zeros are optional. The year may be omitted, in which case it- will be inferred from the context - the current transaction, the- default year set with a default year directive, or the current date- when the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31,+ Within a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)+ Leading zeros are optional. The year may be omitted, in which case it+ will be inferred from the context - the current transaction, the de-+ fault year set with a default year directive, or the current date when+ the command is run. Some examples: 2010/01/31, 1/31, 2010-01-31, 2010.1.31. Secondary dates- Real-life transactions sometimes involve more than one date - eg the+ Real-life transactions sometimes involve more than one date - eg the date you write a cheque, and the date it clears in your bank. When you- want to model this, eg for more accurate balances, you can specify- individual posting dates, which I recommend. Or, you can use the sec-- ondary dates (aka auxiliary/effective dates) feature, supported for+ want to model this, eg for more accurate balances, you can specify in-+ dividual posting dates, which I recommend. Or, you can use the sec-+ ondary dates (aka auxiliary/effective dates) feature, supported for compatibility with Ledger. A secondary date can be written after the primary date, separated by an- equals sign. The primary date, on the left, is used by default; the- secondary date, on the right, is used when the --date2 flag is speci-+ equals sign. The primary date, on the left, is used by default; the+ secondary date, on the right, is used when the --date2 flag is speci- fied (--aux-date or --effective also work). - The meaning of secondary dates is up to you, but it's best to follow a- consistent rule. Eg write the bank's clearing date as primary, and+ The meaning of secondary dates is up to you, but it's best to follow a+ consistent rule. Eg write the bank's clearing date as primary, and when needed, the date the transaction was initiated as secondary. Here's an example. Note that a secondary date will use the year of the@@ -139,18 +139,18 @@ $ hledger register checking --date2 2010/02/19 movie ticket assets:checking $-10 $-10 - Secondary dates require some effort; you must use them consistently in+ Secondary dates require some effort; you must use them consistently in your journal entries and remember whether to use or not use the --date2 flag for your reports. They are included in hledger for Ledger compat-- ibility, but posting dates are a more powerful and less confusing- alternative.+ ibility, but posting dates are a more powerful and less confusing al-+ ternative. Posting dates- You can give individual postings a different date from their parent- transaction, by adding a posting comment containing a tag (see below)+ You can give individual postings a different date from their parent+ transaction, by adding a posting comment containing a tag (see below) like date:DATE. This is probably the best way to control posting dates- precisely. Eg in this example the expense should appear in May- reports, and the deduction from checking should be reported on 6/1 for+ precisely. Eg in this example the expense should appear in May re-+ ports, and the deduction from checking should be reported on 6/1 for easy bank reconciliation: 2015/5/30@@ -163,24 +163,23 @@ $ hledger -f t.j register checking 2015/06/01 assets:checking $-10 $-10 - DATE should be a simple date; if the year is not specified it will use- the year of the transaction's date. You can set the secondary date- similarly, with date2:DATE2. The date: or date2: tags must have a- valid simple date value if they are present, eg a date: tag with no+ DATE should be a simple date; if the year is not specified it will use+ the year of the transaction's date. You can set the secondary date+ similarly, with date2:DATE2. The date: or date2: tags must have a+ valid simple date value if they are present, eg a date: tag with no value is not allowed. Ledger's earlier, more compact bracketed date syntax is also supported:- [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any+ [DATE], [DATE=DATE2] or [=DATE2]. hledger will attempt to parse any square-bracketed sequence of the 0123456789/-.= characters in this way.- With this syntax, DATE infers its year from the transaction and DATE2+ With this syntax, DATE infers its year from the transaction and DATE2 infers its year from DATE. Status- Transactions, or individual postings within a transaction, can have a- status mark, which is a single character before the transaction- description or posting account name, separated from it by a space,- indicating one of three statuses:-+ Transactions, or individual postings within a transaction, can have a+ status mark, which is a single character before the transaction de-+ scription or posting account name, separated from it by a space, indi-+ cating one of three statuses: mark status ------------------@@ -188,26 +187,25 @@ ! pending * cleared - When reporting, you can filter by status with the -U/--unmarked,- -P/--pending, and -C/--cleared flags; or the status:, status:!, and+ When reporting, you can filter by status with the -U/--unmarked,+ -P/--pending, and -C/--cleared flags; or the status:, status:!, and status:* queries; or the U, P, C keys in hledger-ui. - Note, in Ledger and in older versions of hledger, the "unmarked" state- is called "uncleared". As of hledger 1.3 we have renamed it to- unmarked for clarity.+ Note, in Ledger and in older versions of hledger, the "unmarked" state+ is called "uncleared". As of hledger 1.3 we have renamed it to un-+ marked for clarity. - To replicate Ledger and old hledger's behaviour of also matching pend-+ To replicate Ledger and old hledger's behaviour of also matching pend- ing, combine -U and -P. - Status marks are optional, but can be helpful eg for reconciling with+ Status marks are optional, but can be helpful eg for reconciling with real-world accounts. Some editor modes provide highlighting and short-- cuts for working with status. Eg in Emacs ledger-mode, you can toggle+ cuts for working with status. Eg in Emacs ledger-mode, you can toggle transaction status with C-c C-e, or posting status with C-c C-c. - What "uncleared", "pending", and "cleared" actually mean is up to you.+ What "uncleared", "pending", and "cleared" actually mean is up to you. Here's one suggestion: - status meaning -------------------------------------------------------------------------- uncleared recorded but not yet reconciled; needs review@@ -216,33 +214,33 @@ cleared complete, reconciled as far as possible, and considered cor- rect - With this scheme, you would use -PC to see the current balance at your- bank, -U to see things which will probably hit your bank soon (like- uncashed checks), and no flags to see the most up-to-date state of your+ With this scheme, you would use -PC to see the current balance at your+ bank, -U to see things which will probably hit your bank soon (like un-+ cashed checks), and no flags to see the most up-to-date state of your finances. Description- A transaction's description is the rest of the line following the date- and status mark (or until a comment begins). Sometimes called the+ A transaction's description is the rest of the line following the date+ and status mark (or until a comment begins). Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you- wish, or left blank. Transaction descriptions can be queried, unlike+ wish, or left blank. Transaction descriptions can be queried, unlike comments. Payee and note You can optionally include a | (pipe) character in descriptions to sub- divide the description into separate fields for payee/payer name on the- left (up to the first |) and an additional note field on the right- (after the first |). This may be worthwhile if you need to do more- precise querying and pivoting by payee or by note.+ left (up to the first |) and an additional note field on the right (af-+ ter the first |). This may be worthwhile if you need to do more pre-+ cise querying and pivoting by payee or by note. Account names- Account names typically have several parts separated by a full colon,- from which hledger derives a hierarchical chart of accounts. They can- be anything you like, but in finance there are traditionally five top-+ Account names typically have several parts separated by a full colon,+ from which hledger derives a hierarchical chart of accounts. They can+ be anything you like, but in finance there are traditionally five top- level accounts: assets, liabilities, income, expenses, and equity. - Account names may contain single spaces, eg: assets:accounts receiv-- able. Because of this, they must always be followed by two or more+ Account names may contain single spaces, eg: assets:accounts receiv-+ able. Because of this, they must always be followed by two or more spaces (or newline). Account names can be aliased.@@ -251,7 +249,7 @@ After the account name, there is usually an amount. Important: between account name and amount, there must be two or more spaces. - Amounts consist of a number and (usually) a currency symbol or commod-+ Amounts consist of a number and (usually) a currency symbol or commod- ity name. Some examples: 2.00001@@ -267,35 +265,35 @@ As you can see, the amount format is somewhat flexible: - o amounts are a number (the "quantity") and optionally a currency sym-+ o amounts are a number (the "quantity") and optionally a currency sym- bol/commodity name (the "commodity"). - o the commodity is a symbol, word, or phrase, on the left or right,- with or without a separating space. If the commodity contains num-- bers, spaces or non-word punctuation it must be enclosed in double+ o the commodity is a symbol, word, or phrase, on the left or right,+ with or without a separating space. If the commodity contains num-+ bers, spaces or non-word punctuation it must be enclosed in double quotes. o negative amounts with a commodity on the left can have the minus sign before or after it - o digit groups (thousands, or any other grouping) can be separated by- space or comma or period and should be used as separator between all+ o digit groups (thousands, or any other grouping) can be separated by+ space or comma or period and should be used as separator between all groups - o decimal part can be separated by comma or period and should be dif-+ o decimal part can be separated by comma or period and should be dif- ferent from digit groups separator - o scientific E-notation is allowed. Be careful not to use a digit- group separator character in scientific notation, as it's not sup-+ o scientific E-notation is allowed. Be careful not to use a digit+ group separator character in scientific notation, as it's not sup- ported and it might get mistaken for a decimal point. (Declaring the digit group separator character explicitly with a commodity directive will prevent this.) - You can use any of these variations when recording data. However,- there is some ambiguous way of representing numbers like $1.000 and- $1,000 both may mean either one thousand or one dollar. By default- hledger will assume that this is sole delimiter is used only for deci-- mals. On the other hand commodity format declared prior to that line+ You can use any of these variations when recording data. However,+ there is some ambiguous way of representing numbers like $1.000 and+ $1,000 both may mean either one thousand or one dollar. By default+ hledger will assume that this is sole delimiter is used only for deci-+ mals. On the other hand commodity format declared prior to that line will help to resolve that ambiguity differently: commodity $1,000.00@@ -304,9 +302,9 @@ expenses:gifts $1,000 assets - Though journal may contain mixed styles to represent amount, when- hledger displays amounts, it will choose a consistent format for each- commodity. (Except for price amounts, which are always formatted as+ Though journal may contain mixed styles to represent amount, when+ hledger displays amounts, it will choose a consistent format for each+ commodity. (Except for price amounts, which are always formatted as written). The display format is chosen as follows: o if there is a commodity directive specifying the format, that is used@@ -582,11 +580,11 @@ nodes to be ignored, allowing emacs users to fold and navigate their journals with org-mode or orgstruct-mode.) - You can attach comments to a transaction by writing them after the- description and/or indented on the following lines (before the post-- ings). Similarly, you can attach comments to an individual posting by- writing them after the amount and/or indented on the following lines.- Transaction and posting comments must begin with a semicolon (;).+ You can attach comments to a transaction by writing them after the de-+ scription and/or indented on the following lines (before the postings).+ Similarly, you can attach comments to an individual posting by writing+ them after the amount and/or indented on the following lines. Transac-+ tion and posting comments must begin with a semicolon (;). Some examples: @@ -662,47 +660,48 @@ here is a table summarising the directives and their effects, with links to more detailed docs. -- direc- end subdi- purpose can affect (as of- tive directive rec- 2018/06)+ direc- end di- subdi- purpose can affect (as of+ tive rective rec- 2018/06) tives ------------------------------------------------------------------------------------+ account any document account names, de- all entries in all+ text clare account types & dis- files, before or+ play order after - account any document account names, all entries in all- text declare account types & dis- files, before or- play order after- alias end rewrite account names following- aliases inline/included- entries until end- of current file or- end directive- apply end apply prepend a common parent to following- account account account names inline/included- entries until end- of current file or- end directive- comment end com- ignore part of journal following- ment inline/included- entries until end- of current file or- end directive- commod- format declare a commodity and its number notation:+++ alias end rewrite account names following in-+ aliases line/included en-+ tries until end of+ current file or end+ directive+ apply end apply prepend a common parent to following in-+ account account account names line/included en-+ tries until end of+ current file or end+ directive+ comment end com- ignore part of journal following in-+ ment line/included en-+ tries until end of+ current file or end+ directive+ commod- format declare a commodity and its number notation: ity number notation & display following entries style in that commodity- in all files; dis-+ in all files; dis- play style: amounts of that commodity in reports- D declare a commodity, number commodity: all com-+ D declare a commodity, number commodity: all com- notation & display style for modityless entries- commodityless amounts in all files; num-- ber notation: fol-+ commodityless amounts in all files; num-+ ber notation: fol- lowing commodity-- less entries and+ less entries and entries in that- commodity in all+ commodity in all files; display style: amounts of that commodity in@@ -710,22 +709,21 @@ include include entries/directives what the included from another file directives affect P declare a market price for a amounts of that- commodity commodity in- reports, when -V is+ commodity commodity in re-+ ports, when -V is used- Y declare a year for yearless following- dates inline/included- entries until end- of current file+ Y declare a year for yearless following in-+ dates line/included en-+ tries until end of+ current file And some definitions: - subdirec- optional indented directive line immediately following a par- tive ent directive- number how to interpret numbers when parsing journal entries (the- notation identity of the decimal separator character). (Currently- each commodity can have its own notation, even in the same+ number how to interpret numbers when parsing journal entries (the+ notation identity of the decimal separator character). (Currently+ each commodity can have its own notation, even in the same file.) display how to display amounts of a commodity in reports (symbol side style and spacing, digit groups, decimal separator, decimal places)@@ -733,8 +731,8 @@ scope are affected by a directive As you can see, directives vary in which journal entries and files they- affect, and whether they are focussed on input (parsing) or output- (reports). Some directives have multiple effects.+ affect, and whether they are focussed on input (parsing) or output (re-+ ports). Some directives have multiple effects. If you have a journal made up of multiple files, or pass multiple -f options on the command line, note that directives which affect input@@ -758,8 +756,8 @@ file. The include file path may contain common glob patterns (e.g. *). - The include directive can only be used in journal files. It can- include journal, timeclock or timedot files, but not CSV files.+ The include directive can only be used in journal files. It can in-+ clude journal, timeclock or timedot files, but not CSV files. Default year You can set a default year to be used for subsequent dates which don't@@ -815,8 +813,8 @@ Normally the display format is inferred from journal entries, but this can be unpredictable; declaring it with a commodity directive overrides- this and removes ambiguity. Towards this end, amounts in commodity- directives must always be written with a decimal point (a period or+ this and removes ambiguity. Towards this end, amounts in commodity di-+ rectives must always be written with a decimal point (a period or comma, followed by 0 or more decimal digits). Commodity directives do not affect how amounts are parsed; the parser@@ -829,8 +827,8 @@ and display format will be applied to all subsequent commodity-less amounts, or until the next D directive. - # commodity-less amounts should be treated as dollars- # (and displayed with symbol on the left, thousands separators and two decimal places)+ ; commodity-less amounts should be treated as dollars+ ; (and displayed with symbol on the left, thousands separators and two decimal places) D $1,000.00 1/1@@ -841,8 +839,8 @@ a decimal point. Market prices- The P directive declares a market price, which is an exchange rate- between two commodities on a certain date. (In Ledger, they are called+ The P directive declares a market price, which is an exchange rate be-+ tween two commodities on a certain date. (In Ledger, they are called "historical prices".) These are often obtained from a stock exchange, cryptocurrency exchange, or the foreign exchange market. @@ -867,8 +865,8 @@ commodity using these prices. Declaring accounts- account directives can be used to pre-declare accounts. Though not- required, they can provide several benefits:+ account directives can be used to pre-declare accounts. Though not re-+ quired, they can provide several benefits: o They can document your intended chart of accounts, providing a refer- ence.@@ -927,8 +925,8 @@ detected automatically. Account types declared with tags- More generally, you can declare an account's type with an account- directive, by writing a type: tag in a comment, followed by one of the+ More generally, you can declare an account's type with an account di-+ rective, by writing a type: tag in a comment, followed by one of the words Asset, Liability, Equity, Revenue, Expense, or one of the letters ALERX (case insensitive): @@ -984,16 +982,16 @@ Undeclared accounts, if any, are displayed last, in alphabetical order. - Note that sorting is done at each level of the account tree (within- each group of sibling accounts under the same parent). And currently,+ Note that sorting is done at each level of the account tree (within+ each group of sibling accounts under the same parent). And currently, this directive: account other:zoo - would influence the position of zoo among other's subaccounts, but not- the position of other among the top-level accounts. This means: - you- will sometimes declare parent accounts (eg account other above) that- you don't intend to post to, just to customize their display order -+ would influence the position of zoo among other's subaccounts, but not+ the position of other among the top-level accounts. This means: - you+ will sometimes declare parent accounts (eg account other above) that+ you don't intend to post to, just to customize their display order - sibling accounts stay together (you couldn't display x:y in between a:b and a:c). @@ -1012,14 +1010,14 @@ o customising reports Account aliases also rewrite account names in account directives. They- do not affect account names being entered via hledger add or hledger-+ do not affect account names being entered via hledger add or hledger- web. See also Cookbook: Rewrite account names. Basic aliases- To set an account alias, use the alias directive in your journal file.- This affects all subsequent journal entries in the current file or its+ To set an account alias, use the alias directive in your journal file.+ This affects all subsequent journal entries in the current file or its included files. The spaces around the = are optional: alias OLD = NEW@@ -1027,12 +1025,12 @@ Or, you can use the --alias 'OLD=NEW' option on the command line. This affects all entries. It's useful for trying out aliases interactively. - OLD and NEW are case sensitive full account names. hledger will- replace any occurrence of the old account name with the new one. Sub-- accounts are also affected. Eg:+ OLD and NEW are case sensitive full account names. hledger will re-+ place any occurrence of the old account name with the new one. Subac-+ counts are also affected. Eg: alias checking = assets:bank:wells fargo:checking- # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"+ ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a" Regex aliases There is also a more powerful variant that uses a regular expression,@@ -1048,7 +1046,7 @@ erenced by the usual numeric backreferences in REPLACEMENT. Eg: alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3- # rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"+ ; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking" Also note that REPLACEMENT continues to the end of line (or on command line, to end of option argument), so it can contain trailing white-@@ -1080,23 +1078,23 @@ o aliases defined after/below the entry do not affect it. - This gives nearby aliases precedence over distant ones, and helps pro-- vide semantic stability - aliases will keep working the same way inde-+ This gives nearby aliases precedence over distant ones, and helps pro-+ vide semantic stability - aliases will keep working the same way inde- pendent of which files are being read and in which order. - In case of trouble, adding --debug=6 to the command line will show+ In case of trouble, adding --debug=6 to the command line will show which aliases are being applied when. end aliases- You can clear (forget) all currently defined aliases with the end+ You can clear (forget) all currently defined aliases with the end aliases directive: end aliases Default parent account- You can specify a parent account which will be prepended to all- accounts within a section of the journal. Use the apply account and- end apply account directives like so:+ You can specify a parent account which will be prepended to all ac-+ counts within a section of the journal. Use the apply account and end+ apply account directives like so: apply account home @@ -1112,7 +1110,7 @@ home:food $10 home:cash $-10 - If end apply account is omitted, the effect lasts to the end of the+ If end apply account is omitted, the effect lasts to the end of the file. Included files are also affected, eg: apply account business@@ -1121,19 +1119,19 @@ apply account personal include personal.journal - Prior to hledger 1.0, legacy account and end spellings were also sup-+ Prior to hledger 1.0, legacy account and end spellings were also sup- ported. - A default parent account also affects account directives. It does not- affect account names being entered via hledger add or hledger-web. If- account aliases are present, they are applied after the default parent+ A default parent account also affects account directives. It does not+ affect account names being entered via hledger add or hledger-web. If+ account aliases are present, they are applied after the default parent account. Periodic transactions- Periodic transaction rules describe transactions that recur. They- allow you to generate future transactions for forecasting, without hav-- ing to write them out explicitly in the journal (with --forecast).- Secondly, they also can be used to define budget goals (with --budget).+ Periodic transaction rules describe transactions that recur. They al-+ low you to generate future transactions for forecasting, without having+ to write them out explicitly in the journal (with --forecast). Sec-+ ondly, they also can be used to define budget goals (with --budget). A periodic transaction rule looks like a normal journal entry, with the date replaced by a tilde (~) followed by a period expression (mnemonic:@@ -1166,8 +1164,8 @@ income:acme inc Forecasting with periodic transactions- With the --forecast flag, each periodic transaction rule generates- future transactions recurring at the specified interval. These are not+ With the --forecast flag, each periodic transaction rule generates fu-+ ture transactions recurring at the specified interval. These are not saved in the journal, but appear in all reports. They will look like normal transactions, but with an extra tag: @@ -1225,7 +1223,6 @@ For more details, see: balance: Budget report and Cookbook: Budgeting and Forecasting. - Auto postings / transaction modifiers Transaction modifier rules, AKA auto posting rules, describe changes to be applied automatically to certain matched transactions. Currently@@ -1304,12 +1301,12 @@ tions Currently, transaction modifiers are applied / auto postings are added: - o after missing amounts are inferred, and transactions are checked for+ o after missing amounts are inferred, and transactions are checked for balancedness, o but before balance assertions are checked. - Note this means that journal entries must be balanced both before and+ Note this means that journal entries must be balanced both before and after auto postings are added. This changed in hledger 1.12+; see #893 for background. @@ -1319,11 +1316,11 @@ o generated-posting:= QUERY - shows this was generated by an auto post- ing rule, and the query - o _generated-posting:= QUERY - a hidden tag, which does not appear in+ o _generated-posting:= QUERY - a hidden tag, which does not appear in hledger's output. This can be used to match postings generated "just now", rather than generated in the past and saved to the journal. - Also, any transaction that has been changed by transaction modifier+ Also, any transaction that has been changed by transaction modifier rules will have these tags added: o modified: - this transaction was modified@@ -1332,18 +1329,18 @@ tion was modified "just now". EDITOR SUPPORT- Helper modes exist for popular text editors, which make working with+ Helper modes exist for popular text editors, which make working with journal files easier. They add colour, formatting, tab completion, and- helpful commands, and are quite recommended if you edit your journal- with a text editor. They include ledger-mode or hledger-mode for- Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and- others. See the [[Cookbook]] at hledger.org for the latest informa-+ helpful commands, and are quite recommended if you edit your journal+ with a text editor. They include ledger-mode or hledger-mode for+ Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and+ others. See the [[Cookbook]] at hledger.org for the latest informa- tion. REPORTING BUGS- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -1357,7 +1354,7 @@ SEE ALSO- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1)
hledger_timeclock.txt view
@@ -7,11 +7,11 @@ Timeclock - the time logging format of timeclock.el, as read by hledger DESCRIPTION- hledger can read timeclock files. As with Ledger, these are (a subset+ hledger can read timeclock files. As with Ledger, these are (a subset of) timeclock.el's format, containing clock-in and clock-out entries as- in the example below. The date is a simple date. The time format is- HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone,- if present, must be four digits and is ignored (currently the time is+ in the example below. The date is a simple date. The time format is+ HH:MM[:SS][+-ZZZZ]. Seconds and timezone are optional. The timezone,+ if present, must be four digits and is ignored (currently the time is always interpreted as a local time). i 2015/03/30 09:00:00 some:account name optional description after two spaces@@ -19,9 +19,9 @@ i 2015/03/31 22:21:45 another account o 2015/04/01 02:00:34 - hledger treats each clock-in/clock-out pair as a transaction posting- some number of hours to an account. Or if the session spans more than- one day, it is split into several transactions, one for each day. For+ hledger treats each clock-in/clock-out pair as a transaction posting+ some number of hours to an account. Or if the session spans more than+ one day, it is split into several transactions, one for each day. For the above time log, hledger print generates these journal entries: $ hledger -f t.timeclock print@@ -42,21 +42,21 @@ To generate time logs, ie to clock in and clock out, you could: - o use emacs and the built-in timeclock.el, or the extended timeclock-+ o use emacs and the built-in timeclock.el, or the extended timeclock- x.el and perhaps the extras in ledgerutils.el o at the command line, use these bash aliases: shell alias ti="echo i- `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date+ `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG" o or use the old ti and to scripts in the ledger 2.x repository. These- rely on a "timeclock" executable which I think is just the ledger 2+ rely on a "timeclock" executable which I think is just the ledger 2 executable renamed. REPORTING BUGS- Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel+ Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel or hledger mail list) @@ -70,7 +70,7 @@ SEE ALSO- hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),+ hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1), hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time- dot(5), ledger(1)
hledger_timedot.txt view
@@ -28,8 +28,8 @@ Quantities can be written as: - o a sequence of dots (.) representing quarter hours. Spaces may- optionally be used for grouping and readability. Eg: .... ..+ o a sequence of dots (.) representing quarter hours. Spaces may op-+ tionally be used for grouping and readability. Eg: .... .. o an integral or decimal number, representing hours. Eg: 1.5