-
Notifications
You must be signed in to change notification settings - Fork 30
Common command line options
Many of the AQUARIUS Time-Series console utilities share some common logic for parsing command-line arguments.
Taking some time to understand how command line options are processed can help you make the most out of the open source tools provided by the Aquatic Informatics community.
Command line arguments are Name=value pairs, and you are free to use either the CMD.EXE style of /Name=value or the bash / PowerShell style of -name=value. This allows you to easily invoke the utilities from your favorite shell without worrying about ugly escape sequences.
C:\> MyTool.exe /SomeOption=SomeValueis treated the same as:
$ mytool -someOption=SomeValueIf you can't remember all the command-line details, simply add a /help or -? should give you a better idea of what a tool does.
Command line parsing tries to be as case-insensitive as possible, to be more wrist-friendly.
The "Name" portion of /Name=value or -name=value is always case-insensitive, but the "value" portion may not be case-insensitive. That behaviour will be option-specific, so you'll need to check the tool's help page for details.
TL;DR - Use "double-quotes" to surround any significant whitespace on the command line. Don't use quotes from within an @options.txt file (see below for details)
Our console-based tools can be launched from a number of different command shells on a Windows system. All shells use spaces to separate command-line options by default, but each shell has different rules on how to include a space an argument.
Here is a table showing how you can set a option called ReportName with a value contain a space.
| Context | Double quotes? | Single quotes? | Example |
|---|---|---|---|
| CMD | Y | N |
-ReportName="My Report" CMD.exe is the default command prompt on Windows. |
| PowerShell | Y | Y |
-ReportName="My Report"-ReportName='My Report' PowerShell supports single or double quotes. The starting quote character must match the ending quote character. |
| bash | Y | Y |
-ReportName="My Report"-ReportName='My Report' Bash (and other *nix shells) supports single or double quotes. The starting quote character must match the ending quote character. |
@options.txt |
N | N |
-ReportName=My Report The @options.txt format treats each line as separate argument, so no special quote characters are required to include a value containing a space. |
All the console utilities allow you to specify some or all of your command line options in a text file.
This allows you to quickly replace a bulky command line like this:
C:\> mytool /Option1="Some value with spaces" -option2=123.45 /SomeOtherReallyObscureSetting=SomeOtherMagicValuewith all the options stored in a file named "options.txt":
C:\> mytool @options.txtThe "options.txt" file would look like this 5-line text file:
/Option1=Some value with spaces
-option2=123.45
# Note: Fred added the right magic value on 2017-Feb-28.
/SomeOtherReallyObscureSetting=SomeOtherMagicValueWhen a command-line argument begins with an at-sign (@), instead of a forward-slash (/) or minus-sign (-), the rest of the argument after the at-sign is treated as filename with UTF-8 encoding assumed.
- Each line in the file is treated as a command line option.
- Blank lines and leading/trailing whitespace are ignored.
- Comment lines begin with a
#or//marker.
The filename can be anything. The example above used "options.txt" but you could use any filename, including a file in another folder. This next example uses an options file stored on the D: drive:
C:\> mytool @D:\someFolder\MyOtherOptions.optCommand shells (CMD.EXE, bash.exe and PowerShell.exe) separate their commands and arguments with spaces. So when your argument needs to contain a space, things get a bit messy. You typically need to surround the value in quotes, or use an escape-character of some sort. These approaches are completely specific to the shell you use.
In CMD.EXE, you can use double quotes (") to surround a string containing spaces, or you can use the caret (^) as an escape character. All three command lines below are equivalent. CMD.EXE takes care of interpreting the double-quote or caret characters. The mytool.exe code receives the same input regardless.
C:\> mytool /Title=This^ is^ my^ title
C:\> mytool /Title="This is my title"
C:\> mytool "/Title=This is my title"When you specify that same command line argument in an @options.txt file, it is simply:
/Title=This is my title
Some shells support multi-lingual characters, and others don't, or only support common Latin characters but not other language character sets.
Because the @options.txt file supports UTF-8, you can reliably use Unicode characters in values as needed.
/Title=❤️ Made With Love ❤️
All of these command line arguments can be a bit cryptic to decypher later on.
The @options.txt syntax allows for comment lines which begin with a (#) or a (//) marker. Combined with blank lines, this allows you to easily document why certain parameters are being specified.
Your future self will thank you!
The command line can mix any number of /Name=value, '-name=value, and @options.txt` arguments together.
- Arguments are processed in the order they appear on the command line, from left to right.
- When an
@options.txtfile is encountered, the file is read, stripped of comments and blank lines, and the remaining lines from the file are injected into the command line argument collection, instead of the named@filename.ext. - The utility doesn't actually know or care if an option came from the command line or from a text file.
If the threeoptions.txt file contained these three lines:
/Option1=one
/Option2=two
/Option3=3
Then the following command lines in a bash shell have the same effect:
# Just set all the options from a command line
$ mytool -option1=one -option2=two -option3=3
# Only use the file
$ mytool @threeoptions.txt
# Mix and match example 1. The values from the file "win" because they appear later
$ mytool -option1=1 @threeoptions.txt
# Mix and match example 2. Option3 will be "three" (from the command line, not "3" from the file)
$ mytool @threeoptions.txt -option3=threeThis allows you to flexibly use different @files for different types of settings.
You can also use @files as templates, and then override anything later in the command line.
Usually no. Usually command line options can be set in any order.
Most options in the tools are used to set a single value, like /Server=xxx to set the AQTS server connection. For options that set a single value, only the last value specified on the command line is retained.
This wiki page has been showing various forms of the fictitious mytool /Title="Some title" option to set the title property of a tool. If the command line contains multiple /Title=xxx options, the last option set will win.
$ mytool.exe -title="Title 1" -title="Title 2"
The title is: Title 2
...The tool will behave as if /Title="Title 1" was never specified.
The order of command line options does matter when specifying collections of items.
Some options are used to set a collection of values. Let's say that a /TimeSeries=xxx option could be set multiple times, to build a list of time-series for which the tool retrieves data. In that case, the order of command line options does matter.
C:\> MyTool -TimeSeries="Stage.Logger@Location1" -TimeSeries="Stage.Telemetry@Location2"
Doing work for Stage.Logger@Location1 ...
Doing work for Stage.Telemetry@Location2 ...If we swap the order of command line options, the output will change because the tool will process the telemetry signal before the logger signal.
C:\> MyTool -TimeSeries="Stage.Telemetry@Location2" -TimeSeries="Stage.Logger@Location1"
Doing work for Stage.Telemetry@Location2 ...
Doing work for Stage.Logger@Location1 ...