From 0cd86d959eef4f74be8d99b6266c8d8c498bc537 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Thu, 6 Mar 2025 16:05:25 -1000 Subject: [PATCH] ;doc: update command docs --- hledger/Hledger/Cli/Commands/Demo.txt | 2 + hledger/Hledger/Cli/Commands/Register.txt | 8 +- hledger/Hledger/Cli/Commands/Repl.txt | 76 +++++++++++------- hledger/Hledger/Cli/Commands/Run.txt | 94 ++++++++++++----------- 4 files changed, 100 insertions(+), 80 deletions(-) diff --git a/hledger/Hledger/Cli/Commands/Demo.txt b/hledger/Hledger/Cli/Commands/Demo.txt index 280e759bd..406c9b927 100644 --- a/hledger/Hledger/Cli/Commands/Demo.txt +++ b/hledger/Hledger/Cli/Commands/Demo.txt @@ -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. diff --git a/hledger/Hledger/Cli/Commands/Register.txt b/hledger/Hledger/Cli/Commands/Register.txt index 24c34552d..7bfe615dd 100644 --- a/hledger/Hledger/Cli/Commands/Register.txt +++ b/hledger/Hledger/Cli/Commands/Register.txt @@ -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), diff --git a/hledger/Hledger/Cli/Commands/Repl.txt b/hledger/Hledger/Cli/Commands/Repl.txt index 6a524e332..e50120b36 100644 --- a/hledger/Hledger/Cli/Commands/Repl.txt +++ b/hledger/Hledger/Cli/Commands/Repl.txt @@ -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 will print out +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 diff --git a/hledger/Hledger/Cli/Commands/Run.txt b/hledger/Hledger/Cli/Commands/Run.txt index 537fc85ad..e686c9cca 100644 --- a/hledger/Hledger/Cli/Commands/Run.txt +++ b/hledger/Hledger/Cli/Commands/Run.txt @@ -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 will print out - 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