BLCommand Class Reference

#include <BLCommand.hh>

Inheritance diagram for BLCommand:

List of all members.

---

Detailed Description

class BLCommand - interface to define a command.

The standard usage for a command without a BLElement is to derive from this class and define a static instance using the default constructor. In the derived-class default constructor the command is registered, calls to setSynopsis() and setDescription() provide help text, and initial values are given to all class variables. This instance is used to execute the command, and normally no other instances are needed.

The static instance is used to keep the default arguments for the element.

Standard usage for a command for a BLElement is to derive a class from BLElement (which is derived from BLCommand), and do the above in its default constructor. The derived command() function then creates an instance of the class. Only the static instance is used to execute the command, but other instances implement the various elements (to be placed later in the input file).

See BLCMDdemo.cc and BLCMDtubs.cc for examples (.hh files are not needed for most commands, as their classes are not needed anywhere but in their implementation file).

NOTE: ONLY the default object should use the default constructor!

Public Member Functions
virtual G4String	commandName ()=0
	commandName() returns the name of the command.
virtual int	command (BLArgumentVector &argv, BLArgumentMap &namedArgs)=0
	command() executes the command associated with this element. argv and namedArgs come from parsing the command-line: argv has a vector of any positional arguments (without "="); namedArgs has a map of any named arguments of the form name=value. Returns 0 if OK, -1 on error. NOTE: for classes derived via BLElement.hh, arguments can be given when an object is defined and when it is placed. For that to work, argument values must not be used in the command() function unless they are defined with permitChange=false (in the above argString... functions). Also the correct units must be given to argDouble().
virtual void	defineNamedArgs ()
	defineNamedArgs() defines the named arguments for the command. This function should consist ONLY of a series of calls to argString(), argDouble(), and argInt(). Used by handleNamedArgs(), help(), and print() (they manipulate the behavior of the argXXX() functions via argMode).
virtual void	argChanged ()
	argChanged() will be called whenever some argument value has changed. Derived classes should define it and perform any internal computations that depend on argument values. Many/most derived classes won't need to use it. In particular, after argChanged() returns the functions getHeight(), getWidth() and getLength() must return the correct values for the current arguments. BEWARE: a single argument change may call this multiple times. Applies only to named arguments, not positional ones.
virtual void	print (G4String name)
	print() will print to stdout the command. The default versions will do for most commands and elements. name can be "". prints commandname() and name in the space of IndentArg, followed by the values of all named arguments, in the order they appear in defineNamedArgs().
void	print (G4String name, BLArgumentMap &namedArgs)
	Print() -- alternate version for commands with special arguments. does not use defineNamedArgs() to print arguments, but rather prints namedArgs.
virtual G4String	getName () const
	getName() returns the element's name; do not confuse this with commandName(). Re-defined by BLElement.
void	setPos (BLCommandPos &pos)
	setPos() will set the Command input stream to a specified position
Static Public Member Functions
bool	isValidCommand (G4String &cmd)
	isValidCommand() returns true if cmd is a valid command.
int	doCommand (G4String &line)
	doCommand() will parse line and perform a single command. Returns 0 if OK, -1 if error.
int	parseArgs (const G4String &line, BLArgumentVector &argv, BLArgumentMap &namedArgs)
	parseArgs() will parse the arguments of a command line. Arguments are appended to argv[] and added to namedArgs. Returns 0 if OK, -1 if syntax error.
int	readFile (G4String filename)
	readFile() reads a file of commands and executes them. "-" is stdin. Returns the number of errors encountered, or -1 if filename cannot be read.
void	printError (const char *fmt,...)
	printError() prints an error message, using sprintf-style args. It also increments the errorCount.
int	getErrorCount ()
	getErrorCount() will return the number of errors so far.
G4String *	getNextCommand ()
	getNextCommand() returns the next command. backslash-newline has been handled, and the line is stripped of whitespace at both ends. returns 0 if error or EOF. The pointer should NOT be deleted.
BLCommandPos	getPos ()
	getPos() returns the current position of the Command input stream
G4Material *	getMaterial (G4String materialName, bool error=true)
	getMaterial() searches the G4Material list and returns the entry corresponding to name. Searches the NIST database if the material is not already defined. Prepends "G4_" if necessary. prints an error and exits if the material is not found, so all materials MUST be defined before they are used, unless they can be found in the geant4 NIST database.
G4VisAttributes *	getVisAttrib (G4String color)
	getVisAttrib() returns the appropriate G4VisAttributes.
G4RotationMatrix *	stringToRotationMatrix (G4String rotation)
	stringToRotationMatrix() converts a string "X90,Y45" into a G4RotationMatrix. This is an active rotation, in that the object is first rotated around the parent's X axis by 90 degrees, then the object is further rotated around the parent's Y axis by 45 degrees. The return value points to a G4RotationMatrix on the heap, so it is persistent. Angles are in degrees, can have decimals, and can be negative. Axes are X, Y, Z.
void	dumpRotation (const G4RotationMatrix *rot, const char *str)
	dumpRotation() dumps info about a rotation matrix to stdout.
Protected Types
enum	ArgumentMode {   PROCESS, COUNT, HELP, PRINT,   CHANGE }
Protected Member Functions
	BLCommand ()
	Default Constructor.
virtual	~BLCommand ()
	Destructor.
	BLCommand (const BLCommand &r)
	Copy Constructor.
void	registerCommand (BLCmdType _type)
	registerCommand() registers the command. Used only in the default constructor -- ensures mapCommand is properly initialized regardless of order.
BLCmdType	getCmdType ()
	getCmdType(0 returns the type of this command
void	deleteCommand (G4String &name)
	deleteCommand() will delete a command by name
void	setSynopsis (const char *_synopsis)
	setSynopsis() gives a 1-line (64 char) description of what the command does. Used by the help command with no arguments. The string should be 64 characters or less, and should not contain any newline; no word wrapping. Used only in the default constructor.
void	setDescription (const char *_description)
	setDescription() gives a more complete description of the command, when help for this specific command is requested. When printed by the help() function, word wrapping is performed, but lines beginning with whitespace are kept intact. Named arguments are automatically described by the help() function, but positional arguments should be described here. Words are wrapped using wrapWords(). Used only in the default constructor.
void	argString (G4String &var, G4String name, G4String description, bool permitChange=true)
	argString() declares a string-valued argument. name should be a valid C identifier 15 chars or less, and description should be a short description (wrapWords() is used). Used only in the defineNamedArgs() function. permitChange affects whether this argument can be set when an element is placed.
void	argDouble (G4double &var, G4String name, G4String description, G4double units=1.0, G4String fmt=DefaultDoubleFmt, bool permitChange=true)
	argDouble() declares a G4double-valued argument. name should be a valid C identifier 15 chars or less, and description should be a short description (wrapWords() is used). Used only in the defineNamedArgs() function. units should be the human units for the argument, because the value of var is always in internal units. fmt and units are used when argMode=PRINT. permitChange affects whether this argument can be set when an element is placed.
void	argTunable (G4double &var, G4String name, G4String description, G4double units=1.0, G4String fmt=DefaultDoubleFmt)
	argTunable() declares a G4double-valued argument that is tunable (see the tune command in BLCMDtune.cc). name should be a valid C identifier 15 chars or less, and description should be a short description (wrapWords() is used). Used only in the defineNamedArgs() function. units should be the human units for the argument, because the value of var is always in internal units. fmt and units are used when argMode=PRINT. Tunable arguments can always be set when an element is placed, and will be changed during the tracking of the Tune Particle if their value includes a tune variable. See BLTune.hh for a description of how tunable arguments are handled.
void	argInt (G4int &var, G4String name, G4String description, bool permitChange=true)
	argInt() declares a integer-valued argument. name should be a valid C identifier 15 chars or less, and description should be a short description (wrapWords() is used). Used only in the defineNamedArgs() function. permitChange affects whether this argument can be set when an element is placed.
int	handleNamedArgs (BLArgumentMap &namedArgs)
	handleNamedArgs() handles all named arguments to the command (i.e. those defined in defineNamedArgs()). For use in the command() function. returns 0 if OK, -1 on error.
virtual void	help (bool detailed)
	help() prints the help information for this command. detailed=false prints only the name and synopsis; true prints the description and arguments also.
G4String	wrapWords (G4String text, G4String indent1, G4String indent, unsigned width=79)
	wrapWords() will wrap words for descriptions in help(). In text, lines beginning with whitespace are preserved as is, including blank lines. Otherwise, newlines aren't needed in text. indent1 is the start of the first line, and indent is used at the start of succeeding lines ("" is OK); indents are counted in the line width. The returned string always ends with "\n".
void	printArgs (G4String indent1)
	printArgs() will print (to stdout) the named arguments of the command entered, for log purposes. Calls defineNamedArgs() with argMode=PRINT to print the args. indent1 is the indent for the first line.
Protected Attributes
ArgumentMode	argMode
bool	argFound
G4String	argName
G4String	argValue
G4String	synopsis
G4String	description
G4String	printArgString
int	nArgs
int	nFixed
int	nTunable
BLCmdType	type
Private Types
enum	TokenType { NONE, ARGNAME, ARGVALUE }
Private Member Functions
void	printArgDesc (G4String name, G4String _description)
	printArgDesc will print the description of an argument, using wrapWords().
Static Private Member Functions
G4String	nextToken (const G4String &line, unsigned int &place, TokenType &type)
	nextToken() will return the next token in line; called only by doCommand(). Side-effect: updates place and sets type.
Static Private Attributes
std::map< G4String, BLCommand * > *	mapCommand
int	errors = 0
std::istream *	in = 0
Friends
class	BLCMDplace
class	BLCMDhelp

---

Member Enumeration Documentation

enum BLCommand::TokenType [private]

Enumeration values: NONE  ARGNAME  ARGVALUE

enum BLCommand::ArgumentMode [protected]

Enumeration values: PROCESS  COUNT  HELP  PRINT  CHANGE

---

Constructor & Destructor Documentation

BLCommand::BLCommand (   )  [inline, protected]

Default Constructor.

BLCommand::~BLCommand (   )  [protected, virtual]

Destructor.

BLCommand::BLCommand (  const BLCommand &  r  )  [inline, protected]

Copy Constructor.

---

Member Function Documentation

G4String BLCommand::nextToken (  const G4String &  line, unsigned int &  place, TokenType &  type )  [static, private]

nextToken() will return the next token in line; called only by doCommand(). Side-effect: updates place and sets type.

void BLCommand::printArgDesc (  G4String  name, G4String  _description )  [private]

printArgDesc will print the description of an argument, using wrapWords().

void BLCommand::registerCommand (  BLCmdType  _type  )  [protected]

registerCommand() registers the command. Used only in the default constructor -- ensures mapCommand is properly initialized regardless of order.

BLCmdType BLCommand::getCmdType (   )  [inline, protected]

getCmdType(0 returns the type of this command

void BLCommand::deleteCommand (  G4String &  name  )  [inline, protected]

deleteCommand() will delete a command by name

void BLCommand::setSynopsis (  const char *  _synopsis  )  [inline, protected]

setSynopsis() gives a 1-line (64 char) description of what the command does. Used by the help command with no arguments. The string should be 64 characters or less, and should not contain any newline; no word wrapping. Used only in the default constructor.

void BLCommand::setDescription (  const char *  _description  )  [inline, protected]

setDescription() gives a more complete description of the command, when help for this specific command is requested. When printed by the help() function, word wrapping is performed, but lines beginning with whitespace are kept intact. Named arguments are automatically described by the help() function, but positional arguments should be described here. Words are wrapped using wrapWords(). Used only in the default constructor.

void BLCommand::argString (  G4String &  var, G4String  name, G4String  description, bool  permitChange = true )  [protected]

argString() declares a string-valued argument. name should be a valid C identifier 15 chars or less, and description should be a short description (wrapWords() is used). Used only in the defineNamedArgs() function. permitChange affects whether this argument can be set when an element is placed.

void BLCommand::argDouble (  G4double &  var, G4String  name, G4String  description, G4double  units = 1.0, G4String  fmt = DefaultDoubleFmt, bool  permitChange = true )  [protected]

argDouble() declares a G4double-valued argument. name should be a valid C identifier 15 chars or less, and description should be a short description (wrapWords() is used). Used only in the defineNamedArgs() function. units should be the human units for the argument, because the value of var is always in internal units. fmt and units are used when argMode=PRINT. permitChange affects whether this argument can be set when an element is placed.

void BLCommand::argTunable (  G4double &  var, G4String  name, G4String  description, G4double  units = 1.0, G4String  fmt = DefaultDoubleFmt )  [protected]

argTunable() declares a G4double-valued argument that is tunable (see the tune command in BLCMDtune.cc). name should be a valid C identifier 15 chars or less, and description should be a short description (wrapWords() is used). Used only in the defineNamedArgs() function. units should be the human units for the argument, because the value of var is always in internal units. fmt and units are used when argMode=PRINT. Tunable arguments can always be set when an element is placed, and will be changed during the tracking of the Tune Particle if their value includes a tune variable. See BLTune.hh for a description of how tunable arguments are handled.

void BLCommand::argInt (  G4int &  var, G4String  name, G4String  description, bool  permitChange = true )  [protected]

argInt() declares a integer-valued argument. name should be a valid C identifier 15 chars or less, and description should be a short description (wrapWords() is used). Used only in the defineNamedArgs() function. permitChange affects whether this argument can be set when an element is placed.

int BLCommand::handleNamedArgs (  BLArgumentMap &  namedArgs  )  [protected]

handleNamedArgs() handles all named arguments to the command (i.e. those defined in defineNamedArgs()). For use in the command() function. returns 0 if OK, -1 on error. Reimplemented in BLCMDplace.

void BLCommand::help (  bool  detailed  )  [protected, virtual]

help() prints the help information for this command. detailed=false prints only the name and synopsis; true prints the description and arguments also. Reimplemented in BLCMDmaterial, and BLCMDphysics.

G4String BLCommand::wrapWords (  G4String  text, G4String  indent1, G4String  indent, unsigned  width = 79 )  [protected]

wrapWords() will wrap words for descriptions in help(). In text, lines beginning with whitespace are preserved as is, including blank lines. Otherwise, newlines aren't needed in text. indent1 is the start of the first line, and indent is used at the start of succeeding lines ("" is OK); indents are counted in the line width. The returned string always ends with "\n".

void BLCommand::printArgs (  G4String  indent1  )  [protected]

printArgs() will print (to stdout) the named arguments of the command entered, for log purposes. Calls defineNamedArgs() with argMode=PRINT to print the args. indent1 is the indent for the first line.

virtual G4String BLCommand::commandName (   )  [pure virtual]

commandName() returns the name of the command. Implemented in BLGroup, BLCMDabsorber, BLCMDbeam, BLCMDbeamlossntuple, BLCMDbox, BLCMDcoil, BLCMDcollective, BLCMDcorner, BLCMDcornerarc, BLCMDcosmicraybeam, BLCMDdefine, Macro, BLCMDdemo, BLCMDdo, BLCMDendgroup, BLCMDeventcuts, BLCMDexit, BLCMDextrusion, BLCMDfieldexpr, BLCMDfieldmap, BLCMDg4ui, BLCMDgenericbend, BLCMDgenericquad, BLCMDgeometry, BLCMDhelicaldipole, BLCMDhelp, BLCMDidealsectorbend, BLCMDif, BLCMDinclude, BLCMDlist, BLCMDload, BLCMDmaterial, BLCMDmultipole, BLCMDnewparticlentuple, BLCMDntuple, BLCMDparam, BLCMDparticlecolor, BLCMDparticlefilter, BLCMDphysics, BLCMDpillbox, BLCMDpillbox2, BLCMDplace, BLCMDpolycone, BLCMDprintf, BLCMDprintfield, BLCMDprobefield, BLCMDprofile, BLCMDrandomseed, BLCMDreference, BLCMDshowmaterial, BLCMDsolenoid, BLCMDsphere, BLCMDstart, BLCMDtest, BLCMDtimentuple, BLCMDtrace, BLCMDtrackcuts, BLCMDtracker, BLCMDtrackerplane, BLCMDtrackermode, BLCMDtrap, BLCMDtubs, BLCMDtune, BLCMDvirtualdetector, and BLCMDzntuple.

virtual int BLCommand::command (  BLArgumentVector &  argv, BLArgumentMap &  namedArgs )  [pure virtual]

command() executes the command associated with this element. argv and namedArgs come from parsing the command-line: argv has a vector of any positional arguments (without "="); namedArgs has a map of any named arguments of the form name=value. Returns 0 if OK, -1 on error. NOTE: for classes derived via BLElement.hh, arguments can be given when an object is defined and when it is placed. For that to work, argument values must not be used in the command() function unless they are defined with permitChange=false (in the above argString... functions). Also the correct units must be given to argDouble(). Implemented in BLGroup, BLCMDabsorber, BLCMDbeam, BLCMDbeamlossntuple, BLCMDbox, BLCMDcoil, BLCMDcollective, BLCMDcorner, BLCMDcornerarc, BLCMDcosmicraybeam, BLCMDdefine, Macro, BLCMDdemo, BLCMDdo, BLCMDendgroup, BLCMDeventcuts, BLCMDexit, BLCMDextrusion, BLCMDfieldexpr, BLCMDfieldmap, BLCMDg4ui, BLCMDgenericbend, BLCMDgenericquad, BLCMDgeometry, BLCMDhelicaldipole, BLCMDhelp, BLCMDidealsectorbend, BLCMDif, BLCMDinclude, BLCMDlist, BLCMDload, BLCMDmaterial, BLCMDmultipole, BLCMDnewparticlentuple, BLCMDntuple, BLCMDparam, BLCMDparticlecolor, BLCMDparticlefilter, BLCMDphysics, BLCMDpillbox, BLCMDpillbox2, BLCMDplace, BLCMDpolycone, BLCMDprintf, BLCMDprintfield, BLCMDprobefield, BLCMDprofile, BLCMDrandomseed, BLCMDreference, BLCMDshowmaterial, BLCMDsolenoid, BLCMDsphere, BLCMDstart, BLCMDtest, BLCMDtimentuple, BLCMDtrace, BLCMDtrackcuts, BLCMDtracker, BLCMDtrackerplane, BLCMDtrackermode, BLCMDtrap, BLCMDtubs, BLCMDtune, BLCMDvirtualdetector, and BLCMDzntuple.

void BLCommand::defineNamedArgs (   )  [virtual]

defineNamedArgs() defines the named arguments for the command. This function should consist ONLY of a series of calls to argString(), argDouble(), and argInt(). Used by handleNamedArgs(), help(), and print() (they manipulate the behavior of the argXXX() functions via argMode). Reimplemented in BLGroup, BLCMDabsorber, BLCMDbeam, BLCMDbeamlossntuple, BLCMDbox, BLCMDcoil, BLCMDcollective, BLCMDcorner, BLCMDcornerarc, BLCMDcosmicraybeam, Macro, BLCMDdemo, BLCMDeventcuts, BLCMDextrusion, BLCMDfieldexpr, BLCMDfieldmap, BLCMDg4ui, BLCMDgenericbend, BLCMDgenericquad, BLCMDgeometry, BLCMDhelicaldipole, BLCMDidealsectorbend, BLCMDmaterial, BLCMDmultipole, BLCMDnewparticlentuple, BLCMDntuple, BLCMDparticlecolor, BLCMDparticlefilter, BLCMDphysics, BLCMDpillbox, BLCMDpillbox2, BLCMDplace, BLCMDpolycone, BLCMDprintf, BLCMDprintfield, BLCMDprobefield, BLCMDprofile, BLCMDrandomseed, BLCMDreference, BLCMDsolenoid, BLCMDsphere, BLCMDstart, BLCMDtest, BLCMDtimentuple, BLCMDtrace, BLCMDtrackcuts, BLCMDtracker, BLCMDtrackerplane, BLCMDtrackermode, BLCMDtrap, BLCMDtubs, BLCMDtune, BLCMDvirtualdetector, and BLCMDzntuple.

virtual void BLCommand::argChanged (   )  [inline, virtual]

argChanged() will be called whenever some argument value has changed. Derived classes should define it and perform any internal computations that depend on argument values. Many/most derived classes won't need to use it. In particular, after argChanged() returns the functions getHeight(), getWidth() and getLength() must return the correct values for the current arguments. BEWARE: a single argument change may call this multiple times. Applies only to named arguments, not positional ones. Reimplemented in BLCMDpillbox, BLCMDpillbox2, BLCMDtrackerplane, and BLCMDvirtualdetector.

void BLCommand::print (  G4String  name  )  [virtual]

print() will print to stdout the command. The default versions will do for most commands and elements. name can be "". prints commandname() and name in the space of IndentArg, followed by the values of all named arguments, in the order they appear in defineNamedArgs().

void BLCommand::print (  G4String  name, BLArgumentMap &  namedArgs )

Print() -- alternate version for commands with special arguments. does not use defineNamedArgs() to print arguments, but rather prints namedArgs.

virtual G4String BLCommand::getName (   )  const [inline, virtual]

getName() returns the element's name; do not confuse this with commandName(). Re-defined by BLElement. Reimplemented in BLElement, and BLCMDtracker.

bool BLCommand::isValidCommand (  G4String &  cmd  )  [inline, static]

isValidCommand() returns true if cmd is a valid command.

int BLCommand::doCommand (  G4String &  line  )  [static]

doCommand() will parse line and perform a single command. Returns 0 if OK, -1 if error.

int BLCommand::parseArgs (  const G4String &  line, BLArgumentVector &  argv, BLArgumentMap &  namedArgs )  [static]

parseArgs() will parse the arguments of a command line. Arguments are appended to argv[] and added to namedArgs. Returns 0 if OK, -1 if syntax error.

int BLCommand::readFile (  G4String  filename  )  [static]

readFile() reads a file of commands and executes them. "-" is stdin. Returns the number of errors encountered, or -1 if filename cannot be read.

void BLCommand::printError (  const char *  fmt, ...  )  [static]

printError() prints an error message, using sprintf-style args. It also increments the errorCount.

int BLCommand::getErrorCount (   )  [inline, static]

getErrorCount() will return the number of errors so far.

G4String * BLCommand::getNextCommand (   )  [static]

getNextCommand() returns the next command. backslash-newline has been handled, and the line is stripped of whitespace at both ends. returns 0 if error or EOF. The pointer should NOT be deleted.

BLCommandPos BLCommand::getPos (   )  [static]

getPos() returns the current position of the Command input stream

void BLCommand::setPos (  BLCommandPos &  pos  )

setPos() will set the Command input stream to a specified position

G4Material * BLCommand::getMaterial (  G4String  materialName, bool  error = true )  [static]

getMaterial() searches the G4Material list and returns the entry corresponding to name. Searches the NIST database if the material is not already defined. Prepends "G4_" if necessary. prints an error and exits if the material is not found, so all materials MUST be defined before they are used, unless they can be found in the geant4 NIST database.

G4VisAttributes * BLCommand::getVisAttrib (  G4String  color  )  [static]

getVisAttrib() returns the appropriate G4VisAttributes.

G4RotationMatrix * BLCommand::stringToRotationMatrix (  G4String  rotation  )  [static]

stringToRotationMatrix() converts a string "X90,Y45" into a G4RotationMatrix. This is an active rotation, in that the object is first rotated around the parent's X axis by 90 degrees, then the object is further rotated around the parent's Y axis by 45 degrees. The return value points to a G4RotationMatrix on the heap, so it is persistent. Angles are in degrees, can have decimals, and can be negative. Axes are X, Y, Z.

void BLCommand::dumpRotation (  const G4RotationMatrix *  rot, const char *  str )  [static]

dumpRotation() dumps info about a rotation matrix to stdout.

---

Friends And Related Function Documentation

friend class BLCMDplace [friend]

friend class BLCMDhelp [friend]

---

Member Data Documentation

std::map< G4String, BLCommand * > * BLCommand::mapCommand [static, private]

int BLCommand::errors = 0 [static, private]

std::istream * BLCommand::in = 0 [static, private]

Reimplemented in BLCMDprobefield.

ArgumentMode BLCommand::argMode [protected]

bool BLCommand::argFound [protected]

G4String BLCommand::argName [protected]

G4String BLCommand::argValue [protected]

G4String BLCommand::synopsis [protected]

G4String BLCommand::description [protected]

G4String BLCommand::printArgString [protected]

int BLCommand::nArgs [protected]

int BLCommand::nFixed [protected]

int BLCommand::nTunable [protected]

BLCmdType BLCommand::type [protected]

Reimplemented in BLCMDbeam, and BLCMDprintfield.

---

The documentation for this class was generated from the following files:

• BLCommand.hh
• BLCommand.cc

g4beamline