FAQ: command-line arguments

[Sven Thommesen]

I have today sent on to Paul Johnson for inclusion in the Swarm FAQ the 
text below as well as 5 code examples (not included here). Feel free to use 
the code in the examples in any way you see fit. Enjoy!

Please direct comments or questions to me at <address@hidden>

----------------------------------------------------------------------------------------------------

Q: How do I parse command-line arguments and make the data available to 
objects and agents in my simulation?

----------------------------------------------------------------------------------------------------

/*
 * Title:       TestArguments
 * Version:     0.1
 * Copyright:   Copyright (c) 2001
 * Author:      Sven Thommesen <address@hidden>
 * Description: Sample app to show parsing of command line arguments.
 *              5 Examples.
 */

/*
Every Swarm application of any size need to set the values of several
simulation parameters before execution starts. These parameters may
live in any of the objects participating in the simulation, not just
in the top swarm object.

Such parameter values may come from several sources: they may be hard
coded in the constructors for the different objects, they may be provided
by the user via probe displays (in GUI mode), they may be retrieved from
archive (.scm) files when an object is created, or they may be passed to
the program on the command line.

The 5 examples I have appended here demonstrate two aspects of this:
a) retrieving parameter values passed in via the command line; and
b) storing parameter values in a database object which can be passed
   around and accessed by other objects/agents in the simulation.

As discussed on the Swarm list recently (by pj, mgd, and myself),
command line arguments can be passed to a Swarm application in 2 ways:

1)      $ javaswarm -Dkey1=value1 -Dkey2=value2 ProgramName -b

In this case, the Java runtime system picks up the key-value pairs
and puts them into a Properties object which is globally accessible,
and our application can extract the information from this object.
This variant only works for Java Swarm programs, obviously.

2a)     $ javaswarm ProgramName -b -- -Dkeyi1=value1 -Dkey2=value2

In this case, the program must manually pick out the key-value pairs
from the command line after the '--' token. This way has the advantage
that it can also be implemented in objective-C, in which case you'd say:

2b)     $ ./ProgramName -b -- -Dkey1=value1 -Dkey2=value2

and so on. There is no limit to the number of parameters you can pass
to a program this way, other than operating-system limits on the length of
a command line.

(There is a third way to pass command line arguments to Swarm, which
involves sub-classing the Arguments class. This document does not
discuss that option.)

In the examples I give, the 'key' string and the 'value' string are used
when the information is stored in the application database (which is
either a HashMap object or a Properties object.) Any object in the simulation
may retrieve the 'value' by specifying the 'key'.

In the examples I give, the 'key' is also taken to be the name of an instance
variable in some object in the simulation, and the 'value' a valid
value for that variable. There is no reason, however, why you could not
use the general code shown in the examples to pass other kinds of information
to your program which you parse and use in some way relevant to you:

        $ javaswarm -Dkey=SomeGeneralString ProgramName -b

There are several choices to be made when setting up a Swarm program to
parse command line data and store it in a local database, such as:
 - whether data will be passed before the ProgramName or after '--'
 - whether the data will be stored in a HashMap or a Properties object
 - whether batchSwarm variables will be set before or after data are
        loaded into the database object
 - whether the database object will contain only those key-value pairs
        passed on the command line, or a full set of default values
 - whether Probes are used to set the values of instance variables,
        or this is done manually

The 5 examples show a small set of answers to these questions.

FEEL FREE to use the code in the examples in any way you see fit.
----------------------------------------

Please direct comments and questions to:
Sven Thommesen <address@hidden>
Auburn, AL, 2001-07-10

 */


                 ==================================
  Swarm-Support is for discussion of the technical details of the day
  to day usage of Swarm.  For list administration needs (esp.
  [un]subscribing), please send a message to <address@hidden>
  with "help" in the body of the message.