;doc: update command docs
This commit is contained in:
Simon Michael
parent
cdbbe40e5b
commit
0cd86d959e
@ -26,3 +26,5 @@ Examples:
|
||||
$ hledger demo # list available demos
|
||||
$ hledger demo 1 # play the first demo at default speed (2x)
|
||||
$ hledger demo install -s4 # play the "install" demo at 4x speed
|
||||
|
||||
This command is experimental: there aren't many useful demos yet.
|
||||
|
||||
@ -132,9 +132,8 @@ will be shown and the program exit code will be non-zero.
|
||||
|
||||
Custom register output
|
||||
|
||||
register uses the full terminal width by default, except on windows. You
|
||||
can override this by setting the COLUMNS environment variable (not a
|
||||
bash shell variable) or by using the --width/-w option.
|
||||
register normally uses the full terminal width (or 80 columns if it
|
||||
can't detect that). You can override this with the --width/-w option.
|
||||
|
||||
The description and account columns normally share the space equally
|
||||
(about half of (width - 40) each). You can adjust this by adding a
|
||||
@ -149,10 +148,7 @@ and some examples:
|
||||
|
||||
$ hledger reg # use terminal width (or 80 on windows)
|
||||
$ hledger reg -w 100 # use width 100
|
||||
$ COLUMNS=100 hledger reg # set with one-time environment variable
|
||||
$ export COLUMNS=100; hledger reg # set till session end (or window resize)
|
||||
$ hledger reg -w 100,40 # set overall width 100, description width 40
|
||||
$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40
|
||||
|
||||
This command also supports the output destination and output format
|
||||
options The output formats supported are txt, csv, tsv (Added in 1.32),
|
||||
|
||||
@ -1,49 +1,67 @@
|
||||
repl
|
||||
|
||||
Runs hledger commands interactively.
|
||||
|
||||
This command is EXPERIMENTAL and could change in the future.
|
||||
Start an interactive prompt, where you can run any of hledger's
|
||||
commands. Data files are parsed just once, so the commands run faster.
|
||||
|
||||
Flags:
|
||||
no command-specific flags
|
||||
|
||||
This command starts a read-eval-print loop (REPL) where you can enter
|
||||
commands interactively. To exit REPL, use "exit" or "quit", or send EOF.
|
||||
This command is experimental and could change in the future.
|
||||
|
||||
It could also accept commands from standard input, if you pipe commands
|
||||
into it.
|
||||
hledger repl starts a read-eval-print loop (REPL) where you can enter
|
||||
commands interactively. As with the run command, each input file (or
|
||||
each input file/input options combination) is parsed just once, so
|
||||
commands will run more quickly than if you ran them individually at the
|
||||
command line.
|
||||
|
||||
The commands will run more quickly than if run individually, because the
|
||||
input files would be parsed only once.
|
||||
Also like run, the input file(s) specified for the repl command will be
|
||||
the default input for all interactive commands, you can override this
|
||||
temporarily by specifying an -f option in particular commands, and
|
||||
commands will not see any changes made to input files (eg by add) until
|
||||
you exit and restart the REPL.
|
||||
|
||||
Syntax of the commands is intentionally simple: - each line is a single
|
||||
hledger command - empty lines are skipped - everything after # is
|
||||
considered to be a comment and will be ignored, and will not be printed
|
||||
out - echo <text> will print out <text>
|
||||
The command syntax is the same as with run:
|
||||
|
||||
You can use single or double quotes to quote arguments that need it
|
||||
('like this' or "like this").
|
||||
- enter one hledger command at a time, without the usual hledger first
|
||||
word
|
||||
- empty lines and comment text from # to end of line are ignored
|
||||
- use single or double quotes to quote arguments when needed
|
||||
- type exit or quit or control-D to exit the REPL.
|
||||
|
||||
Caveats:
|
||||
While it is running, the REPL remembers your command history, and you
|
||||
can navigate in the usual ways: - Keypad or Emacs navigation keys to
|
||||
edit the current command line - UP/DOWN or control-P/control-N to step
|
||||
back/forward through history - control-R to search for a past command,
|
||||
etc.
|
||||
|
||||
- Repl, like any other command, will load the input file(s) (specified
|
||||
by LEDGER_FILE or by -f arguments). The contents of those files
|
||||
would be used by all the commands that repl runs. If you want a
|
||||
particular command to use a different input file, you can use -f
|
||||
flag for that particular command. This will override (not add) the
|
||||
input for that particular command. All the input files would be
|
||||
cached, and would be read only once.
|
||||
The commands and help commands, and the command help flags (CMD --tldr,
|
||||
CMD -h/--help, CMD --info, CMD --man), work in the usual way, and can be
|
||||
useful.
|
||||
|
||||
Examples:
|
||||
You can type control-C to cancel a long-running command (but only once;
|
||||
typing it a second time will exit the REPL).
|
||||
|
||||
To start the REPL:
|
||||
And in most shells you can type control-Z to exit temporarily to the
|
||||
shell (and fg to return to the REPL).
|
||||
|
||||
Caveats
|
||||
|
||||
You may find some differences in behaviour between run command lines and
|
||||
normal hledger command lines. For example, in the REPL,
|
||||
|
||||
- the command name must be written first, options afterward
|
||||
- full command names or official abbreviations (as in the command
|
||||
list) must be used
|
||||
- options parsing with addon commands might be less flexible than the
|
||||
CLI
|
||||
- the stats command gives false timings, currently
|
||||
|
||||
Examples
|
||||
|
||||
Start the REPL:
|
||||
|
||||
hledger repl
|
||||
|
||||
or
|
||||
|
||||
hledger repl -f some.journal
|
||||
|
||||
To pipe commands into REPL:
|
||||
|
||||
(echo "files"; echo "stats") | hledger repl -f some.journal
|
||||
|
||||
@ -1,74 +1,78 @@
|
||||
run
|
||||
|
||||
Runs a sequence of hledger commands on the same input file(s), taking
|
||||
them from the command line or from file(s).
|
||||
|
||||
This command is EXPERIMENTAL and syntax could change in the future.
|
||||
Run a sequence of hledger commands, provided as files or command line
|
||||
arguments. Data files are parsed just once, so the commands run faster.
|
||||
|
||||
Flags:
|
||||
no command-specific flags
|
||||
|
||||
The commands will run more quickly than if run individually, because the
|
||||
input files would be parsed only once.
|
||||
This command is experimental and could change in the future.
|
||||
|
||||
"run" has three ways of invocation:
|
||||
You can use run in three ways:
|
||||
|
||||
- when all positional arguments of "run" are valid file names, "run"
|
||||
will read commands from these files, in order:
|
||||
run -f some.journal file1.txt file2.txt file3.txt.
|
||||
- hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command
|
||||
line, separated by --
|
||||
- hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
|
||||
files
|
||||
- cat SCRIPTFILE1 | hledger run - read commands from standard input.
|
||||
|
||||
- commands could be specified directly on the command line. All
|
||||
commands (including the very first one) should be preceded by
|
||||
argument "--": run -f some.journal -- cmd1 -- cmd2 -- cmd3.
|
||||
run first loads the input file(s) specified by LEDGER_FILE or by -f
|
||||
options, in the usual way. Then it runs each command in turn, each using
|
||||
the same input data. But if you want a particular command to use
|
||||
different input, you can specify an -f option within that command. This
|
||||
will override (not add to) the default input, just for that command.
|
||||
|
||||
- it could also accept commands from standard input, if you don't
|
||||
provide an positional arguments and pipe commands into it.
|
||||
Each input file (more precisely, each combination of input file and
|
||||
input options) is parsed only once. This means that commands will not
|
||||
see any changes made to these files, until the next run. But the
|
||||
commands will run more quickly than if run individually (typically about
|
||||
twice as fast).
|
||||
|
||||
Syntax of the command is intentionally simple: - each line read from a
|
||||
file is a single hledger command - empty lines are skipped - everything
|
||||
after # is considered to be a comment and will be ignored, and will not
|
||||
be printed out - echo <text> will print out <text> - run is a valid
|
||||
command to use as well, so you can have run call run if you want to.
|
||||
Command scripts, whether in a file or written on the command line, have
|
||||
a simple syntax:
|
||||
|
||||
You can use single or double quotes to quote arguments that need it
|
||||
('like this' or "like this").
|
||||
- each line may contain a single hledger command and its arguments,
|
||||
without the usual hledger first word
|
||||
- empty lines are ignored
|
||||
- text from # to end of line is a comment, and ignored
|
||||
- you can use single or double quotes to quote arguments when needed,
|
||||
as on the command line
|
||||
- these extra commands are available: echo TEXT prints some text, and
|
||||
exit or quit ends the run.
|
||||
|
||||
You can use #!/usr/bin/env hledger run in the first line of the file to
|
||||
make it a runnable script. If this complains about "binary hledger run
|
||||
not found", use /usr/bin/env -S hledger run.
|
||||
On unix systems you can use #!/usr/bin/env hledger run in the first line
|
||||
of a command file to make it a runnable script. If that gives an error,
|
||||
use #!/usr/bin/env -S hledger run.
|
||||
|
||||
Caveats:
|
||||
It's ok to use the run command recursively within a command script.
|
||||
|
||||
- If you meant to provide file name as an argument, but made a mistake
|
||||
and a gave file name that does not exist, "run" will attempt to
|
||||
interpret it as a command.
|
||||
Caveats
|
||||
|
||||
- Run, like any other command, will load the input file(s) (specified
|
||||
by LEDGER_FILE or by -f arguments). The contents of those files
|
||||
would be used by all the commands that run runs. If you want a
|
||||
particular command to use a different input file, you can use -f
|
||||
flag for that particular command. This will override (not add) the
|
||||
input for that particular command. All the input files would be
|
||||
cached, and would be read only once.
|
||||
You may find some differences in behaviour between run command lines and
|
||||
normal hledger command lines. For example, with run,
|
||||
|
||||
Examples:
|
||||
- the command name must be written first, options afterward
|
||||
- full command names or official abbreviations (as in the command
|
||||
list) must be used
|
||||
|
||||
Pipe commands into run, one per line:
|
||||
Examples
|
||||
|
||||
(echo "files"; echo "stats") | hledger repl -f some.journal
|
||||
Run commands specified on the command line:
|
||||
|
||||
To provide commands on the command line, separate them with --
|
||||
(including the first one):
|
||||
|
||||
hledger run -f some.journal -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats
|
||||
hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats
|
||||
|
||||
This would load some.journal, run balance assets --depth 2 on it, then
|
||||
run balance liabilities --depth 3 --transpose on /some/other.journal,
|
||||
and finally will run stats on some.journal
|
||||
and finally run stats on some.journal
|
||||
|
||||
To provide commands in the file, as a runnable scripts:
|
||||
Run commands from standard input:
|
||||
|
||||
(echo "files"; echo "stats") | hledger -f some.journal run
|
||||
|
||||
Provide commands as a runnable script:
|
||||
|
||||
#!/usr/bin/env -S hledger run -f some.journal
|
||||
|
||||
echo "List of accounts in some.journal"
|
||||
accounts
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user