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

docs: manual cleanups/updates

Browse Source
This commit is contained in:
Simon Michael 2013-04-14 19:36:31 -07:00
parent ea231df31d
commit eb9744f600
1 changed files with 141 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

266
MANUAL.md
View File

@ -122,61 +122,20 @@ Here's an example:
Now let's explore the available journal file syntax in detail. Now let's explore the available journal file syntax in detail.
#### Transactions #### Entries
Each transaction begins with a date in column 0, followed by three Each journal entry begins with a [simple date](#simple-dates) in
optional fields with spaces between them: a status flag (`*` or `!` or column 0, followed by three optional fields with spaces between them:
nothing), a transaction code (eg a check number), and/or a description; a status flag (`*` or `!` or nothing), a transaction code (eg a check
then two or more postings (of some amount to some account), each on their number), and/or a description; then two or more postings (of some
own line. amount to some account), each on their own line.
The posting amounts within a transaction must always balance, ie add up to The posting amounts within a transaction must always balance, ie add up to
0. You can leave one amount blank and it will be inferred. 0. You can leave one amount blank and it will be inferred.
#### Account names #### Dates
Account names typically have several parts separated by a full colon, from ##### Simple dates
which hledger derives a hierarchical chart of accounts. They can be
anything you like, but in finance there are traditionally five top-level
accounts: `assets`, `liabilities`, `income`, `expenses`, and `equity`.
Account names may contain single spaces, eg: `assets:accounts receivable`.
#### Amounts
After the account name, separated by ***two or more*** spaces, there is
usually an amount. This is a number, optionally with a currency symbol or
commodity name on either the left or right. Commodity names which contain
more than just letters should be enclosed in double quotes.
Negative amounts usually have the minus sign next to the number: `$-1`.
Or it may go before the symbol: `-$1`.
hledger supports flexible decimal points and digit group separators so you
can use your country's convention. Numbers can use either a period (`.`)
or a comma (`,`) as decimal point. They can also have digit group
separators at any position (eg thousands separators) which can be comma or
period - whichever one you did not use as a decimal point. If you use
digit group separators, you must also include a decimal point in at least
one number in the same commodity, so that hledger knows which character is
which. Eg, write `$1,000.00` or `$1.000,00`.
#### Amount styles
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that
commodity. Amount styles include:
- the position (left or right) and spacing (space or no separator) of the commodity symbol
- the digit group separator character (comma or period) and digit group sizes, if any
- the decimal point character (period or comma)
- the display precision (number of decimal places displayed)
The canonical style is generally the style of the first amount seen in a commodity
(which may be in a [default commodity directive](#default-commodity).
The precision is the highest precision seen among all amounts in the commmodity.
#### Simple dates
Within a journal file, transaction dates always follow a year/month/day Within a journal file, transaction dates always follow a year/month/day
format, although several different separator characters are accepted. Some format, although several different separator characters are accepted. Some
@ -198,7 +157,7 @@ transactions, like so:
1/31 ; equivalent to 2010/1/31 1/31 ; equivalent to 2010/1/31
... ...
#### Secondary dates ##### Secondary dates
Real-life transactions sometimes involve more than one date - eg the date Real-life transactions sometimes involve more than one date - eg the date
you write a cheque, and the date it clears in your bank. When you want to you write a cheque, and the date it clears in your bank. When you want to
@ -225,7 +184,7 @@ Example:
$ hledger register checking --date2 $ hledger register checking --date2
2010/02/19 movie ticket assets:checking $-10 $-10 2010/02/19 movie ticket assets:checking $-10 $-10
#### Posting dates ##### Posting dates
[Comments and tags](#comments) are covered below, but while we are talking [Comments and tags](#comments) are covered below, but while we are talking
about dates: you can give individual postings a different date from their about dates: you can give individual postings a different date from their
@ -235,28 +194,61 @@ a [simple date](#simple-dates). The secondary date can be set with
Ledger's bracketed posting date syntax (`[DATE]`, Ledger's bracketed posting date syntax (`[DATE]`,
`[DATE=DATE2]` or `[=DATE2]` in a posting comment) `[DATE=DATE2]` or `[=DATE2]` in a posting comment)
is also supported, as an alternate spelling of the date tags. is also supported, as an alternate spelling of the date and date2 tags.
#### Default commodity #### Accounts
You can set a default commodity, to be used for any subsequent amounts Account names typically have several parts separated by a full colon, from
which have no commodity symbol, with the D directive: which hledger derives a hierarchical chart of accounts. They can be
anything you like, but in finance there are traditionally five top-level
accounts: `assets`, `liabilities`, `income`, `expenses`, and `equity`.
; set british pound as default commodity Account names may contain single spaces, eg: `assets:accounts receivable`.
; also sets canonical style for pound amounts, since it's the first one
; (pound symbol on left, comma thousands separator, two decimal places)
D £1,000.00
2010/1/1
a 2340 ; no symbol, will use pound
b
A default commodity directive may also influence the canonical #### Amounts
[amount style](#commodity-display-settings) for the commodity.
After the account name, there is usually an amount.
Important: between account name and amount, there must be **two or more** spaces.
The amount is a number, optionally with a currency symbol or commodity name on either the left or right.
Negative amounts may have the minus sign either before or after the currency symbol (`-$1` or `$-1`).
Commodity names which contain more than just letters should be enclosed in double quotes (`1 "person hours"`).
##### Decimal points and digit groups
hledger supports flexible decimal point and digit group separator styles,
to support international variations. Numbers can use either a period (`.`)
or a comma (`,`) as decimal point. They can also have digit group
separators at any position (eg thousands separators) which can be comma or
period - whichever one you did not use as a decimal point. If you use
digit group separators, you must also include a decimal point in at least
one number in the same commodity, so that hledger knows which character is
which. Eg, write `$1,000.00` or `$1.000,00`.
##### Canonical amount styles
Based on how you format amounts, hledger will infer canonical display
styles for each commodity, and use these when displaying amounts in that
commodity. Amount styles include:
- the position (left or right) and spacing (space or no separator) of the commodity symbol
- the digit group separator character (comma or period) and digit group sizes, if any
- the decimal point character (period or comma)
- the display precision (number of decimal places displayed)
The canonical style is generally the style of the first amount seen in a commodity
(which may be in a [default commodity directive](#default-commodity).
The precision is the highest precision seen among all amounts in the commmodity.
##### Balance Assertions
hledger will parse and ignore ledger-style
[balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions).
These look like `=CURRENTBALANCE` following a posting's amount.
#### Prices #### Prices
##### Transaction prices <!-- ##### Transaction prices -->
When recording an amount, you can also record its price in another When recording an amount, you can also record its price in another
commodity. This documents an exchange rate that was applied within commodity. This documents an exchange rate that was applied within
@ -290,12 +282,16 @@ examples we get:
assets:foreign currency $135.00 assets:foreign currency $135.00
assets $-135.00 assets $-135.00
##### Fixed Lot Prices
hledger will parse and ignore ledger-style
[fixed lot prices](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-lot-prices)
(`{=PRICE}` following an amount).
hledger's prices always work like ledger's fixed lot prices.
##### Historical prices ##### Historical prices
You can also record a series of historical prices for a commodity using P hledger will parse and ignore ledger-style historical price directives:
directives. Typically these are used to record daily market prices or
exchange rates. ledger uses them to calculate market value with -V, but
hledger currently ignores them. They look like this:
<!-- (A time and numeric time zone are allowed but ignored, like ledger.) --> <!-- (A time and numeric time zone are allowed but ignored, like ledger.) -->
; Historical price directives look like: P DATE COMMODITYSYMBOL UNITPRICE ; Historical price directives look like: P DATE COMMODITYSYMBOL UNITPRICE
@ -304,21 +300,6 @@ hledger currently ignores them. They look like this:
P 2009/1/1 € $1.35 P 2009/1/1 € $1.35
P 2010/1/1 € $1.40 P 2010/1/1 € $1.40
#### Balance Assertions
ledger supports
[balance assertions](http://ledger-cli.org/3.0/doc/ledger3.html#Balance-assertions):
following a posting's amount, an equals sign and another amount which is
the expected balance in this account at this point. hledger does not
currently enforce these but will ignore them, so you can put them in your
journal and test with ledger if needed.
#### Fixed Lot Prices
Similarly, we ignore ledger's
[fixed lot prices](http://ledger-cli.org/3.0/doc/ledger3.html#Fixing-lot-prices).
hledger's [prices](#transaction-prices) always work like ledger's fixed lot prices.
#### Comments #### Comments
A semicolon in the journal file marks the start of a comment. You can A semicolon in the journal file marks the start of a comment. You can
@ -342,8 +323,7 @@ on following lines. Some examples:
Currently `print` preserves transaction and posting comments but not Currently `print` preserves transaction and posting comments but not
journal comments. journal comments.
A "tag comment" is a transaction or posting comment containing a tag, Comments may contain [tags](#tags).
explained in the next section.
#### Tags #### Tags
@ -364,27 +344,52 @@ one, and all tags have values except TAG1:
; TAG3: a third transaction tag ; TAG3: a third transaction tag
a $1 ; TAG4: a posting tag a $1 ; TAG4: a posting tag
#### Including other files #### Directives
You can pull in the content of additional journal files, by writing lines like this: ##### Account aliases
!include path/to/file.journal You can define account aliases to rewrite certain account names (and their subaccounts).
This tends to be a little more reliable than post-processing with sed or similar.
The directive is `alias ORIG = ALIAS`, where ORIG and ALIAS are full account names.
Eg:
The `!include` directive may only be used in journal files, and currently alias expenses = equity:draw:personal
it may only include other journal files (eg, not timelog files.)
#### Default parent account To forget all aliases defined to this point, use:
end aliases
See also [How to use account aliases](ALIASES.html).
##### Default commodity
You can set a default commodity, to be used for any subsequent amounts
which have no commodity symbol, with the D directive:
; set british pound as default commodity
; also sets canonical style for pound amounts, since it's the first one
; (pound symbol on left, comma thousands separator, two decimal places)
D £1,000.00
2010/1/1
a 2340 ; no symbol, will use pound
b
A default commodity directive may also influence the canonical
[amount style](#commodity-display-settings) for the commodity.
##### Default parent account
You can specify a parent account which will be prepended to all accounts You can specify a parent account which will be prepended to all accounts
within a section of the journal. Use the `!account` directive like so: within a section of the journal. Use the `account` directive like so:
!account home account home
2010/1/1 2010/1/1
food $10 food $10
cash cash
!end end
If `!end` is omitted, the effect lasts to the end of the file. If `!end` is omitted, the effect lasts to the end of the file.
The above is equivalent to: The above is equivalent to:
@ -395,20 +400,21 @@ The above is equivalent to:
Included files are also affected, eg: Included files are also affected, eg:
!account business account business
!include biz.journal include biz.journal
!end end
!account personal account personal
!include personal.journal include personal.journal
!end end
#### Account aliases ##### Including other files
You can define account aliases to rewrite certain account names (and their subaccounts). You can pull in the content of additional journal files, by writing lines like this:
This tends to be a little more reliable than post-processing with sed or similar.
The directive is `alias ORIG = ALIAS`, where ORIG and ALIAS are full account names. include path/to/file.journal
To forget all aliases defined to this point, use `end aliases`.
For an example, see [How to use account aliases](ALIASES.html). The `include` directive may only be used in journal files, and currently
it may only include other journal files (eg, not CSV or timelog files.)
### CSV files ### CSV files
@ -538,7 +544,7 @@ To generate time logs, ie to clock in and clock out, you could:
hledger provides a number of subcommands; run `hledger` with no arguments to see a list. hledger provides a number of subcommands; run `hledger` with no arguments to see a list.
Most subcommands are built in to the core hledger package; Most subcommands are built in to the core hledger package;
more [add-on commands](#add-on-commands) will appear if you install additional hledger-* packages. more [add-on commands](#add-on-commands) will appear if you install additional `hledger-*` packages.
You can also install your own subcommands by putting programs or scripts named `hledger-NAME` in your PATH. You can also install your own subcommands by putting programs or scripts named `hledger-NAME` in your PATH.
### Data entry ### Data entry
@ -606,7 +612,8 @@ An example:
### Reporting ### Reporting
These are the commands for querying your ledger. These are the commands for actually querying your ledger.
The most basic reporting commands are `print`, `register` and `balance`:
#### print #### print
@ -849,8 +856,10 @@ Examples:
## Reporting options ## Reporting options
The following additional features and options allow for fine-grained Part of hledger's usefulness is being able to report on just a precise
reporting. They are common to most commands, where applicable. subset of your data. The following common features and options work
with most subcommands, allowing you to specify search criteria and
adjust the output.
### Queries ### Queries
@ -900,12 +909,14 @@ With the [print](#print) command, they select transactions which
> *have no postings matching any of the negative account terms AND* > *have no postings matching any of the negative account terms AND*
> *match all the other terms* > *match all the other terms*
Note many of the above query terms can also be expressed as command-line Query expressions (mostly) work the same way on the command line and [web](#web) interfaces.
flags; you can use either, or both at once. Note that many query terms have equivalent (older) command-line flags.
You can mix and match query arguments and flags, but note that
[period expressions](#period-expressions) override other date queries.
### Smart dates ### Smart dates
Unlike the journal file, hledger's user interface accepts more flexible Unlike the journal file format, hledger's user interface accepts flexible
"smart dates", for example in the `-b` and `-e` options, period "smart dates", for example in the `-b` and `-e` options, period
expressions, display expressions, the add command and the web add form. expressions, display expressions, the add command and the web add form.
Smart dates allow some natural english words, will assume 1 where Smart dates allow some natural english words, will assume 1 where
@ -921,7 +932,7 @@ today's date. Examples:
- `last week` (the monday of the week before this one) - `last week` (the monday of the week before this one)
- `today`, `yesterday`, `tomorrow` - `today`, `yesterday`, `tomorrow`
Spaces in smart dates are optional, so eg: `-b lastmonth` is valid. Spaces in smart dates are optional, so eg `-b lastmonth` or `date:fromlastmonth` are valid.
### Period expressions ### Period expressions
@ -992,18 +1003,23 @@ options. But as noted above, a --period option will override these.
### Display expressions ### Display expressions
Unlike a [period expression](#period-expressions), which selects the A [period expression](#period-expressions) or other [query](#queries)
transactions to be used for calculation, a display expression (specified selects the transactions to be used for calculation. A display
with `-d/--display`) selects which transactions will be displayed. This expression, specified with `-d/--display`, selects a more limited
useful, say, if you want to see your checking register just for this subset of transactions to be displayed in the report output.
month, but with an accurate running balance based on all transactions. Eg:
This useful, say, if you want to see your checking register just for
this month, but with an accurate running balance based on all
transactions. Eg:
$ hledger register checking --display "d>=[1]" $ hledger register checking --display "d>=[1]"
meaning "make a register report of all checking transactions, but display meaning "make a register report of all checking transactions, but
only the ones with date on or after the 1st of this month." This the only display only the ones with date on or after the 1st of this month."
kind of display expression we currently support, ie transactions before or Any [smart date](#smart-dates) can appear inside the brackets.
after a given (smart) date.
The above the only kind of display expression we currently support:
transactions before or after a given date.
### Depth limiting ### Depth limiting