This repository contains eight command line tools built using the MainFunction macro provided
by provided by cmd-arg-lib.
This example uses three simple types, a Flag, String and an Optional Int, and a meta-flag, "--help". It uses a typealias for String to clarify the code and enhance the help screen.
This example shows how to use enums as basic parameter types in a command function. The command function shows the use of a default value, an optional type, a required type (i.e., with no default value), and a postional parameter.
This example shows how to use arrays and variadics.
This example shows how to validate input data and handle i/o errors.
It also shows how the code generated by the MainFunction macro automatically
handles errors, including system I/O errors not handled by the annotated command
function.
This example shows the use of positional parameters in a command function. It is recommended that a CLI have at most one positional parameter. This example shows why.
This example shows the use of show macros, which can be used to insert formatted label and type names in meta services text. This is especially useful for composing manual pages in which label and type names should be formatted in descriptive text using standard mdoc formats.
This example shows
- how to add completion scripts
- how to set up unit tests, including "CLI level" unit tests
Add a completion constructor for the fish or the zsh shell by adding a MetaFlag parameter to the command function. E.g.,
generateFishCompletionScript fish: MetaFlag = MetaFlag(completionScriptFor: .fish, name: "mf7-completion", showElements: helpElements),Set up CLI level tests in a test file:
- import Swfit's Testing Module, CmdArgLib, and the targets to be tested
- set up tests using the
testOutputandtestReturnfunctions provided by CmdArgLib - For each test
- run the program in the terminal
- copy the arguments passed to the program and the program's output
- paste the arguments and output into the test
CLI Level Test Example
> mf7-completion -iuxyz --count
Errors:
unrecognized options: "-x", "-y" and "-z", in "-iuxyz"
missing expected value after "--count"
missing a "<animal>"
See "mf7-completion --help" for more information.
@Test func ErrorsTest() {
let input = "-iuxyz --count"
let output = """
Errors:
unrecognized options: "-x", "-y" and "-z", in "-iuxyz"
missing expected value after "--count"
missing a "<animal>"
See "mf7-completion --help" for more information.
"""
let ok = testOutput(of: Example_7_CompletionSupport.run, with: input, expecting: output)
#expect(ok)
}The testOutput and testReturn functions do not invoke a subprocess. Rather, they call the run function
generated by the MainFunction macro directly. Accordingly, the annotated command function must
throw instances of CmdArgLib's Exception.stdout and Exception.stderr, rather than write directly to stdout and stderr.
This example wraps sed. The code is more complex than usual because sed has two ways of being called, and the two calls use postional parameters differently. Another complication is that the order of option arguments in a command argument list affects how the program runs.
Help Screen
> ./mf8-sed --help
DESCRIPTION
A sed wrapper.
USAGE
mf8-sed [-np] [-i <extension>] <command> [<file>...]
mf8-sed [-np] [-i <extension>] [-e <command>] [-f <command_file>] [<file>...]
OPTIONS
-n/--quiet By default, each line of input is echoed to the
standard output after all of the commands have been
applied to it. The -n option suppresses this
behavior.
-p/--preview Print the genrated sed command without executing it.
-i/--inplace <extension> Edit the <file>s in-place, saving backups with the
specified <extension>. If a zero-length extension is
given (""), no backup will be saved.
-e/--expression <command> Append <command> to the list of editing <command>s
(may be repeated).
-f/--command-file <command_file> Append the editing <command>s found in the file
<command_file> to the list of editing <command>s (may
be repeated). The editing commands should each be
listed on a separate line. The <command>s are read
from the standard input if <command_file> is “-”.
NOTES
The mf8-sed utility reads the specified <file>s, or the standard input if no <file>s
are specified, modifying the input as specified by a list of <command>s. The input is
then written to the standard output.
A single <command> may be specified as the first argument to mf8-sed, in which case no
-e or -f options are allowed. Multiple <command>s may be specified by using the -e or
-f options, in which case all arguments are <file>s. All <command>s are applied to the
input in the order they are specified regardless of their origin.
Regular expressions are always interpreted as extended (modern) regular expressions.
Manual Page
Command Calls
> echo FOO > foo.text
> ./mf8-sed s/FOO/BAR/ foo.text
BAR
#### --- ⚠️ Something is wrong with sed (or its manual page's first synopsis) --- ###
> echo FOO > foo.text
> sed s/FOO/BAR/ -i~ foo.text
sed: -i~: No such file or directory
BAR
> cat foo.text
FOO
> cat foo.text~
cat: foo.text~: No such file or directory
#### --- 👍 mf8-sed to to the rescue --- ###
> echo FOO > foo.text
> ./mf8-sed s/FOO/BAR/ -i~ foo.text
> cat foo.text; cat foo.text~
BAR
FOO
It is recommended to download and install caltool.
The caltool utility makes it easy to build, install, and uninstall command line tools built using cmd-arg-lib.
Clone and Build CmdArgLib_MainFunction
> rm -rf Demo && mkdir Demo && cd Demo
Demo> git clone https://github.com/ouser4629/CmdArgLib_MainFunction.git
Demo> cd CmdArgLib_MainFunction
> swift build -c release
...Install CmdArgLib_MainFunction Products Locally
CmdArgLib_MainFunction> caltool install -s fish zsh
mf1-greet
installed "mf1-greet" in /Users/po/.local/bin
mf2-enums
installed "mf2-enums" in /Users/po/.local/bin
mf3-lists
installed "mf3-lists" in /Users/po/.local/bin
mf4-errors
installed "mf4-errors" in /Users/po/.local/bin
mf5-positionals
installed "mf5-positionals" in /Users/po/.local/bin
mf6-show-macros
installed "mf6-show-macros" in /Users/po/.local/bin
mf7-completion
installed "mf7-completion" in /Users/po/.local/bin
installed "mf7-completion.fish" in /Users/po/.config/fish/completions
installed "_mf7-completion" in /Users/po/.config/zsh/completions
mf8-sed
installed "mf8-sed" in /Users/po/.local/bin
installed "mf8-sed.1" in /Users/po/.local/share/man/man1Run Selected Products
CmdArgLib_MainFunction> mf1-greet -h
DESCRIPTION: Print a greeting.
USAGE: [-uh] [--count <int>] <a_phrase>
PARAMETERS:
<a_phrase> A friendly greeting.
-u Uppercase the greeting.
--count <int> The number of times to print the greeting (default: 1).
-h/--help Show this help message.Open mf8-sed's ManPage
## Press "q" to get out of less
CmdArgLib_MainFunction> man mf8-sed
Uninstall Products
CmdArgLib_MainFunction> caltool uninstall
mf1-greet
uninstalled "mf1-greet" in /Users/po/.local/bin
mf2-enums
uninstalled "mf2-enums" in /Users/po/.local/bin
mf3-lists
uninstalled "mf3-lists" in /Users/po/.local/bin
mf4-errors
uninstalled "mf4-errors" in /Users/po/.local/bin
mf5-positionals
uninstalled "mf5-positionals" in /Users/po/.local/bin
mf6-show-macros
uninstalled "mf6-show-macros" in /Users/po/.local/bin
mf7-completion
uninstalled "mf7-completion" in /Users/po/.local/bin
uninstalled "mf7-completion.fish" in /Users/po/.config/fish/completions
uninstalled "_mf7-completion" in /Users/po/.config/zsh/completions
mf8-sed
uninstalled "mf8-sed" in /Users/po/.local/bin
uninstalled "mf8-sed.1" in /Users/po/.local/share/man/man1