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

cli: clarify spec

Browse Source
This commit is contained in:
Simon Michael 2014-04-27 23:33:13 -07:00
parent f3c90a1351
commit dbd35fbe3e
1 changed files with 27 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
tests/command-line.test
View File

@ -2,38 +2,39 @@
# #
# Quick guide to terms used here: # Quick guide to terms used here:
# #
# - flag: generally a synonym for option. Or sometimes, just the first # - flag: a synonym for option. Or, just the first part of an option,
# part of an option: a hyphen followed by a letter (short flag) or a # which can be either a short flag (hyphen followed by a letter) or
# word (long flag). # a long flag (double hyphen followed by a word).
# #
# - option: a command modifier. An option consists of a short flag, a # - option: a command modifier. An option consists of a short flag, a
# long flag, or both, and possibly an optional or required value. # long flag, or both, and possibly an optional or required value.
# Each option has some effect on program execution, and is described # Each option has some effect on program execution, and is described
# in the command line help. # in the command line help.
# #
# - argument: # - raw arguments: everything following the program name on the
# - raw command line arguments: everything following the program # command line, ie what is returned by getArgs.
# name on the command line, ie what is returned by getArgs
# - parsed arguments: all raw command line arguments that are not
# options (flags or values).
# - (sub)command arguments: all parsed arguments except the first
# (which is the subcommand's name)
# #
# - RawOpts: the command, options and arguments as parsed by cmdargs, # - parsed arguments: all raw arguments that are not options.
# as an assocation list. Eg: #
# - 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","")] # [("command","register"),("args","a"),("debug",""),("help","")]
# #
# - CliOpts: the command, options and arguments from cmdargs, plus # - CliOpts: a RawOpts, plus the same information with some additional
# additional cleanup, in a more convenient data structure used # cleanup in a more convenient data structure. Used throughout the
# throughout the hledger CLI code. # hledger CLI code.
# #
# - command: # - command line, shell command: what you type in the shell or
# - command line, shell command: what you type in the shell/terminal window to start a program # terminal window to start a program.
# - hledger command, subcommand: one of hledger's several modes of operation, #
# usually selected by the first command-line argument that isn't an option. # - hledger command, subcommand: one of hledger's modes of operation,
# Commands are listed in the general command line help. There are two kinds: # named and selected by the first parsed argument. There are two kinds:
# - internal commands: built in to the main hledger executable # - internal or built-in commands are part of the main hledger executable.
# - external commands, or add-ons: any other hledger-* executables in the users's PATH # - external or add-on commands are provided by hledger-* executables in
# the PATH.
# #
# Description of existing/expected behaviour as of 2013/9/16: # Description of existing/expected behaviour as of 2013/9/16:
# #
@ -42,8 +43,8 @@
# - commands are internal (built in to the main hledger executable) or external (any hledger-* executables found in the PATH) # - 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 # - some internal commands have aliases, which are displayed in the general help
# - there are also a few hidden internal commands # - there are also a few hidden internal commands
# - COMMAND is an exact command or alias name, or any unique prefix of one (eg reg for register) # - COMMAND is an exact command (balance), an alias (bal), or any unique command prefix (inc)
# - when COMMAND is a non-unique prefix, matching commands will be listed, including hidden ones (eg hledger c) # - 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 # - 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 # - usually the command must come first, followed by options and arguments in any order
@ -52,9 +53,9 @@
# - if the command is external, options and arguments after the command are handled by that executable, not hledger # - if the command is external, options and arguments after the command are handled by that executable, not hledger
# #
# - the --help flag has highest priority # - the --help flag has highest priority
# - --help before the command, or no command, shows general help, including available commands # - --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 # - --help after an internal command shows command-specific help, including command and general flags
# - there is no built-in "help" command # - there is no internal "help" command
# version # version