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

regen manuals

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2019-02-20 13:15:41 -08:00
parent 861baadb2b
commit 8620e5414f
6 changed files with 697 additions and 479 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
hledger-lib/hledger_journal.5
View File

@ -491,10 +491,10 @@ which is more correct and provides better error checking.
.SS Balance Assertions
.PP
hledger supports Ledger\-style balance assertions in journal files.
These look like \f[C]=EXPECTEDBALANCE\f[] following a posting\[aq]s
amount.
Eg in this example we assert the expected dollar balance in accounts a
and b after each posting:
These look like, for example, \f[C]=\ EXPECTEDBALANCE\f[] following a
posting\[aq]s amount.
Eg here we assert the expected dollar balance in accounts a and b after
each posting:
.IP
.nf
\f[C]
@ -513,7 +513,7 @@ and report an error if any of them fail.
Balance assertions can protect you from, eg, inadvertently disrupting
reconciled balances while cleaning up old entries.
You can disable them temporarily with the
\f[C]\-\-ignore\-assertions\f[] flag, which can be useful for
\f[C]\-I/\-\-ignore\-assertions\f[] flag, which can be useful for
troubleshooting or for reading Ledger files.
.SS Assertions and ordering
.PP
@ -558,11 +558,10 @@ We could call this a "partial" balance assertion.
To assert the balance of more than one commodity in an account, you can
write multiple postings, each asserting one commodity\[aq]s balance.
.PP
You can make a stronger kind of balance assertion, by writing a double
equals sign (\f[C]==EXPECTEDBALANCE\f[]).
This "complete" balance assertion asserts the absence of other
commodities (or, that their balance is 0, which to hledger is
equivalent.)
You can make a stronger "total" balance assertion by writing a double
equals sign (\f[C]==\ EXPECTEDBALANCE\f[]).
This asserts that there are no other unasserted commodities in the
account (or, that their balance is 0).
.IP
.nf
\f[C]
@ -619,29 +618,19 @@ generate balance assertions with prices), and because balance
\f[I]assignments\f[] do use them (see below).
.SS Assertions and subaccounts
.PP
Balance assertions do not count the balance from subaccounts; they check
the posted account\[aq]s exclusive balance.
For example:
The balance assertions above (\f[C]=\f[] and \f[C]==\f[]) do not count
the balance from subaccounts; they check the account\[aq]s exclusive
balance only.
You can assert the balance including subaccounts by writing \f[C]=*\f[]
or \f[C]==*\f[], eg:
.IP
.nf
\f[C]
1/1
\ \ checking:fund\ \ \ 1\ =\ 1\ \ ;\ post\ to\ this\ subaccount,\ its\ balance\ is\ now\ 1
\ \ checking\ \ \ \ \ \ \ \ 1\ =\ 1\ \ ;\ post\ to\ the\ parent\ account,\ its\ exclusive\ balance\ is\ now\ 1
\ \ equity
\f[]
.fi
.PP
The balance report\[aq]s flat mode shows these exclusive balances more
clearly:
.IP
.nf
\f[C]
$\ hledger\ bal\ checking\ \-\-flat
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 1\ \ checking:fund
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 2
2019/1/1
\ \ equity:opening\ balances
\ \ checking:a\ \ \ \ \ \ \ 5
\ \ checking:b\ \ \ \ \ \ \ 5
\ \ checking\ \ \ \ \ \ \ \ \ 1\ \ ==*\ 11
\f[]
.fi
.SS Assertions and virtual postings

194
hledger-lib/hledger_journal.info
View File

@ -449,9 +449,9 @@ File: hledger_journal.info, Node: Balance Assertions, Next: Balance Assignment
======================
hledger supports Ledger-style balance assertions in journal files.
These look like '=EXPECTEDBALANCE' following a posting's amount. Eg in
this example we assert the expected dollar balance in accounts a and b
after each posting:
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 each posting:
2013/1/1
a $1 =$1
@ -465,8 +465,8 @@ after each posting:
assertions and report an error if any of them fail. Balance assertions
can protect you from, eg, inadvertently disrupting reconciled balances
while cleaning up old entries. You can disable them temporarily with
the '--ignore-assertions' flag, which can be useful for troubleshooting
or for reading Ledger files.
the '-I/--ignore-assertions' flag, which can be useful for
troubleshooting or for reading Ledger files.
* Menu:
* Assertions and ordering::
@ -533,10 +533,10 @@ This is how assertions work in Ledger also. We could call this a
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 make a stronger kind of balance assertion, by writing a
double equals sign ('==EXPECTEDBALANCE'). This "complete" balance
assertion asserts the absence of other commodities (or, that their
balance is 0, which to hledger is equivalent.)
You can make a stronger "total" balance assertion by writing a double
equals sign ('== EXPECTEDBALANCE'). This asserts that there are no
other unasserted commodities in the account (or, that their balance is
0).
2013/1/1
a $1
@ -591,22 +591,16 @@ File: hledger_journal.info, Node: Assertions and subaccounts, Next: Assertions
1.9.6 Assertions and subaccounts
--------------------------------
Balance assertions do not count the balance from subaccounts; they check
the posted account's exclusive balance. For example:
The balance assertions above ('=' and '==') do not count the balance
from subaccounts; they check the account's exclusive balance only. You
can assert the balance including subaccounts by writing '=*' or '==*',
eg:
1/1
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
equity
The balance report's flat mode shows these exclusive balances more
clearly:
$ hledger bal checking --flat
1 checking
1 checking:fund
--------------------
2
2019/1/1
equity:opening balances
checking:a 5
checking:b 5
checking 1 ==* 11

File: hledger_journal.info, Node: Assertions and virtual postings, Next: Assertions and precision, Prev: Assertions and subaccounts, Up: Balance Assertions
@ -1619,81 +1613,81 @@ Node: Virtual Postings15032
Ref: #virtual-postings15191
Node: Balance Assertions16411
Ref: #balance-assertions16586
Node: Assertions and ordering17537
Ref: #assertions-and-ordering17723
Node: Assertions and included files18423
Ref: #assertions-and-included-files18664
Node: Assertions and multiple -f options18997
Ref: #assertions-and-multiple--f-options19251
Node: Assertions and commodities19383
Ref: #assertions-and-commodities19613
Node: Assertions and prices20801
Ref: #assertions-and-prices21013
Node: Assertions and subaccounts21453
Ref: #assertions-and-subaccounts21680
Node: Assertions and virtual postings22201
Ref: #assertions-and-virtual-postings22441
Node: Assertions and precision22583
Ref: #assertions-and-precision22774
Node: Balance Assignments23041
Ref: #balance-assignments23222
Node: Balance assignments and prices24386
Ref: #balance-assignments-and-prices24558
Node: Transaction prices24782
Ref: #transaction-prices24951
Node: Comments27219
Ref: #comments27353
Node: Tags28523
Ref: #tags28641
Node: Directives30043
Ref: #directives30186
Node: Comment blocks35793
Ref: #comment-blocks35938
Node: Including other files36114
Ref: #including-other-files36294
Node: Default year36702
Ref: #default-year36871
Node: Declaring commodities37294
Ref: #declaring-commodities37477
Node: Default commodity38704
Ref: #default-commodity38880
Node: Market prices39516
Ref: #market-prices39681
Node: Declaring accounts40522
Ref: #declaring-accounts40698
Node: Account comments41623
Ref: #account-comments41786
Node: Account subdirectives42181
Ref: #account-subdirectives42376
Node: Account types42689
Ref: #account-types42873
Node: Account display order44517
Ref: #account-display-order44687
Node: Rewriting accounts45816
Ref: #rewriting-accounts46001
Node: Basic aliases46735
Ref: #basic-aliases46881
Node: Regex aliases47585
Ref: #regex-aliases47756
Node: Multiple aliases48474
Ref: #multiple-aliases48649
Node: end aliases49147
Ref: #end-aliases49294
Node: Default parent account49395
Ref: #default-parent-account49561
Node: Periodic transactions50445
Ref: #periodic-transactions50627
Node: Two spaces after the period expression51752
Ref: #two-spaces-after-the-period-expression51997
Node: Forecasting with periodic transactions52482
Ref: #forecasting-with-periodic-transactions52772
Node: Budgeting with periodic transactions54459
Ref: #budgeting-with-periodic-transactions54698
Node: Transaction modifiers55157
Ref: #transaction-modifiers55320
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57304
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57605
Node: EDITOR SUPPORT57983
Ref: #editor-support58101
Node: Assertions and ordering17544
Ref: #assertions-and-ordering17730
Node: Assertions and included files18430
Ref: #assertions-and-included-files18671
Node: Assertions and multiple -f options19004
Ref: #assertions-and-multiple--f-options19258
Node: Assertions and commodities19390
Ref: #assertions-and-commodities19620
Node: Assertions and prices20776
Ref: #assertions-and-prices20988
Node: Assertions and subaccounts21428
Ref: #assertions-and-subaccounts21655
Node: Assertions and virtual postings21979
Ref: #assertions-and-virtual-postings22219
Node: Assertions and precision22361
Ref: #assertions-and-precision22552
Node: Balance Assignments22819
Ref: #balance-assignments23000
Node: Balance assignments and prices24164
Ref: #balance-assignments-and-prices24336
Node: Transaction prices24560
Ref: #transaction-prices24729
Node: Comments26997
Ref: #comments27131
Node: Tags28301
Ref: #tags28419
Node: Directives29821
Ref: #directives29964
Node: Comment blocks35571
Ref: #comment-blocks35716
Node: Including other files35892
Ref: #including-other-files36072
Node: Default year36480
Ref: #default-year36649
Node: Declaring commodities37072
Ref: #declaring-commodities37255
Node: Default commodity38482
Ref: #default-commodity38658
Node: Market prices39294
Ref: #market-prices39459
Node: Declaring accounts40300
Ref: #declaring-accounts40476
Node: Account comments41401
Ref: #account-comments41564
Node: Account subdirectives41959
Ref: #account-subdirectives42154
Node: Account types42467
Ref: #account-types42651
Node: Account display order44295
Ref: #account-display-order44465
Node: Rewriting accounts45594
Ref: #rewriting-accounts45779
Node: Basic aliases46513
Ref: #basic-aliases46659
Node: Regex aliases47363
Ref: #regex-aliases47534
Node: Multiple aliases48252
Ref: #multiple-aliases48427
Node: end aliases48925
Ref: #end-aliases49072
Node: Default parent account49173
Ref: #default-parent-account49339
Node: Periodic transactions50223
Ref: #periodic-transactions50405
Node: Two spaces after the period expression51530
Ref: #two-spaces-after-the-period-expression51775
Node: Forecasting with periodic transactions52260
Ref: #forecasting-with-periodic-transactions52550
Node: Budgeting with periodic transactions54237
Ref: #budgeting-with-periodic-transactions54476
Node: Transaction modifiers54935
Ref: #transaction-modifiers55098
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57082
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57383
Node: EDITOR SUPPORT57761
Ref: #editor-support57879

End Tag Table

407
hledger-lib/hledger_journal.txt
View File

@ -358,9 +358,9 @@ FILE FORMAT
Balance Assertions
hledger supports Ledger-style balance assertions in journal files.
These look like =EXPECTEDBALANCE following a posting's amount. Eg in
this example we assert the expected dollar balance in accounts a and b
after each posting:
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 each posting:
2013/1/1
a $1 =$1
@ -374,7 +374,7 @@ FILE FORMAT
and report an error if any of them fail. Balance assertions can pro-
tect you from, eg, inadvertently disrupting reconciled balances while
cleaning up old entries. You can disable them temporarily with the
--ignore-assertions flag, which can be useful for troubleshooting or
-I/--ignore-assertions flag, which can be useful for troubleshooting or
for reading Ledger files.
Assertions and ordering
@ -412,10 +412,9 @@ FILE FORMAT
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 make a stronger kind of balance assertion, by writing a double
equals sign (==EXPECTEDBALANCE). This "complete" balance assertion
asserts the absence of other commodities (or, that their balance is 0,
which to hledger is equivalent.)
You can make a stronger "total" balance assertion by writing a double
equals sign (== EXPECTEDBALANCE). This asserts that there are no other
unasserted commodities in the account (or, that their balance is 0).
2013/1/1
a $1
@ -433,7 +432,7 @@ FILE FORMAT
a 0 == $1
It's not yet possible to make a complete assertion about a balance that
has multiple commodities. One workaround is to isolate each commodity
has multiple commodities. One workaround is to isolate each commodity
into its own subaccount:
2013/1/1
@ -447,51 +446,44 @@ FILE FORMAT
a:euro 0 == 1
Assertions and prices
Balance assertions ignore transaction prices, and should normally be
Balance assertions ignore transaction prices, and should normally be
written without one:
2019/1/1
(a) $1 @ 1 = $1
We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign-
We do allow prices to be written there, however, and print shows them,
even though they don't affect whether the assertion passes or fails.
This is for backward compatibility (hledger's close command used to
generate balance assertions with prices), and because balance assign-
ments do use them (see below).
Assertions and subaccounts
Balance assertions do not count the balance from subaccounts; they
check the posted account's exclusive balance. For example:
The balance assertions above (= and ==) do not count the balance from
subaccounts; they check the account's exclusive balance only. You can
assert the balance including subaccounts by writing =* or ==*, eg:
1/1
checking:fund 1 = 1 ; post to this subaccount, its balance is now 1
checking 1 = 1 ; post to the parent account, its exclusive balance is now 1
equity
The balance report's flat mode shows these exclusive balances more
clearly:
$ hledger bal checking --flat
1 checking
1 checking:fund
--------------------
2
2019/1/1
equity:opening balances
checking:a 5
checking:b 5
checking 1 ==* 11
Assertions and virtual postings
Balance assertions are checked against all postings, both real and vir-
tual. They are not affected by the --real/-R flag or real: query.
Assertions and precision
Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser-
Balance assertions compare the exactly calculated amounts, which are
not always what is shown by reports. Eg a commodity directive may
limit the display precision, but this will not affect balance asser-
tions. Balance assertion failure messages show exact amounts.
Balance Assignments
Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when
Ledger-style balance assignments are also supported. These are like
balance assertions, but with no posting amount on the left side of the
equals sign; instead it is calculated automatically so as to satisfy
the assertion. This can be a convenience during data entry, eg when
setting opening balances:
; starting a new journal, set asset account balances
@ -509,14 +501,14 @@ FILE FORMAT
expenses:misc
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 since the last balance assertion or assign-
at that point (which depends on the previously-dated postings of the
commodity to that account since the last balance assertion or assign-
ment). Note that using balance assignments makes your journal a little
less explicit; to know the exact amount posted, you have to run hledger
or do the calculations yourself, instead of just reading it.
Balance assignments and prices
A transaction price in a balance assignment will cause the calculated
A transaction price in a balance assignment will cause the calculated
amount to have that price attached:
2019/1/1
@ -528,9 +520,9 @@ FILE FORMAT
Transaction prices
Within a transaction, you can note an amount's price in another commod-
ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are
ity. This can be used to document the cost (in a purchase) or selling
price (in a sale). For example, transaction prices are useful to
record purchases of a foreign currency. Note transaction prices are
fixed at the time of the transaction, and do not change over time. See
also market prices, which represent prevailing exchange rates on a cer-
tain date.
@ -559,7 +551,7 @@ FILE FORMAT
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
PRICE}, which hledger currently ignores).
Use the -B/--cost flag to convert amounts to their transaction price's
Use the -B/--cost flag to convert amounts to their transaction price's
commodity, if any. (mnemonic: "B" is from "cost Basis", as in Ledger).
Eg here is how -B affects the balance report for the example above:
@ -570,8 +562,8 @@ FILE FORMAT
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
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
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. So if example 3's postings are reversed, while the transaction
is equivalent, -B shows something different:
@ -585,14 +577,14 @@ FILE FORMAT
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star
(*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their
(*) are comments, and will be ignored. (Star comments cause org-mode
nodes to be ignored, allowing emacs users to fold and navigate their
journals with org-mode or orgstruct-mode.)
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
You can attach comments to a transaction by writing them after the
description and/or indented on the following lines (before the post-
ings). Similarly, you can attach comments to an individual posting by
writing them after the amount and/or indented on the following lines.
Transaction and posting comments must begin with a semicolon (;).
Some examples:
@ -616,24 +608,24 @@ FILE FORMAT
; another comment line for posting 2
; a file comment (because not indented)
You can also comment larger regions of a file using comment and
You can also comment larger regions of a file using comment and
end comment directives.
Tags
Tags are a way to add extra labels or labelled data to postings and
Tags are a way to add extra labels or labelled data to postings and
transactions, which you can then search or pivot on.
A simple tag is a word (which may contain hyphens) followed by a full
A simple tag is a word (which may contain hyphens) followed by a full
colon, written inside a transaction or posting comment line:
2017/1/16 bought groceries ; sometag:
Tags can have a value, which is the text after the colon, up to the
Tags can have a value, which is the text after the colon, up to the
next comma or end of line, with leading/trailing whitespace removed:
expenses:food $10 ; a-posting-tag: the tag value
Note this means hledger's tag values can not contain commas or new-
Note this means hledger's tag values can not contain commas or new-
lines. Ending at commas means you can write multiple short tags on one
line, comma separated:
@ -647,69 +639,70 @@ FILE FORMAT
o "tag2" is another tag, whose value is "some value ..."
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2,
third-tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value
(a) $1 ; posting-tag:
Tags are like Ledger's metadata feature, except hledger's tag values
Tags are like Ledger's metadata feature, except hledger's tag values
are simple strings.
Directives
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. hledger's directives are
based on a subset of Ledger's, but there are many differences (and also
some differences between hledger versions).
Directives' behaviour and interactions can get a little bit complex, so
here is a table summarising the directives and their effects, with
here is a table summarising the directives and their effects, with
links to more detailed docs.
direc- end subdi- purpose can affect (as of
direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06)
tives
-------------------------------------------------------------------------------------------------
account any document account names, all entries in all
text declare account types & dis- files, before or
account any document account names, all entries in all
text declare account types & dis- files, before or
play order after
alias end aliases rewrite account names following
inline/included
entries until end
of current file or
of current file or
end directive
apply account end apply account prepend a common parent to following
apply account end apply account prepend a common parent to following
account names inline/included
entries until end
of current file or
of current file or
end directive
comment end comment ignore part of journal following
inline/included
entries until end
of current file or
of current file or
end directive
commodity format declare a commodity and its number notation:
commodity format declare a commodity and its number notation:
number notation & display following entries
style in that commodity
in all files; dis-
in all files; dis-
play style: amounts
of that commodity
in reports
D declare a commodity, number commodity: all com-
D declare a commodity, number commodity: all com-
notation & display style for modityless entries
commodityless amounts in all files; num-
ber notation: fol-
commodityless amounts in all files; num-
ber notation: fol-
lowing commodity-
less entries and
less entries and
entries in that
commodity in all
commodity in all
files; display
style: amounts of
that commodity in
@ -720,7 +713,7 @@ FILE FORMAT
commodity commodity in
reports, when -V is
used
Y declare a year for yearless following
Y declare a year for yearless following
dates inline/included
entries until end
of current file
@ -730,9 +723,9 @@ FILE FORMAT
subdirec- optional indented directive line immediately following a par-
tive ent directive
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
number how to interpret numbers when parsing journal entries (the
notation identity of the decimal separator character). (Currently
each commodity can have its own notation, even in the same
file.)
display how to display amounts of a commodity in reports (symbol side
style and spacing, digit groups, decimal separator, decimal places)
@ -740,37 +733,37 @@ FILE FORMAT
scope are affected by a directive
As you can see, directives vary in which journal entries and files they
affect, and whether they are focussed on input (parsing) or output
affect, and whether they are focussed on input (parsing) or output
(reports). Some directives have multiple effects.
If you have a journal made up of multiple files, or pass multiple -f
options on the command line, note that directives which affect input
typically last only until the end of their defining file. This pro-
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. This pro-
vides more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at
writing file options in a different order. It can be surprising at
times though.
Comment blocks
A line containing just comment starts a commented region of the file,
A line containing just comment starts a commented region of the file,
and a line containing just end comment (or the end of the current file)
ends it. See also comments.
Including other files
You can pull in the content of additional files by writing an include
You can pull in the content of additional files by writing an include
directive, like this:
include path/to/file.journal
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
If the path does not begin with a slash, it is relative to the current
file. The include file path may contain common glob patterns (e.g.
*).
The include directive can only be used in journal files. It can
The include directive can only be used in journal files. It can
include journal, timeclock or timedot files, but not CSV files.
Default year
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
You can set a default year to be used for subsequent dates which don't
specify a year. This is a line beginning with Y followed by the year.
Eg:
Y2009 ; set default year to 2009
@ -790,8 +783,8 @@ FILE FORMAT
assets
Declaring commodities
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
The commodity directive declares commodities which may be used in the
journal (though currently we do not enforce this). It may be written
on a single line, like this:
; commodity EXAMPLEAMOUNT
@ -801,8 +794,8 @@ FILE FORMAT
; separating thousands with comma.
commodity 1,000.0000 AAAA
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
or on multiple lines, using the "format" subdirective. In this case
the commodity symbol appears twice and should be the same in both
places:
; commodity SYMBOL
@ -814,19 +807,19 @@ FILE FORMAT
commodity INR
format INR 9,99,99,999.00
Commodity directives have a second purpose: they define the standard
Commodity directives have a second purpose: they define the standard
display format for amounts in the commodity. Normally the display for-
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
mat is inferred from journal entries, but this can be unpredictable;
declaring it with a commodity directive overrides this and removes
ambiguity. Towards this end, amounts in commodity directives must
always be written with a decimal point (a period or comma, followed by
0 or more decimal digits).
Default commodity
The D directive sets a default commodity (and display format), to be
The D directive sets a default commodity (and display format), to be
used for amounts without a commodity symbol (ie, plain numbers). (Note
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
this differs from Ledger's default commodity directive.) The commodity
and display format will be applied to all subsequent commodity-less
amounts, or until the next D directive.
# commodity-less amounts should be treated as dollars
@ -841,9 +834,9 @@ FILE FORMAT
a decimal point.
Market prices
The P directive declares a market price, which is an exchange rate
The P directive declares a market price, which is an exchange rate
between two commodities on a certain date. (In Ledger, they are called
"historical prices".) These are often obtained from a stock exchange,
"historical prices".) These are often obtained from a stock exchange,
cryptocurrency exchange, or the foreign exchange market.
Here is the format:
@ -854,39 +847,39 @@ FILE FORMAT
o COMMODITYA is the symbol of the commodity being priced
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
o COMMODITYBAMOUNT is an amount (symbol and quantity) in a second com-
modity, 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
These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35
P 2010/1/1 $1.40
The -V/--value flag can be used to convert reported amounts to another
The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
Declaring accounts
account directives can be used to pre-declare accounts. Though not
account directives can be used to pre-declare accounts. Though not
required, they can provide several benefits:
o They can document your intended chart of accounts, providing a refer-
ence.
o They can store extra information about accounts (account numbers,
o They can store extra information about accounts (account numbers,
notes, etc.)
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
o They can help hledger know your accounts' types (asset, liability,
equity, revenue, expense), useful for reports like balancesheet and
incomestatement.
o They control account display order in reports, allowing non-alpha-
o They control account display order in reports, allowing non-alpha-
betic sorting (eg Revenues to appear above Expenses).
o They help with account name completion in the add command,
o They help with account name completion 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, eg:
account assets:bank:checking
@ -904,7 +897,7 @@ FILE FORMAT
the next line instead.
Account subdirectives
We also allow (and ignore) Ledger-style indented subdirectives, just
We also allow (and ignore) Ledger-style indented subdirectives, just
for compatibility.:
account assets:bank:checking
@ -917,18 +910,18 @@ FILE FORMAT
[LEDGER-STYLE SUBDIRECTIVES, IGNORED]
Account types
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
hledger recognises five types (or classes) of account: Asset, Liabil-
ity, Equity, Revenue, Expense. This is used by a few accounting-aware
reports such as balancesheet, incomestatement and cashflow.
Auto-detected account types
If you name your top-level accounts with some variation of assets, lia-
bilities/debts, equity, revenues/income, or expenses, their types are
bilities/debts, equity, revenues/income, or expenses, their types are
detected automatically.
Account types declared with tags
More generally, you can declare an account's type with an account
directive, by writing a type: tag in a comment, followed by one of the
More generally, you can declare an account's type with an account
directive, by writing a type: tag in a comment, followed by one of the
words Asset, Liability, Equity, Revenue, Expense, or one of the letters
ALERX (case insensitive):
@ -939,8 +932,8 @@ FILE FORMAT
account expenses ; type:Expenses
Account types declared with account type codes
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
Or, you can write one of those letters separated from the account name
by two or more spaces, but this should probably be considered depre-
cated as of hledger 1.13:
account assets A
@ -950,7 +943,7 @@ FILE FORMAT
account expenses X
Overriding auto-detected types
If you ever override the types of those auto-detected english account
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:
; make "liabilities" not have the liability type - who knows why
@ -961,8 +954,8 @@ FILE FORMAT
account - ; type:L
Account display order
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
Account directives also set the order in which accounts are displayed,
eg in reports, the hledger-ui accounts screen, and the hledger-web
sidebar. By default accounts are listed in alphabetical order. But if
you have these account directives in the journal:
@ -984,16 +977,16 @@ FILE FORMAT
Undeclared accounts, if any, are displayed last, in alphabetical order.
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
Note that sorting is done at each level of the account tree (within
each group of sibling accounts under the same parent). And currently,
this directive:
account other:zoo
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
would influence the position of zoo among other's subaccounts, but not
the position of other among the top-level accounts. This means: - you
will sometimes declare parent accounts (eg account other above) that
you don't intend to post to, just to customize their display order -
sibling accounts stay together (you couldn't display x:y in between a:b
and a:c).
@ -1012,14 +1005,14 @@ FILE FORMAT
o customising reports
Account aliases also rewrite account names in account directives. They
do not affect account names being entered via hledger add or
do not affect account names being entered via hledger add or
hledger-web.
See also Cookbook: Rewrite account names.
Basic aliases
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
To set an account alias, use the alias directive in your journal file.
This affects all subsequent journal entries in the current file or its
included files. The spaces around the = are optional:
alias OLD = NEW
@ -1027,54 +1020,54 @@ FILE FORMAT
Or, you can use the --alias 'OLD=NEW' option on the command line. This
affects all entries. It's useful for trying out aliases interactively.
OLD and NEW are case sensitive full account names. hledger will
replace any occurrence of the old account name with the new one. Sub-
OLD and NEW are case sensitive full account names. hledger will
replace any occurrence of the old account name with the new one. Sub-
accounts are also affected. Eg:
alias checking = assets:bank:wells fargo:checking
# rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
Regex aliases
There is also a more powerful variant that uses a regular expression,
There is also a more powerful variant that uses a regular expression,
indicated by the forward slashes:
alias /REGEX/ = REPLACEMENT
or --alias '/REGEX/=REPLACEMENT'.
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
REGEX is a case-insensitive regular expression. Anywhere it matches
inside an account name, the matched part will be replaced by REPLACE-
MENT. If REGEX contains parenthesised match groups, these can be ref-
erenced by the usual numeric backreferences in REPLACEMENT. Eg:
alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
# rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
Also note that REPLACEMENT continues to the end of line (or on command
line, to end of option argument), so it can contain trailing white-
space.
Multiple aliases
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
You can define as many aliases as you like using directives or com-
mand-line options. Aliases are recursive - each alias sees the result
of applying previous ones. (This is different from Ledger, where
aliases are non-recursive by default). Aliases are applied in the fol-
lowing order:
1. alias directives, most recently seen first (recent directives take
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
2. alias options, in the order they appear on the command line
end aliases
You can clear (forget) all currently defined aliases with the
You can clear (forget) all currently defined aliases with the
end aliases directive:
end aliases
Default parent account
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
You can specify a parent account which will be prepended to all
accounts within a section of the journal. Use the apply account and
end apply account directives like so:
apply account home
@ -1091,7 +1084,7 @@ FILE FORMAT
home:food $10
home:cash $-10
If end apply account is omitted, the effect lasts to the end of the
If end apply account is omitted, the effect lasts to the end of the
file. Included files are also affected, eg:
apply account business
@ -1100,18 +1093,18 @@ FILE FORMAT
apply account personal
include personal.journal
Prior to hledger 1.0, legacy account and end spellings were also sup-
Prior to hledger 1.0, legacy account and end spellings were also sup-
ported.
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
A default parent account also affects account directives. It does not
affect account names being entered via hledger add or hledger-web. If
account aliases are present, they are applied after the default parent
account.
Periodic transactions
Periodic transaction rules describe transactions that recur. They
Periodic transaction rules describe transactions that recur. They
allow you to generate future transactions for forecasting, without hav-
ing to write them out explicitly in the journal (with --forecast).
ing to write them out explicitly in the journal (with --forecast).
Secondly, they also can be used to define budget goals (with --budget).
A periodic transaction rule looks like a normal journal entry, with the
@ -1122,17 +1115,17 @@ FILE FORMAT
expenses:rent $2000
assets:bank:checking
There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg
There is an additional constraint on the period expression: 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.
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 a Y default year directive is in effect, in which case
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 a Y default year directive is in effect, in which case
they will be relative to Y/1/1.
Two spaces after the period expression
If the period expression is followed by a transaction description,
If the period expression is followed by a transaction description,
these must be separated by two or more spaces. This helps hledger know
where the period expression ends, so that descriptions can not acciden-
tally alter their meaning, as in this example:
@ -1145,66 +1138,66 @@ FILE FORMAT
income:acme inc
Forecasting with periodic transactions
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. These are not
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is
saved in the journal, but appear in all reports. They will look like
normal transactions, but with an extra tag named recur, whose value is
the generating period expression.
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
Forecast transactions start on the first occurrence, and end on the
last occurrence, of their interval within the forecast period. The
forecast period:
o begins on the later of
o the report start date if specified with -b/-p/date:
o the day after the latest normal (non-periodic) transaction in the
o the day after the latest normal (non-periodic) transaction in the
journal, or today if there are no normal transactions.
o ends on the report end date if specified with -e/-p/date:, or 180
o ends on the report end date if specified with -e/-p/date:, or 180
days from today.
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
where "today" means the current date at report time. The "later of"
rule ensures that forecast transactions do not overlap normal transac-
tions in time; they will begin only after normal transactions end.
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
Forecasting can be useful for estimating balances into the future, and
experimenting with different scenarios. Note the start date logic
means that forecasted transactions are automatically replaced by normal
transactions as you add those.
Forecasting can also help with data entry: describe most of your trans-
actions with periodic rules, and every so often copy the output of
actions with periodic rules, and every so often copy the output of
print --forecast to the journal.
You can generate one-time transactions too: just write a period expres-
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
sion specifying a date with no report interval. (You could also write
a normal transaction with a future date, but remember this disables
forecast transactions on previous dates.)
Budgeting with periodic transactions
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
With the --budget flag, currently supported by the balance command,
each periodic transaction rule declares recurring budget goals for the
specified accounts. Eg the first example above declares a goal of
spending $2000 on rent (and also, a goal of depositing $2000 into
checking) every month. Goals and actual performance can then be com-
pared in budget reports.
For more details, see: balance: Budget report and Cookbook: Budgeting
For more details, see: balance: Budget report and Cookbook: Budgeting
and Forecasting.
Transaction modifiers
Transaction modifier rules describe changes that should be applied
automatically to certain transactions. They can be enabled by using
the --auto flag. Currently, just one kind of change is possible:
adding extra postings. These rule-generated postings are known as
Transaction modifier rules describe changes that should be applied
automatically to certain transactions. They can be enabled by using
the --auto flag. Currently, just one kind of change is possible:
adding extra postings. These rule-generated postings are known as
"automated postings" or "auto postings".
A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that
matches certain postings (mnemonic: = suggests matching). And each
A transaction modifier rule looks quite like a normal transaction,
except the first line is an equals sign followed by a query that
matches certain postings (mnemonic: = suggests matching). And each
"posting" is actually a posting-generating rule:
= QUERY
@ -1212,20 +1205,20 @@ FILE FORMAT
ACCT [AMT]
...
These posting rules look like normal postings, except the amount can
These posting rules look like normal postings, except the amount can
be:
o a normal amount with a commodity symbol, eg $2. This will be used
o a normal amount with a commodity symbol, eg $2. This will be used
as-is.
o a number, eg 2. The commodity symbol (if any) from the matched post-
ing will be added to this.
o a numeric multiplier, eg *2 (a star followed by a number N). The
o 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.
o a multiplier with a commodity symbol, eg *$2 (a star, number N, and
o 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.
@ -1265,28 +1258,28 @@ FILE FORMAT
Currently, transaction modifiers are applied / auto postings are added:
o after missing amounts are inferred, and transactions are checked for
o after missing amounts are inferred, and transactions are checked for
balancedness,
o but before balance assertions are checked.
Note this means that journal entries must be balanced both before and
Note this means that journal entries must be balanced both before and
after auto postings are added. This changed in hledger 1.12+; see #893
for background.
EDITOR SUPPORT
Helper modes exist for popular text editors, which make working with
Helper modes exist for popular text editors, which make working with
journal files easier. They add colour, formatting, tab completion, and
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the [[Cookbook]] at hledger.org for the latest informa-
helpful commands, and are quite recommended if you edit your journal
with a text editor. They include ledger-mode or hledger-mode for
Emacs, vim-ledger for Vim, hledger-vscode for Visual Studio Code, and
others. See the [[Cookbook]] at hledger.org for the latest informa-
tion.
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -1300,7 +1293,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)

163
hledger-web/hledger-web.1
View File

@ -41,54 +41,15 @@ timeclock, timedot, or CSV format specified with \f[C]\-f\f[], or
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[]).
For more about this see hledger(1), hledger_journal(5) etc.
.PP
By default, hledger\-web starts the web app in "transient mode" and also
opens it in your default web browser if possible.
In this mode the web app will keep running for as long as you have it
open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it).
With \f[C]\-\-serve\f[], it just runs the web app without exiting, and
logs requests to the console.
.PP
By default the server listens on IP address 127.0.0.1, accessible only
to local requests.
You can use \f[C]\-\-host\f[] to change this, eg
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses.
.PP
Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg
if you are running multiple hledger\-web instances.
.PP
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
port and path that appear in hyperlinks, useful eg for integrating
hledger\-web within a larger website.
The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
80).
.PP
With \f[C]\-\-file\-url\f[] you can set a different base url for static
files, eg for better caching or cookie\-less serving on high performance
websites.
.PP
Note there is no built\-in access control (aside from listening on
127.0.0.1 by default).
So you will need to hide hledger\-web behind an authenticating proxy
(such as apache or nginx) if you want to restrict who can see and add
entries to your journal.
.SH OPTIONS
.PP
Command\-line options and arguments may be used to set an initial filter
on the data.
This is not shown in the web UI, but it will be applied in addition to
any search query entered there.
.PP
With journal and timeclock files (but not CSV files, currently) the web
app detects changes made by other means and will show the new data on
the next request.
If a change makes the file unparseable, hledger\-web will show an error
until the file has been fixed.
.SH OPTIONS
These filter options are not shown in the web UI, but it will be applied
in addition to any search query entered there.
.PP
Note: if invoking hledger\-web as a hledger subcommand, write
\f[C]\-\-\f[] before options as shown above.
\f[C]\-\-\f[] before options, as shown in the synopsis above.
.TP
.B \f[C]\-\-serve\f[]
serve and log requests, don\[aq]t browse or auto\-exit
@ -119,6 +80,17 @@ serve them from another server for efficiency, you would set the url
with this.
.RS
.RE
.TP
.B \f[C]\-\-capabilities=CAP[,CAP..]\f[]
enable the view, add, and/or manage capabilities (default: view,add)
.RS
.RE
.TP
.B \f[C]\-\-capabilities\-header=HTTPHEADER\f[]
read capabilities to enable from a HTTP header, like
X\-Sandstorm\-Permissions (default: disabled)
.RS
.RE
.PP
hledger input options:
.TP
@ -286,6 +258,111 @@ show debug output (levels 1\-9, default: 1)
A \@FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line.
(To prevent this, insert a \f[C]\-\-\f[] argument before.)
.PP
By default, hledger\-web starts the web app in "transient mode" and also
opens it in your default web browser if possible.
In this mode the web app will keep running for as long as you have it
open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it).
With \f[C]\-\-serve\f[], it just runs the web app without exiting, and
logs requests to the console.
.PP
By default the server listens on IP address 127.0.0.1, accessible only
to local requests.
You can use \f[C]\-\-host\f[] to change this, eg
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses.
.PP
Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg
if you are running multiple hledger\-web instances.
.PP
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname,
port and path that appear in hyperlinks, useful eg for integrating
hledger\-web within a larger website.
The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s
configured host address and TCP port (or \f[C]http://HOST\f[] if PORT is
80).
.PP
With \f[C]\-\-file\-url\f[] you can set a different base url for static
files, eg for better caching or cookie\-less serving on high performance
websites.
.SH PERMISSIONS
.PP
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.
.PP
You can restrict who can reach it by
.IP \[bu] 2
setting the IP address it listens on (see \f[C]\-\-host\f[] above).
By default it listens on 127.0.0.1, accessible to all users on the local
machine.
.IP \[bu] 2
putting it behind an authenticating proxy, using eg apache or nginx
.IP \[bu] 2
custom firewall rules
.PP
You can restrict what the users who reach it can do, by
.IP \[bu] 2
using the \f[C]\-\-capabilities=CAP[,CAP..]\f[] flag when you start it,
enabling one or more of the following capabilities.
The default value is \f[C]view,add\f[]:
.RS 2
.IP \[bu] 2
\f[C]view\f[] \- allows viewing the journal file and all included files
.IP \[bu] 2
\f[C]add\f[] \- allows adding new transactions to the main journal file
.IP \[bu] 2
\f[C]manage\f[] \- allows editing, uploading or downloading the main or
included files
.RE
.IP \[bu] 2
using the \f[C]\-\-capabilities\-header=HTTPHEADER\f[] flag to specify a
HTTP header from which it will read capabilities to enable.
hledger\-web on Sandstorm uses the X\-Sandstorm\-Permissions header to
integrate with Sandstorm\[aq]s permissions.
This is disabled by default.
.SH EDITING, UPLOADING, DOWNLOADING
.PP
If you enable the \f[C]manage\f[] capability mentioned above, you\[aq]ll
see a new "spanner" button to the right of the search form.
Clicking this will let you edit, upload, or download the journal file or
any files it includes.
.PP
Note, unlike any other hledger command, in this mode you (or any
visitor) can alter or wipe the data files.
.PP
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.) hledger\-web is not aware of version control systems,
currently; if you use one, you\[aq]ll have to arrange to commit the
changes yourself (eg with a cron job or a file watcher like entr).
.PP
Changes which would leave the journal file(s) unparseable or non\-valid
(eg with failing balance assertions) are prevented.
(Probably.
This needs re\-testing.)
.SH RELOADING
.PP
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 when you reload the page or navigate to a new page.
If a change makes a file unparseable, hledger\-web will display an error
message until the file has been fixed.
.SH JSON API
.PP
In addition to the web UI, hledger\-web provides some JSON API routes.
These are similar to the API provided by the hledger\-api tool, but it
may be convenient to have them in hledger\-web also.
.IP
.nf
\f[C]
/accountnames
/transactions
/prices
/commodities
/accounts
/accounttransactions/#AccountName
\f[]
.fi
.SH ENVIRONMENT
.PP
\f[B]LEDGER_FILE\f[] The journal file path when not specified with

183
hledger-web/hledger-web.info
View File

@ -25,56 +25,26 @@ journal, timeclock, timedot, or CSV format specified with '-f', or
'$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
hledger_journal(5) etc.
By default, hledger-web starts the web app in "transient mode" and
also opens it in your default web browser if possible. In this mode the
web app will keep running for as long as you have it open in a browser
window, and will exit after two minutes of inactivity (no requests and
no browser windows viewing it). With '--serve', it just runs the web
app without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible
only to local requests. You can use '--host' to change this, eg '--host
0.0.0.0' to listen on all configured addresses.
Similarly, use '--port' to set a TCP port other than 5000, eg if you
are running multiple hledger-web instances.
You can use '--base-url' to change the protocol, hostname, port and
path that appear in hyperlinks, useful eg for integrating hledger-web
within a larger website. The default is 'http://HOST:PORT/' using the
server's configured host address and TCP port (or 'http://HOST' if PORT
is 80).
With '--file-url' you can set a different base url for static files,
eg for better caching or cookie-less serving on high performance
websites.
Note there is no built-in access control (aside from listening on
127.0.0.1 by default). So you will need to hide hledger-web behind an
authenticating proxy (such as apache or nginx) if you want to restrict
who can see and add entries to your journal.
Command-line options and arguments may be used to set an initial
filter on the data. This is not shown in the web UI, but it will be
applied in addition to any search query entered there.
With journal and timeclock files (but not CSV files, currently) the
web app detects changes made by other means and will show the new data
on the next request. If a change makes the file unparseable,
hledger-web will show an error until the file has been fixed.
* Menu:
* OPTIONS::
* PERMISSIONS::
* EDITING UPLOADING DOWNLOADING::
* RELOADING::
* JSON API::

File: hledger-web.info, Node: OPTIONS, Prev: Top, Up: Top
File: hledger-web.info, Node: OPTIONS, Next: PERMISSIONS, Prev: Top, Up: Top
1 OPTIONS
*********
Note: if invoking hledger-web as a hledger subcommand, write '--' before
options as shown above.
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, 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, as shown in the synopsis above.
'--serve'
@ -96,6 +66,14 @@ options as shown above.
normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url with
this.
'--capabilities=CAP[,CAP..]'
enable the view, add, and/or manage capabilities (default:
view,add)
'--capabilities-header=HTTPHEADER'
read capabilities to enable from a HTTP header, like
X-Sandstorm-Permissions (default: disabled)
hledger input options:
@ -209,10 +187,129 @@ the last one takes precedence.
should contain one command line option/argument per line. (To prevent
this, insert a '--' argument before.)
By default, hledger-web starts the web app in "transient mode" and
also opens it in your default web browser if possible. In this mode the
web app will keep running for as long as you have it open in a browser
window, and will exit after two minutes of inactivity (no requests and
no browser windows viewing it). With '--serve', it just runs the web
app without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible
only to local requests. You can use '--host' to change this, eg '--host
0.0.0.0' to listen on all configured addresses.
Similarly, use '--port' to set a TCP port other than 5000, eg if you
are running multiple hledger-web instances.
You can use '--base-url' to change the protocol, hostname, port and
path that appear in hyperlinks, useful eg for integrating hledger-web
within a larger website. The default is 'http://HOST:PORT/' using the
server's configured host address and TCP port (or 'http://HOST' if PORT
is 80).
With '--file-url' you can set a different base url for static files,
eg for better caching or cookie-less serving on high performance
websites.

File: hledger-web.info, Node: PERMISSIONS, Next: EDITING UPLOADING DOWNLOADING, Prev: OPTIONS, Up: Top
2 PERMISSIONS
*************
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.
You can restrict who can reach it by
* 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.
* putting it behind an authenticating proxy, using eg apache or nginx
* custom firewall rules
You can restrict what the users who reach it can do, by
* using the '--capabilities=CAP[,CAP..]' flag when you start it,
enabling one or more of the following capabilities. The default
value is 'view,add':
* 'view' - allows viewing the journal file and all included
files
* 'add' - allows adding new transactions to the main journal
file
* 'manage' - allows editing, uploading or downloading the main
or included files
* using the '--capabilities-header=HTTPHEADER' flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.

File: hledger-web.info, Node: EDITING UPLOADING DOWNLOADING, Next: RELOADING, Prev: PERMISSIONS, Up: Top
3 EDITING, UPLOADING, DOWNLOADING
*********************************
If you enable the 'manage' capability mentioned above, 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 file or any files it
includes.
Note, unlike any other hledger command, in this mode you (or any
visitor) can alter or wipe the data files.
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.) 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 or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or
non-valid (eg with failing balance assertions) are prevented.
(Probably. This needs re-testing.)

File: hledger-web.info, Node: RELOADING, Next: JSON API, Prev: EDITING UPLOADING DOWNLOADING, Up: Top
4 RELOADING
***********
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
when you reload the page or navigate to a new page. If a change makes a
file unparseable, hledger-web will display an error message until the
file has been fixed.

File: hledger-web.info, Node: JSON API, Prev: RELOADING, Up: Top
5 JSON API
**********
In addition to the web UI, hledger-web provides some JSON API routes.
These are similar to the API provided by the hledger-api tool, but it
may be convenient to have them in hledger-web also.
/accountnames
/transactions
/prices
/commodities
/accounts
/accounttransactions/#AccountName

Tag Table:
Node: Top72
Node: OPTIONS3160
Ref: #options3245
Node: OPTIONS1360
Ref: #options1465
Node: PERMISSIONS6555
Ref: #permissions6694
Node: EDITING UPLOADING DOWNLOADING7906
Ref: #editing-uploading-downloading8087
Node: RELOADING8921
Ref: #reloading9055
Node: JSON API9365
Ref: #json-api9459

End Tag Table

180
hledger-web/hledger-web.txt
View File

@ -35,45 +35,13 @@ DESCRIPTION
C:/Users/USER/.hledger.journal). For more about this see hledger(1),
hledger_journal(5) etc.
By default, hledger-web starts the web app in "transient mode" and also
opens it in your default web browser if possible. In this mode the web
app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg
--host 0.0.0.0 to listen on all configured addresses.
Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances.
You can use --base-url to change the protocol, hostname, port and path
that appear in hyperlinks, useful eg for integrating hledger-web within
a larger website. The default is http://HOST:PORT/ using the server's
configured host address and TCP port (or http://HOST if PORT is 80).
With --file-url you can set a different base url for static files, eg
for better caching or cookie-less serving on high performance websites.
Note there is no built-in access control (aside from listening on
127.0.0.1 by default). So you will need to hide hledger-web behind an
authenticating proxy (such as apache or nginx) if you want to restrict
who can see and add entries to your journal.
Command-line options and arguments may be used to set an initial filter
on the data. This is not shown in the web UI, but it will be applied
in addition to any search query entered there.
With journal and timeclock files (but not CSV files, currently) the web
app detects changes made by other means and will show the new data on
the next request. If a change makes the file unparseable, hledger-web
will show an error until the file has been fixed.
OPTIONS
Note: if invoking hledger-web as a hledger subcommand, write -- before
options as shown above.
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, 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, as shown in the synopsis above.
--serve
serve and log requests, don't browse or auto-exit
@ -85,16 +53,24 @@ OPTIONS
listen on this TCP port (default: 5000)
--base-url=URL
set the base url (default: http://IPADDR:PORT). You would
set the base url (default: http://IPADDR:PORT). You would
change this when sharing over the network, or integrating within
a larger website.
--file-url=URL
set the static files url (default: BASEURL/static). hledger-web
normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url
normally serves static files itself, but if you wanted to serve
them from another server for efficiency, you would set the url
with this.
--capabilities=CAP[,CAP..]
enable the view, add, and/or manage capabilities (default:
view,add)
--capabilities-header=HTTPHEADER
read capabilities to enable from a HTTP header, like X-Sand-
storm-Permissions (default: disabled)
hledger input options:
-f FILE --file=FILE
@ -102,7 +78,7 @@ OPTIONS
$LEDGER_FILE or $HOME/.hledger.journal)
--rules-file=RULESFILE
Conversion rules file to use when reading CSV (default:
Conversion rules file to use when reading CSV (default:
FILE.rules)
--separator=CHAR
@ -143,11 +119,11 @@ OPTIONS
multiperiod/multicolumn report by year
-p --period=PERIODEXP
set start date, end date, and/or reporting interval all at once
set start date, end date, and/or reporting interval all at once
using period expressions syntax (overrides the flags above)
--date2
match the secondary date instead (see command help for other
match the secondary date instead (see command help for other
effects)
-U --unmarked
@ -166,21 +142,21 @@ OPTIONS
hide/aggregate accounts or postings more than NUM levels deep
-E --empty
show items with zero amount, normally hidden (and vice-versa in
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
-B --cost
convert amounts to their cost at transaction time (using the
convert amounts to their cost at transaction time (using the
transaction price, if any)
-V --value
convert amounts to their market value on the report end date
convert amounts to their market value on the report end date
(using the most recent applicable market price, if any)
--auto apply automated posting rules to modify transactions.
--forecast
apply periodic transaction rules to generate future transac-
apply periodic transaction rules to generate future transac-
tions, to 6 months from now or report end date.
When a reporting option appears more than once in the command line, the
@ -200,22 +176,114 @@ OPTIONS
show debug output (levels 1-9, default: 1)
A @FILE argument will be expanded to the contents of FILE, which should
contain one command line option/argument per line. (To prevent this,
contain one command line option/argument per line. (To prevent this,
insert a -- argument before.)
By default, hledger-web starts the web app in "transient mode" and also
opens it in your default web browser if possible. In this mode the web
app will keep running for as long as you have it open in a browser win-
dow, and will exit after two minutes of inactivity (no requests and no
browser windows viewing it). With --serve, it just runs the web app
without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible only
to local requests. You can use --host to change this, eg
--host 0.0.0.0 to listen on all configured addresses.
Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances.
You can use --base-url to change the protocol, hostname, port and path
that appear in hyperlinks, useful eg for integrating hledger-web within
a larger website. The default is http://HOST:PORT/ using the server's
configured host address and TCP port (or http://HOST if PORT is 80).
With --file-url you can set a different base url for static files, eg
for better caching or cookie-less serving on high performance websites.
PERMISSIONS
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.
You can restrict who can reach it by
o 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.
o putting it behind an authenticating proxy, using eg apache or nginx
o custom firewall rules
You can restrict what the users who reach it can do, by
o using the --capabilities=CAP[,CAP..] flag when you start it, enabling
one or more of the following capabilities. The default value is
view,add:
o view - allows viewing the journal file and all included files
o add - allows adding new transactions to the main journal file
o manage - allows editing, uploading or downloading the main or
included files
o using the --capabilities-header=HTTPHEADER flag to specify a HTTP
header from which it will read capabilities to enable. hledger-web
on Sandstorm uses the X-Sandstorm-Permissions header to integrate
with Sandstorm's permissions. This is disabled by default.
EDITING, UPLOADING, DOWNLOADING
If you enable the manage capability mentioned above, 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 file or any files it
includes.
Note, unlike any other hledger command, in this mode you (or any visi-
tor) can alter or wipe the data files.
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.) hledger-web is not aware of version control systems, cur-
rently; if you use one, you'll have to arrange to commit the changes
yourself (eg with a cron job or a file watcher like entr).
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented. (Probably. This
needs re-testing.)
RELOADING
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 when you reload the page or navigate to a new page. If a change
makes a file unparseable, hledger-web will display an error message
until the file has been fixed.
JSON API
In addition to the web UI, hledger-web provides some JSON API routes.
These are similar to the API provided by the hledger-api tool, but it
may be convenient to have them in hledger-web also.
/accountnames
/transactions
/prices
/commodities
/accounts
/accounttransactions/#AccountName
ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
nal).
FILES
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
Reads data from one or more files in hledger journal, timeclock, time-
dot, or CSV format specified with -f, or $LEDGER_FILE, or
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
The need to precede options with -- when invoked from hledger is awk-
The need to precede options with -- when invoked from hledger is awk-
ward.
-f- doesn't work (hledger-web can't read from stdin).
@ -229,7 +297,7 @@ BUGS
REPORTING BUGS
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
Report bugs at http://bugs.hledger.org (or on the #hledger IRC channel
or hledger mail list)
@ -243,7 +311,7 @@ COPYRIGHT
SEE ALSO
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger(1), hledger-ui(1), hledger-web(1), hledger-api(1),
hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
dot(5), ledger(1)