hledger/tests/cli/cli.test

# 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 association 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]/
>>>2
>>>=0

# 2. --version also works after a command, if it's internal
hledger balance --version
>>> /^hledger [0-9]/
>>>2
>>>=0

# help

# 3. with no command, show commands list
hledger
>>> /^Commands/
>>>2
>>>=0

# 4. no-command help still works if there are flags, at least the common ones
hledger -fsomefile
>>> /^Commands/
>>>2
>>>=0

# 5. and also with a space between flag and value
hledger -f somefile
>>> /^Commands/
>>>2
>>>=0

# 6. with -h, and possibly other common flags present, show general usage
hledger -h --version -f /dev/null
>>> /^hledger \[CMD\]/
>>>2
>>>=0

# 7. with -h before COMMAND, show general usage
hledger -h balance --cost
>>> /^hledger \[CMD\]/
>>>2
>>>=0

# 8. with -h after command, show command usage
hledger balance -h
>>> /balance \[OPTIONS\]/
>>>2
>>>=0

# 9. with an unrecognised command, give an error and non-zero exit status
hledger nosuchcommand
>>>
>>>2 /not recognized.*to see a list/
>>>=1

# flag positions

# 10. general flags can go before command
hledger -f /dev/null --alias somealiases --rules-file -h --help --version --debug 1 --daily register
>>> /^hledger \[CMD\]/
>>>2
>>>=0

# 11. or after it, and spaces in options are optional
hledger register -f/dev/null --alias=somealiases --rules-file -h --version --debug 1 --daily
>>> /^register \[OPTIONS\]/
>>>2
>>>=0

# 12. general flags before command should work
hledger -f /dev/null --daily register
>>>
>>>2
>>>=0

# 13. command-specific flags can go after command
hledger -f /dev/null register --daily
>>>
>>>2
>>>=0

# 14. but not before it
hledger --related register
>>>
>>>2 /Unknown flag: --related/
>>>=1