//	BLCommand.hh
/*
This source file is part of G4beamline, http://g4beamline.muonsinc.com
Copyright (C) 2003,2004,2005,2006 by Tom Roberts, all rights reserved.

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

http://www.gnu.org/copyleft/gpl.html
*/

#ifndef BLCOMMAND_HH
#define BLCOMMAND_HH

#include <vector>
#include <map>
#include <iostream>
#include <fstream>

#include "globals.hh"
#include "G4RotationMatrix.hh"
#include "G4VisAttributes.hh"
#include "G4Material.hh"

#include "BLEvaluator.hh"

typedef std::vector<G4String> BLArgumentVector;
typedef std::map<G4String,G4String> BLArgumentMap;

const G4String IndentDesc("             ");
const G4String IndentArg("                           ");

const G4String DefaultDoubleFmt = "%.4g";

/**	class BLCommandPos - postion of the command input
 *	(used to get the input position for do loops)
 *	see also: BLCommand::setPos().
 **/
class BLCommandPos {
	std::istream *in;
	std::streampos pos;
	friend class BLCommand;
public:
	BLCommandPos(std::istream *_in) {
		in = _in;
		pos = in->tellg();
	}
	bool isValid() { return pos != (std::streampos)-1; }
};

/**	enum BLCmdType -- types of commands (for help index).
 **/
enum BLCmdType {BLCMDTYPE_HELP,BLCMDTYPE_CONTROL,BLCMDTYPE_LAYOUT,
		BLCMDTYPE_BEAM,BLCMDTYPE_AUX,BLCMDTYPE_ELEMENT,
		BLCMDTYPE_PLACE,BLCMDTYPE_CUTS,BLCMDTYPE_DATA,
		BLCMDTYPE_PHYSICS,BLCMDTYPE_OTHER };


/**	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!
 **/
class BLCommand {
	enum TokenType { NONE, ARGNAME, ARGVALUE };
	static std::map<G4String,BLCommand*> *mapCommand;
	static int errors;
	/// nextToken() will return the next token in line; called only by
	/// doCommand(). Side-effect: updates place and sets type.
	static G4String nextToken(const G4String& line, 
				G4String::size_type& place, TokenType& type);
	/// printArgDesc will print the description of an argument, using
	/// wrapWords().
	void printArgDesc(G4String name, G4String _description);
	static std::istream *in;
	friend class BLCMDplace;
protected:
	enum ArgumentMode { PROCESS, COUNT, HELP, PRINT, CHANGE };
	ArgumentMode argMode;
	bool argFound;
	G4String argName;
	G4String argValue;
	G4String synopsis;
	G4String description;
	G4String printArgString;
	int nArgs;
	int nFixed;
	int nTunable;
	BLCmdType type;
	friend class BLCMDhelp;
protected:
	/// Default Constructor.
	BLCommand() : synopsis(), description()
		{ }

	/// Destructor.
	virtual ~BLCommand();

	/// Copy Constructor.
	BLCommand(const BLCommand& r) : synopsis(), description()
		{ }

	// general functions for use by derived classes:

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

	/// deleteCommand() will delete a command by name
	void deleteCommand(G4String &name)
		{ if(mapCommand) mapCommand->erase(name); }

	/// 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 setSynopsis(const char * _synopsis) 
		{ synopsis = _synopsis; }

	/// 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 setDescription(const char * _description) 
		{ description = _description; }

	/// 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 argString(G4String& var, G4String name, G4String description,
			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 argDouble(G4double& var, G4String name, G4String description,
		G4double units=1.0, G4String fmt=DefaultDoubleFmt,
		bool permitChange=true);

	/// 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 argTunable(G4double& var, G4String name, G4String description,
		G4double units=1.0, G4String fmt=DefaultDoubleFmt);

	/// 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.
	void argInt(G4int& var, G4String name, G4String description,
			bool permitChange=true);

	/// 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.
	int handleNamedArgs(BLArgumentMap& namedArgs);

	/// help() prints the help information for this command.
	/// detailed=false prints only the name and synopsis; true prints
	/// the description and arguments also.
	virtual void help(bool detailed);

	/// 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".
	G4String wrapWords(G4String text, G4String indent1, G4String indent,
							G4String::size_type width=79);

	/// 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.
	void printArgs(G4String indent1);
public:
	// Functions implemented by the derived class:

	/// commandName() returns the name of the command.
	virtual G4String commandName() = 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 int command(BLArgumentVector& argv,
						BLArgumentMap& namedArgs) = 0;

	/// 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 defineNamedArgs();

	/// 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 argChanged() { }

	/// 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().
	virtual void print(G4String name);

	/// Print() -- alternate version for commands with special arguments.
	/// does not use defineNamedArgs() to print arguments, but rather
	/// prints namedArgs.
	void print(G4String name, BLArgumentMap& namedArgs);

	/// getName() returns the element's name; do not confuse this with
	/// commandName(). Re-defined by BLElement.
	virtual G4String getName() const { return "??"; }

	/// undefined() returns a quiet Not-A-Number, for initializing
	/// arguments to determine if the user set them or not.
	static double undefined();

	/// isUndefined() determines wheter an argument has been set.
	static bool isUndefined(double v);
public:
	// general functions:

	/// getCmdType() returns the type of this command
	BLCmdType getCmdType() { return type; }

	/// isValidCommand() returns true if cmd is a valid command.
	static bool isValidCommand(G4String& cmd)
		{ return mapCommand != 0 && mapCommand->count(cmd) > 0; }

	/// doCommand() will parse line and perform a single command.
	/// Returns 0 if OK, -1 if error.
	static int doCommand(G4String& line);

	/// 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.
	static int parseArgs(const G4String &line, BLArgumentVector &argv,
						BLArgumentMap &namedArgs);

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

	/// printError() prints an error message, using sprintf-style args.
	/// It also increments the errorCount.
	static void printError(const char *fmt, ...);

	/// getErrorCount() will return the number of errors so far.
	static int getErrorCount() { return errors; }

	/// 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.
	static G4String *getNextCommand();

	/// getPos() returns the current position of the Command input stream
	static BLCommandPos getPos();

	/// setPos() will set the Command input stream to a specified position
	void setPos(BLCommandPos &pos);

	// general utility functions for use by other classes

	/// 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.
	static G4Material *getMaterial(G4String materialName, bool error=true);

	/// getVisAttrib() returns the appropriate G4VisAttributes.
	static G4VisAttributes *getVisAttrib(G4String color);

	/// 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.
	/// NOTE: This is expensive and should not be used during tracking.
	static G4RotationMatrix *stringToRotationMatrix(G4String rotation);

	/// dumpRotation() dumps info about a rotation matrix to stdout.
	/// NOTE: This is expensive and should not be used during tracking.
	static void dumpRotation(const G4RotationMatrix *rot, const char *str);

	/// splitString() splits a string at each instance of any character
	/// in delim, returning a vector<G4String>. If trim is true, each
	/// returned string has whitespace removed from its front and rear.
	/// Successive delimiters, or delimiters at the beginning or end,
	/// generate an empty string.
	/// NOTE: This is expensive and should not be used during tracking.
	static std::vector<G4String> splitString(const G4String &s, 
					const G4String &delim, bool trim=false);

	/// getDouble() converts a string expression to a double, returning
	/// nan if the string is not a valid expression using double constants
	/// and standard C operators and functions; whitespace is permitted as
	/// in C but an empty or all-whitespace string is invalid.
	/// Callers can use std::isnan(double) or gsl_isnan(double) to test
	/// for validity.
	/// NOTE: This is expensive and should not be used during tracking.
	static double getDouble(const G4String &s)
		{ BLEvaluator e; return e.evaluate(s); }

	/// getList() converts a string containing a delimited list
	/// of double expressions to a vector<G4double>. Any character in
	/// delim separates entries. Functions and operators known to
	/// BLEvaluator can be used in each entry of the list.
	/// Empty entries (null or consisting only of whitespace) are invalid.
	/// Returns an empty list if any entry is an invalid expression.
	/// NOTE: This is expensive and should not be used during tracking.
	static std::vector<G4double> getList(const G4String &s,
							const G4String &delim);

	/// matchList() returns true if s matches any pattern in
	/// patternList, whch is a comma-separated list of file-glob patterns.
	/// NOTE: This is expensive and should not be used during tracking.
	static bool matchList(const G4String s, const G4String patternList);
};

#endif // BLCOMMAND_HH