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

;regen embedded manuals

Browse Source
This commit is contained in:
Simon Michael 2019-05-23 22:26:43 -07:00
parent 7ef3ddd1e6
commit 5e54920160
24 changed files with 4335 additions and 3645 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
hledger-api/hledger-api.1
View File

@ -1,46 +1,46 @@
.TH "hledger\-api" "1" "March 2019" "hledger\-api 1.14" "hledger User Manuals"
.TH "hledger-api" "1" "March 2019" "hledger-api 1.14.99" "hledger User Manuals"
.SH NAME
.PP
hledger\-api \- web API server for the hledger accounting tool
hledger-api - web API server for the hledger accounting tool
.SH SYNOPSIS
.PP
\f[C]hledger\-api\ [OPTIONS]\f[]
\f[C]hledger-api [OPTIONS]\f[R]
.PD 0
.P
.PD
\f[C]hledger\ api\ \-\-\ [OPTIONS]\f[]
\f[C]hledger api -- [OPTIONS]\f[R]
.SH DESCRIPTION
.PP
hledger is a cross\-platform program for tracking money, time, or any
other commodity, using double\-entry accounting and a simple, editable
hledger is a cross-platform program for tracking money, time, or any
other commodity, using double-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger\-api is a simple web API server, intended to support
client\-side web apps operating on hledger data.
It comes with a series of simple client\-side app examples, which drive
hledger-api is a simple web API server, intended to support client-side
web apps operating on hledger data.
It comes with a series of simple client-side app examples, which drive
its evolution.
.PP
Like hledger, it reads data from one or more files in hledger journal,
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[]).
timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1), hledger_journal(5) etc.
.PP
The server listens on IP address 127.0.0.1, accessible only to local
requests, by default.
You can change this with \f[C]\-\-host\f[], eg
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all addresses.
Note there is no other access control, and hledger\-api allows file
You can change this with \f[C]--host\f[R], eg \f[C]--host 0.0.0.0\f[R]
to listen on all addresses.
Note there is no other access control, and hledger-api allows file
browsing, so on shared machines you will certainly need to put it behind
an authenticating proxy to restrict access.
.PP
You can change the TCP port it listens on (default: 8001) with
\f[C]\-p\ PORT\f[].
\f[C]-p PORT\f[R].
.PP
API methods look like:
.IP
@ -52,73 +52,59 @@ API methods look like:
/api/v1/commodities
/api/v1/accounts
/api/v1/accounts/ACCTNAME
\f[]
\f[R]
.fi
.PP
See \f[C]/api/swagger.json\f[] for a full list in Swagger 2.0 format.
(Or you can run \f[C]hledger\-api\ \-\-swagger\f[] to print this in the
See \f[C]/api/swagger.json\f[R] for a full list in Swagger 2.0 format.
(Or you can run \f[C]hledger-api --swagger\f[R] to print this in the
console.)
.PP
hledger\-api also serves files, from the current directory by default,
and the \f[C]/\f[] path will also show a directory listing.
This is convenient for serving client\-side web code, in addition to the
server\-side api.
hledger-api also serves files, from the current directory by default,
and the \f[C]/\f[R] path will also show a directory listing.
This is convenient for serving client-side web code, in addition to the
server-side api.
.SH OPTIONS
.PP
Note: if invoking hledger\-api as a hledger subcommand, write
\f[C]\-\-\f[] before options as shown above.
Note: if invoking hledger-api as a hledger subcommand, write
\f[C]--\f[R] before options as shown above.
.TP
.B \f[C]\-f\ \-\-file=FILE\f[]
.B \f[C]-f --file=FILE\f[R]
use a different input file.
For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or
\f[C]$HOME/.hledger.journal\f[])
.RS
.RE
For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
\f[C]$HOME/.hledger.journal\f[R])
.TP
.B \f[C]\-d\ \-\-static\-dir=DIR\f[]
serve files from a different directory (default: \f[C]\&.\f[])
.RS
.RE
.B \f[C]-d --static-dir=DIR\f[R]
serve files from a different directory (default: \f[C].\f[R])
.TP
.B \f[C]\-\-host=IPADDR\f[]
.B \f[C]--host=IPADDR\f[R]
listen on this IP address (default: 127.0.0.1)
.RS
.RE
.TP
.B \f[C]\-p\ \-\-port=PORT\f[]
.B \f[C]-p --port=PORT\f[R]
listen on this TCP port (default: 8001)
.RS
.RE
.TP
.B \f[C]\-\-swagger\f[]
.B \f[C]--swagger\f[R]
print API docs in Swagger 2.0 format, and exit
.RS
.RE
.TP
.B \f[C]\-\-version\f[]
.B \f[C]--version\f[R]
show version
.RS
.RE
.TP
.B \f[C]\-h\ \-\-help\f[]
.B \f[C]-h --help\f[R]
show usage
.RS
.RE
.SH ENVIRONMENT
.PP
\f[B]LEDGER_FILE\f[] The journal file path when not specified with
\f[C]\-f\f[].
Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[]).
\f[B]LEDGER_FILE\f[R] The journal file path when not specified with
\f[C]-f\f[R].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH FILES
.PP
Reads data from one or more files in hledger journal, 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[]).
timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH BUGS
.PP
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
The need to precede options with \f[C]--\f[R] when invoked from hledger
is awkward.

9
hledger-api/hledger-api.info
View File

@ -3,8 +3,8 @@ This is hledger-api.info, produced by makeinfo version 6.5 from stdin.

File: hledger-api.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-api(1) hledger-api 1.14
*******************************
hledger-api(1) hledger-api 1.14.99
**********************************
hledger-api is a simple web API server, intended to support client-side
web apps operating on hledger data. It comes with a series of simple
@ -41,6 +41,7 @@ you can run 'hledger-api --swagger' to print this in the console.)
hledger-api also serves files, from the current directory by default,
and the '/' path will also show a directory listing. This is convenient
for serving client-side web code, in addition to the server-side api.
* Menu:
* OPTIONS::
@ -80,7 +81,7 @@ options as shown above.

Tag Table:
Node: Top72
Node: OPTIONS1660
Ref: #options1745
Node: OPTIONS1667
Ref: #options1752

End Tag Table

12
hledger-api/hledger-api.txt
View File

@ -27,11 +27,11 @@ DESCRIPTION
hledger_journal(5) etc.
The server listens on IP address 127.0.0.1, accessible only to local
requests, by default. You can change this with --host, eg
--host 0.0.0.0 to listen on all addresses. Note there is no other
access control, and hledger-api allows file browsing, so on shared
machines you will certainly need to put it behind an authenticating
proxy to restrict access.
requests, by default. You can change this with --host, eg --host
0.0.0.0 to listen on all addresses. Note there is no other access con-
trol, and hledger-api allows file browsing, so on shared machines you
will certainly need to put it behind an authenticating proxy to
restrict access.
You can change the TCP port it listens on (default: 8001) with -p PORT.
@ -117,4 +117,4 @@ SEE ALSO
hledger-api 1.14 March 2019 hledger-api(1)
hledger-api 1.14.99 March 2019 hledger-api(1)

290
hledger-lib/hledger_csv.5
View File

@ -1,17 +1,17 @@
.TH "hledger_csv" "5" "March 2019" "hledger 1.14" "hledger User Manuals"
.TH "hledger_csv" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals"
.SH NAME
.PP
CSV \- how hledger reads CSV data, and the CSV rules file format
CSV - how hledger reads CSV data, and the CSV rules file format
.SH DESCRIPTION
.PP
hledger can read CSV (comma\-separated value) files as if they were
hledger can read CSV (comma-separated value) files as if they were
journal files, automatically converting each CSV record into a
transaction.
(To learn about \f[I]writing\f[] CSV, see CSV output.)
(To learn about \f[I]writing\f[R] CSV, see CSV output.)
.PP
Converting CSV to transactions requires some special conversion rules.
These do several things:
@ -24,58 +24,57 @@ templating language
they can add refinements based on patterns in the CSV data, eg
categorizing transactions with more detailed account names.
.PP
When reading a CSV file named \f[C]FILE.csv\f[], hledger looks for a
conversion rules file named \f[C]FILE.csv.rules\f[] in the same
When reading a CSV file named \f[C]FILE.csv\f[R], hledger looks for a
conversion rules file named \f[C]FILE.csv.rules\f[R] in the same
directory.
You can override this with the \f[C]\-\-rules\-file\f[] option.
If the rules file does not exist, hledger will auto\-create one with
some example rules, which you\[aq]ll need to adjust.
You can override this with the \f[C]--rules-file\f[R] option.
If the rules file does not exist, hledger will auto-create one with some
example rules, which you\[aq]ll need to adjust.
.PP
At minimum, the rules file must identify the \f[C]date\f[] and
\f[C]amount\f[] fields.
It may also be necessary to specify the date format, and the number of
header lines to skip.
At minimum, the rules file must identify the date and amount fields.
It\[aq]s often necessary to specify the date format, and the number of
header lines to skip, also.
Eg:
.IP
.nf
\f[C]
fields\ date,\ _,\ _,\ amount
date\-format\ \ %d/%m/%Y
skip\ 1
\f[]
fields date, _, _, amount
date-format %d/%m/%Y
skip 1
\f[R]
.fi
.PP
A more complete example:
.IP
.nf
\f[C]
#\ hledger\ CSV\ rules\ for\ amazon.com\ order\ history
# hledger CSV rules for amazon.com order history
#\ sample:
#\ "Date","Type","To/From","Name","Status","Amount","Fees","Transaction\ ID"
#\ "Jul\ 29,\ 2012","Payment","To","Adapteva,\ Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL"
# sample:
# \[dq]Date\[dq],\[dq]Type\[dq],\[dq]To/From\[dq],\[dq]Name\[dq],\[dq]Status\[dq],\[dq]Amount\[dq],\[dq]Fees\[dq],\[dq]Transaction ID\[dq]
# \[dq]Jul 29, 2012\[dq],\[dq]Payment\[dq],\[dq]To\[dq],\[dq]Adapteva, Inc.\[dq],\[dq]Completed\[dq],\[dq]$25.00\[dq],\[dq]$0.00\[dq],\[dq]17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL\[dq]
#\ skip\ one\ header\ line
skip\ 1
# skip one header line
skip 1
#\ name\ the\ csv\ fields\ (and\ assign\ the\ transaction\[aq]s\ date,\ amount\ and\ code)
fields\ date,\ _,\ toorfrom,\ name,\ amzstatus,\ amount,\ fees,\ code
# name the csv fields (and assign the transaction\[aq]s date, amount and code)
fields date, _, toorfrom, name, amzstatus, amount, fees, code
#\ how\ to\ parse\ the\ date
date\-format\ %b\ %\-d,\ %Y
# how to parse the date
date-format %b %-d, %Y
#\ combine\ two\ fields\ to\ make\ the\ description
description\ %toorfrom\ %name
# combine two fields to make the description
description %toorfrom %name
#\ save\ these\ fields\ as\ tags
comment\ \ \ \ \ status:%amzstatus,\ fees:%fees
# save these fields as tags
comment status:%amzstatus, fees:%fees
#\ set\ the\ base\ account\ for\ all\ transactions
account1\ \ \ \ assets:amazon
# set the base account for all transactions
account1 assets:amazon
#\ flip\ the\ sign\ on\ the\ amount
amount\ \ \ \ \ \ \-%amount
\f[]
# flip the sign on the amount
amount -%amount
\f[R]
.fi
.PP
For more examples, see Convert CSV files.
@ -83,11 +82,11 @@ For more examples, see Convert CSV files.
.PP
The following seven kinds of rule can appear in the rules file, in any
order.
Blank lines and lines beginning with \f[C]#\f[] or \f[C];\f[] are
Blank lines and lines beginning with \f[C]#\f[R] or \f[C];\f[R] are
ignored.
.SS skip
.PP
\f[C]skip\f[]\f[I]\f[CI]N\f[I]\f[]
\f[C]skip\f[R]\f[I]\f[CI]N\f[I]\f[R]
.PP
Skip this number of CSV records at the beginning.
You\[aq]ll need this whenever your CSV data contains header lines.
@ -95,122 +94,123 @@ Eg:
.IP
.nf
\f[C]
#\ ignore\ the\ first\ CSV\ line
skip\ 1
\f[]
# ignore the first CSV line
skip 1
\f[R]
.fi
.SS date\-format
.SS date-format
.PP
\f[C]date\-format\f[]\f[I]\f[CI]DATEFMT\f[I]\f[]
\f[C]date-format\f[R]\f[I]\f[CI]DATEFMT\f[I]\f[R]
.PP
When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or
\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to
When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[R]
(or \f[C]YYYY-MM-DD\f[R] or \f[C]YYYY.MM.DD\f[R]), you\[aq]ll need to
specify the format.
DATEFMT is a strptime\-like date parsing pattern, which must parse the
DATEFMT is a strptime-like date parsing pattern, which must parse the
date field values completely.
Examples:
.IP
.nf
\f[C]
#\ for\ dates\ like\ "11/06/2013":
date\-format\ %m/%d/%Y
\f[]
# for dates like \[dq]11/06/2013\[dq]:
date-format %m/%d/%Y
\f[R]
.fi
.IP
.nf
\f[C]
#\ for\ dates\ like\ "6/11/2013"\ (note\ the\ \-\ to\ make\ leading\ zeros\ optional):
date\-format\ %\-d/%\-m/%Y
\f[]
# for dates like \[dq]6/11/2013\[dq] (note the - to make leading zeros optional):
date-format %-d/%-m/%Y
\f[R]
.fi
.IP
.nf
\f[C]
#\ for\ dates\ like\ "2013\-Nov\-06":
date\-format\ %Y\-%h\-%d
\f[]
# for dates like \[dq]2013-Nov-06\[dq]:
date-format %Y-%h-%d
\f[R]
.fi
.IP
.nf
\f[C]
#\ for\ dates\ like\ "11/6/2013\ 11:32\ PM":
date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p
\f[]
# for dates like \[dq]11/6/2013 11:32 PM\[dq]:
date-format %-m/%-d/%Y %l:%M %p
\f[R]
.fi
.SS field list
.PP
\f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\f[I]\f[],
\f[I]\f[CI]FIELDNAME2\f[I]\f[]...
\f[C]fields\f[R]\f[I]\f[CI]FIELDNAME1\f[I]\f[R],
\f[I]\f[CI]FIELDNAME2\f[I]\f[R]...
.PP
This (a) names the CSV fields, in order (names may not contain
whitespace; uninteresting names may be left blank), and (b) assigns them
to journal entry fields if you use any of these standard field names:
\f[C]date\f[], \f[C]date2\f[], \f[C]status\f[], \f[C]code\f[],
\f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[],
\f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[],
\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[].
\f[C]date\f[R], \f[C]date2\f[R], \f[C]status\f[R], \f[C]code\f[R],
\f[C]description\f[R], \f[C]comment\f[R], \f[C]account1\f[R],
\f[C]account2\f[R], \f[C]amount\f[R], \f[C]amount-in\f[R],
\f[C]amount-out\f[R], \f[C]currency\f[R], \f[C]balance\f[R],
\f[C]balance1\f[R], \f[C]balance2\f[R].
Eg:
.IP
.nf
\f[C]
#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\[aq]s\ date,\ description\ and\ amount,
#\ and\ give\ the\ 7th\ and\ 8th\ fields\ meaningful\ names\ for\ later\ reference:
# use the 1st, 2nd and 4th CSV fields as the entry\[aq]s date, description and amount,
# and give the 7th and 8th fields meaningful names for later reference:
#
#\ CSV\ field:
#\ \ \ \ \ \ 1\ \ \ \ \ 2\ \ \ \ \ \ \ \ \ \ \ \ 3\ 4\ \ \ \ \ \ \ 5\ 6\ 7\ \ \ \ \ \ \ \ \ \ 8
#\ entry\ field:
fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield
\f[]
# CSV field:
# 1 2 3 4 5 6 7 8
# entry field:
fields date, description, , amount, , , somefield, anotherfield
\f[R]
.fi
.SS field assignment
.PP
\f[I]\f[CI]ENTRYFIELDNAME\f[I]\f[] \f[I]\f[CI]FIELDVALUE\f[I]\f[]
\f[I]\f[CI]ENTRYFIELDNAME\f[I]\f[R] \f[I]\f[CI]FIELDVALUE\f[I]\f[R]
.PP
This sets a journal entry field (one of the standard names above) to the
given text value, which can include CSV field values interpolated by
name (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]).
Eg:
name (\f[C]%CSVFIELDNAME\f[R]) or 1-based position (\f[C]%N\f[R]).
Eg:
.IP
.nf
\f[C]
#\ set\ the\ amount\ to\ the\ 4th\ CSV\ field\ with\ "USD\ "\ prepended
amount\ USD\ %4
\f[]
# set the amount to the 4th CSV field with \[dq]USD \[dq] prepended
amount USD %4
\f[R]
.fi
.IP
.nf
\f[C]
#\ combine\ three\ fields\ to\ make\ a\ comment\ (containing\ two\ tags)
comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1
\f[]
# combine three fields to make a comment (containing two tags)
comment note: %somefield - %anotherfield, date: %1
\f[R]
.fi
.PP
Field assignments can be used instead of or in addition to a field list.
.SS conditional block
.PP
\f[C]if\f[] \f[I]\f[CI]PATTERN\f[I]\f[]
\f[C]if\f[R] \f[I]\f[CI]PATTERN\f[I]\f[R]
.PD 0
.P
.PD
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]...
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[R]...
.PP
\f[C]if\f[]
\f[C]if\f[R]
.PD 0
.P
.PD
\f[I]\f[CI]PATTERN\f[I]\f[]
\f[I]\f[CI]PATTERN\f[I]\f[R]
.PD 0
.P
.PD
\f[I]\f[CI]PATTERN\f[I]\f[]...
\f[I]\f[CI]PATTERN\f[I]\f[R]...
.PD 0
.P
.PD
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]...
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[R]...
.PP
This applies one or more field assignments, only to those CSV records
matched by one of the PATTERNs.
The patterns are case\-insensitive regular expressions which match
The patterns are case-insensitive regular expressions which match
anywhere within the whole CSV record (it\[aq]s not yet possible to match
within a specific field).
When there are multiple patterns they can be written on separate lines,
@ -221,46 +221,46 @@ Examples:
.IP
.nf
\f[C]
#\ if\ the\ CSV\ record\ contains\ "groceries",\ set\ account2\ to\ "expenses:groceries"
if\ groceries
\ account2\ expenses:groceries
\f[]
# if the CSV record contains \[dq]groceries\[dq], set account2 to \[dq]expenses:groceries\[dq]
if groceries
account2 expenses:groceries
\f[R]
.fi
.IP
.nf
\f[C]
#\ if\ the\ CSV\ record\ contains\ any\ of\ these\ patterns,\ set\ account2\ and\ comment\ as\ shown
# if the CSV record contains any of these patterns, set account2 and comment as shown
if
monthly\ service\ fee
atm\ transaction\ fee
banking\ thru\ software
\ account2\ expenses:business:banking
\ comment\ \ XXX\ deductible\ ?\ check\ it
\f[]
monthly service fee
atm transaction fee
banking thru software
account2 expenses:business:banking
comment XXX deductible ? check it
\f[R]
.fi
.SS include
.PP
\f[C]include\f[]\f[I]\f[CI]RULESFILE\f[I]\f[]
\f[C]include\f[R]\f[I]\f[CI]RULESFILE\f[I]\f[R]
.PP
Include another rules file at this point.
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to
the current file\[aq]s directory.
\f[C]RULESFILE\f[R] is either an absolute file path or a path relative
to the current file\[aq]s directory.
Eg:
.IP
.nf
\f[C]
#\ rules\ reused\ with\ several\ CSV\ files
include\ common.rules
\f[]
# rules reused with several CSV files
include common.rules
\f[R]
.fi
.SS newest\-first
.SS newest-first
.PP
\f[C]newest\-first\f[]
\f[C]newest-first\f[R]
.PP
Consider adding this rule if all of the following are true: you might be
processing just one day of data, your CSV records are in reverse
chronological order (newest first), and you care about preserving the
order of same\-day transactions.
order of same-day transactions.
It usually isn\[aq]t needed, because hledger autodetects the CSV order,
but when all CSV records have the same date it will assume they are
oldest first.
@ -268,49 +268,69 @@ oldest first.
.SS CSV ordering
.PP
The generated journal entries will be sorted by date.
The order of same\-day entries will be preserved (except in the special
case where you might need \f[C]newest\-first\f[], see above).
The order of same-day entries will be preserved (except in the special
case where you might need \f[C]newest-first\f[R], see above).
.SS CSV accounts
.PP
Each journal entry will have two postings, to \f[C]account1\f[] and
\f[C]account2\f[] respectively.
Each journal entry will have two postings, to \f[C]account1\f[R] and
\f[C]account2\f[R] respectively.
It\[aq]s not yet possible to generate entries with more than two
postings.
It\[aq]s conventional and recommended to use \f[C]account1\f[] for the
It\[aq]s conventional and recommended to use \f[C]account1\f[R] for the
account whose CSV we are reading.
.SS CSV amounts
.PP
The \f[C]amount\f[] field sets the amount of the \f[C]account1\f[]
posting.
.PP
If the CSV has debit/credit amounts in separate fields, assign to the
\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead.
(Whichever one has a value will be used, with appropriate sign.
If both contain a value, it may not work so well.)
.PP
If an amount value is parenthesised, it will be de\-parenthesised and
sign\-flipped.
A transaction amount must be set, in one of these ways:
.IP \[bu] 2
with an \f[C]amount\f[R] field assignment, which sets the first
posting\[aq]s amount
.IP \[bu] 2
(When the CSV has debit and credit amounts in separate fields:)
.PD 0
.P
.PD
with field assignments for the \f[C]amount-in\f[R] and
\f[C]amount-out\f[R] pseudo fields (both of them).
Whichever one has a value will be used, with appropriate sign.
If both contain a value, it might not work so well.
.IP \[bu] 2
or implicitly by means of a balance assignment (see below).
.PP
There is some special handling for sign in amounts:
.IP \[bu] 2
If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped.
.IP \[bu] 2
If an amount value begins with a double minus sign, those will cancel
out and be removed.
.PP
If the CSV has the currency symbol in a separate field, assign that to
the \f[C]currency\f[] pseudo field to have it prepended to the amount.
Or, you can use a field assignment to \f[C]amount\f[] that interpolates
both CSV fields (giving more control, eg to put the currency symbol on
the right).
.SS CSV balance assertions
If the currency/commodity symbol is provided as a separate CSV field,
assign it to the \f[C]currency\f[R] pseudo field; the symbol will be
prepended to the amount (TODO: when there is an amount).
Or, you can use an \f[C]amount\f[R] field assignment for more control,
eg:
.IP
.nf
\f[C]
fields date,description,currency,amount
amount %amount %currency
\f[R]
.fi
.SS CSV balance assertions/assignments
.PP
If the CSV includes a running balance, you can assign that to the
\f[C]balance\f[] pseudo field; whenever the running balance value is
non\-empty, it will be asserted as the balance after the
\f[C]account1\f[] posting.
If the CSV includes a running balance, you can assign that to one of the
pseudo fields \f[C]balance\f[R] (or \f[C]balance1\f[R]) or
\f[C]balance2\f[R].
This will generate a balance assertion (or if the amount is left empty,
a balance assignment), on the first or second posting, whenever the
running balance field is non-empty.
(TODO: #1000)
.SS Reading multiple CSV files
.PP
You can read multiple CSV files at once using multiple \f[C]\-f\f[]
You can read multiple CSV files at once using multiple \f[C]-f\f[R]
arguments on the command line, and hledger will look for a
correspondingly\-named rules file for each.
Note if you use the \f[C]\-\-rules\-file\f[] option, this one rules file
correspondingly-named rules file for each.
Note if you use the \f[C]--rules-file\f[R] option, this one rules file
will be used for all the CSV files being read.

129
hledger-lib/hledger_csv.info
View File

@ -3,8 +3,8 @@ This is hledger_csv.info, produced by makeinfo version 6.5 from stdin.

File: hledger_csv.info, Node: Top, Next: CSV RULES, Up: (dir)
hledger_csv(5) hledger 1.14
***************************
hledger_csv(5) hledger 1.14.99
******************************
hledger can read CSV (comma-separated value) files as if they were
journal files, automatically converting each CSV record into a
@ -25,9 +25,9 @@ can override this with the '--rules-file' option. If the rules file
does not exist, hledger will auto-create one with some example rules,
which you'll need to adjust.
At minimum, the rules file must identify the 'date' and 'amount'
fields. It may also be necessary to specify the date format, and the
number of header lines to skip. Eg:
At minimum, the rules file must identify the date and amount fields.
It's often necessary to specify the date format, and the number of
header lines to skip, also. Eg:
fields date, _, _, amount
date-format %d/%m/%Y
@ -63,6 +63,7 @@ account1 assets:amazon
amount -%amount
For more examples, see Convert CSV files.
* Menu:
* CSV RULES::
@ -76,6 +77,7 @@ File: hledger_csv.info, Node: CSV RULES, Next: CSV TIPS, Prev: Top, Up: Top
The following seven kinds of rule can appear in the rules file, in any
order. Blank lines and lines beginning with '#' or ';' are ignored.
* Menu:
* skip::
@ -137,8 +139,8 @@ File: hledger_csv.info, Node: field list, Next: field assignment, Prev: date-
whitespace; uninteresting names may be left blank), and (b) assigns them
to journal entry fields if you use any of these standard field names:
'date', 'date2', 'status', 'code', 'description', 'comment', 'account1',
'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'.
Eg:
'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance',
'balance1', 'balance2'. Eg:
# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
# and give the 7th and 8th fields meaningful names for later reference:
@ -244,7 +246,7 @@ File: hledger_csv.info, Node: CSV TIPS, Prev: CSV RULES, Up: Top
* CSV ordering::
* CSV accounts::
* CSV amounts::
* CSV balance assertions::
* CSV balance assertions/assignments::
* Reading multiple CSV files::

@ -269,42 +271,53 @@ two postings. It's conventional and recommended to use 'account1' for
the account whose CSV we are reading.

File: hledger_csv.info, Node: CSV amounts, Next: CSV balance assertions, Prev: CSV accounts, Up: CSV TIPS
File: hledger_csv.info, Node: CSV amounts, Next: CSV balance assertions/assignments, Prev: CSV accounts, Up: CSV TIPS
2.3 CSV amounts
===============
The 'amount' field sets the amount of the 'account1' posting.
A transaction amount must be set, in one of these ways:
If the CSV has debit/credit amounts in separate fields, assign to the
'amount-in' and 'amount-out' pseudo fields instead. (Whichever one has
a value will be used, with appropriate sign. If both contain a value,
it may not work so well.)
* with an 'amount' field assignment, which sets the first posting's
amount
If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped.
* (When the CSV has debit and credit amounts in separate fields:)
with field assignments for the 'amount-in' and 'amount-out' pseudo
fields (both of them). Whichever one has a value will be used,
with appropriate sign. If both contain a value, it might not work
so well.
If an amount value begins with a double minus sign, those will cancel
out and be removed.
* or implicitly by means of a balance assignment (see below).
If the CSV has the currency symbol in a separate field, assign that
to the 'currency' pseudo field to have it prepended to the amount. Or,
you can use a field assignment to 'amount' that interpolates both CSV
fields (giving more control, eg to put the currency symbol on the
right).
There is some special handling for sign in amounts:
* If an amount value is parenthesised, it will be de-parenthesised
and sign-flipped.
* If an amount value begins with a double minus sign, those will
cancel out and be removed.
If the currency/commodity symbol is provided as a separate CSV field,
assign it to the 'currency' pseudo field; the symbol will be prepended
to the amount (TODO: when there is an amount). Or, you can use an
'amount' field assignment for more control, eg:
fields date,description,currency,amount
amount %amount %currency

File: hledger_csv.info, Node: CSV balance assertions, Next: Reading multiple CSV files, Prev: CSV amounts, Up: CSV TIPS
File: hledger_csv.info, Node: CSV balance assertions/assignments, Next: Reading multiple CSV files, Prev: CSV amounts, Up: CSV TIPS
2.4 CSV balance assertions
==========================
2.4 CSV balance assertions/assignments
======================================
If the CSV includes a running balance, you can assign that to the
'balance' pseudo field; whenever the running balance value is non-empty,
it will be asserted as the balance after the 'account1' posting.
If the CSV includes a running balance, you can assign that to one of the
pseudo fields 'balance' (or 'balance1') or 'balance2'. This will
generate a balance assertion (or if the amount is left empty, a balance
assignment), on the first or second posting, whenever the running
balance field is non-empty. (TODO: #1000)

File: hledger_csv.info, Node: Reading multiple CSV files, Prev: CSV balance assertions, Up: CSV TIPS
File: hledger_csv.info, Node: Reading multiple CSV files, Prev: CSV balance assertions/assignments, Up: CSV TIPS
2.5 Reading multiple CSV files
==============================
@ -317,33 +330,33 @@ one rules file will be used for all the CSV files being read.

Tag Table:
Node: Top72
Node: CSV RULES2163
Ref: #csv-rules2271
Node: skip2533
Ref: #skip2627
Node: date-format2799
Ref: #date-format2926
Node: field list3476
Ref: #field-list3613
Node: field assignment4318
Ref: #field-assignment4473
Node: conditional block4977
Ref: #conditional-block5131
Node: include6027
Ref: #include6157
Node: newest-first6388
Ref: #newest-first6502
Node: CSV TIPS6913
Ref: #csv-tips7007
Node: CSV ordering7125
Ref: #csv-ordering7243
Node: CSV accounts7424
Ref: #csv-accounts7562
Node: CSV amounts7816
Ref: #csv-amounts7962
Node: CSV balance assertions8737
Ref: #csv-balance-assertions8919
Node: Reading multiple CSV files9124
Ref: #reading-multiple-csv-files9294
Node: CSV RULES2167
Ref: #csv-rules2275
Node: skip2538
Ref: #skip2632
Node: date-format2804
Ref: #date-format2931
Node: field list3481
Ref: #field-list3618
Node: field assignment4348
Ref: #field-assignment4503
Node: conditional block5007
Ref: #conditional-block5161
Node: include6057
Ref: #include6187
Node: newest-first6418
Ref: #newest-first6532
Node: CSV TIPS6943
Ref: #csv-tips7037
Node: CSV ordering7167
Ref: #csv-ordering7285
Node: CSV accounts7466
Ref: #csv-accounts7604
Node: CSV amounts7858
Ref: #csv-amounts8016
Node: CSV balance assertions/assignments9096
Ref: #csv-balance-assertionsassignments9314
Node: Reading multiple CSV files9635
Ref: #reading-multiple-csv-files9817

End Tag Table

62
hledger-lib/hledger_csv.txt
View File

@ -29,8 +29,8 @@ DESCRIPTION
you'll need to adjust.
At minimum, the rules file must identify the date and amount fields.
It may also be necessary to specify the date format, and the number of
header lines to skip. Eg:
It's often necessary to specify the date format, and the number of
header lines to skip, also. Eg:
fields date, _, _, amount
date-format %d/%m/%Y
@ -83,10 +83,10 @@ CSV RULES
date-format
date-formatDATEFMT
When your CSV date fields are not formatted like YYYY/MM/DD (or
YYYY-MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT
is a strptime-like date parsing pattern, which must parse the date
field values completely. Examples:
When your CSV date fields are not formatted like YYYY/MM/DD (or YYYY-
MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT is a
strptime-like date parsing pattern, which must parse the date field
values completely. Examples:
# for dates like "11/06/2013":
date-format %m/%d/%Y
@ -107,7 +107,8 @@ CSV RULES
space; uninteresting names may be left blank), and (b) assigns them to
journal entry fields if you use any of these standard field names:
date, date2, status, code, description, comment, account1, account2,
amount, amount-in, amount-out, currency, balance. Eg:
amount, amount-in, amount-out, currency, balance, balance1, balance2.
Eg:
# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
# and give the 7th and 8th fields meaningful names for later reference:
@ -122,8 +123,7 @@ CSV RULES
This sets a journal entry field (one of the standard names above) to
the given text value, which can include CSV field values interpolated
by name (%CSVFIELDNAME) or 1-based position (%N).
Eg:
by name (%CSVFIELDNAME) or 1-based position (%N). Eg:
# set the amount to the 4th CSV field with "USD " prepended
amount USD %4
@ -195,28 +195,40 @@ CSV TIPS
the account whose CSV we are reading.
CSV amounts
The amount field sets the amount of the account1 posting.
A transaction amount must be set, in one of these ways:
If the CSV has debit/credit amounts in separate fields, assign to the
amount-in and amount-out pseudo fields instead. (Whichever one has a
value will be used, with appropriate sign. If both contain a value, it
may not work so well.)
o with an amount field assignment, which sets the first posting's
amount
If an amount value is parenthesised, it will be de-parenthesised and
o (When the CSV has debit and credit amounts in separate fields:)
with field assignments for the amount-in and amount-out pseudo fields
(both of them). Whichever one has a value will be used, with appropri-
ate sign. If both contain a value, it might not work so well.
o or implicitly by means of a balance assignment (see below).
There is some special handling for sign in amounts:
o If an amount value is parenthesised, it will be de-parenthesised and
sign-flipped.
If an amount value begins with a double minus sign, those will cancel
o If an amount value begins with a double minus sign, those will cancel
out and be removed.
If the CSV has the currency symbol in a separate field, assign that to
the currency pseudo field to have it prepended to the amount. Or, you
can use a field assignment to amount that interpolates both CSV fields
(giving more control, eg to put the currency symbol on the right).
If the currency/commodity symbol is provided as a separate CSV field,
assign it to the currency pseudo field; the symbol will be prepended to
the amount (TODO: when there is an amount). Or, you can use an amount
field assignment for more control, eg:
CSV balance assertions
If the CSV includes a running balance, you can assign that to the bal-
ance pseudo field; whenever the running balance value is non-empty, it
will be asserted as the balance after the account1 posting.
fields date,description,currency,amount
amount %amount %currency
CSV balance assertions/assignments
If the CSV includes a running balance, you can assign that to one of
the pseudo fields balance (or balance1) or balance2. This will gener-
ate a balance assertion (or if the amount is left empty, a balance
assignment), on the first or second posting, whenever the running bal-
ance field is non-empty. (TODO: #1000)
Reading multiple CSV files
You can read multiple CSV files at once using multiple -f arguments on
@ -249,4 +261,4 @@ SEE ALSO
hledger 1.14 March 2019 hledger_csv(5)
hledger 1.14.99 March 2019 hledger_csv(5)

1066
hledger-lib/hledger_journal.5
View File

File diff suppressed because it is too large Load Diff

256
hledger-lib/hledger_journal.info
View File

@ -4,8 +4,8 @@ stdin.

File: hledger_journal.info, Node: Top, Next: FILE FORMAT, Up: (dir)
hledger_journal(5) hledger 1.14
*******************************
hledger_journal(5) hledger 1.14.99
**********************************
hledger's usual data source is a plain text file containing journal
entries in hledger journal format. This file represents a standard
@ -82,7 +82,7 @@ File: hledger_journal.info, Node: FILE FORMAT, Next: EDITOR SUPPORT, Prev: To
* Tags::
* Directives::
* Periodic transactions::
* Transaction modifiers::
* Auto postings / transaction modifiers::

File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT
@ -296,6 +296,7 @@ and status mark (or until a comment begins). Sometimes called the
"narration" in traditional bookkeeping, it can be used for whatever you
wish, or left blank. Transaction descriptions can be queried, unlike
comments.
* Menu:
* Payee and note::
@ -467,6 +468,7 @@ can protect you from, eg, inadvertently disrupting reconciled balances
while cleaning up old entries. You can disable them temporarily with
the '-I/--ignore-assertions' flag, which can be useful for
troubleshooting or for reading Ledger files.
* Menu:
* Assertions and ordering::
@ -655,6 +657,7 @@ of the commodity to that account since the last balance assertion or
assignment). 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.
* Menu:
* Balance assignments and prices::
@ -914,6 +917,7 @@ 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. It can be surprising at
times though.
* Menu:
* Comment blocks::
@ -1248,6 +1252,7 @@ They do not affect account names being entered via hledger add or
hledger-web.
See also Cookbook: Rewrite account names.
* Menu:
* Basic aliases::
@ -1372,7 +1377,7 @@ If account aliases are present, they are applied after the default
parent account.

File: hledger_journal.info, Node: Periodic transactions, Next: Transaction modifiers, Prev: Directives, Up: FILE FORMAT
File: hledger_journal.info, Node: Periodic transactions, Next: Auto postings / transaction modifiers, Prev: Directives, Up: FILE FORMAT
1.15 Periodic transactions
==========================
@ -1398,6 +1403,7 @@ date must fall on a natural boundary of the interval. Eg 'monthly from
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.
* Menu:
* Two spaces after the period expression::
@ -1482,29 +1488,29 @@ compared in budget reports.
and Forecasting.

File: hledger_journal.info, Node: Transaction modifiers, Prev: Periodic transactions, Up: FILE FORMAT
File: hledger_journal.info, Node: Auto postings / transaction modifiers, Prev: Periodic transactions, Up: FILE FORMAT
1.16 Transaction modifiers
==========================
1.16 Auto postings / 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 "automated
postings" or "auto postings".
Transaction modifier rules describe changes to be applied automatically
to certain matched transactions. Currently just one kind of change is
possible - adding extra postings, which we call "automated postings" or
just "auto postings". These rules become active when you use the
'--auto' flag.
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:
A transaction modifier, AKA auto posting rule, looks much 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
ACCT AMT
ACCT [AMT]
...
These posting 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.
@ -1517,6 +1523,10 @@ be:
and symbol S). The matched posting's amount will be multiplied by
N, and its commodity symbol will be replaced with S.
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.
Some examples:
; every time I buy food, schedule a dollar donation
@ -1553,7 +1563,7 @@ $ hledger print --auto
* Auto postings and transaction balancing / inferred amounts / balance assertions::

File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Transaction modifiers
File: hledger_journal.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings / transaction modifiers
1.16.1 Auto postings and transaction balancing / inferred amounts /
-------------------------------------------------------------------
@ -1585,109 +1595,109 @@ See the [[Cookbook]] at hledger.org for the latest information.

Tag Table:
Node: Top76
Node: FILE FORMAT2372
Ref: #file-format2496
Node: Transactions2783
Ref: #transactions2904
Node: Postings3588
Ref: #postings3715
Node: Dates4710
Ref: #dates4825
Node: Simple dates4890
Ref: #simple-dates5016
Node: Secondary dates5382
Ref: #secondary-dates5536
Node: Posting dates7099
Ref: #posting-dates7228
Node: Status8602
Ref: #status8722
Node: Description10430
Ref: #description10568
Node: Payee and note10887
Ref: #payee-and-note11001
Node: Account names11243
Ref: #account-names11386
Node: Amounts11873
Ref: #amounts12009
Node: Virtual Postings15026
Ref: #virtual-postings15185
Node: Balance Assertions16405
Ref: #balance-assertions16580
Node: Assertions and ordering17538
Ref: #assertions-and-ordering17724
Node: Assertions and included files18424
Ref: #assertions-and-included-files18665
Node: Assertions and multiple -f options18998
Ref: #assertions-and-multiple--f-options19252
Node: Assertions and commodities19384
Ref: #assertions-and-commodities19614
Node: Assertions and prices20770
Ref: #assertions-and-prices20982
Node: Assertions and subaccounts21422
Ref: #assertions-and-subaccounts21649
Node: Assertions and virtual postings21973
Ref: #assertions-and-virtual-postings22213
Node: Assertions and precision22355
Ref: #assertions-and-precision22546
Node: Balance Assignments22813
Ref: #balance-assignments22994
Node: Balance assignments and prices24158
Ref: #balance-assignments-and-prices24330
Node: Transaction prices24554
Ref: #transaction-prices24723
Node: Comments26991
Ref: #comments27125
Node: Tags28295
Ref: #tags28413
Node: Directives29815
Ref: #directives29958
Node: Comment blocks35565
Ref: #comment-blocks35710
Node: Including other files35886
Ref: #including-other-files36066
Node: Default year36474
Ref: #default-year36643
Node: Declaring commodities37066
Ref: #declaring-commodities37249
Node: Default commodity38476
Ref: #default-commodity38652
Node: Market prices39288
Ref: #market-prices39453
Node: Declaring accounts40294
Ref: #declaring-accounts40470
Node: Account comments41395
Ref: #account-comments41558
Node: Account subdirectives41953
Ref: #account-subdirectives42148
Node: Account types42461
Ref: #account-types42645
Node: Account display order44289
Ref: #account-display-order44459
Node: Rewriting accounts45588
Ref: #rewriting-accounts45773
Node: Basic aliases46507
Ref: #basic-aliases46653
Node: Regex aliases47357
Ref: #regex-aliases47528
Node: Multiple aliases48246
Ref: #multiple-aliases48421
Node: end aliases48919
Ref: #end-aliases49066
Node: Default parent account49167
Ref: #default-parent-account49333
Node: Periodic transactions50217
Ref: #periodic-transactions50399
Node: Two spaces after the period expression51524
Ref: #two-spaces-after-the-period-expression51769
Node: Forecasting with periodic transactions52254
Ref: #forecasting-with-periodic-transactions52544
Node: Budgeting with periodic transactions54231
Ref: #budgeting-with-periodic-transactions54470
Node: Transaction modifiers54929
Ref: #transaction-modifiers55092
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57076
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57377
Node: EDITOR SUPPORT57755
Ref: #editor-support57873
Node: FILE FORMAT2378
Ref: #file-format2502
Node: Transactions2805
Ref: #transactions2926
Node: Postings3610
Ref: #postings3737
Node: Dates4732
Ref: #dates4847
Node: Simple dates4912
Ref: #simple-dates5038
Node: Secondary dates5404
Ref: #secondary-dates5558
Node: Posting dates7121
Ref: #posting-dates7250
Node: Status8624
Ref: #status8744
Node: Description10452
Ref: #description10590
Node: Payee and note10910
Ref: #payee-and-note11024
Node: Account names11266
Ref: #account-names11409
Node: Amounts11896
Ref: #amounts12032
Node: Virtual Postings15049
Ref: #virtual-postings15208
Node: Balance Assertions16428
Ref: #balance-assertions16603
Node: Assertions and ordering17562
Ref: #assertions-and-ordering17748
Node: Assertions and included files18448
Ref: #assertions-and-included-files18689
Node: Assertions and multiple -f options19022
Ref: #assertions-and-multiple--f-options19276
Node: Assertions and commodities19408
Ref: #assertions-and-commodities19638
Node: Assertions and prices20794
Ref: #assertions-and-prices21006
Node: Assertions and subaccounts21446
Ref: #assertions-and-subaccounts21673
Node: Assertions and virtual postings21997
Ref: #assertions-and-virtual-postings22237
Node: Assertions and precision22379
Ref: #assertions-and-precision22570
Node: Balance Assignments22837
Ref: #balance-assignments23018
Node: Balance assignments and prices24183
Ref: #balance-assignments-and-prices24355
Node: Transaction prices24579
Ref: #transaction-prices24748
Node: Comments27016
Ref: #comments27150
Node: Tags28320
Ref: #tags28438
Node: Directives29840
Ref: #directives29983
Node: Comment blocks35591
Ref: #comment-blocks35736
Node: Including other files35912
Ref: #including-other-files36092
Node: Default year36500
Ref: #default-year36669
Node: Declaring commodities37092
Ref: #declaring-commodities37275
Node: Default commodity38502
Ref: #default-commodity38678
Node: Market prices39314
Ref: #market-prices39479
Node: Declaring accounts40320
Ref: #declaring-accounts40496
Node: Account comments41421
Ref: #account-comments41584
Node: Account subdirectives41979
Ref: #account-subdirectives42174
Node: Account types42487
Ref: #account-types42671
Node: Account display order44315
Ref: #account-display-order44485
Node: Rewriting accounts45614
Ref: #rewriting-accounts45799
Node: Basic aliases46534
Ref: #basic-aliases46680
Node: Regex aliases47384
Ref: #regex-aliases47555
Node: Multiple aliases48273
Ref: #multiple-aliases48448
Node: end aliases48946
Ref: #end-aliases49093
Node: Default parent account49194
Ref: #default-parent-account49360
Node: Periodic transactions50244
Ref: #periodic-transactions50442
Node: Two spaces after the period expression51568
Ref: #two-spaces-after-the-period-expression51813
Node: Forecasting with periodic transactions52298
Ref: #forecasting-with-periodic-transactions52588
Node: Budgeting with periodic transactions54275
Ref: #budgeting-with-periodic-transactions54514
Node: Auto postings / transaction modifiers54973
Ref: #auto-postings-transaction-modifiers55184
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57356
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57673
Node: EDITOR SUPPORT58051
Ref: #editor-support58169

End Tag Table

141
hledger-lib/hledger_journal.txt
View File

@ -237,8 +237,8 @@ FILE FORMAT
Account names
Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can
be anything you like, but in finance there are traditionally five
top-level accounts: assets, liabilities, income, expenses, and equity.
be anything you like, but in finance there are traditionally five top-
level accounts: assets, liabilities, income, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more
@ -384,12 +384,12 @@ FILE FORMAT
Ledger assertions do not see the accumulated effect of repeated post-
ings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder differ-
ently-dated transactions within the journal. But if you reorder
same-dated transactions or postings, assertions might break and require
updating. This order dependence does bring an advantage: precise con-
trol over the order of postings and assertions within a day, so you can
assert intra-day balances.
So, hledger balance assertions keep working if you reorder differently-
dated transactions within the journal. But if you reorder same-dated
transactions or postings, assertions might break and require updating.
This order dependence does bring an advantage: precise control over the
order of postings and assertions within a day, so you can assert intra-
day balances.
Assertions and included files
With included files, things are a little more complicated. Including
@ -418,17 +418,17 @@ FILE FORMAT
2013/1/1
a $1
a 1
a 1EUR
b $-1
c -1
c -1EUR
2013/1/2 ; These assertions succeed
a 0 = $1
a 0 = 1
a 0 = 1EUR
b 0 == $-1
c 0 == -1
c 0 == -1EUR
2013/1/3 ; This assertion fails as 'a' also contains 1
2013/1/3 ; This assertion fails as 'a' also contains 1EUR
a 0 == $1
It's not yet possible to make a complete assertion about a balance that
@ -437,20 +437,20 @@ FILE FORMAT
2013/1/1
a:usd $1
a:euro 1
a:euro 1EUR
b
2013/1/2
a 0 == 0
a:usd 0 == $1
a:euro 0 == 1
a:euro 0 == 1EUR
Assertions and prices
Balance assertions ignore transaction prices, and should normally be
written without one:
2019/1/1
(a) $1 @ 1 = $1
(a) $1 @ EUR1 = $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.
@ -512,11 +512,11 @@ FILE FORMAT
amount to have that price attached:
2019/1/1
(a) = $1 @ 2
(a) = $1 @ EUR2
$ hledger print --explicit
2019/01/01
(a) $1 @ 2 = $1 @ 2
(a) $1 @ EUR2 = $1 @ EUR2
Transaction prices
Within a transaction, you can note an amount's price in another commod-
@ -532,20 +532,20 @@ FILE FORMAT
1. Write the price per unit, as @ UNITPRICE after the amount:
2009/1/1
assets:euros 100 @ $1.35 ; one hundred euros purchased at $1.35 each
assets:euros EUR100 @ $1.35 ; one hundred euros purchased at $1.35 each
assets:dollars ; balancing amount is -$135.00
2. Write the total price, as @@ TOTALPRICE after the amount:
2009/1/1
assets:euros 100 @@ $135 ; one hundred euros purchased at $135 for the lot
assets:euros EUR100 @@ $135 ; one hundred euros purchased at $135 for the lot
assets:dollars
3. Specify amounts for all postings, using exactly two commodities, and
let hledger infer the price that balances the transaction:
2009/1/1
assets:euros 100 ; one hundred euros purchased
assets:euros EUR100 ; one hundred euros purchased
assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
@ -557,7 +557,7 @@ FILE FORMAT
$ hledger bal -N --flat
$-135 assets:dollars
100 assets:euros
EUR100 assets:euros
$ hledger bal -N --flat -B
$-135 assets:dollars
$135 assets:euros # <- the euros' cost
@ -569,11 +569,11 @@ FILE FORMAT
2009/1/1
assets:dollars $-135 ; 135 dollars sold
assets:euros 100 ; for 100 euros
assets:euros EUR100 ; for 100 euros
$ hledger bal -N --flat -B
-100 assets:dollars # <- the dollars' selling price
100 assets:euros
EUR-100 assets:dollars # <- the dollars' selling price
EUR100 assets:euros
Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star
@ -608,8 +608,8 @@ 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
end comment directives.
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
@ -641,8 +641,8 @@ FILE FORMAT
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):
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
@ -665,7 +665,7 @@ FILE FORMAT
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
play order after
@ -673,23 +673,23 @@ FILE FORMAT
alias end aliases rewrite account names following
inline/included
alias end rewrite account names following
aliases inline/included
entries until end
of current file or
end directive
apply account end apply account prepend a common parent to following
account names inline/included
apply end apply prepend a common parent to following
account account account names inline/included
entries until end
of current file or
end directive
comment end comment ignore part of journal following
inline/included
comment end com- ignore part of journal following
ment inline/included
entries until end
of current file or
end directive
commodity format declare a commodity and its number notation:
number notation & display following entries
commod- format declare a commodity and its number notation:
ity number notation & display following entries
style in that commodity
in all files; dis-
play style: amounts
@ -853,8 +853,8 @@ FILE FORMAT
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
P 2009/1/1 EUR $1.35
P 2010/1/1 EUR $1.40
The -V/--value flag can be used to convert reported amounts to another
commodity using these prices.
@ -876,8 +876,8 @@ FILE FORMAT
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,
hledger-iadd, hledger-web, ledger-mode etc.
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
account name, eg:
@ -1005,8 +1005,8 @@ 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
hledger-web.
do not affect account names being entered via hledger add or hledger-
web.
See also Cookbook: Rewrite account names.
@ -1048,11 +1048,11 @@ FILE FORMAT
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
aliases are non-recursive by default). Aliases are applied in the fol-
lowing order:
You can define as many aliases as you like using directives or command-
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 following
order:
1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored)
@ -1060,8 +1060,8 @@ FILE FORMAT
2. alias options, in the order they appear on the command line
end aliases
You can clear (forget) all currently defined aliases with the
end aliases directive:
You can clear (forget) all currently defined aliases with the end
aliases directive:
end aliases
@ -1116,8 +1116,8 @@ FILE FORMAT
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
monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not.
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
@ -1188,25 +1188,25 @@ FILE FORMAT
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
"automated postings" or "auto postings".
Auto postings / transaction modifiers
Transaction modifier rules describe changes to be applied automatically
to certain matched transactions. Currently just one kind of change is
possible - adding extra postings, which we call "automated postings" or
just "auto postings". These rules become active when you use the
--auto flag.
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:
A transaction modifier, AKA auto posting rule, looks much 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
ACCT AMT
ACCT [AMT]
...
These posting rules look like normal postings, except the amount can
be:
These posting-generating rules look like normal postings, except the
amount can be:
o a normal amount with a commodity symbol, eg $2. This will be used
as-is.
@ -1222,6 +1222,10 @@ FILE FORMAT
symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S.
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.
Some examples:
; every time I buy food, schedule a dollar donation
@ -1253,9 +1257,8 @@ FILE FORMAT
assets:checking:gifts -$20
assets:checking $20
Auto postings and transaction balancing / inferred amounts / balance
assertions
Auto postings and transaction balancing / inferred amounts / balance asser-
tions
Currently, transaction modifiers are applied / auto postings are added:
o after missing amounts are inferred, and transactions are checked for
@ -1301,4 +1304,4 @@ SEE ALSO
hledger 1.14 March 2019 hledger_journal(5)
hledger 1.14.99 March 2019 hledger_journal(5)

58
hledger-lib/hledger_timeclock.5
View File

@ -1,74 +1,74 @@
.TH "hledger_timeclock" "5" "March 2019" "hledger 1.14" "hledger User Manuals"
.TH "hledger_timeclock" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals"
.SH NAME
.PP
Timeclock \- the time logging format of timeclock.el, as read by hledger
Timeclock - the time logging format of timeclock.el, as read by hledger
.SH DESCRIPTION
.PP
hledger can read timeclock files.
As with Ledger, these are (a subset of) timeclock.el\[aq]s format,
containing clock\-in and clock\-out entries as in the example below.
containing clock-in and clock-out entries as in the example below.
The date is a simple date.
The time format is HH:MM[:SS][+\-ZZZZ].
The time format is HH:MM[:SS][+-ZZZZ].
Seconds and timezone are optional.
The timezone, if present, must be four digits and is ignored (currently
the time is always interpreted as a local time).
.IP
.nf
\f[C]
i\ 2015/03/30\ 09:00:00\ some:account\ name\ \ optional\ description\ after\ two\ spaces
o\ 2015/03/30\ 09:20:00
i\ 2015/03/31\ 22:21:45\ another\ account
o\ 2015/04/01\ 02:00:34
\f[]
i 2015/03/30 09:00:00 some:account name optional description after two spaces
o 2015/03/30 09:20:00
i 2015/03/31 22:21:45 another account
o 2015/04/01 02:00:34
\f[R]
.fi
.PP
hledger treats each clock\-in/clock\-out pair as a transaction posting
hledger treats each clock-in/clock-out pair as a transaction posting
some number of hours to an account.
Or if the session spans more than one day, it is split into several
transactions, one for each day.
For the above time log, \f[C]hledger\ print\f[] generates these journal
For the above time log, \f[C]hledger print\f[R] generates these journal
entries:
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.timeclock\ print
2015/03/30\ *\ optional\ description\ after\ two\ spaces
\ \ \ \ (some:account\ name)\ \ \ \ \ \ \ \ \ 0.33h
$ hledger -f t.timeclock print
2015/03/30 * optional description after two spaces
(some:account name) 0.33h
2015/03/31\ *\ 22:21\-23:59
\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 1.64h
2015/03/31 * 22:21-23:59
(another account) 1.64h
2015/04/01\ *\ 00:00\-02:00
\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 2.01h
\f[]
2015/04/01 * 00:00-02:00
(another account) 2.01h
\f[R]
.fi
.PP
Here is a sample.timeclock to download and some queries to try:
.IP
.nf
\f[C]
$\ hledger\ \-f\ sample.timeclock\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ current\ time\ balances
$\ hledger\ \-f\ sample.timeclock\ register\ \-p\ 2009/3\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ sessions\ in\ march\ 2009
$\ hledger\ \-f\ sample.timeclock\ register\ \-p\ weekly\ \-\-depth\ 1\ \-\-empty\ \ #\ time\ summary\ by\ week
\f[]
$ hledger -f sample.timeclock balance # current time balances
$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009
$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week
\f[R]
.fi
.PP
To generate time logs, ie to clock in and clock out, you could:
.IP \[bu] 2
use emacs and the built\-in timeclock.el, or the extended
timeclock\-x.el and perhaps the extras in ledgerutils.el
use emacs and the built-in timeclock.el, or the extended timeclock-x.el
and perhaps the extras in ledgerutils.el
.IP \[bu] 2
at the command line, use these bash aliases:
\f[C]shell\ \ \ alias\ ti="echo\ i\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ \\$*\ >>$TIMELOG"\ \ \ alias\ to="echo\ o\ `date\ \[aq]+%Y\-%m\-%d\ %H:%M:%S\[aq]`\ >>$TIMELOG"\f[]
\f[C]shell alias ti=\[dq]echo i \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] \[rs]$* >>$TIMELOG\[dq] alias to=\[dq]echo o \[ga]date \[aq]+%Y-%m-%d %H:%M:%S\[aq]\[ga] >>$TIMELOG\[dq]\f[R]
.IP \[bu] 2
or use the old \f[C]ti\f[] and \f[C]to\f[] scripts in the ledger 2.x
or use the old \f[C]ti\f[R] and \f[C]to\f[R] scripts in the ledger 2.x
repository.
These rely on a "timeclock" executable which I think is just the ledger
2 executable renamed.
These rely on a \[dq]timeclock\[dq] executable which I think is just the
ledger 2 executable renamed.
.SH "REPORTING BUGS"

5
hledger-lib/hledger_timeclock.info
View File

@ -4,8 +4,8 @@ stdin.

File: hledger_timeclock.info, Node: Top, Up: (dir)
hledger_timeclock(5) hledger 1.14
*********************************
hledger_timeclock(5) hledger 1.14.99
************************************
hledger can read timeclock files. As with Ledger, these are (a subset
of) timeclock.el's format, containing clock-in and clock-out entries as
@ -48,6 +48,7 @@ $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summa
* at the command line, use these bash aliases: 'shell alias ti="echo
i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
`date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"'
* or use the old 'ti' and 'to' scripts in the ledger 2.x repository.
These rely on a "timeclock" executable which I think is just the
ledger 2 executable renamed.

11
hledger-lib/hledger_timeclock.txt
View File

@ -42,11 +42,12 @@ DESCRIPTION
To generate time logs, ie to clock in and clock out, you could:
o use emacs and the built-in timeclock.el, or the extended time-
clock-x.el and perhaps the extras in ledgerutils.el
o use emacs and the built-in timeclock.el, or the extended timeclock-
x.el and perhaps the extras in ledgerutils.el
o at the command line, use these bash aliases:
shell alias ti="echo i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
o at the command line, use these bash aliases: shell alias ti="echo i
`date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o `date
'+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"
o or use the old ti and to scripts in the ledger 2.x repository. These
rely on a "timeclock" executable which I think is just the ledger 2
@ -77,4 +78,4 @@ SEE ALSO
hledger 1.14 March 2019 hledger_timeclock(5)
hledger 1.14.99 March 2019 hledger_timeclock(5)

104
hledger-lib/hledger_timedot.5
View File

@ -1,32 +1,32 @@
.TH "hledger_timedot" "5" "March 2019" "hledger 1.14" "hledger User Manuals"
.TH "hledger_timedot" "5" "March 2019" "hledger 1.14.99" "hledger User Manuals"
.SH NAME
.PP
Timedot \- hledger\[aq]s human\-friendly time logging format
Timedot - hledger\[aq]s human-friendly time logging format
.SH DESCRIPTION
.PP
Timedot is a plain text format for logging dated, categorised quantities
(of time, usually), supported by hledger.
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.
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.
.PP
Though called "timedot", this format is read by hledger as commodityless
quantities, so it could be used to represent dated quantities other than
time.
Though called \[dq]timedot\[dq], this format is read by hledger as
commodityless quantities, so it could be used to represent dated
quantities other than time.
In the docs below we\[aq]ll assume it\[aq]s time.
.SH FILE FORMAT
.PP
A timedot file contains a series of day entries.
A day entry begins with a date, and is followed by category/quantity
pairs, one per line.
Dates are hledger\-style simple dates (see hledger_journal(5)).
Categories are hledger\-style account names, optionally indented.
Dates are hledger-style simple dates (see hledger_journal(5)).
Categories are hledger-style account names, optionally indented.
As in a hledger journal, there must be at least two spaces between the
category (account name) and the quantity.
.PP
@ -41,9 +41,9 @@ an integral or decimal number, representing hours.
Eg: 1.5
.IP \[bu] 2
an integral or decimal number immediately followed by a unit symbol
\f[C]s\f[], \f[C]m\f[], \f[C]h\f[], \f[C]d\f[], \f[C]w\f[], \f[C]mo\f[],
or \f[C]y\f[], representing seconds, minutes, hours, days weeks, months
or years respectively.
\f[C]s\f[R], \f[C]m\f[R], \f[C]h\f[R], \f[C]d\f[R], \f[C]w\f[R],
\f[C]mo\f[R], or \f[C]y\f[R], representing seconds, minutes, hours, days
weeks, months or years respectively.
Eg: 90m.
The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m,
1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
@ -53,16 +53,16 @@ An example:
.IP
.nf
\f[C]
#\ 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
inc:client1\ \ \ ....\ ....\ ....\ ....\ ....\ ....
fos:haskell\ \ \ ....\ ..\
biz:research\ \ .
inc:client1 .... .... .... .... .... ....
fos:haskell .... ..
biz:research .
2016/2/2
inc:client1\ \ \ ....\ ....
biz:research\ \ .
\f[]
inc:client1 .... ....
biz:research .
\f[R]
.fi
.PP
Or with numbers:
@ -70,42 +70,42 @@ Or with numbers:
.nf
\f[C]
2016/2/3
inc:client1\ \ \ 4
fos:hledger\ \ \ 3
biz:research\ \ 1
\f[]
inc:client1 4
fos:hledger 3
biz:research 1
\f[R]
.fi
.PP
Reporting:
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.timedot\ print\ date:2016/2/2
2016/02/02\ *
\ \ \ \ (inc:client1)\ \ \ \ \ \ \ \ \ \ 2.00
$ hledger -f t.timedot print date:2016/2/2
2016/02/02 *
(inc:client1) 2.00
2016/02/02\ *
\ \ \ \ (biz:research)\ \ \ \ \ \ \ \ \ \ 0.25
\f[]
2016/02/02 *
(biz:research) 0.25
\f[R]
.fi
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.timedot\ bal\ \-\-daily\ \-\-tree
Balance\ changes\ in\ 2016/02/01\-2016/02/03:
$ hledger -f t.timedot bal --daily --tree
Balance changes in 2016/02/01-2016/02/03:
\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ 2016/02/01d\ \ 2016/02/02d\ \ 2016/02/03d\
|| 2016/02/01d 2016/02/02d 2016/02/03d
============++========================================
\ biz\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\
\ \ \ research\ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\
\ fos\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\
\ \ \ haskell\ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\
\ \ \ hledger\ \ ||\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\
\ inc\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\
\ \ \ client1\ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\
\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 7.75\ \ \ \ \ \ \ \ \ 2.25\ \ \ \ \ \ \ \ \ 8.00\
\f[]
biz || 0.25 0.25 1.00
research || 0.25 0.25 1.00
fos || 1.50 0 3.00
haskell || 1.50 0 0
hledger || 0 0 3.00
inc || 6.00 2.00 4.00
client1 || 6.00 2.00 4.00
------------++----------------------------------------
|| 7.75 2.25 8.00
\f[R]
.fi
.PP
I prefer to use period for separating account components.
@ -114,20 +114,20 @@ We can make this work with an account alias:
.nf
\f[C]
2016/2/4
fos.hledger.timedot\ \ 4
fos.ledger\ \ \ \ \ \ \ \ \ \ \ ..
\f[]
fos.hledger.timedot 4
fos.ledger ..
\f[R]
.fi
.IP
.nf
\f[C]
$\ hledger\ \-f\ t.timedot\ \-\-alias\ /\\\\./=:\ bal\ date:2016/2/4
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50\ \ fos
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.00\ \ \ \ hledger:timedot
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0.50\ \ \ \ ledger
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50
\f[]
$ hledger -f t.timedot --alias /\[rs]\[rs]./=: bal date:2016/2/4
4.50 fos
4.00 hledger:timedot
0.50 ledger
--------------------
4.50
\f[R]
.fi
.PP
Here is a sample.timedot.

9
hledger-lib/hledger_timedot.info
View File

@ -4,8 +4,8 @@ stdin.

File: hledger_timedot.info, Node: Top, Next: FILE FORMAT, Up: (dir)
hledger_timedot(5) hledger 1.14
*******************************
hledger_timedot(5) hledger 1.14.99
**********************************
Timedot is a plain text format for logging dated, categorised quantities
(of time, usually), supported by hledger. It is convenient for
@ -17,6 +17,7 @@ glance where time was spent.
Though called "timedot", this format is read by hledger as
commodityless quantities, so it could be used to represent dated
quantities other than time. In the docs below we'll assume it's time.
* Menu:
* FILE FORMAT::
@ -110,7 +111,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4

Tag Table:
Node: Top76
Node: FILE FORMAT807
Ref: #file-format908
Node: FILE FORMAT814
Ref: #file-format915

End Tag Table

10
hledger-lib/hledger_timedot.txt
View File

@ -9,10 +9,10 @@ NAME
DESCRIPTION
Timedot is a plain text format for logging dated, categorised quanti-
ties (of time, usually), supported by hledger. 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. It can be formatted like a bar chart, making clear at a
glance where time was spent.
approximate and retroactive time logging, eg when the real-time clock-
in/out required with a timeclock file is too precise or too interrup-
tive. 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 commodity-
less quantities, so it could be used to represent dated quantities
@ -124,4 +124,4 @@ SEE ALSO
hledger 1.14 March 2019 hledger_timedot(5)
hledger 1.14.99 March 2019 hledger_timedot(5)

357
hledger-ui/hledger-ui.1
View File

@ -1,227 +1,161 @@
.TH "hledger\-ui" "1" "March 2019" "hledger\-ui 1.14" "hledger User Manuals"
.TH "hledger-ui" "1" "March 2019" "hledger-ui 1.14.99" "hledger User Manuals"
.SH NAME
.PP
hledger\-ui \- curses\-style interface for the hledger accounting tool
hledger-ui - curses-style interface for the hledger accounting tool
.SH SYNOPSIS
.PP
\f[C]hledger\-ui\ [OPTIONS]\ [QUERYARGS]\f[]
\f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]
.PD 0
.P
.PD
\f[C]hledger\ ui\ \-\-\ [OPTIONS]\ [QUERYARGS]\f[]
\f[C]hledger ui -- [OPTIONS] [QUERYARGS]\f[R]
.SH DESCRIPTION
.PP
hledger is a cross\-platform program for tracking money, time, or any
other commodity, using double\-entry accounting and a simple, editable
hledger is a cross-platform program for tracking money, time, or any
other commodity, using double-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger\-ui is hledger\[aq]s curses\-style interface, providing an
efficient full\-window text UI for viewing accounts and transactions,
and some limited data entry capability.
It is easier than hledger\[aq]s command\-line interface, and sometimes
hledger-ui is hledger\[aq]s curses-style interface, providing an
efficient full-window text UI for viewing accounts and transactions, and
some limited data entry capability.
It is easier than hledger\[aq]s command-line interface, and sometimes
quicker and more convenient than the web interface.
.PP
Note hledger\-ui has some different defaults (experimental):
Note hledger-ui has some different defaults (experimental):
.IP \[bu] 2
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).
.IP \[bu] 2
it hides transactions dated in the future by default (change this with
\-\-future or the F key).
--future or the F key).
.PP
Like hledger, it reads data from one or more files in hledger journal,
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[]).
timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1), hledger_journal(5) etc.
.SH OPTIONS
.PP
Note: if invoking hledger\-ui as a hledger subcommand, write
\f[C]\-\-\f[] before options as shown above.
Note: if invoking hledger-ui as a hledger subcommand, write \f[C]--\f[R]
before options as shown above.
.PP
Any QUERYARGS are interpreted as a hledger search query which filters
the data.
.TP
.B \f[C]\-\-watch\f[]
.B \f[C]--watch\f[R]
watch for data and date changes and reload automatically
.RS
.RE
.TP
.B \f[C]\-\-theme=default|terminal|greenterm\f[]
.B \f[C]--theme=default|terminal|greenterm\f[R]
use this custom display theme
.RS
.RE
.TP
.B \f[C]\-\-register=ACCTREGEX\f[]
.B \f[C]--register=ACCTREGEX\f[R]
start in the (first) matched account\[aq]s register screen
.RS
.RE
.TP
.B \f[C]\-\-change\f[]
.B \f[C]--change\f[R]
show period balances (changes) at startup instead of historical balances
.RS
.RE
.TP
.B \f[C]\-F\ \-\-flat\f[]
.B \f[C]-F --flat\f[R]
show accounts as a list (default)
.RS
.RE
.TP
.B \f[C]\-T\ \-\-tree\f[]
.B \f[C]-T --tree\f[R]
show accounts as a tree
.RS
.RE
.TP
.B \f[C]\-\-future\f[]
.B \f[C]--future\f[R]
show transactions dated later than today (normally hidden)
.RS
.RE
.PP
hledger input options:
.TP
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[]
.B \f[C]-f FILE --file=FILE\f[R]
use a different input file.
For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or
\f[C]$HOME/.hledger.journal\f[])
.RS
.RE
For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
\f[C]$HOME/.hledger.journal\f[R])
.TP
.B \f[C]\-\-rules\-file=RULESFILE\f[]
.B \f[C]--rules-file=RULESFILE\f[R]
Conversion rules file to use when reading CSV (default: FILE.rules)
.RS
.RE
.TP
.B \f[C]\-\-separator=CHAR\f[]
.B \f[C]--separator=CHAR\f[R]
Field separator to expect when reading CSV (default: \[aq],\[aq])
.RS
.RE
.TP
.B \f[C]\-\-alias=OLD=NEW\f[]
.B \f[C]--alias=OLD=NEW\f[R]
rename accounts named OLD to NEW
.RS
.RE
.TP
.B \f[C]\-\-anon\f[]
.B \f[C]--anon\f[R]
anonymize accounts and payees
.RS
.RE
.TP
.B \f[C]\-\-pivot\ FIELDNAME\f[]
.B \f[C]--pivot FIELDNAME\f[R]
use some other field or tag for the account name
.RS
.RE
.TP
.B \f[C]\-I\ \-\-ignore\-assertions\f[]
.B \f[C]-I --ignore-assertions\f[R]
ignore any failing balance assertions
.RS
.RE
.PP
hledger reporting options:
.TP
.B \f[C]\-b\ \-\-begin=DATE\f[]
.B \f[C]-b --begin=DATE\f[R]
include postings/txns on or after this date
.RS
.RE
.TP
.B \f[C]\-e\ \-\-end=DATE\f[]
.B \f[C]-e --end=DATE\f[R]
include postings/txns before this date
.RS
.RE
.TP
.B \f[C]\-D\ \-\-daily\f[]
.B \f[C]-D --daily\f[R]
multiperiod/multicolumn report by day
.RS
.RE
.TP
.B \f[C]\-W\ \-\-weekly\f[]
.B \f[C]-W --weekly\f[R]
multiperiod/multicolumn report by week
.RS
.RE
.TP
.B \f[C]\-M\ \-\-monthly\f[]
.B \f[C]-M --monthly\f[R]
multiperiod/multicolumn report by month
.RS
.RE
.TP
.B \f[C]\-Q\ \-\-quarterly\f[]
.B \f[C]-Q --quarterly\f[R]
multiperiod/multicolumn report by quarter
.RS
.RE
.TP
.B \f[C]\-Y\ \-\-yearly\f[]
.B \f[C]-Y --yearly\f[R]
multiperiod/multicolumn report by year
.RS
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
.B \f[C]-p --period=PERIODEXP\f[R]
set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above)
.RS
.RE
.TP
.B \f[C]\-\-date2\f[]
.B \f[C]--date2\f[R]
match the secondary date instead (see command help for other effects)
.RS
.RE
.TP
.B \f[C]\-U\ \-\-unmarked\f[]
include only unmarked postings/txns (can combine with \-P or \-C)
.RS
.RE
.B \f[C]-U --unmarked\f[R]
include only unmarked postings/txns (can combine with -P or -C)
.TP
.B \f[C]\-P\ \-\-pending\f[]
.B \f[C]-P --pending\f[R]
include only pending postings/txns
.RS
.RE
.TP
.B \f[C]\-C\ \-\-cleared\f[]
.B \f[C]-C --cleared\f[R]
include only cleared postings/txns
.RS
.RE
.TP
.B \f[C]\-R\ \-\-real\f[]
include only non\-virtual postings
.RS
.RE
.B \f[C]-R --real\f[R]
include only non-virtual postings
.TP
.B \f[C]\-NUM\ \-\-depth=NUM\f[]
.B \f[C]-NUM --depth=NUM\f[R]
hide/aggregate accounts or postings more than NUM levels deep
.RS
.RE
.TP
.B \f[C]\-E\ \-\-empty\f[]
show items with zero amount, normally hidden (and vice\-versa in
hledger\-ui/hledger\-web)
.RS
.RE
.B \f[C]-E --empty\f[R]
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
.TP
.B \f[C]\-B\ \-\-cost\f[]
.B \f[C]-B --cost\f[R]
convert amounts to their cost at transaction time (using the transaction
price, if any)
.RS
.RE
.TP
.B \f[C]\-V\ \-\-value\f[]
.B \f[C]-V --value\f[R]
convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.RS
.RE
.TP
.B \f[C]\-\-auto\f[]
.B \f[C]--auto\f[R]
apply automated posting rules to modify transactions.
.RS
.RE
.TP
.B \f[C]\-\-forecast\f[]
.B \f[C]--forecast\f[R]
apply periodic transaction rules to generate future transactions, to 6
months from now or report end date.
.RS
.RE
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -230,38 +164,33 @@ Some reporting options can also be written as query arguments.
.PP
hledger help options:
.TP
.B \f[C]\-h\ \-\-help\f[]
.B \f[C]-h --help\f[R]
show general usage (or after COMMAND, command usage)
.RS
.RE
.TP
.B \f[C]\-\-version\f[]
.B \f[C]--version\f[R]
show version
.RS
.RE
.TP
.B \f[C]\-\-debug[=N]\f[]
show debug output (levels 1\-9, default: 1)
.RS
.RE
.B \f[C]--debug[=N]\f[R]
show debug output (levels 1-9, default: 1)
.PP
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.)
A \[at]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[R] argument before.)
.SH KEYS
.PP
\f[C]?\f[] shows a help dialog listing all keys.
\f[C]?\f[R] shows a help dialog listing all keys.
(Some of these also appear in the quick help at the bottom of each
screen.) Press \f[C]?\f[] again (or \f[C]ESCAPE\f[], or \f[C]LEFT\f[])
to close it.
screen.) Press \f[C]?\f[R] again (or \f[C]ESCAPE\f[R], or
\f[C]LEFT\f[R]) to close it.
The following keys work on most screens:
.PP
The cursor keys navigate: \f[C]right\f[] (or \f[C]enter\f[]) goes
deeper, \f[C]left\f[] returns to the previous screen,
\f[C]up\f[]/\f[C]down\f[]/\f[C]page\ up\f[]/\f[C]page\ down\f[]/\f[C]home\f[]/\f[C]end\f[]
The cursor keys navigate: \f[C]right\f[R] (or \f[C]enter\f[R]) goes
deeper, \f[C]left\f[R] returns to the previous screen,
\f[C]up\f[R]/\f[C]down\f[R]/\f[C]page up\f[R]/\f[C]page down\f[R]/\f[C]home\f[R]/\f[C]end\f[R]
move up and down through lists.
Vi\-style (\f[C]h\f[]/\f[C]j\f[]/\f[C]k\f[]/\f[C]l\f[]) and Emacs\-style
(\f[C]CTRL\-p\f[]/\f[C]CTRL\-n\f[]/\f[C]CTRL\-f\f[]/\f[C]CTRL\-b\f[])
Vi-style (\f[C]h\f[R]/\f[C]j\f[R]/\f[C]k\f[R]/\f[C]l\f[R]) and
Emacs-style
(\f[C]CTRL-p\f[R]/\f[C]CTRL-n\f[R]/\f[C]CTRL-f\f[R]/\f[C]CTRL-b\f[R])
movement keys are also supported.
A tip: movement speed is limited by your keyboard repeat rate, to move
faster you may want to adjust it.
@ -269,67 +198,67 @@ faster you may want to adjust it.
.PP
With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown).
\f[C]shift\-down/up\f[] steps downward and upward through these standard
\f[C]shift-down/up\f[R] steps downward and upward through these standard
report period durations: year, quarter, month, week, day.
Then, \f[C]shift\-left/right\f[] moves to the previous/next period.
\f[C]t\f[] sets the report period to today.
With the \f[C]\-\-watch\f[] option, when viewing a "current" period (the
current day, week, month, quarter, or year), the period will move
automatically to track the current date.
To set a non\-standard period, you can use \f[C]/\f[] and a
\f[C]date:\f[] query.
Then, \f[C]shift-left/right\f[R] moves to the previous/next period.
\f[C]t\f[R] sets the report period to today.
With the \f[C]--watch\f[R] option, when viewing a \[dq]current\[dq]
period (the current day, week, month, quarter, or year), the period will
move automatically to track the current date.
To set a non-standard period, you can use \f[C]/\f[R] and a
\f[C]date:\f[R] query.
.PP
\f[C]/\f[] lets you set a general filter query limiting the data shown,
using the same query terms as in hledger and hledger\-web.
While editing the query, you can use CTRL\-a/e/d/k, BS, cursor keys;
press \f[C]ENTER\f[] to set it, or \f[C]ESCAPE\f[]to cancel.
\f[C]/\f[R] lets you set a general filter query limiting the data shown,
using the same query terms as in hledger and hledger-web.
While editing the query, you can use CTRL-a/e/d/k, BS, cursor keys;
press \f[C]ENTER\f[R] to set it, or \f[C]ESCAPE\f[R]to cancel.
There are also keys for quickly adjusting some common filters like
account depth and transaction status (see below).
\f[C]BACKSPACE\f[] or \f[C]DELETE\f[] removes all filters, showing all
\f[C]BACKSPACE\f[R] or \f[C]DELETE\f[R] removes all filters, showing all
transactions.
.PP
As mentioned above, hledger\-ui shows auto\-generated periodic
transactions, and hides future transactions (auto\-generated or not) by
As mentioned above, hledger-ui shows auto-generated periodic
transactions, and hides future transactions (auto-generated or not) by
default.
\f[C]F\f[] toggles showing and hiding these future transactions.
This is similar to using a query like \f[C]date:\-tomorrow\f[], but more
\f[C]F\f[R] toggles showing and hiding these future transactions.
This is similar to using a query like \f[C]date:-tomorrow\f[R], but more
convenient.
(experimental)
.PP
\f[C]ESCAPE\f[] removes all filters and jumps back to the top screen.
\f[C]ESCAPE\f[R] removes all filters and jumps back to the top screen.
Or, it cancels a minibuffer edit or help dialog in progress.
.PP
\f[C]CTRL\-l\f[] redraws the screen and centers the selection if
\f[C]CTRL-l\f[R] redraws the screen and centers the selection if
possible (selections near the top won\[aq]t be centered, since we
don\[aq]t scroll above the top).
.PP
\f[C]g\f[] reloads from the data file(s) and updates the current screen
\f[C]g\f[R] reloads from the data file(s) and updates the current screen
and any previous screens.
(With large files, this could cause a noticeable pause.)
.PP
\f[C]I\f[] toggles balance assertion checking.
\f[C]I\f[R] toggles balance assertion checking.
Disabling balance assertions temporarily can be useful for
troubleshooting.
.PP
\f[C]a\f[] runs command\-line hledger\[aq]s add command, and reloads the
\f[C]a\f[R] runs command-line hledger\[aq]s add command, and reloads the
updated file.
This allows some basic data entry.
.PP
\f[C]A\f[] is like \f[C]a\f[], but runs the hledger\-iadd tool, which
provides a curses\-style interface.
This key will be available if \f[C]hledger\-iadd\f[] is installed in
\f[C]A\f[R] is like \f[C]a\f[R], but runs the hledger-iadd tool, which
provides a curses-style interface.
This key will be available if \f[C]hledger-iadd\f[R] is installed in
$PATH.
.PP
\f[C]E\f[] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default
(\f[C]emacsclient\ \-a\ ""\ \-nw\f[]) on the journal file.
\f[C]E\f[R] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default
(\f[C]emacsclient -a \[dq]\[dq] -nw\f[R]) on the journal file.
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
error screen.
.PP
\f[C]q\f[] quits the application.
\f[C]q\f[R] quits the application.
.PP
Additional screen\-specific keys are described below.
Additional screen-specific keys are described below.
.SH SCREENS
.SS Accounts screen
.PP
@ -342,21 +271,21 @@ if you specify a query on the command line, it shows just the matched
accounts and the balances from matched transactions.
.PP
Account names are shown as a flat list by default.
Press \f[C]T\f[] to toggle tree mode.
Press \f[C]T\f[R] 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 tree mode, all account balances are inclusive of subaccounts.
.PP
To see less detail, press a number key, \f[C]1\f[] to \f[C]9\f[], to set
a depth limit.
Or use \f[C]\-\f[] to decrease and \f[C]+\f[]/\f[C]=\f[] to increase the
depth limit.
\f[C]0\f[] shows even less detail, collapsing all accounts to a single
To see less detail, press a number key, \f[C]1\f[R] to \f[C]9\f[R], to
set a depth limit.
Or use \f[C]-\f[R] to decrease and \f[C]+\f[R]/\f[C]=\f[R] to increase
the depth limit.
\f[C]0\f[R] shows even less detail, collapsing all accounts to a single
total.
To remove the depth limit, set it higher than the maximum account depth,
or press \f[C]ESCAPE\f[].
or press \f[C]ESCAPE\f[R].
.PP
\f[C]H\f[] toggles between showing historical balances or period
\f[C]H\f[R] toggles between showing historical balances or period
balances.
Historical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date
@ -368,21 +297,21 @@ 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.
.PP
\f[C]U\f[] toggles filtering by unmarked status, including or excluding
\f[C]U\f[R] toggles filtering by unmarked status, including or excluding
unmarked postings in the balances.
Similarly, \f[C]P\f[] toggles pending postings, and \f[C]C\f[] toggles
Similarly, \f[C]P\f[R] toggles pending postings, and \f[C]C\f[R] toggles
cleared postings.
(By default, balances include all postings; if you activate one or two
status filters, only those postings are included; and if you activate
all three, the filter is removed.)
.PP
\f[C]R\f[] toggles real mode, in which virtual postings are ignored.
\f[C]R\f[R] toggles real mode, in which virtual postings are ignored.
.PP
\f[C]Z\f[] toggles nonzero mode, in which only accounts with nonzero
balances are shown (hledger\-ui shows zero items by default, unlike
command\-line hledger).
\f[C]Z\f[R] toggles nonzero mode, in which only accounts with nonzero
balances are shown (hledger-ui shows zero items by default, unlike
command-line hledger).
.PP
Press \f[C]right\f[] or \f[C]enter\f[] to view an account\[aq]s
Press \f[C]right\f[R] or \f[C]enter\f[R] to view an account\[aq]s
transactions register.
.SS Register screen
.PP
@ -399,7 +328,7 @@ inflow to this account, negative for an outflow.
.IP \[bu] 2
the running historical total or period total for the current account,
after the transaction.
This can be toggled with \f[C]H\f[].
This can be toggled with \f[C]H\f[R].
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.
@ -416,23 +345,23 @@ to the balance shown on the accounts screen.
.PD 0
.P
.PD
Tree mode/flat mode can be toggled with \f[C]T\f[] here also.
Tree mode/flat mode can be toggled with \f[C]T\f[R] here also.
.PP
\f[C]U\f[] toggles filtering by unmarked status, showing or hiding
\f[C]U\f[R] toggles filtering by unmarked status, showing or hiding
unmarked transactions.
Similarly, \f[C]P\f[] toggles pending transactions, and \f[C]C\f[]
Similarly, \f[C]P\f[R] toggles pending transactions, and \f[C]C\f[R]
toggles cleared transactions.
(By default, transactions with all statuses 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.)
.PP
\f[C]R\f[] toggles real mode, in which virtual postings are ignored.
\f[C]R\f[R] toggles real mode, in which virtual postings are ignored.
.PP
\f[C]Z\f[] toggles nonzero mode, in which only transactions posting a
nonzero change are shown (hledger\-ui shows zero items by default,
unlike command\-line hledger).
\f[C]Z\f[R] toggles nonzero mode, in which only transactions posting a
nonzero change are shown (hledger-ui shows zero items by default, unlike
command-line hledger).
.PP
Press \f[C]right\f[] (or \f[C]enter\f[]) to view the selected
Press \f[C]right\f[R] (or \f[C]enter\f[R]) to view the selected
transaction in detail.
.SS Transaction screen
.PP
@ -445,8 +374,8 @@ description, comments, along with all of its account postings are shown.
Simple transactions have two postings, but there can be more (or in
certain cases, fewer).
.PP
\f[C]up\f[] and \f[C]down\f[] will step through all transactions listed
in the previous account register screen.
\f[C]up\f[R] and \f[C]down\f[R] will step through all transactions
listed in the previous account register screen.
In the title bar, the numbers in parentheses show your position within
that account register.
They will vary depending on which account register you came from
@ -463,39 +392,39 @@ normal operation.
(Or, you can press escape to cancel the reload attempt.)
.SH ENVIRONMENT
.PP
\f[B]COLUMNS\f[] The screen width to use.
\f[B]COLUMNS\f[R] The screen width to use.
Default: the full terminal width.
.PP
\f[B]LEDGER_FILE\f[] The journal file path when not specified with
\f[C]\-f\f[].
Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[]).
\f[B]LEDGER_FILE\f[R] The journal file path when not specified with
\f[C]-f\f[R].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH FILES
.PP
Reads data from one or more files in hledger journal, 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[]).
timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH BUGS
.PP
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
The need to precede options with \f[C]--\f[R] when invoked from hledger
is awkward.
.PP
\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-ui can\[aq]t read from stdin).
\f[C]-f-\f[R] doesn\[aq]t work (hledger-ui can\[aq]t read from stdin).
.PP
\f[C]\-V\f[] affects only the accounts screen.
\f[C]-V\f[R] affects only the accounts screen.
.PP
When you press \f[C]g\f[], the current and all previous screens are
When you press \f[C]g\f[R], the current and all previous screens are
regenerated, which may cause a noticeable pause with large files.
Also there is no visual indication that this is in progress.
.PP
\f[C]\-\-watch\f[] is not yet fully robust.
\f[C]--watch\f[R] is not yet fully robust.
It works well for normal usage, but many file changes in a short time
(eg saving the file thousands of times with an editor macro) can cause
problems at least on OSX.
Symptoms include: unresponsive UI, periodic resetting of the cursor
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.

33
hledger-ui/hledger-ui.info
View File

@ -3,8 +3,8 @@ This is hledger-ui.info, produced by makeinfo version 6.5 from stdin.

File: hledger-ui.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-ui(1) hledger-ui 1.14
*****************************
hledger-ui(1) hledger-ui 1.14.99
********************************
hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some
@ -24,6 +24,7 @@ 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.
* Menu:
* OPTIONS::
@ -398,19 +399,19 @@ to cancel the reload attempt.)

Tag Table:
Node: Top71
Node: OPTIONS1100
Ref: #options1197
Node: KEYS4616
Ref: #keys4711
Node: SCREENS7967
Ref: #screens8052
Node: Accounts screen8142
Ref: #accounts-screen8270
Node: Register screen10486
Ref: #register-screen10641
Node: Transaction screen12637
Ref: #transaction-screen12795
Node: Error screen13665
Ref: #error-screen13787
Node: OPTIONS1107
Ref: #options1204
Node: KEYS4623
Ref: #keys4718
Node: SCREENS7974
Ref: #screens8059
Node: Accounts screen8149
Ref: #accounts-screen8277
Node: Register screen10493
Ref: #register-screen10648
Node: Transaction screen12644
Ref: #transaction-screen12802
Node: Error screen13672
Ref: #error-screen13794

End Tag Table

48
hledger-ui/hledger-ui.txt
View File

@ -18,9 +18,9 @@ DESCRIPTION
hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some
limited data entry capability. It is easier than hledger's com-
mand-line interface, and sometimes quicker and more convenient than the
web interface.
limited data entry capability. It is easier than hledger's command-
line interface, and sometimes quicker and more convenient than the web
interface.
Note hledger-ui has some different defaults (experimental):
@ -180,21 +180,21 @@ KEYS
The cursor keys navigate: right (or enter) goes deeper, left returns to
the previous screen, 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. A tip:
movement speed is limited by your keyboard repeat rate, to move faster
you may want to adjust it. (If you're on a mac, the Karabiner app is
one way to do that.)
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. A tip: movement
speed is limited by your keyboard repeat rate, to move faster you may
want to adjust it. (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, limiting
the transactions to be shown (by default, all are shown).
shift-down/up steps downward and upward through these standard report
period durations: year, quarter, month, week, day. Then,
shift-left/right moves to the previous/next period. t sets the report
period to today. With the --watch option, when viewing a "current"
period (the current day, week, month, quarter, or year), the period
will move automatically to track the current date. To set a non-stan-
dard period, you can use / and a date: query.
the transactions to be shown (by default, all are shown). shift-
down/up steps downward and upward through these standard report period
durations: year, quarter, month, week, day. Then, shift-left/right
moves to the previous/next period. t sets the report period to today.
With the --watch option, when viewing a "current" period (the current
day, week, month, quarter, or year), the period will move automatically
to track the current date. To set a non-standard period, you can use /
and a date: query.
/ lets you set a general filter query limiting the data shown, using
the same query terms as in hledger and hledger-web. While editing the
@ -226,15 +226,15 @@ KEYS
a runs command-line hledger's add command, and reloads the updated
file. This allows some basic data entry.
A is like a, but runs the hledger-iadd tool, which provides a
curses-style interface. This key will be available if hledger-iadd is
A is like a, but runs the hledger-iadd tool, which provides a curses-
style interface. This key will be available if hledger-iadd is
installed in $PATH.
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac-
sclient -a "" -nw) on the journal file. 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 error screen.
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 when invoked from the
register and transaction screens, and at the error location (if possi-
ble) when invoked from the error screen.
q quits the application.
@ -406,4 +406,4 @@ SEE ALSO
hledger-ui 1.14 March 2019 hledger-ui(1)
hledger-ui 1.14.99 March 2019 hledger-ui(1)

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

@ -1,34 +1,34 @@
.TH "hledger\-web" "1" "March 2019" "hledger\-web 1.14" "hledger User Manuals"
.TH "hledger-web" "1" "March 2019" "hledger-web 1.14.99" "hledger User Manuals"
.SH NAME
.PP
hledger\-web \- web interface for the hledger accounting tool
hledger-web - web interface for the hledger accounting tool
.SH SYNOPSIS
.PP
\f[C]hledger\-web\ [OPTIONS]\f[]
\f[C]hledger-web [OPTIONS]\f[R]
.PD 0
.P
.PD
\f[C]hledger\ web\ \-\-\ [OPTIONS]\f[]
\f[C]hledger web -- [OPTIONS]\f[R]
.SH DESCRIPTION
.PP
hledger is a cross\-platform program for tracking money, time, or any
other commodity, using double\-entry accounting and a simple, editable
hledger is a cross-platform program for tracking money, time, or any
other commodity, using double-entry accounting and a simple, editable
file format.
hledger is inspired by and largely compatible with ledger(1).
.PP
hledger\-web is hledger\[aq]s web interface.
hledger-web is hledger\[aq]s web interface.
It starts a simple web application for browsing and adding transactions,
and optionally opens it in a web browser window if possible.
It provides a more user\-friendly UI than the hledger CLI or hledger\-ui
It provides a more user-friendly UI than the hledger CLI or hledger-ui
interface, showing more at once (accounts, the current account register,
balance charts) and allowing history\-aware data entry, interactive
balance charts) and allowing history-aware data entry, interactive
searching, and bookmarking.
.PP
hledger\-web also lets you share a ledger with multiple users, or even
hledger-web also lets you share a ledger with multiple users, or even
the public web.
There is no access control, so if you need that you should put it behind
a suitable web proxy.
@ -37,201 +37,135 @@ instance, it writes a numbered backup of the main journal file (only ?)
on every edit.
.PP
Like hledger, it reads data from one or more files in hledger journal,
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[]).
timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1), hledger_journal(5) etc.
.SH OPTIONS
.PP
Command\-line options and arguments may be used to set an initial filter
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.
.PP
Note: if invoking hledger\-web as a hledger subcommand, write
\f[C]\-\-\f[] before options, as shown in the synopsis above.
Note: if invoking hledger-web as a hledger subcommand, write
\f[C]--\f[R] 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
.RS
.RE
.B \f[C]--serve\f[R]
serve and log requests, don\[aq]t browse or auto-exit
.TP
.B \f[C]\-\-host=IPADDR\f[]
.B \f[C]--host=IPADDR\f[R]
listen on this IP address (default: 127.0.0.1)
.RS
.RE
.TP
.B \f[C]\-\-port=PORT\f[]
.B \f[C]--port=PORT\f[R]
listen on this TCP port (default: 5000)
.RS
.RE
.TP
.B \f[C]\-\-base\-url=URL\f[]
.B \f[C]--base-url=URL\f[R]
set the base url (default: http://IPADDR:PORT).
You would change this when sharing over the network, or integrating
within a larger website.
.RS
.RE
.TP
.B \f[C]\-\-file\-url=URL\f[]
.B \f[C]--file-url=URL\f[R]
set the static files url (default: BASEURL/static).
hledger\-web normally serves static files itself, but if you wanted to
hledger-web normally serves static files itself, but if you wanted to
serve them from another server for efficiency, you would set the url
with this.
.RS
.RE
.TP
.B \f[C]\-\-capabilities=CAP[,CAP..]\f[]
.B \f[C]--capabilities=CAP[,CAP..]\f[R]
enable the view, add, and/or manage capabilities (default: view,add)
.RS
.RE
.TP
.B \f[C]\-\-capabilities\-header=HTTPHEADER\f[]
.B \f[C]--capabilities-header=HTTPHEADER\f[R]
read capabilities to enable from a HTTP header, like
X\-Sandstorm\-Permissions (default: disabled)
.RS
.RE
X-Sandstorm-Permissions (default: disabled)
.PP
hledger input options:
.TP
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[]
.B \f[C]-f FILE --file=FILE\f[R]
use a different input file.
For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or
\f[C]$HOME/.hledger.journal\f[])
.RS
.RE
For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
\f[C]$HOME/.hledger.journal\f[R])
.TP
.B \f[C]\-\-rules\-file=RULESFILE\f[]
.B \f[C]--rules-file=RULESFILE\f[R]
Conversion rules file to use when reading CSV (default: FILE.rules)
.RS
.RE
.TP
.B \f[C]\-\-separator=CHAR\f[]
.B \f[C]--separator=CHAR\f[R]
Field separator to expect when reading CSV (default: \[aq],\[aq])
.RS
.RE
.TP
.B \f[C]\-\-alias=OLD=NEW\f[]
.B \f[C]--alias=OLD=NEW\f[R]
rename accounts named OLD to NEW
.RS
.RE
.TP
.B \f[C]\-\-anon\f[]
.B \f[C]--anon\f[R]
anonymize accounts and payees
.RS
.RE
.TP
.B \f[C]\-\-pivot\ FIELDNAME\f[]
.B \f[C]--pivot FIELDNAME\f[R]
use some other field or tag for the account name
.RS
.RE
.TP
.B \f[C]\-I\ \-\-ignore\-assertions\f[]
.B \f[C]-I --ignore-assertions\f[R]
ignore any failing balance assertions
.RS
.RE
.PP
hledger reporting options:
.TP
.B \f[C]\-b\ \-\-begin=DATE\f[]
.B \f[C]-b --begin=DATE\f[R]
include postings/txns on or after this date
.RS
.RE
.TP
.B \f[C]\-e\ \-\-end=DATE\f[]
.B \f[C]-e --end=DATE\f[R]
include postings/txns before this date
.RS
.RE
.TP
.B \f[C]\-D\ \-\-daily\f[]
.B \f[C]-D --daily\f[R]
multiperiod/multicolumn report by day
.RS
.RE
.TP
.B \f[C]\-W\ \-\-weekly\f[]
.B \f[C]-W --weekly\f[R]
multiperiod/multicolumn report by week
.RS
.RE
.TP
.B \f[C]\-M\ \-\-monthly\f[]
.B \f[C]-M --monthly\f[R]
multiperiod/multicolumn report by month
.RS
.RE
.TP
.B \f[C]\-Q\ \-\-quarterly\f[]
.B \f[C]-Q --quarterly\f[R]
multiperiod/multicolumn report by quarter
.RS
.RE
.TP
.B \f[C]\-Y\ \-\-yearly\f[]
.B \f[C]-Y --yearly\f[R]
multiperiod/multicolumn report by year
.RS
.RE
.TP
.B \f[C]\-p\ \-\-period=PERIODEXP\f[]
.B \f[C]-p --period=PERIODEXP\f[R]
set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above)
.RS
.RE
.TP
.B \f[C]\-\-date2\f[]
.B \f[C]--date2\f[R]
match the secondary date instead (see command help for other effects)
.RS
.RE
.TP
.B \f[C]\-U\ \-\-unmarked\f[]
include only unmarked postings/txns (can combine with \-P or \-C)
.RS
.RE
.B \f[C]-U --unmarked\f[R]
include only unmarked postings/txns (can combine with -P or -C)
.TP
.B \f[C]\-P\ \-\-pending\f[]
.B \f[C]-P --pending\f[R]
include only pending postings/txns
.RS
.RE
.TP
.B \f[C]\-C\ \-\-cleared\f[]
.B \f[C]-C --cleared\f[R]
include only cleared postings/txns
.RS
.RE
.TP
.B \f[C]\-R\ \-\-real\f[]
include only non\-virtual postings
.RS
.RE
.B \f[C]-R --real\f[R]
include only non-virtual postings
.TP
.B \f[C]\-NUM\ \-\-depth=NUM\f[]
.B \f[C]-NUM --depth=NUM\f[R]
hide/aggregate accounts or postings more than NUM levels deep
.RS
.RE
.TP
.B \f[C]\-E\ \-\-empty\f[]
show items with zero amount, normally hidden (and vice\-versa in
hledger\-ui/hledger\-web)
.RS
.RE
.B \f[C]-E --empty\f[R]
show items with zero amount, normally hidden (and vice-versa in
hledger-ui/hledger-web)
.TP
.B \f[C]\-B\ \-\-cost\f[]
.B \f[C]-B --cost\f[R]
convert amounts to their cost at transaction time (using the transaction
price, if any)
.RS
.RE
.TP
.B \f[C]\-V\ \-\-value\f[]
.B \f[C]-V --value\f[R]
convert amounts to their market value on the report end date (using the
most recent applicable market price, if any)
.RS
.RE
.TP
.B \f[C]\-\-auto\f[]
.B \f[C]--auto\f[R]
apply automated posting rules to modify transactions.
.RS
.RE
.TP
.B \f[C]\-\-forecast\f[]
.B \f[C]--forecast\f[R]
apply periodic transaction rules to generate future transactions, to 6
months from now or report end date.
.RS
.RE
.PP
When a reporting option appears more than once in the command line, the
last one takes precedence.
@ -240,59 +174,53 @@ Some reporting options can also be written as query arguments.
.PP
hledger help options:
.TP
.B \f[C]\-h\ \-\-help\f[]
.B \f[C]-h --help\f[R]
show general usage (or after COMMAND, command usage)
.RS
.RE
.TP
.B \f[C]\-\-version\f[]
.B \f[C]--version\f[R]
show version
.RS
.RE
.TP
.B \f[C]\-\-debug[=N]\f[]
show debug output (levels 1\-9, default: 1)
.RS
.RE
.B \f[C]--debug[=N]\f[R]
show debug output (levels 1-9, default: 1)
.PP
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.)
A \[at]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[R] 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.
By default, hledger-web starts the web app in \[dq]transient mode\[dq]
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
With \f[C]--serve\f[R], 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.
You can use \f[C]--host\f[R] to change this, eg \f[C]--host 0.0.0.0\f[R]
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.
Similarly, use \f[C]--port\f[R] 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).
You can use \f[C]--base-url\f[R] 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[R] using the server\[aq]s
configured host address and TCP port (or \f[C]http://HOST\f[R] 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
With \f[C]--file-url\f[R] 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
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).
setting the IP address it listens on (see \f[C]--host\f[R] above).
By default it listens on 127.0.0.1, accessible to all users on the local
machine.
.IP \[bu] 2
@ -302,56 +230,59 @@ 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,
using the \f[C]--capabilities=CAP[,CAP..]\f[R] flag when you start it,
enabling one or more of the following capabilities.
The default value is \f[C]view,add\f[]:
The default value is \f[C]view,add\f[R]:
.RS 2
.IP \[bu] 2
\f[C]view\f[] \- allows viewing the journal file and all included files
\f[C]view\f[R] - 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
\f[C]add\f[R] - allows adding new transactions to the main journal file
.IP \[bu] 2
\f[C]manage\f[] \- allows editing, uploading or downloading the main or
\f[C]manage\f[R] - 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
using the \f[C]--capabilities-header=HTTPHEADER\f[R] 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
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.
If you enable the \f[C]manage\f[R] capability mentioned above,
you\[aq]ll see a new \[dq]spanner\[dq] 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
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,
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
Changes which would leave the journal file(s) unparseable or non-valid
(eg with failing balance assertions) are prevented.
(Probably.
This needs re\-testing.)
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
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.
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests.
Currently these are same ones provided by the hledger-api tool, but
hledger-web will likely receive more attention than hledger-api in
future:
.IP
.nf
\f[C]
@ -361,31 +292,65 @@ may be convenient to have them in hledger\-web also.
/commodities
/accounts
/accounttransactions/#AccountName
\f[]
\f[R]
.fi
.PP
Also, you can append a new transaction to the journal by sending a PUT
request to \f[C]/add\f[R] (hledger-web only).
As with the web UI\[aq]s add form, hledger-web must be started with the
\f[C]add\f[R] capability for this (enabled by default).
.PP
The payload should be a valid hledger transaction as JSON, similar to
what you get from \f[C]/transactions\f[R] or
\f[C]/accounttransactions\f[R].
.PP
Another way to generate test data is with the
\f[C]readJsonFile\f[R]/\f[C]writeJsonFile\f[R] helpers in
Hledger.Web.Json, which read or write any of hledger\[aq]s JSON-capable
types from or to a file.
Eg here we write the first transaction of a sample journal:
.IP
.nf
\f[C]
$ make ghci-web
>>> :m +*Hledger.Web.Json
>>> writeJsonFile \[dq]txn.json\[dq] (head $ jtxns samplejournal)
>>> :q
$ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readable
\f[R]
.fi
.PP
(sample output & discussion)
.PP
And here\[aq]s how to test adding that with curl:
.IP
.nf
\f[C]
$ curl -s http://127.0.0.1:5000/add -X PUT -H \[aq]Content-Type: application/json\[aq] --data-binary \[at]txn.pretty.json; echo
\f[R]
.fi
.SH ENVIRONMENT
.PP
\f[B]LEDGER_FILE\f[] The journal file path when not specified with
\f[C]\-f\f[].
Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[]).
\f[B]LEDGER_FILE\f[R] The journal file path when not specified with
\f[C]-f\f[R].
Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH FILES
.PP
Reads data from one or more files in hledger journal, 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[]).
timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[R], or \f[C]$HOME/.hledger.journal\f[R] (on windows,
perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH BUGS
.PP
The need to precede options with \f[C]\-\-\f[] when invoked from hledger
The need to precede options with \f[C]--\f[R] when invoked from hledger
is awkward.
.PP
\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-web can\[aq]t read from
stdin).
\f[C]-f-\f[R] doesn\[aq]t work (hledger-web can\[aq]t read from stdin).
.PP
Query arguments and some hledger options are ignored.
.PP
Does not work in text\-mode browsers.
Does not work in text-mode browsers.
.PP
Does not work well on small screens.

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

@ -3,8 +3,8 @@ This is hledger-web.info, produced by makeinfo version 6.5 from stdin.

File: hledger-web.info, Node: Top, Next: OPTIONS, Up: (dir)
hledger-web(1) hledger-web 1.14
*******************************
hledger-web(1) hledger-web 1.14.99
**********************************
hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions, and optionally opens
@ -25,6 +25,7 @@ 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.
* Menu:
* OPTIONS::
@ -287,9 +288,10 @@ 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.
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. Currently these are same ones
provided by the hledger-api tool, but hledger-web will likely receive
more attention than hledger-api in future:
/accountnames
/transactions
@ -298,18 +300,43 @@ may be convenient to have them in hledger-web also.
/accounts
/accounttransactions/#AccountName
Also, you can append a new transaction to the journal by sending a
PUT request to '/add' (hledger-web only). As with the web UI's add
form, hledger-web must be started with the 'add' capability for this
(enabled by default).
The payload should be a valid hledger transaction as JSON, similar to
what you get from '/transactions' or '/accounttransactions'.
Another way to generate test data is with the
'readJsonFile'/'writeJsonFile' helpers in Hledger.Web.Json, which read
or write any of hledger's JSON-capable types from or to a file. Eg here
we write the first transaction of a sample journal:
$ make ghci-web
>>> :m +*Hledger.Web.Json
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
>>> :q
$ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readable
(sample output & discussion)
And here's how to test adding that with curl:
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo

Tag Table:
Node: Top72
Node: OPTIONS1354
Ref: #options1459
Node: PERMISSIONS6549
Ref: #permissions6688
Node: EDITING UPLOADING DOWNLOADING7900
Ref: #editing-uploading-downloading8081
Node: RELOADING8915
Ref: #reloading9049
Node: JSON API9359
Ref: #json-api9453
Node: OPTIONS1361
Ref: #options1466
Node: PERMISSIONS6556
Ref: #permissions6695
Node: EDITING UPLOADING DOWNLOADING7907
Ref: #editing-uploading-downloading8088
Node: RELOADING8922
Ref: #reloading9056
Node: JSON API9366
Ref: #json-api9460

End Tag Table

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

@ -187,8 +187,8 @@ OPTIONS
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.
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.
@ -260,9 +260,10 @@ RELOADING
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.
In addition to the web UI, hledger-web provides some API routes that
serve JSON in response to GET requests. Currently these are same ones
provided by the hledger-api tool, but hledger-web will likely receive
more attention than hledger-api in future:
/accountnames
/transactions
@ -271,6 +272,31 @@ JSON API
/accounts
/accounttransactions/#AccountName
Also, you can append a new transaction to the journal by sending a PUT
request to /add (hledger-web only). As with the web UI's add form,
hledger-web must be started with the add capability for this (enabled
by default).
The payload should be a valid hledger transaction as JSON, similar to
what you get from /transactions or /accounttransactions.
Another way to generate test data is with the readJsonFile/writeJson-
File helpers in Hledger.Web.Json, which read or write any of hledger's
JSON-capable types from or to a file. Eg here we write the first
transaction of a sample journal:
$ make ghci-web
>>> :m +*Hledger.Web.Json
>>> writeJsonFile "txn.json" (head $ jtxns samplejournal)
>>> :q
$ python -m json.tool <txn.json >txn.pretty.json # optional: make human-readable
(sample output & discussion)
And here's how to test adding that with curl:
$ curl -s http://127.0.0.1:5000/add -X PUT -H 'Content-Type: application/json' --data-binary @txn.pretty.json; echo
ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
@ -319,4 +345,4 @@ SEE ALSO
hledger-web 1.14 March 2019 hledger-web(1)
hledger-web 1.14.99 March 2019 hledger-web(1)

2850
hledger/hledger.1
View File

File diff suppressed because it is too large Load Diff

642
hledger/hledger.info
View File

@ -3,8 +3,8 @@ This is hledger.info, produced by makeinfo version 6.5 from stdin.

File: hledger.info, Node: Top, Next: EXAMPLES, Up: (dir)
hledger(1) hledger 1.14.1
*************************
hledger(1) hledger 1.14.99
**************************
This is hledger's command-line interface (there are also curses and web
interfaces). Its basic function is to read a plain text file describing
@ -40,6 +40,7 @@ hledger never changes existing transactions.
'~/.hledger.journal', or run 'hledger add' and follow the prompts. Then
try some commands like 'hledger print' or 'hledger balance'. Run
'hledger' with no arguments for a list of commands.
* Menu:
* EXAMPLES::
@ -131,7 +132,7 @@ File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* Pivoting::
* Cost::
* Market value::
* Combining -B and -V::
* Combining -B -V --value::
* Output destination::
* Output format::
* Regular expressions::
@ -303,6 +304,7 @@ characters. Eg:
'hledger register -p 'last year' "accounts receivable
(receivable|payable)" amt:\>100'.
* Menu:
* More escaping::
@ -393,24 +395,38 @@ File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Comman
2.7 Unicode characters
======================
hledger is expected to handle unicode (non-ascii) characters, but this
requires a well-configured environment.
hledger is expected to handle non-ascii characters correctly:
To handle unicode characters in the command line or input data, a
system locale that can decode them must be configured (POSIX's default
'C' locale will not work). Eg in bash, you could do:
* they should be parsed correctly in input files and on the command
line, by all hledger tools (add, iadd, hledger-web's
search/add/edit forms, etc.)
export LANG=en_US.UTF-8
* they should be displayed correctly by all hledger tools, and
on-screen alignment should be preserved.
See Troubleshooting for more about this.
This requires a well-configured environment. Here are some tips:
Unicode characters should appear correctly in hledger's output. For
the hledger and hledger-ui tools, this requires that
* A system locale must be configured, and it must be one that can
decode the characters being used. In bash, you can set a locale
like this: 'export LANG=en_US.UTF-8'. There are some more details
in Troubleshooting. This step is essential - without it, hledger
will quit on encountering a non-ascii character (as with all
GHC-compiled programs).
* your terminal supports unicode
* the terminal's font includes the required unicode glyphs
* the terminal is configured to display "wide" characters as double
width (otherwise report alignment will be off)
* your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
must support unicode
* the terminal must be using a font which includes the required
unicode glyphs
* the terminal should be configured to display wide characters as
double width (for report alignment)
* on Windows, for best results you should run hledger in the same
kind of environment in which it was built. Eg hledger built in the
standard CMD.EXE environment (like the binaries on our download
page) might show display problems when run in a cygwin or msys
terminal, and vice versa. (See eg #961).

File: hledger.info, Node: Input files, Next: Smart dates, Prev: Unicode characters, Up: OPTIONS
@ -729,22 +745,15 @@ The '-B/--cost' flag converts amounts to their cost at transaction time,
if they have a transaction price specified.

File: hledger.info, Node: Market value, Next: Combining -B and -V, Prev: Cost, Up: OPTIONS
File: hledger.info, Node: Market value, Next: Combining -B -V --value, Prev: Cost, Up: OPTIONS
2.16 Market value
=================
The '-V/--value' flag converts reported amounts to their current market
value.
Specifically, when there is a market price (P directive) for the
amount's commodity, dated on or before today's date (or the report end
date if specified), the amount will be converted to the price's
commodity.
When there are multiple applicable P directives, -V chooses the most
recent one, or in case of equal dates, the last-parsed one.
For example:
The '-V/--market' flag converts reported amounts to their market value
in another commodity. It uses the commodity referenced in the latest
market price (P directive) dated on or before the valuation date. The
default valuation date is today. For example:
# one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10
@ -773,25 +782,211 @@ specified, defaults to today)
$ hledger -f t.j bal -N euros -V
$103.00 assets:euros
Currently, hledger's -V only uses market prices recorded with P
directives, not transaction prices (unlike Ledger).
Ledger users: Ledger's -V also infers market prices from journal
entries, but we don't do that. hledger's -V uses only market prices
declared explicitly, with P directives. (Mnemonic: -B/-cost uses
transaction prices, -V/-market uses market prices.)
Currently, -V has a limitation in multicolumn balance reports: it
uses the market prices on the report end date for all columns. (Instead
of the prices on each column's end date.)
* Menu:
* More control over valuation::
* Effect of --value on reports::
* Some useful value reports::

File: hledger.info, Node: Combining -B and -V, Next: Output destination, Prev: Market value, Up: OPTIONS
File: hledger.info, Node: More control over valuation, Next: Effect of --value on reports, Up: Market value
2.17 Combining -B and -V
========================
2.16.1 More control over valuation
----------------------------------
Using -B/-cost and -V/-value together is currently allowed, but the
results are probably not meaningful. Let us know if you find a use for
this.
_(experimental, added 201905)_
You can control valuation more precisely with the '--value' option.
--value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD
The argument is one of the keywords shown, or their first letter, or
a custom date. The precise effect of the keywords is command-specific,
but here is their general meaning:
'--value=cost' (or 'c')
Convert amounts to cost, using the prices recorded in transactions.
'-B'/'--cost' does this.
'--value=end' (or 'e')
Convert amounts to their value in default valuation commodity using
market prices on the last day of the report period (or of each
subperiod in a multiperiod report). When no report period is
specified, uses the journal's last transaction date.
'--value=now' (or 'n')
Convert amounts to their value in default valuation commodity using
current market prices (as of when report is generated).
'-V'/'--market' does this.
'--value=YYYY-MM-DD'
Convert amounts to their value in default valuation commodity using
market prices on the given date (which must be 8 digits with '-' or
'/' or '.' separators). Eg '--value=2019-04-25'.
Here are the effects of '--value' as seen with 'print':
P 2000-01-01 A 1 B
P 2000-02-01 A 2 B
P 2000-03-01 A 3 B
P 2000-04-01 A 4 B
2000-01-01
(a) 1 A @ 5 B
2000-02-01
(a) 1 A @ 6 B
2000-03-01
(a) 1 A @ 7 B
Show the cost of each posting:
$ hledger -f- print --value=cost
2000/01/01
(a) 5 B
2000/02/01
(a) 6 B
2000/03/01
(a) 7 B
Show the value as of the last day of the report period (2000-02-29):
$ hledger -f- print --value=end date:2000/01-2000/03
2000-01-01
(a) 2 B
2000-02-01
(a) 2 B
With no report period specified, that shows the value as of the last
day of the journal (2000-03-01):
$ hledger -f- print --value=end
2000/01/01
(a) 3 B
2000/02/01
(a) 3 B
2000/03/01
(a) 3 B
Show the current value (the 2000-04-01 price is still in effect
today):
$ hledger -f- print --value=now
2000-01-01
(a) 4 B
2000-02-01
(a) 4 B
2000-03-01
(a) 4 B
Show the value on 2000/01/15:
$ hledger -f- print --value=2000-01-15
2000/01/01
(a) 1 B
2000/02/01
(a) 1 B
2000/03/01
(a) 1 B

File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B and -V, Up: OPTIONS
File: hledger.info, Node: Effect of --value on reports, Next: Some useful value reports, Prev: More control over valuation, Up: Market value
2.16.2 Effect of -value on reports
----------------------------------
Below is how '--value' affects each of hledger's reports, currently.
You're not expected to remember all this, but when troubleshooting a
report, look here. If you find problems - useless reports, misbehaving
reports, or error messages being printed - please report them (with
reproducible examples) eg at #329.
Report type '--value' '--value' 'end' '--value'
'cost' 'DATE'/'now'
----------------------------------------------------------------------------
*print*
posting cost, as market value at report market value at
amounts recorded in end DATE
transaction
balance show show unvalued show unvalued
assertions/assignmentsunvalued
*register*
starting cost of market value at day market value at
balance starting before report start DATE
with -H balance
posting cost market value at report market value at
amounts end DATE
posting summarised market value each market value each
amounts, cost summary posting at summary posting
multiperiod period end at DATE
running sum/average sum/average of the sum/average of
total/average of the displayed values the displayed
displayed values
values
*balance
(bs, cf,
is..)*
starting costs of market value at day market value at
balances starting before report start of DATE of sum of
with -H balances sum of previous postings previous postings
balances, summed costs market value at period market value at
simple end of sum of postings DATE of sum of
balance postings
report
balances, summed costs market value at period market value at
multiperiod end of sum of postings DATE of sum of
report postings
budget costs of budget-setting periodic budget-setting
amounts budget txns are valued at periodic txns are
with amounts period end valued at DATE
-budget
column/row/grandsum/average market value at period market value at
totals/averagesof the end of sum/average of DATE of
displayed postings sum/average of
values postings

File: hledger.info, Node: Some useful value reports, Prev: Effect of --value on reports, Up: Market value
2.16.3 Some useful value reports
--------------------------------
Here are some probably useful reports - please send suggestions if you
find out more:
Command: Description of report: Could answer:
---------------------------------------------------------------------------
'hledger bs -M Monthly historical value How are my investments
--value=p' of assets/liabilities performing ?
'hledger is -M Monthly contemporaneous How much foreign currency
--value=t' value of revenues/expenses have I been spending ?

File: hledger.info, Node: Combining -B -V --value, Next: Output destination, Prev: Market value, Up: OPTIONS
2.17 Combining -B, -V, -value
=============================
The rightmost of these flags wins.

File: hledger.info, Node: Output destination, Next: Output format, Prev: Combining -B -V --value, Up: OPTIONS
2.18 Output destination
=======================
@ -987,6 +1182,7 @@ unambiguous prefix of a command name ('hledger inc').
Here are all the builtin commands in alphabetical order. See also
'hledger' for a more organised command list, and 'hledger CMD -h' for
detailed command help.
* Menu:
* accounts::
@ -1162,6 +1358,7 @@ show real-world account balances. In some cases the -H/-historical flag
is used to ensure this (more below).
The balance command can produce several styles of report:
* Menu:
* Classic balance report::
@ -1250,7 +1447,9 @@ with data fields interpolated like so:
'%[MIN][.MAX](FIELDNAME)'
* MIN pads with spaces to at least this width (optional)
* MAX truncates at this width (optional)
* FIELDNAME must be enclosed in parentheses, and can be one of:
* 'depth_spacer' - a number of spaces equal to the account's
@ -1390,6 +1589,10 @@ different information:
----------------------++-------------------------------------
|| 0 0 0
Note that '--cumulative' or '--historical/-H' disable
'--row-total/-T', since summing end balances generally does not make
sense.
Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use '--tree'.
@ -1557,6 +1760,7 @@ Budget performance in 2017/11/01-2017/12/31:
|| 0 [ 0] 0 [ 0]
For more examples, see Budgeting and Forecasting.
* Menu:
* Nested budgets::
@ -1696,7 +1900,9 @@ Total:
each report period. As with multicolumn balance reports, you can alter
the report mode with '--change'/'--cumulative'/'--historical'. Normally
balancesheet shows historical ending balances, which is what you need
for a balance sheet; note this means it ignores report begin dates.
for a balance sheet; note this means it ignores report begin dates (and
'-T/--row-total', since summing end balances generally does not make
sense).
This command also supports output destination and output format
selection.
@ -1815,7 +2021,7 @@ end of a period.
The closing transaction transfers balances to "equity:closing
balances". The opening transaction transfers balances from
"equity:opening balances". You can chose to print just one of the
"equity:opening balances". You can choose to print just one of the
transactions by using the '--opening' or '--closing' flag.
If you split your journal files by time (eg yearly), you will
@ -1959,6 +2165,29 @@ see only uncategorised transactions:
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
* Menu:
* Importing balance assignments::

File: hledger.info, Node: Importing balance assignments, Up: import
4.13.1 Importing balance assignments
------------------------------------
Entries added by import will have their posting amounts made explicit
(like 'hledger print -x'). This means that any balance assignments in
imported files must be evaluated; but, imported files don't get to see
the main file's account balances. As a result, importing entries with
balance assignments (eg from an institution that provides only balances
and not posting amounts) will probably generate incorrect posting
amounts. To avoid this problem, use print instead of import:
$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
(If you think import should leave amounts implicit like print does,
please test it and send a pull request.)

File: hledger.info, Node: incomestatement, Next: prices, Prev: import, Up: COMMANDS
@ -2225,6 +2454,7 @@ $ hledger register --monthly assets --depth 1h
these will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full
length and comparable to the others in the report.
* Menu:
* Custom register output::
@ -2292,9 +2522,9 @@ transaction's first posting amount.
Examples:
hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
hledger-rewrite.hs -f rewrites.hledger
$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
$ hledger-rewrite.hs -f rewrites.hledger
rewrites.hledger may consist of entries like:
@ -2557,6 +2787,7 @@ haskell) library functions that built-in commands do, for command-line
options, journal parsing, reporting, etc.
Here are some hledger add-ons available:
* Menu:
* Official add-ons::
@ -2570,6 +2801,7 @@ File: hledger.info, Node: Official add-ons, Next: Third party add-ons, Up: AD
====================
These are maintained and released along with hledger.
* Menu:
* api::
@ -2608,6 +2840,7 @@ File: hledger.info, Node: Third party add-ons, Next: Experimental add-ons, Pr
These are maintained separately, and usually updated shortly after a
hledger release.
* Menu:
* diff::
@ -2661,6 +2894,7 @@ These are available in source form in the hledger repo's bin/ directory;
installing them is pretty easy. They may be less mature and documented
than built-in commands. Reading and tweaking these is a good way to
start making your own!
* Menu:
* autosync::
@ -2697,160 +2931,168 @@ hledger-check.hs checks more powerful account balance assertions.

Tag Table:
Node: Top68
Node: EXAMPLES1888
Ref: #examples1988
Node: OPTIONS3634
Ref: #options3736
Node: General options4171
Ref: #general-options4296
Node: Command options6978
Ref: #command-options7129
Node: Command arguments7527
Ref: #command-arguments7681
Node: Argument files7802
Ref: #argument-files7978
Node: Special characters in arguments and queries8244
Ref: #special-characters-in-arguments-and-queries8478
Node: More escaping8928
Ref: #more-escaping9090
Node: Even more escaping9386
Ref: #even-more-escaping9580
Node: Less escaping10251
Ref: #less-escaping10413
Node: Command line tips10658
Ref: #command-line-tips10844
Node: Unicode characters11221
Ref: #unicode-characters11377
Node: Input files12102
Ref: #input-files12238
Node: Smart dates14208
Ref: #smart-dates14349
Node: Report start & end date15755
Ref: #report-start-end-date15927
Node: Report intervals16993
Ref: #report-intervals17158
Node: Period expressions17559
Ref: #period-expressions17719
Node: Depth limiting21676
Ref: #depth-limiting21820
Node: Pivoting22162
Ref: #pivoting22280
Node: Cost23956
Ref: #cost24064
Node: Market value24182
Ref: #market-value24317
Node: Combining -B and -V25683
Ref: #combining--b-and--v25846
Node: Output destination25993
Ref: #output-destination26155
Node: Output format26438
Ref: #output-format26590
Node: Regular expressions26975
Ref: #regular-expressions27112
Node: QUERIES28473
Ref: #queries28575
Node: COMMANDS32537
Ref: #commands32649
Node: accounts33649
Ref: #accounts33747
Node: activity34446
Ref: #activity34556
Node: add34939
Ref: #add35038
Node: balance37625
Ref: #balance37736
Node: Classic balance report39177
Ref: #classic-balance-report39350
Node: Customising the classic balance report40719
Ref: #customising-the-classic-balance-report40947
Node: Colour support43021
Ref: #colour-support43188
Node: Flat mode43361
Ref: #flat-mode43509
Node: Depth limited balance reports43922
Ref: #depth-limited-balance-reports44122
Node: Multicolumn balance report44578
Ref: #multicolumn-balance-report44776
Node: Budget report49956
Ref: #budget-report50099
Node: Nested budgets55300
Ref: #nested-budgets55412
Ref: #output-format-158892
Node: balancesheet58970
Ref: #balancesheet59106
Node: balancesheetequity60340
Ref: #balancesheetequity60489
Node: cashflow61050
Ref: #cashflow61178
Node: check-dates62206
Ref: #check-dates62333
Node: check-dupes62612
Ref: #check-dupes62736
Node: close63029
Ref: #close63137
Node: files66550
Ref: #files66651
Node: help66798
Ref: #help66898
Node: import67991
Ref: #import68105
Node: incomestatement68849
Ref: #incomestatement68983
Node: prices70319
Ref: #prices70434
Node: print70713
Ref: #print70823
Node: print-unique75316
Ref: #print-unique75442
Node: register75727
Ref: #register75854
Node: Custom register output80025
Ref: #custom-register-output80154
Node: register-match81416
Ref: #register-match81550
Node: rewrite81901
Ref: #rewrite82016
Node: Re-write rules in a file83865
Ref: #re-write-rules-in-a-file83999
Node: Diff output format85209
Ref: #diff-output-format85378
Node: rewrite vs print --auto86470
Ref: #rewrite-vs.-print---auto86649
Node: roi87205
Ref: #roi87303
Node: stats88315
Ref: #stats88414
Node: tags89168
Ref: #tags89266
Node: test89496
Ref: #test89580
Node: ADD-ON COMMANDS90341
Ref: #add-on-commands90451
Node: Official add-ons91738
Ref: #official-add-ons91878
Node: api91965
Ref: #api92054
Node: ui92106
Ref: #ui92205
Node: web92263
Ref: #web92352
Node: Third party add-ons92398
Ref: #third-party-add-ons92573
Node: diff92708
Ref: #diff92805
Node: iadd92904
Ref: #iadd93018
Node: interest93101
Ref: #interest93222
Node: irr93317
Ref: #irr93415
Node: Experimental add-ons93546
Ref: #experimental-add-ons93698
Node: autosync93978
Ref: #autosync94089
Node: chart94328
Ref: #chart94447
Node: check94518
Ref: #check94620
Node: EXAMPLES1891
Ref: #examples1991
Node: OPTIONS3637
Ref: #options3739
Node: General options4178
Ref: #general-options4303
Node: Command options6985
Ref: #command-options7136
Node: Command arguments7534
Ref: #command-arguments7688
Node: Argument files7809
Ref: #argument-files7985
Node: Special characters in arguments and queries8251
Ref: #special-characters-in-arguments-and-queries8485
Node: More escaping8936
Ref: #more-escaping9098
Node: Even more escaping9394
Ref: #even-more-escaping9588
Node: Less escaping10259
Ref: #less-escaping10421
Node: Command line tips10666
Ref: #command-line-tips10852
Node: Unicode characters11229
Ref: #unicode-characters11385
Node: Input files12797
Ref: #input-files12933
Node: Smart dates14903
Ref: #smart-dates15044
Node: Report start & end date16450
Ref: #report-start-end-date16622
Node: Report intervals17688
Ref: #report-intervals17853
Node: Period expressions18254
Ref: #period-expressions18414
Node: Depth limiting22371
Ref: #depth-limiting22515
Node: Pivoting22857
Ref: #pivoting22975
Node: Cost24651
Ref: #cost24759
Node: Market value24877
Ref: #market-value25016
Node: More control over valuation26257
Ref: #more-control-over-valuation26442
Node: Effect of --value on reports28897
Ref: #effect-of---value-on-reports29116
Node: Some useful value reports31807
Ref: #some-useful-value-reports31986
Node: Combining -B -V --value32484
Ref: #combining--b--v---value32661
Node: Output destination32697
Ref: #output-destination32863
Node: Output format33146
Ref: #output-format33298
Node: Regular expressions33683
Ref: #regular-expressions33820
Node: QUERIES35181
Ref: #queries35283
Node: COMMANDS39245
Ref: #commands39357
Node: accounts40358
Ref: #accounts40456
Node: activity41155
Ref: #activity41265
Node: add41648
Ref: #add41747
Node: balance44334
Ref: #balance44445
Node: Classic balance report45887
Ref: #classic-balance-report46060
Node: Customising the classic balance report47429
Ref: #customising-the-classic-balance-report47657
Node: Colour support49733
Ref: #colour-support49900
Node: Flat mode50073
Ref: #flat-mode50221
Node: Depth limited balance reports50634
Ref: #depth-limited-balance-reports50834
Node: Multicolumn balance report51290
Ref: #multicolumn-balance-report51488
Node: Budget report56802
Ref: #budget-report56945
Node: Nested budgets62147
Ref: #nested-budgets62259
Ref: #output-format-165739
Node: balancesheet65817
Ref: #balancesheet65953
Node: balancesheetequity67268
Ref: #balancesheetequity67417
Node: cashflow67978
Ref: #cashflow68106
Node: check-dates69134
Ref: #check-dates69261
Node: check-dupes69540
Ref: #check-dupes69664
Node: close69957
Ref: #close70065
Node: files73479
Ref: #files73580
Node: help73727
Ref: #help73827
Node: import74920
Ref: #import75034
Node: Importing balance assignments75822
Ref: #importing-balance-assignments75970
Node: incomestatement76619
Ref: #incomestatement76753
Node: prices78089
Ref: #prices78204
Node: print78483
Ref: #print78593
Node: print-unique83086
Ref: #print-unique83212
Node: register83497
Ref: #register83624
Node: Custom register output87796
Ref: #custom-register-output87925
Node: register-match89187
Ref: #register-match89321
Node: rewrite89672
Ref: #rewrite89787
Node: Re-write rules in a file91642
Ref: #re-write-rules-in-a-file91776
Node: Diff output format92986
Ref: #diff-output-format93155
Node: rewrite vs print --auto94247
Ref: #rewrite-vs.-print---auto94426
Node: roi94982
Ref: #roi95080
Node: stats96092
Ref: #stats96191
Node: tags96945
Ref: #tags97043
Node: test97273
Ref: #test97357
Node: ADD-ON COMMANDS98118
Ref: #add-on-commands98228
Node: Official add-ons99516
Ref: #official-add-ons99656
Node: api99744
Ref: #api99833
Node: ui99885
Ref: #ui99984
Node: web100042
Ref: #web100131
Node: Third party add-ons100177
Ref: #third-party-add-ons100352
Node: diff100488
Ref: #diff100585
Node: iadd100684
Ref: #iadd100798
Node: interest100881
Ref: #interest101002
Node: irr101097
Ref: #irr101195
Node: Experimental add-ons101326
Ref: #experimental-add-ons101478
Node: autosync101759
Ref: #autosync101870
Node: chart102109
Ref: #chart102228
Node: check102299
Ref: #check102401

End Tag Table

348
hledger/hledger.txt
View File

@ -310,26 +310,38 @@ OPTIONS
to troubleshoot.
Unicode characters
hledger is expected to handle unicode (non-ascii) characters, but this
requires a well-configured environment.
hledger is expected to handle non-ascii characters correctly:
To handle unicode characters in the command line or input data, a sys-
tem locale that can decode them must be configured (POSIX's default C
locale will not work). Eg in bash, you could do:
o they should be parsed correctly in input files and on the command
line, by all hledger tools (add, iadd, hledger-web's search/add/edit
forms, etc.)
export LANG=en_US.UTF-8
o they should be displayed correctly by all hledger tools, and on-
screen alignment should be preserved.
See Troubleshooting for more about this.
This requires a well-configured environment. Here are some tips:
Unicode characters should appear correctly in hledger's output. For
the hledger and hledger-ui tools, this requires that
o A system locale must be configured, and it must be one that can
decode the characters being used. In bash, you can set a locale like
this: export LANG=en_US.UTF-8. There are some more details in Trou-
bleshooting. This step is essential - without it, hledger will quit
on encountering a non-ascii character (as with all GHC-compiled pro-
grams).
o your terminal supports unicode
o your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
must support unicode
o the terminal's font includes the required unicode glyphs
o the terminal must be using a font which includes the required unicode
glyphs
o the terminal is configured to display "wide" characters as double
width (otherwise report alignment will be off)
o the terminal should be configured to display wide characters as dou-
ble width (for report alignment)
o on Windows, for best results you should run hledger in the same kind
of environment in which it was built. Eg hledger built in the stan-
dard CMD.EXE environment (like the binaries on our download page)
might show display problems when run in a cygwin or msys terminal,
and vice versa. (See eg #961).
Input files
hledger reads transactions from a data file (and the add command writes
@ -397,7 +409,6 @@ OPTIONS
4+ digits, month is 1-12,
day is 1-31
2004 start of year
2004/10 start of month
10/1 month and day in current
year
@ -405,8 +416,9 @@ OPTIONS
october, oct start of month in current
year
yesterday, today, tomorrow -1, 0, 1 days from today
last/this/next day/week/month/quar- -1, 0, 1 periods from the
ter/year current period
last/this/next -1, 0, 1 periods from the
day/week/month/quar- current period
ter/year
20181201 8 digit YYYYMMDD with
valid year month and day
201812 6 digit YYYYMM with valid
@ -450,6 +462,9 @@ OPTIONS
ber 1st of the current
year (11/30 will be the
last date included)
-b thismonth all transactions on or
after the 1st of the cur-
rent month
@ -516,6 +531,7 @@ OPTIONS
-p "2009/1" the month of jan; equiva-
lent to "2009/1/1 to
2009/2/1"
-p "2009/1/1" just that day; equivalent
to "2009/1/1 to 2009/1/2"
@ -543,17 +559,16 @@ OPTIONS
ceeding Monday
-p "monthly in 2008/11/25" -- starts on
2018/11/01
-p "quar-
terly from 2009-05-05 to 2009-06-01" -
starts on 2009/04/01, ends on
2009/06/30, which are first and last
days of Q2 2009
-p "quarterly from 2009-05-05 to
2009-06-01" - starts on 2009/04/01,
ends on 2009/06/30, which are first and
last days of Q2 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:
biweekly, bimonthly, every day|week|month|quarter|year,
every N days|weeks|months|quarters|years.
biweekly, bimonthly, every day|week|month|quarter|year, every N
days|weeks|months|quarters|years.
All of these will start on the first day of the requested period and
end on the last one, as described above.
@ -573,9 +588,9 @@ OPTIONS
If you want intervals that start on arbitrary day of your choosing and
span a week, month or year, you need to use any of the following:
every Nth day of week, every <weekday>, every Nth day [of month],
every Nth weekday [of month], every MM/DD [of year],
every Nth MMM [of year], every MMM Nth [of year].
every Nth day of week, every <weekday>, every Nth day [of month], every
Nth weekday [of month], every MM/DD [of year], every Nth MMM [of year],
every MMM Nth [of year].
Examples:
@ -583,6 +598,7 @@ OPTIONS
-p "every 2nd day of week" -- periods
will go from Tue to Tue
-p "every Tue" -- same
-p "every 15th day" -- period bound-
aries will be on 15th of each month
-p "every 2nd Monday" -- period bound-
@ -667,33 +683,26 @@ OPTIONS
if they have a transaction price specified.
Market value
The -V/--value flag converts reported amounts to their current market
value.
Specifically, when there is a market price (P directive) for the
amount's commodity, dated on or before today's date (or the report end
date if specified), the amount will be converted to the price's commod-
ity.
When there are multiple applicable P directives, -V chooses the most
recent one, or in case of equal dates, the last-parsed one.
For example:
The -V/--market flag converts reported amounts to their market value in
another commodity. It uses the commodity referenced in the latest mar-
ket price (P directive) dated on or before the valuation date. The
default valuation date is today. For example:
# one euro is worth this many dollars from nov 1
P 2016/11/01 $1.10
P 2016/11/01 EUR $1.10
# purchase some euros on nov 3
2016/11/3
assets:euros 100
assets:euros EUR100
assets:checking
# the euro is worth fewer dollars by dec 21
P 2016/12/21 $1.03
P 2016/12/21 EUR $1.03
How many euros do I have ?
$ hledger -f t.j bal -N euros
100 assets:euros
EUR100 assets:euros
What are they worth at end of nov 3 ?
@ -706,17 +715,181 @@ OPTIONS
$ hledger -f t.j bal -N euros -V
$103.00 assets:euros
Currently, hledger's -V only uses market prices recorded with P direc-
tives, not transaction prices (unlike Ledger).
Ledger users: Ledger's -V also infers market prices from journal
entries, but we don't do that. hledger's -V uses only market prices
declared explicitly, with P directives. (Mnemonic: -B/--cost uses
transaction prices, -V/--market uses market prices.)
Currently, -V has a limitation in multicolumn balance reports: it uses
the market prices on the report end date for all columns. (Instead of
the prices on each column's end date.)
More control over valuation
(experimental, added 201905)
Combining -B and -V
Using -B/--cost and -V/--value together is currently allowed, but the
results are probably not meaningful. Let us know if you find a use for
this.
You can control valuation more precisely with the --value option.
--value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD
The argument is one of the keywords shown, or their first letter, or a
custom date. The precise effect of the keywords is command-specific,
but here is their general meaning:
--value=cost (or c)
Convert amounts to cost, using the prices recorded in transac-
tions. -B/--cost does this.
--value=end (or e)
Convert amounts to their value in default valuation commodity
using market prices on the last day of the report period (or of
each subperiod in a multiperiod report). When no report period
is specified, uses the journal's last transaction date.
--value=now (or n)
Convert amounts to their value in default valuation commodity
using current market prices (as of when report is generated).
-V/--market does this.
--value=YYYY-MM-DD
Convert amounts to their value in default valuation commodity
using market prices on the given date (which must be 8 digits
with - or / or . separators). Eg --value=2019-04-25.
Here are the effects of --value as seen with print:
P 2000-01-01 A 1 B
P 2000-02-01 A 2 B
P 2000-03-01 A 3 B
P 2000-04-01 A 4 B
2000-01-01
(a) 1 A @ 5 B
2000-02-01
(a) 1 A @ 6 B
2000-03-01
(a) 1 A @ 7 B
Show the cost of each posting:
$ hledger -f- print --value=cost
2000/01/01
(a) 5 B
2000/02/01
(a) 6 B
2000/03/01
(a) 7 B
Show the value as of the last day of the report period (2000-02-29):
$ hledger -f- print --value=end date:2000/01-2000/03
2000-01-01
(a) 2 B
2000-02-01
(a) 2 B
With no report period specified, that shows the value as of the last
day of the journal (2000-03-01):
$ hledger -f- print --value=end
2000/01/01
(a) 3 B
2000/02/01
(a) 3 B
2000/03/01
(a) 3 B
Show the current value (the 2000-04-01 price is still in effect today):
$ hledger -f- print --value=now
2000-01-01
(a) 4 B
2000-02-01
(a) 4 B
2000-03-01
(a) 4 B
Show the value on 2000/01/15:
$ hledger -f- print --value=2000-01-15
2000/01/01
(a) 1 B
2000/02/01
(a) 1 B
2000/03/01
(a) 1 B
Effect of --value on reports
Below is how --value affects each of hledger's reports, currently.
You're not expected to remember all this, but when troubleshooting a
report, look here. If you find problems - useless reports, misbehaving
reports, or error messages being printed - please report them (with
reproducible examples) eg at #329.
Report type --value cost --value end --value DATE/now
---------------------------------------------------------------------------------
print
posting cost, as market value at report market value at
amounts recorded in end DATE
transaction
balance show unvalued show unvalued show unvalued
asser-
tions/assign-
ments
register
starting bal- cost of start- market value at day market value at
ance with -H ing balance before report start DATE
posting cost market value at report market value at
amounts end DATE
posting summarised market value each summary market value each
amounts, mul- cost posting at period end summary posting at
tiperiod DATE
running sum/average of sum/average of the dis- sum/average of the
total/average the displayed played values displayed values
values
balance (bs,
cf, is..)
starting bal- costs of market value at day market value at
ances with -H starting bal- before report start of DATE of sum of
ances sum of previous postings previous postings
balances, summed costs market value at period market value at
simple bal- end of sum of postings DATE of sum of
ance report postings
balances, summed costs market value at period market value at
multiperiod end of sum of postings DATE of sum of
report postings
budget costs of bud- budget-setting periodic budget-setting
amounts with get amounts txns are valued at period periodic txns are
--budget end valued at DATE
col- sum/average of market value at period market value at
umn/row/grand the displayed end of sum/average of DATE of sum/aver-
totals/aver- values postings age of postings
ages
Some useful value reports
Here are some probably useful reports - please send suggestions if you
find out more:
Command: Description of report: Could answer:
-----------------------------------------------------------------------------
hledger bs -M Monthly historical value of How are my investments
--value=p assets/liabilities performing ?
hledger is -M Monthly contemporaneous How much foreign currency
--value=t value of revenues/expenses have I been spending ?
Combining -B, -V, --value
The rightmost of these flags wins.
Output destination
Some commands (print, register, stats, the balance commands) can write
@ -813,8 +986,7 @@ QUERIES
REGEX, acct:REGEX
match account names by this regular expression. (With no pre-
fix, acct: is assumed.)
same as above
fix, acct: is assumed.) same as above
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
match postings with a single-commodity amount that is equal to,
@ -833,8 +1005,8 @@ QUERIES
tial match, use .*REGEX.*). Note, to match characters which are
regex-significant, like the dollar sign ($), you need to prepend
\. And when using the command line you need to add one more
level of quoting to hide it from the shell, so eg do:
hledger print cur:'\$' or hledger print cur:\\$.
level of quoting to hide it from the shell, so eg do: hledger
print cur:'\$' or hledger print cur:\\$.
desc:REGEX
match transaction descriptions.
@ -893,10 +1065,10 @@ COMMANDS
scripts named hledger-NAME in your PATH, these will also be listed as
subcommands.
Run a subcommand by writing its name as first argument (eg
hledger incomestatement). You can also write one of the standard short
aliases displayed in parentheses in the command list (hledger b), or
any any unambiguous prefix of a command name (hledger inc).
Run a subcommand by writing its name as first argument (eg hledger
incomestatement). You can also write one of the standard short aliases
displayed in parentheses in the command list (hledger b), or any any
unambiguous prefix of a command name (hledger inc).
Here are all the builtin commands in alphabetical order. See also
hledger for a more organised command list, and hledger CMD -h for
@ -950,8 +1122,8 @@ COMMANDS
Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (if there are multiple
-f FILE options, the first file is used.) Existing transactions are not
actions, and appends them to the journal file (if there are multiple -f
FILE options, the first file is used.) Existing transactions are not
changed. This is the only hledger command that writes to the journal
file.
@ -1082,8 +1254,8 @@ COMMANDS
$1 supplies
Customising the classic balance report
You can customise the layout of classic balance reports with --for-
mat FMT:
You can customise the layout of classic balance reports with --format
FMT:
$ hledger balance --format "%20(account) %12(total)"
assets $-1
@ -1128,8 +1300,8 @@ COMMANDS
o %, - render on one line, comma-separated
There are some quirks. Eg in one-line mode, %(depth_spacer) has no
effect, instead %(account) has indentation built in.
Experimentation may be needed to get pleasing results.
effect, instead %(account) has indentation built in. Experimentation
may be needed to get pleasing results.
Some example formats:
@ -1237,6 +1409,9 @@ COMMANDS
----------------------++-------------------------------------
|| 0 0 0
Note that --cumulative or --historical/-H disable --row-total/-T, since
summing end balances generally does not make sense.
Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree.
@ -1522,7 +1697,9 @@ COMMANDS
report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for
a balance sheet; note this means it ignores report begin dates.
a balance sheet; note this means it ignores report begin dates (and
-T/--row-total, since summing end balances generally does not make
sense).
This command also supports output destination and output format selec-
tion.
@ -1616,7 +1793,7 @@ COMMANDS
The closing transaction transfers balances to "equity:closing bal-
ances". The opening transaction transfers balances from "equity:open-
ing balances". You can chose to print just one of the transactions by
ing balances". You can choose to print just one of the transactions by
using the --opening or --closing flag.
If you split your journal files by time (eg yearly), you will typically
@ -1744,6 +1921,20 @@ COMMANDS
$ hledger import --dry ... | hledger -f- print unknown --ignore-assertions
Importing balance assignments
Entries added by import will have their posting amounts made explicit
(like hledger print -x). This means that any balance assignments in
imported files must be evaluated; but, imported files don't get to see
the main file's account balances. As a result, importing entries with
balance assignments (eg from an institution that provides only balances
and not posting amounts) will probably generate incorrect posting
amounts. To avoid this problem, use print instead of import:
$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE
(If you think import should leave amounts implicit like print does,
please test it and send a pull request.)
incomestatement
incomestatement, is
This command displays a simple income statement, showing revenues and
@ -2021,8 +2212,8 @@ COMMANDS
Print the one posting whose transaction description is closest to DESC,
in the style of the register command. If there are multiple equally
good matches, it shows the most recent. Query options (options, not
arguments) can be used to restrict the search space. Helps
ledger-autosync detect already-seen transactions when importing.
arguments) can be used to restrict the search space. Helps ledger-
autosync detect already-seen transactions when importing.
rewrite
rewrite
@ -2038,9 +2229,9 @@ COMMANDS
Examples:
hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
hledger-rewrite.hs -f rewrites.hledger
$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'
$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'
$ hledger-rewrite.hs -f rewrites.hledger
rewrites.hledger may consist of entries like:
@ -2220,8 +2411,8 @@ COMMANDS
seed, for repeatable results from tests using randomness (currently
none of them).
This is mainly used by developers, but it's nice to be able to san-
ity-check your installed hledger executable at any time. All tests are
This is mainly used by developers, but it's nice to be able to sanity-
check your installed hledger executable at any time. All tests are
expected to pass - if you ever see otherwise, something has gone wrong,
please report a bug!
@ -2241,8 +2432,8 @@ ADD-ON COMMANDS
from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000.
o You can always run add-ons directly if preferred:
hledger-web --serve --port 9000.
o You can always run add-ons directly if preferred: hledger-web --serve
--port 9000.
Add-ons are a relatively easy way to add local features or experiment
with new ideas. They can be written in any language, but haskell
@ -2316,7 +2507,7 @@ FILES
$HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal).
BUGS
LIMITATIONS
The need to precede addon command options with -- when invoked from
hledger is awkward.
@ -2327,6 +2518,9 @@ BUGS
In a Microsoft Windows CMD window, non-ascii characters and colours are
not supported.
On Windows, non-ascii characters may not display correctly when running
a hledger built in CMD in MSYS/CYGWIN, or vice-versa.
In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add.
@ -2418,4 +2612,4 @@ SEE ALSO
hledger 1.14.1 March 2019 hledger(1)
hledger 1.14.99 March 2019 hledger(1)