diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index beb3ee5c2..e6ef6dd6d 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -7,7 +7,6 @@ m4_dnl m4_dnl hledger.1.m4.md m4_dnl hledger_examples.m4.md m4_dnl hledger_options.m4.md -m4_dnl hledger_queries.m4.md m4_dnl hledger_commands.m4.md m4_dnl hledger_troubleshooting.m4.md @@ -66,8 +65,9 @@ try some commands like `hledger print` or `hledger balance`. Run `hledger` with no arguments for a list of commands. _include_(hledger_examples.m4.md) + _include_(hledger_options.m4.md) -_include_(hledger_queries.m4.md) + _include_(hledger_commands.m4.md) # ENVIRONMENT diff --git a/hledger/hledger_addons.m4.md b/hledger/hledger_addons.m4.md deleted file mode 100644 index 1a8b355fe..000000000 --- a/hledger/hledger_addons.m4.md +++ /dev/null @@ -1,68 +0,0 @@ -# ADD-ON COMMANDS - -hledger also searches for external add-on commands, and will include these in the commands list. -These are programs or scripts in your PATH whose name starts with `hledger-` -and ends with a recognised file extension -(currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`). - -Add-ons can be invoked like any hledger command, but there are a few things to be aware of. -Eg if the `hledger-web` add-on is installed, - -- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help. - -- Flags specific to the add-on must have a preceding `--` to hide them from hledger. - So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`. - -- You can always run add-ons directly if preferred: `hledger-web --serve --port 9000`. - -Add-ons are a relatively easy way to add local features or experiment with new ideas. -They can be written in any language, but haskell scripts have a big advantage: -they can use the same hledger (and haskell) library functions that built-in commands do, -for command-line options, journal parsing, reporting, etc. - -Here are some hledger add-ons available: - -## Official add-ons - -These are maintained and released along with hledger. - -### ui -[hledger-ui](hledger-ui.html) provides an efficient terminal interface. - -### web -[hledger-web](hledger-web.html) provides a simple web interface. - -## Third party add-ons - -These are maintained separately, and usually updated shortly after a hledger release. - -### iadd - -[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) -is a more interactive, terminal UI replacement for the [add command](hledger.html#add). - -### interest - -[hledger-interest](http://hackage.haskell.org/package/hledger-interest) -generates interest transactions for an account according to various schemes. - -## Experimental add-ons - -These are available in source form in the hledger repo's bin/ directory. -They may be less mature and documented than built-in commands. -Reading and tweaking these is a good way to start making your own! - -### autosync - -[hledger-autosync](https://github.com/simonmichael/hledger/blob/master/bin/hledger-autosync) -is a symbolic link for easily running -[ledger-autosync](https://pypi.python.org/pypi/ledger-autosync), if installed. -ledger-autosync does deduplicating conversion of OFX data and some CSV formats, -and can also download the data -[if your bank offers OFX Direct Connect](http://wiki.gnucash.org/wiki/OFX_Direct_Connect_Bank_Settings). - -### chart - -[hledger-chart.hs](https://github.com/simonmichael/hledger/blob/master/bin/_hledger-chart.hs#L47) -is an old very basic pie chart generator. - diff --git a/hledger/hledger_commands.m4.md b/hledger/hledger_commands.m4.md index 34f82ee90..664ece9da 100644 --- a/hledger/hledger_commands.m4.md +++ b/hledger/hledger_commands.m4.md @@ -132,4 +132,59 @@ _include_({{Hledger/Cli/Commands/Tags.md}}) _include_({{Hledger/Cli/Commands/Test.md}}) -_include_(hledger_addons.m4.md) + +## Add-on Commands + +hledger also searches for external add-on commands, and will include these in the commands list. +These are programs or scripts in your PATH whose name starts with `hledger-` +and ends with a recognised file extension +(currently: no extension, `bat`,`com`,`exe`, `hs`,`lhs`,`pl`,`py`,`rb`,`rkt`,`sh`). + +Add-ons can be invoked like any hledger command, but there are a few things to be aware of. +Eg if the `hledger-web` add-on is installed, + +- `hledger -h web` shows hledger's help, while `hledger web -h` shows hledger-web's help. + +- Flags specific to the add-on must have a preceding `--` to hide them from hledger. + So `hledger web --serve --port 9000` will be rejected; you must use `hledger web -- --serve --port 9000`. + +- You can always run add-ons directly if preferred: `hledger-web --serve --port 9000`. + +Add-ons are a relatively easy way to add local features or experiment with new ideas. +They can be written in any language, but haskell scripts have a big advantage: +they can use the same hledger (and haskell) library functions that built-in commands do, +for command-line options, journal parsing, reporting, etc. + +Two important add-ons are the hledger-ui and hledger-web user interfaces. +These are maintained and released along with hledger: + +### ui +[hledger-ui](hledger-ui.html) provides an efficient terminal interface. + +### web +[hledger-web](hledger-web.html) provides a simple web interface. + +Third party add-ons, maintained separately from hledger, include: + +### iadd + +[hledger-iadd](http://hackage.haskell.org/package/hledger-iadd) +is a more interactive, terminal UI replacement for the [add command](hledger.html#add). + +### interest + +[hledger-interest](http://hackage.haskell.org/package/hledger-interest) +generates interest transactions for an account according to various schemes. + + + + + + + + + + +A few more experimental or old add-ons can be found in hledger's bin/ +directory. These are typically prototypes and not guaranteed to work. + diff --git a/hledger/hledger_examples.m4.md b/hledger/hledger_examples.m4.md index 790a564f3..b243eaf17 100644 --- a/hledger/hledger_examples.m4.md +++ b/hledger/hledger_examples.m4.md @@ -2,7 +2,17 @@ m4_dnl Quick examples included early in the manual m4_dnl TODO make these and all the command examples pasteable/doctestable ? m4_dnl eg include -f FILE or $LEDGER_FILE details -# EXAMPLES +# COMMON TASKS + +Here are some quick examples of how to do some basic tasks with hledger. +For more background, see the reference section below, and the journal format manual. +For a more gentle introduction and additional how-tos, see the hledger.org website. + +## Starting a Journal + +## Setting Opening Balances + +## Recording Transactions Two simple transactions in hledger journal format: @@ -16,7 +26,9 @@ Two simple transactions in hledger journal format: assets:cash ``` -Some basic reports: +## Reconciling + +## Some basic reports ```shell $ hledger print @@ -54,7 +66,7 @@ $ hledger register cash 2015-10-16 farmers market assets:cash $-10 $10 ``` -More commands: +## More commands ```shell $ hledger # show available commands diff --git a/hledger/hledger_options.m4.md b/hledger/hledger_options.m4.md index a9e242d9b..508c6d14c 100644 --- a/hledger/hledger_options.m4.md +++ b/hledger/hledger_options.m4.md @@ -32,8 +32,6 @@ Or, you can run the addon executable directly: `hledger-ui --watch`. Most hledger commands accept arguments after the command name, which are often a [query](#queries), filtering the data in some way. -## Argument files - You can save a set of command line options/arguments in a file, and then reuse them by writing `@FILENAME` as a command line argument. Eg: `hledger bal @foo.args`. @@ -66,6 +64,105 @@ Good: See also: [Save frequently used options](save-frequently-used-options.html). +## Queries + +One of hledger's strengths is being able to quickly report on precise subsets of your data. +Most commands accept an optional query expression, written as arguments after the command name, +to filter the data by date, account name or other criteria. +The syntax is similar to a web search: +one or more space-separated search terms, +quotes to enclose whitespace, +prefixes to match specific fields, +a not: prefix to negate the match. + +We do not yet support arbitrary boolean combinations of search terms; +instead most commands show transactions/postings/accounts which match (or negatively match): + +- any of the description terms AND +- any of the account terms AND +- any of the status terms AND +- all the other terms. + +The [print](hledger.html#print) command instead shows transactions which: + +- match any of the description terms AND +- have any postings matching any of the positive account terms AND +- have no postings matching any of the negative account terms AND +- match all the other terms. + +The following kinds of search terms can be used. +Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount. + +**`REGEX`, `acct:REGEX`** +: match account names by this regular expression. (With no prefix, `acct:` is assumed.) + +: same as above + +**`amt:N, amt:N, amt:>=N`** +: match postings with a single-commodity amount that is equal to, less +than, or greater than N. (Multi-commodity amounts are not tested, and +will always match.) The comparison has two modes: if N is preceded by +a + or - sign (or is 0), the two signed numbers are +compared. Otherwise, the absolute magnitudes are compared, ignoring +sign. + +**`code:REGEX`** +: match by transaction code (eg check number) + +**`cur:REGEX`** +: match postings or transactions including any amounts whose +currency/commodity symbol is fully matched by REGEX. (For a partial +match, use `.*REGEX.*`). Note, to match characters which are +regex-significant, like the dollar sign (`$`), you need to prepend `\`. +And when using the command line you need to add one more level of +quoting to hide it from the shell, so eg do: `hledger print cur:'\$'` +or `hledger print cur:\\$`. + +**`desc:REGEX`** +: match transaction descriptions. + +**`date:PERIODEXPR`** +: match dates within the specified period. +PERIODEXPR is a [period expression](hledger.html#period-expressions) (with no report interval). +Examples: `date:2016`, `date:thismonth`, `date:2000/2/1-2/15`, `date:lastweek-`. +If the `--date2` command line flag is present, this matches [secondary dates](journal.html#secondary-dates) instead. + +**`date2:PERIODEXPR`** +: match secondary dates within the specified period. + +**`depth:N`** +: match (or display, depending on command) accounts at or above this depth + +**`note:REGEX`** +: match transaction [notes](journal.html#payee-and-note) +(part of description right of `|`, or whole description when there's no `|`) + +**`payee:REGEX`** +: match transaction [payee/payer names](journal.html#payee-and-note) +(part of description left of `|`, or whole description when there's no `|`) + +**`real:, real:0`** +: match real or virtual postings respectively + +**`status:, status:!, status:*`** +: match unmarked, pending, or cleared transactions respectively + +**`tag:REGEX[=REGEX]`** +: match by tag name, and optionally also by tag value. Note a +tag: query is considered to match a transaction if it matches any of +the postings. Also remember that postings inherit the tags of their +parent transaction. + +The following special search term is used automatically in hledger-web, only: + +**`inacct:ACCTNAME`** +: tells hledger-web to show the transaction register for this account. +Can be filtered further with `acct` etc. + +Some of these can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`). +Generally you can mix options and query arguments, and the resulting query will be their intersection +(perhaps excluding the `-p/--period` option). + ## Special characters in arguments and queries In shell command lines, option and argument values which contain "problematic" characters, @@ -823,3 +920,4 @@ meaning to the shell and so must be escaped at least once more. See [Special characters](#special-characters). + diff --git a/hledger/hledger_queries.m4.md b/hledger/hledger_queries.m4.md index 7c6510126..e69de29bb 100644 --- a/hledger/hledger_queries.m4.md +++ b/hledger/hledger_queries.m4.md @@ -1,98 +0,0 @@ -# QUERIES - -One of hledger's strengths is being able to quickly report on precise subsets of your data. -Most commands accept an optional query expression, written as arguments after the command name, -to filter the data by date, account name or other criteria. -The syntax is similar to a web search: -one or more space-separated search terms, -quotes to enclose whitespace, -prefixes to match specific fields, -a not: prefix to negate the match. - -We do not yet support arbitrary boolean combinations of search terms; -instead most commands show transactions/postings/accounts which match (or negatively match): - -- any of the description terms AND -- any of the account terms AND -- any of the status terms AND -- all the other terms. - -The [print](hledger.html#print) command instead shows transactions which: - -- match any of the description terms AND -- have any postings matching any of the positive account terms AND -- have no postings matching any of the negative account terms AND -- match all the other terms. - -The following kinds of search terms can be used. -Remember these can also be prefixed with **`not:`**, eg to exclude a particular subaccount. - -**`REGEX`, `acct:REGEX`** -: match account names by this regular expression. (With no prefix, `acct:` is assumed.) - -: same as above - -**`amt:N, amt:N, amt:>=N`** -: match postings with a single-commodity amount that is equal to, less -than, or greater than N. (Multi-commodity amounts are not tested, and -will always match.) The comparison has two modes: if N is preceded by -a + or - sign (or is 0), the two signed numbers are -compared. Otherwise, the absolute magnitudes are compared, ignoring -sign. - -**`code:REGEX`** -: match by transaction code (eg check number) - -**`cur:REGEX`** -: match postings or transactions including any amounts whose -currency/commodity symbol is fully matched by REGEX. (For a partial -match, use `.*REGEX.*`). Note, to match characters which are -regex-significant, like the dollar sign (`$`), you need to prepend `\`. -And when using the command line you need to add one more level of -quoting to hide it from the shell, so eg do: `hledger print cur:'\$'` -or `hledger print cur:\\$`. - -**`desc:REGEX`** -: match transaction descriptions. - -**`date:PERIODEXPR`** -: match dates within the specified period. -PERIODEXPR is a [period expression](hledger.html#period-expressions) (with no report interval). -Examples: `date:2016`, `date:thismonth`, `date:2000/2/1-2/15`, `date:lastweek-`. -If the `--date2` command line flag is present, this matches [secondary dates](journal.html#secondary-dates) instead. - -**`date2:PERIODEXPR`** -: match secondary dates within the specified period. - -**`depth:N`** -: match (or display, depending on command) accounts at or above this depth - -**`note:REGEX`** -: match transaction [notes](journal.html#payee-and-note) -(part of description right of `|`, or whole description when there's no `|`) - -**`payee:REGEX`** -: match transaction [payee/payer names](journal.html#payee-and-note) -(part of description left of `|`, or whole description when there's no `|`) - -**`real:, real:0`** -: match real or virtual postings respectively - -**`status:, status:!, status:*`** -: match unmarked, pending, or cleared transactions respectively - -**`tag:REGEX[=REGEX]`** -: match by tag name, and optionally also by tag value. Note a -tag: query is considered to match a transaction if it matches any of -the postings. Also remember that postings inherit the tags of their -parent transaction. - -The following special search term is used automatically in hledger-web, only: - -**`inacct:ACCTNAME`** -: tells hledger-web to show the transaction register for this account. -Can be filtered further with `acct` etc. - -Some of these can also be expressed as command-line options (eg `depth:2` is equivalent to `--depth 2`). -Generally you can mix options and query arguments, and the resulting query will be their intersection -(perhaps excluding the `-p/--period` option).