CSE 332 Autumn '10

Command-Line Input


When creating Java programs, we often work with either a GUI (graphical user
interface), or from a text-based interface.  The command-line is frequently
used to access and run programs, due to the flexibility it provides.

When running a program from the command-line, the following format is used:

ProgramName <flags> <arguments>

ProgramName can be the name of an executable in the current directory, or it
could be in a bin directory.  'java' is one such program: you can run it from
any directory, even if the 'java' program is not in that directory.

Flags are used to set options in the program.  You can think of them as the
dials and knobs of the program, making it do exactly what you want it to do.
Flags are usually in the form -X, where X is any upper or lower-case letter.
They can appear in any order.  Some take values as well: for example, a program
may use the flag -L=50 to set the line length to 50 characters.
You shouldn't need to worry about flags in this class; however, they are
useful to know about.

Arguments are used to feed input to your program.  Unlike flags, 
arguments can pass in more complex types of data.  One of the
most common types of arguments used are filenames: this allows the program to
run by using a file as input, or funnel its output to a second file.

As an example, one of the command-line operations you've used for a long time,
perhaps without knowing it, is the 'java' program.  When you normally use it,
the 'java' program takes one argument: the name of a class in the
current directory.  Here's an example use:

java MyClass


Command-Line Input and Java

We see that we can pass information to the 'java' program through arguments.
But how do we give arguments to our own program?

It turns out that you've probably seen the answer all along without realizing
what it was.  Remember that mysterious main function?

public static void main(String[] args){ ...

Look at that for a bit.  See anything that might match what we're looking for?
That's right, our command-line arguments are passed directly to our main
method in the form of an array of strings.  Let's take a closer look: say we want to pass
the name of a file that we want to read input from.  We can pass a filename in
as an argument:

java MyClass foo.dat

When we enter the main method, args will contain one item: the filename we
entered.  The array would look like this for the previous call:

["foo.dat"]

What if we wanted to give the user the option to examine a subset of lines in
the file? Perhaps we could attach two more arguments: start-line and end-line.

java MyClass foo.dat 30 67

The args array would then look like this:

["foo.dat", "30", "67"]

Arguments can be made optional, as well.  We could write MyClass to use
start-line and end-line only if there are enough arguments.  But note that we
rely on the position of each argument to know what it means.  So, while it may
be fine to run this command:

java MyClass foo.dat 30

...it is not legal to leave out earlier operations:

java MyClass 30 67

...or rearrange them:

java MyClass 67 foo.dat 30

When reading which arguments a program takes, optional arguments are denoted
by square brackets:

java <filename> [<first line> [<last line>]]


Argument Validation

The user may pass us a value, but that doesn't mean it's legal.  We need to
check any command-line input we receive to make sure it's within bounds for
the program.  Checking whether a file exists or making sure an argument is
a valid number are both common tasks within a Java program.  Here are some
common cases to check for:

1. Number of Arguments
Maybe your program requires the user to pass in a filename.  We need to make
sure they passed in at least one argument:

if(args.length < 1)
    throw new IllegalArgumentException("Usage: java MyClass <filename>");
else
    String filename = args[0];
...

We might also want to change behavior based on how many arguments were passed:

if(args.length >= 2){
    String baz = args[1];
    ...

2. Argument Type
Did the user pass in an integer, or a floating point? Was it even a number?
These are important to check beforehand, so you can give proper feedback to
the user.

int firstLine = 0;
try{
    firstLine = Integer.parseInt(args[1]);
}catch(NumberFormatException e){
    throw new IllegalArgumentException(
        "Usage: java MyClass <filename> [<first line> [<last line>]]");
}
...

3. Argument Validity
Now that we have the right types taken care of, did they pass us values that
are useable? Maybe they tried to set the first line to a negative number, or
gave us a file that doesn't exist.  Make sure to validate these in the same way
you would validate input that users would give in an interactive program.