[Avida-SVN] r1407 - in development: documentation source/main source/tools

[matt at myxo.css.msu.edu]

Author: matt
Date: 2007-03-18 21:47:12 -0400 (Sun, 18 Mar 2007)
New Revision: 1407

Modified:
   development/documentation/actions.html
   development/source/main/cInstruction.cc
   development/source/main/cInstruction.h
   development/source/tools/tArray.h
Log:
Submitting files that should have been submitted with last commit.

Modified: development/documentation/actions.html
===================================================================
--- development/documentation/actions.html	2007-03-19 01:37:00 UTC (rev 1406)
+++ development/documentation/actions.html	2007-03-19 01:47:12 UTC (rev 1407)
@@ -20,6 +20,7 @@
 <h1>List of Actions</h1>
 </div>
 
+<a name="ActionCategories"><h2>Action Categories</h2></a>
 <p>
 There is a large library of actions available for scheduling as events.
 Additionally, all of these actions can be used within analyze scripts.
@@ -27,6 +28,7 @@
 actions, along with detailed sections for each them.
 </p>
 
+
 <dl>
 <dt><a href="#PrintActions">Print</a></dt>
 <dd>Print actions are the primary way of saving data from an Avida experiments.</dd>
@@ -42,6 +44,9 @@
 <dd>Actions that allow user to control program execution, including experiment termination.</dd>
 </dl>
 
+<p>
+For a brief overview of writing a new action, please see <a href="#CreateAction">Creating an Action</a> below.
+</p>
 
 <p>&nbsp;</p>
 <h2>Alphabetical Listing of Available Actions</h2>
@@ -1174,6 +1179,45 @@
 </ul>
 
 
+<p>&nbsp;</p>
+<h2><a name="CreateAction">Creating an Action</a></h2>
+
+<p>
+The action source code is contained in the source/action directory.  
+Each of the individual <a href="#ActionCategories">action categories</a> has its own source code files (e.g. Landcape Actions are located in the LandscapeActions files).
+</p>
+<p>Each action is derrived from the cAction class.  Briefly, to get an action to work you must create a child class that has a Process and GetDescription function defined as well as a constructor.  You must also register this new class with the action library.</p>
+<p>So, with that quick review of what must be done, here is a step by step guide to creating an action:
+<ol>
+	<li>Identify which of the action categories your action should be assigned to.  There are six different action categories described <a href="#ActionCategories">above</a>.  Each category has a similar means of creating a new action, but do note that some action commands are generated via macros defined at the top of the files.  For instance, in the PrintActions file, you will notice a number of STATS_OUT_FILE macros being used to generate rather repetitively coded standard output files.&nbsp;</p></li>
+	<li><p>Create a new class in the file that follows proper naming conventions.  Any class should begin with "cAction" and be followed by the name of the action command you will register with the library.  For instance, if we were to create a new command "MyAction", we'd name the class cActionMyAction.  Below is a stub for this new action class:</p>
+			<p>
+			<pre>
+class cActionMyAction : public cAction
+{
+	private:
+		// Private data members for this action
+	public:
+		cActionMyAction(cWorld* world, const cString& args) : cAction(world, args) { ; }
+		
+		static const cString GetDescription() { return "Arguments: My Arguments"; }
+		
+		void Process(cAvidaContext& ctx)
+		{
+			//Perform whatever processing is needed when the action is triggered.
+		}
+};
+</pre></p>
+
+	<li><p>Define the private data members, constructor, description string in GetDescription, and the Process function.  Any arguments that you specify after the action name in the events configuration will be passed to your new class via the args argument in the constructor.</p></li>
+	<li><p>Register the new action with the action library.  At the bottom of each action definitions file, there are the commands that register the individual actions with the action library.  To register our example action "MyAction", we'd write<p>
+<p><pre>action_lib->Register<cActionMyAction>("MyAction");</pre><p>
+	<li><p>Test your action.</p></li>
+</ol>
+</p>
+
+
+
 <hr />
 <p>
 <a href="index.html">Return to the Index</a> &nbsp;|&nbsp;

Modified: development/source/main/cInstruction.cc
===================================================================
--- development/source/main/cInstruction.cc	2007-03-19 01:37:00 UTC (rev 1406)
+++ development/source/main/cInstruction.cc	2007-03-19 01:47:12 UTC (rev 1407)
@@ -43,3 +43,12 @@
   else m_operand = 254;
 }
 
+int cInstruction::ConvertSymbol(char symbol)
+{
+	int retval;
+	if (symbol >= 'a' && symbol <= 'z') retval = symbol - 'a';
+  else if (symbol >= 'A' && symbol <= 'Z') retval = symbol - 'A' + 26;
+  else if (symbol >= '0' && symbol <= '9') retval = symbol - '0' + 52;
+  else retval = 254;
+	return retval;
+}
\ No newline at end of file

Modified: development/source/main/cInstruction.h
===================================================================
--- development/source/main/cInstruction.h	2007-03-19 01:37:00 UTC (rev 1406)
+++ development/source/main/cInstruction.h	2007-03-19 01:47:12 UTC (rev 1407)
@@ -61,6 +61,8 @@
   // Some extra methods to convert too and from alpha-numeric symbols...
   char GetSymbol() const;
   void SetSymbol(char symbol);
+	
+	static int ConvertSymbol(const char symbol);
 };
 
 

Modified: development/source/tools/tArray.h
===================================================================
--- development/source/tools/tArray.h	2007-03-19 01:37:00 UTC (rev 1406)
+++ development/source/tools/tArray.h	2007-03-19 01:47:12 UTC (rev 1407)
@@ -49,7 +49,8 @@
 
 public:
   explicit tArray(const int size = 0) : m_data(NULL), m_size(0) { ResizeClear(size); }
-  tArray(const tArray& rhs) : m_data(NULL), m_size(0) { this->operator=(rhs); }
+  explicit tArray(const int size = 0, const T& init_val) : m_data(NULL), m_size(0) { Resize(size, init_val); }
+	tArray(const tArray& rhs) : m_data(NULL), m_size(0) { this->operator=(rhs); }
 
   ~tArray() { delete [] m_data; }