When you type a command on the command-line, it is passed onto the shell (a generic name for the program that manages the command-line) as a string of characters. As an example, see the “Invoking ProgramName” sections in this manual for some examples of commands with each program, like Invoking Table, Invoking Fits, or Invoking Statistics.
The shell then brakes up your string into separate tokens or words using any metacharacters (like white-space, tab, |, > or ;) that are in the string.
On the command-line, the first thing you usually enter is the name of the program you want to run.
After that, you can specify two types of tokens: arguments and options.
In the GNU-style, arguments are those tokens that are not preceded by any hyphens (-, see Arguments).
Here is one example:
$ astcrop --center=53.162551,-27.789676 -w10/3600 --mode=wcs udf.fits
In the example above, we are running Crop to crop a region of width 10 arc-seconds centered at the given RA and Dec from the input Hubble Ultra-Deep Field (UDF) FITS image. Here, the argument is udf.fits. Arguments are most commonly the input file names containing your data. Options start with one or two hyphens, followed by an identifier for the option (the option’s name, for example, --center, -w, --mode in the example above) and its value (anything after the option name, or the optional = character). Through options you can configure how the program runs (interprets the data you provided).
Arguments can be mandatory and optional and unlike options, they do not have any identifiers.
Hence, when there multiple arguments, their order might also matter (for example, in cp which is used for copying one file to another location).
The outputs of --usage and --help shows which arguments are optional and which are mandatory, see --usage.
As their name suggests, options can be considered to be optional and most of the time, you do not have to worry about what order you specify them in. When the order does matter, or the option can be invoked multiple times, it is explicitly mentioned in the “Invoking ProgramName” section of each program (this is a very important aspect of an option).
If there is only one such character, you can use a backslash (\) before it.
If there are multiple, it might be easier to simply put your whole argument or option value inside of double quotes (").
In such cases, everything inside the double quotes will be seen as one token or word.
For example, let’s say you want to specify the header data unit (HDU) of your FITS file using a complex expression like ‘3; images(exposure > 100)’.
If you simply add these after the --hdu (-h) option, the programs in Gnuastro will read the value to the HDU option as ‘3’ and run.
Then, the shell will attempt to run a separate command ‘images(exposure > 100)’ and complain about a syntax error.
This is because the semicolon (;) is an ‘end of command’ character in the shell.
To solve this problem you can simply put double quotes around the whole string you want to pass to --hdu as seen below:
$ astcrop --hdu="3; images(exposure > 100)" image.fits
GNU Astronomy Utilities 0.22 manual, February 2024.