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

;doc: special characters: updates

Browse Source
This commit is contained in:
Simon Michael 2024-10-16 15:05:57 -10:00
parent 391bd6fac9
commit 0dbcafdebb
1 changed files with 65 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
hledger/hledger.m4.md
View File

@ -273,13 +273,22 @@ feel free to skip these until you need them.
## Special characters ## Special characters
### Single escaping (for shell metacharacters) ### Single-escaping shell special characters
In shell command lines, characters significant to your shell - such as At the command line, characters which have special meaning for your shell -
spaces, `<`, `>`, `(`, `)`, `|`, `$` and `\` - should be such as spaces, `<`, `>`, `(`, `)`, `|`, `$` and `\` -
"shell-escaped" if you want hledger to see them. This is done by must be "shell-escaped" (AKA "quoted") if you want hledger to see them.
enclosing them in single or double quotes, or by writing a backslash In most shells this can be done by enclosing the argument containing them in single or double quotes.
before them. Eg to match an account name containing a space: In Unix shells, writing a backslash before the character also works.
For example, to match an account name containing the phrase "credit card", don't write this
(which will match accounts containing "credit" or "card"):
```cli
$ hledger register credit card
```
Instead, write:
```cli ```cli
$ hledger register "credit card" $ hledger register "credit card"
@ -291,7 +300,7 @@ or:
$ hledger register 'credit card' $ hledger register 'credit card'
``` ```
or: or (in a Unix shell):
```cli ```cli
$ hledger register credit\ card $ hledger register credit\ card
@ -299,23 +308,22 @@ $ hledger register credit\ card
### Escaping on Windows ### Escaping on Windows
If you are using hledger on Microsoft Windows, unless you are using a Unix-like shell (such Windows Subsystem for Linux), If you are using hledger in a Powershell or Command window on Microsoft Windows, the escaping rules are different:
be aware that the escaping rules are different. In particular:
- In a powershell window (`powershell`, blue background), you must use double quotes or single quotes (not backslash). - In a Powershell window (`powershell`, blue background), you must use double quotes or single quotes (not backslash).
- In a command window (`cmd`, black background), you must use double quotes (not single quotes or backslash). - In a Command window (`cmd`, black background), you must use double quotes (not single quotes or backslash).
The following sections assume a Unix-like shell, and will need to be adapted if you're using `cmd` or `powershell`. (Edits welcome.) The next two sections were written for Unix-like shells, so might need to be adapted if you're using `cmd` or `powershell`. (Edits welcome.)
### Double escaping (for regular expression metacharacters) ### Double-escaping regular expression special characters
Characters significant in [regular expressions] Characters which have special meaning in [regular expressions] (described below),
(described below) - such as `.`, `^`, `$`, `[`, `]`, `(`, `)`, `|`, such as `.`, `^`, `$`, `[`, `]`, `(`, `)`, `|`, and `\`,
and `\` - may need to be "regex-escaped" if you don't want them to be may need to be "regex-escaped" if you don't want them to be interpreted by hledger's regular expression engine.
interpreted by hledger's regular expression engine. This is done by This is done by writing backslashes before them.
writing backslashes before them, but since backslash is typically also But since backslash is usually also special to the shell, both shell-escaping and regex-escaping will be needed.
a shell metacharacter, both shell-escaping and regex-escaping will be
needed. Eg to match a literal `$` sign while using the bash shell: Eg, to match a literal `$` sign while using the bash shell, you could write:
```cli ```cli
$ hledger balance cur:'\$' $ hledger balance cur:'\$'
@ -327,13 +335,14 @@ or:
$ hledger balance cur:\\$ $ hledger balance cur:\\$
``` ```
### Triple escaping (for add-on commands) ### Triple-escaping add-on command arguments
When you use hledger to run an external add-on command (described When you run an external add-on command with `hledger` (described below),
below), one level of shell-escaping is lost from any options or any options or arguments being passed through to the add-on command will lose one level of shell-escaping.
arguments intended for by the add-on command, so those need an extra So those will need an extra level of shell-escaping.
level of shell-escaping. Eg to match a literal `$` sign while using Or, you can avoid this issue by running the add-on executable directly.
the bash shell and running an add-on command (`ui`):
So, to match a literal `$` sign while using the bash shell and running the `ui` add-on, you could write:
```cli ```cli
$ hledger ui cur:'\\$' $ hledger ui cur:'\\$'
@ -345,7 +354,13 @@ or:
$ hledger ui cur:\\\\$ $ hledger ui cur:\\\\$
``` ```
If you wondered why *four* backslashes, perhaps this helps: or (running the add-on executable directly):
```cli
$ hledger-ui cur:\\$
```
If you're wondering why there's *four* backslashes in the second example, perhaps this helps:
| | | | | |
|-----------------|---------| |-----------------|---------|
@ -354,24 +369,33 @@ If you wondered why *four* backslashes, perhaps this helps:
| double-escaped: | `\\$` | | double-escaped: | `\\$` |
| triple-escaped: | `\\\\$` | | triple-escaped: | `\\\\$` |
Or, you can avoid the extra escaping by running the add-on executable directly:
### Escaping in other contexts
hledger options and arguments are sometimes used in places other than the command line, where the escaping rules can be different.
Windows has been mentioned above; here are some more notes.
| ||
|:----------------------------------|:--------------------------------------------------------------------------------------------
| In Windows `cmd` | Use double quotes
| In Windows `powershell` | Use single or double quotes
| In hledger-ui's `/` filter prompt | Use single or double quotes
| In hledger-web's search form | Use single or double quotes
| In an [argument file] | Use one less level of quoting than the command line, and avoid spaces
| In a [config file] | Use single or double quotes, and enclose the whole argument<br> (`"desc:a b"` not `desc:"a b"`)
| In GHCI (the Haskell REPL) | Use double quotes, enclosing the whole argument.
[argument file]: #argument-files
[config file]: #config-files
When escaping a special character is too much hassle, or even impossible,
you can often work around by writing `.` (period), which in regular expressions means any character.
Eg:
```cli ```cli
$ hledger-ui cur:\\$ $ hledger register credit.card
``` ```
### Less escaping
Options and arguments are sometimes used in places other than the
shell command line, where shell-escaping is not needed, so there you
should use one less level of escaping. Those places include:
- an @argumentfile
- hledger-ui's filter field
- hledger-web's search form
- GHCI's prompt (used by developers).
## Unicode characters ## Unicode characters
hledger is expected to handle non-ascii characters correctly: hledger is expected to handle non-ascii characters correctly: