21d9945ba9
Using "hledgerdev" was a hack to help ensure that tests used a fresh developer build by default. Now they specify "hledger" again, which fits better with stack. It's up to the tester to make sure the desired executable is first in PATH or specified with -w. (Note a couple of tests currently don't obey -w and will always run "hledger", see addons.test).
134 lines
4.4 KiB
Plaintext
134 lines
4.4 KiB
Plaintext
# hledger command line processing
|
|
#
|
|
# Quick guide to terms used here:
|
|
#
|
|
# - flag: a synonym for option. Or, just the first part of an option,
|
|
# which can be either a short flag (hyphen followed by a letter) or
|
|
# a long flag (double hyphen followed by a word).
|
|
#
|
|
# - option: a command modifier. An option consists of a short flag, a
|
|
# long flag, or both, and possibly an optional or required value.
|
|
# Each option has some effect on program execution, and is described
|
|
# in the command line help.
|
|
#
|
|
# - raw arguments: everything following the program name on the
|
|
# command line, ie what is returned by getArgs.
|
|
#
|
|
# - parsed arguments: all raw arguments that are not options.
|
|
#
|
|
# - command arguments: all parsed arguments after the first, which is
|
|
# the command name.
|
|
#
|
|
# - RawOpts: the command name, options, and arguments parsed by cmdargs,
|
|
# as an assocation list of strings. Eg:
|
|
# [("command","register"),("args","a"),("debug",""),("help","")]
|
|
#
|
|
# - CliOpts: a RawOpts, plus the same information with some additional
|
|
# cleanup in a more convenient data structure. Used throughout the
|
|
# hledger CLI code.
|
|
#
|
|
# - command line, shell command: what you type in the shell or
|
|
# terminal window to start a program.
|
|
#
|
|
# - hledger command, subcommand: one of hledger's modes of operation,
|
|
# named and selected by the first parsed argument. There are two kinds:
|
|
# - internal or built-in commands are part of the main hledger executable.
|
|
# - external or add-on commands are provided by hledger-* executables in
|
|
# the PATH.
|
|
#
|
|
# Description of existing/expected behaviour as of 2013/9/16:
|
|
#
|
|
# - general usage is hledger [COMMAND] [OPTIONS] [ARGS]
|
|
#
|
|
# - commands are internal (built in to the main hledger executable) or external (any hledger-* executables found in the PATH)
|
|
# - some internal commands have aliases, which are displayed in the general help
|
|
# - there are also a few hidden internal commands
|
|
# - COMMAND is an exact command (balance), an alias (bal), or any unique command prefix (inc)
|
|
# - when COMMAND is a non-unique prefix, all matched commands will be listed, including hidden ones (eg hledger c)
|
|
# - an unrecognised command shows an error and gives non-zero exit status
|
|
#
|
|
# - usually the command must come first, followed by options and arguments in any order
|
|
# - a few options may also go before the command: -f, --rules-file, --alias, --help, --version, --debug.
|
|
# - option flags may be written in full or as a unique prefix, eg --rules for --rules-file
|
|
# - if the command is external, options and arguments after the command are handled by that executable, not hledger
|
|
#
|
|
# - the --help flag has highest priority
|
|
# - --help before the command (or no command) shows general help, including the commands list
|
|
# - --help after an internal command shows command-specific help, including command and general flags
|
|
# - there is no internal "help" command
|
|
|
|
# version
|
|
|
|
# 1. --version shows version
|
|
hledger --version
|
|
>>> /^hledger [0-9]/
|
|
>>>=0
|
|
|
|
# 2. --version also works after a command, if it's internal
|
|
hledger balance --version
|
|
>>> /^hledger [0-9]/
|
|
>>>=0
|
|
|
|
# help
|
|
|
|
# 3. with no command, show general help
|
|
hledger
|
|
>>> /^hledger \[COMMAND\]/
|
|
>>>=0
|
|
|
|
# 4. no-command help still works if there are flags, at least the common ones
|
|
hledger -fsomefile
|
|
>>> /^hledger \[COMMAND\]/
|
|
>>>=0
|
|
|
|
# 5. and also with a space between flag and value
|
|
hledger -f somefile
|
|
>>> /^hledger \[COMMAND\]/
|
|
>>>=0
|
|
|
|
# 6. with --help, and possibly other common flags present, show general help
|
|
hledger --help --version -f /dev/null
|
|
>>> /^hledger \[COMMAND\]/
|
|
>>>=0
|
|
|
|
# 7. with --help before COMMAND, show general help
|
|
hledger --help balance --cost
|
|
>>> /^hledger \[COMMAND\]/
|
|
>>>=0
|
|
|
|
# 8. with --help after command, show command help
|
|
hledger balance --help
|
|
>>> /^balance \[OPTIONS\]/
|
|
>>>=0
|
|
|
|
# 9. should work with deprecated commands too
|
|
hledger convert --help
|
|
>>>
|
|
>>>2 /no longer needed/
|
|
>>>=1
|
|
|
|
# 10. with an unrecognised command, give general help and non-zero exit status
|
|
hledger nosuchcommand
|
|
>>>
|
|
>>>2 /not recognized/
|
|
>>>=1
|
|
|
|
# flag positions
|
|
|
|
# 11. most flags can not go before command
|
|
hledger --daily register
|
|
>>>
|
|
>>>2 /Unknown flag: --daily/
|
|
>>>=1
|
|
|
|
# 12. help and input flags can go before command
|
|
hledger -f /dev/null --alias somealiases --rules-file -? -h --help --version --debug 1 register --daily
|
|
>>> /^hledger \[COMMAND\]/
|
|
>>>=0
|
|
|
|
# 13. or after it, and spaces in options are optional
|
|
hledger register -f/dev/null --alias=somealiases --rules-file -? -h --help --version --debug 1 --daily
|
|
>>> /^register \[OPTIONS\]/
|
|
>>>=0
|
|
|