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

;doc: manuals: whitespace cleanup

Browse Source 
Remove a bunch of trailing whitespace with M-x whitespace-cleanup.
Except for examples showing hledger output, which might be tested
with shelltest some day, so stripping that whitespace might be problematic.

[ci skip]
This commit is contained in:
Simon Michael 2020-02-08 12:08:47 -08:00
parent 98d0cc9c17
commit 4d94a5273b
6 changed files with 217 additions and 219 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
hledger-lib/hledger_csv.m4.md
View File

@ -45,7 +45,7 @@ these are described more fully below, after the examples:
| [**`newest-first`**](#newest-first) | disambiguate record order when there's only one date | | [**`newest-first`**](#newest-first) | disambiguate record order when there's only one date |
| [**`include`**](#include) | inline another CSV rules file | | [**`include`**](#include) | inline another CSV rules file |
Note, for best error messages when reading CSV files, use a `.csv`, `.tsv` or `.ssv` Note, for best error messages when reading CSV files, use a `.csv`, `.tsv` or `.ssv`
file extension or file prefix - see [File Extension](#file-extension) below. file extension or file prefix - see [File Extension](#file-extension) below.
There's an introductory [Convert CSV files](convert-csv-files.html) tutorial on hledger.org. There's an introductory [Convert CSV files](convert-csv-files.html) tutorial on hledger.org.
@ -102,7 +102,7 @@ fields date, description, amount-out, amount-in, balance
# We generate balance assertions by assigning to "balance" # We generate balance assertions by assigning to "balance"
# above, but you may sometimes need to remove these because: # above, but you may sometimes need to remove these because:
# #
# - the CSV balance differs from the true balance, # - the CSV balance differs from the true balance,
# by up to 0.0000000000005 in my experience # by up to 0.0000000000005 in my experience
# #
# - it is sometimes calculated based on non-chronological ordering, # - it is sometimes calculated based on non-chronological ordering,
@ -176,7 +176,7 @@ amount2 %amzamount
# add a third posting for fees, but only if they are non-zero. # add a third posting for fees, but only if they are non-zero.
# Commas in the data makes counting fields hard, so count from the right instead. # Commas in the data makes counting fields hard, so count from the right instead.
# (Regex translation: "a field containing a non-zero dollar amount, # (Regex translation: "a field containing a non-zero dollar amount,
# immediately before the 1 right-most fields") # immediately before the 1 right-most fields")
if ,\$[1-9][.0-9]+(,[^,]*){1}$ if ,\$[1-9][.0-9]+(,[^,]*){1}$
account3 expenses:fees account3 expenses:fees
@ -232,11 +232,11 @@ date-format %-m/%-d/%Y
if if
In Progress In Progress
Temporary Hold Temporary Hold
Update to Update to
skip skip
# add more fields to the description # add more fields to the description
description %description_ %itemtitle description %description_ %itemtitle
# save some other fields as tags # save some other fields as tags
comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_ comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
@ -284,9 +284,9 @@ include common.rules
# apply some overrides specific to this csv # apply some overrides specific to this csv
# Transfers from/to bank. These are usually marked Pending, # Transfers from/to bank. These are usually marked Pending,
# which can be disregarded in this case. # which can be disregarded in this case.
if if
Bank Account Bank Account
Bank Deposit to PP Account Bank Deposit to PP Account
description %type for %referencetxnid %itemtitle description %type for %referencetxnid %itemtitle
@ -388,27 +388,27 @@ A fields list (the word "fields" followed by comma-separated field
names) is the quick way to assign CSV field values to hledger fields. names) is the quick way to assign CSV field values to hledger fields.
It does two things: It does two things:
1. it names the CSV fields. 1. it names the CSV fields.
This is optional, but can be convenient later for interpolating them. This is optional, but can be convenient later for interpolating them.
2. when you use a standard hledger field name, 2. when you use a standard hledger field name,
it assigns the CSV value to that part of the hledger transaction. it assigns the CSV value to that part of the hledger transaction.
Here's an example that says Here's an example that says
"use the 1st, 2nd and 4th fields as the transaction's date, description and amount; "use the 1st, 2nd and 4th fields as the transaction's date, description and amount;
name the last two fields for later reference; and ignore the others": name the last two fields for later reference; and ignore the others":
```rules ```rules
fields date, description, , amount, , , somefield, anotherfield fields date, description, , amount, , , somefield, anotherfield
``` ```
Field names may not contain whitespace. Field names may not contain whitespace.
Fields you don't care about can be left unnamed. Fields you don't care about can be left unnamed.
Currently there must be least two items (there must be at least one comma). Currently there must be least two items (there must be at least one comma).
Note, always use comma in the fields list, even if your CSV uses Note, always use comma in the fields list, even if your CSV uses
[another separator character](#separator). [another separator character](#separator).
Here are the standard hledger field/pseudo-field names. Here are the standard hledger field/pseudo-field names.
For more about the transaction parts they refer to, see the manual for hledger's journal format. For more about the transaction parts they refer to, see the manual for hledger's journal format.
### Transaction field names ### Transaction field names
@ -421,7 +421,7 @@ For more about the transaction parts they refer to, see the manual for hledger's
`accountN`, where N is 1 to 9, generates a `accountN`, where N is 1 to 9, generates a
[posting](journal.html#postings), with that account name. [posting](journal.html#postings), with that account name.
Most often there are two postings, so you'll want to set `account1` and `account2`. Most often there are two postings, so you'll want to set `account1` and `account2`.
If a posting's account name is left unset but its amount is set, If a posting's account name is left unset but its amount is set,
a default account name will be chosen (like expenses:unknown or income:unknown). a default account name will be chosen (like expenses:unknown or income:unknown).
`amountN` sets posting N's amount. Or, `amount` with no N sets posting `amountN` sets posting N's amount. Or, `amount` with no N sets posting
@ -432,18 +432,18 @@ a default account name will be chosen (like expenses:unknown or income:unknown).
For convenience and backwards compatibility, if you set the amount of For convenience and backwards compatibility, if you set the amount of
posting 1 only, a second posting with the negative amount will be posting 1 only, a second posting with the negative amount will be
generated automatically. generated automatically.
(Unless the account name is parenthesised indicating an (Unless the account name is parenthesised indicating an
[unbalanced posting](journal.html#virtual-postings).) [unbalanced posting](journal.html#virtual-postings).)
If the CSV has the currency symbol in a separate field, you can use If the CSV has the currency symbol in a separate field, you can use
`currencyN` to prepend it to posting N's amount. `currency` with no N `currencyN` to prepend it to posting N's amount. `currency` with no N
affects ALL postings. affects ALL postings.
`balanceN` sets a [balance assertion](journal.html#balance-assertions) amount `balanceN` sets a [balance assertion](journal.html#balance-assertions) amount
(or if the posting amount is left empty, a [balance assignment](journal.html#balance-assignments)). (or if the posting amount is left empty, a [balance assignment](journal.html#balance-assignments)).
You may need to adjust this with the [`balance-type` rule](#balance-type). You may need to adjust this with the [`balance-type` rule](#balance-type).
Finally, `commentN` sets a [comment](journal.html#comments) on the Nth posting. Finally, `commentN` sets a [comment](journal.html#comments) on the Nth posting.
Comments can also contain [tags](journal.html#tags), as usual. Comments can also contain [tags](journal.html#tags), as usual.
See TIPS below for more about setting amounts and currency. See TIPS below for more about setting amounts and currency.
@ -459,7 +459,7 @@ Instead of or in addition to a [fields list](#fields), you can use a
"field assignment" rule to set the value of a single hledger field, by "field assignment" rule to set the value of a single hledger field, by
writing its name (any of the standard hledger field names above) writing its name (any of the standard hledger field names above)
followed by a text value. followed by a text value.
The value may contain interpolated CSV fields, The value may contain interpolated CSV fields,
referenced by their 1-based position in the CSV record (`%N`), referenced by their 1-based position in the CSV record (`%N`),
or by the name they were given in the fields list (`%CSVFIELDNAME`). or by the name they were given in the fields list (`%CSVFIELDNAME`).
Some examples: Some examples:
@ -554,7 +554,7 @@ banking thru software
## `end` ## `end`
This rule can be used inside [if blocks](#if) (only), to make hledger stop This rule can be used inside [if blocks](#if) (only), to make hledger stop
reading this CSV file and move on to the next input file, or to command execution. reading this CSV file and move on to the next input file, or to command execution.
Eg: Eg:
```rules ```rules
# ignore everything following the first empty record # ignore everything following the first empty record
@ -641,7 +641,7 @@ Balance assertions generated by [assigning to balanceN](#posting-field-names)
are of the simple `=` type by default, are of the simple `=` type by default,
which is a [single-commodity](https://hledger.org/journal.html#assertions-and-commodities), which is a [single-commodity](https://hledger.org/journal.html#assertions-and-commodities),
[subaccount-excluding](https://hledger.org/journal.html#assertions-and-subaccounts) assertion. [subaccount-excluding](https://hledger.org/journal.html#assertions-and-subaccounts) assertion.
You may find the subaccount-including variants more useful, You may find the subaccount-including variants more useful,
eg if you have created some virtual subaccounts of checking to help with budgeting. eg if you have created some virtual subaccounts of checking to help with budgeting.
You can select a different type of assertion with the `balance-type` rule: You can select a different type of assertion with the `balance-type` rule:
```rules ```rules
@ -752,11 +752,11 @@ A posting amount can be set in one of these ways:
`amountN` (posting N's amount) or `amount` (posting 1's amount) `amountN` (posting N's amount) or `amount` (posting 1's amount)
- by assigning to `amountN-in` and `amountN-out` (or `amount-in` and `amount-out`). - by assigning to `amountN-in` and `amountN-out` (or `amount-in` and `amount-out`).
For each CSV record, whichever of these has a non-zero value will be used, with appropriate sign. For each CSV record, whichever of these has a non-zero value will be used, with appropriate sign.
If both contain a non-zero value, this may not work. If both contain a non-zero value, this may not work.
- by assigning to `balanceN` (or `balance`) instead of the above, - by assigning to `balanceN` (or `balance`) instead of the above,
setting the amount indirectly via a setting the amount indirectly via a
[balance assignment](journal.html#balance-assignments). [balance assignment](journal.html#balance-assignments).
If you do this the default account name may be wrong, so you should set that explicitly. If you do this the default account name may be wrong, so you should set that explicitly.

129
hledger-lib/hledger_journal.m4.md
View File

@ -33,8 +33,8 @@ create and update it.
Many users, though, edit the journal file with a text editor, Many users, though, edit the journal file with a text editor,
and track changes with a version control system such as git. and track changes with a version control system such as git.
Editor addons such as Editor addons such as
ledger-mode or hledger-mode for Emacs, ledger-mode or hledger-mode for Emacs,
vim-ledger for Vim, vim-ledger for Vim,
and hledger-vscode for Visual Studio Code, and hledger-vscode for Visual Studio Code,
make this easier, adding colour, formatting, tab completion, and useful commands. make this easier, adding colour, formatting, tab completion, and useful commands.
See [Editor configuration](editors.html) at hledger.org for the full list. See [Editor configuration](editors.html) at hledger.org for the full list.
@ -93,7 +93,7 @@ Each transaction is recorded as a journal entry, beginning with a
[simple date](#simple-dates) in column 0. This can be followed by any [simple date](#simple-dates) in column 0. This can be followed by any
of the following optional fields, separated by spaces: of the following optional fields, separated by spaces:
- a [status](#status) character (empty, `!`, or `*`) - a [status](#status) character (empty, `!`, or `*`)
- a code (any short number or text, enclosed in parentheses) - a code (any short number or text, enclosed in parentheses)
- a description (any remaining text until end of line or a semicolon) - a description (any remaining text until end of line or a semicolon)
- a comment (any remaining text following a semicolon until end of line, - a comment (any remaining text following a semicolon until end of line,
@ -116,7 +116,7 @@ Here's a simple journal file containing one transaction:
Dates in the journal file use *simple dates* format: Dates in the journal file use *simple dates* format:
`YYYY-MM-DD` or `YYYY/MM/DD` or `YYYY.MM.DD`, with leading zeros optional. `YYYY-MM-DD` or `YYYY/MM/DD` or `YYYY.MM.DD`, with leading zeros optional.
The year may be omitted, in which case it will be inferred from the context: 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](#default-year), the current transaction, the default year set with a [default year directive](#default-year),
or the current date when the command is run. or the current date when the command is run.
Some examples: `2010-01-31`, `2010/01/31`, `2010.1.31`, `1/31`. Some examples: `2010-01-31`, `2010/01/31`, `2010.1.31`, `1/31`.
@ -145,7 +145,7 @@ default, but with the `--date2` flag (or `--aux-date` or
`--effective`), the secondary (right) date will be used instead. `--effective`), the secondary (right) date will be used instead.
The meaning of secondary dates is up to you, but it's best to follow a The meaning of secondary dates is up to you, but it's best to follow a
consistent rule. Eg "primary = the bank's clearing date, secondary = consistent rule. Eg "primary = the bank's clearing date, secondary =
date the transaction was initiated, if different", as shown here: date the transaction was initiated, if different", as shown here:
```journal ```journal
2010/2/23=2/19 movie ticket 2010/2/23=2/19 movie ticket
@ -200,9 +200,9 @@ the transaction and DATE2 infers its year from DATE.
## Status ## Status
Transactions, or individual postings within a transaction, Transactions, or individual postings within a transaction,
can have a status mark, which is a single character before can have a status mark, which is a single character before
the transaction description or posting account name, the transaction description or posting account name,
separated from it by a space, indicating one of three statuses: separated from it by a space, indicating one of three statuses:
| mark   | status | | mark   | status |
@ -243,7 +243,7 @@ and no flags to see the most up-to-date state of your finances.
A transaction's description is the rest of the line following the date and status mark (or until a comment begins). 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, Sometimes called the "narration" in traditional bookkeeping, it can be used for whatever you wish,
or left blank. Transaction descriptions can be queried, unlike [comments](#comments). or left blank. Transaction descriptions can be queried, unlike [comments](#comments).
### Payee and note ### Payee and note
@ -263,7 +263,7 @@ You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual postings). Similarly, you can attach comments to an individual
posting by writing them after the amount and/or indented on the posting by writing them after the amount and/or indented on the
following lines. following lines.
Transaction and posting comments must begin with a semicolon (`;`). Transaction and posting comments must begin with a semicolon (`;`).
Some examples: Some examples:
@ -334,15 +334,15 @@ Tags are like Ledger's
feature, except hledger's tag values are simple strings. feature, except hledger's tag values are simple strings.
## Postings ## Postings
A posting is an addition of some amount to, or removal of some amount from, an account. 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: Each posting line begins with at least one space or tab (2 or 4 spaces is common), followed by:
- (optional) a [status](#status) character (empty, `!`, or `*`), followed by a space - (optional) a [status](#status) character (empty, `!`, or `*`), followed by a space
- (required) an [account name](#account-names) (any text, optionally containing **single spaces**, until end of line or a double space) - (required) an [account name](#account-names) (any text, optionally containing **single spaces**, until end of line or a double space)
- (optional) **two or more spaces** or tabs followed by an [amount](#amounts). - (optional) **two or more spaces** or tabs followed by an [amount](#amounts).
Positive amounts are being added to the account, negative amounts are being removed. Positive amounts are being added to the account, negative amounts are being removed.
The amounts within a transaction must always sum up to zero. The amounts within a transaction must always sum up to zero.
As a convenience, one amount may be left blank; it will be inferred so as to balance the transaction. As a convenience, one amount may be left blank; it will be inferred so as to balance the transaction.
@ -377,7 +377,7 @@ to zero (separately from other postings). Eg:
assets:cash $-10 ; <- these balance assets:cash $-10 ; <- these balance
expenses:food $7 ; <- expenses:food $7 ; <-
expenses:food $3 ; <- expenses:food $3 ; <-
[assets:checking:budget:food] $-10 ; <- and these balance [assets:checking:budget:food] $-10 ; <- and these balance
[assets:checking:available] $10 ; <- [assets:checking:available] $10 ; <-
(something:else) $5 ; <- not required to balance (something:else) $5 ; <- not required to balance
``` ```
@ -403,7 +403,7 @@ Account names can be [aliased](#rewriting-accounts).
After the account name, there is usually an amount. After the account name, there is usually an amount.
(Important: between account name and amount, there must be **two or more spaces**.) (Important: between account name and amount, there must be **two or more spaces**.)
hledger's amount format is flexible, supporting several international formats. hledger's amount format is flexible, supporting several international formats.
Here are some examples. Here are some examples.
Amounts have a number (the "quantity"): Amounts have a number (the "quantity"):
@ -442,7 +442,7 @@ A decimal mark (decimal point) can be written with a period or a comma:
In the integer part of the quantity (left of the decimal mark), groups In the integer part of the quantity (left of the decimal mark), groups
of digits can optionally be separated by a "digit group mark" - a of digits can optionally be separated by a "digit group mark" - a
space, comma, or period (different from the decimal mark): space, comma, or period (different from the decimal mark):
$1,000,000.00 $1,000,000.00
EUR 2.000.000,00 EUR 2.000.000,00
INR 9,99,99,999.00 INR 9,99,99,999.00
@ -458,7 +458,7 @@ hledger will treat them both as decimal marks by default (cf
[#793](https://github.com/simonmichael/hledger/issues/793)). [#793](https://github.com/simonmichael/hledger/issues/793)).
If you use digit group marks, If you use digit group marks,
to prevent confusion and undetected typos to prevent confusion and undetected typos
we recommend you write [commodity directives](#declaring-commodities) we recommend you write [commodity directives](#declaring-commodities)
at the top of the file to explicitly declare the decimal mark (and at the top of the file to explicitly declare the decimal mark (and
optionally a digit group mark). optionally a digit group mark).
Note, these formats ("amount styles") are specific to each commodity, Note, these formats ("amount styles") are specific to each commodity,
@ -533,7 +533,7 @@ There are several ways to record a transaction price:
(Ledger users: Ledger uses a different [syntax](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices) (Ledger users: Ledger uses a different [syntax](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-Lot-Prices)
for fixed prices, `{=UNITPRICE}`, which hledger currently ignores). for fixed prices, `{=UNITPRICE}`, which hledger currently ignores).
Use the [`-B/--cost`](hledger.html#reporting-options) flag to convert Use the [`-B/--cost`](hledger.html#reporting-options) flag to convert
amounts to their transaction price's commodity, if any. amounts to their transaction price's commodity, if any.
(mnemonic: "B" is from "cost Basis", as in Ledger). (mnemonic: "B" is from "cost Basis", as in Ledger).
Eg here is how -B affects the balance report for the example above: Eg here is how -B affects the balance report for the example above:
@ -548,7 +548,7 @@ $ hledger bal -N --flat -B
``` ```
Note -B is sensitive to the order of postings when a transaction price is inferred: Note -B is sensitive to the order of postings when a transaction price is inferred:
the inferred price will be in the commodity of the last amount. the inferred price will be in the commodity of the last amount.
So if example 3's postings are reversed, while the transaction So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different: is equivalent, -B shows something different:
@ -565,10 +565,10 @@ $ hledger bal -N --flat -B
## Balance Assertions ## Balance Assertions
hledger supports hledger supports
[Ledger-style balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions) [Ledger-style balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions)
in journal files. in journal files.
These look like, for example, `= EXPECTEDBALANCE` following a posting's amount. These look like, for example, `= EXPECTEDBALANCE` following a posting's amount.
Eg here we assert the expected dollar balance in accounts a and b after Eg here we assert the expected dollar balance in accounts a and b after
each posting: each posting:
@ -624,17 +624,17 @@ instead.
The asserted balance must be a simple single-commodity amount, and in The asserted balance must be a simple single-commodity amount, and in
fact the assertion checks only this commodity's balance within the fact the assertion checks only this commodity's balance within the
(possibly multi-commodity) account balance. (possibly multi-commodity) account balance.
This is how assertions work in Ledger also. This is how assertions work in Ledger also.
We could call this a "partial" balance assertion. We could call this a "partial" balance assertion.
To assert the balance of more than one commodity in an account, To assert the balance of more than one commodity in an account,
you can write multiple postings, each asserting one commodity's balance. you can write multiple postings, each asserting one commodity's balance.
You can make a stronger "total" balance assertion by writing a You can make a stronger "total" balance assertion by writing a
double equals sign (`== EXPECTEDBALANCE`). double equals sign (`== EXPECTEDBALANCE`).
This asserts that there are no other unasserted commodities in the account This asserts that there are no other unasserted commodities in the account
(or, that their balance is 0). (or, that their balance is 0).
``` journal ``` journal
2013/1/1 2013/1/1
@ -685,9 +685,9 @@ and because [balance *assignments*](#balance-assignments) do use them (see below
### Assertions and subaccounts ### Assertions and subaccounts
The balance assertions above (`=` and `==`) do not count the balance The balance assertions above (`=` and `==`) do not count the balance
from subaccounts; they check the account's exclusive balance only. from subaccounts; they check the account's exclusive balance only.
You can assert the balance including subaccounts by writing `=*` or `==*`, eg: You can assert the balance including subaccounts by writing `=*` or `==*`, eg:
```journal ```journal
2019/1/1 2019/1/1
@ -718,7 +718,7 @@ These are like [balance assertions](#balance-assertions), but with no posting am
instead it is calculated automatically so as to satisfy the assertion. instead it is calculated automatically so as to satisfy the assertion.
This can be a convenience during data entry, eg when setting opening balances: This can be a convenience during data entry, eg when setting opening balances:
```journal ```journal
; starting a new journal, set asset account balances ; starting a new journal, set asset account balances
2016/1/1 opening balances 2016/1/1 opening balances
assets:checking = $409.32 assets:checking = $409.32
assets:savings = $735.24 assets:savings = $735.24
@ -733,7 +733,7 @@ or when adjusting a balance to reality:
expenses:misc expenses:misc
``` ```
The calculated amount depends on the account's balance in the commodity at that point The calculated amount depends on the account's balance in the commodity at that point
(which depends on the previously-dated postings of the commodity to that account (which depends on the previously-dated postings of the commodity to that account
since the last balance assertion or assignment). since the last balance assertion or assignment).
Note that using balance assignments makes your journal a little less explicit; Note that using balance assignments makes your journal a little less explicit;
@ -759,10 +759,10 @@ $ hledger print --explicit
A directive is a line in the journal beginning with a special keyword, A directive is a line in the journal beginning with a special keyword,
that influences how the journal is processed. that influences how the journal is processed.
hledger's directives are based on a subset of Ledger's, but there are many differences hledger's directives are based on a subset of Ledger's, but there are many differences
(and also some differences between hledger versions). (and also some differences between hledger versions).
Directives' behaviour and interactions can get a little bit [complex](https://github.com/simonmichael/hledger/issues/793), Directives' behaviour and interactions can get a little bit [complex](https://github.com/simonmichael/hledger/issues/793),
so here is a table summarising the directives and their effects, with links to more detailed docs. so here is a table summarising the directives and their effects, with links to more detailed docs.
<!-- <style> --> <!-- <style> -->
@ -818,7 +818,7 @@ Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f options on the command line, 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 typically last only until the end of their defining file. note that directives which affect input typically last only until the end of their defining file.
This provides more simplicity and predictability, eg reports are not changed by writing file options in a different order. This provides more simplicity and predictability, eg reports are not changed by writing file options in a different order.
It can be surprising at times though. It can be surprising at times though.
<!-- TODO: retest <!-- TODO: retest
For example, in: For example, in:
@ -939,11 +939,11 @@ D $1,000.00
b b
``` ```
As with the `commodity` directive, the amount must always be written with a decimal point. As with the `commodity` directive, the amount must always be written with a decimal point.
### Market prices ### Market prices
The `P` directive declares a market price, which is The `P` directive declares a market price, which is
an exchange rate between two commodities on a certain date. an exchange rate between two commodities on a certain date.
(In Ledger, they are called "historical prices".) (In Ledger, they are called "historical prices".)
These are often obtained from a These are often obtained from a
@ -961,7 +961,7 @@ P DATE COMMODITYA COMMODITYBAMOUNT
- COMMODITYBAMOUNT is an [amount](#amounts) (symbol and quantity) in a - COMMODITYBAMOUNT is an [amount](#amounts) (symbol and quantity) in a
second commodity, giving the price in commodity B of one unit of commodity A. second commodity, giving the price in commodity B of one unit of commodity A.
These two market price directives say that one euro was worth 1.35 US dollars during 2009, These two market price directives say that one euro was worth 1.35 US dollars during 2009,
and $1.40 from 2010 onward: and $1.40 from 2010 onward:
```journal ```journal
P 2009/1/1 € $1.35 P 2009/1/1 € $1.35
@ -973,7 +973,7 @@ to another commodity using these prices.
### Declaring accounts ### Declaring accounts
`account` directives can be used to pre-declare accounts. `account` directives can be used to pre-declare accounts.
Though not required, they can provide several benefits: Though not required, they can provide several benefits:
- They can document your intended chart of accounts, providing a reference. - They can document your intended chart of accounts, providing a reference.
@ -981,11 +981,11 @@ Though not required, they can provide several benefits:
- They can help hledger know your accounts' types (asset, liability, equity, revenue, expense), - They can help hledger know your accounts' types (asset, liability, equity, revenue, expense),
useful for reports like balancesheet and incomestatement. useful for reports like balancesheet and incomestatement.
- They control account display order in reports, allowing non-alphabetic sorting - They control account display order in reports, allowing non-alphabetic sorting
(eg Revenues to appear above Expenses). (eg Revenues to appear above Expenses).
- They help with account name completion - They help with account name completion
in the add command, hledger-iadd, hledger-web, ledger-mode etc. in the add command, hledger-iadd, hledger-web, ledger-mode etc.
The simplest form is just the word `account` followed by a hledger-style The simplest form is just the word `account` followed by a hledger-style
[account name](journal.html#account-names), eg: [account name](journal.html#account-names), eg:
```journal ```journal
account assets:bank:checking account assets:bank:checking
@ -1004,7 +1004,7 @@ An example of both:
account assets:bank:checking ; same-line comment, note 2+ spaces before ; account assets:bank:checking ; same-line comment, note 2+ spaces before ;
; next-line comment ; next-line comment
; another with tag, acctno:12345 (not used yet) ; another with tag, acctno:12345 (not used yet)
``` ```
Same-line comments are not supported by Ledger, or hledger <1.13. Same-line comments are not supported by Ledger, or hledger <1.13.
@ -1016,7 +1016,7 @@ We also allow (and ignore) Ledger-style indented subdirectives, just for compati
```journal ```journal
account assets:bank:checking account assets:bank:checking
format blah blah ; <- subdirective, ignored format blah blah ; <- subdirective, ignored
``` ```
Here is the full syntax of account directives: Here is the full syntax of account directives:
```journal ```journal
@ -1036,7 +1036,7 @@ This is used by a few accounting-aware reports such as [balancesheet][], [income
##### Auto-detected account types ##### Auto-detected account types
If you name your top-level accounts with some variation of If you name your top-level accounts with some variation of
`assets`, `liabilities`/`debts`, `equity`, `revenues`/`income`, or `expenses`, `assets`, `liabilities`/`debts`, `equity`, `revenues`/`income`, or `expenses`,
their types are detected automatically. their types are detected automatically.
@ -1068,14 +1068,14 @@ account expenses X
##### Overriding auto-detected types ##### Overriding auto-detected types
If you ever override the types of those auto-detected english account names mentioned above, If you ever override the types of those auto-detected english account names mentioned above,
you might need to help the reports a bit. Eg: you might need to help the reports a bit. Eg:
```journal ```journal
; make "liabilities" not have the liability type - who knows why ; make "liabilities" not have the liability type - who knows why
account liabilities ; type:E account liabilities ; type:E
; we need to ensure some other account has the liability type, ; we need to ensure some other account has the liability type,
; otherwise balancesheet would still show "liabilities" under Liabilities ; otherwise balancesheet would still show "liabilities" under Liabilities
account - ; type:L account - ; type:L
``` ```
@ -1109,17 +1109,17 @@ Note that sorting is done at each level of the account tree (within each group o
And currently, this directive: And currently, this directive:
```journal ```journal
account other:zoo account other:zoo
``` ```
would influence the position of `zoo` among `other`'s subaccounts, but not the position of `other` among the top-level accounts. would influence the position of `zoo` among `other`'s subaccounts, but not the position of `other` among the top-level accounts.
This means: 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 - 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`). - sibling accounts stay together (you couldn't display `x:y` in between `a:b` and `a:c`).
### Rewriting accounts ### Rewriting accounts
You can define account alias rules which rewrite your account names, or parts of them, You can define account alias rules which rewrite your account names, or parts of them,
before generating reports. before generating reports.
This can be useful for: This can be useful for:
- expanding shorthand account names to their full form, allowing easier data entry and a less verbose journal - expanding shorthand account names to their full form, allowing easier data entry and a less verbose journal
@ -1180,7 +1180,7 @@ alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
``` ```
Also note that REPLACEMENT continues to the end of line (or on command line, Also note that REPLACEMENT continues to the end of line (or on command line,
to end of option argument), so it can contain trailing whitespace. to end of option argument), so it can contain trailing whitespace.
#### Combining aliases #### Combining aliases
@ -1281,7 +1281,7 @@ read this whole section - or at least these tips:
### Periodic rule syntax ### Periodic rule syntax
A periodic transaction rule looks like a normal journal entry, A periodic transaction rule looks like a normal journal entry,
with the date replaced by a tilde (`~`) followed by a with the date replaced by a tilde (`~`) followed by a
[period expression](hledger.html#period-expressions) [period expression](hledger.html#period-expressions)
(mnemonic: `~` looks like a recurring sine wave.): (mnemonic: `~` looks like a recurring sine wave.):
```journal ```journal
@ -1294,7 +1294,7 @@ the start date must fall on a natural boundary of the interval.
Eg `monthly from 2018/1/1` is valid, but `monthly from 2018/1/15` is not. Eg `monthly from 2018/1/1` is valid, but `monthly from 2018/1/15` is not.
Partial or relative dates (M/D, D, tomorrow, last week) in the period expression Partial or relative dates (M/D, D, tomorrow, last week) in the period expression
can work (useful or not). They will be relative to today's date, unless can work (useful or not). They will be relative to today's date, unless
a Y default year directive is in effect, in which case they will be relative to Y/1/1. a Y default year directive is in effect, in which case they will be relative to Y/1/1.
### Two spaces between period expression and description! ### Two spaces between period expression and description!
@ -1323,9 +1323,9 @@ So,
With the `--forecast` flag, each periodic transaction rule generates With the `--forecast` flag, each periodic transaction rule generates
future transactions recurring at the specified interval. future transactions recurring at the specified interval.
These are not saved in the journal, but appear in all reports. These are not saved in the journal, but appear in all reports.
They will look like normal transactions, but with an extra They will look like normal transactions, but with an extra
[tag](journal.html#tags): [tag](journal.html#tags):
- `generated-transaction:~ PERIODICEXPR` - shows that this was generated by a periodic transaction rule, and the period - `generated-transaction:~ PERIODICEXPR` - shows that this was generated by a periodic transaction rule, and the period
There is also a hidden tag, with an underscore prefix, which does not appear in hledger's output: There is also a hidden tag, with an underscore prefix, which does not appear in hledger's output:
@ -1350,7 +1350,7 @@ where "today" means the current date at report time.
The "later of" rule ensures that forecast transactions do not overlap normal transactions in time; The "later of" rule ensures that forecast transactions do not overlap normal transactions in time;
they will begin only after normal transactions end. they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, Forecasting can be useful for estimating balances into the future,
and experimenting with different scenarios. and experimenting with different scenarios.
Note the start date logic means that forecasted transactions are automatically replaced Note the start date logic means that forecasted transactions are automatically replaced
by normal transactions as you add those. by normal transactions as you add those.
@ -1387,7 +1387,7 @@ Currently just one kind of change is possible - adding extra postings, which we
These rules become active when you use the `--auto` flag. These rules become active when you use the `--auto` flag.
A transaction modifier rule looks much like a normal transaction A transaction modifier rule looks much like a normal transaction
except the first line is an equals sign followed by a except the first line is an equals sign followed by a
[query](hledger.html#queries) that matches certain postings [query](hledger.html#queries) that matches certain postings
(mnemonic: `=` suggests matching). (mnemonic: `=` suggests matching).
And each "posting" is actually a posting-generating rule: And each "posting" is actually a posting-generating rule:
@ -1402,7 +1402,7 @@ And each "posting" is actually a posting-generating rule:
These posting-generating rules look like normal postings, except the amount can be: These posting-generating rules look like normal postings, except the amount can be:
- a normal amount with a commodity symbol, eg `$2`. This will be used as-is. - a normal amount with a commodity symbol, eg `$2`. This will be used as-is.
- a number, eg `2`. The commodity symbol (if any) from the matched posting will be added to this. - a number, eg `2`. The commodity symbol (if any) from the matched posting will be added to this.
- a numeric multiplier, eg `*2` (a star followed by a number N). The matched posting's amount (and total price, if any) will be multiplied by N. - a numeric multiplier, eg `*2` (a star followed by a number N). The matched posting's amount (and total price, if any) will be multiplied by N.
- a multiplier with a commodity symbol, eg `*$2` (a star, number N, and symbol S). The matched posting's amount will be multiplied by N, and its commodity symbol will be replaced with S. - a multiplier with a commodity symbol, eg `*$2` (a star, number N, and symbol S). The matched posting's amount will be multiplied by N, and its commodity symbol will be replaced with S.
@ -1410,7 +1410,7 @@ A query term containing spaces must be enclosed in single or double
quotes, as on the command line. Eg, note the quotes around the second query term below: quotes, as on the command line. Eg, note the quotes around the second query term below:
```journal ```journal
= expenses:groceries 'expenses:dining out' = expenses:groceries 'expenses:dining out'
(budget:funds:dining out) *-1 (budget:funds:dining out) *-1
``` ```
These rules have global effect - a rule appearing anywhere in your data can potentially affect any transaction, including transactions recorded above it or in another file. These rules have global effect - a rule appearing anywhere in your data can potentially affect any transaction, including transactions recorded above it or in another file.
@ -1468,7 +1468,7 @@ background.
### Auto posting tags ### Auto posting tags
Postings added by transaction modifiers will have some extra [tags](#tags-1): Postings added by transaction modifiers will have some extra [tags](#tags-1):
- `generated-posting:= QUERY` - shows this was generated by an auto posting rule, and the query - `generated-posting:= QUERY` - shows this was generated by an auto posting rule, and the query
- `_generated-posting:= QUERY` - a hidden tag, which does not appear in hledger's output. - `_generated-posting:= QUERY` - a hidden tag, which does not appear in hledger's output.
@ -1479,4 +1479,3 @@ Also, any transaction that has been changed by transaction modifier rules will h
- `modified:` - this transaction was modified - `modified:` - this transaction was modified
- `_modified:` - a hidden tag not appearing in the comment; this transaction was modified "just now". - `_modified:` - a hidden tag not appearing in the comment; this transaction was modified "just now".

14
hledger-lib/hledger_timedot.m4.md
View File

@ -17,7 +17,7 @@ It is convenient for approximate and retroactive time logging,
eg when the real-time clock-in/out required with a timeclock file is too precise or too interruptive. eg when the real-time clock-in/out required with a timeclock file is too precise or too interruptive.
It can be formatted like a bar chart, making clear at a glance where time was spent. It can be formatted like a bar chart, making clear at a glance where time was spent.
Though called "timedot", this format is read by hledger as commodityless quantities, Though called "timedot", this format is read by hledger as commodityless quantities,
so it could be used to represent dated quantities other than time. so it could be used to represent dated quantities other than time.
In the docs below we'll assume it's time. In the docs below we'll assume it's time.
@ -31,16 +31,16 @@ Quantities can be written as:
- a sequence of dots (.) representing quarter hours. - a sequence of dots (.) representing quarter hours.
Spaces may optionally be used for grouping and readability. Spaces may optionally be used for grouping and readability.
Eg: .... .. Eg: .... ..
- an integral or decimal number, representing hours. - an integral or decimal number, representing hours.
Eg: 1.5 Eg: 1.5
- an integral or decimal number immediately followed by a unit symbol - an integral or decimal number immediately followed by a unit symbol
`s`, `m`, `h`, `d`, `w`, `mo`, or `y`, representing seconds, minutes, hours, days `s`, `m`, `h`, `d`, `w`, `mo`, or `y`, representing seconds, minutes, hours, days
weeks, months or years respectively. weeks, months or years respectively.
Eg: 90m. Eg: 90m.
The following equivalencies are assumed, currently: The following equivalencies are assumed, currently:
1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. 1m = 60s, 1h = 60m, 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
Blank lines and lines beginning with #, ; or * are ignored. Blank lines and lines beginning with #, ; or * are ignored.
@ -50,7 +50,7 @@ An example:
# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc. # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
2016/2/1 2016/2/1
inc:client1 .... .... .... .... .... .... inc:client1 .... .... .... .... .... ....
fos:haskell .... .. fos:haskell .... ..
biz:research . biz:research .
2016/2/2 2016/2/2

86
hledger-ui/hledger-ui.m4.md
View File

@ -41,12 +41,12 @@ _web_({{
hledger-ui is hledger's terminal interface, providing an efficient full-window text UI hledger-ui is hledger's terminal interface, providing an efficient full-window text UI
for viewing accounts and transactions, and some limited data entry capability. for viewing accounts and transactions, and some limited data entry capability.
It is easier than hledger's command-line interface, and It is easier than hledger's command-line interface, and
sometimes quicker and more convenient than the web interface. sometimes quicker and more convenient than the web interface.
Note hledger-ui has some different defaults (experimental): Note hledger-ui has some different defaults (experimental):
- it generates rule-based transactions and postings by default (--forecast and --auto are always on). - it generates rule-based transactions and postings by default (--forecast and --auto are always on).
- it hides transactions dated in the future by default (change this with --future or the F key). - it hides transactions dated in the future by default (change this with --future or the F key).
Like hledger, it reads _files_ Like hledger, it reads _files_
@ -68,7 +68,7 @@ Any QUERYARGS are interpreted as a hledger search query which filters the data.
: start in the (first) matched account's register screen : start in the (first) matched account's register screen
`--change` `--change`
: show period balances (changes) at startup instead of historical balances : show period balances (changes) at startup instead of historical balances
`-F --flat` `-F --flat`
: show accounts as a list (default) : show accounts as a list (default)
@ -97,34 +97,34 @@ which should contain one command line option/argument per line.
# KEYS # KEYS
`?` shows a help dialog listing all keys. `?` shows a help dialog listing all keys.
(Some of these also appear in the quick help at the bottom of each screen.) (Some of these also appear in the quick help at the bottom of each screen.)
Press `?` again (or `ESCAPE`, or `LEFT`) to close it. Press `?` again (or `ESCAPE`, or `LEFT`) to close it.
The following keys work on most screens: The following keys work on most screens:
The cursor keys navigate: The cursor keys navigate:
`right` (or `enter`) goes deeper, `right` (or `enter`) goes deeper,
`left` returns to the previous screen, `left` returns to the previous screen,
`up`/`down`/`page up`/`page down`/`home`/`end` move up and down through lists. `up`/`down`/`page up`/`page down`/`home`/`end` move up and down through lists.
Vi-style (`h`/`j`/`k`/`l`) and Emacs-style (`CTRL-p`/`CTRL-n`/`CTRL-f`/`CTRL-b`) movement keys are also supported. Vi-style (`h`/`j`/`k`/`l`) and Emacs-style (`CTRL-p`/`CTRL-n`/`CTRL-f`/`CTRL-b`) movement keys are also supported.
A tip: movement speed is limited by your keyboard repeat rate, A tip: movement speed is limited by your keyboard repeat rate,
to move faster you may want to adjust it. to move faster you may want to adjust it.
(If you're on a mac, the Karabiner app is one way to do that.) (If you're on a mac, the Karabiner app is one way to do that.)
With shift pressed, the cursor keys adjust the report period, With shift pressed, the cursor keys adjust the report period,
limiting the transactions to be shown (by default, all are shown). limiting the transactions to be shown (by default, all are shown).
`shift-down/up` steps downward and upward through these standard report period durations: `shift-down/up` steps downward and upward through these standard report period durations:
year, quarter, month, week, day. year, quarter, month, week, day.
Then, `shift-left/right` moves to the previous/next period. Then, `shift-left/right` moves to the previous/next period.
`t` sets the report period to today. `t` sets the report period to today.
With the `--watch` option, when viewing a "current" period With the `--watch` option, when viewing a "current" period
(the current day, week, month, quarter, or year), (the current day, week, month, quarter, or year),
the period will move automatically to track the current date. the period will move automatically to track the current date.
To set a non-standard period, you can use `/` and a `date:` query. To set a non-standard period, you can use `/` and a `date:` query.
`/` lets you set a general filter query limiting the data shown, `/` lets you set a general filter query limiting the data shown,
using the same [query terms](hledger.html#queries) as in hledger and hledger-web. using the same [query terms](hledger.html#queries) as in hledger and hledger-web.
While editing the query, you can use [CTRL-a/e/d/k, BS, cursor keys](http://hackage.haskell.org/package/brick-0.7/docs/Brick-Widgets-Edit.html#t:Editor); While editing the query, you can use [CTRL-a/e/d/k, BS, cursor keys](http://hackage.haskell.org/package/brick-0.7/docs/Brick-Widgets-Edit.html#t:Editor);
press `ENTER` to set it, or `ESCAPE`to cancel. press `ENTER` to set it, or `ESCAPE`to cancel.
There are also keys for quickly adjusting some common filters like account depth and transaction status (see below). There are also keys for quickly adjusting some common filters like account depth and transaction status (see below).
`BACKSPACE` or `DELETE` removes all filters, showing all transactions. `BACKSPACE` or `DELETE` removes all filters, showing all transactions.
@ -133,31 +133,31 @@ As mentioned above, hledger-ui shows auto-generated periodic transactions,
and hides future transactions (auto-generated or not) by default. and hides future transactions (auto-generated or not) by default.
`F` toggles showing and hiding these future transactions. `F` toggles showing and hiding these future transactions.
This is similar to using a query like `date:-tomorrow`, but more convenient. This is similar to using a query like `date:-tomorrow`, but more convenient.
(experimental) (experimental)
`ESCAPE` removes all filters and jumps back to the top screen. `ESCAPE` removes all filters and jumps back to the top screen.
Or, it cancels a minibuffer edit or help dialog in progress. Or, it cancels a minibuffer edit or help dialog in progress.
`CTRL-l` redraws the screen and centers the selection if possible `CTRL-l` redraws the screen and centers the selection if possible
(selections near the top won't be centered, since we don't scroll above the top). (selections near the top won't be centered, since we don't scroll above the top).
`g` reloads from the data file(s) and updates the current screen and any `g` reloads from the data file(s) and updates the current screen and any
previous screens. (With large files, this could cause a noticeable pause.) previous screens. (With large files, this could cause a noticeable pause.)
`I` toggles balance assertion checking. `I` toggles balance assertion checking.
Disabling balance assertions temporarily can be useful for troubleshooting. Disabling balance assertions temporarily can be useful for troubleshooting.
`a` runs command-line hledger's add command, and reloads the updated file. `a` runs command-line hledger's add command, and reloads the updated file.
This allows some basic data entry. This allows some basic data entry.
`A` is like `a`, but runs the [hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) tool, `A` is like `a`, but runs the [hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) tool,
which provides a terminal interface. which provides a terminal interface.
This key will be available if `hledger-iadd` is installed in $PATH. This key will be available if `hledger-iadd` is installed in $PATH.
`E` runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (`emacsclient -a "" -nw`) on the journal file. `E` runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (`emacsclient -a "" -nw`) on the journal file.
With some editors (emacs, vi), the cursor will be positioned at the current transaction With some editors (emacs, vi), the cursor will be positioned at the current transaction
when invoked from the register and transaction screens, and at the error location (if possible) when invoked from the register and transaction screens, and at the error location (if possible)
when invoked from the error screen. when invoked from the error screen.
`q` quits the application. `q` quits the application.
@ -173,18 +173,18 @@ default valuation commodity (like toggling the
Note, "current market value" means the value on the report end date if specified, otherwise today. Note, "current market value" means the value on the report end date if specified, otherwise today.
To see the value on another date, you can temporarily set that as the report end date. To see the value on another date, you can temporarily set that as the report end date.
Eg: to see a transaction as it was valued on july 30, Eg: to see a transaction as it was valued on july 30,
go to the accounts or register screen, go to the accounts or register screen,
press `/`, press `/`,
and add ` date:-7/30` to the query. and add ` date:-7/30` to the query.
At most one of cost or value mode can be active at once. At most one of cost or value mode can be active at once.
There's not yet any visual reminder when cost or value mode is active; There's not yet any visual reminder when cost or value mode is active;
for now pressing `B` `B` `V` should reliably reset to normal mode. for now pressing `B` `B` `V` should reliably reset to normal mode.
With --watch active, if you save an edit to the journal file With --watch active, if you save an edit to the journal file
while viewing the transaction screen in cost or value mode, while viewing the transaction screen in cost or value mode,
the `B`/`V` keys will stop working. the `B`/`V` keys will stop working.
To work around, press g to force a manual reload, or exit the transaction screen. To work around, press g to force a manual reload, or exit the transaction screen.
Additional screen-specific keys are described below. Additional screen-specific keys are described below.
@ -198,7 +198,7 @@ It lists accounts and their balances, like hledger's balance command.
By default, it shows all accounts and their latest ending balances (including the balances of subaccounts). By default, it shows all accounts and their latest ending balances (including the balances of subaccounts).
if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions. if you specify a query on the command line, it shows just the matched accounts and the balances from matched transactions.
Account names are shown as a flat list by default. Press `T` to toggle tree mode. Account names are shown as a flat list by default. Press `T` to toggle tree mode.
In flat mode, account balances are exclusive of subaccounts, except where subaccounts are hidden by a depth limit (see below). In flat mode, account balances are exclusive of subaccounts, except where subaccounts are hidden by a depth limit (see below).
In tree mode, all account balances are inclusive of subaccounts. In tree mode, all account balances are inclusive of subaccounts.
@ -208,19 +208,19 @@ Or use `-` to decrease and `+`/`=` to increase the depth limit.
To remove the depth limit, set it higher than the maximum account depth, or press `ESCAPE`. To remove the depth limit, set it higher than the maximum account depth, or press `ESCAPE`.
`H` toggles between showing historical balances or period balances. `H` toggles between showing historical balances or period balances.
Historical balances (the default) are ending balances at the end of the report period, Historical balances (the default) are ending balances at the end of the report period,
taking into account all transactions before that date (filtered by the filter query if any), taking into account all transactions before that date (filtered by the filter query if any),
including transactions before the start of the report period. In other words, historical including transactions before the start of the report period. In other words, historical
balances are what you would see on a bank statement for that account (unless disturbed by balances are what you would see on a bank statement for that account (unless disturbed by
a filter query). Period balances ignore transactions before the report start date, so they a filter query). Period balances ignore transactions before the report start date, so they
show the change in balance during the report period. They are more useful eg when viewing a time log. show the change in balance during the report period. They are more useful eg when viewing a time log.
`U` toggles filtering by [unmarked status](journal.html#status), `U` toggles filtering by [unmarked status](journal.html#status),
including or excluding unmarked postings in the balances. including or excluding unmarked postings in the balances.
Similarly, `P` toggles pending postings, Similarly, `P` toggles pending postings,
and `C` toggles cleared postings. and `C` toggles cleared postings.
(By default, balances include all postings; (By default, balances include all postings;
if you activate one or two status filters, only those postings are included; if you activate one or two status filters, only those postings are included;
and if you activate all three, the filter is removed.) and if you activate all three, the filter is removed.)
`R` toggles real mode, in which [virtual postings](journal.html#virtual-postings) are ignored. `R` toggles real mode, in which [virtual postings](journal.html#virtual-postings) are ignored.
@ -233,14 +233,14 @@ Press `right` or `enter` to view an account's transactions register.
## Register screen ## Register screen
This screen shows the transactions affecting a particular account, like a check register. This screen shows the transactions affecting a particular account, like a check register.
Each line represents one transaction and shows: Each line represents one transaction and shows:
- the other account(s) involved, in abbreviated form. - the other account(s) involved, in abbreviated form.
(If there are both real and virtual postings, it (If there are both real and virtual postings, it
shows only the accounts affected by real postings.) shows only the accounts affected by real postings.)
- the overall change to the current account's balance; - the overall change to the current account's balance;
positive for an inflow to this account, negative for an outflow. positive for an inflow to this account, negative for an outflow.
- the running historical total or period total for the current account, after the transaction. - the running historical total or period total for the current account, after the transaction.
@ -248,18 +248,18 @@ This can be toggled with `H`.
Similar to the accounts screen, the historical total is affected by transactions Similar to the accounts screen, the historical total is affected by transactions
(filtered by the filter query) before the report start date, while the period total is not. (filtered by the filter query) before the report start date, while the period total is not.
If the historical total is not disturbed by a filter query, it will be the If the historical total is not disturbed by a filter query, it will be the
running historical balance you would see on a bank register for the current account. running historical balance you would see on a bank register for the current account.
Transactions affecting this account's subaccounts will be included in the register Transactions affecting this account's subaccounts will be included in the register
if the accounts screen is in tree mode, if the accounts screen is in tree mode,
or if it's in flat mode but this account has subaccounts which are not shown due to a depth limit. or if it's in flat mode but this account has subaccounts which are not shown due to a depth limit.
In other words, the register always shows the transactions contributing to the balance shown on the accounts screen. In other words, the register always shows the transactions contributing to the balance shown on the accounts screen.
Tree mode/flat mode can be toggled with `T` here also. Tree mode/flat mode can be toggled with `T` here also.
`U` toggles filtering by [unmarked status](journal.html#status), showing or hiding unmarked transactions. `U` toggles filtering by [unmarked status](journal.html#status), showing or hiding unmarked transactions.
Similarly, `P` toggles pending transactions, and `C` toggles cleared transactions. Similarly, `P` toggles pending transactions, and `C` toggles cleared transactions.
(By default, transactions with all statuses are shown; (By default, transactions with all statuses are shown;
if you activate one or two status filters, only those transactions are shown; if you activate one or two status filters, only those transactions are shown;
and if you activate all three, the filter is removed.) and if you activate all three, the filter is removed.)
`R` toggles real mode, in which [virtual postings](journal.html#virtual-postings) are ignored. `R` toggles real mode, in which [virtual postings](journal.html#virtual-postings) are ignored.
@ -300,7 +300,7 @@ press g again to reload and resume normal operation.
# ENVIRONMENT # ENVIRONMENT
**COLUMNS** **COLUMNS**
The screen width to use. The screen width to use.
Default: the full terminal width. Default: the full terminal width.
_LEDGER_FILE_ _LEDGER_FILE_
@ -327,7 +327,7 @@ times with an editor macro) can cause problems at least on OSX.
Symptoms include: unresponsive UI, periodic resetting of the cursor Symptoms include: unresponsive UI, periodic resetting of the cursor
position, momentary display of parse errors, high CPU usage eventually position, momentary display of parse errors, high CPU usage eventually
subsiding, and possibly a small but persistent build-up of CPU usage subsiding, and possibly a small but persistent build-up of CPU usage
until the program is restarted. until the program is restarted.
Also, if you are viewing files mounted from another machine, `--watch` Also, if you are viewing files mounted from another machine, `--watch`
requires that both machine clocks are roughly in step. requires that both machine clocks are roughly in step.

38
hledger-web/hledger-web.m4.md
View File

@ -54,10 +54,10 @@ For more about this see hledger(1), hledger_journal(5) etc.
# OPTIONS # OPTIONS
Command-line options and arguments may be used to set an initial Command-line options and arguments may be used to set an initial
filter on the data. These filter options are not shown in the web UI, filter on the data. These filter options are not shown in the web UI,
but it will be applied in addition to any search query entered there. but it will be applied in addition to any search query entered there.
Note: if invoking hledger-web as a hledger subcommand, write `--` before options, Note: if invoking hledger-web as a hledger subcommand, write `--` before options,
as shown in the synopsis above. as shown in the synopsis above.
`--serve` `--serve`
@ -114,7 +114,7 @@ browser window, and will exit after two minutes of inactivity (no
requests and no browser windows viewing it). requests and no browser windows viewing it).
With `--serve`, it just runs the web app without exiting, and logs With `--serve`, it just runs the web app without exiting, and logs
requests to the console. requests to the console.
With `--serve-api`, only the JSON web api (see below) is served, With `--serve-api`, only the JSON web api (see below) is served,
with the usual HTML server-side web UI disabled. with the usual HTML server-side web UI disabled.
By default the server listens on IP address 127.0.0.1, accessible only to local requests. By default the server listens on IP address 127.0.0.1, accessible only to local requests.
@ -123,14 +123,14 @@ You can use `--host` to change this, eg `--host 0.0.0.0` to listen on all config
Similarly, use `--port` to set a TCP port other than 5000, eg if you are Similarly, use `--port` to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances. running multiple hledger-web instances.
Both of these options are ignored when `--socket` is used. In this case, it Both of these options are ignored when `--socket` is used. In this case, it
creates an `AF_UNIX` socket file at the supplied path and uses that for communication. creates an `AF_UNIX` socket file at the supplied path and uses that for communication.
This is an alternative way of running multiple hledger-web instances behind This is an alternative way of running multiple hledger-web instances behind
a reverse proxy that handles authentication for different users. a reverse proxy that handles authentication for different users.
The path can be derived in a predictable way, eg by using the username within the path. The path can be derived in a predictable way, eg by using the username within the path.
As an example, `nginx` as reverse proxy can use the variabel `$remote_user` to As an example, `nginx` as reverse proxy can use the variabel `$remote_user` to
derive a path from the username used in a [HTTP basic authentication](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/). derive a path from the username used in a [HTTP basic authentication](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/).
The following `proxy_pass` directive allows access to all `hledger-web` The following `proxy_pass` directive allows access to all `hledger-web`
instances that created a socket in `/tmp/hledger/`: instances that created a socket in `/tmp/hledger/`:
``` ```
@ -147,27 +147,27 @@ eg for better caching or cookie-less serving on high performance websites.
# PERMISSIONS # PERMISSIONS
By default, hledger-web allows anyone who can reach it to view the journal By default, hledger-web allows anyone who can reach it to view the journal
and to add new transactions, but not to change existing data. and to add new transactions, but not to change existing data.
You can restrict who can reach it by You can restrict who can reach it by
- setting the IP address it listens on (see `--host` above). - setting the IP address it listens on (see `--host` above).
By default it listens on 127.0.0.1, accessible to all users on the local machine. By default it listens on 127.0.0.1, accessible to all users on the local machine.
- putting it behind an authenticating proxy, using eg apache or nginx - putting it behind an authenticating proxy, using eg apache or nginx
- custom firewall rules - custom firewall rules
You can restrict what the users who reach it can do, by You can restrict what the users who reach it can do, by
- using the `--capabilities=CAP[,CAP..]` flag when you start it, - using the `--capabilities=CAP[,CAP..]` flag when you start it,
enabling one or more of the following capabilities. The default value is `view,add`: enabling one or more of the following capabilities. The default value is `view,add`:
- `view` - allows viewing the journal file and all included files - `view` - allows viewing the journal file and all included files
- `add` - allows adding new transactions to the main journal file - `add` - allows adding new transactions to the main journal file
- `manage` - allows editing, uploading or downloading the main or included files - `manage` - allows editing, uploading or downloading the main or included files
- using the `--capabilities-header=HTTPHEADER` flag to specify a HTTP header - using the `--capabilities-header=HTTPHEADER` flag to specify a HTTP header
from which it will read capabilities to enable. hledger-web on Sandstorm from which it will read capabilities to enable. hledger-web on Sandstorm
uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions. uses the X-Sandstorm-Permissions header to integrate with Sandstorm's permissions.
This is disabled by default. This is disabled by default.
# EDITING, UPLOADING, DOWNLOADING # EDITING, UPLOADING, DOWNLOADING
@ -175,10 +175,10 @@ You can restrict what the users who reach it can do, by
If you enable the `manage` capability mentioned above, If you enable the `manage` capability mentioned above,
you'll see a new "spanner" button to the right of the search form. you'll see a new "spanner" button to the right of the search form.
Clicking this will let you edit, upload, or download the journal Clicking this will let you edit, upload, or download the journal
file or any files it includes. file or any files it includes.
Note, unlike any other hledger command, in this mode you (or any visitor) Note, unlike any other hledger command, in this mode you (or any visitor)
can alter or wipe the data files. can alter or wipe the data files.
Normally whenever a file is changed in this way, hledger-web saves a numbered backup Normally whenever a file is changed in this way, hledger-web saves a numbered backup
(assuming file permissions allow it, the disk is not full, etc.) (assuming file permissions allow it, the disk is not full, etc.)
@ -186,7 +186,7 @@ hledger-web is not aware of version control systems, currently; if you use one,
you'll have to arrange to commit the changes yourself (eg with a cron job you'll have to arrange to commit the changes yourself (eg with a cron job
or a file watcher like entr). or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (eg with failing balance assertions) are prevented.
(Probably. This needs re-testing.) (Probably. This needs re-testing.)
@ -194,7 +194,7 @@ Changes which would leave the journal file(s) unparseable or non-valid
hledger-web detects changes made to the files by other means (eg if you edit hledger-web detects changes made to the files by other means (eg if you edit
it directly, outside of hledger-web), and it will show the new data it directly, outside of hledger-web), and it will show the new data
when you reload the page or navigate to a new page. when you reload the page or navigate to a new page.
If a change makes a file unparseable, If a change makes a file unparseable,
hledger-web will display an error message until the file has been fixed. hledger-web will display an error message until the file has been fixed.

129
hledger/hledger.m4.md
View File

@ -37,11 +37,11 @@ interfaces). Its basic function is to read a plain text file describing
financial transactions (in accounting terms, a general journal) and financial transactions (in accounting terms, a general journal) and
print useful reports on standard output, or export them as CSV. hledger print useful reports on standard output, or export them as CSV. hledger
can also read some other file formats such as CSV files, translating can also read some other file formats such as CSV files, translating
them to journal format. Additionally, hledger lists other hledger-\* them to journal format. Additionally, hledger lists other hledger-\*
executables found in the user’s \$PATH and can invoke them as subcommands. executables found in the user’s \$PATH and can invoke them as subcommands.
hledger reads _files_ hledger reads _files_
If using `$LEDGER_FILE`, note this must be a real environment variable, If using `$LEDGER_FILE`, note this must be a real environment variable,
not a shell variable. not a shell variable.
You can specify standard input with `-f-`. You can specify standard input with `-f-`.
@ -66,7 +66,7 @@ To get started, you can either save some entries like the above in
`~/.hledger.journal`, or run `hledger add` and follow the prompts. Then `~/.hledger.journal`, or run `hledger add` and follow the prompts. Then
try some commands like `hledger print` or `hledger balance`. try some commands like `hledger print` or `hledger balance`.
Run `hledger` with no arguments for a list of commands. Run `hledger` with no arguments for a list of commands.
# COMMON TASKS # COMMON TASKS
Here are some quick examples of how to do some basic tasks with hledger. Here are some quick examples of how to do some basic tasks with hledger.
@ -92,7 +92,7 @@ Find more docs, chat, mail list, reddit, issue tracker:
hledger has an extensive and powerful command line interface. We hledger has an extensive and powerful command line interface. We
strive to keep it simple and ergonomic, but you may run into one of strive to keep it simple and ergonomic, but you may run into one of
the confusing real world details described in OPTIONS, below. the confusing real world details described in OPTIONS, below.
If that happens, here are some tips that may help: If that happens, here are some tips that may help:
- command-specific options must go after the command (it's fine to put all options there) (`hledger CMD OPTS ARGS`) - command-specific options must go after the command (it's fine to put all options there) (`hledger CMD OPTS ARGS`)
@ -248,10 +248,10 @@ If you let it pile up, expect it to take longer as you hunt down errors and disc
A typical workflow: A typical workflow:
1. Reconcile cash. 1. Reconcile cash.
Count what's in your wallet. Count what's in your wallet.
Compare with what hledger reports (`hledger bal cash`). Compare with what hledger reports (`hledger bal cash`).
If they are different, try to remember the missing transaction, If they are different, try to remember the missing transaction,
or look for the error in the already-recorded transactions. or look for the error in the already-recorded transactions.
A register report can be helpful (`hledger reg cash`). A register report can be helpful (`hledger reg cash`).
If you can't find the error, add an adjustment transaction. If you can't find the error, add an adjustment transaction.
@ -269,7 +269,7 @@ A typical workflow:
or add an adjustment transaction, similar to the above. or add an adjustment transaction, similar to the above.
Unlike the cash case, you can usually compare the transaction history and running balance from your bank Unlike the cash case, you can usually compare the transaction history and running balance from your bank
with the one reported by `hledger reg checking -C`. with the one reported by `hledger reg checking -C`.
This will be easier if you generally record transaction dates This will be easier if you generally record transaction dates
quite similar to your bank's clearing dates. quite similar to your bank's clearing dates.
3. Repeat for other asset/liability accounts. 3. Repeat for other asset/liability accounts.
@ -449,7 +449,7 @@ If using version control, don't forget to `git add` the new file.
## General options ## General options
To see general usage help, including general options To see general usage help, including general options
which are supported by most hledger commands, run `hledger -h`. which are supported by most hledger commands, run `hledger -h`.
General help options: General help options:
@ -470,14 +470,14 @@ To see options for a particular command, including command-specific options, run
Command-specific options must be written after the command name, eg: `hledger print -x`. Command-specific options must be written after the command name, eg: `hledger print -x`.
Additionally, if the command is an [addon](#commands), Additionally, if the command is an [addon](#commands),
you may need to put its options after a double-hyphen, eg: `hledger ui -- --watch`. you may need to put its options after a double-hyphen, eg: `hledger ui -- --watch`.
Or, you can run the addon executable directly: `hledger-ui --watch`. Or, you can run the addon executable directly: `hledger-ui --watch`.
## Command arguments ## Command arguments
Most hledger commands accept arguments after the command name, Most hledger commands accept arguments after the command name,
which are often a [query](#queries), filtering the data in some way. which are often a [query](#queries), filtering the data in some way.
You can save a set of command line options/arguments in a file, You can save a set of command line options/arguments in a file,
and then reuse them by writing `@FILENAME` as a command line argument. and then reuse them by writing `@FILENAME` as a command line argument.
@ -500,7 +500,7 @@ Good:
-X=USD -X=USD
For special characters (see below), use one less level of quoting than For special characters (see below), use one less level of quoting than
you would at the command prompt. you would at the command prompt.
Bad: Bad:
-X"$" -X"$"
@ -537,7 +537,7 @@ The [print](hledger.html#print) command instead shows transactions which:
- have no postings matching any of the negative account terms AND - have no postings matching any of the negative account terms AND
- match all the other terms. - match all the other terms.
The following kinds of search terms can be used. The following kinds of search terms can be used.
Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount. Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount.
**`REGEX`, `acct:REGEX`** **`REGEX`, `acct:REGEX`**
@ -613,7 +613,7 @@ Generally you can mix options and query arguments, and the resulting query will
## Special characters in arguments and queries ## Special characters in arguments and queries
In shell command lines, option and argument values which contain "problematic" characters, In shell command lines, option and argument values which contain "problematic" characters,
ie spaces, ie spaces,
and also characters significant to your shell such as `<`, `>`, `(`, `)`, `|` and `$`, and also characters significant to your shell such as `<`, `>`, `(`, `)`, `|` and `$`,
should be escaped by enclosing them in quotes or by writing backslashes before the characters. should be escaped by enclosing them in quotes or by writing backslashes before the characters.
Eg: Eg:
@ -622,7 +622,7 @@ Eg:
### More escaping ### More escaping
Characters significant both to the shell and in [regular expressions](#regular-expressions) Characters significant both to the shell and in [regular expressions](#regular-expressions)
may need one extra level of escaping. These include parentheses, the pipe symbol and the dollar sign. may need one extra level of escaping. These include parentheses, the pipe symbol and the dollar sign.
Eg, to match the dollar symbol, bash users should do: Eg, to match the dollar symbol, bash users should do:
@ -634,9 +634,9 @@ or:
### Even more escaping ### Even more escaping
When hledger runs an addon executable (eg you type `hledger ui`, hledger runs `hledger-ui`), When hledger runs an addon executable (eg you type `hledger ui`, hledger runs `hledger-ui`),
it de-escapes command-line options and arguments once, so you might need to *triple*-escape. it de-escapes command-line options and arguments once, so you might need to *triple*-escape.
Eg in bash, running the ui command and matching the dollar sign, it's: Eg in bash, running the ui command and matching the dollar sign, it's:
`hledger ui cur:'\\$'` `hledger ui cur:'\\$'`
@ -662,10 +662,10 @@ You can always avoid the extra escaping for addons by running the addon directly
### Less escaping ### Less escaping
Inside an [argument file](#argument-expansion), Inside an [argument file](#argument-expansion),
or in the search field of hledger-ui or hledger-web, or in the search field of hledger-ui or hledger-web,
or at a GHCI prompt, or at a GHCI prompt,
you need one less level of escaping than at the command line. you need one less level of escaping than at the command line.
And backslashes may work better than quotes. And backslashes may work better than quotes.
Eg: Eg:
`ghci> :main balance cur:\$` `ghci> :main balance cur:\$`
@ -684,8 +684,8 @@ forms, etc.)
This requires a well-configured environment. Here are some tips: This requires a well-configured environment. Here are some tips:
- A system locale must be configured, and it must be one that can - A system locale must be configured, and it must be one that can
decode the characters being used. decode the characters being used.
In bash, you can set a locale like this: `export LANG=en_US.UTF-8`. In bash, you can set a locale like this: `export LANG=en_US.UTF-8`.
There are some more details in [Troubleshooting](#troubleshooting). There are some more details in [Troubleshooting](#troubleshooting).
This step is essential - without it, hledger will quit on encountering This step is essential - without it, hledger will quit on encountering
a non-ascii character (as with all GHC-compiled programs). a non-ascii character (as with all GHC-compiled programs).
@ -706,7 +706,7 @@ This requires a well-configured environment. Here are some tips:
## Input files ## Input files
hledger reads transactions from a data file (and the add command writes to it). hledger reads transactions from a data file (and the add command writes to it).
By default this file is `$HOME/.hledger.journal` By default this file is `$HOME/.hledger.journal`
(or on Windows, something like `C:/Users/USER/.hledger.journal`). (or on Windows, something like `C:/Users/USER/.hledger.journal`).
You can override this with the `$LEDGER_FILE` environment variable: You can override this with the `$LEDGER_FILE` environment variable:
```shell ```shell
@ -723,7 +723,7 @@ The file name `-` (hyphen) means standard input:
$ cat some.journal | hledger -f- $ cat some.journal | hledger -f-
``` ```
Usually the data file is in hledger's journal format, Usually the data file is in hledger's journal format,
but it can also be one of several other formats, listed below. but it can also be one of several other formats, listed below.
hledger detects the format automatically based on the file extension, hledger detects the format automatically based on the file extension,
or if that is not recognised, by trying each built-in "reader" in turn: or if that is not recognised, by trying each built-in "reader" in turn:
@ -735,8 +735,8 @@ or if that is not recognised, by trying each built-in "reader" in turn:
| `timedot` | timedot files (approximate time logging) | `.timedot` | | `timedot` | timedot files (approximate time logging) | `.timedot` |
| `csv` | comma-separated values (data interchange) | `.csv` | | `csv` | comma-separated values (data interchange) | `.csv` |
If needed (eg to ensure correct error messages when a file has the "wrong" extension), If needed (eg to ensure correct error messages when a file has the "wrong" extension),
you can force a specific reader/format by prepending it to the file path with a colon. you can force a specific reader/format by prepending it to the file path with a colon.
Examples: Examples:
```shell ```shell
$ hledger -f csv:/some/csv-file.dat stats $ hledger -f csv:/some/csv-file.dat stats
@ -754,8 +754,8 @@ or concatenate the files, eg: `cat a.journal b.journal | hledger -f- CMD`.
## Output destination ## Output destination
Some commands (print, register, stats, the balance commands) Some commands (print, register, stats, the balance commands)
can write their output to a destination other than the console. can write their output to a destination other than the console.
This is controlled by the `-o/--output-file` option. This is controlled by the `-o/--output-file` option.
```shell ```shell
@ -799,18 +799,18 @@ Some things to note:
must be enclosed in forward slashes (`/REGEX/`). Elsewhere in hledger, must be enclosed in forward slashes (`/REGEX/`). Elsewhere in hledger,
these are not required. these are not required.
- In queries, to match a regular expression metacharacter like `$` - In queries, to match a regular expression metacharacter like `$`
as a literal character, prepend a backslash. Eg to search for amounts with the as a literal character, prepend a backslash. Eg to search for amounts with the
dollar sign in hledger-web, write `cur:\$`. dollar sign in hledger-web, write `cur:\$`.
- On the command line, some metacharacters like `$` have a special - On the command line, some metacharacters like `$` have a special
meaning to the shell and so must be escaped at least once more. meaning to the shell and so must be escaped at least once more.
See [Special characters](#special-characters). See [Special characters](#special-characters).
## Smart dates ## Smart dates
hledger's user interfaces accept a flexible "smart date" syntax (unlike dates in the journal file). hledger's user interfaces accept a flexible "smart date" syntax (unlike dates in the journal file).
Smart dates allow some english words, can be relative to today's date, Smart dates allow some english words, can be relative to today's date,
and can have less-significant date parts omitted (defaulting to 1). and can have less-significant date parts omitted (defaulting to 1).
Examples: Examples:
@ -843,10 +843,10 @@ Most hledger reports show the full span of time represented by the journal data,
So, the effective report start and end dates will be the earliest and latest transaction or posting dates found in the journal. So, the effective report start and end dates will be the earliest and latest transaction or posting dates found in the journal.
Often you will want to see a shorter time span, such as the current month. Often you will want to see a shorter time span, such as the current month.
You can specify a start and/or end date using You can specify a start and/or end date using
[`-b/--begin`](#reporting-options), [`-b/--begin`](#reporting-options),
[`-e/--end`](#reporting-options), [`-e/--end`](#reporting-options),
[`-p/--period`](#period-expressions) [`-p/--period`](#period-expressions)
or a [`date:` query](#queries) (described below). or a [`date:` query](#queries) (described below).
All of these accept the [smart date](#smart-dates) syntax. All of these accept the [smart date](#smart-dates) syntax.
@ -882,7 +882,7 @@ A report interval can be specified so that commands like
reports into multiple subperiods. The basic intervals can be reports into multiple subperiods. The basic intervals can be
selected with one of `-D/--daily`, `-W/--weekly`, `-M/--monthly`, selected with one of `-D/--daily`, `-W/--weekly`, `-M/--monthly`,
`-Q/--quarterly`, or `-Y/--yearly`. More complex intervals may be `-Q/--quarterly`, or `-Y/--yearly`. More complex intervals may be
specified with a [period expression](#period-expressions). specified with a [period expression](#period-expressions).
Report intervals can not be specified with a [query](#queries). Report intervals can not be specified with a [query](#queries).
## Period expressions ## Period expressions
@ -935,10 +935,10 @@ like so:
| `-p "2009/1/1"` | just that day; equivalent to “2009/1/1 to 2009/1/2” | | `-p "2009/1/1"` | just that day; equivalent to “2009/1/1 to 2009/1/2” |
The argument of `-p` can also begin with, or be, a [report interval](#report-intervals) expression. The argument of `-p` can also begin with, or be, a [report interval](#report-intervals) expression.
The basic report intervals are `daily`, `weekly`, `monthly`, `quarterly`, or `yearly`, The basic report intervals are `daily`, `weekly`, `monthly`, `quarterly`, or `yearly`,
which have the same effect as the `-D`,`-W`,`-M`,`-Q`, or `-Y` flags. which have the same effect as the `-D`,`-W`,`-M`,`-Q`, or `-Y` flags.
Between report interval and start/end dates (if any), the word `in` is optional. Between report interval and start/end dates (if any), the word `in` is optional.
Examples: Examples:
| | | |
|-----------------------------------------| |-----------------------------------------|
@ -961,7 +961,7 @@ For example:
| `-p "yearly from 2009-12-29"` | starts on 2009/01/01, first day of 2009 | | `-p "yearly from 2009-12-29"` | starts on 2009/01/01, first day of 2009 |
The following more complex report intervals are also supported: The following more complex report intervals are also supported:
`biweekly`, `biweekly`,
`bimonthly`, `bimonthly`,
`every day|week|month|quarter|year`, `every day|week|month|quarter|year`,
`every N days|weeks|months|quarters|years`. `every N days|weeks|months|quarters|years`.
@ -1005,7 +1005,7 @@ Show historical balances at end of 15th each month (N is exclusive end date):
Group postings from start of wednesday to end of next tuesday (N is start date and exclusive end date): Group postings from start of wednesday to end of next tuesday (N is start date and exclusive end date):
`hledger register checking -p "every 3rd day of week"` `hledger register checking -p "every 3rd day of week"`
## Depth limiting ## Depth limiting
@ -1013,20 +1013,20 @@ With the `--depth N` option (short form: `-N`), commands like [account](#account
and [register](#register) will show only the uppermost accounts in the account and [register](#register) will show only the uppermost accounts in the account
tree, down to level N. Use this when you want a summary with less detail. tree, down to level N. Use this when you want a summary with less detail.
This flag has the same effect as a `depth:` query argument This flag has the same effect as a `depth:` query argument
(so `-2`, `--depth=2` or `depth:2` are basically equivalent). (so `-2`, `--depth=2` or `depth:2` are basically equivalent).
## Pivoting ## Pivoting
Normally hledger sums amounts, and organizes them in a hierarchy, based on account name. Normally hledger sums amounts, and organizes them in a hierarchy, based on account name.
The `--pivot FIELD` option causes it to sum and organize hierarchy based on the value of some other field instead. The `--pivot FIELD` option causes it to sum and organize hierarchy based on the value of some other field instead.
FIELD can be: FIELD can be:
`code`, `description`, `payee`, `note`, `code`, `description`, `payee`, `note`,
or the full name (case insensitive) of any [tag](journal.html#tags). or the full name (case insensitive) of any [tag](journal.html#tags).
As with account names, values containing `colon:separated:parts` will be displayed hierarchically in reports. As with account names, values containing `colon:separated:parts` will be displayed hierarchically in reports.
`--pivot` is a general option affecting all reports; you can think of hledger transforming `--pivot` is a general option affecting all reports; you can think of hledger transforming
the journal before any other processing, replacing every posting's account name with the journal before any other processing, replacing every posting's account name with
the value of the specified field on that posting, inheriting it from the transaction the value of the specified field on that posting, inheriting it from the transaction
or using a blank value if it's not present. or using a blank value if it's not present.
An example: An example:
@ -1071,7 +1071,7 @@ $ hledger balance --pivot member acct:.
### -B: Cost ### -B: Cost
The `-B/--cost` flag converts amounts to their cost (or selling price) at transaction time, The `-B/--cost` flag converts amounts to their cost (or selling price) at transaction time,
if they have a [transaction price](journal.html#transaction-prices) specified. if they have a [transaction price](journal.html#transaction-prices) specified.
This flag is equivalent to `--value=cost`, described below. This flag is equivalent to `--value=cost`, described below.
@ -1150,11 +1150,11 @@ The TYPE part basically selects either "cost", or "market value" plus a valuatio
or in multiperiod reports, market prices on the last day of each subperiod. or in multiperiod reports, market prices on the last day of each subperiod.
`--value=now` `--value=now`
: Convert amounts to their value in default valuation commodity using current market prices : Convert amounts to their value in default valuation commodity using current market prices
(as of when report is generated). (as of when report is generated).
`--value=YYYY-MM-DD` `--value=YYYY-MM-DD`
: Convert amounts to their value in default valuation commodity using market prices : Convert amounts to their value in default valuation commodity using market prices
on this date. on this date.
The default valuation commodity is the commodity mentioned in the most The default valuation commodity is the commodity mentioned in the most
@ -1170,7 +1170,7 @@ hledger will do its best to convert amounts to this commodity, using:
- reverse prices (declared prices from valuation to source commodity, inverted) - reverse prices (declared prices from valuation to source commodity, inverted)
- indirect prices (prices calculated from the shortest chain of declared or reverse prices from source to valuation commodity) - indirect prices (prices calculated from the shortest chain of declared or reverse prices from source to valuation commodity)
in that order. in that order.
Here are some examples showing the effect of `--value` as seen with `print`: Here are some examples showing the effect of `--value` as seen with `print`:
@ -1299,7 +1299,7 @@ Here is a reference for how `--value` currently affects each part of hledger's r
It's work in progress, but may be useful for troubleshooting or reporting bugs. It's work in progress, but may be useful for troubleshooting or reporting bugs.
See also the definitions and notes below. See also the definitions and notes below.
If you find problems, please report them, ideally with a reproducible example. If you find problems, please report them, ideally with a reproducible example.
Related: Related:
[#329](https://github.com/simonmichael/hledger/issues/329), [#329](https://github.com/simonmichael/hledger/issues/329),
[#1083](https://github.com/simonmichael/hledger/issues/1083). [#1083](https://github.com/simonmichael/hledger/issues/1083).
@ -1366,11 +1366,11 @@ listed as subcommands.
Run a subcommand by writing its name as first argument (eg `hledger Run a subcommand by writing its name as first argument (eg `hledger
incomestatement`). You can also write one of the standard short aliases incomestatement`). You can also write one of the standard short aliases
displayed in parentheses in the command list (`hledger b`), or any displayed in parentheses in the command list (`hledger b`), or any
any unambiguous prefix of a command name (`hledger inc`). any unambiguous prefix of a command name (`hledger inc`).
Here are all the builtin commands in alphabetical order. Here are all the builtin commands in alphabetical order.
See also `hledger` for a more organised command list, See also `hledger` for a more organised command list,
and `hledger CMD -h` for detailed command help. and `hledger CMD -h` for detailed command help.
## accounts ## accounts
@ -1493,14 +1493,14 @@ _include_({{Hledger/Cli/Commands/Test.md}})
hledger also searches for external add-on commands, and will include these in the commands list. hledger also searches for external add-on commands, and will include these in the commands list.
These are programs or scripts in your PATH whose name starts with `hledger-` These are programs or scripts in your PATH whose name starts with `hledger-`
and ends with a recognised file extension and ends with a recognised file extension
(currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`). (currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`).
Add-ons can be invoked like any hledger command, but there are a few things to be aware of. Add-ons can be invoked like any hledger command, but there are a few things to be aware of.
Eg if the `hledger-web` add-on is installed, Eg if the `hledger-web` add-on is installed,
- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help. - `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help.
- Flags specific to the add-on must have a preceding `--` to hide them from hledger. - Flags specific to the add-on must have a preceding `--` to hide them from hledger.
So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`. So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`.
@ -1515,7 +1515,7 @@ Two important add-ons are the hledger-ui and hledger-web user interfaces.
These are maintained and released along with hledger: These are maintained and released along with hledger:
### ui ### ui
[hledger-ui](hledger-ui.html) provides an efficient terminal interface. [hledger-ui](hledger-ui.html) provides an efficient terminal interface.
### web ### web
[hledger-web](hledger-web.html) provides a simple web interface. [hledger-web](hledger-web.html) provides a simple web interface.
@ -1525,12 +1525,12 @@ Third party add-ons, maintained separately from hledger, include:
### iadd ### iadd
[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) [hledger-iadd](http://hackage.haskell.org/package/hledger-iadd)
is a more interactive, terminal UI replacement for the [add command](hledger.html#add). is a more interactive, terminal UI replacement for the [add command](hledger.html#add).
### interest ### interest
[hledger-interest](http://hackage.haskell.org/package/hledger-interest) [hledger-interest](http://hackage.haskell.org/package/hledger-interest)
generates interest transactions for an account according to various schemes. generates interest transactions for an account according to various schemes.
<!-- ### autosync --> <!-- ### autosync -->
@ -1547,7 +1547,7 @@ directory. These are typically prototypes and not guaranteed to work.
# ENVIRONMENT # ENVIRONMENT
**COLUMNS** **COLUMNS**
The screen width used by the register command. The screen width used by the register command.
Default: the full terminal width. Default: the full terminal width.
m4_dnl Standard LEDGER_FILE description: m4_dnl Standard LEDGER_FILE description:
@ -1584,17 +1584,17 @@ Here are some issues you might encounter when you run hledger
[mail list](http://list.hledger.org) or [mail list](http://list.hledger.org) or
[bug tracker](http://bugs.hledger.org)): [bug tracker](http://bugs.hledger.org)):
**Successfully installed, but "No command 'hledger' found"** **Successfully installed, but "No command 'hledger' found"**\
stack and cabal install binaries into a special directory, which stack and cabal install binaries into a special directory, which
should be added to your PATH environment variable. Eg on unix-like should be added to your PATH environment variable. Eg on unix-like
systems, that is ~/.local/bin and ~/.cabal/bin respectively. systems, that is ~/.local/bin and ~/.cabal/bin respectively.
**I set a custom LEDGER_FILE, but hledger is still using the default file** **I set a custom LEDGER_FILE, but hledger is still using the default file**\
`LEDGER_FILE` should be a real environment variable, not just a shell variable. `LEDGER_FILE` should be a real environment variable, not just a shell variable.
The command `env | grep LEDGER_FILE` should show it. The command `env | grep LEDGER_FILE` should show it.
You may need to use `export`. Here's an [explanation](http://stackoverflow.com/a/7411509). You may need to use `export`. Here's an [explanation](http://stackoverflow.com/a/7411509).
**"Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors** **"Illegal byte sequence" or "Invalid or incomplete multibyte or wide character" errors**\
In order to handle non-ascii letters and symbols (like £), hledger needs In order to handle non-ascii letters and symbols (like £), hledger needs
an appropriate locale. This is usually configured system-wide; you can an appropriate locale. This is usually configured system-wide; you can
also configure it temporarily. The locale may need to be one that also configure it temporarily. The locale may need to be one that
@ -1638,4 +1638,3 @@ $ LANG=fr_FR.utf8 hledger -f my.journal print
Note some platforms allow variant locale spellings, but not all (ubuntu Note some platforms allow variant locale spellings, but not all (ubuntu
accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`). accepts `fr_FR.UTF8`, mac osx requires exactly `fr_FR.UTF-8`).