#
# $Id: timer.pretty,v 1.11 1999/09/10 22:19:23 joi Exp joi $
# $Log: timer.pretty,v $
# Revision 1.11  1999/09/10 22:19:23  joi
# Queue bug from this morning's version corrected.
# Quoting the entire file into a mush now creates a complete system.
# Many comments added.
#
# Revision 1.10  1999/09/10 15:40:17  joi
# /list and /schedule output reformatted and sorted by next heartbeat
# counted item support added
# at <time>, at +<offset> commands added.
# u_next_midnight, tr_kick_me attributes added.
# new commands initialize for next midnight, not next modulo.
#
# Revision 1.9  1998/08/16 19:31:33  joi
# Checkpoint.
#
# Revision 1.8  1998/08/16 01:08:38  joi
# Checkpoint.  Adding nifty formatting and some user-friendly scheduling
# commands.
#
# Revision 1.7  1998/08/15 05:22:45  joi
# Added +timer commands to manipulate events easily.
# Added wizhelp.
# Added event offsets.
# Spiffied up the descs.
#
# Revision 1.6  1997/12/10 03:14:52  joi
# Moving setup of stats object into that object's source file.
#
# Revision 1.5  1997/12/09 23:58:57  joi
# Added hooks to trigger the boozers database.
#
# Revision 1.4  1997/07/31 17:53:40  joi
# Changed to have it trigger an attrib on #131 stats_object instead.
#
# Revision 1.3  1997/07/31 00:39:34  joi
# Converted it into a cron facility.  Heartbeats every 5 minutes.
#
# Revision 1.2  1997/07/22 04:09:55  joi
# Corrected update command, commented out multiplier so it doesn't overwrite my
# production version.
#
# Revision 1.1  1997/07/21 17:41:17  joi
# Initial revision
#
#
# Suggested Tinyfugue command to use to quote this in via the unprettifier:
#
#   /quote -w -1 !"unprettify -v < ~/MyMush/timer.pretty"
#
# Do NOT use -0 with the above command if you're quoting the entire file
# in.  
#
# #include dbrefs.inc
#-
###############################################################################
#
# TODO LIST:
# The one thing it seems to be missing is a way to schedule jobs for every
# Nth day of the month, i.e., at midnight on the 1st of every month.
#
# Add ability for mortals to schedule @pemits to objects they own.
#   (add ownership info to items.  Use the comment attribute.)
#   (requires changing permissions on all the commands and filtering
#   /list and /schedule to only display that user's items.)
#
###############################################################################
#
# start of user configurable stuff
#
###############################################################################

###############################################################################
#
# Master Timer 
#
# This object does all the work.  It keeps a @wait on the semaphore queue
# and handles triggering the items in the schedule.
#
# This object goes someplace safe, but NOT in your master room.
#
# This object does not need to be INHERIT to run, but if you plan on @triggering
# OTHER players' objects with it, then it needs to be inherit.
#
# I don't have mine set inherit...  I use @listens on player objects and
# a @pemit to fire them off.  If you restrict its actions to @pemit, and your
# mush allows mortals to far-pemit, then nothing in this whole system needs to 
# be owned by a wizard player, either.  But, it requires a wizard to use the
# +timer commands to configure it.  A determined non-wiz could figure out the 
# data object and set those attributes directly.   (ick.)
#
###############################################################################
# 
@pemit me=Looking for an existing Master Timer. Don't worry about "I don't see that here"
" messages.
-
@switch/first isdbref(v(dbref_master_timer))+[owner(v(dbref_master_timer))]=
  1+%#,
  {
    @pemit me=Re-using object [v(dbref_master_timer))];
  },
  {
    @create Master Timer;
    &dbref_master_timer me=[num(Master Timer)];
  }
-
###############################################################################
#
# Timer Data
# 
# Master Timer is parented to this for easy access to data attributes.
# +timer/* commands from the Global Object are used to configure the items
# stored here.  This object is kept in Master Timer's inventory.
#
###############################################################################
@pemit me=Looking for an existing Timer Data. Don't worry about "I don't see that here"
" messages.
-
@switch/first isdbref(v(dbref_timer_data))+[owner(v(dbref_timer_data))]=
  1+%#,
  {
   @pemit me=Re-using object [v(dbref_timer_data)];
  },
  {
    @create Timer Data;
    &dbref_timer_data me=[num(Timer Data)];
    &dbref_master_timer Timer Data=[v(dbref_master_timer)];
  }
-
###############################################################################
#
# Global Object
# 
# This should be a non-wiz/non-inherit global object in your Master Room.  If you already
# have one, place a &dbref_global_object attribute on yourself containing the
# dbref of your existing object.  
#
# If you don't already have such an object, or you don't want to mix the
# Timer's globals with your existing ones (good idea for testing, anyway)
# then you need to put this new Global Object in your Master Room.
# 
###############################################################################
@pemit me=Looking for an existing Global Object. Don't worry about "I don't see that here"
" messages.
-
@switch/first isdbref(v(dbref_global_object))+[owner(v(dbref_global_object))]=
  1,
  {
   @pemit me=Re-using object [v(dbref_global_object)];
  },
  {
    @create Global Object;
    &dbref_global_object me=[num(Global Object)];
    @set v(dbref_global_object)=COMMANDS;
  }
-
###############################################################################
#
# Global Object Parent
# 
# This is a data-storage object which the Global Object is Parented to.
# As with the Global Object, if you already have one, you may use it by
# placing &dbref_global_object_parent on yourself containing the dbref of 
# your existing object.
#
# Otherwise, this object goes somewhere safe, but NOT in your master room.
# 
###############################################################################
@pemit me=Looking for an existing Global Object Parent. Don't worry about "I don't see that here"
" messages.
-
@switch/first isdbref(v(dbref_global_object_parent))+[owner(v(dbref_global_object_parent))]=
  1,
  {
   @pemit me=Re-using object [v(dbref_global_object_parent)];
  },
  {
    @create Global Object Parent;
    &dbref_global_object_parent me=[num(Global Object Parent)];
    @parent [v(dbref_global_object)]=[v(dbref_global_object_parent)];
  }
-
###############################################################################
#
# Help Object 
# 
# This object contains the HELP_ and WIZHELP_ entries.  These are compatible
# with my +help system.  Feel free to rearrange these to suit your own +help
# command.
#
# This goes someplace safe, but NOT in your master room.
# 
###############################################################################
@pemit me=Looking for an existing Help Object. Don't worry about "I don't see that here"
" messages.
-
@switch/first isdbref(v(dbref_help_object))+[owner(v(dbref_help_object))]=
  1,
  {
   @pemit me=Re-using object [v(dbref_help_object)];
  },
  {
    @create Help Object;
    &dbref_help_object me=[num(Help Object)];
    &dbref_help_object [v(dbref_global_object_parent)]=[num(Help Object)];
  }
-
###############################################################################
#
# end of user configurable stuff
#
###############################################################################

@fo me=&dbref_timer_data [v(dbref_master_timer)]=[num(Timer Data)]
-
@fo me=&dbref_timer_data me=[num(Timer Data)]
-
@fo me=@va [v(dbref_master_timer)]=[v(dbref_timer_data)]
-
@fo me=@parent [v(dbref_master_timer)]=[v(dbref_timer_data)]
-
@fo me=@link [v(dbref_timer_data)]=[v(dbref_master_timer)]
-
@set [v(dbref_timer_data)]=sticky
-
drop timer data
-
# ---
#
#   /quote -w -1 !"unprettify -v U_TRIGGER_LIST < ~/MyMush/timer.pretty"
#
&U_TRIGGER_LIST [v(dbref_master_timer)]=
  edit(lattr(%va/trw_*),TRW_,)
-
&U_TRIGGER_LIST_SORTED [v(dbref_master_timer)]=
  setq(9,
    sort(
      iter(
        lattr(%va/trw_*),
        v(NHB_[after(##,_)]):##
      ),
    )
  )
  [setq(9,
    iter(
      %q9,
      after(##,:)
    )
  )]
  [edit(
    %q9,
    TRW_,
  )]
-
# mod=1, off=0, nhb=at time
#
#   /quote -w -1 !"unprettify -v Desc < ~/MyMush/timer.pretty"
#
@Desc [v(dbref_master_timer)]=
  It is presently:%r
  %t [ time() ]%r
  The next Master Timer update will occur at:%r
  %t [ convsecs(v(next_heartbeat)) ]%r
  %t [ sub(v(next_heartbeat),secs()) ] seconds from now.%r
  %r
  [ljust(Triggers,9)] [rjust(Offset,6)] [rjust(Modulo,8)] CNT [ljust(Last,24)] \
     [ljust(Next,24)]
  %r[repeat(-,79)]
  [iter(u(u_trigger_list_sorted),
   %r[ljust(##,9)] \
     [switch(v(OFF_##)+[v(MOD_##)],
       0+1,
         [space(15)] [rjust(v(CNT_##),3)] [space(24)],
       [rjust(v(OFF_##),6)] [rjust(v(MOD_##),8)] [rjust(v(CNT_##),3)] \
       [switch(gt(v(LHB_##),0),1,convsecs(v(LHB_##)),space(24))]
     )] \ 
     [switch(gt(v(NHB_##),0),1,convsecs(v(NHB_##)),space(24))]
  )]
-
# /quote -w -1 !"unprettify -v Startup TR_KICK_ME <~/MyMush/timer.pretty"
#
@Startup [v(dbref_master_timer)]=
  &last_restart me=secs();
  @trigger me/tr_kick_me;
-
#
# retrigger.  Now that all the previous items have updated their heartbeat
# values, figure out which is the next one to run and compute a wait that
# will bring us out in time to trigger it exactly on time.
#
# I'm using a tinymush feature here.  I'm using the timed sempahore version
# of @wait, but I am NOT using any @notify commands.  This means the commnds
# placed on the semaphore queue will run after the timeout expires.  The reason
# I'm doing this is because a tinymush object can't @halt itself and keep
# running, but it can @drain itself and continue.  I want the device to be
# able to immediately recompute its wait period when ever someone does something
# that could change the item order.
#
&TR_KICK_ME [v(dbref_master_timer)]=
  @drain me;
  &next_heartbeat me=u(u_next_beat);
  @wait me/[max(0,add(v(next_heartbeat),-[secs()],v(trigger_lag)))]=@tr me/tr_heartbeat;
-
##############################################################################
# 
# This is the main loop.  It filters all of the known TRW work attributes
# to find those that are ready to be run.  Those are pushed onto the queue
# and their timers are updated.
#
# Once all the TRW work attributes are checked, a new wait value is computed
# and used to push a retrigger into the queue.
#
##############################################################################
# /quote -w -1 !"unprettify -v TR_HEARTBEAT  <~/MyMush/timer.pretty"
#
&TR_HEARTBEAT [v(dbref_master_timer)]=
  pose thinks.;
#
# This is the bit that triggers off all the work people want done at
# this tick of time.  Each item has its own heartbeat value.
# Default modulo value is 3600, to have an item run at the top of each hour.
#
  @dolist \
    filter(u_trigger_filt,u(u_trigger_list))=
  {
    @tr me/TRW_##;
    pose triggers ## at [time()].%rPrevious: [convsecs(v(LHB_##))] Current: [convsecs(v(NHB_##))];
    &nhb_## %va=add(u(u_next_time_modulo,default(me/MOD_##,3600)),default(me/OFF_##,0));
    &lhb_## %va=secs();
    @switch/first \
      setq(1,default(%va/cnt_##,#-1))
      %q1=#-1,
      {
#         do nothing, has no count value.
      },
      1,
      {
#         timed out.  delete it.
        @wipe %va/*_##;
      },
      {
         &cnt_## %va=sub(%q1,1);
      };
  };
  @tr me/tr_kick_me;
-
#
# call this one just to trigger one item right now.
#
# /quote -w -1 !"unprettify -v TR_ONE  <~/MyMush/timer.pretty"
#
&TR_ONE [v(dbref_master_timer)]=
    @tr me/TRW_%0;
    &NHB_%0 %va=add(u(u_next_time_modulo,default(me/MOD_%0,3600)),default(me/OFF_%0,0));
    &LHB_%0 %va=secs();
    @switch/first \
      setq(1,default(%va/cnt_%0,#-1))
      %q1=#-1,
      {
#         do nothing, has no count value.
      },
      1,
      {
#         timed out.  delete it.
        @wipe %va/*_%0;
      },
      {
         &cnt_%0 %va=sub(%q1,1);
      };
    @trigger me/tr_kick_me;
-
&TRIGGER_LAG [v(dbref_master_timer)]=
  -3
-
#
# This function accepts a number in %0 and returns
# the earliest future secs() value that is a multiple
# of that value.  This value is also adjusted for the host's timezone.
#
# /quote -w -1 !"unprettify -v U_NEXT_TIME_MODULO  <~/MyMush/timer.pretty"
#
&U_NEXT_TIME_MODULO [v(dbref_master_timer)]=
  setq(9,secs())
  [add(
    sub(
      %q9,
      mod(%q9,%0)
    ),
    %0,
    %1
  )]
-
# /quote -w -1 !"unprettify -v U_FIND_NEXT  <~/MyMush/timer.pretty"
#
#&U_FIND_NEXT [v(dbref_master_timer)]= 
#  setq(9,secs())
#  [add(
#    v(off_%0),
#    mod(
#      add(
#        %q9,
#        v(mod_%0),
#        -1
#      ),
#      v(mod_%0)
#    )
#  )]
#-
#
# this filter returns true if the work item is due to be run.
# Any time the master heart beats, this filter is used to run
# all items that are due, not just the first one on the list.
#
&U_TRIGGER_FILT [v(dbref_master_timer)]=
  gte(secs(),add(v(TRIGGER_LAG),v(NHB_%0)))
-
#
# this function returns the earliest upcoming heartbeat.
# This will determine how long the heart @waits before it
# beats again. If there are no NHB attributes on the data object
# yet, provide a default of once daily.
#
# /quote -w -1 !"unprettify -v U_NEXT_BEAT  <~/MyMush/timer.pretty"
#
&U_NEXT_BEAT [v(dbref_master_timer)]=
  first(
    sort(
      iter(
        lattr(%va/NHB_*),
        v(##)
      ) [add(secs(),86400)]
    )
  )
-
#&U_FUTURE_BEAT [v(dbref_master_timer)]=
#   first(sort(iter(edit(lattr(%va/LHB_*),LHB_,),add(v(LHB_##),v(MOD_##)))))
#-
#  iter(min%([join(iter(lattr(%va/NHB*),v(##)),,%,)]%),##)
#-
@set [v(dbref_master_timer)]=COMMANDS
-
##############################################################################
#
# Timer Data Object
#
##############################################################################
#
@Use [v(dbref_master_timer)]=
"
" Invent an event name, for instance, 'THING'.
" Add two attributes to the Data object for the new event, as follows:
"
"   MOD_THING Timer Data = How often THING's heart beats, in seconds.
"     60 = once a minute
"     3600 = once every hour
"     86400 = once a day
"     604800 = once a week
"      etc
"
"   TRW_THING  Timer Data = code to trigger for THING.
"
" Additional values that are stored on the data object are:
"   NHB_THING = Secs() value when THING be triggered next.
"   LHB_THING = Secs() value when THING was last triggered.
" These are computed and stored automatically, you don't need to
" provide them yourself.
-
##############################################################################
#
# /quote -w -1 !"unprettify -v Desc <~/MyMush/timer.pretty"
#
&Desc [v(dbref_timer_data)]=
  Master Timer's Schedule:%r
    [ljust(Item,12)] [ljust(Scheduled,28)] [ljust(Trigger,36)]%r
    Comment%r
    [repeat(-,79)]
  [iter(
    u(v(dbref_master_timer)/u_trigger_list_sorted),
    %r[ljust(##,12)] [ljust(u(v(dbref_master_timer)/u_format_time,##),28)] \
      [left(v(TRW_##),36)%r
    [v(COM_##)]]
  )]
-
@Use [v(dbref_timer_data)]=
  @pemit %#=See the Master Timer for instructions.
-
#
# Okay, the stuff is built.  Start it running.
#
@trigger [v(dbref_master_timer)]/tr_heartbeat
-
##############################################################################
#
# Global +Timer commands.  Need not be inherit or wiz-owned unless the objects
# you're triggering are not owned by the same player.  You can get around 
# control issues with @pemits and @listens to secure internal objects.
#
##############################################################################
#
# /quote -w -1 !"unprettify -v DO_TIMER_LIST <~/MyMush/timer.pretty"
#
# Set &dbref_global_object_parent to the data parent of your global commands
# object, or to the global commands object itself if you aren't using a
# parent to hold data attributes.
#
@fo me=&DBREF_MASTER_TIMER [v(dbref_global_object_parent)]=[v(dbref_master_timer)]
-
@fo me=&DBREF_TIMER_DATA [v(dbref_global_object_parent)]=[v(dbref_timer_data)]
-
&DO_TIMER_LIST [v(dbref_global_object)]=$+timer/l*:
  @switch/first \
    hasflag(%#,WIZARD)=
    1,
    {
        @pemit %#=get_eval(v(dbref_timer_data)/desc)
    },
    {
        @pemit %#=u(u_huh);
    }
-
&DO_TIMER_SCHEDULE [v(dbref_global_object)]=$+timer/sc*:
  @switch/first \
    hasflag(%#,WIZARD)=
    1,
    {
        @pemit %#=get_eval(v(dbref_master_timer)/desc)
    },
    {
        @pemit %#=u(u_huh);
    }
-
#
# /quote -w -1 !"unprettify -v U_HUH <~/MyMush/timer.pretty"
#
&U_HUH [v(dbref_global_object)]=
  Huh?%b%b(Type "help" for help.)
-
#
# %0 = timer name
# %1 = dbref of user to pemit
#
# /quote -w -1 !"unprettify -v TR_TIMER_CHECK <~/MyMush/timer.pretty"
#
&TR_TIMER_CHECK [v(dbref_master_timer)]=
  @switch/all \
      strmatch(get(v(dbref_timer_data)/trw_%0),@@)+
      [hasattr(v(dbref_timer_data),mod_%0)]=
      0+1,@pemit %1=Setup complete for Timer %0.,
      ?+0,@pemit %1=Now use '+timer/set %0' to configure the period between events.,
      1+?,@pemit %1=Now use '+timer/trigger %0=command' to configure the @trigger or \
          @pemit command the timer will execute.;
-
# /quote -w -1 !"unprettify -v DO_TIMER_ADD <~/MyMush/timer.pretty"
#
&DO_TIMER_ADD [v(dbref_global_object)]=$+timer/add *=*:
  @switch/first \
    setq(0,secure(%0))
    [setq(1,secure(%1))]
    [hasflag(%#,WIZARD)]=
    1,
    {
      &com_%0 [v(dbref_timer_data)]=%q1;
      &trw_%0 [v(dbref_timer_data)]=@@;
      &nhb_%0 [v(dbref_timer_data)]=
          u(v(dbref_master_timer)/u_next_midnight);
      @pemit %#=
        switch(
          get(v(dbref_timer_data)/com_%q0),
          %q1,Event %q0 added with comment "%q1".,
          Error setting timer value.  %q0 is not a good name.
        );
      @tr v(dbref_master_timer)/tr_timer_check=%q0,%#;
      @trigger v(dbref_master_timer)/tr_kick_me;
    },
    {
        @pemit %#=u(u_huh);
    }
-
#
# /quote -w -1 !"unprettify -v DO_TIMER_SET <~/MyMush/timer.pretty"
#
&DO_TIMER_SET [v(dbref_global_object)]=$+timer/set *=every *:
  @switch/first \
    setq(0,secure(%0))
    [setq(1,secure(%1))]
    [hasflag(%#,WIZARD)]+[and(isnum(%q1),gt(%q1,0))]=
    1+1,
    {
       &mod_%q0 [v(dbref_timer_data)]=%q1;
       &NHB_%0 [v(dbref_timer_data)]=add(
         u(v(dbref_master_timer)/u_next_time_modulo,
           default(v(dbref_master_timer)/MOD_%0,3600)),
         default(me/OFF_%0,0)
        );
       @pemit %#=
         switch(
           get(v(dbref_timer_data)/mod_%q0),
           %q1,Modulo for Timer %q0 set to [get(v(dbref_timer_data)/mod_%q0)].,
           Error setting timer value.  %q0 is not a good name.
          );
       @trigger v(dbref_master_timer)/tr_check_timer=%q0,%#;
       @trigger v(dbref_master_timer)/tr_kick_me;
    },
    1+0,
    {
        @pemit %#=The modulo value must be a positive number.
    },
    {
        @pemit %#=u(u_huh);
    }
-
#
# /quote -w -1 !"unprettify -v DO_TIMER_TRIGGER <~/MyMush/timer.pretty"
#
&DO_TIMER_TRIGGER [v(dbref_global_object)]=$+timer/trigger *=*:
  @switch/first \
    setq(0,secure(%0))
    [hasflag(%#,WIZARD)]=
    1,
    {
       &trw_%q0 [v(dbref_timer_data)]=%1;
       @pemit %#=
         switch(
           get(v(dbref_timer_data)/trw_%q0),
           %1,Trigger code for Timer %q0 set to '[get(v(dbref_timer_data)/trw_%q0)]'.,
           Error setting timer trigger.  %q0 is not a good name.
          );
       @pemit %#=
         switch(
           hasattr(v(dbref_timer_data),mod_%q0),
           1,Setup complete for Timer %q0.,
           Default Modulo is 3600 (top of the hour.)%r
         );
       @trigger v(dbref_master_timer)/tr_check_timer=%q0,%#;
    },
    {
        @pemit %#=u(u_huh);
    }
-
# /quote -w -1 !"unprettify -v DO_TIMER_TRIGGER <~/MyMush/timer.pretty"
#
&DO_TIMER_KICK [v(dbref_global_object)]=$+timer/kick *:
  @switch/first \
    setq(0,secure(%0))
    [hasflag(%#,WIZARD)]+[hasattr(v(dbref_timer_data),trw_%q0)]=
    1+1,
    {
      @tr [v(dbref_master_timer)]/tr_one=%q0;
      @pemit %#=%q0 has been triggered.;
    },
    1+0,
    {
      @pemit %#=There is no such Timer.;
    },
    {
      @pemit %#=u(u_huh);
    }
-
# /quote -w -1 !"unprettify -v DO_TIMER_DELETE <~/MyMush/timer.pretty"
#
&DO_TIMER_DELETE [v(dbref_global_object)]=$+timer/delete *:
  @switch/first \
    setq(0,secure(%0))
    [hasflag(%#,WIZARD)]+[hasattr(v(dbref_timer_data),trw_%q0)]=
    1+1,
    {
      @wipe [v(dbref_timer_data)]/*_%q0;
      @pemit %#=%q0 has been deleted.;
      @trigger v(dbref_master_timer)/tr_kick_me;
    },
    1+0,
    {
      @pemit %#=There is no such Timer.;
    },
    {
      @pemit %#=u(u_huh);
    }
-
# /quote -w -1 !"unprettify -v DO_TIMER_OFFSET <~/MyMush/timer.pretty"
#
&DO_TIMER_OFFSET [v(dbref_global_object)]=$+timer/offset *=*:
  @switch/first \
    setq(0,secure(%0))
    [setq(1,secure(%1))]
    [hasflag(%#,WIZARD)]+[hasattr(v(dbref_timer_data),MOD_%q0)]+[isnum(%q1)]=
    1+1+1,
    {
       &off_%q0 [v(dbref_timer_data)]=%q1;
       @pemit %#=
         switch(
           get(v(dbref_timer_data)/off_%q0),
           %q1,Offset for Timer %q0 set to [get(v(dbref_timer_data)/off_%q0)].,
           Error setting timer value.  %q0 is not a good name.
          );
       @trigger v(dbref_master_timer)/tr_check_timer=%q0,%#;
       @trigger v(dbref_master_timer)/tr_kick_me;
    },
    1+1+0,
    {
        @pemit %#=The offset value must be a number.
    },
    1+0+*,
    {
        @pemit %#=There is no such trigger.  Please '+timer/add %q0=every value' or \
          '+timer/trigger %q0=command' first.
    },
    0+*,
    {
        @pemit %#=u(u_huh);
    }
-
# /quote -w -1 !"unprettify -v DO_TIMER_HELP <~/MyMush/timer.pretty"
#
&DO_TIMER_HELP [v(dbref_global_object)]=$+timer:
  @switch/first \
    hasflag(%#,WIZARD)=
  1,
  {
    @pemit %#=get_eval(v(dbref_help_object)/wizhelp_timer);
  },
  {
    @pemit %#=u(u_huh)
  }
-
#
# Help Template entry.
# /quote -w -0 !"unprettify -v WIZHELP_TIMER <~/MyMush/timer.pretty"
#
&WIZHELP_TIMER [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/add name=comment
"  +timer/set name=every <seconds> | daily at <time> |
"       weekly on day at <time> | at <date-time> | at +<count>\[s|m|h|d|w\]
"  +timer/trigger name=code
"  +timer/offset name=seconds
"  +timer/count name=count
"  +timer/delete name
"  +timer/list
"  +timer/schedule
"  +timer/kick name
"
"Examples:
"  +timer/set clock=every 60
"  +timer/trigger clock=@pemit #1=Tick.
"  +timer/kick clock
"
"This wizard-only command manipulates the events on the master timer.
"
"See Also: timer *
-
#
# Help Template entry.
# /quote -w -0 !"unprettify -v WIZHELP_TIMER_SET <~/MyMush/timer.pretty"
#
&WIZHELP_TIMER_SET [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/set name=every <seconds>
"  +timer/set name=daily at <time>
"  +timer/set name=daily at +<count>\[s|m|h|d|w\]
"  +timer/set name=weekly on <day> at <time>
"  +timer/set name=at <date-time>
"
"Examples:
"  +timer/set clock=every 60
"  +timer/set clock=at Thu Sep  9 21:10:59 1999
"  +timer/set clock=at +10m
"
"This command schedules an event to occur at some time in the future.
"New events have a default offset of zero seconds, and
"no trigger code assigned to it.
"
"See Also: timer *
-
# /quote -w -0 !"unprettify -v WIZHELP_TIMER_ADD <~/MyMush/timer.pretty"
#
&WIZHELP_TIMER_ADD [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/add name=comment
"
"Examples:
"  +timer/add clock=Wake up a tired wizard.
"
"This command creates a new event, assigning a comment or short
"description to it.
"
"Newly added events have a default period of 60 minutes, an offset of
"zero (meaning they occur at the top of the hour) and no assigned 
"trigger code. 
"
"See Also: timer *
-
&WIZHELP_TIMER_TRIGGER [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/trigger name=code
"
"Examples:
"  +timer/trigger clock=@pemit #1=Tick.
"
"This command assigns a trigger command to an event name.  The default
"period for a new event is 3600 seconds (once hourly) and the default
"offset is zero (top of the hour.)
"
"The code assigned to an event trigger should be a @trigger command or
"a @pemit command, and should not be very long or complex, otherwise
"there may be lag introduced in other triggers scheduled for the same
"time.
"
"If that other object presents control issues, then the master timer may 
"need to be wiz-owned and/or inherit.
"
"See Also: timer *
-
&WIZHELP_TIMER_OFFSET [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/offset name=seconds
"
"Examples:
"  +timer/offset clock=5
"
"This command assigns an offset to an event.  The offset is used to
"adjust the time of the event forwards or backwards in relationship
"to the period.  
"
"For instance, to create an event that runs four times an hour starting
"at five minutes after the hour, assign the event a period of 900 and
"an offset of 300.
"
"
"See Also: timer *
-
&WIZHELP_TIMER_KICK [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/kick name=
"
"Examples:
"  +timer/kick clock
"
"This command causes the timer to trigger the event immediately.  This
"can be used to initialize the event, if desired.  Otherwise, the Timer
"will not know of new events until the next heartbeat.
"
"The time of the next heartbeat can be checked with '+timer/schedule'.
"
"See Also: timer *
-
&WIZHELP_TIMER_SCHEDULE [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/schedule 
"
"This command displays the current schedule of events.  The time of
"each event's most recent triggering, and the scheduled time of its next
"triggering are displayed, along with their names, offsets, and periods.
"
"To see the code triggered for each event, use '+timer/list'.
"
"See Also: timer *
-
&WIZHELP_TIMER_LIST [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/list 
"
"This command displays the Timer's list of configured events.  Each
"event's name, offset, period, and trigger code are displayed.
"
"To see when these events were last triggered, and when they are 
"scheduled to be triggered, use the '+timer/schedule' command.
"
"See Also: timer *
-
&WIZHELP_TIMER_DELETE [v(dbref_help_object)]=
########################################################################
"The syntax of the command is:
"  +timer/delete name 
"
"This command removes an event from the Timer.  
"
"See Also: timer *
-
# /quote -w -1 !"unprettify -v U_PREV_MIDNIGHT  <~/MyMush/timer.pretty"
#
&U_PREV_MIDNIGHT [v(dbref_master_timer)]=
  convtime(replace(time(),4,00:00:00))
-
# /quote -w -1 !"unprettify -v U_NEXT_MIDNIGHT  <~/MyMush/timer.pretty"
#
&U_NEXT_MIDNIGHT [v(dbref_master_timer)]=
  add(
    u(u_prev_midnight),
    v(secs_in_day)
  )
-
#
# this function accepts a day, ie "Mon", and returns the offset
# of that day within the week.  IE, Sun = 0, Mon =1, Sat = 6, etc.
#
&U_DAY_OF_WEEK [v(dbref_master_timer)]=
  setq(9,
    sub(
      match(Sun Mon Tue Wed Thu Fri Sat,%0),
      1
    )
  )
  [switch(
    %q9,
    -1,#-1 INVALID DAY,
    %q9
  )]
-
#
# some useful constants.
#
@fo me=
  &secs_in_hour [v(dbref_master_timer)]=
    mul(60,60)
-
@fo me=
  &secs_in_day [v(dbref_master_timer)]=
    mul(24,60,60)
-
@fo me=
  &secs_in_week [v(dbref_master_timer)]=
    mul(7,24,60,60)
-
#
# have the timer recompute these values once a day.
#
# /quote -w -1 !"unprettify -v TR_CONFIG  <~/MyMush/timer.pretty"
#
&TR_CONFIG [v(dbref_master_timer)]= 
  &secs_tz_offset me=convtime(Thu Jan  1 00:00:00 1970);
  &secs_dst_offset me=convtime(convsecs(0));
  &secs_adj me=sub(get(#73/secs_tz_offset),get(#73/secs_dst_offset));
-
#
# this function accepts a time and makes sure it has 3 sets of digits in it,
# otherwise convtime() gets upset.
#
# /quote -w -1 !"unprettify -v U_NORMALIZE_TIME  <~/MyMush/timer.pretty"
#
&U_NORMALIZE_TIME [v(dbref_master_timer)]=
  switch(%0,
    *:*:*,%0,
    *:*,%0:00,
    %0:00:00
  )
-
#
# this function accepts an hour and an optional day and computes
# an offset for them.  If the day is not provided, the offset is
# against midnight.  If the day is provided, the offset is against
# Sunday morning at midnight.
#
# u(u_compute_offset,10:00,Mon)
# u(u_compute_offset,10:00)
#
# The time can be supplied at just an hour "10", an hour and minute,
# "10:30", or as "10:30:05"
#
# The day is optional and defaults to Sunday.
#
# /quote -w -1 !"unprettify -v U_COMPUTE_OFFSET  <~/MyMush/timer.pretty"
#
&U_COMPUTE_OFFSET [v(dbref_master_timer)]= 
  setq(9,time())
  [setq(8,u(u_normalize_time,%0))]
  [add(
    sub(
      convtime(replace(%q9,4,%q8)),
      convtime(replace(%q9,4,00:00:00))
    ),
    mul(
      v(secs_in_day),
      u(u_day_of_week,%1)
    )
  )]
-
#
# /quote -w -1 !"unprettify -v U_PREV_WEEK  <~/MyMush/timer.pretty"
#
# this function returns the secs value from midnight of the previous
# sunday.  IE the beginning of this week.
#
&U_PREV_WEEK [v(dbref_master_timer)]=
  sub(
    u(u_prev_midnight),
    mul(
      u(u_day_of_week,first(time())),
      v(secs_in_day)
    )
  )
-
#
# /quote -w -1 !"unprettify -v DO_TIMER_SET_DAILY  <~/MyMush/timer.pretty"
#
&DO_TIMER_SET_DAILY [v(dbref_global_object)]=$+timer/set *=daily at *:
  @switch/first \
    setq(0,secure(%0))
    [setq(1,secure(%1))]
    [setq(2,secure(%2))]
    [hasflag(%#,WIZARD)]+[isnum(edit(%q1,:,))]+[hasattr(v(dbref_master_timer),com_%q0)]=
    1+1+1,
    {
      &mod_%q0 [v(dbref_timer_data)]=
        [get(v(dbref_master_timer)/secs_in_day)];
      &off_%q0 [v(dbref_timer_data)]=
        [u(v(dbref_master_timer)/u_compute_offset,%q1)];
      @pemit %#=Event %q0 added with period [get(v(dbref_master_timer)/mod_%q0)] and offset \
        [get(v(dbref_master_timer)/off_%q0)].;
      @trigger v(dbref_master_timer)/tr_check_timer=%q0,%#;
      @trigger v(dbref_master_timer)/tr_kick_me;
    },
    1+1+0,
    {
      @pemit %#=That event does not exist.  Use '+timer/add name=comment'.
    },
    1+0+*,
    {
      @pemit %#=Invalid time specified.  Please provide something like \
        '10', '10:30', or '10:30:15'.
    },
    0+*,
    {
      @pemit %#=u(u_huh)
    }
-
#
# u(u_format_time,##)
#
# Give this function an event name and it will print a formatted
# reprensation of the schedule of that event.
#
# ie, "every 5 minutes","hourly at 45:05", "Daily at 13:30:05",
# "Monday at 10:30:15"
#
# /quote -w -1 !"unprettify -v U_FORMAT_TIME  <~/MyMush/timer.pretty"
#
#
&U_FORMAT_TIME [v(dbref_master_timer)]=
  setq(9,default(me/mod_%0,v(secs_in_day)))
  [setq(8,default(me/off_%0,0))]
  [switch(
    1,
#
# Is it an one-shot event?
#
    and(eq(v(mod_%0),1),eq(v(off_%0),0)),
    At [convsecs(v(nhb_%0))],
#
# is it a an hourly event? 
#
    eq(%q9,v(secs_in_hour)),
      Hourly at [u(u_convert_offset2hour,%q8)],
#
# Is it a daily event?
#
    eq(%q9,v(secs_in_day)),
      Daily at [u(u_convert_offset2hour,%q8)],
#
# Is it a weekly event?
#
    eq(%q9,v(secs_in_week)),
      [u(u_convert_offset2weekday)] at [u(u_convert_offset2hour,%q8)],
#
# Dunno what this is.
#
    Every %q9 Offset %q8
  )]
-
#
# this function accepts an offset number and returns the hour it        
# represents.  The number is modulo 86400.
#
# /quote -w -1 !"unprettify -v U_CONVERT_OFFSET  <~/MyMush/timer.pretty"
#
&U_CONVERT_OFFSET2HOUR [v(dbref_master_timer)]=
    extract(
        convsecs(
          add(
            mod(%0,v(secs_in_day)),
            u(u_prev_midnight)
          )
        ),
        4,1
      )
-
&U_CONVERT_OFFSET2WEEKDAY [v(dbref_master_timer)]=
    first(
        convsecs(
          add(
            u(u_prev_week),
            %0
          )
        )
      )
-
#
# /quote -w -1 !"unprettify -v DO_TIMER_SET_AT  <~/MyMush/timer.pretty"
#
&DO_TIMER_SET_AT [v(dbref_global_object)]=$+timer/set *=at *:
  @switch/first \
    setq(0,secure(%0))
    [setq(1,secure(%1))]
    [switch(%q1,+*,
      [setq(1,after(%q1,+))]
      [setq(2,
        switch(%q1,
          *s,1[setq(1,before(%q1,s))],
          *m,60[setq(1,before(%q1,m))],
          *h,3600[setq(1,before(%q1,h))],
          *d,86400[setq(1,before(%q1,d))],
          *w,604800[setq(1,before(%q1,w))],
          1
        )
      )]
      [setq(1,
        convsecs(
          add(
            mul(
              %q1,
              %q2
            ),
            secs()
          )
        )
      )],
      setq(2,1)
    )]
    [hasflag(%#,WIZARD)]+
    [isnum(setq(2,convtime(%q1))%q2)]+
    [hasattr(v(dbref_master_timer),com_%q0)]=
    1+1+1,
    {
      &mod_%q0 [v(dbref_timer_data)]=1;
      &off_%q0 [v(dbref_timer_data)]=0;
      &nhb_%q0 [v(dbref_timer_data)]=%q2;
      &cnt_%q0 [v(dbref_timer_data)]=1;
      @pemit %#=Event %q0 set for [convsecs(%q2)].;
      @trigger v(dbref_master_timer)/tr_check_timer=%q0,%#;
      @trigger v(dbref_master_timer)/tr_kick_me;
    },
    1+1+0,
    {
      @pemit %#=That event does not exist.  Use '+timer/add name=comment'.
    },
    1+0+*,
    {
      @pemit %#=Invalid time specified.  Please provide something like \
        '10', '10:30', or '10:30:15'.
    },
    0+*,
    {
      @pemit %#=u(u_huh)
    }
-
#
# /quote -w -1 !"unprettify -v DO_TIMER_COUNT  <~/MyMush/timer.pretty"
#
&DO_TIMER_COUNT [v(dbref_global_object)]=$+timer/count *=*:
  @switch/first \
    setq(0,secure(%0))
    [setq(1,secure(%1))]
    [hasflag(%#,WIZARD)]+
    [isnum(%q1)]+
    [hasattr(v(dbref_master_timer),com_%q0)]+
    %q1=
    1+1+1+0,
    {
      &cnt_%q0 [v(dbref_timer_data)];
      @pemit %#=Event %q0 count removed.;
    },
    1+1+1+*,
    {
      &cnt_%q0 [v(dbref_timer_data)]=%q1;
      @pemit %#=Event %q0 count set to %q1.;
    },
    1+1+0+*,
    {
      @pemit %#=That event does not exist.  Use '+timer/add name=comment'.
    },
    1+0+*,
    {
      @pemit %#=Invalid count specified.  Please provide a number.  Set it to \
        zero to erase the count value.;
    },
    0+*,
    {
      @pemit %#=u(u_huh)
    }
-
#
# Example timed event.  TICK can be deleted or removed as desired.
#
# This event causes the Master Timer to @emit 'Tick' every 3 minutes.
# This @emit would normally be a @trigger of a remote object, but
# could also be a @pemit or some other device. 
#
# The code stored here should be minimal, otherwise the timer may
# begin to lag.
#
#
# /quote -w -1 !"unprettify -v TICK  <~/MyMush/timer.pretty"
#
@switch/first hasflag(me,WIZARD)=
  1,
  {
    +timer/add TICK=Sample event makes the clock tick.;
    +timer/trigger TICK=@emit Tick.;
    +timer/set TICK=every 180;
    +timer/list;
    +timer/schedule
  },
  {
    @pemit me=You aren't a wizard so I'm manually creating a sample item.;
    &COM_TICK [v(dbref_timer_data)]=Sample event makes the clock tick.;
    &TRW_TICK [v(dbref_timer_data)]=@emit Tick.;
    &NHB_TICK [v(dbref_timer_data)]=[add(secs(),180)];
    &MOD_TICK [v(dbref_timer_data)]=180;
    @tr [v(dbref_master_timer)]/tr_kick_me;
    look master timer;
    look master timer's data
  }
-
@pemit me=Master Timer Completed!
-