From 8c5aa130e76e6bb50e9b70929c2e7d811c2eba01 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 7 Feb 2020 12:14:43 -0800 Subject: [PATCH] ;doc: hledger: reorder OPTIONS sections, move one to COMMON TASKS [ci skip] --- hledger/hledger_examples.m4.md | 15 +++- hledger/hledger_options.m4.md | 123 +++++++++++++++------------------ 2 files changed, 69 insertions(+), 69 deletions(-) diff --git a/hledger/hledger_examples.m4.md b/hledger/hledger_examples.m4.md index 78fd7faf4..2421b6423 100644 --- a/hledger/hledger_examples.m4.md +++ b/hledger/hledger_examples.m4.md @@ -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 . -## 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: +## 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: diff --git a/hledger/hledger_options.m4.md b/hledger/hledger_options.m4.md index 508c6d14c..c6cea02dd 100644 --- a/hledger/hledger_options.m4.md +++ b/hledger/hledger_options.m4.md @@ -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). - - -