Documented more of MiniCron, and added some cool new help features to OptParser.

4 files changed, 67 insertions, 6 deletions

diff --git a/src/minicron.h b/src/minicron.h
index b100ad0..3e6beea 100644
--- a/src/minicron.h
+++ b/src/minicron.h
@@ -30,6 +30,12 @@ namespace Bu
          * By default a job will continually reschedule itself after being run
          * unless it calls stop() on it's job object, it is removed using
          * removeJob() on the cron object, or it is added with addJobOnce.
+         *
+         *@todo A minor change to the job execution system could allow a Timer to
+         * defer or reschedule execution instead of the job executing.  This would,
+         * in effect, allow us to do every type of interesting scheduling that
+         * systems like fcron offer, including time constrained load-balanced
+         * execution.
          */
         class MiniCron
         {
@@ -89,16 +95,35 @@ namespace Bu
                  */
                 virtual void removeJob( JobId jid );
 
+                /**
+                 * The baseclass for timer/schedulers for MiniCron jobs.  Classes that
+                 * inherit from this are used to determine when jobs will run and at
+                 * what interval.
+                 */
                 class Timer
                 {
                 public:
                         Timer();
                         virtual ~Timer();
 
+                        /**
+                         * Called by MiniCron when each job is run to determine the next
+                         * time that a job should be run.  When a job is run, this function
+                         * is actually called before the job is executed again so that the
+                         * job can tell when the next time it will be run will be.
+                         */
                         virtual time_t nextTime()=0;
+
+                        /**
+                         * This function should return a copy of the child class.
+                         */
                         virtual Timer *clone() const = 0;
                 };
 
+                /**
+                 * Execute the job every tInterval seconds, also you can delay the
+                 * first run by a different amount of time from the job's creation.
+                 */
                 class TimerInterval : public Timer
                 {
                 public:
@@ -113,6 +138,23 @@ namespace Bu
                         time_t tInterval;
                 };
 
+                /**
+                 * A much more general timer class that can be used for much more
+                 * "cron-like" functionality.  The constructor takes a string that
+                 * describes the times that the job should be run.  At the moment the
+                 * following schemes are understood:
+                 *
+                 * "daily [hour] [minute]"
+                 * "hourly [minute]"
+                 * "weekly [day] [hour] [minute]"
+                 *
+                 * In these examples each word in [brackets] represents a number that
+                 * matches the data type in the brackets.  [day] is the number of days
+                 * since sunday, 0-6.  You can also use lowercase three character
+                 * abbreviations for the day names.
+                 *
+                 * Many more forms follow.
+                 */
                 class TimerBasic : public Timer
                 {
                 public:
@@ -142,13 +184,21 @@ namespace Bu
                         Bu::FString sSpec;
                 };
                 
+                /**
+                 * Represents a MiniCron Job.  This class is used for both internal
+                 * job management as well as job slot interaction and control.  Objects
+                 * of this class are passed into the slots that are signaled when a job
+                 * is executed.
+                 */
                 class Job
                 {
                         friend class Bu::MiniCron;
-                public:
+                private:
                         Job( JobId jid, bool bRepeat=true );
                         virtual ~Job();
 
+                public:
+
                         /**
                          * Execute this job once, increment the runcount and schedule the
                          * next occurance of it.
diff --git a/src/optparser.cpp b/src/optparser.cpp
index 14e7418..081b26c 100644
--- a/src/optparser.cpp
+++ b/src/optparser.cpp
@@ -179,6 +179,11 @@ void Bu::OptParser::setOverride( const Bu::FString &sOpt, const Bu::FString &sOv
         hlOption.get( sOpt )->sOverride = sOverride;
 }
 
+void Bu::OptParser::setHelpDefault( const Bu::FString &sOpt, const Bu::FString &sTxt )
+{
+        hlOption.get( sOpt )->sHelpDefault = sTxt;
+}
+
 void Bu::OptParser::addHelpOption( char c, const Bu::FString &s, const Bu::FString &sHelp )
 {
         Option o;
@@ -213,8 +218,9 @@ int Bu::OptParser::optHelp( StrArray /*aParams*/ )
         {
                 if( (*i).cOpt != '\0' )
                         bHasShort = true;
-                if( (*i).sOpt && iMaxWidth < (*i).sOpt.getSize() )
-                        iMaxWidth = (*i).sOpt.getSize();
+                int lOptSize = (*i).sOpt.getSize() + (*i).sHelpDefault.getSize();
+                if( (*i).sOpt && iMaxWidth < lOptSize )
+                        iMaxWidth = lOptSize;
         }
         int iIndent = 4;
         if( bHasShort )
@@ -249,7 +255,8 @@ int Bu::OptParser::optHelp( StrArray /*aParams*/ )
                 {
                         if( (*i).sOpt )
                         {
-                                sio << "--" << Fmt(iMaxWidth, Fmt::Left) << (*i).sOpt;
+                                sio << "--" << Fmt(iMaxWidth, Fmt::Left)
+                                        << (*i).sOpt + (*i).sHelpDefault;
                         }
                         else
                         {
diff --git a/src/optparser.h b/src/optparser.h
index 89ef14d..6b0ae58 100644
--- a/src/optparser.h
+++ b/src/optparser.h
@@ -81,6 +81,7 @@ namespace Bu
                         OptionSignal sUsed;
                         _ValueProxy *pProxy;
                         Bu::FString sOverride;
+                        Bu::FString sHelpDefault;
                 };
         
         private:
@@ -157,6 +158,8 @@ namespace Bu
                 void setOverride( char cOpt, const Bu::FString &sOverride );
                 void setOverride( const Bu::FString &sOpt,
                                 const Bu::FString &sOverride );
+
+                void setHelpDefault( const Bu::FString &sOpt, const Bu::FString &sTxt );
                 
                 void addHelpOption( char c='h', const Bu::FString &s="help",
                                 const Bu::FString &sHelp="This help." );
diff --git a/src/tests/optparser.cpp b/src/tests/optparser.cpp
index 5c91351..449677d 100644
--- a/src/tests/optparser.cpp
+++ b/src/tests/optparser.cpp
@@ -34,10 +34,11 @@ public:
                         true
                         );
                 addOption( sVar, 's', "str", "Set a variable, see what it does.");
-                addOption( iBob, "bob", "Change iBob to wahtever you want.");
-                addOption( dBob, 'd', "Change dBob to wahtever you want.");
+                addOption( iBob, "bob", "Change iBob to whatever you want.");
+                addOption( dBob, 'd', "Change dBob to whatever you want.");
 
                 setOverride("str", "Bob!");
+                setHelpDefault("bob", "=542");
         
                 addHelpOption();