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

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

@ -27,11 +27,11 @@ DESCRIPTION
hledger_journal(5) etc. hledger_journal(5) etc.
The server listens on IP address 127.0.0.1, accessible only to local The server listens on IP address 127.0.0.1, accessible only to local
requests, by default. You can change this with --host, eg requests, by default. You can change this with --host, eg --host
--host 0.0.0.0 to listen on all addresses. Note there is no other 0.0.0.0 to listen on all addresses. Note there is no other access con-
access control, and hledger-api allows file browsing, so on shared trol, and hledger-api allows file browsing, so on shared machines you
machines you will certainly need to put it behind an authenticating will certainly need to put it behind an authenticating proxy to
proxy to restrict access. restrict access.
You can change the TCP port it listens on (default: 8001) with -p PORT. 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 .SH NAME
.PP .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 .SH DESCRIPTION
.PP .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 journal files, automatically converting each CSV record into a
transaction. 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 .PP
Converting CSV to transactions requires some special conversion rules. Converting CSV to transactions requires some special conversion rules.
These do several things: These do several things:
@ -24,58 +24,57 @@ templating language
they can add refinements based on patterns in the CSV data, eg they can add refinements based on patterns in the CSV data, eg
categorizing transactions with more detailed account names. categorizing transactions with more detailed account names.
.PP .PP
When reading a CSV file named \f[C]FILE.csv\f[], hledger looks for a 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[] in the same conversion rules file named \f[C]FILE.csv.rules\f[R] in the same
directory. directory.
You can override this with the \f[C]\-\-rules\-file\f[] option. 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 If the rules file does not exist, hledger will auto-create one with some
some example rules, which you\[aq]ll need to adjust. example rules, which you\[aq]ll need to adjust.
.PP .PP
At minimum, the rules file must identify the \f[C]date\f[] and At minimum, the rules file must identify the date and amount fields.
\f[C]amount\f[] fields. It\[aq]s often necessary to specify the date format, and the number of
It may also be necessary to specify the date format, and the number of header lines to skip, also.
header lines to skip.
Eg: Eg:
.IP .IP
.nf .nf
\f[C] \f[C]
fields\ date,\ _,\ _,\ amount fields date, _, _, amount
date\-format\ \ %d/%m/%Y date-format %d/%m/%Y
skip\ 1 skip 1
\f[] \f[R]
.fi .fi
.PP .PP
A more complete example: A more complete example:
.IP .IP
.nf .nf
\f[C] \f[C]
#\ hledger\ CSV\ rules\ for\ amazon.com\ order\ history # hledger CSV rules for amazon.com order history
#\ sample: # sample:
#\ "Date","Type","To/From","Name","Status","Amount","Fees","Transaction\ ID" # \[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]
#\ "Jul\ 29,\ 2012","Payment","To","Adapteva,\ Inc.","Completed","$25.00","$0.00","17LA58JSK6PRD4HDGLNJQPI1PB9N8DKPVHL" # \[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 one header line
skip\ 1 skip 1
#\ name\ the\ csv\ fields\ (and\ assign\ the\ transaction\[aq]s\ date,\ amount\ and\ code) # name the csv fields (and assign the transaction\[aq]s date, amount and code)
fields\ date,\ _,\ toorfrom,\ name,\ amzstatus,\ amount,\ fees,\ code fields date, _, toorfrom, name, amzstatus, amount, fees, code
#\ how\ to\ parse\ the\ date # how to parse the date
date\-format\ %b\ %\-d,\ %Y date-format %b %-d, %Y
#\ combine\ two\ fields\ to\ make\ the\ description # combine two fields to make the description
description\ %toorfrom\ %name description %toorfrom %name
#\ save\ these\ fields\ as\ tags # save these fields as tags
comment\ \ \ \ \ status:%amzstatus,\ fees:%fees comment status:%amzstatus, fees:%fees
#\ set\ the\ base\ account\ for\ all\ transactions # set the base account for all transactions
account1\ \ \ \ assets:amazon account1 assets:amazon
#\ flip\ the\ sign\ on\ the\ amount # flip the sign on the amount
amount\ \ \ \ \ \ \-%amount amount -%amount
\f[] \f[R]
.fi .fi
.PP .PP
For more examples, see Convert CSV files. For more examples, see Convert CSV files.
@ -83,11 +82,11 @@ For more examples, see Convert CSV files.
.PP .PP
The following seven kinds of rule can appear in the rules file, in any The following seven kinds of rule can appear in the rules file, in any
order. 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. ignored.
.SS skip .SS skip
.PP .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 .PP
Skip this number of CSV records at the beginning. Skip this number of CSV records at the beginning.
You\[aq]ll need this whenever your CSV data contains header lines. You\[aq]ll need this whenever your CSV data contains header lines.
@ -95,122 +94,123 @@ Eg:
.IP .IP
.nf .nf
\f[C] \f[C]
#\ ignore\ the\ first\ CSV\ line # ignore the first CSV line
skip\ 1 skip 1
\f[] \f[R]
.fi .fi
.SS date\-format .SS date-format
.PP .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 .PP
When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[] (or When your CSV date fields are not formatted like \f[C]YYYY/MM/DD\f[R]
\f[C]YYYY\-MM\-DD\f[] or \f[C]YYYY.MM.DD\f[]), you\[aq]ll need to (or \f[C]YYYY-MM-DD\f[R] or \f[C]YYYY.MM.DD\f[R]), you\[aq]ll need to
specify the format. 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. date field values completely.
Examples: Examples:
.IP .IP
.nf .nf
\f[C] \f[C]
#\ for\ dates\ like\ "11/06/2013": # for dates like \[dq]11/06/2013\[dq]:
date\-format\ %m/%d/%Y date-format %m/%d/%Y
\f[] \f[R]
.fi .fi
.IP .IP
.nf .nf
\f[C] \f[C]
#\ for\ dates\ like\ "6/11/2013"\ (note\ the\ \-\ to\ make\ leading\ zeros\ optional): # for dates like \[dq]6/11/2013\[dq] (note the - to make leading zeros optional):
date\-format\ %\-d/%\-m/%Y date-format %-d/%-m/%Y
\f[] \f[R]
.fi .fi
.IP .IP
.nf .nf
\f[C] \f[C]
#\ for\ dates\ like\ "2013\-Nov\-06": # for dates like \[dq]2013-Nov-06\[dq]:
date\-format\ %Y\-%h\-%d date-format %Y-%h-%d
\f[] \f[R]
.fi .fi
.IP .IP
.nf .nf
\f[C] \f[C]
#\ for\ dates\ like\ "11/6/2013\ 11:32\ PM": # for dates like \[dq]11/6/2013 11:32 PM\[dq]:
date\-format\ %\-m/%\-d/%Y\ %l:%M\ %p date-format %-m/%-d/%Y %l:%M %p
\f[] \f[R]
.fi .fi
.SS field list .SS field list
.PP .PP
\f[C]fields\f[]\f[I]\f[CI]FIELDNAME1\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[]... \f[I]\f[CI]FIELDNAME2\f[I]\f[R]...
.PP .PP
This (a) names the CSV fields, in order (names may not contain This (a) names the CSV fields, in order (names may not contain
whitespace; uninteresting names may be left blank), and (b) assigns them whitespace; uninteresting names may be left blank), and (b) assigns them
to journal entry fields if you use any of these standard field names: 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]date\f[R], \f[C]date2\f[R], \f[C]status\f[R], \f[C]code\f[R],
\f[C]description\f[], \f[C]comment\f[], \f[C]account1\f[], \f[C]description\f[R], \f[C]comment\f[R], \f[C]account1\f[R],
\f[C]account2\f[], \f[C]amount\f[], \f[C]amount\-in\f[], \f[C]account2\f[R], \f[C]amount\f[R], \f[C]amount-in\f[R],
\f[C]amount\-out\f[], \f[C]currency\f[], \f[C]balance\f[]. \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: Eg:
.IP .IP
.nf .nf
\f[C] \f[C]
#\ use\ the\ 1st,\ 2nd\ and\ 4th\ CSV\ fields\ as\ the\ entry\[aq]s\ date,\ description\ and\ amount, # 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: # and give the 7th and 8th fields meaningful names for later reference:
# #
#\ CSV\ field: # CSV field:
#\ \ \ \ \ \ 1\ \ \ \ \ 2\ \ \ \ \ \ \ \ \ \ \ \ 3\ 4\ \ \ \ \ \ \ 5\ 6\ 7\ \ \ \ \ \ \ \ \ \ 8 # 1 2 3 4 5 6 7 8
#\ entry\ field: # entry field:
fields\ date,\ description,\ ,\ amount,\ ,\ ,\ somefield,\ anotherfield fields date, description, , amount, , , somefield, anotherfield
\f[] \f[R]
.fi .fi
.SS field assignment .SS field assignment
.PP .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 .PP
This sets a journal entry field (one of the standard names above) to the 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 given text value, which can include CSV field values interpolated by
name (\f[C]%CSVFIELDNAME\f[]) or 1\-based position (\f[C]%N\f[]). name (\f[C]%CSVFIELDNAME\f[R]) or 1-based position (\f[C]%N\f[R]).
Eg: Eg:
.IP .IP
.nf .nf
\f[C] \f[C]
#\ set\ the\ amount\ to\ the\ 4th\ CSV\ field\ with\ "USD\ "\ prepended # set the amount to the 4th CSV field with \[dq]USD \[dq] prepended
amount\ USD\ %4 amount USD %4
\f[] \f[R]
.fi .fi
.IP .IP
.nf .nf
\f[C] \f[C]
#\ combine\ three\ fields\ to\ make\ a\ comment\ (containing\ two\ tags) # combine three fields to make a comment (containing two tags)
comment\ note:\ %somefield\ \-\ %anotherfield,\ date:\ %1 comment note: %somefield - %anotherfield, date: %1
\f[] \f[R]
.fi .fi
.PP .PP
Field assignments can be used instead of or in addition to a field list. Field assignments can be used instead of or in addition to a field list.
.SS conditional block .SS conditional block
.PP .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 .PD 0
.P .P
.PD .PD
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]... \ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[R]...
.PP .PP
\f[C]if\f[] \f[C]if\f[R]
.PD 0 .PD 0
.P .P
.PD .PD
\f[I]\f[CI]PATTERN\f[I]\f[] \f[I]\f[CI]PATTERN\f[I]\f[R]
.PD 0 .PD 0
.P .P
.PD .PD
\f[I]\f[CI]PATTERN\f[I]\f[]... \f[I]\f[CI]PATTERN\f[I]\f[R]...
.PD 0 .PD 0
.P .P
.PD .PD
\ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[]... \ \ \ \ \f[I]\f[CI]FIELDASSIGNMENTS\f[I]\f[R]...
.PP .PP
This applies one or more field assignments, only to those CSV records This applies one or more field assignments, only to those CSV records
matched by one of the PATTERNs. 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 anywhere within the whole CSV record (it\[aq]s not yet possible to match
within a specific field). within a specific field).
When there are multiple patterns they can be written on separate lines, When there are multiple patterns they can be written on separate lines,
@ -221,46 +221,46 @@ Examples:
.IP .IP
.nf .nf
\f[C] \f[C]
#\ if\ the\ CSV\ record\ contains\ "groceries",\ set\ account2\ to\ "expenses:groceries" # if the CSV record contains \[dq]groceries\[dq], set account2 to \[dq]expenses:groceries\[dq]
if\ groceries if groceries
\ account2\ expenses:groceries account2 expenses:groceries
\f[] \f[R]
.fi .fi
.IP .IP
.nf .nf
\f[C] \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 if
monthly\ service\ fee monthly service fee
atm\ transaction\ fee atm transaction fee
banking\ thru\ software banking thru software
\ account2\ expenses:business:banking account2 expenses:business:banking
\ comment\ \ XXX\ deductible\ ?\ check\ it comment XXX deductible ? check it
\f[] \f[R]
.fi .fi
.SS include .SS include
.PP .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 .PP
Include another rules file at this point. Include another rules file at this point.
\f[C]RULESFILE\f[] is either an absolute file path or a path relative to \f[C]RULESFILE\f[R] is either an absolute file path or a path relative
the current file\[aq]s directory. to the current file\[aq]s directory.
Eg: Eg:
.IP .IP
.nf .nf
\f[C] \f[C]
#\ rules\ reused\ with\ several\ CSV\ files # rules reused with several CSV files
include\ common.rules include common.rules
\f[] \f[R]
.fi .fi
.SS newest\-first .SS newest-first
.PP .PP
\f[C]newest\-first\f[] \f[C]newest-first\f[R]
.PP .PP
Consider adding this rule if all of the following are true: you might be 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 processing just one day of data, your CSV records are in reverse
chronological order (newest first), and you care about preserving the 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, 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 but when all CSV records have the same date it will assume they are
oldest first. oldest first.
@ -268,49 +268,69 @@ oldest first.
.SS CSV ordering .SS CSV ordering
.PP .PP
The generated journal entries will be sorted by date. The generated journal entries will be sorted by date.
The order of same\-day entries will be preserved (except in the special 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). case where you might need \f[C]newest-first\f[R], see above).
.SS CSV accounts .SS CSV accounts
.PP .PP
Each journal entry will have two postings, to \f[C]account1\f[] and Each journal entry will have two postings, to \f[C]account1\f[R] and
\f[C]account2\f[] respectively. \f[C]account2\f[R] respectively.
It\[aq]s not yet possible to generate entries with more than two It\[aq]s not yet possible to generate entries with more than two
postings. 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. account whose CSV we are reading.
.SS CSV amounts .SS CSV amounts
.PP .PP
The \f[C]amount\f[] field sets the amount of the \f[C]account1\f[] A transaction amount must be set, in one of these ways:
posting. .IP \[bu] 2
.PP with an \f[C]amount\f[R] field assignment, which sets the first
If the CSV has debit/credit amounts in separate fields, assign to the posting\[aq]s amount
\f[C]amount\-in\f[] and \f[C]amount\-out\f[] pseudo fields instead. .IP \[bu] 2
(Whichever one has a value will be used, with appropriate sign. (When the CSV has debit and credit amounts in separate fields:)
If both contain a value, it may not work so well.) .PD 0
.PP .P
If an amount value is parenthesised, it will be de\-parenthesised and .PD
sign\-flipped. 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 .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 If an amount value begins with a double minus sign, those will cancel
out and be removed. out and be removed.
.PP .PP
If the CSV has the currency symbol in a separate field, assign that to If the currency/commodity symbol is provided as a separate CSV field,
the \f[C]currency\f[] pseudo field to have it prepended to the amount. assign it to the \f[C]currency\f[R] pseudo field; the symbol will be
Or, you can use a field assignment to \f[C]amount\f[] that interpolates prepended to the amount (TODO: when there is an amount).
both CSV fields (giving more control, eg to put the currency symbol on Or, you can use an \f[C]amount\f[R] field assignment for more control,
the right). eg:
.SS CSV balance assertions .IP
.nf
\f[C]
fields date,description,currency,amount
amount %amount %currency
\f[R]
.fi
.SS CSV balance assertions/assignments
.PP .PP
If the CSV includes a running balance, you can assign that to the If the CSV includes a running balance, you can assign that to one of the
\f[C]balance\f[] pseudo field; whenever the running balance value is pseudo fields \f[C]balance\f[R] (or \f[C]balance1\f[R]) or
non\-empty, it will be asserted as the balance after the \f[C]balance2\f[R].
\f[C]account1\f[] posting. 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 .SS Reading multiple CSV files
.PP .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 arguments on the command line, and hledger will look for a
correspondingly\-named rules file for each. correspondingly-named rules file for each.
Note if you use the \f[C]\-\-rules\-file\f[] option, this one rules file 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. 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) 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 hledger can read CSV (comma-separated value) files as if they were
journal files, automatically converting each CSV record into a 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, does not exist, hledger will auto-create one with some example rules,
which you'll need to adjust. which you'll need to adjust.
At minimum, the rules file must identify the 'date' and 'amount' At minimum, the rules file must identify the date and amount fields.
fields. It may also be necessary to specify the date format, and the It's often necessary to specify the date format, and the number of
number of header lines to skip. Eg: header lines to skip, also. Eg:
fields date, _, _, amount fields date, _, _, amount
date-format %d/%m/%Y date-format %d/%m/%Y
@ -63,6 +63,7 @@ account1 assets:amazon
amount -%amount amount -%amount
For more examples, see Convert CSV files. For more examples, see Convert CSV files.
* Menu: * Menu:
* CSV RULES:: * 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 The following seven kinds of rule can appear in the rules file, in any
order. Blank lines and lines beginning with '#' or ';' are ignored. order. Blank lines and lines beginning with '#' or ';' are ignored.
* Menu: * Menu:
* skip:: * 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 whitespace; uninteresting names may be left blank), and (b) assigns them
to journal entry fields if you use any of these standard field names: to journal entry fields if you use any of these standard field names:
'date', 'date2', 'status', 'code', 'description', 'comment', 'account1', 'date', 'date2', 'status', 'code', 'description', 'comment', 'account1',
'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance'. 'account2', 'amount', 'amount-in', 'amount-out', 'currency', 'balance',
Eg: 'balance1', 'balance2'. Eg:
# use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount, # 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: # 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 ordering::
* CSV accounts:: * CSV accounts::
* CSV amounts:: * CSV amounts::
* CSV balance assertions:: * CSV balance assertions/assignments::
* Reading multiple CSV files:: * 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. 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 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 * with an 'amount' field assignment, which sets the first posting's
'amount-in' and 'amount-out' pseudo fields instead. (Whichever one has amount
a value will be used, with appropriate sign. If both contain a value,
it may not work so well.)
If an amount value is parenthesised, it will be de-parenthesised and * (When the CSV has debit and credit amounts in separate fields:)
sign-flipped. 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 * or implicitly by means of a balance assignment (see below).
out and be removed.
If the CSV has the currency symbol in a separate field, assign that There is some special handling for sign in amounts:
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 * If an amount value is parenthesised, it will be de-parenthesised
fields (giving more control, eg to put the currency symbol on the and sign-flipped.
right). * 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 If the CSV includes a running balance, you can assign that to one of the
'balance' pseudo field; whenever the running balance value is non-empty, pseudo fields 'balance' (or 'balance1') or 'balance2'. This will
it will be asserted as the balance after the 'account1' posting. 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 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: Tag Table:
Node: Top72 Node: Top72
Node: CSV RULES2163 Node: CSV RULES2167
Ref: #csv-rules2271 Ref: #csv-rules2275
Node: skip2533 Node: skip2538
Ref: #skip2627 Ref: #skip2632
Node: date-format2799 Node: date-format2804
Ref: #date-format2926 Ref: #date-format2931
Node: field list3476 Node: field list3481
Ref: #field-list3613 Ref: #field-list3618
Node: field assignment4318 Node: field assignment4348
Ref: #field-assignment4473 Ref: #field-assignment4503
Node: conditional block4977 Node: conditional block5007
Ref: #conditional-block5131 Ref: #conditional-block5161
Node: include6027 Node: include6057
Ref: #include6157 Ref: #include6187
Node: newest-first6388 Node: newest-first6418
Ref: #newest-first6502 Ref: #newest-first6532
Node: CSV TIPS6913 Node: CSV TIPS6943
Ref: #csv-tips7007 Ref: #csv-tips7037
Node: CSV ordering7125 Node: CSV ordering7167
Ref: #csv-ordering7243 Ref: #csv-ordering7285
Node: CSV accounts7424 Node: CSV accounts7466
Ref: #csv-accounts7562 Ref: #csv-accounts7604
Node: CSV amounts7816 Node: CSV amounts7858
Ref: #csv-amounts7962 Ref: #csv-amounts8016
Node: CSV balance assertions8737 Node: CSV balance assertions/assignments9096
Ref: #csv-balance-assertions8919 Ref: #csv-balance-assertionsassignments9314
Node: Reading multiple CSV files9124 Node: Reading multiple CSV files9635
Ref: #reading-multiple-csv-files9294 Ref: #reading-multiple-csv-files9817
 
End Tag Table End Tag Table

62
hledger-lib/hledger_csv.txt
View File

@ -29,8 +29,8 @@ DESCRIPTION
you'll need to adjust. you'll need to adjust.
At minimum, the rules file must identify the date and amount fields. 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 It's often necessary to specify the date format, and the number of
header lines to skip. Eg: header lines to skip, also. Eg:
fields date, _, _, amount fields date, _, _, amount
date-format %d/%m/%Y date-format %d/%m/%Y
@ -83,10 +83,10 @@ CSV RULES
date-format date-format
date-formatDATEFMT date-formatDATEFMT
When your CSV date fields are not formatted like YYYY/MM/DD (or When your CSV date fields are not formatted like YYYY/MM/DD (or YYYY-
YYYY-MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT MM-DD or YYYY.MM.DD), you'll need to specify the format. DATEFMT is a
is a strptime-like date parsing pattern, which must parse the date strptime-like date parsing pattern, which must parse the date field
field values completely. Examples: values completely. Examples:
# for dates like "11/06/2013": # for dates like "11/06/2013":
date-format %m/%d/%Y date-format %m/%d/%Y
@ -107,7 +107,8 @@ CSV RULES
space; uninteresting names may be left blank), and (b) assigns them to space; uninteresting names may be left blank), and (b) assigns them to
journal entry fields if you use any of these standard field names: journal entry fields if you use any of these standard field names:
date, date2, status, code, description, comment, account1, account2, 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, # 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: # 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 This sets a journal entry field (one of the standard names above) to
the given text value, which can include CSV field values interpolated the given text value, which can include CSV field values interpolated
by name (%CSVFIELDNAME) or 1-based position (%N). by name (%CSVFIELDNAME) or 1-based position (%N). Eg:
Eg:
# set the amount to the 4th CSV field with "USD " prepended # set the amount to the 4th CSV field with "USD " prepended
amount USD %4 amount USD %4
@ -195,28 +195,40 @@ CSV TIPS
the account whose CSV we are reading. the account whose CSV we are reading.
CSV amounts 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 o with an amount field assignment, which sets the first posting's
amount-in and amount-out pseudo fields instead. (Whichever one has a amount
value will be used, with appropriate sign. If both contain a value, it
may not work so well.)
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. 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. out and be removed.
If the CSV has the currency symbol in a separate field, assign that to If the currency/commodity symbol is provided as a separate CSV field,
the currency pseudo field to have it prepended to the amount. Or, you assign it to the currency pseudo field; the symbol will be prepended to
can use a field assignment to amount that interpolates both CSV fields the amount (TODO: when there is an amount). Or, you can use an amount
(giving more control, eg to put the currency symbol on the right). field assignment for more control, eg:
CSV balance assertions fields date,description,currency,amount
If the CSV includes a running balance, you can assign that to the bal- amount %amount %currency
ance pseudo field; whenever the running balance value is non-empty, it
will be asserted as the balance after the account1 posting. 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 Reading multiple CSV files
You can read multiple CSV files at once using multiple -f arguments on 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) 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 hledger's usual data source is a plain text file containing journal
entries in hledger journal format. This file represents a standard 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:: * Tags::
* Directives:: * Directives::
* Periodic transactions:: * Periodic transactions::
* Transaction modifiers:: * Auto postings / transaction modifiers::
 
File: hledger_journal.info, Node: Transactions, Next: Postings, Up: FILE FORMAT 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 "narration" in traditional bookkeeping, it can be used for whatever you
wish, or left blank. Transaction descriptions can be queried, unlike wish, or left blank. Transaction descriptions can be queried, unlike
comments. comments.
* Menu: * Menu:
* Payee and note:: * 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 while cleaning up old entries. You can disable them temporarily with
the '-I/--ignore-assertions' flag, which can be useful for the '-I/--ignore-assertions' flag, which can be useful for
troubleshooting or for reading Ledger files. troubleshooting or for reading Ledger files.
* Menu: * Menu:
* Assertions and ordering:: * 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 assignment). Note that using balance assignments makes your journal a
little less explicit; to know the exact amount posted, you have to run little less explicit; to know the exact amount posted, you have to run
hledger or do the calculations yourself, instead of just reading it. hledger or do the calculations yourself, instead of just reading it.
* Menu: * Menu:
* Balance assignments and prices:: * 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 more simplicity and predictability, eg reports are not changed by
writing file options in a different order. It can be surprising at writing file options in a different order. It can be surprising at
times though. times though.
* Menu: * Menu:
* Comment blocks:: * Comment blocks::
@ -1248,6 +1252,7 @@ They do not affect account names being entered via hledger add or
hledger-web. hledger-web.
See also Cookbook: Rewrite account names. See also Cookbook: Rewrite account names.
* Menu: * Menu:
* Basic aliases:: * Basic aliases::
@ -1372,7 +1377,7 @@ If account aliases are present, they are applied after the default
parent account. 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 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 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 date, unless a Y default year directive is in effect, in which case they
will be relative to Y/1/1. will be relative to Y/1/1.
* Menu: * Menu:
* Two spaces after the period expression:: * Two spaces after the period expression::
@ -1482,29 +1488,29 @@ compared in budget reports.
and Forecasting. 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 Transaction modifier rules describe changes to be applied automatically
automatically to certain transactions. They can be enabled by using the to certain matched transactions. Currently just one kind of change is
'--auto' flag. Currently, just one kind of change is possible: adding possible - adding extra postings, which we call "automated postings" or
extra postings. These rule-generated postings are known as "automated just "auto postings". These rules become active when you use the
postings" or "auto postings". '--auto' flag.
A transaction modifier rule looks quite like a normal transaction, A transaction modifier, AKA auto posting rule, looks much like a
except the first line is an equals sign followed by a query that matches normal transaction except the first line is an equals sign followed by a
certain postings (mnemonic: '=' suggests matching). And each "posting" query that matches certain postings (mnemonic: '=' suggests matching).
is actually a posting-generating rule: And each "posting" is actually a posting-generating rule:
= QUERY = QUERY
ACCT AMT ACCT AMT
ACCT [AMT] ACCT [AMT]
... ...
These posting rules look like normal postings, except the amount can These posting-generating rules look like normal postings, except the
be: amount can be:
* a normal amount with a commodity symbol, eg '$2'. This will be * a normal amount with a commodity symbol, eg '$2'. This will be
used as-is. used as-is.
@ -1517,6 +1523,10 @@ be:
and symbol S). The matched posting's amount will be multiplied by and symbol S). The matched posting's amount will be multiplied by
N, and its commodity symbol will be replaced with S. 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: Some examples:
; every time I buy food, schedule a dollar donation ; 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:: * 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 / 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: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT2372 Node: FILE FORMAT2378
Ref: #file-format2496 Ref: #file-format2502
Node: Transactions2783 Node: Transactions2805
Ref: #transactions2904 Ref: #transactions2926
Node: Postings3588 Node: Postings3610
Ref: #postings3715 Ref: #postings3737
Node: Dates4710 Node: Dates4732
Ref: #dates4825 Ref: #dates4847
Node: Simple dates4890 Node: Simple dates4912
Ref: #simple-dates5016 Ref: #simple-dates5038
Node: Secondary dates5382 Node: Secondary dates5404
Ref: #secondary-dates5536 Ref: #secondary-dates5558
Node: Posting dates7099 Node: Posting dates7121
Ref: #posting-dates7228 Ref: #posting-dates7250
Node: Status8602 Node: Status8624
Ref: #status8722 Ref: #status8744
Node: Description10430 Node: Description10452
Ref: #description10568 Ref: #description10590
Node: Payee and note10887 Node: Payee and note10910
Ref: #payee-and-note11001 Ref: #payee-and-note11024
Node: Account names11243 Node: Account names11266
Ref: #account-names11386 Ref: #account-names11409
Node: Amounts11873 Node: Amounts11896
Ref: #amounts12009 Ref: #amounts12032
Node: Virtual Postings15026 Node: Virtual Postings15049
Ref: #virtual-postings15185 Ref: #virtual-postings15208
Node: Balance Assertions16405 Node: Balance Assertions16428
Ref: #balance-assertions16580 Ref: #balance-assertions16603
Node: Assertions and ordering17538 Node: Assertions and ordering17562
Ref: #assertions-and-ordering17724 Ref: #assertions-and-ordering17748
Node: Assertions and included files18424 Node: Assertions and included files18448
Ref: #assertions-and-included-files18665 Ref: #assertions-and-included-files18689
Node: Assertions and multiple -f options18998 Node: Assertions and multiple -f options19022
Ref: #assertions-and-multiple--f-options19252 Ref: #assertions-and-multiple--f-options19276
Node: Assertions and commodities19384 Node: Assertions and commodities19408
Ref: #assertions-and-commodities19614 Ref: #assertions-and-commodities19638
Node: Assertions and prices20770 Node: Assertions and prices20794
Ref: #assertions-and-prices20982 Ref: #assertions-and-prices21006
Node: Assertions and subaccounts21422 Node: Assertions and subaccounts21446
Ref: #assertions-and-subaccounts21649 Ref: #assertions-and-subaccounts21673
Node: Assertions and virtual postings21973 Node: Assertions and virtual postings21997
Ref: #assertions-and-virtual-postings22213 Ref: #assertions-and-virtual-postings22237
Node: Assertions and precision22355 Node: Assertions and precision22379
Ref: #assertions-and-precision22546 Ref: #assertions-and-precision22570
Node: Balance Assignments22813 Node: Balance Assignments22837
Ref: #balance-assignments22994 Ref: #balance-assignments23018
Node: Balance assignments and prices24158 Node: Balance assignments and prices24183
Ref: #balance-assignments-and-prices24330 Ref: #balance-assignments-and-prices24355
Node: Transaction prices24554 Node: Transaction prices24579
Ref: #transaction-prices24723 Ref: #transaction-prices24748
Node: Comments26991 Node: Comments27016
Ref: #comments27125 Ref: #comments27150
Node: Tags28295 Node: Tags28320
Ref: #tags28413 Ref: #tags28438
Node: Directives29815 Node: Directives29840
Ref: #directives29958 Ref: #directives29983
Node: Comment blocks35565 Node: Comment blocks35591
Ref: #comment-blocks35710 Ref: #comment-blocks35736
Node: Including other files35886 Node: Including other files35912
Ref: #including-other-files36066 Ref: #including-other-files36092
Node: Default year36474 Node: Default year36500
Ref: #default-year36643 Ref: #default-year36669
Node: Declaring commodities37066 Node: Declaring commodities37092
Ref: #declaring-commodities37249 Ref: #declaring-commodities37275
Node: Default commodity38476 Node: Default commodity38502
Ref: #default-commodity38652 Ref: #default-commodity38678
Node: Market prices39288 Node: Market prices39314
Ref: #market-prices39453 Ref: #market-prices39479
Node: Declaring accounts40294 Node: Declaring accounts40320
Ref: #declaring-accounts40470 Ref: #declaring-accounts40496
Node: Account comments41395 Node: Account comments41421
Ref: #account-comments41558 Ref: #account-comments41584
Node: Account subdirectives41953 Node: Account subdirectives41979
Ref: #account-subdirectives42148 Ref: #account-subdirectives42174
Node: Account types42461 Node: Account types42487
Ref: #account-types42645 Ref: #account-types42671
Node: Account display order44289 Node: Account display order44315
Ref: #account-display-order44459 Ref: #account-display-order44485
Node: Rewriting accounts45588 Node: Rewriting accounts45614
Ref: #rewriting-accounts45773 Ref: #rewriting-accounts45799
Node: Basic aliases46507 Node: Basic aliases46534
Ref: #basic-aliases46653 Ref: #basic-aliases46680
Node: Regex aliases47357 Node: Regex aliases47384
Ref: #regex-aliases47528 Ref: #regex-aliases47555
Node: Multiple aliases48246 Node: Multiple aliases48273
Ref: #multiple-aliases48421 Ref: #multiple-aliases48448
Node: end aliases48919 Node: end aliases48946
Ref: #end-aliases49066 Ref: #end-aliases49093
Node: Default parent account49167 Node: Default parent account49194
Ref: #default-parent-account49333 Ref: #default-parent-account49360
Node: Periodic transactions50217 Node: Periodic transactions50244
Ref: #periodic-transactions50399 Ref: #periodic-transactions50442
Node: Two spaces after the period expression51524 Node: Two spaces after the period expression51568
Ref: #two-spaces-after-the-period-expression51769 Ref: #two-spaces-after-the-period-expression51813
Node: Forecasting with periodic transactions52254 Node: Forecasting with periodic transactions52298
Ref: #forecasting-with-periodic-transactions52544 Ref: #forecasting-with-periodic-transactions52588
Node: Budgeting with periodic transactions54231 Node: Budgeting with periodic transactions54275
Ref: #budgeting-with-periodic-transactions54470 Ref: #budgeting-with-periodic-transactions54514
Node: Transaction modifiers54929 Node: Auto postings / transaction modifiers54973
Ref: #transaction-modifiers55092 Ref: #auto-postings-transaction-modifiers55184
Node: Auto postings and transaction balancing / inferred amounts / balance assertions57076 Node: Auto postings and transaction balancing / inferred amounts / balance assertions57356
Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57377 Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions57673
Node: EDITOR SUPPORT57755 Node: EDITOR SUPPORT58051
Ref: #editor-support57873 Ref: #editor-support58169
 
End Tag Table End Tag Table

141
hledger-lib/hledger_journal.txt
View File

@ -237,8 +237,8 @@ FILE FORMAT
Account names Account names
Account names typically have several parts separated by a full colon, Account names typically have several parts separated by a full colon,
from which hledger derives a hierarchical chart of accounts. They can from which hledger derives a hierarchical chart of accounts. They can
be anything you like, but in finance there are traditionally five be anything you like, but in finance there are traditionally five top-
top-level accounts: assets, liabilities, income, expenses, and equity. level accounts: assets, liabilities, income, expenses, and equity.
Account names may contain single spaces, eg: assets:accounts receiv- Account names may contain single spaces, eg: assets:accounts receiv-
able. Because of this, they must always be followed by two or more 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- Ledger assertions do not see the accumulated effect of repeated post-
ings to the same account within a transaction.) ings to the same account within a transaction.)
So, hledger balance assertions keep working if you reorder differ- So, hledger balance assertions keep working if you reorder differently-
ently-dated transactions within the journal. But if you reorder dated transactions within the journal. But if you reorder same-dated
same-dated transactions or postings, assertions might break and require transactions or postings, assertions might break and require updating.
updating. This order dependence does bring an advantage: precise con- This order dependence does bring an advantage: precise control over the
trol over the order of postings and assertions within a day, so you can order of postings and assertions within a day, so you can assert intra-
assert intra-day balances. day balances.
Assertions and included files Assertions and included files
With included files, things are a little more complicated. Including With included files, things are a little more complicated. Including
@ -418,17 +418,17 @@ FILE FORMAT
2013/1/1 2013/1/1
a $1 a $1
a 1 a 1EUR
b $-1 b $-1
c -1 c -1EUR
2013/1/2 ; These assertions succeed 2013/1/2 ; These assertions succeed
a 0 = $1 a 0 = $1
a 0 = 1 a 0 = 1EUR
b 0 == $-1 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 a 0 == $1
It's not yet possible to make a complete assertion about a balance that It's not yet possible to make a complete assertion about a balance that
@ -437,20 +437,20 @@ FILE FORMAT
2013/1/1 2013/1/1
a:usd $1 a:usd $1
a:euro 1 a:euro 1EUR
b b
2013/1/2 2013/1/2
a 0 == 0 a 0 == 0
a:usd 0 == $1 a:usd 0 == $1
a:euro 0 == 1 a:euro 0 == 1EUR
Assertions and prices Assertions and prices
Balance assertions ignore transaction prices, and should normally be Balance assertions ignore transaction prices, and should normally be
written without one: written without one:
2019/1/1 2019/1/1
(a) $1 @ 1 = $1 (a) $1 @ EUR1 = $1
We do allow prices to be written there, however, and print shows them, 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. even though they don't affect whether the assertion passes or fails.
@ -512,11 +512,11 @@ FILE FORMAT
amount to have that price attached: amount to have that price attached:
2019/1/1 2019/1/1
(a) = $1 @ 2 (a) = $1 @ EUR2
$ hledger print --explicit $ hledger print --explicit
2019/01/01 2019/01/01
(a) $1 @ 2 = $1 @ 2 (a) $1 @ EUR2 = $1 @ EUR2
Transaction prices Transaction prices
Within a transaction, you can note an amount's price in another commod- 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: 1. Write the price per unit, as @ UNITPRICE after the amount:
2009/1/1 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 assets:dollars ; balancing amount is -$135.00
2. Write the total price, as @@ TOTALPRICE after the amount: 2. Write the total price, as @@ TOTALPRICE after the amount:
2009/1/1 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 assets:dollars
3. Specify amounts for all postings, using exactly two commodities, and 3. Specify amounts for all postings, using exactly two commodities, and
let hledger infer the price that balances the transaction: let hledger infer the price that balances the transaction:
2009/1/1 2009/1/1
assets:euros 100 ; one hundred euros purchased assets:euros EUR100 ; one hundred euros purchased
assets:dollars $-135 ; for $135 assets:dollars $-135 ; for $135
(Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT- (Ledger users: Ledger uses a different syntax for fixed prices, {=UNIT-
@ -557,7 +557,7 @@ FILE FORMAT
$ hledger bal -N --flat $ hledger bal -N --flat
$-135 assets:dollars $-135 assets:dollars
100 assets:euros EUR100 assets:euros
$ hledger bal -N --flat -B $ hledger bal -N --flat -B
$-135 assets:dollars $-135 assets:dollars
$135 assets:euros # <- the euros' cost $135 assets:euros # <- the euros' cost
@ -569,11 +569,11 @@ FILE FORMAT
2009/1/1 2009/1/1
assets:dollars $-135 ; 135 dollars sold assets:dollars $-135 ; 135 dollars sold
assets:euros 100 ; for 100 euros assets:euros EUR100 ; for 100 euros
$ hledger bal -N --flat -B $ hledger bal -N --flat -B
-100 assets:dollars # <- the dollars' selling price EUR-100 assets:dollars # <- the dollars' selling price
100 assets:euros EUR100 assets:euros
Comments Comments
Lines in the journal beginning with a semicolon (;) or hash (#) or star Lines in the journal beginning with a semicolon (;) or hash (#) or star
@ -608,8 +608,8 @@ FILE FORMAT
; another comment line for posting 2 ; another comment line for posting 2
; a file comment (because not indented) ; a file comment (because not indented)
You can also comment larger regions of a file using comment and You can also comment larger regions of a file using comment and end
end comment directives. comment directives.
Tags Tags
Tags are a way to add extra labels or labelled data to postings and Tags are a way to add extra labels or labelled data to postings and
@ -641,8 +641,8 @@ FILE FORMAT
Tags in a transaction comment affect the transaction and all of its Tags in a transaction comment affect the transaction and all of its
postings, while tags in a posting comment affect only that posting. postings, while tags in a posting comment affect only that posting.
For example, the following transaction has three tags (A, TAG2, For example, the following transaction has three tags (A, TAG2, third-
third-tag) and the posting has four (those plus posting-tag): tag) and the posting has four (those plus posting-tag):
1/1 a transaction ; A:, TAG2: 1/1 a transaction ; A:, TAG2:
; third-tag: a third transaction tag, <- with a value ; third-tag: a third transaction tag, <- with a value
@ -665,7 +665,7 @@ FILE FORMAT
direc- end subdi- purpose can affect (as of direc- end subdi- purpose can affect (as of
tive directive rec- 2018/06) tive directive rec- 2018/06)
tives tives
------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------
account any document account names, all entries in all account any document account names, all entries in all
text declare account types & dis- files, before or text declare account types & dis- files, before or
play order after play order after
@ -673,23 +673,23 @@ FILE FORMAT
alias end aliases rewrite account names following alias end rewrite account names following
inline/included aliases inline/included
entries until end entries until end
of current file or of current file or
end directive end directive
apply account end apply account prepend a common parent to following apply end apply prepend a common parent to following
account names inline/included account account account names inline/included
entries until end entries until end
of current file or of current file or
end directive end directive
comment end comment ignore part of journal following comment end com- ignore part of journal following
inline/included ment inline/included
entries until end entries until end
of current file or of current file or
end directive end directive
commodity format declare a commodity and its number notation: commod- format declare a commodity and its number notation:
number notation & display following entries ity number notation & display following entries
style in that commodity style in that commodity
in all files; dis- in all files; dis-
play style: amounts play style: amounts
@ -853,8 +853,8 @@ FILE FORMAT
These two market price directives say that one euro was worth 1.35 US These two market price directives say that one euro was worth 1.35 US
dollars during 2009, and $1.40 from 2010 onward: dollars during 2009, and $1.40 from 2010 onward:
P 2009/1/1 $1.35 P 2009/1/1 EUR $1.35
P 2010/1/1 $1.40 P 2010/1/1 EUR $1.40
The -V/--value flag can be used to convert reported amounts to another The -V/--value flag can be used to convert reported amounts to another
commodity using these prices. commodity using these prices.
@ -876,8 +876,8 @@ FILE FORMAT
o They control account display order in reports, allowing non-alpha- o They control account display order in reports, allowing non-alpha-
betic sorting (eg Revenues to appear above Expenses). betic sorting (eg Revenues to appear above Expenses).
o They help with account name completion in the add command, o They help with account name completion in the add command, hledger-
hledger-iadd, hledger-web, ledger-mode etc. iadd, hledger-web, ledger-mode etc.
The simplest form is just the word account followed by a hledger-style The simplest form is just the word account followed by a hledger-style
account name, eg: account name, eg:
@ -1005,8 +1005,8 @@ FILE FORMAT
o customising reports o customising reports
Account aliases also rewrite account names in account directives. They Account aliases also rewrite account names in account directives. They
do not affect account names being entered via hledger add or do not affect account names being entered via hledger add or hledger-
hledger-web. web.
See also Cookbook: Rewrite account names. See also Cookbook: Rewrite account names.
@ -1048,11 +1048,11 @@ FILE FORMAT
space. space.
Multiple aliases Multiple aliases
You can define as many aliases as you like using directives or com- You can define as many aliases as you like using directives or command-
mand-line options. Aliases are recursive - each alias sees the result line options. Aliases are recursive - each alias sees the result of
of applying previous ones. (This is different from Ledger, where applying previous ones. (This is different from Ledger, where aliases
aliases are non-recursive by default). Aliases are applied in the fol- are non-recursive by default). Aliases are applied in the following
lowing order: order:
1. alias directives, most recently seen first (recent directives take 1. alias directives, most recently seen first (recent directives take
precedence over earlier ones; directives not yet seen are ignored) 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 2. alias options, in the order they appear on the command line
end aliases end aliases
You can clear (forget) all currently defined aliases with the You can clear (forget) all currently defined aliases with the end
end aliases directive: aliases directive:
end aliases end aliases
@ -1116,8 +1116,8 @@ FILE FORMAT
assets:bank:checking assets:bank:checking
There is an additional constraint on the period expression: the start There is an additional constraint on the period expression: the start
date must fall on a natural boundary of the interval. Eg date must fall on a natural boundary of the interval. Eg monthly from
monthly from 2018/1/1 is valid, but monthly from 2018/1/15 is not. 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 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 expression can work (useful or not). They will be relative to today's
@ -1188,25 +1188,25 @@ FILE FORMAT
and Forecasting. and Forecasting.
Transaction modifiers Auto postings / transaction modifiers
Transaction modifier rules describe changes that should be applied Transaction modifier rules describe changes to be applied automatically
automatically to certain transactions. They can be enabled by using to certain matched transactions. Currently just one kind of change is
the --auto flag. Currently, just one kind of change is possible: possible - adding extra postings, which we call "automated postings" or
adding extra postings. These rule-generated postings are known as just "auto postings". These rules become active when you use the
"automated postings" or "auto postings". --auto flag.
A transaction modifier rule looks quite like a normal transaction, A transaction modifier, AKA auto posting rule, looks much like a normal
except the first line is an equals sign followed by a query that transaction except the first line is an equals sign followed by a query
matches certain postings (mnemonic: = suggests matching). And each that matches certain postings (mnemonic: = suggests matching). And
"posting" is actually a posting-generating rule: each "posting" is actually a posting-generating rule:
= QUERY = QUERY
ACCT AMT ACCT AMT
ACCT [AMT] ACCT [AMT]
... ...
These posting rules look like normal postings, except the amount can These posting-generating rules look like normal postings, except the
be: amount can be:
o a normal amount with a commodity symbol, eg $2. This will be used o a normal amount with a commodity symbol, eg $2. This will be used
as-is. as-is.
@ -1222,6 +1222,10 @@ FILE FORMAT
symbol S). The matched posting's amount will be multiplied by N, and symbol S). The matched posting's amount will be multiplied by N, and
its commodity symbol will be replaced with S. 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: Some examples:
; every time I buy food, schedule a dollar donation ; every time I buy food, schedule a dollar donation
@ -1253,9 +1257,8 @@ FILE FORMAT
assets:checking:gifts -$20 assets:checking:gifts -$20
assets:checking $20 assets:checking $20
Auto postings and transaction balancing / inferred amounts / balance Auto postings and transaction balancing / inferred amounts / balance asser-
assertions tions
Currently, transaction modifiers are applied / auto postings are added: Currently, transaction modifiers are applied / auto postings are added:
o after missing amounts are inferred, and transactions are checked for o after missing amounts are inferred, and transactions are checked for
@ -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 .SH NAME
.PP .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 .SH DESCRIPTION
.PP .PP
hledger can read timeclock files. hledger can read timeclock files.
As with Ledger, these are (a subset of) timeclock.el\[aq]s format, 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 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. Seconds and timezone are optional.
The timezone, if present, must be four digits and is ignored (currently The timezone, if present, must be four digits and is ignored (currently
the time is always interpreted as a local time). the time is always interpreted as a local time).
.IP .IP
.nf .nf
\f[C] \f[C]
i\ 2015/03/30\ 09:00:00\ some:account\ name\ \ optional\ description\ after\ two\ spaces i 2015/03/30 09:00:00 some:account name optional description after two spaces
o\ 2015/03/30\ 09:20:00 o 2015/03/30 09:20:00
i\ 2015/03/31\ 22:21:45\ another\ account i 2015/03/31 22:21:45 another account
o\ 2015/04/01\ 02:00:34 o 2015/04/01 02:00:34
\f[] \f[R]
.fi .fi
.PP .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. some number of hours to an account.
Or if the session spans more than one day, it is split into several Or if the session spans more than one day, it is split into several
transactions, one for each day. 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: entries:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ \-f\ t.timeclock\ print $ hledger -f t.timeclock print
2015/03/30\ *\ optional\ description\ after\ two\ spaces 2015/03/30 * optional description after two spaces
\ \ \ \ (some:account\ name)\ \ \ \ \ \ \ \ \ 0.33h (some:account name) 0.33h
2015/03/31\ *\ 22:21\-23:59 2015/03/31 * 22:21-23:59
\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 1.64h (another account) 1.64h
2015/04/01\ *\ 00:00\-02:00 2015/04/01 * 00:00-02:00
\ \ \ \ (another\ account)\ \ \ \ \ \ \ \ \ 2.01h (another account) 2.01h
\f[] \f[R]
.fi .fi
.PP .PP
Here is a sample.timeclock to download and some queries to try: Here is a sample.timeclock to download and some queries to try:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ \-f\ sample.timeclock\ balance\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ #\ current\ time\ balances $ 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 2009/3 # sessions in march 2009
$\ hledger\ \-f\ sample.timeclock\ register\ \-p\ weekly\ \-\-depth\ 1\ \-\-empty\ \ #\ time\ summary\ by\ week $ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week
\f[] \f[R]
.fi .fi
.PP .PP
To generate time logs, ie to clock in and clock out, you could: To generate time logs, ie to clock in and clock out, you could:
.IP \[bu] 2 .IP \[bu] 2
use emacs and the built\-in timeclock.el, or the extended use emacs and the built-in timeclock.el, or the extended timeclock-x.el
timeclock\-x.el and perhaps the extras in ledgerutils.el and perhaps the extras in ledgerutils.el
.IP \[bu] 2 .IP \[bu] 2
at the command line, use these bash aliases: 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 .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. repository.
These rely on a "timeclock" executable which I think is just the ledger These rely on a \[dq]timeclock\[dq] executable which I think is just the
2 executable renamed. ledger 2 executable renamed.
.SH "REPORTING BUGS" .SH "REPORTING BUGS"

5
hledger-lib/hledger_timeclock.info
View File

@ -4,8 +4,8 @@ stdin.
 
File: hledger_timeclock.info, Node: Top, Up: (dir) 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 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 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 * 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 i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o
`date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"' `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"'
* or use the old 'ti' and 'to' scripts in the ledger 2.x repository. * 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 These rely on a "timeclock" executable which I think is just the
ledger 2 executable renamed. 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: 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- o use emacs and the built-in timeclock.el, or the extended timeclock-
clock-x.el and perhaps the extras in ledgerutils.el x.el and perhaps the extras in ledgerutils.el
o at the command line, use these bash aliases: o at the command line, use these bash aliases: shell alias ti="echo i
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" `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 o or use the old ti and to scripts in the ledger 2.x repository. These
rely on a "timeclock" executable which I think is just the ledger 2 rely on a "timeclock" executable which I think is just the ledger 2
@ -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 .SH NAME
.PP .PP
Timedot \- hledger\[aq]s human\-friendly time logging format Timedot - hledger\[aq]s human-friendly time logging format
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
Timedot is a plain text format for logging dated, categorised quantities Timedot is a plain text format for logging dated, categorised quantities
(of time, usually), supported by hledger. (of time, usually), supported by hledger.
It is convenient for approximate and retroactive time logging, eg when It is convenient for approximate and retroactive time logging, eg when
the real\-time clock\-in/out required with a timeclock file is too the real-time clock-in/out required with a timeclock file is too precise
precise or too interruptive. or too interruptive.
It can be formatted like a bar chart, making clear at a glance where It can be formatted like a bar chart, making clear at a glance where
time was spent. time was spent.
.PP .PP
Though called "timedot", this format is read by hledger as commodityless Though called \[dq]timedot\[dq], this format is read by hledger as
quantities, so it could be used to represent dated quantities other than commodityless quantities, so it could be used to represent dated
time. quantities other than time.
In the docs below we\[aq]ll assume it\[aq]s time. In the docs below we\[aq]ll assume it\[aq]s time.
.SH FILE FORMAT .SH FILE FORMAT
.PP .PP
A timedot file contains a series of day entries. A timedot file contains a series of day entries.
A day entry begins with a date, and is followed by category/quantity A day entry begins with a date, and is followed by category/quantity
pairs, one per line. pairs, one per line.
Dates are hledger\-style simple dates (see hledger_journal(5)). Dates are hledger-style simple dates (see hledger_journal(5)).
Categories are hledger\-style account names, optionally indented. Categories are hledger-style account names, optionally indented.
As in a hledger journal, there must be at least two spaces between the As in a hledger journal, there must be at least two spaces between the
category (account name) and the quantity. category (account name) and the quantity.
.PP .PP
@ -41,9 +41,9 @@ an integral or decimal number, representing hours.
Eg: 1.5 Eg: 1.5
.IP \[bu] 2 .IP \[bu] 2
an integral or decimal number immediately followed by a unit symbol 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[], \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],
or \f[C]y\f[], representing seconds, minutes, hours, days weeks, months \f[C]mo\f[R], or \f[C]y\f[R], representing seconds, minutes, hours, days
or years respectively. weeks, months or years respectively.
Eg: 90m. Eg: 90m.
The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m, The following equivalencies are assumed, currently: 1m = 60s, 1h = 60m,
1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d. 1d = 24h, 1w = 7d, 1mo = 30d, 1y=365d.
@ -53,16 +53,16 @@ An example:
.IP .IP
.nf .nf
\f[C] \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 2016/2/1
inc:client1\ \ \ ....\ ....\ ....\ ....\ ....\ .... inc:client1 .... .... .... .... .... ....
fos:haskell\ \ \ ....\ ..\ fos:haskell .... ..
biz:research\ \ . biz:research .
2016/2/2 2016/2/2
inc:client1\ \ \ ....\ .... inc:client1 .... ....
biz:research\ \ . biz:research .
\f[] \f[R]
.fi .fi
.PP .PP
Or with numbers: Or with numbers:
@ -70,42 +70,42 @@ Or with numbers:
.nf .nf
\f[C] \f[C]
2016/2/3 2016/2/3
inc:client1\ \ \ 4 inc:client1 4
fos:hledger\ \ \ 3 fos:hledger 3
biz:research\ \ 1 biz:research 1
\f[] \f[R]
.fi .fi
.PP .PP
Reporting: Reporting:
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ \-f\ t.timedot\ print\ date:2016/2/2 $ hledger -f t.timedot print date:2016/2/2
2016/02/02\ * 2016/02/02 *
\ \ \ \ (inc:client1)\ \ \ \ \ \ \ \ \ \ 2.00 (inc:client1) 2.00
2016/02/02\ * 2016/02/02 *
\ \ \ \ (biz:research)\ \ \ \ \ \ \ \ \ \ 0.25 (biz:research) 0.25
\f[] \f[R]
.fi .fi
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ \-f\ t.timedot\ bal\ \-\-daily\ \-\-tree $ hledger -f t.timedot bal --daily --tree
Balance\ changes\ in\ 2016/02/01\-2016/02/03: 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\ biz || 0.25 0.25 1.00
\ \ \ research\ ||\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 0.25\ \ \ \ \ \ \ \ \ 1.00\ research || 0.25 0.25 1.00
\ fos\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\ fos || 1.50 0 3.00
\ \ \ haskell\ \ ||\ \ \ \ \ \ \ \ \ 1.50\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ haskell || 1.50 0 0
\ \ \ hledger\ \ ||\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ \ \ \ 0\ \ \ \ \ \ \ \ \ 3.00\ hledger || 0 0 3.00
\ inc\ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\ inc || 6.00 2.00 4.00
\ \ \ client1\ \ ||\ \ \ \ \ \ \ \ \ 6.00\ \ \ \ \ \ \ \ \ 2.00\ \ \ \ \ \ \ \ \ 4.00\ client1 || 6.00 2.00 4.00
\-\-\-\-\-\-\-\-\-\-\-\-++\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- ------------++----------------------------------------
\ \ \ \ \ \ \ \ \ \ \ \ ||\ \ \ \ \ \ \ \ \ 7.75\ \ \ \ \ \ \ \ \ 2.25\ \ \ \ \ \ \ \ \ 8.00\ || 7.75 2.25 8.00
\f[] \f[R]
.fi .fi
.PP .PP
I prefer to use period for separating account components. I prefer to use period for separating account components.
@ -114,20 +114,20 @@ We can make this work with an account alias:
.nf .nf
\f[C] \f[C]
2016/2/4 2016/2/4
fos.hledger.timedot\ \ 4 fos.hledger.timedot 4
fos.ledger\ \ \ \ \ \ \ \ \ \ \ .. fos.ledger ..
\f[] \f[R]
.fi .fi
.IP .IP
.nf .nf
\f[C] \f[C]
$\ hledger\ \-f\ t.timedot\ \-\-alias\ /\\\\./=:\ bal\ date:2016/2/4 $ hledger -f t.timedot --alias /\[rs]\[rs]./=: bal date:2016/2/4
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50\ \ fos 4.50 fos
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.00\ \ \ \ hledger:timedot 4.00 hledger:timedot
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 0.50\ \ \ \ ledger 0.50 ledger
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --------------------
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 4.50 4.50
\f[] \f[R]
.fi .fi
.PP .PP
Here is a sample.timedot. 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) 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 Timedot is a plain text format for logging dated, categorised quantities
(of time, usually), supported by hledger. It is convenient for (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 Though called "timedot", this format is read by hledger as
commodityless quantities, so it could be used to represent dated commodityless quantities, so it could be used to represent dated
quantities other than time. In the docs below we'll assume it's time. quantities other than time. In the docs below we'll assume it's time.
* Menu: * Menu:
* FILE FORMAT:: * FILE FORMAT::
@ -110,7 +111,7 @@ $ hledger -f t.timedot --alias /\\./=: bal date:2016/2/4
 
Tag Table: Tag Table:
Node: Top76 Node: Top76
Node: FILE FORMAT807 Node: FILE FORMAT814
Ref: #file-format908 Ref: #file-format915
 
End Tag Table End Tag Table

10
hledger-lib/hledger_timedot.txt
View File

@ -9,10 +9,10 @@ NAME
DESCRIPTION DESCRIPTION
Timedot is a plain text format for logging dated, categorised quanti- Timedot is a plain text format for logging dated, categorised quanti-
ties (of time, usually), supported by hledger. It is convenient for ties (of time, usually), supported by hledger. It is convenient for
approximate and retroactive time logging, eg when the real-time approximate and retroactive time logging, eg when the real-time clock-
clock-in/out required with a timeclock file is too precise or too in/out required with a timeclock file is too precise or too interrup-
interruptive. It can be formatted like a bar chart, making clear at a tive. It can be formatted like a bar chart, making clear at a glance
glance where time was spent. where time was spent.
Though called "timedot", this format is read by hledger as commodity- Though called "timedot", this format is read by hledger as commodity-
less quantities, so it could be used to represent dated quantities 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 .SH NAME
.PP .PP
hledger\-ui \- curses\-style interface for the hledger accounting tool hledger-ui - curses-style interface for the hledger accounting tool
.SH SYNOPSIS .SH SYNOPSIS
.PP .PP
\f[C]hledger\-ui\ [OPTIONS]\ [QUERYARGS]\f[] \f[C]hledger-ui [OPTIONS] [QUERYARGS]\f[R]
.PD 0 .PD 0
.P .P
.PD .PD
\f[C]hledger\ ui\ \-\-\ [OPTIONS]\ [QUERYARGS]\f[] \f[C]hledger ui -- [OPTIONS] [QUERYARGS]\f[R]
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
hledger is a cross\-platform program for tracking money, time, or any hledger is a cross-platform program for tracking money, time, or any
other commodity, using double\-entry accounting and a simple, editable other commodity, using double-entry accounting and a simple, editable
file format. file format.
hledger is inspired by and largely compatible with ledger(1). hledger is inspired by and largely compatible with ledger(1).
.PP .PP
hledger\-ui is hledger\[aq]s curses\-style interface, providing an hledger-ui is hledger\[aq]s curses-style interface, providing an
efficient full\-window text UI for viewing accounts and transactions, efficient full-window text UI for viewing accounts and transactions, and
and some limited data entry capability. some limited data entry capability.
It is easier than hledger\[aq]s command\-line interface, and sometimes It is easier than hledger\[aq]s command-line interface, and sometimes
quicker and more convenient than the web interface. quicker and more convenient than the web interface.
.PP .PP
Note hledger\-ui has some different defaults (experimental): Note hledger-ui has some different defaults (experimental):
.IP \[bu] 2 .IP \[bu] 2
it generates rule\-based transactions and postings by default it generates rule-based transactions and postings by default (--forecast
(\-\-forecast and \-\-auto are always on). and --auto are always on).
.IP \[bu] 2 .IP \[bu] 2
it hides transactions dated in the future by default (change this with it hides transactions dated in the future by default (change this with
\-\-future or the F key). --future or the F key).
.PP .PP
Like hledger, it reads data from one or more files in hledger journal, 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 timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, \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[]). perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1), hledger_journal(5) etc. For more about this see hledger(1), hledger_journal(5) etc.
.SH OPTIONS .SH OPTIONS
.PP .PP
Note: if invoking hledger\-ui as a hledger subcommand, write Note: if invoking hledger-ui as a hledger subcommand, write \f[C]--\f[R]
\f[C]\-\-\f[] before options as shown above. before options as shown above.
.PP .PP
Any QUERYARGS are interpreted as a hledger search query which filters Any QUERYARGS are interpreted as a hledger search query which filters
the data. the data.
.TP .TP
.B \f[C]\-\-watch\f[] .B \f[C]--watch\f[R]
watch for data and date changes and reload automatically watch for data and date changes and reload automatically
.RS
.RE
.TP .TP
.B \f[C]\-\-theme=default|terminal|greenterm\f[] .B \f[C]--theme=default|terminal|greenterm\f[R]
use this custom display theme use this custom display theme
.RS
.RE
.TP .TP
.B \f[C]\-\-register=ACCTREGEX\f[] .B \f[C]--register=ACCTREGEX\f[R]
start in the (first) matched account\[aq]s register screen start in the (first) matched account\[aq]s register screen
.RS
.RE
.TP .TP
.B \f[C]\-\-change\f[] .B \f[C]--change\f[R]
show period balances (changes) at startup instead of historical balances show period balances (changes) at startup instead of historical balances
.RS
.RE
.TP .TP
.B \f[C]\-F\ \-\-flat\f[] .B \f[C]-F --flat\f[R]
show accounts as a list (default) show accounts as a list (default)
.RS
.RE
.TP .TP
.B \f[C]\-T\ \-\-tree\f[] .B \f[C]-T --tree\f[R]
show accounts as a tree show accounts as a tree
.RS
.RE
.TP .TP
.B \f[C]\-\-future\f[] .B \f[C]--future\f[R]
show transactions dated later than today (normally hidden) show transactions dated later than today (normally hidden)
.RS
.RE
.PP .PP
hledger input options: hledger input options:
.TP .TP
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] .B \f[C]-f FILE --file=FILE\f[R]
use a different input file. use a different input file.
For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
\f[C]$HOME/.hledger.journal\f[]) \f[C]$HOME/.hledger.journal\f[R])
.RS
.RE
.TP .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) Conversion rules file to use when reading CSV (default: FILE.rules)
.RS
.RE
.TP .TP
.B \f[C]\-\-separator=CHAR\f[] .B \f[C]--separator=CHAR\f[R]
Field separator to expect when reading CSV (default: \[aq],\[aq]) Field separator to expect when reading CSV (default: \[aq],\[aq])
.RS
.RE
.TP .TP
.B \f[C]\-\-alias=OLD=NEW\f[] .B \f[C]--alias=OLD=NEW\f[R]
rename accounts named OLD to NEW rename accounts named OLD to NEW
.RS
.RE
.TP .TP
.B \f[C]\-\-anon\f[] .B \f[C]--anon\f[R]
anonymize accounts and payees anonymize accounts and payees
.RS
.RE
.TP .TP
.B \f[C]\-\-pivot\ FIELDNAME\f[] .B \f[C]--pivot FIELDNAME\f[R]
use some other field or tag for the account name use some other field or tag for the account name
.RS
.RE
.TP .TP
.B \f[C]\-I\ \-\-ignore\-assertions\f[] .B \f[C]-I --ignore-assertions\f[R]
ignore any failing balance assertions ignore any failing balance assertions
.RS
.RE
.PP .PP
hledger reporting options: hledger reporting options:
.TP .TP
.B \f[C]\-b\ \-\-begin=DATE\f[] .B \f[C]-b --begin=DATE\f[R]
include postings/txns on or after this date include postings/txns on or after this date
.RS
.RE
.TP .TP
.B \f[C]\-e\ \-\-end=DATE\f[] .B \f[C]-e --end=DATE\f[R]
include postings/txns before this date include postings/txns before this date
.RS
.RE
.TP .TP
.B \f[C]\-D\ \-\-daily\f[] .B \f[C]-D --daily\f[R]
multiperiod/multicolumn report by day multiperiod/multicolumn report by day
.RS
.RE
.TP .TP
.B \f[C]\-W\ \-\-weekly\f[] .B \f[C]-W --weekly\f[R]
multiperiod/multicolumn report by week multiperiod/multicolumn report by week
.RS
.RE
.TP .TP
.B \f[C]\-M\ \-\-monthly\f[] .B \f[C]-M --monthly\f[R]
multiperiod/multicolumn report by month multiperiod/multicolumn report by month
.RS
.RE
.TP .TP
.B \f[C]\-Q\ \-\-quarterly\f[] .B \f[C]-Q --quarterly\f[R]
multiperiod/multicolumn report by quarter multiperiod/multicolumn report by quarter
.RS
.RE
.TP .TP
.B \f[C]\-Y\ \-\-yearly\f[] .B \f[C]-Y --yearly\f[R]
multiperiod/multicolumn report by year multiperiod/multicolumn report by year
.RS
.RE
.TP .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 set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above) period expressions syntax (overrides the flags above)
.RS
.RE
.TP .TP
.B \f[C]\-\-date2\f[] .B \f[C]--date2\f[R]
match the secondary date instead (see command help for other effects) match the secondary date instead (see command help for other effects)
.RS
.RE
.TP .TP
.B \f[C]\-U\ \-\-unmarked\f[] .B \f[C]-U --unmarked\f[R]
include only unmarked postings/txns (can combine with \-P or \-C) include only unmarked postings/txns (can combine with -P or -C)
.RS
.RE
.TP .TP
.B \f[C]\-P\ \-\-pending\f[] .B \f[C]-P --pending\f[R]
include only pending postings/txns include only pending postings/txns
.RS
.RE
.TP .TP
.B \f[C]\-C\ \-\-cleared\f[] .B \f[C]-C --cleared\f[R]
include only cleared postings/txns include only cleared postings/txns
.RS
.RE
.TP .TP
.B \f[C]\-R\ \-\-real\f[] .B \f[C]-R --real\f[R]
include only non\-virtual postings include only non-virtual postings
.RS
.RE
.TP .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 hide/aggregate accounts or postings more than NUM levels deep
.RS
.RE
.TP .TP
.B \f[C]\-E\ \-\-empty\f[] .B \f[C]-E --empty\f[R]
show items with zero amount, normally hidden (and vice\-versa in show items with zero amount, normally hidden (and vice-versa in
hledger\-ui/hledger\-web) hledger-ui/hledger-web)
.RS
.RE
.TP .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 convert amounts to their cost at transaction time (using the transaction
price, if any) price, if any)
.RS
.RE
.TP .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 convert amounts to their market value on the report end date (using the
most recent applicable market price, if any) most recent applicable market price, if any)
.RS
.RE
.TP .TP
.B \f[C]\-\-auto\f[] .B \f[C]--auto\f[R]
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
.RS
.RE
.TP .TP
.B \f[C]\-\-forecast\f[] .B \f[C]--forecast\f[R]
apply periodic transaction rules to generate future transactions, to 6 apply periodic transaction rules to generate future transactions, to 6
months from now or report end date. months from now or report end date.
.RS
.RE
.PP .PP
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
last one takes precedence. last one takes precedence.
@ -230,38 +164,33 @@ Some reporting options can also be written as query arguments.
.PP .PP
hledger help options: hledger help options:
.TP .TP
.B \f[C]\-h\ \-\-help\f[] .B \f[C]-h --help\f[R]
show general usage (or after COMMAND, command usage) show general usage (or after COMMAND, command usage)
.RS
.RE
.TP .TP
.B \f[C]\-\-version\f[] .B \f[C]--version\f[R]
show version show version
.RS
.RE
.TP .TP
.B \f[C]\-\-debug[=N]\f[] .B \f[C]--debug[=N]\f[R]
show debug output (levels 1\-9, default: 1) show debug output (levels 1-9, default: 1)
.RS
.RE
.PP .PP
A \@FILE argument will be expanded to the contents of FILE, which should A \[at]FILE argument will be expanded to the contents of FILE, which
contain one command line option/argument per line. should contain one command line option/argument per line.
(To prevent this, insert a \f[C]\-\-\f[] argument before.) (To prevent this, insert a \f[C]--\f[R] argument before.)
.SH KEYS .SH KEYS
.PP .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 (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[]) screen.) Press \f[C]?\f[R] again (or \f[C]ESCAPE\f[R], or
to close it. \f[C]LEFT\f[R]) to close it.
The following keys work on most screens: The following keys work on most screens:
.PP .PP
The cursor keys navigate: \f[C]right\f[] (or \f[C]enter\f[]) goes The cursor keys navigate: \f[C]right\f[R] (or \f[C]enter\f[R]) goes
deeper, \f[C]left\f[] returns to the previous screen, deeper, \f[C]left\f[R] 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[] \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. 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 Vi-style (\f[C]h\f[R]/\f[C]j\f[R]/\f[C]k\f[R]/\f[C]l\f[R]) and
(\f[C]CTRL\-p\f[]/\f[C]CTRL\-n\f[]/\f[C]CTRL\-f\f[]/\f[C]CTRL\-b\f[]) 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. movement keys are also supported.
A tip: movement speed is limited by your keyboard repeat rate, to move A tip: movement speed is limited by your keyboard repeat rate, to move
faster you may want to adjust it. faster you may want to adjust it.
@ -269,67 +198,67 @@ faster you may want to adjust it.
.PP .PP
With shift pressed, the cursor keys adjust the report period, limiting With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown). 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. report period durations: year, quarter, month, week, day.
Then, \f[C]shift\-left/right\f[] moves to the previous/next period. Then, \f[C]shift-left/right\f[R] moves to the previous/next period.
\f[C]t\f[] sets the report period to today. \f[C]t\f[R] sets the report period to today.
With the \f[C]\-\-watch\f[] option, when viewing a "current" period (the With the \f[C]--watch\f[R] option, when viewing a \[dq]current\[dq]
current day, week, month, quarter, or year), the period will move period (the current day, week, month, quarter, or year), the period will
automatically to track the current date. move automatically to track the current date.
To set a non\-standard period, you can use \f[C]/\f[] and a To set a non-standard period, you can use \f[C]/\f[R] and a
\f[C]date:\f[] query. \f[C]date:\f[R] query.
.PP .PP
\f[C]/\f[] lets you set a general filter query limiting the data shown, \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. 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; 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. 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 There are also keys for quickly adjusting some common filters like
account depth and transaction status (see below). 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. transactions.
.PP .PP
As mentioned above, hledger\-ui shows auto\-generated periodic As mentioned above, hledger-ui shows auto-generated periodic
transactions, and hides future transactions (auto\-generated or not) by transactions, and hides future transactions (auto-generated or not) by
default. default.
\f[C]F\f[] toggles showing and hiding these future transactions. \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[], but more This is similar to using a query like \f[C]date:-tomorrow\f[R], but more
convenient. convenient.
(experimental) (experimental)
.PP .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. Or, it cancels a minibuffer edit or help dialog in progress.
.PP .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 possible (selections near the top won\[aq]t be centered, since we
don\[aq]t scroll above the top). don\[aq]t scroll above the top).
.PP .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. and any previous screens.
(With large files, this could cause a noticeable pause.) (With large files, this could cause a noticeable pause.)
.PP .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 Disabling balance assertions temporarily can be useful for
troubleshooting. troubleshooting.
.PP .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. updated file.
This allows some basic data entry. This allows some basic data entry.
.PP .PP
\f[C]A\f[] is like \f[C]a\f[], but runs the hledger\-iadd tool, which \f[C]A\f[R] is like \f[C]a\f[R], but runs the hledger-iadd tool, which
provides a curses\-style interface. provides a curses-style interface.
This key will be available if \f[C]hledger\-iadd\f[] is installed in This key will be available if \f[C]hledger-iadd\f[R] is installed in
$PATH. $PATH.
.PP .PP
\f[C]E\f[] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default \f[C]E\f[R] runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default
(\f[C]emacsclient\ \-a\ ""\ \-nw\f[]) on the journal file. (\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 With some editors (emacs, vi), the cursor will be positioned at the
current transaction when invoked from the register and transaction current transaction when invoked from the register and transaction
screens, and at the error location (if possible) when invoked from the screens, and at the error location (if possible) when invoked from the
error screen. error screen.
.PP .PP
\f[C]q\f[] quits the application. \f[C]q\f[R] quits the application.
.PP .PP
Additional screen\-specific keys are described below. Additional screen-specific keys are described below.
.SH SCREENS .SH SCREENS
.SS Accounts screen .SS Accounts screen
.PP .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. accounts and the balances from matched transactions.
.PP .PP
Account names are shown as a flat list by default. 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 In flat mode, account balances are exclusive of subaccounts, except
where subaccounts are hidden by a depth limit (see below). where subaccounts are hidden by a depth limit (see below).
In tree mode, all account balances are inclusive of subaccounts. In tree mode, all account balances are inclusive of subaccounts.
.PP .PP
To see less detail, press a number key, \f[C]1\f[] to \f[C]9\f[], to set To see less detail, press a number key, \f[C]1\f[R] to \f[C]9\f[R], to
a depth limit. set a depth limit.
Or use \f[C]\-\f[] to decrease and \f[C]+\f[]/\f[C]=\f[] to increase the Or use \f[C]-\f[R] to decrease and \f[C]+\f[R]/\f[C]=\f[R] to increase
depth limit. the depth limit.
\f[C]0\f[] shows even less detail, collapsing all accounts to a single \f[C]0\f[R] shows even less detail, collapsing all accounts to a single
total. total.
To remove the depth limit, set it higher than the maximum account depth, 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 .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. balances.
Historical balances (the default) are ending balances at the end of the Historical balances (the default) are ending balances at the end of the
report period, taking into account all transactions before that date 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 show the change in balance during the report period.
They are more useful eg when viewing a time log. They are more useful eg when viewing a time log.
.PP .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. 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. cleared postings.
(By default, balances include all postings; if you activate one or two (By default, balances include all postings; if you activate one or two
status filters, only those postings are included; and if you activate status filters, only those postings are included; and if you activate
all three, the filter is removed.) all three, the filter is removed.)
.PP .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 .PP
\f[C]Z\f[] toggles nonzero mode, in which only accounts with nonzero \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 balances are shown (hledger-ui shows zero items by default, unlike
command\-line hledger). command-line hledger).
.PP .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. transactions register.
.SS Register screen .SS Register screen
.PP .PP
@ -399,7 +328,7 @@ inflow to this account, negative for an outflow.
.IP \[bu] 2 .IP \[bu] 2
the running historical total or period total for the current account, the running historical total or period total for the current account,
after the transaction. 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 Similar to the accounts screen, the historical total is affected by
transactions (filtered by the filter query) before the report start transactions (filtered by the filter query) before the report start
date, while the period total is not. date, while the period total is not.
@ -416,23 +345,23 @@ to the balance shown on the accounts screen.
.PD 0 .PD 0
.P .P
.PD .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 .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. 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. toggles cleared transactions.
(By default, transactions with all statuses are shown; if you activate (By default, transactions with all statuses are shown; if you activate
one or two status filters, only those transactions are shown; and if you one or two status filters, only those transactions are shown; and if you
activate all three, the filter is removed.) activate all three, the filter is removed.)
.PP .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 .PP
\f[C]Z\f[] toggles nonzero mode, in which only transactions posting a \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, nonzero change are shown (hledger-ui shows zero items by default, unlike
unlike command\-line hledger). command-line hledger).
.PP .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. transaction in detail.
.SS Transaction screen .SS Transaction screen
.PP .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 Simple transactions have two postings, but there can be more (or in
certain cases, fewer). certain cases, fewer).
.PP .PP
\f[C]up\f[] and \f[C]down\f[] will step through all transactions listed \f[C]up\f[R] and \f[C]down\f[R] will step through all transactions
in the previous account register screen. listed in the previous account register screen.
In the title bar, the numbers in parentheses show your position within In the title bar, the numbers in parentheses show your position within
that account register. that account register.
They will vary depending on which account register you came from 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.) (Or, you can press escape to cancel the reload attempt.)
.SH ENVIRONMENT .SH ENVIRONMENT
.PP .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. Default: the full terminal width.
.PP .PP
\f[B]LEDGER_FILE\f[] The journal file path when not specified with \f[B]LEDGER_FILE\f[R] The journal file path when not specified with
\f[C]\-f\f[]. \f[C]-f\f[R].
Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[]). \f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH FILES .SH FILES
.PP .PP
Reads data from one or more files in hledger journal, timeclock, Reads data from one or more files in hledger journal, timeclock,
timedot, or CSV format specified with \f[C]\-f\f[], or timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, \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[]). perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH BUGS .SH BUGS
.PP .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. is awkward.
.PP .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 .PP
\f[C]\-V\f[] affects only the accounts screen. \f[C]-V\f[R] affects only the accounts screen.
.PP .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. regenerated, which may cause a noticeable pause with large files.
Also there is no visual indication that this is in progress. Also there is no visual indication that this is in progress.
.PP .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 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 (eg saving the file thousands of times with an editor macro) can cause
problems at least on OSX. problems at least on OSX.
Symptoms include: unresponsive UI, periodic resetting of the cursor Symptoms include: unresponsive UI, periodic resetting of the cursor
position, momentary display of parse errors, high CPU usage eventually position, momentary display of parse errors, high CPU usage eventually
subsiding, and possibly a small but persistent build\-up of CPU usage subsiding, and possibly a small but persistent build-up of CPU usage
until the program is restarted. until the program is restarted.

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) 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 hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some 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 '$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), 'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
hledger_journal(5) etc. hledger_journal(5) etc.
* Menu: * Menu:
* OPTIONS:: * OPTIONS::
@ -398,19 +399,19 @@ to cancel the reload attempt.)
 
Tag Table: Tag Table:
Node: Top71 Node: Top71
Node: OPTIONS1100 Node: OPTIONS1107
Ref: #options1197 Ref: #options1204
Node: KEYS4616 Node: KEYS4623
Ref: #keys4711 Ref: #keys4718
Node: SCREENS7967 Node: SCREENS7974
Ref: #screens8052 Ref: #screens8059
Node: Accounts screen8142 Node: Accounts screen8149
Ref: #accounts-screen8270 Ref: #accounts-screen8277
Node: Register screen10486 Node: Register screen10493
Ref: #register-screen10641 Ref: #register-screen10648
Node: Transaction screen12637 Node: Transaction screen12644
Ref: #transaction-screen12795 Ref: #transaction-screen12802
Node: Error screen13665 Node: Error screen13672
Ref: #error-screen13787 Ref: #error-screen13794
 
End Tag Table 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 hledger-ui is hledger's curses-style interface, providing an efficient
full-window text UI for viewing accounts and transactions, and some full-window text UI for viewing accounts and transactions, and some
limited data entry capability. It is easier than hledger's com- limited data entry capability. It is easier than hledger's command-
mand-line interface, and sometimes quicker and more convenient than the line interface, and sometimes quicker and more convenient than the web
web interface. interface.
Note hledger-ui has some different defaults (experimental): 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 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 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 down through lists. Vi-style (h/j/k/l) and Emacs-style (CTRL-p/CTRL-
(CTRL-p/CTRL-n/CTRL-f/CTRL-b) movement keys are also supported. A tip: n/CTRL-f/CTRL-b) movement keys are also supported. A tip: movement
movement speed is limited by your keyboard repeat rate, to move faster speed is limited by your keyboard repeat rate, to move faster you may
you may want to adjust it. (If you're on a mac, the Karabiner app is want to adjust it. (If you're on a mac, the Karabiner app is one way
one way to do that.) to do that.)
With shift pressed, the cursor keys adjust the report period, limiting With shift pressed, the cursor keys adjust the report period, limiting
the transactions to be shown (by default, all are shown). the transactions to be shown (by default, all are shown). shift-
shift-down/up steps downward and upward through these standard report down/up steps downward and upward through these standard report period
period durations: year, quarter, month, week, day. Then, durations: year, quarter, month, week, day. Then, shift-left/right
shift-left/right moves to the previous/next period. t sets the report moves to the previous/next period. t sets the report period to today.
period to today. With the --watch option, when viewing a "current" With the --watch option, when viewing a "current" period (the current
period (the current day, week, month, quarter, or year), the period day, week, month, quarter, or year), the period will move automatically
will move automatically to track the current date. To set a non-stan- to track the current date. To set a non-standard period, you can use /
dard period, you can use / and a date: query. and a date: query.
/ lets you set a general filter query limiting the data shown, using / 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 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 a runs command-line hledger's add command, and reloads the updated
file. This allows some basic data entry. file. This allows some basic data entry.
A is like a, but runs the hledger-iadd tool, which provides a A is like a, but runs the hledger-iadd tool, which provides a curses-
curses-style interface. This key will be available if hledger-iadd is style interface. This key will be available if hledger-iadd is
installed in $PATH. installed in $PATH.
E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emac- E runs $HLEDGER_UI_EDITOR, or $EDITOR, or a default (emacsclient -a ""
sclient -a "" -nw) on the journal file. With some editors (emacs, vi), -nw) on the journal file. With some editors (emacs, vi), the cursor
the cursor will be positioned at the current transaction when invoked will be positioned at the current transaction when invoked from the
from the register and transaction screens, and at the error location register and transaction screens, and at the error location (if possi-
(if possible) when invoked from the error screen. ble) when invoked from the error screen.
q quits the application. 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 .SH NAME
.PP .PP
hledger\-web \- web interface for the hledger accounting tool hledger-web - web interface for the hledger accounting tool
.SH SYNOPSIS .SH SYNOPSIS
.PP .PP
\f[C]hledger\-web\ [OPTIONS]\f[] \f[C]hledger-web [OPTIONS]\f[R]
.PD 0 .PD 0
.P .P
.PD .PD
\f[C]hledger\ web\ \-\-\ [OPTIONS]\f[] \f[C]hledger web -- [OPTIONS]\f[R]
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
hledger is a cross\-platform program for tracking money, time, or any hledger is a cross-platform program for tracking money, time, or any
other commodity, using double\-entry accounting and a simple, editable other commodity, using double-entry accounting and a simple, editable
file format. file format.
hledger is inspired by and largely compatible with ledger(1). hledger is inspired by and largely compatible with ledger(1).
.PP .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, It starts a simple web application for browsing and adding transactions,
and optionally opens it in a web browser window if possible. 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, 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. searching, and bookmarking.
.PP .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. the public web.
There is no access control, so if you need that you should put it behind There is no access control, so if you need that you should put it behind
a suitable web proxy. a suitable web proxy.
@ -37,201 +37,135 @@ instance, it writes a numbered backup of the main journal file (only ?)
on every edit. on every edit.
.PP .PP
Like hledger, it reads data from one or more files in hledger journal, 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 timeclock, timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, \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[]). perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
For more about this see hledger(1), hledger_journal(5) etc. For more about this see hledger(1), hledger_journal(5) etc.
.SH OPTIONS .SH OPTIONS
.PP .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. on the data.
These filter options are not shown in the web UI, but it will be applied These filter options are not shown in the web UI, but it will be applied
in addition to any search query entered there. in addition to any search query entered there.
.PP .PP
Note: if invoking hledger\-web as a hledger subcommand, write Note: if invoking hledger-web as a hledger subcommand, write
\f[C]\-\-\f[] before options, as shown in the synopsis above. \f[C]--\f[R] before options, as shown in the synopsis above.
.TP .TP
.B \f[C]\-\-serve\f[] .B \f[C]--serve\f[R]
serve and log requests, don\[aq]t browse or auto\-exit serve and log requests, don\[aq]t browse or auto-exit
.RS
.RE
.TP .TP
.B \f[C]\-\-host=IPADDR\f[] .B \f[C]--host=IPADDR\f[R]
listen on this IP address (default: 127.0.0.1) listen on this IP address (default: 127.0.0.1)
.RS
.RE
.TP .TP
.B \f[C]\-\-port=PORT\f[] .B \f[C]--port=PORT\f[R]
listen on this TCP port (default: 5000) listen on this TCP port (default: 5000)
.RS
.RE
.TP .TP
.B \f[C]\-\-base\-url=URL\f[] .B \f[C]--base-url=URL\f[R]
set the base url (default: http://IPADDR:PORT). set the base url (default: http://IPADDR:PORT).
You would change this when sharing over the network, or integrating You would change this when sharing over the network, or integrating
within a larger website. within a larger website.
.RS
.RE
.TP .TP
.B \f[C]\-\-file\-url=URL\f[] .B \f[C]--file-url=URL\f[R]
set the static files url (default: BASEURL/static). 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 serve them from another server for efficiency, you would set the url
with this. with this.
.RS
.RE
.TP .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) enable the view, add, and/or manage capabilities (default: view,add)
.RS
.RE
.TP .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 read capabilities to enable from a HTTP header, like
X\-Sandstorm\-Permissions (default: disabled) X-Sandstorm-Permissions (default: disabled)
.RS
.RE
.PP .PP
hledger input options: hledger input options:
.TP .TP
.B \f[C]\-f\ FILE\ \-\-file=FILE\f[] .B \f[C]-f FILE --file=FILE\f[R]
use a different input file. use a different input file.
For stdin, use \- (default: \f[C]$LEDGER_FILE\f[] or For stdin, use - (default: \f[C]$LEDGER_FILE\f[R] or
\f[C]$HOME/.hledger.journal\f[]) \f[C]$HOME/.hledger.journal\f[R])
.RS
.RE
.TP .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) Conversion rules file to use when reading CSV (default: FILE.rules)
.RS
.RE
.TP .TP
.B \f[C]\-\-separator=CHAR\f[] .B \f[C]--separator=CHAR\f[R]
Field separator to expect when reading CSV (default: \[aq],\[aq]) Field separator to expect when reading CSV (default: \[aq],\[aq])
.RS
.RE
.TP .TP
.B \f[C]\-\-alias=OLD=NEW\f[] .B \f[C]--alias=OLD=NEW\f[R]
rename accounts named OLD to NEW rename accounts named OLD to NEW
.RS
.RE
.TP .TP
.B \f[C]\-\-anon\f[] .B \f[C]--anon\f[R]
anonymize accounts and payees anonymize accounts and payees
.RS
.RE
.TP .TP
.B \f[C]\-\-pivot\ FIELDNAME\f[] .B \f[C]--pivot FIELDNAME\f[R]
use some other field or tag for the account name use some other field or tag for the account name
.RS
.RE
.TP .TP
.B \f[C]\-I\ \-\-ignore\-assertions\f[] .B \f[C]-I --ignore-assertions\f[R]
ignore any failing balance assertions ignore any failing balance assertions
.RS
.RE
.PP .PP
hledger reporting options: hledger reporting options:
.TP .TP
.B \f[C]\-b\ \-\-begin=DATE\f[] .B \f[C]-b --begin=DATE\f[R]
include postings/txns on or after this date include postings/txns on or after this date
.RS
.RE
.TP .TP
.B \f[C]\-e\ \-\-end=DATE\f[] .B \f[C]-e --end=DATE\f[R]
include postings/txns before this date include postings/txns before this date
.RS
.RE
.TP .TP
.B \f[C]\-D\ \-\-daily\f[] .B \f[C]-D --daily\f[R]
multiperiod/multicolumn report by day multiperiod/multicolumn report by day
.RS
.RE
.TP .TP
.B \f[C]\-W\ \-\-weekly\f[] .B \f[C]-W --weekly\f[R]
multiperiod/multicolumn report by week multiperiod/multicolumn report by week
.RS
.RE
.TP .TP
.B \f[C]\-M\ \-\-monthly\f[] .B \f[C]-M --monthly\f[R]
multiperiod/multicolumn report by month multiperiod/multicolumn report by month
.RS
.RE
.TP .TP
.B \f[C]\-Q\ \-\-quarterly\f[] .B \f[C]-Q --quarterly\f[R]
multiperiod/multicolumn report by quarter multiperiod/multicolumn report by quarter
.RS
.RE
.TP .TP
.B \f[C]\-Y\ \-\-yearly\f[] .B \f[C]-Y --yearly\f[R]
multiperiod/multicolumn report by year multiperiod/multicolumn report by year
.RS
.RE
.TP .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 set start date, end date, and/or reporting interval all at once using
period expressions syntax (overrides the flags above) period expressions syntax (overrides the flags above)
.RS
.RE
.TP .TP
.B \f[C]\-\-date2\f[] .B \f[C]--date2\f[R]
match the secondary date instead (see command help for other effects) match the secondary date instead (see command help for other effects)
.RS
.RE
.TP .TP
.B \f[C]\-U\ \-\-unmarked\f[] .B \f[C]-U --unmarked\f[R]
include only unmarked postings/txns (can combine with \-P or \-C) include only unmarked postings/txns (can combine with -P or -C)
.RS
.RE
.TP .TP
.B \f[C]\-P\ \-\-pending\f[] .B \f[C]-P --pending\f[R]
include only pending postings/txns include only pending postings/txns
.RS
.RE
.TP .TP
.B \f[C]\-C\ \-\-cleared\f[] .B \f[C]-C --cleared\f[R]
include only cleared postings/txns include only cleared postings/txns
.RS
.RE
.TP .TP
.B \f[C]\-R\ \-\-real\f[] .B \f[C]-R --real\f[R]
include only non\-virtual postings include only non-virtual postings
.RS
.RE
.TP .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 hide/aggregate accounts or postings more than NUM levels deep
.RS
.RE
.TP .TP
.B \f[C]\-E\ \-\-empty\f[] .B \f[C]-E --empty\f[R]
show items with zero amount, normally hidden (and vice\-versa in show items with zero amount, normally hidden (and vice-versa in
hledger\-ui/hledger\-web) hledger-ui/hledger-web)
.RS
.RE
.TP .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 convert amounts to their cost at transaction time (using the transaction
price, if any) price, if any)
.RS
.RE
.TP .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 convert amounts to their market value on the report end date (using the
most recent applicable market price, if any) most recent applicable market price, if any)
.RS
.RE
.TP .TP
.B \f[C]\-\-auto\f[] .B \f[C]--auto\f[R]
apply automated posting rules to modify transactions. apply automated posting rules to modify transactions.
.RS
.RE
.TP .TP
.B \f[C]\-\-forecast\f[] .B \f[C]--forecast\f[R]
apply periodic transaction rules to generate future transactions, to 6 apply periodic transaction rules to generate future transactions, to 6
months from now or report end date. months from now or report end date.
.RS
.RE
.PP .PP
When a reporting option appears more than once in the command line, the When a reporting option appears more than once in the command line, the
last one takes precedence. last one takes precedence.
@ -240,59 +174,53 @@ Some reporting options can also be written as query arguments.
.PP .PP
hledger help options: hledger help options:
.TP .TP
.B \f[C]\-h\ \-\-help\f[] .B \f[C]-h --help\f[R]
show general usage (or after COMMAND, command usage) show general usage (or after COMMAND, command usage)
.RS
.RE
.TP .TP
.B \f[C]\-\-version\f[] .B \f[C]--version\f[R]
show version show version
.RS
.RE
.TP .TP
.B \f[C]\-\-debug[=N]\f[] .B \f[C]--debug[=N]\f[R]
show debug output (levels 1\-9, default: 1) show debug output (levels 1-9, default: 1)
.RS
.RE
.PP .PP
A \@FILE argument will be expanded to the contents of FILE, which should A \[at]FILE argument will be expanded to the contents of FILE, which
contain one command line option/argument per line. should contain one command line option/argument per line.
(To prevent this, insert a \f[C]\-\-\f[] argument before.) (To prevent this, insert a \f[C]--\f[R] argument before.)
.PP .PP
By default, hledger\-web starts the web app in "transient mode" and also By default, hledger-web starts the web app in \[dq]transient mode\[dq]
opens it in your default web browser if possible. 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 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 open in a browser window, and will exit after two minutes of inactivity
(no requests and no browser windows viewing it). (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. logs requests to the console.
.PP .PP
By default the server listens on IP address 127.0.0.1, accessible only By default the server listens on IP address 127.0.0.1, accessible only
to local requests. to local requests.
You can use \f[C]\-\-host\f[] to change this, eg You can use \f[C]--host\f[R] to change this, eg \f[C]--host 0.0.0.0\f[R]
\f[C]\-\-host\ 0.0.0.0\f[] to listen on all configured addresses. to listen on all configured addresses.
.PP .PP
Similarly, use \f[C]\-\-port\f[] to set a TCP port other than 5000, eg Similarly, use \f[C]--port\f[R] to set a TCP port other than 5000, eg if
if you are running multiple hledger\-web instances. you are running multiple hledger-web instances.
.PP .PP
You can use \f[C]\-\-base\-url\f[] to change the protocol, hostname, You can use \f[C]--base-url\f[R] to change the protocol, hostname, port
port and path that appear in hyperlinks, useful eg for integrating and path that appear in hyperlinks, useful eg for integrating
hledger\-web within a larger website. hledger-web within a larger website.
The default is \f[C]http://HOST:PORT/\f[] using the server\[aq]s 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[] if PORT is configured host address and TCP port (or \f[C]http://HOST\f[R] if PORT
80). is 80).
.PP .PP
With \f[C]\-\-file\-url\f[] you can set a different base url for static 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 files, eg for better caching or cookie-less serving on high performance
websites. websites.
.SH PERMISSIONS .SH PERMISSIONS
.PP .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. journal and to add new transactions, but not to change existing data.
.PP .PP
You can restrict who can reach it by You can restrict who can reach it by
.IP \[bu] 2 .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 By default it listens on 127.0.0.1, accessible to all users on the local
machine. machine.
.IP \[bu] 2 .IP \[bu] 2
@ -302,56 +230,59 @@ custom firewall rules
.PP .PP
You can restrict what the users who reach it can do, by You can restrict what the users who reach it can do, by
.IP \[bu] 2 .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. 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 .RS 2
.IP \[bu] 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 .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 .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 included files
.RE .RE
.IP \[bu] 2 .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. 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. integrate with Sandstorm\[aq]s permissions.
This is disabled by default. This is disabled by default.
.SH EDITING, UPLOADING, DOWNLOADING .SH EDITING, UPLOADING, DOWNLOADING
.PP .PP
If you enable the \f[C]manage\f[] capability mentioned above, you\[aq]ll If you enable the \f[C]manage\f[R] capability mentioned above,
see a new "spanner" button to the right of the search form. 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 Clicking this will let you edit, upload, or download the journal file or
any files it includes. any files it includes.
.PP .PP
Note, unlike any other hledger command, in this mode you (or any Note, unlike any other hledger command, in this mode you (or any
visitor) can alter or wipe the data files. visitor) can alter or wipe the data files.
.PP .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 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 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). changes yourself (eg with a cron job or a file watcher like entr).
.PP .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. (eg with failing balance assertions) are prevented.
(Probably. (Probably.
This needs re\-testing.) This needs re-testing.)
.SH RELOADING .SH RELOADING
.PP .PP
hledger\-web detects changes made to the files by other means (eg if you 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 edit it directly, outside of hledger-web), and it will show the new data
data when you reload the page or navigate to a new page. when you reload the page or navigate to a new page.
If a change makes a file unparseable, hledger\-web will display an error If a change makes a file unparseable, hledger-web will display an error
message until the file has been fixed. message until the file has been fixed.
.SH JSON API .SH JSON API
.PP .PP
In addition to the web UI, hledger\-web provides some JSON API routes. In addition to the web UI, hledger-web provides some API routes that
These are similar to the API provided by the hledger\-api tool, but it serve JSON in response to GET requests.
may be convenient to have them in hledger\-web also. 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 .IP
.nf .nf
\f[C] \f[C]
@ -361,31 +292,65 @@ may be convenient to have them in hledger\-web also.
/commodities /commodities
/accounts /accounts
/accounttransactions/#AccountName /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 .fi
.SH ENVIRONMENT .SH ENVIRONMENT
.PP .PP
\f[B]LEDGER_FILE\f[] The journal file path when not specified with \f[B]LEDGER_FILE\f[R] The journal file path when not specified with
\f[C]\-f\f[]. \f[C]-f\f[R].
Default: \f[C]~/.hledger.journal\f[] (on windows, perhaps Default: \f[C]\[ti]/.hledger.journal\f[R] (on windows, perhaps
\f[C]C:/Users/USER/.hledger.journal\f[]). \f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH FILES .SH FILES
.PP .PP
Reads data from one or more files in hledger journal, timeclock, Reads data from one or more files in hledger journal, timeclock,
timedot, or CSV format specified with \f[C]\-f\f[], or timedot, or CSV format specified with \f[C]-f\f[R], or
\f[C]$LEDGER_FILE\f[], or \f[C]$HOME/.hledger.journal\f[] (on windows, \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[]). perhaps \f[C]C:/Users/USER/.hledger.journal\f[R]).
.SH BUGS .SH BUGS
.PP .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. is awkward.
.PP .PP
\f[C]\-f\-\f[] doesn\[aq]t work (hledger\-web can\[aq]t read from \f[C]-f-\f[R] doesn\[aq]t work (hledger-web can\[aq]t read from stdin).
stdin).
.PP .PP
Query arguments and some hledger options are ignored. Query arguments and some hledger options are ignored.
.PP .PP
Does not work in text\-mode browsers. Does not work in text-mode browsers.
.PP .PP
Does not work well on small screens. 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) 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 hledger-web is hledger's web interface. It starts a simple web
application for browsing and adding transactions, and optionally opens 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 '$LEDGER_FILE', or '$HOME/.hledger.journal' (on windows, perhaps
'C:/Users/USER/.hledger.journal'). For more about this see hledger(1), 'C:/Users/USER/.hledger.journal'). For more about this see hledger(1),
hledger_journal(5) etc. hledger_journal(5) etc.
* Menu: * Menu:
* OPTIONS:: * OPTIONS::
@ -287,9 +288,10 @@ File: hledger-web.info, Node: JSON API, Prev: RELOADING, Up: Top
5 JSON API 5 JSON API
********** **********
In addition to the web UI, hledger-web provides some JSON API routes. In addition to the web UI, hledger-web provides some API routes that
These are similar to the API provided by the hledger-api tool, but it serve JSON in response to GET requests. Currently these are same ones
may be convenient to have them in hledger-web also. provided by the hledger-api tool, but hledger-web will likely receive
more attention than hledger-api in future:
/accountnames /accountnames
/transactions /transactions
@ -298,18 +300,43 @@ may be convenient to have them in hledger-web also.
/accounts /accounts
/accounttransactions/#AccountName /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: Tag Table:
Node: Top72 Node: Top72
Node: OPTIONS1354 Node: OPTIONS1361
Ref: #options1459 Ref: #options1466
Node: PERMISSIONS6549 Node: PERMISSIONS6556
Ref: #permissions6688 Ref: #permissions6695
Node: EDITING UPLOADING DOWNLOADING7900 Node: EDITING UPLOADING DOWNLOADING7907
Ref: #editing-uploading-downloading8081 Ref: #editing-uploading-downloading8088
Node: RELOADING8915 Node: RELOADING8922
Ref: #reloading9049 Ref: #reloading9056
Node: JSON API9359 Node: JSON API9366
Ref: #json-api9453 Ref: #json-api9460
 
End Tag Table End Tag Table

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

@ -187,8 +187,8 @@ OPTIONS
without exiting, and logs requests to the console. without exiting, and logs requests to the console.
By default the server listens on IP address 127.0.0.1, accessible only 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 to local requests. You can use --host to change this, eg --host
--host 0.0.0.0 to listen on all configured addresses. 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 Similarly, use --port to set a TCP port other than 5000, eg if you are
running multiple hledger-web instances. running multiple hledger-web instances.
@ -260,9 +260,10 @@ RELOADING
until the file has been fixed. until the file has been fixed.
JSON API JSON API
In addition to the web UI, hledger-web provides some JSON API routes. In addition to the web UI, hledger-web provides some API routes that
These are similar to the API provided by the hledger-api tool, but it serve JSON in response to GET requests. Currently these are same ones
may be convenient to have them in hledger-web also. provided by the hledger-api tool, but hledger-web will likely receive
more attention than hledger-api in future:
/accountnames /accountnames
/transactions /transactions
@ -271,6 +272,31 @@ JSON API
/accounts /accounts
/accounttransactions/#AccountName /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 ENVIRONMENT
LEDGER_FILE The journal file path when not specified with -f. Default: LEDGER_FILE The journal file path when not specified with -f. Default:
~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour- ~/.hledger.journal (on windows, perhaps C:/Users/USER/.hledger.jour-
@ -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) 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 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 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 '~/.hledger.journal', or run 'hledger add' and follow the prompts. Then
try some commands like 'hledger print' or 'hledger balance'. Run try some commands like 'hledger print' or 'hledger balance'. Run
'hledger' with no arguments for a list of commands. 'hledger' with no arguments for a list of commands.
* Menu: * Menu:
* EXAMPLES:: * EXAMPLES::
@ -131,7 +132,7 @@ File: hledger.info, Node: OPTIONS, Next: QUERIES, Prev: EXAMPLES, Up: Top
* Pivoting:: * Pivoting::
* Cost:: * Cost::
* Market value:: * Market value::
* Combining -B and -V:: * Combining -B -V --value::
* Output destination:: * Output destination::
* Output format:: * Output format::
* Regular expressions:: * Regular expressions::
@ -303,6 +304,7 @@ characters. Eg:
'hledger register -p 'last year' "accounts receivable 'hledger register -p 'last year' "accounts receivable
(receivable|payable)" amt:\>100'. (receivable|payable)" amt:\>100'.
* Menu: * Menu:
* More escaping:: * More escaping::
@ -393,24 +395,38 @@ File: hledger.info, Node: Unicode characters, Next: Input files, Prev: Comman
2.7 Unicode characters 2.7 Unicode characters
====================== ======================
hledger is expected to handle unicode (non-ascii) characters, but this hledger is expected to handle non-ascii characters correctly:
requires a well-configured environment.
To handle unicode characters in the command line or input data, a * they should be parsed correctly in input files and on the command
system locale that can decode them must be configured (POSIX's default line, by all hledger tools (add, iadd, hledger-web's
'C' locale will not work). Eg in bash, you could do: 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 * A system locale must be configured, and it must be one that can
the hledger and hledger-ui tools, this requires that 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 * your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
* the terminal's font includes the required unicode glyphs must support unicode
* the terminal is configured to display "wide" characters as double
width (otherwise report alignment will be off) * 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 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. 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 2.16 Market value
================= =================
The '-V/--value' flag converts reported amounts to their current market The '-V/--market' flag converts reported amounts to their market value
value. in another commodity. It uses the commodity referenced in the latest
Specifically, when there is a market price (P directive) for the market price (P directive) dated on or before the valuation date. The
amount's commodity, dated on or before today's date (or the report end default valuation date is today. For example:
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:
# one euro is worth this many dollars from nov 1 # one euro is worth this many dollars from nov 1
P 2016/11/01 € $1.10 P 2016/11/01 € $1.10
@ -773,25 +782,211 @@ specified, defaults to today)
$ hledger -f t.j bal -N euros -V $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $103.00 assets:euros
Currently, hledger's -V only uses market prices recorded with P Ledger users: Ledger's -V also infers market prices from journal
directives, not transaction prices (unlike Ledger). 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 * Menu:
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::
* 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 _(experimental, added 201905)_
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 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 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 Here are all the builtin commands in alphabetical order. See also
'hledger' for a more organised command list, and 'hledger CMD -h' for 'hledger' for a more organised command list, and 'hledger CMD -h' for
detailed command help. detailed command help.
* Menu: * Menu:
* accounts:: * accounts::
@ -1162,6 +1358,7 @@ show real-world account balances. In some cases the -H/-historical flag
is used to ensure this (more below). is used to ensure this (more below).
The balance command can produce several styles of report: The balance command can produce several styles of report:
* Menu: * Menu:
* Classic balance report:: * Classic balance report::
@ -1250,7 +1447,9 @@ with data fields interpolated like so:
'%[MIN][.MAX](FIELDNAME)' '%[MIN][.MAX](FIELDNAME)'
* MIN pads with spaces to at least this width (optional) * MIN pads with spaces to at least this width (optional)
* MAX truncates at this width (optional) * MAX truncates at this width (optional)
* FIELDNAME must be enclosed in parentheses, and can be one of: * FIELDNAME must be enclosed in parentheses, and can be one of:
* 'depth_spacer' - a number of spaces equal to the account's * 'depth_spacer' - a number of spaces equal to the account's
@ -1390,6 +1589,10 @@ different information:
----------------------++------------------------------------- ----------------------++-------------------------------------
|| 0 0 0 || 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; Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use '--tree'. to see the hierarchy, use '--tree'.
@ -1557,6 +1760,7 @@ Budget performance in 2017/11/01-2017/12/31:
|| 0 [ 0] 0 [ 0] || 0 [ 0] 0 [ 0]
For more examples, see Budgeting and Forecasting. For more examples, see Budgeting and Forecasting.
* Menu: * Menu:
* Nested budgets:: * Nested budgets::
@ -1696,7 +1900,9 @@ Total:
each report period. As with multicolumn balance reports, you can alter each report period. As with multicolumn balance reports, you can alter
the report mode with '--change'/'--cumulative'/'--historical'. Normally the report mode with '--change'/'--cumulative'/'--historical'. Normally
balancesheet shows historical ending balances, which is what you need 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 This command also supports output destination and output format
selection. selection.
@ -1815,7 +2021,7 @@ end of a period.
The closing transaction transfers balances to "equity:closing The closing transaction transfers balances to "equity:closing
balances". The opening transaction transfers balances from 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. transactions by using the '--opening' or '--closing' flag.
If you split your journal files by time (eg yearly), you will 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 $ 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 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 these will be adjusted outward if necessary to contain a whole number of
intervals. This ensures that the first and last intervals are full intervals. This ensures that the first and last intervals are full
length and comparable to the others in the report. length and comparable to the others in the report.
* Menu: * Menu:
* Custom register output:: * Custom register output::
@ -2292,9 +2522,9 @@ transaction's first posting amount.
Examples: Examples:
hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' $ 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 expenses:gifts --add-posting '(reserve:gifts) *-1"'
hledger-rewrite.hs -f rewrites.hledger $ hledger-rewrite.hs -f rewrites.hledger
rewrites.hledger may consist of entries like: 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. options, journal parsing, reporting, etc.
Here are some hledger add-ons available: Here are some hledger add-ons available:
* Menu: * Menu:
* Official add-ons:: * 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. These are maintained and released along with hledger.
* Menu: * Menu:
* api:: * 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 These are maintained separately, and usually updated shortly after a
hledger release. hledger release.
* Menu: * Menu:
* diff:: * 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 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 than built-in commands. Reading and tweaking these is a good way to
start making your own! start making your own!
* Menu: * Menu:
* autosync:: * autosync::
@ -2697,160 +2931,168 @@ hledger-check.hs checks more powerful account balance assertions.
 
Tag Table: Tag Table:
Node: Top68 Node: Top68
Node: EXAMPLES1888 Node: EXAMPLES1891
Ref: #examples1988 Ref: #examples1991
Node: OPTIONS3634 Node: OPTIONS3637
Ref: #options3736 Ref: #options3739
Node: General options4171 Node: General options4178
Ref: #general-options4296 Ref: #general-options4303
Node: Command options6978 Node: Command options6985
Ref: #command-options7129 Ref: #command-options7136
Node: Command arguments7527 Node: Command arguments7534
Ref: #command-arguments7681 Ref: #command-arguments7688
Node: Argument files7802 Node: Argument files7809
Ref: #argument-files7978 Ref: #argument-files7985
Node: Special characters in arguments and queries8244 Node: Special characters in arguments and queries8251
Ref: #special-characters-in-arguments-and-queries8478 Ref: #special-characters-in-arguments-and-queries8485
Node: More escaping8928 Node: More escaping8936
Ref: #more-escaping9090 Ref: #more-escaping9098
Node: Even more escaping9386 Node: Even more escaping9394
Ref: #even-more-escaping9580 Ref: #even-more-escaping9588
Node: Less escaping10251 Node: Less escaping10259
Ref: #less-escaping10413 Ref: #less-escaping10421
Node: Command line tips10658 Node: Command line tips10666
Ref: #command-line-tips10844 Ref: #command-line-tips10852
Node: Unicode characters11221 Node: Unicode characters11229
Ref: #unicode-characters11377 Ref: #unicode-characters11385
Node: Input files12102 Node: Input files12797
Ref: #input-files12238 Ref: #input-files12933
Node: Smart dates14208 Node: Smart dates14903
Ref: #smart-dates14349 Ref: #smart-dates15044
Node: Report start & end date15755 Node: Report start & end date16450
Ref: #report-start-end-date15927 Ref: #report-start-end-date16622
Node: Report intervals16993 Node: Report intervals17688
Ref: #report-intervals17158 Ref: #report-intervals17853
Node: Period expressions17559 Node: Period expressions18254
Ref: #period-expressions17719 Ref: #period-expressions18414
Node: Depth limiting21676 Node: Depth limiting22371
Ref: #depth-limiting21820 Ref: #depth-limiting22515
Node: Pivoting22162 Node: Pivoting22857
Ref: #pivoting22280 Ref: #pivoting22975
Node: Cost23956 Node: Cost24651
Ref: #cost24064 Ref: #cost24759
Node: Market value24182 Node: Market value24877
Ref: #market-value24317 Ref: #market-value25016
Node: Combining -B and -V25683 Node: More control over valuation26257
Ref: #combining--b-and--v25846 Ref: #more-control-over-valuation26442
Node: Output destination25993 Node: Effect of --value on reports28897
Ref: #output-destination26155 Ref: #effect-of---value-on-reports29116
Node: Output format26438 Node: Some useful value reports31807
Ref: #output-format26590 Ref: #some-useful-value-reports31986
Node: Regular expressions26975 Node: Combining -B -V --value32484
Ref: #regular-expressions27112 Ref: #combining--b--v---value32661
Node: QUERIES28473 Node: Output destination32697
Ref: #queries28575 Ref: #output-destination32863
Node: COMMANDS32537 Node: Output format33146
Ref: #commands32649 Ref: #output-format33298
Node: accounts33649 Node: Regular expressions33683
Ref: #accounts33747 Ref: #regular-expressions33820
Node: activity34446 Node: QUERIES35181
Ref: #activity34556 Ref: #queries35283
Node: add34939 Node: COMMANDS39245
Ref: #add35038 Ref: #commands39357
Node: balance37625 Node: accounts40358
Ref: #balance37736 Ref: #accounts40456
Node: Classic balance report39177 Node: activity41155
Ref: #classic-balance-report39350 Ref: #activity41265
Node: Customising the classic balance report40719 Node: add41648
Ref: #customising-the-classic-balance-report40947 Ref: #add41747
Node: Colour support43021 Node: balance44334
Ref: #colour-support43188 Ref: #balance44445
Node: Flat mode43361 Node: Classic balance report45887
Ref: #flat-mode43509 Ref: #classic-balance-report46060
Node: Depth limited balance reports43922 Node: Customising the classic balance report47429
Ref: #depth-limited-balance-reports44122 Ref: #customising-the-classic-balance-report47657
Node: Multicolumn balance report44578 Node: Colour support49733
Ref: #multicolumn-balance-report44776 Ref: #colour-support49900
Node: Budget report49956 Node: Flat mode50073
Ref: #budget-report50099 Ref: #flat-mode50221
Node: Nested budgets55300 Node: Depth limited balance reports50634
Ref: #nested-budgets55412 Ref: #depth-limited-balance-reports50834
Ref: #output-format-158892 Node: Multicolumn balance report51290
Node: balancesheet58970 Ref: #multicolumn-balance-report51488
Ref: #balancesheet59106 Node: Budget report56802
Node: balancesheetequity60340 Ref: #budget-report56945
Ref: #balancesheetequity60489 Node: Nested budgets62147
Node: cashflow61050 Ref: #nested-budgets62259
Ref: #cashflow61178 Ref: #output-format-165739
Node: check-dates62206 Node: balancesheet65817
Ref: #check-dates62333 Ref: #balancesheet65953
Node: check-dupes62612 Node: balancesheetequity67268
Ref: #check-dupes62736 Ref: #balancesheetequity67417
Node: close63029 Node: cashflow67978
Ref: #close63137 Ref: #cashflow68106
Node: files66550 Node: check-dates69134
Ref: #files66651 Ref: #check-dates69261
Node: help66798 Node: check-dupes69540
Ref: #help66898 Ref: #check-dupes69664
Node: import67991 Node: close69957
Ref: #import68105 Ref: #close70065
Node: incomestatement68849 Node: files73479
Ref: #incomestatement68983 Ref: #files73580
Node: prices70319 Node: help73727
Ref: #prices70434 Ref: #help73827
Node: print70713 Node: import74920
Ref: #print70823 Ref: #import75034
Node: print-unique75316 Node: Importing balance assignments75822
Ref: #print-unique75442 Ref: #importing-balance-assignments75970
Node: register75727 Node: incomestatement76619
Ref: #register75854 Ref: #incomestatement76753
Node: Custom register output80025 Node: prices78089
Ref: #custom-register-output80154 Ref: #prices78204
Node: register-match81416 Node: print78483
Ref: #register-match81550 Ref: #print78593
Node: rewrite81901 Node: print-unique83086
Ref: #rewrite82016 Ref: #print-unique83212
Node: Re-write rules in a file83865 Node: register83497
Ref: #re-write-rules-in-a-file83999 Ref: #register83624
Node: Diff output format85209 Node: Custom register output87796
Ref: #diff-output-format85378 Ref: #custom-register-output87925
Node: rewrite vs print --auto86470 Node: register-match89187
Ref: #rewrite-vs.-print---auto86649 Ref: #register-match89321
Node: roi87205 Node: rewrite89672
Ref: #roi87303 Ref: #rewrite89787
Node: stats88315 Node: Re-write rules in a file91642
Ref: #stats88414 Ref: #re-write-rules-in-a-file91776
Node: tags89168 Node: Diff output format92986
Ref: #tags89266 Ref: #diff-output-format93155
Node: test89496 Node: rewrite vs print --auto94247
Ref: #test89580 Ref: #rewrite-vs.-print---auto94426
Node: ADD-ON COMMANDS90341 Node: roi94982
Ref: #add-on-commands90451 Ref: #roi95080
Node: Official add-ons91738 Node: stats96092
Ref: #official-add-ons91878 Ref: #stats96191
Node: api91965 Node: tags96945
Ref: #api92054 Ref: #tags97043
Node: ui92106 Node: test97273
Ref: #ui92205 Ref: #test97357
Node: web92263 Node: ADD-ON COMMANDS98118
Ref: #web92352 Ref: #add-on-commands98228
Node: Third party add-ons92398 Node: Official add-ons99516
Ref: #third-party-add-ons92573 Ref: #official-add-ons99656
Node: diff92708 Node: api99744
Ref: #diff92805 Ref: #api99833
Node: iadd92904 Node: ui99885
Ref: #iadd93018 Ref: #ui99984
Node: interest93101 Node: web100042
Ref: #interest93222 Ref: #web100131
Node: irr93317 Node: Third party add-ons100177
Ref: #irr93415 Ref: #third-party-add-ons100352
Node: Experimental add-ons93546 Node: diff100488
Ref: #experimental-add-ons93698 Ref: #diff100585
Node: autosync93978 Node: iadd100684
Ref: #autosync94089 Ref: #iadd100798
Node: chart94328 Node: interest100881
Ref: #chart94447 Ref: #interest101002
Node: check94518 Node: irr101097
Ref: #check94620 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 End Tag Table

348
hledger/hledger.txt
View File

@ -310,26 +310,38 @@ OPTIONS
to troubleshoot. to troubleshoot.
Unicode characters Unicode characters
hledger is expected to handle unicode (non-ascii) characters, but this hledger is expected to handle non-ascii characters correctly:
requires a well-configured environment.
To handle unicode characters in the command line or input data, a sys- o they should be parsed correctly in input files and on the command
tem locale that can decode them must be configured (POSIX's default C line, by all hledger tools (add, iadd, hledger-web's search/add/edit
locale will not work). Eg in bash, you could do: 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 o A system locale must be configured, and it must be one that can
the hledger and hledger-ui tools, this requires that 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 o the terminal should be configured to display wide characters as dou-
width (otherwise report alignment will be off) 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 Input files
hledger reads transactions from a data file (and the add command writes hledger reads transactions from a data file (and the add command writes
@ -397,7 +409,6 @@ OPTIONS
4+ digits, month is 1-12, 4+ digits, month is 1-12,
day is 1-31 day is 1-31
2004 start of year 2004 start of year
2004/10 start of month 2004/10 start of month
10/1 month and day in current 10/1 month and day in current
year year
@ -405,8 +416,9 @@ OPTIONS
october, oct start of month in current october, oct start of month in current
year year
yesterday, today, tomorrow -1, 0, 1 days from today yesterday, today, tomorrow -1, 0, 1 days from today
last/this/next day/week/month/quar- -1, 0, 1 periods from the last/this/next -1, 0, 1 periods from the
ter/year current period day/week/month/quar- current period
ter/year
20181201 8 digit YYYYMMDD with 20181201 8 digit YYYYMMDD with
valid year month and day valid year month and day
201812 6 digit YYYYMM with valid 201812 6 digit YYYYMM with valid
@ -450,6 +462,9 @@ OPTIONS
ber 1st of the current ber 1st of the current
year (11/30 will be the year (11/30 will be the
last date included) last date included)
-b thismonth all transactions on or -b thismonth all transactions on or
after the 1st of the cur- after the 1st of the cur-
rent month rent month
@ -516,6 +531,7 @@ OPTIONS
-p "2009/1" the month of jan; equiva- -p "2009/1" the month of jan; equiva-
lent to "2009/1/1 to lent to "2009/1/1 to
2009/2/1" 2009/2/1"
-p "2009/1/1" just that day; equivalent -p "2009/1/1" just that day; equivalent
to "2009/1/1 to 2009/1/2" to "2009/1/1 to 2009/1/2"
@ -543,17 +559,16 @@ OPTIONS
ceeding Monday ceeding Monday
-p "monthly in 2008/11/25" -- starts on -p "monthly in 2008/11/25" -- starts on
2018/11/01 2018/11/01
-p "quar- -p "quarterly from 2009-05-05 to
terly from 2009-05-05 to 2009-06-01" - 2009-06-01" - starts on 2009/04/01,
starts on 2009/04/01, ends on ends on 2009/06/30, which are first and
2009/06/30, which are first and last last days of Q2 2009
days of Q2 2009
-p "yearly from 2009-12-29" - starts on -p "yearly from 2009-12-29" - starts on
2009/01/01, first day of 2009 2009/01/01, first day of 2009
The following more complex report intervals are also supported: The following more complex report intervals are also supported:
biweekly, bimonthly, every day|week|month|quarter|year, biweekly, bimonthly, every day|week|month|quarter|year, every N
every N days|weeks|months|quarters|years. days|weeks|months|quarters|years.
All of these will start on the first day of the requested period and All of these will start on the first day of the requested period and
end on the last one, as described above. 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 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: 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 day of week, every <weekday>, every Nth day [of month], every
every Nth weekday [of month], every MM/DD [of year], Nth weekday [of month], every MM/DD [of year], every Nth MMM [of year],
every Nth MMM [of year], every MMM Nth [of year]. every MMM Nth [of year].
Examples: Examples:
@ -583,6 +598,7 @@ OPTIONS
-p "every 2nd day of week" -- periods -p "every 2nd day of week" -- periods
will go from Tue to Tue will go from Tue to Tue
-p "every Tue" -- same -p "every Tue" -- same
-p "every 15th day" -- period bound- -p "every 15th day" -- period bound-
aries will be on 15th of each month aries will be on 15th of each month
-p "every 2nd Monday" -- period bound- -p "every 2nd Monday" -- period bound-
@ -667,33 +683,26 @@ OPTIONS
if they have a transaction price specified. if they have a transaction price specified.
Market value Market value
The -V/--value flag converts reported amounts to their current market The -V/--market flag converts reported amounts to their market value in
value. another commodity. It uses the commodity referenced in the latest mar-
Specifically, when there is a market price (P directive) for the ket price (P directive) dated on or before the valuation date. The
amount's commodity, dated on or before today's date (or the report end default valuation date is today. For example:
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:
# one euro is worth this many dollars from nov 1 # 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 # purchase some euros on nov 3
2016/11/3 2016/11/3
assets:euros 100 assets:euros EUR100
assets:checking assets:checking
# the euro is worth fewer dollars by dec 21 # 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 ? How many euros do I have ?
$ hledger -f t.j bal -N euros $ hledger -f t.j bal -N euros
100 assets:euros EUR100 assets:euros
What are they worth at end of nov 3 ? What are they worth at end of nov 3 ?
@ -706,17 +715,181 @@ OPTIONS
$ hledger -f t.j bal -N euros -V $ hledger -f t.j bal -N euros -V
$103.00 assets:euros $103.00 assets:euros
Currently, hledger's -V only uses market prices recorded with P direc- Ledger users: Ledger's -V also infers market prices from journal
tives, not transaction prices (unlike Ledger). 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 More control over valuation
the market prices on the report end date for all columns. (Instead of (experimental, added 201905)
the prices on each column's end date.)
Combining -B and -V You can control valuation more precisely with the --value option.
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 --value=TYPE which type of valuation should be done ? cost|end|now|YYYY-MM-DD
this.
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 Output destination
Some commands (print, register, stats, the balance commands) can write Some commands (print, register, stats, the balance commands) can write
@ -813,8 +986,7 @@ QUERIES
REGEX, acct:REGEX REGEX, acct:REGEX
match account names by this regular expression. (With no pre- match account names by this regular expression. (With no pre-
fix, acct: is assumed.) fix, acct: is assumed.) same as above
same as above
amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N
match postings with a single-commodity amount that is equal to, 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 tial match, use .*REGEX.*). Note, to match characters which are
regex-significant, like the dollar sign ($), you need to prepend regex-significant, like the dollar sign ($), you need to prepend
\. And when using the command line you need to add one more \. And when using the command line you need to add one more
level of quoting to hide it from the shell, so eg do: level of quoting to hide it from the shell, so eg do: hledger
hledger print cur:'\$' or hledger print cur:\\$. print cur:'\$' or hledger print cur:\\$.
desc:REGEX desc:REGEX
match transaction descriptions. match transaction descriptions.
@ -893,10 +1065,10 @@ COMMANDS
scripts named hledger-NAME in your PATH, these will also be listed as scripts named hledger-NAME in your PATH, these will also be listed as
subcommands. subcommands.
Run a subcommand by writing its name as first argument (eg Run a subcommand by writing its name as first argument (eg hledger
hledger incomestatement). You can also write one of the standard short incomestatement). You can also write one of the standard short aliases
aliases displayed in parentheses in the command list (hledger b), or displayed in parentheses in the command list (hledger b), or any any
any any unambiguous prefix of a command name (hledger inc). unambiguous prefix of a command name (hledger inc).
Here are all the builtin commands in alphabetical order. See also Here are all the builtin commands in alphabetical order. See also
hledger for a more organised command list, and hledger CMD -h for 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 Many hledger users edit their journals directly with a text editor, or
generate them from CSV. For more interactive data entry, there is the generate them from CSV. For more interactive data entry, there is the
add command, which prompts interactively on the console for new trans- add command, which prompts interactively on the console for new trans-
actions, and appends them to the journal file (if there are multiple actions, and appends them to the journal file (if there are multiple -f
-f FILE options, the first file is used.) Existing transactions are not FILE options, the first file is used.) Existing transactions are not
changed. This is the only hledger command that writes to the journal changed. This is the only hledger command that writes to the journal
file. file.
@ -1082,8 +1254,8 @@ COMMANDS
$1 supplies $1 supplies
Customising the classic balance report Customising the classic balance report
You can customise the layout of classic balance reports with --for- You can customise the layout of classic balance reports with --format
mat FMT: FMT:
$ hledger balance --format "%20(account) %12(total)" $ hledger balance --format "%20(account) %12(total)"
assets $-1 assets $-1
@ -1128,8 +1300,8 @@ COMMANDS
o %, - render on one line, comma-separated o %, - render on one line, comma-separated
There are some quirks. Eg in one-line mode, %(depth_spacer) has no There are some quirks. Eg in one-line mode, %(depth_spacer) has no
effect, instead %(account) has indentation built in. effect, instead %(account) has indentation built in. Experimentation
Experimentation may be needed to get pleasing results. may be needed to get pleasing results.
Some example formats: Some example formats:
@ -1237,6 +1409,9 @@ COMMANDS
----------------------++------------------------------------- ----------------------++-------------------------------------
|| 0 0 0 || 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; Multicolumn balance reports display accounts in flat mode by default;
to see the hierarchy, use --tree. to see the hierarchy, use --tree.
@ -1522,7 +1697,9 @@ COMMANDS
report period. As with multicolumn balance reports, you can alter the report period. As with multicolumn balance reports, you can alter the
report mode with --change/--cumulative/--historical. Normally bal- report mode with --change/--cumulative/--historical. Normally bal-
ancesheet shows historical ending balances, which is what you need for 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- This command also supports output destination and output format selec-
tion. tion.
@ -1616,7 +1793,7 @@ COMMANDS
The closing transaction transfers balances to "equity:closing bal- The closing transaction transfers balances to "equity:closing bal-
ances". The opening transaction transfers balances from "equity:open- 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. using the --opening or --closing flag.
If you split your journal files by time (eg yearly), you will typically 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 $ 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
incomestatement, is incomestatement, is
This command displays a simple income statement, showing revenues and 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, Print the one posting whose transaction description is closest to DESC,
in the style of the register command. If there are multiple equally in the style of the register command. If there are multiple equally
good matches, it shows the most recent. Query options (options, not good matches, it shows the most recent. Query options (options, not
arguments) can be used to restrict the search space. Helps arguments) can be used to restrict the search space. Helps ledger-
ledger-autosync detect already-seen transactions when importing. autosync detect already-seen transactions when importing.
rewrite rewrite
rewrite rewrite
@ -2038,9 +2229,9 @@ COMMANDS
Examples: Examples:
hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100' $ 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 expenses:gifts --add-posting '(reserve:gifts) *-1"'
hledger-rewrite.hs -f rewrites.hledger $ hledger-rewrite.hs -f rewrites.hledger
rewrites.hledger may consist of entries like: rewrites.hledger may consist of entries like:
@ -2220,8 +2411,8 @@ COMMANDS
seed, for repeatable results from tests using randomness (currently seed, for repeatable results from tests using randomness (currently
none of them). none of them).
This is mainly used by developers, but it's nice to be able to san- This is mainly used by developers, but it's nice to be able to sanity-
ity-check your installed hledger executable at any time. All tests are check your installed hledger executable at any time. All tests are
expected to pass - if you ever see otherwise, something has gone wrong, expected to pass - if you ever see otherwise, something has gone wrong,
please report a bug! please report a bug!
@ -2241,8 +2432,8 @@ ADD-ON COMMANDS
from hledger. So hledger web --serve --port 9000 will be rejected; from hledger. So hledger web --serve --port 9000 will be rejected;
you must use hledger web -- --serve --port 9000. you must use hledger web -- --serve --port 9000.
o You can always run add-ons directly if preferred: o You can always run add-ons directly if preferred: hledger-web --serve
hledger-web --serve --port 9000. --port 9000.
Add-ons are a relatively easy way to add local features or experiment 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 with new ideas. They can be written in any language, but haskell
@ -2316,7 +2507,7 @@ FILES
$HOME/.hledger.journal (on windows, perhaps $HOME/.hledger.journal (on windows, perhaps
C:/Users/USER/.hledger.journal). C:/Users/USER/.hledger.journal).
BUGS LIMITATIONS
The need to precede addon command options with -- when invoked from The need to precede addon command options with -- when invoked from
hledger is awkward. hledger is awkward.
@ -2327,6 +2518,9 @@ BUGS
In a Microsoft Windows CMD window, non-ascii characters and colours are In a Microsoft Windows CMD window, non-ascii characters and colours are
not supported. 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 In a Cygwin/MSYS/Mintty window, the tab key is not supported in hledger
add. add.
@ -2418,4 +2612,4 @@ SEE ALSO
hledger 1.14.1 March 2019 hledger(1) hledger 1.14.99 March 2019 hledger(1)