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

;doc: hledger: reorder OPTIONS sections, move one to COMMON TASKS

Browse Source 
[ci skip]
This commit is contained in:
Simon Michael 2020-02-07 12:14:43 -08:00
parent 202d2e945b
commit 8c5aa130e7
2 changed files with 69 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
hledger/hledger_examples.m4.md
View File

@ -8,7 +8,7 @@ Here are some quick examples of how to do some basic tasks with hledger.
For more details, see the reference section below, the hledger_journal(5) manual,
or the more extensive docs at <https://hledger.org>.
## Get help
## Getting help
```shell
$ hledger # show available commands
@ -23,6 +23,19 @@ $ hledger help --help # show more detailed help for the help command
Find more docs, chat, mail list, reddit, issue tracker:
<https://hledger.org#help-feedback>
## Constructing a command line
hledger has an extensive and powerful command line interface. We
strive to keep it simple and ergonomic, but you may run into one of
the confusing real world details described in OPTIONS, below.
If that happens, here are some tips that may help:
- command-specific options must go after the command (it's fine to put all options there) (`hledger CMD OPTS ARGS`)
- running add-on executables directly simplifies command line parsing (`hledger-ui OPTS ARGS`)
- enclose "problematic" args in single quotes
- if needed, also add a backslash to hide regular expression metacharacters from the shell
- to see how a misbehaving command is being parsed, add `--debug=2`.
## Starting a Journal
hledger looks for your accounting data in a journal file, `$HOME/.hledger.journal` by default:

123
hledger/hledger_options.m4.md
View File

@ -223,17 +223,6 @@ Eg:
`ghci> :main balance cur:\$`
## Command line tips
If in doubt, keep things simple:
- write options after the command (`hledger CMD -OPTIONS ARGS`)
- run add-on executables directly (`hledger-ui -OPTIONS ARGS`)
- enclose problematic args in single quotes
- if needed, also add a backslash to escape regexp metacharacters
To find out exactly how a command line is being parsed, add `--debug=2` to troubleshoot.
## Unicode characters
hledger is expected to handle non-ascii characters correctly:
@ -316,6 +305,61 @@ There are some limitations with this:
If you need those, either use the [include directive](journal.html#including-other-files),
or concatenate the files, eg: `cat a.journal b.journal | hledger -f- CMD`.
## Output destination
Some commands (print, register, stats, the balance commands)
can write their output to a destination other than the console.
This is controlled by the `-o/--output-file` option.
```shell
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE
```
## Output format
Some commands can write their output in other formats.
Eg print and register can output CSV, and the balance commands can output CSV or HTML.
This is controlled by the `-O/--output-format` option, or by specifying a `.csv` or `.html` file extension with `-o/--output-file`.
```shell
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv
```
## Regular expressions
hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places:
- [query terms](#queries), on the command line and in the hledger-web search form: `REGEX`, `desc:REGEX`, `cur:REGEX`, `tag:...=REGEX`
- [CSV rules](#csv-rules) conditional blocks: `if REGEX ...`
- [account alias](#rewriting-accounts) directives and options: `alias /REGEX/ = REPLACEMENT`, `--alias /REGEX/=REPLACEMENT`
hledger's regular expressions come from the
[regex-tdfa](http://hackage.haskell.org/package/regex-tdfa/docs/Text-Regex-TDFA.html)
library. In general they:
- are case insensitive
- are infix matching (do not need to match the entire thing being matched)
- are [POSIX extended regular expressions](http://www.regular-expressions.info/posix.html#ere)
- also support [GNU word boundaries](http://www.regular-expressions.info/wordboundaries.html) (\\<, \\>, \\b, \\B)
- and parenthesised [capturing groups](http://www.regular-expressions.info/refcapture.html) and numeric backreferences in replacement strings
- do not support [mode modifiers](http://www.regular-expressions.info/modifiers.html) like (?s)
Some things to note:
- In the `alias` directive and `--alias` option, regular expressions
must be enclosed in forward slashes (`/REGEX/`). Elsewhere in hledger,
these are not required.
- In queries, to match a regular expression metacharacter like `$`
as a literal character, prepend a backslash. Eg to search for amounts with the
dollar sign in hledger-web, write `cur:\$`.
- On the command line, some metacharacters like `$` have a special
meaning to the shell and so must be escaped at least once more.
See [Special characters](#special-characters).
## Smart dates
hledger's user interfaces accept a flexible "smart date" syntax (unlike dates in the journal file).
@ -864,60 +908,3 @@ Related:
The rightmost of these flags wins.
## Output destination
Some commands (print, register, stats, the balance commands)
can write their output to a destination other than the console.
This is controlled by the `-o/--output-file` option.
```shell
$ hledger balance -o - # write to stdout (the default)
$ hledger balance -o FILE # write to FILE
```
## Output format
Some commands can write their output in other formats.
Eg print and register can output CSV, and the balance commands can output CSV or HTML.
This is controlled by the `-O/--output-format` option, or by specifying a `.csv` or `.html` file extension with `-o/--output-file`.
```shell
$ hledger balance -O csv # write CSV to stdout
$ hledger balance -o FILE.csv # write CSV to FILE.csv
```
## Regular expressions
hledger uses [regular expressions](http://www.regular-expressions.info) in a number of places:
- [query terms](#queries), on the command line and in the hledger-web search form: `REGEX`, `desc:REGEX`, `cur:REGEX`, `tag:...=REGEX`
- [CSV rules](#csv-rules) conditional blocks: `if REGEX ...`
- [account alias](#rewriting-accounts) directives and options: `alias /REGEX/ = REPLACEMENT`, `--alias /REGEX/=REPLACEMENT`
hledger's regular expressions come from the
[regex-tdfa](http://hackage.haskell.org/package/regex-tdfa/docs/Text-Regex-TDFA.html)
library. In general they:
- are case insensitive
- are infix matching (do not need to match the entire thing being matched)
- are [POSIX extended regular expressions](http://www.regular-expressions.info/posix.html#ere)
- also support [GNU word boundaries](http://www.regular-expressions.info/wordboundaries.html) (\\<, \\>, \\b, \\B)
- and parenthesised [capturing groups](http://www.regular-expressions.info/refcapture.html) and numeric backreferences in replacement strings
- do not support [mode modifiers](http://www.regular-expressions.info/modifiers.html) like (?s)
Some things to note:
- In the `alias` directive and `--alias` option, regular expressions
must be enclosed in forward slashes (`/REGEX/`). Elsewhere in hledger,
these are not required.
- In queries, to match a regular expression metacharacter like `$`
as a literal character, prepend a backslash. Eg to search for amounts with the
dollar sign in hledger-web, write `cur:\$`.
- On the command line, some metacharacters like `$` have a special
meaning to the shell and so must be escaped at least once more.
See [Special characters](#special-characters).