nsICommandLine

Components may implement the nsICommandLineHandler interface to add custom command line handling behavior.

Definitions

arguments

Any values found on the command line.

switches

Flags. In normalized form, these are preceded by a single dash. Some flags may take parameters; for example: "-url <param>" or "-install-xpi <param>".

Method overview

Attributes

Constants

State constants

Methods

findFlag()

Finds a command-line flag, returning its position on the command line.

long findFlag(
  in AString aFlag,
  in boolean aCaseSensitive
);

Parameters

aFlag

The flag name to locate. Do not include the initial hyphen.

aCaseSensitive

Whether to do case-sensitive comparisons.

Return value

The position of the flag in the command line, or -1 if the flag is not found.

getArgument()

Gets the value an argument from the array of command-line arguments, given the index into the argument list.

On Windows, flags of the form /flag are normalized to -flag. /flag:param are normalized to -flag param.

On Unix/Linux and Mac OS X, flags of the form --flag are normalized to -flag, and flags of the form --flag=param are normalized to the form -flag param.

AString getArgument(
  in long aIndex
);

Parameters

aIndex

The argument to retrieve. This index is 0-based, and does not include the application name.

Return value

The value of the specified argument. This is the full text of that argument, so if the argument is a flag, the returned value is "-flag [<flagvalue>]".

Exceptions thrown

NS_ERROR_INVALID_ARG

The specified index is out of bounds.

handleFlag()

Finds the specified flag, removing it from the array of flags. Reports whether or not the specified flag was found. This is useful for Boolean flags; that is, flags that don't accept a parameter. You can determine if the flag was provided and remove it from the list of flags waiting to be processed in one operation.

boolean handleFlag(
  in AString aFlag,
  in boolean aCaseSensitive
);

Parameters

aFlag

The flag name to find and remove.

aCaseSensitive

Whether to do case-sensitive comparisons.

Return value

true if the flag was found, otherwise false.

handleFlagWithParam()

Finds a flag in the list of flags waiting to be processed and returns its value, after removing both the flag and its value from the list of flags waiting to be handled. This is useful for processing flags that accept a value. This is, essentially, a helper method that combines findFlag() and removeArguments() into one operation.

AString handleFlagWithParam(
  in AString aFlag,
  in boolean aCaseSensitive
);

Parameters

aFlag

The flag name to find and remove.

aCaseSensitive

Whether to do case-sensitive flag search.

Return value

The value of the specified flag, an empty string if the flag's value is the empty string, or null if the specified parameter wasn't found.

Exceptions thrown

NS_ERROR_INVALID_ARG

The specified flag has no value.

removeArguments()

Removes a range of arguments from the command line; this is typically done once those arguments have been handled.

void removeArguments(
  in long aStart,
  in long aEnd
);

Parameters

aStart

The index to the first argument to remove from the command line; this is 0-based, and the name of the application is not included.

aEnd

The index to the last argument to remove from the command line.

resolveFile()

Resolves a file-path argument into an nsIFile object. This method gracefully handles relative or absolute file paths, according to the working directory of this command line.

nsIFile resolveFile(
  in AString aArgument
);

Parameters

aArgument

The command-line argument to resolve.

Return value

The file path as an nsIFile.

resolveURI()

Resolves a URI argument into a URI. This method has platform-specific logic for converting an absolute URI or a relative file-path into the appropriate URI object; it gracefully handles win32 C:\ paths which would confuse the I/O service if passed directly.

nsIURI resolveURI(
  in AString aArgument
);

Parameters

aArgument

The command-line argument to resolve.

Return value

A platform-specific URI.

See also

• Sample JS component that implements a command-line flag.